X11 Work Bench Toolkit  1.0
Font Utilities

Macros

#define WB_DEFAULT_FONT   "fixed"
 The default X11 font name (currently "fixed")
 
#define WB_DEFAULT_FONT_SIZE   13 /* override via settings */
 The default X11 font size (currently 13)
 
#define WINDOW_DATA_SIZE   4 /* size of a 'void *' array that stores per-window data */
 The 'window data' array size (currently 4 void pointers)
 
#define EVENT_ALL_MASK   0x01ffffffL /* 2^24 | 2^23 ... 2^0 - see X.h */
 An event mask for ALL events, with bits 0 through 24 set - see X.h which only defines bits 0 to 24 for an event mask.
 

Enumerations

enum  WBFontFlags {
  WBFontFlag_PITCH_FIXED = 1, WBFontFlag_PITCH_VARIABLE = 2, WBFontFlag_PITCH_CONDENSED = 4, WBFontFlag_PITCH_ANY = 0,
  WBFontFlag_PITCH_MASK = 7, WBFontFlag_STYLE_SANS = 8, WBFontFlag_STYLE_SERIF = 0x10, WBFontFlag_Reserved20 = 0x20,
  WBFontFlag_Reserved40 = 0x40, WBFontFlag_STYLE_ANY = 0, WBFontFlag_STYLE_MASK = 0x78, WBFontFlag_RASTER = 0x80,
  WBFontFlag_FREETYPE = 0x100, WBFontFlag_Reserved200 = 0x200, WBFontFlag_FNDRY_ANY = 0, WBFontFlag_FNDRY_MASK = 0x380,
  WBFontFlag_SIZE_PIXELS = 0, WBFontFlag_SIZE_POINTS = 0x400, WBFontFlag_SIZE_TWIPS = 0x800, WBFontFlag_SIZE_Reserved = 0xc00,
  WBFontFlag_SIZE_MASK = 0xc00, WBFontFlag_WT_ANY = 0, WBFontFlag_WT_REGULAR = 0x1000, WBFontFlag_WT_MEDIUM = 0x2000,
  WBFontFlag_WT_DEMIBOLD = 0x3000, WBFontFlag_WT_BOLD = 0x4000, WBFontFlag_WT_Reserved5 = 0x5000, WBFontFlag_WT_Reserved6 = 0x6000,
  WBFontFlag_WT_MASK = 0x7000, WBFontFlag_SLANT_REGULAR = 0x10000, WBFontFlag_SLANT_OBLIQUE = 0x20000, WBFontFlag_SLANT_ITALIC = 0x30000,
  WBFontFlag_SLANT_ANY = 0, WBFontFlag_SLANT_MASK = 0x30000, WBFontFlag_WIDTH_NORMAL = 0x40000, WBFontFlag_WIDTH_SEMICOND = 0x80000,
  WBFontFlag_WIDTH_Reserved = 0xc0000, WBFontFlag_WIDTH_ANY = 0, WBFontFlag_WIDTH_MASK = 0xc0000, WBFontFlag_REG_ISO8859 = 0x100000,
  WBFontFlag_REG_ISO646_1991 = 0x200000, WBFontFlag_REG_ASCII = 0x300000, WBFontFlag_REG_FNTSPECIFIC = 0x400000, WBFontFlag_REG_MISC = 0x500000,
  WBFontFlag_REG_GB2312_1980 = 0x600000, WBFontFlag_REG_ADOBE = 0x700000, WBFontFlag_REG_Reserved8 = 0x800000, WBFontFlag_REG_Reserved9 = 0x900000,
  WBFontFlag_REG_ReservedA = 0xa00000, WBFontFlag_REG_ReservedB = 0xb00000, WBFontFlag_REG_ReservedC = 0xc00000, WBFontFlag_REG_ReservedD = 0xd00000,
  WBFontFlag_REG_ReservedE = 0xe00000, WBFontFlag_REG_ReservedF = 0xf00000, WBFontFlag_REG_MASK = 0xf00000, WBFontFlag_WHATEVER = 0
}
 Font 'flag' enumeration. More...
 

Functions

XFontStruct * WBCopyFont (XFontStruct *pFont)
 make a copy of an existing font (best when assigning to a window) More...
 
XFontStruct * WBLoadFont (Display *pDisplay, const char *szFontName, int iFontSize, int iFlags)
 load a font based on a font name, size, and font flags More...
 
XFontStruct * WBLoadModifyFont (Display *pDisplay, const XFontStruct *pOriginal, int iFontSize, int iFlags)
 load and modify a font according to the specified size and flags More...
 
XFontSet WBCopyModifyFontSet (Display *pDisplay, XFontSet fsOrig, int iFontSize, int iFlags)
 copy and modify a font set according to the specified size and flags More...
 
int WBFontAvgCharWidth (Display *pDisplay, const XFontStruct *pFont)
 Get the average character width for a font. More...
 
int WBFontSetDescent (Display *pDisplay, XFontSet fontSet)
 Get the maximum character descent from a font set. More...
 
int WBFontSetAscent (Display *pDisplay, XFontSet fontSet)
 Get the maximum character ascent from a font set. More...
 
int WBFontSetHeight (Display *pDisplay, XFontSet fontSet)
 Get the maximum character height from a font set. More...
 
int WBFontSetAvgCharWidth (Display *pDisplay, XFontSet fontSet)
 Get the average character width for a font set. More...
 
XCharStruct WBFontSetMaxBounds (Display *pDisplay, XFontSet fontSet)
 Get a 'maximized' copy of the 'max_bounds' member for the font set. More...
 
XFontSet WBFontSetFromFont (Display *pDisplay, const XFontStruct *pFont)
 Creates an 'XFontSet' from an XFontStruct for a given display. More...
 
XFontStruct * WBFontFromFontSet (Display *pDisplay, XFontSet fontSet)
 Creates an 'XFontStruct' from the first font assigned to a Font Set. More...
 
XFontSet WBFontSetFromFontSingle (Display *pDisplay, const XFontStruct *pFont)
 Creates an 'XFontSet' from an XFontStruct for a given display, with only a single font in the set. More...
 
int WBTextWidth (XFontSet fontSet, const char *szText, int cbText)
 Obtain the pixel width of specified text for a specified XFontSet. More...
 
#define WB_TEXT_EXTENTS   Xutf8TextExtents
 
#define WB_TEXT_ESCAPEMENT   Xutf8TextEscapement
 
#define WB_DRAW_STRING   Xutf8DrawString
 
#define WB_DRAW_TEXT   Xutf8DrawText
 
#define WB_LOOKUP_STRING   Xutf8LookupString
 

Detailed Description

GC Utility functions for font selection and modification

This is the definition file for font helper functions and structures, designed to SPECIFICALY work with 'X11 Core' fonts and rendering. Compatibility and support for 'Xft' fonts and rendering is currently 'reserved for future implementation'. Fonts under X11 (core) are generally difficult to deal with. These utility functions allow you to more easily select a font based on an existing font or a general description of a font, with 'fuzzy' matching.
Additionally there is support for creating 'Font Sets' for use with Xmb, Xwc, and Xutf8 versions of 'Core' text rendering APIs.

Macro Definition Documentation

#define WB_DRAW_STRING   Xutf8DrawString

abstraction for Xutf8DrawString or XmbDrawString

Definition at line 92 of file font_helper.h.

#define WB_DRAW_TEXT   Xutf8DrawText

abstraction for Xutf8DrawText or XmbDrawText

Definition at line 93 of file font_helper.h.

#define WB_LOOKUP_STRING   Xutf8LookupString

abstraction for Xutf8LookupString or XmbLookupString

Definition at line 94 of file font_helper.h.

#define WB_TEXT_ESCAPEMENT   Xutf8TextEscapement

abstraction for Xutf8TextEscapement or XmbTextEscapement

Definition at line 91 of file font_helper.h.

#define WB_TEXT_EXTENTS   Xutf8TextExtents

abstraction for Xutf8TextExtents or XmbTextEscapement

Definition at line 90 of file font_helper.h.

Enumeration Type Documentation

Font 'flag' enumeration.

An enumeration of 'Font Flags' used by WBLoadFont() and WBLoadModifyFont() to load and/or modify a font according to the desired specifications.

See Also
WBLoadFont(), WBLoadModifyFont()
Enumerator
WBFontFlag_PITCH_FIXED 

force fixed pitch

WBFontFlag_PITCH_VARIABLE 

force variable pitch

WBFontFlag_PITCH_CONDENSED 

condensed (alternate to 'fixed')

WBFontFlag_PITCH_ANY 

'Any' pitch (default, zero)

WBFontFlag_PITCH_MASK 

'pitch mask'

WBFontFlag_STYLE_SANS 

force sans-serif

WBFontFlag_STYLE_SERIF 

force serif (i.e. 'not sans')

WBFontFlag_Reserved20 

reserved (style)

WBFontFlag_Reserved40 

reserved (style)

WBFontFlag_STYLE_ANY 

'Any' style (default, zero)

WBFontFlag_STYLE_MASK 

style mask

WBFontFlag_RASTER 

force raster (xfree86?)

WBFontFlag_FREETYPE 

force freetype

WBFontFlag_Reserved200 

reserved (foundry)

WBFontFlag_FNDRY_ANY 

'Any' foundry (default, zero)

WBFontFlag_FNDRY_MASK 

'foundry mask'

WBFontFlag_SIZE_PIXELS 

font size is in 'pixels' (when font size > 0)

WBFontFlag_SIZE_POINTS 

font size is in 'points' (when font size > 0)

WBFontFlag_SIZE_TWIPS 

font size is in 'twips' (when font size > 0)

WBFontFlag_SIZE_Reserved 

reserved flags for font size > 0

WBFontFlag_SIZE_MASK 

'size mask' for font size > 0

WBFontFlag_WT_ANY 

Any font weight specification (mutually exclusive)

WBFontFlag_WT_REGULAR 

regular font weight (mutually exclusive0

WBFontFlag_WT_MEDIUM 

medium font weight (mutually exclusive0

WBFontFlag_WT_DEMIBOLD 

demi-bold font weight (mutually exclusive0

WBFontFlag_WT_BOLD 

bold font weight (mutually exclusive0

WBFontFlag_WT_Reserved5 

reserved font weight (5) (not currently in use)

WBFontFlag_WT_Reserved6 

reserved font weight (6) (not currently in use)

WBFontFlag_WT_MASK 

font weight bit mask

WBFontFlag_SLANT_REGULAR 

'regular' slant (mutually exclusive)

WBFontFlag_SLANT_OBLIQUE 

'oblique' slant (mutually exclusive)

WBFontFlag_SLANT_ITALIC 

'italic' slant (mutually exclusive)

WBFontFlag_SLANT_ANY 

'default' slant (zero; mutually exclusive; may return an italic or oblique font)

WBFontFlag_SLANT_MASK 

slant mask

WBFontFlag_WIDTH_NORMAL 

normal width (mutually exclusive)

WBFontFlag_WIDTH_SEMICOND 

semicondensed width (mutually exclusive)

WBFontFlag_WIDTH_Reserved 

'reserved' width type

WBFontFlag_WIDTH_ANY 

'Any' width (zero; mutually exclusive)

WBFontFlag_WIDTH_MASK 

width mask

WBFontFlag_REG_ISO8859 

use ISO8859 registry (mutually exclusive)

WBFontFlag_REG_ISO646_1991 

use ISO646-1991 registry (mutually exclusive)

WBFontFlag_REG_ASCII 

use ASCII registry (mutually exclusive)

WBFontFlag_REG_FNTSPECIFIC 

use a font specific registry (mutually exclusive)

WBFontFlag_REG_MISC 

use 'MISC' registry (mutually exclusive)

WBFontFlag_REG_GB2312_1980 

use ADOBE registry (mutually exclusive)

WBFontFlag_REG_ADOBE 

use ADOBE registry - a lot of fonts use this (mutually exclusive)

WBFontFlag_REG_Reserved8 

reserved reg flag (reserved for future use)

WBFontFlag_REG_Reserved9 

reserved reg flag (reserved for future use)

WBFontFlag_REG_ReservedA 

reserved reg flag (reserved for future use)

WBFontFlag_REG_ReservedB 

reserved reg flag (reserved for future use)

WBFontFlag_REG_ReservedC 

reserved reg flag (reserved for future use)

WBFontFlag_REG_ReservedD 

reserved reg flag (reserved for future use)

WBFontFlag_REG_ReservedE 

reserved reg flag (reserved for future use)

WBFontFlag_REG_ReservedF 

reserved reg flag (reserved for future use)

WBFontFlag_REG_MASK 

font registry mask

Definition at line 385 of file font_helper.h.

Function Documentation

XFontStruct* WBCopyFont ( XFontStruct *  pFont)

make a copy of an existing font (best when assigning to a window)

Parameters
pFontThe original font to be copied
Returns
A copy of the original font as an XFontStruct

use this function to make a copy of an existing XFontStruct.

On error this function returns NULL. The caller must free non-NULL return values via XFreeFont()

Header File: font_helper.h

Definition at line 97 of file font_helper.c.

XFontSet WBCopyModifyFontSet ( Display *  pDisplay,
XFontSet  fsOrig,
int  iFontSize,
int  iFlags 
)

copy and modify a font set according to the specified size and flags

Parameters
pDisplayA pointer to the display
fsOrigThe original font set on which to base the new font set
iFontSizeThe font size (see WBLoadFont() for more details)
For a non-zero value, the font size is based on the WBFontFlag_SIZE_xxx flag specified in 'iFlags' An 'iFontSize' value of ZERO copies the font size from the original font specified in 'pOriginal'.
iFlagsVarious WBFontFlags that specify font characteristics. The existing font is modified according to these flags. If the font size is zero, flags that modify the font size will be ignored.
Returns
An XFontStruct pointer for the desired font, or None on error The returned value (if not NOne) must be free'd using XFreeFontSet()

use this function to select a similar font that differs only by whatever is specified in 'iFontSize' or 'iFlags'. If a matching font is NOT available, a copy of the original font will be returned. Typical use is to 'bold' or 'italicize' an existing font.

The returned value (if not None) will need to be free'd using XFreeFontSet()

Header File: font_helper.h

Definition at line 1441 of file font_helper.c.

int WBFontAvgCharWidth ( Display *  pDisplay,
const XFontStruct *  pFont 
)

Get the average character width for a font.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
pFontA pointer to an XFontStruct
Returns
The average width of a character for this font

Use this function to query an XFontStruct about its average character width.

Definition at line 998 of file font_helper.c.

XFontStruct* WBFontFromFontSet ( Display *  pDisplay,
XFontSet  fontSet 
)

Creates an 'XFontStruct' from the first font assigned to a Font Set.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
fontSetAn XFontSet (may not be 'None')
Returns
An XFontStruct pointer or NULL on error. The caller must free the XFontStruct using XFreeFontStruct() if not NULL.

This function helps to The returned value (if not NULL) will need to be free'd using XFreeFont()

Header File: font_helper.h

Definition at line 2026 of file font_helper.c.

int WBFontSetAscent ( Display *  pDisplay,
XFontSet  fontSet 
)

Get the maximum character ascent from a font set.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
fontSetThe Font Set to query ( None implies the system default font set)
Returns
The average width of a character for this font

Use this function to query an XFontSet about its maximum ascent. This will typically be derived from all of the individual fonts in the font set.

Definition at line 1136 of file font_helper.c.

int WBFontSetAvgCharWidth ( Display *  pDisplay,
XFontSet  fontSet 
)

Get the average character width for a font set.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
fontSetThe Font Set to query ( None implies the system default font set)
Returns
The average width of a character for this font

Use this function to query an XFontSet about its average character width. This will typically be derived from all of the individual fonts in the font set.

Definition at line 1227 of file font_helper.c.

int WBFontSetDescent ( Display *  pDisplay,
XFontSet  fontSet 
)

Get the maximum character descent from a font set.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
fontSetThe Font Set to query ( None implies the system default font set)
Returns
The average width of a character for this font

Use this function to query an XFontSet about its maximum descent. This will typically be derived from all of the individual fonts in the font set.

Definition at line 1094 of file font_helper.c.

XFontSet WBFontSetFromFont ( Display *  pDisplay,
const XFontStruct *  pFont 
)

Creates an 'XFontSet' from an XFontStruct for a given display.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
pFontA pointer to an XFontStruct
Returns
An XFontSet appropriate to the XFontStruct, or None on error. The returned value (if not None) will need to be free'd using XFreeFontSet()

This function helps to support internationalization through use of the 'Xmb' 'Xwc' and 'Xutf8' versions of the X11 'core' text rendering API functions by creating an 'XFontSet' that matches all of the available character sets for a supplied font specification.
The returned value (if not None) will need to be free'd using XFreeFontSet()

Header File: font_helper.h

Definition at line 1749 of file font_helper.c.

XFontSet WBFontSetFromFontSingle ( Display *  pDisplay,
const XFontStruct *  pFont 
)

Creates an 'XFontSet' from an XFontStruct for a given display, with only a single font in the set.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
pFontA pointer to an XFontStruct
Returns
An XFontSet appropriate to the XFontStruct, or NULL on error.The returned value (if not None) will need to be free'd using XFreeFontSet()

This function helps to support internationalization through use of the 'Xmb' 'Xwc' and 'Xutf8' versions of the X11 'core' text rendering API functions by creating an 'XFontSet' that matches all of the available character sets for a supplied font specification.

This function differs from WBFontSetFromFont() in that it only adds a SINGLE font to the font set, without any wildcard substitutions, and with a locale of "C".

The returned value (if not None) will need to be free'd using XFreeFontSet()

Header File: font_helper.h

Definition at line 1924 of file font_helper.c.

int WBFontSetHeight ( Display *  pDisplay,
XFontSet  fontSet 
)

Get the maximum character height from a font set.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
fontSetThe Font Set to query ( None implies the system default font set)
Returns
The average width of a character for this font

Use this function to query an XFontSet about its maximum height. This will typically be derived from all of the individual fonts in the font set.

Definition at line 1178 of file font_helper.c.

XCharStruct WBFontSetMaxBounds ( Display *  pDisplay,
XFontSet  fontSet 
)

Get a 'maximized' copy of the 'max_bounds' member for the font set.

Parameters
pDisplayA pointer to the Display ( NULL uses WBGetDefaultDisplay() )
fontSetThe Font Set to query ( None implies the system default font set)
Returns
A copy of a 'maximized' XCharStruct where all members are 'maximum' values of the entire font set

Use this function to query an XFontSet about its maximum bounds. This will typically be derived from all of the individual fonts in the font set.

Definition at line 1287 of file font_helper.c.

XFontStruct* WBLoadFont ( Display *  pDisplay,
const char *  szFontName,
int  iFontSize,
int  iFlags 
)

load a font based on a font name, size, and font flags

Parameters
pDisplayA pointer to the display
szFontNameA 0-byte terminated ASCII string specifying the desired font name
iFontSizeThe font size, > 0 for height, < 0 for width, 0 for 'do not care'
the font size is based on the WBFontFlag_SIZE_xxx flag specified in 'iFlags'
iFlagsVarious WBFontFlags that specify font characteristics
Returns
An XFontStruct pointer for the desired font, or NULL on error.

font mapping helper - uses size, italic, bold, 'flags' and font name to determine "the best font" based on a simple mapping algorithm.
negative 'iFontSize' is the average font width
Positive 'iFontSize' is the height (including ascend/descend)
A value of '0' is considered to be a 'wildcard' match. Use a positive 'iFontSize' for more precise font measurement.

On error this function returns NULL. The caller must free non-NULL return values via XFreeFont()

Header File: font_helper.h

Definition at line 858 of file font_helper.c.

XFontStruct* WBLoadModifyFont ( Display *  pDisplay,
const XFontStruct *  pOriginal,
int  iFontSize,
int  iFlags 
)

load and modify a font according to the specified size and flags

Parameters
pDisplayA pointer to the display
pOriginalThe original font on which to base the new font
iFontSizeThe font size (see WBLoadFont() for more details)
For a non-zero value, the font size is based on the WBFontFlag_SIZE_xxx flag specified in 'iFlags' An 'iFontSize' value of ZERO copies the font size from the original font specified in 'pOriginal'.
iFlagsVarious WBFontFlags that specify font characteristics. The existing font is modified according to these flags. If the font size is zero, flags that modify the font size will be ignored.
Returns
An XFontStruct pointer for the desired font, or NULL on error

use this function to select a similar font that differs only by whatever is specified in 'iFontSize' or 'iFlags'. If a matching font is NOT available, a copy of the original font will be returned. Typical use is to 'bold' or 'italicize' an existing font.

On error this function returns NULL. The caller must free non-NULL return values via XFreeFont()

Header File: font_helper.h

Definition at line 1350 of file font_helper.c.

int WBTextWidth ( XFontSet  fontSet,
const char *  szText,
int  cbText 
)

Obtain the pixel width of specified text for a specified XFontSet.

Parameters
fontSetAn XFontSet, as returned by WBFontSetFromFont (or similar)
szTextA (const) pointer to a Multi-Byte (or UTF8 string) string
cbTextThe total length of the text pointed to by szText (negative value to use a zero-byte terminator)
Returns
The width of the specified text, in pixels (similar to XTextWidth but for MB and/or UTF8 characters using a font set)

Use this function to determine the correct 'display' width of a UTF8 or Multi-Byte character string.

Header File: font_helper.h

Definition at line 2066 of file font_helper.c.