FLTK: Color & Font functions

FLTK

Functions
Color & Font functions

fl global color, font functions. These functions are declared in <FL/Fl.H> or <FL/fl_draw.H>. More...

## Functions
Fl_Color | fl_color ()
| Returns the last fl_color() that was set. More...
void | fl_color (Fl_Color c)
| Sets the color for all subsequent drawing operations. More...
void | fl_color (int c)
| for back compatibility - use fl_color(Fl_Color c) instead
void | fl_color (uchar r, uchar g, uchar b)
| Sets the color for all subsequent drawing operations. More...
Fl_Color | fl_color_average (Fl_Color color1, Fl_Color color2, float weight)
| Returns the weighted average color between the two given colors. More...
Fl_Color | fl_contrast (Fl_Color fg, Fl_Color bg)
| Returns a color that contrasts with the background color. More...
int | fl_descent ()
| Returns the recommended distance above the bottom of a fl_height() tall box to draw the text at so it looks centered vertically in that box.
Fl_Font | fl_font ()
| Returns the `face` set by the most recent call to fl_font(). More...
void | fl_font (Fl_Font face, Fl_Fontsize fsize)
| Sets the current font, which is then used in various drawing routines. More...
int | fl_height ()
| Returns the recommended minimum line spacing for the current font. More...
FL_EXPORT int | fl_height (int font, int size)
| This function returns the actual height of the specified `font` and `size`. More...
Fl_Color | fl_inactive (Fl_Color c)
| Returns the inactive, dimmed version of the given color.
FL_EXPORT const char * | fl_latin1_to_local (const char *t, int n=-1)
| Converts text from Windows/X11 latin1 character set to local encoding. More...
FL_EXPORT const char * | fl_local_to_latin1 (const char *t, int n=-1)
| Converts text from local encoding to Windowx/X11 latin1 character set. More...
FL_EXPORT const char * | fl_local_to_mac_roman (const char *t, int n=-1)
| Converts text from local encoding to Mac Roman character set. More...
FL_EXPORT const char * | fl_mac_roman_to_local (const char *t, int n=-1)
| Converts text from Mac Roman character set to local encoding. More...
FL_EXPORT Fl_Color | fl_show_colormap (Fl_Color oldcol)
| Pops up a window to let the user pick a colormap entry. More...
Fl_Fontsize | fl_size ()
| Returns the `size` set by the most recent call to fl_font(). More...
FL_EXPORT void | fl_text_extents (const char *, int &dx, int &dy, int &w, int &h)
| Determines the minimum pixel dimensions of a nul-terminated string. More...
void | fl_text_extents (const char *t, int n, int &dx, int &dy, int &w, int &h)
| Determines the minimum pixel dimensions of a sequence of `n` characters. More...
FL_EXPORT double | fl_width (const char *txt)
| Returns the typographical width of a nul-terminated string using the current font face and size.
double | fl_width (const char *txt, int n)
| Returns the typographical width of a sequence of `n` characters using the current font face and size.
double | fl_width (unsigned int c)
| Returns the typographical width of a single character using the current font face and size. More...
ulong | fl_xpixel (Fl_Color i)
| Returns the X pixel number used to draw the given FLTK color index. More...
ulong | fl_xpixel (uchar r, uchar g, uchar b)
| Returns the X pixel number used to draw the given rgb color. More...
static void | Fl::free_color (Fl_Color i, int overlay=0)
| Frees the specified color from the colormap, if applicable. More...
static unsigned | Fl::get_color (Fl_Color i)
| Returns the RGB value(s) for the given FLTK color index. More...
static void | Fl::get_color (Fl_Color i, uchar &red, uchar &green, uchar &blue)
| Returns the RGB value(s) for the given FLTK color index. More...
static const char * | Fl::get_font (Fl_Font)
| Gets the string for this face. More...
static const char * | Fl::get_font_name (Fl_Font, int *attributes=0)
| Get a human-readable string describing the family of this face. More...
static int | Fl::get_font_sizes (Fl_Font, int *&sizep)
| Return an array of sizes in `sizep`. More...
static void | Fl::set_color (Fl_Color i, unsigned c)
| Sets an entry in the fl_color index table. More...
static void | Fl::set_color (Fl_Color, uchar, uchar, uchar)
| Sets an entry in the fl_color index table. More...
static void | Fl::set_font (Fl_Font, const char *)
| Changes a face. More...
static void | Fl::set_font (Fl_Font, Fl_Font)
| Copies one face to another.
static Fl_Font | Fl::set_fonts (const char *=0)
| FLTK will open the display, and add every fonts on the server to the face table. More...

## Detailed Description

fl global color, font functions. These functions are declared in <FL/Fl.H> or <FL/fl_draw.H>.

## Function Documentation

## ◆ fl_color() [1/3]

Fl_Color fl_color | ( |  | ) |
| inline

Returns the last fl_color() that was set.

This can be used for state save/restore.

## ◆ fl_color() [2/3]

void fl_color | ( | Fl_Color | c | ) |
| inline

Sets the color for all subsequent drawing operations.

For colormapped displays, a color cell will be allocated out of `fl_colormap` the first time you use a color. If the colormap fills up then a least-squares algorithm is used to find the closest color. If no valid graphical context (fl_gc) is available, the foreground is not set for the current window.

Parameters

  [in] | c | color

## ◆ fl_color() [3/3]

void fl_color | ( | uchar | r,
|  | uchar | g,
|  | uchar | b
| ) |  |
| inline

Sets the color for all subsequent drawing operations.

The closest possible match to the RGB color is used. The RGB color is used directly on TrueColor displays. For colormap visuals the nearest index in the gray ramp or color cube is used. If no valid graphical context (fl_gc) is available, the foreground is not set for the current window.

Parameters

  [in] | r,g,b | color components

## ◆ fl_color_average()

Fl_Color fl_color_average | ( | Fl_Color | color1,
|  | Fl_Color | color2,
|  | float | weight
| ) |  |

Returns the weighted average color between the two given colors.

The red, green and blue values are averages using the following formula:

color = color1 * weight + color2 * (1 - weight)

Thus, a `weight` value of 1.0 will return the first color, while a value of 0.0 will return the second color.

Parameters

  [in] | color1,color2 | boundary colors
  [in] | weight | weighting factor

## ◆ fl_contrast()

Fl_Color fl_contrast | ( | Fl_Color | fg,
|  | Fl_Color | bg
| ) |  |

Returns a color that contrasts with the background color.

This will be the foreground color if it contrasts sufficiently with the background color. Otherwise, returns `FL_WHITE` or `FL_BLACK` depending on which color provides the best contrast.

Parameters

  [in] | fg,bg | foreground and background colors

Returns
  contrasting color

## ◆ fl_font() [1/2]

Fl_Font fl_font | ( |  | ) |
| inline

Returns the `face` set by the most recent call to fl_font().

This can be used to save/restore the font.

## ◆ fl_font() [2/2]

void fl_font | ( | Fl_Font | face,
|  | Fl_Fontsize | fsize
| ) |  |
| inline

Sets the current font, which is then used in various drawing routines.

You may call this outside a draw context if necessary to call fl_width(), but on X this will open the display.

The font is identified by a `face` and a `size`. The size of the font is measured in pixels and not "points". Lines should be spaced `size` pixels apart or more.

## ◆ fl_height() [1/2]

int fl_height | ( |  | ) |
| inline

Returns the recommended minimum line spacing for the current font.

You can also use the value of `size` passed to fl_font()

## ◆ fl_height() [2/2]

FL_EXPORT int fl_height | ( | int | font,
|  | int | size
| ) |  |

This function returns the actual height of the specified `font` and `size`.

Normally the font height should always be 'size', but with the advent of XFT, there are (currently) complexities that seem to only be solved by asking the font what its actual font height is. (See STR#2115)

This function was originally undocumented in 1.1.x, and was used only by Fl_Text_Display. We're now documenting it in 1.3.x so that apps that need precise height info can get it with this function.

Returns
  the height of the font in pixels.

Todo:
  In the future, when the XFT issues are resolved, this function should simply return the 'size' value.

## ◆ fl_latin1_to_local()

FL_EXPORT const char* fl_latin1_to_local | ( | const char * | t,
|  | int | n = `-1`
| ) |  |

Converts text from Windows/X11 latin1 character set to local encoding.

Parameters

  [in] | t | character string (latin1 encoding)
  [in] | n | optional number of characters to convert (default is all)

Returns
  pointer to internal buffer containing converted characters

## ◆ fl_local_to_latin1()

FL_EXPORT const char* fl_local_to_latin1 | ( | const char * | t,
|  | int | n = `-1`
| ) |  |

Converts text from local encoding to Windowx/X11 latin1 character set.

Parameters

  [in] | t | character string (local encoding)
  [in] | n | optional number of characters to convert (default is all)

Returns
  pointer to internal buffer containing converted characters

## ◆ fl_local_to_mac_roman()

FL_EXPORT const char* fl_local_to_mac_roman | ( | const char * | t,
|  | int | n = `-1`
| ) |  |

Converts text from local encoding to Mac Roman character set.

Parameters

  [in] | t | character string (local encoding)
  [in] | n | optional number of characters to convert (default is all)

Returns
  pointer to internal buffer containing converted characters

## ◆ fl_mac_roman_to_local()

FL_EXPORT const char* fl_mac_roman_to_local | ( | const char * | t,
|  | int | n = `-1`
| ) |  |

Converts text from Mac Roman character set to local encoding.

Parameters

  [in] | t | character string (Mac Roman encoding)
  [in] | n | optional number of characters to convert (default is all)

Returns
  pointer to internal buffer containing converted characters

## ◆ fl_show_colormap()

FL_EXPORT Fl_Color fl_show_colormap | ( | Fl_Color | oldcol | ) |

Pops up a window to let the user pick a colormap entry.

Parameters

  [in] | oldcol | color to be highlighted when grid is shown.

Return values

  Fl_Color | value of the chosen colormap entry.

See also
  Fl_Color_Chooser

## ◆ fl_size()

Fl_Fontsize fl_size | ( |  | ) |
| inline

Returns the `size` set by the most recent call to fl_font().

This can be used to save/restore the font.

## ◆ fl_text_extents() [1/2]

FL_EXPORT void fl_text_extents | ( | const char * | ,
|  | int & | dx,
|  | int & | dy,
|  | int & | w,
|  | int & | h
| ) |  |

Determines the minimum pixel dimensions of a nul-terminated string.

Usage: given a string "txt" drawn using fl_draw(txt, x, y) you would determine its pixel extents on the display using fl_text_extents(txt, dx, dy, wo, ho) such that a bounding box that exactly fits around the text could be drawn with fl_rect(x+dx, y+dy, wo, ho). Note the dx, dy values hold the offset of the first "colored in" pixel of the string, from the draw origin.

No FLTK symbol expansion will be performed.

## ◆ fl_text_extents() [2/2]

void fl_text_extents | ( | const char * | t,
|  | int | n,
|  | int & | dx,
|  | int & | dy,
|  | int & | w,
|  | int & | h
| ) |  |
| inline

Determines the minimum pixel dimensions of a sequence of `n` characters.

See also
  fl_text_extents(const char*, int& dx, int& dy, int& w, int& h)

## ◆ fl_width()

double fl_width | ( | unsigned int | c | ) |
| inline

Returns the typographical width of a single character using the current font face and size.

Note
  if a valid fl_gc is NOT found then it uses the first window gc, or the screen gc if no fltk window is available when called.

## ◆ fl_xpixel() [1/2]

ulong fl_xpixel | ( | Fl_Color | i | ) |

Returns the X pixel number used to draw the given FLTK color index.

This is the X pixel that fl_color() would use.

Parameters

  [in] | i | color index

Returns
  X pixel number

## ◆ fl_xpixel() [2/2]

ulong fl_xpixel | ( | uchar | r,
|  | uchar | g,
|  | uchar | b
| ) |  |

Returns the X pixel number used to draw the given rgb color.

This is the X pixel that fl_color() would use.

Parameters

  [in] | r,g,b | color components

Returns
  X pixel number

## ◆ free_color()

void Fl::free_color | ( | Fl_Color | i,
|  | int | overlay = `0`
| ) |  |
| static

Frees the specified color from the colormap, if applicable.

Free color `i` if used, and clear mapping table entry.

If overlay is non-zero then the color is freed from the overlay colormap.

Parameters

  [in] | i | color index
  [in] | overlay | 0 for normal, 1 for overlay color

## ◆ get_color() [1/2]

unsigned Fl::get_color | ( | Fl_Color | i | ) |
| static

Returns the RGB value(s) for the given FLTK color index.

This form returns the RGB values packed in a 32-bit unsigned integer with the red value in the upper 8 bits, the green value in the next 8 bits, and the blue value in bits 8-15. The lower 8 bits will always be 0.

## ◆ get_color() [2/2]

void Fl::get_color | ( | Fl_Color | i,
|  | uchar & | red,
|  | uchar & | green,
|  | uchar & | blue
| ) |  |
| static

Returns the RGB value(s) for the given FLTK color index.

This form returns the red, green, and blue values separately in referenced variables.

See also unsigned get_color(Fl_Color c)

## ◆ get_font()

const char * Fl::get_font | ( | Fl_Font | fnum | ) |
| static

Gets the string for this face.

This string is different for each face. Under X this value is passed to XListFonts to get all the sizes of this face.

## ◆ get_font_name()

const char * Fl::get_font_name | ( | Fl_Font | fnum,
|  | int * | attributes = `0`
| ) |  |
| static

Get a human-readable string describing the family of this face.

This is useful if you are presenting a choice to the user. There is no guarantee that each face has a different name. The return value points to a static buffer that is overwritten each call.

The integer pointed to by `attributes` (if the pointer is not zero) is set to zero, FL_BOLD or FL_ITALIC or FL_BOLD | FL_ITALIC. To locate a "family" of fonts, search forward and back for a set with non-zero attributes, these faces along with the face with a zero attribute before them constitute a family.

## ◆ get_font_sizes()

int Fl::get_font_sizes | ( | Fl_Font | fnum,
|  | int *& | sizep
| ) |  |
| static

Return an array of sizes in `sizep`.

The return value is the length of this array. The sizes are sorted from smallest to largest and indicate what sizes can be given to fl_font() that will be matched exactly (fl_font() will pick the closest size for other sizes). A zero in the first location of the array indicates a scalable font, where any size works, although the array may list sizes that work "better" than others. Warning: the returned array points at a static buffer that is overwritten each call. Under X this will open the display.

## ◆ set_color() [1/2]

void Fl::set_color | ( | Fl_Color | i,
|  | unsigned | c
| ) |  |
| static

Sets an entry in the fl_color index table.

Set color mapping table entry `i` to color `c`.

You can set it to any 8-bit RGB color. The color is not allocated until fl_color(i) is used.

Parameters

  [in] | i | color index
  [in] | c | color

## ◆ set_color() [2/2]

void Fl::set_color | ( | Fl_Color | i,
|  | uchar | red,
|  | uchar | green,
|  | uchar | blue
| ) |  |
| static

Sets an entry in the fl_color index table.

You can set it to any 8-bit RGB color. The color is not allocated until fl_color(i) is used.

## ◆ set_font()

void Fl::set_font | ( | Fl_Font | fnum,
|  | const char * | name
| ) |  |
| static

Changes a face.

The string pointer is simply stored, the string is not copied, so the string must be in static memory.

## ◆ set_fonts()

Fl_Font Fl::set_fonts | ( | const char * | xstarname = `0` | ) |
| static

FLTK will open the display, and add every fonts on the server to the face table.

It will attempt to put "families" of faces together, so that the normal one is first, followed by bold, italic, and bold italic.

The optional argument is a string to describe the set of fonts to add. Passing NULL will select only fonts that have the ISO8859-1 character set (and are thus usable by normal text). Passing "-*" will select all fonts with any encoding as long as they have normal X font names with dashes in them. Passing "*" will list every font that exists (on X this may produce some strange output). Other values may be useful but are system dependent. With WIN32 NULL selects fonts with ISO8859-1 encoding and non-NULL selects all fonts.

The return value is how many faces are in the table after this is done.

- © 1998-2016 by Bill Spitzak and others.