Modules
	Legacy Font Utilities

	Font Structures

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
void	__internal_font_helper_init (void)
	initialization for font helper - call once at start of program (WBInit() does this for you)

void	__internal_font_helper_exit (void)
	un-initialization for font helper - call once at end of program (WBExit() does this for you)

int	WBFontEnableAntiAlias (void)
	returns non-zero value if certain fonts should be anti-aliased when rendered More...

void	WBFontSetEnableAntiAlias (int bEnable)
	returns non-zero value if certain fonts should be anti-aliased when rendered More...

void	WBFreeFont (Display *pDisplay, WB_FONT pFont)
	free a WB_FONT that was created using one of the WBFont APIs More...

WB_FONT	WBCopyFont (Display *pDisplay, WB_FONTC pFont)
	make a copy of an existing font (best when assigning to a window) More...

WB_FONT	WBCopyModifyFont (Display *pDisplay, WB_FONTC pOriginal, int iFontSize, int iFlags)
	load and modify a font according to the specified size and flags More...

WB_FONT	WBLoadFont (Display pDisplay, const char szFontName, int iFontSize, int iFlags)
	load a WB_FONT font object based on a font name, size, and font flags More...

int	WBFontAvgCharWidth (WB_FONTC pFont)
	Get the average character width for a font. More...

int	WBFontMaxCharWidth (WB_FONTC pFont)
	Get the maximum character width for a font. More...

int	WBFontDescent (WB_FONTC pFont)
	Get the maximum character descent from a WB_FONT. More...

int	WBFontAscent (WB_FONTC pFont)
	Get the maximum character ascent from a WB_FONT. More...

int	WBFontHeight (WB_FONTC pFont)
	Get the maximum character height from a WB_FONT. More...

XCharStruct	WBFontMaxBounds (WB_FONTC pFont)
	Get a 'maximized' copy of 'max_bounds' (applicable to all font faces in the WB_FONT) More...

int	WBTextWidth (WB_FONTC pFont, const char *szText, int cbText)
	Obtain the pixel width of specified text for a specified WB_FONT. More...

void	WBTextExtent (WB_FONTC pFont, const char szText, int cbText, WB_EXTENT pExtent)
	Obtain the pixel extent 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/API functions for WB_FONT mid-level font selection and modification

These are the definitions for font helper functions and structures, designed to SPECIFICALY work with 'Xft' freetype fonts and rendering, but also support legacy (X11) fonts and font sets. For maximum compatibility, they have been abstracted using the (new) WB_FONT/WB_FONTC objects, particularly for legacy implementations that do not have the Xft library installed, and for those fonts that are native X11 fonts or font sets.

Macro Definition Documentation

◆ WB_DRAW_STRING

#define WB_DRAW_STRING Xutf8DrawString

abstraction for Xutf8DrawString or XmbDrawString

Definition at line 101 of file font_helper.h.

◆ WB_DRAW_TEXT

#define WB_DRAW_TEXT Xutf8DrawText

abstraction for Xutf8DrawText or XmbDrawText

Definition at line 102 of file font_helper.h.

◆ WB_LOOKUP_STRING

#define WB_LOOKUP_STRING Xutf8LookupString

abstraction for Xutf8LookupString or XmbLookupString

Definition at line 103 of file font_helper.h.

◆ WB_TEXT_ESCAPEMENT

#define WB_TEXT_ESCAPEMENT Xutf8TextEscapement

abstraction for Xutf8TextEscapement or XmbTextEscapement

Definition at line 100 of file font_helper.h.

◆ WB_TEXT_EXTENTS

#define WB_TEXT_EXTENTS Xutf8TextExtents

abstraction for Xutf8TextExtents or XmbTextExtents

Definition at line 99 of file font_helper.h.

Enumeration Type Documentation

◆ WBFontFlags

enum WBFontFlags

Font 'flag' enumeration.

An enumeration of 'Font Flags' used by WBLoadFont() and WBCopyModifyFont() 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 479 of file font_helper.h.

Function Documentation

◆ WBCopyFont()

WB_FONT WBCopyFont	(	Display *	pDisplay,
		WB_FONTC	pFont
	)

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

Parameters

pDisplay	A pointer to the display
pFont	The original WB_FONTC to be copied

Returns: A copy of the original font as a WB_FONT object (pointer).

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

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

Header File: font_helper.h

Definition at line 168 of file font_helper.c.

◆ WBCopyModifyFont()

WB_FONT WBCopyModifyFont	(	Display *	pDisplay,
		WB_FONTC	pOriginal,
		int	iFontSize,
		int	iFlags
	)

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

Parameters

pDisplay	A pointer to the display
pOriginal	The original WB_FONTC on which to base the new font
iFontSize	The 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'.
iFlags	Various 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: A WB_FONT object (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 WBFreeFont()

Header File: font_helper.h

Definition at line 660 of file font_helper.c.

◆ WBFontAscent()

int WBFontAscent ( WB_FONTC pFont )

Get the maximum character ascent from a WB_FONT.

Parameters

pFont The WB_FONT to query ( NULL implies the system default WB_FONT)

Returns: The ascent of a character for this font

Use this function to query a WB_FONT about its maximum ascent.

Definition at line 495 of file font_helper.c.

◆ WBFontAvgCharWidth()

int WBFontAvgCharWidth ( WB_FONTC pFont )

Get the average character width for a font.

Parameters

pFont A pointer to a WB_FONTC

Returns: The average width of a character for this font

Use this function to query a WB_FONT about its average character width.

Definition at line 343 of file font_helper.c.

◆ WBFontDescent()

int WBFontDescent ( WB_FONTC pFont )

Get the maximum character descent from a WB_FONT.

Parameters

pFont The WB_FONT to query ( NULL implies the system default WB_FONT)

Returns: The descent of a character for this font

Use this function to query a WB_FONT about its maximum descent.

Definition at line 443 of file font_helper.c.

◆ WBFontEnableAntiAlias()

int WBFontEnableAntiAlias ( void )

returns non-zero value if certain fonts should be anti-aliased when rendered

Returns: A non-zero value if certain fonts should be anti-aliased; zero if they should not be. This generally applies to legacy (X11) fonts only. See WBFontSetEnableAntiAlias() which basically controls the internal flag that this function queries.

Anti-aliasing can carry with it a performance degradation due to the somewhat slow process of getting rendering information from the X server. if the Render extension is present, and libXft is also present, then the Xft library uses the Render extension to do the anti-aliasing. Otherwise, it's done "the hard way" which can be slow.

See also: WBFontSetEnableAntiAlias()

Definition at line 157 of file font_helper.c.

◆ WBFontHeight()

int WBFontHeight ( WB_FONTC pFont )

Get the maximum character height from a WB_FONT.

Parameters

pFont The WB_FONT to query ( NULL implies the system default font set)

Returns: The average width of a character for this font

Use this function to query a WB_FONT about its maximum height.

Definition at line 546 of file font_helper.c.

◆ WBFontMaxBounds()

XCharStruct WBFontMaxBounds ( WB_FONTC pFont )

Get a 'maximized' copy of 'max_bounds' (applicable to all font faces in the WB_FONT)

Parameters

pFont The WB_FONT to query ( NULL implies the system default WB_FONT)

Returns: RESERVED: A copy of a 'maximized' XCharStruct where all members are 'maximum' values of the entire WB_FONT

Use this function to query a WB_FONT about its maximum bounds. This will typically be derived from all of the individual font faces within the object

Definition at line 592 of file font_helper.c.

◆ WBFontMaxCharWidth()

int WBFontMaxCharWidth ( WB_FONTC pFont )

Get the maximum character width for a font.

Parameters

pFont A pointer to a WB_FONTC

Returns: The maximum width of a character for this font

Use this function to query a WB_FONT about its maximum character width.

Definition at line 394 of file font_helper.c.

◆ WBFontSetEnableAntiAlias()

void WBFontSetEnableAntiAlias ( int bEnable )

returns non-zero value if certain fonts should be anti-aliased when rendered

Parameters

bEnable A non-zero value if certain fonts should be anti-aliased; zero if they should not be. This generally applies to legacy (X11) fonts only.

Anti-aliasing can carry with it a performance degradation due to the somewhat slow process of getting rendering information from the X server. if the Render extension is present, and libXft is also present, then the Xft library uses the Render extension to do the anti-aliasing. Otherwise, it's done "the hard way" which can be slow.

See also: WBFontEnableAntiAlias()

Definition at line 162 of file font_helper.c.

◆ WBFreeFont()

void WBFreeFont	(	Display *	pDisplay,
		WB_FONT	pFont
	)

free a WB_FONT that was created using one of the WBFont APIs

Parameters

pDisplay	A pointer to the display
pFont	The WB_FONT to be freed

use this function to free up resources associated with an existing WB_FONT, invalidating the pointer.

Header File: font_helper.h

Definition at line 250 of file font_helper.c.

◆ WBLoadFont()

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

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

Parameters

pDisplay	A pointer to the display
szFontName	A 0-byte terminated ASCII string specifying the desired font name
iFontSize	The 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'
iFlags	Various WBFontFlags that specify font characteristics

Returns: A WB_FONT object (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 WBFreeFont()

Header File: font_helper.h

Definition at line 291 of file font_helper.c.

◆ WBTextExtent()

void WBTextExtent	(	WB_FONTC	pFont,
		const char *	szText,
		int	cbText,
		WB_EXTENT *	pExtent
	)

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

Parameters

pFont	A WB_FONT object
szText	A (const) pointer to a Multi-Byte (or UTF8 string) string
cbText	The total length of the text pointed to by szText (negative value to use a zero-byte terminator)
pExtent	A pointer to a WB_EXTENT structure that receives the text extent. This will be the logical text extent, for spacing purposes

Use this function to determine the correct 'display' width and height of a UTF8 or Multi-Byte character string. It calculates the 'logical' extent using either XmbTextExtents() or Xutf8TextExtents() (as applicable) and returns the width/height of the bounding rectangle for the text.

Header File: font_helper.h

Definition at line 790 of file font_helper.c.

◆ WBTextWidth()

int WBTextWidth	(	WB_FONTC	pFont,
		const char *	szText,
		int	cbText
	)

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

Parameters

pFont	A WB_FONT object
szText	A (const) pointer to a Multi-Byte (or UTF8 string) string
cbText	The 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 747 of file font_helper.c.

Modules

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ WB_DRAW_STRING

◆ WB_DRAW_TEXT

◆ WB_LOOKUP_STRING

◆ WB_TEXT_ESCAPEMENT

◆ WB_TEXT_EXTENTS

Enumeration Type Documentation

◆ WBFontFlags

Function Documentation

◆ WBCopyFont()

◆ WBCopyModifyFont()

◆ WBFontAscent()

◆ WBFontAvgCharWidth()

◆ WBFontDescent()

◆ WBFontEnableAntiAlias()

◆ WBFontHeight()

◆ WBFontMaxBounds()

◆ WBFontMaxCharWidth()

◆ WBFontSetEnableAntiAlias()

◆ WBFreeFont()

◆ WBLoadFont()

◆ WBTextExtent()

◆ WBTextWidth()