X11workbench Toolkit
1.0
|
Data Structures | |
struct | tagDT_WORD |
Structure defining a 'word' for rendering purposes. More... | |
struct | tagDT_WORDS |
A collection of DT_WORD structures along with a pointer to the original text. More... | |
Typedefs | |
typedef struct tagDT_WORD | DT_WORD |
Structure defining a 'word' for rendering purposes. More... | |
typedef struct tagDT_WORDS | DT_WORDS |
A collection of DT_WORD structures along with a pointer to the original text. More... | |
Enumerations | |
enum | DTAlignment { DTAlignment_HLEFT = 1, DTAlignment_HCENTER = 2, DTAlignment_HRIGHT = 3, DTAlignment_HJUSTIFY = 4, DTAlignment_HMASK = 0xf, DTAlignment_VTOP = 0x10, DTAlignment_VBOTTOM = 0x20, DTAlignment_VCENTER = 0x30, DTAlignment_VCENTERASCENT = 0x40, DTAlignment_VCENTERBASELINE = 0x50, DTAlignment_VTOPHALF = 0x60, DTAlignment_VTBOTTOMHALF = 0x70, DTAlignment_VMASK = 0xf0, DTAlignment_V_BEFORE_H = 0x100, DTAlignment_NO_VRESIZE = 0x200, DTAlignment_NO_HRESIZE = 0x400, DTAlignment_NO_RESIZE = 0x600, DTAlignment_RESIZE_PIXEL = 0x800, DTAlignment_NO_SHRINK = 0x1000, DTAlignment_ALLOW_TRAILING = 0x2000, DTAlignment_NO_WORD_WRAP = 0x4000, DTAlignment_ANTIALIAS = 0x10000000, DTAlignment_SINGLELINE = 0x20000000, DTAlignment_UNDERSCORE = 0x40000000, DTAlignment_PRINTING = 0x80000000 } |
Alignment flags for various 'draw text' API functions. More... | |
Functions | |
static int | InternalCalcIdealBounds (Display *pDisplay, WB_FONTC pFont, DT_WORDS *pWords, int iTabWidth, unsigned int iTabOrigin, const WB_RECT *prcSource, WB_RECT *prcDest, int iAlignment, int iStartLine, int iEndLine) |
calculate ideal bounds rectangle for text given a font, tab spacing, tab origin, and alignment More... | |
void | DTDrawString (Display *pDisplay, Drawable drawable, WB_FONTC pFont, WBGC gc, int x, int y, const char *pString, int nLength) |
Draw text in a platform-independent manner for UTF-8 or multi-byte text, equivalent to WBDrawString() using the specified WB_FONTC. More... | |
WB_FONT | DTCalcIdealFont (Display *pDisplay, WB_FONTC pFont, const char *szText, WB_GEOM *geomBounds) |
Calculate the ideal font based on the text and rectangle. More... | |
int | DTCalcIdealBounds0 (XFontStruct *pFont, const char *szText, int iTabWidth, unsigned int iTabOrigin, const WB_RECT *prcSource, WB_RECT *prcDest, int iAlignment) |
Calculate the ideal bounding rectangle for the specified text and font. More... | |
int | DTCalcIdealBounds (Display *pDisplay, WB_FONTC pFont, const char *szText, int iTabWidth, unsigned int iTabOrigin, const WB_RECT *prcSource, WB_RECT *prcDest, int iAlignment) |
Calculate the ideal bounding rectangle for the specified text and font. More... | |
void | DTDrawSingleLineText (WB_FONTC pFontt, const char *szText, Display *pDisplay, WBGC gc, Drawable dw, int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment) |
draw single-line text More... | |
void | DTDrawMultiLineText (WB_FONTC pFont, const char *szText, Display *pDisplay, WBGC gc, Drawable dw, int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment) |
draw multi-line text More... | |
DT_WORDS * | DTGetWordsFromText (Display *pDisplay, WB_FONTC pFont, const char *szText, int iAlignment) |
Parse 'DT_WORDS' structure from single-line or multi-line text. More... | |
void | DTPreRender (Display *pDisplay, WB_FONTC pFont, DT_WORDS *pWords, int iTabWidth, int iTabOrigin, WB_RECT *prcBounds, int iAlignment, int iStartLine, int iEndLine) |
Pre-render a 'DT_WORDS' structure for subsequent display. More... | |
void | DTRender (Display *pDisplay, WB_FONTC pFont, const DT_WORDS *pWords, WBGC gc, Drawable dw, int iHScrollBy, int iVScrollBy, const WB_RECT *prcBounds, const WB_RECT *prcViewport, int iAlignment) |
Using pre-rendered 'DT_WORDS' structure, display. More... | |
GC Utility functions for drawing text
GC Utility functions for drawing text, as well as determing ideal fonts and borders using a variety of text alignments and tab methods. The text drawing utilities are designed to SPECIFICALY work with 'X11 Core' fonts and rendering. Compatibility and support for 'Xft' fonts and rendering is currently 'reserved for future implementation'. Current support includes use of the 'Xmb' versions of the API for multi-byte character strings, though actual 'core' font support for UTF-8 characters seems to be a bit limited.
Structure defining a 'word' for rendering purposes.
A 'word' is defined as one or more characters as a group that is to be rendered in as single-line or multi-line text. Special case is white space, line feeds, and tabs. The width and height of the 'word' element can be used to line up and do 'word breaks' on text for line wrapping. Multiple white space blocks can also be eliminated from the output when it is at the end of a line, particularly when wrapping text.
A collection of DT_WORD structures along with a pointer to the original text.
A collection of DT_WORD structures, along with a pointer to the original text. This structure is typically used to render text and calculate bounding rectangles for the purpose of window sizing and viewport scrolling.
enum DTAlignment |
Alignment flags for various 'draw text' API functions.
Enumerator | |
---|---|
DTAlignment_HLEFT | left-justified text |
DTAlignment_HCENTER | horizontally centered text. tabs are treated as white space |
DTAlignment_HRIGHT | right-justified text |
DTAlignment_HJUSTIFY | right/left 'justified' text - add or remove text kerning to 'justify' it As with DTAlignment_HCENTER, tabs are treated as regular white space. |
DTAlignment_HMASK | horizontal alignment mask |
DTAlignment_VTOP | top-aligned text (using highest vertical ascent) |
DTAlignment_VBOTTOM | bottom-aligned text (using lowest vertical descent) |
DTAlignment_VCENTER | center using entire text height (ascent + descent for single line) |
DTAlignment_VCENTERASCENT | center halfway up the 'ascent' portion (single line only) |
DTAlignment_VCENTERBASELINE | center along the font baseline (single line only) |
DTAlignment_VTOPHALF | center within the top half of the rectangle (single line only) |
DTAlignment_VTBOTTOMHALF | center within the bottom half of the rectangle (single line only) |
DTAlignment_V_BEFORE_H | re-size vertically before horizontally (affects text wrapping). if not specified, resize horizontally before vertically. In other words, the default would increase the width of the rectangle BEFORE wrapping the text and adding another line. The general rule attempts to keep the ratio of height to width similar to that of the source rectangle [when specified]. |
DTAlignment_NO_VRESIZE | do not increase size vertically |
DTAlignment_NO_HRESIZE | do not increase size horizontally |
DTAlignment_NO_RESIZE | if specified, does not increase rect size (combination of above 2). If re-sizing is required, and this flag is specified, 'DTCalcIdealBounds' will simply return -1 indicating that resizing is needed, but not calculate the new size. |
DTAlignment_RESIZE_PIXEL | resize by adding an equal number of pixels, both to horizontal and vertical, or as close as possible to the same number. if not specified, try to maintain the same ratio of H : V |
DTAlignment_NO_SHRINK | Do not shrink the bounding rectangle for ideal text dimension. |
DTAlignment_ALLOW_TRAILING | allow trailing white space (normally it is trimmed/ignored for alignment). This only applies with horizontal centering, or when trailing text affects a line split or precedes a line feed |
DTAlignment_NO_WORD_WRAP | do not perform word wrapping in order to 'fit' the text. Normally the DTCalcIdealBounds and DTCalcIdealFont functions will attempt to restructure the text with word-wrapping to fit within horizontal bounds. |
DTAlignment_ANTIALIAS | internal flag, applies simple anti-aliasing. See WBSimpleAntiAliasImage() and WBSimpleAntiAliasPixmap() for more information. |
DTAlignment_SINGLELINE | internal flag, 'single line only' (no line breaks). Implies DTAlignment_NO_WORD_WRAP |
DTAlignment_UNDERSCORE | internal flag, indicates that an underscore underlines the next character |
DTAlignment_PRINTING | internal flag, indicates that I'm printing, so don't go beyond word wrap in order to make the text fit within the display rectangle. |
Definition at line 75 of file draw_text.h.
int DTCalcIdealBounds | ( | Display * | pDisplay, |
WB_FONTC | pFont, | ||
const char * | szText, | ||
int | iTabWidth, | ||
unsigned int | iTabOrigin, | ||
const WB_RECT * | prcSource, | ||
WB_RECT * | prcDest, | ||
int | iAlignment | ||
) |
Calculate the ideal bounding rectangle for the specified text and font.
pDisplay | The Display associated with the WB_FONTC (NULL implies default display) |
pFont | A WB_FONTC for which to measure the bounding rectangle (NULL implies system default font set) |
szText | A pointer to a (0-byte terminated) ASCII string that may span multiple lines |
iTabWidth | A positive integer in 'characters', or negative integer in pixels, indicating tab width |
iTabOrigin | An unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character. |
prcSource | A pointer to the 'source' bounding rectangle in which the text is intended to fit. (If NULL, the function will ALWAYS return non-zero and return the raw text extents without trying to fit it into a particular bounding rectangle.) |
prcDest | A pointer to the 'destination' bounding rectangle, based on the actual text size, and fit according to iAlignment flags. |
iAlignment | The desired text alignment, one or more of the DTAlignment bit flags |
This function will calculate the ideal bounding rectangle for the specified text, if possible, within the limitations of the source rectangle. If the text cannot be rendered within the source rectangle, the function will attempt to calculate an appropriately sized rectangle in which to render it. You can use this function to re-size windows to accomodate the size of the text that must be displayed within the window.
NOTE: tab width is negative for pixels, positive for avg char width, beginning at the left most position of the specified rectangle. Tab Origin is always in pixels using the absolute position (relative to the same origin as prcSource).
Header File: draw_text.h
Definition at line 579 of file draw_text.c.
int DTCalcIdealBounds0 | ( | XFontStruct * | pFont, |
const char * | szText, | ||
int | iTabWidth, | ||
unsigned int | iTabOrigin, | ||
const WB_RECT * | prcSource, | ||
WB_RECT * | prcDest, | ||
int | iAlignment | ||
) |
Calculate the ideal bounding rectangle for the specified text and font.
pFont | A pointer to an XFontStruct (NULL implies system default font) |
szText | A pointer to a (0-byte terminated) ASCII string that may span multiple lines |
iTabWidth | A positive integer in 'characters', or negative integer in pixels, indicating tab width |
iTabOrigin | An unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character. |
prcSource | A pointer to the 'source' bounding rectangle in which the text is intended to fit. (If NULL, the function will ALWAYS return non-zero and return the raw text extents without trying to fit it into a particular bounding rectangle.) |
prcDest | A pointer to the 'destination' bounding rectangle, based on the actual text size, and fit according to iAlignment flags. |
iAlignment | The desired text alignment, one or more of the DTAlignment bit flags |
This function will calculate the ideal bounding rectangle for the specified text, if possible, within the limitations of the source rectangle. If the text cannot be rendered within the source rectangle, the function will attempt to calculate an appropriately sized rectangle in which to render it. You can use this function to re-size windows to accomodate the size of the text that must be displayed within the window.
NOTE: tab width is negative for pixels, positive for avg char width, beginning at the left most position of the specified rectangle. Tab Origin is always in pixels using the absolute position (relative to the same origin as prcSource).
Header File: draw_text.h
WB_FONT DTCalcIdealFont | ( | Display * | pDisplay, |
WB_FONTC | pFont, | ||
const char * | szText, | ||
WB_GEOM * | geomBounds | ||
) |
Calculate the ideal font based on the text and rectangle.
pRefFont | A pointer to an XFontStruct (NULL implies system default font) |
szText | A pointer to a (0-byte terminated) ASCII string that may span multiple lines |
geomBounds | A pointer to a WB_GEOM structure that defines a bounding rectangle |
sometimes you want to adjust text size to fit within a particular rectangle. This function determines how to do that by adjusting the font size.
Header File: draw_text.h Calculate the ideal font based on the text and rectangle
pDisplay | A pointer to the Display associated with the font set |
pFont | The reference WB_FONTC (NULL implies system default font set) |
szText | A pointer to a (0-byte terminated) ASCII string that may span multiple lines |
geomBounds | A pointer to a WB_GEOM structure that defines a bounding rectangle |
sometimes you want to adjust text size to fit within a particular rectangle. This function determines how to do that by adjusting the font size. It is similar to 'DTCalcIdealFont'.
Header File: draw_text.h
Definition at line 277 of file draw_text.c.
void DTDrawMultiLineText | ( | WB_FONTC | pFont, |
const char * | szText, | ||
Display * | pDisplay, | ||
WBGC | gc, | ||
Drawable | dw, | ||
int | iTabWidth, | ||
int | iTabOrigin, | ||
const WB_RECT * | prcBounds, | ||
int | iAlignment | ||
) |
draw multi-line text
pFont | A WB_FONTC to use for drawing text (NULL implies system default font set) |
szText | A pointer to a (0-byte terminated) ASCII string that may span multiple lines |
pDisplay | the display associated with the WBGC and Drawable. |
gc | The graphics context for the drawable |
dw | The Drawable (Window or Pixmap, typically) |
iTabWidth | The width of a tab, negative for pixels, positive for avg char width |
iTabOrigin | The 'origin point' for tabulation corresponding to the first character in the string |
prcBounds | A pointer to the bounding rectangle |
iAlignment | The desired text alignment, one or more of the DTAlignment bit flags |
This function draws multi-line text within the specified bounds rectangle on the specified drawable using the specified WBGC, adjusting for tab width and text alignment.
NOTE: tabs begin at the 'left most' position, adjusted by 'iTabOrigin'.
Header File: draw_text.h
Definition at line 1538 of file draw_text.c.
void DTDrawSingleLineText | ( | WB_FONTC | pFontt, |
const char * | szText, | ||
Display * | pDisplay, | ||
WBGC | gc, | ||
Drawable | dw, | ||
int | iTabWidth, | ||
int | iTabOrigin, | ||
const WB_RECT * | prcBounds, | ||
int | iAlignment | ||
) |
draw single-line text
pFont | A WB_FONTC to use for drawing text (NULL implies system default font set) |
szText | A pointer to a (0-byte terminated) ASCII string that may span multiple lines |
pDisplay | the display associated with the WBGC and Drawable. |
gc | The graphics context for the Drawable |
dw | The Drawable (Window or Pixmap, typically) |
iTabWidth | The width of a tab, negative for pixels, positive for avg char width |
iTabOrigin | The 'origin point' for tabulation corresponding to the first character in the string |
prcBounds | A pointer to the bounding rectangle |
iAlignment | The desired text alignment, one or more of the DTAlignment bit flags |
This function draws single-line text within the specified bounds rectangle on the specified drawable using the specified WBGC, adjusting for tab width and text alignment.
If the text cannot fit within the bounding rectangle, it will be truncated.
If you want the text to wrap, use DTDrawMultiLineText()
NOTE: tabs begin at the 'left most' text position, adjusted by 'iTabOrigin'.
Header File: draw_text.h
Definition at line 1531 of file draw_text.c.
void DTDrawString | ( | Display * | pDisplay, |
Drawable | drawable, | ||
WB_FONTC | pFont, | ||
WBGC | gc, | ||
int | x, | ||
int | y, | ||
const char * | pString, | ||
int | nLength | ||
) |
Draw text in a platform-independent manner for UTF-8 or multi-byte text, equivalent to WBDrawString() using the specified WB_FONTC.
pDisplay | A pointer to the display to use for rendering the text |
drawable | The 'Drawable' object upon which to render the text |
pFont | The WB_FONTC for which to query metrics |
gc | The graphics context 'WBGC' for rendering the text |
x | The 'x' coordinate for the text alignment (left) |
y | The 'y' coordinate for the text alignment (bottom) |
pString | A const pointer to a UTF-8 or multi-byte string |
nLength | The BYTE LENGTH of the UTF-8 or mult-byte string (not character length) |
Use this function to 'Draw Text' in a platform-independent manner, using the specified WB_FONTC, upon the specified 'Drawable'. This function is the equivalent of the X11 library's XmbDrawString() and Xutf8DrawString(). It implements similar to the WBDrawString() function.
As an extra added bonus, this function may apply anti-aliasing features, as appropriate
Header File: draw_text.h
Definition at line 111 of file draw_text.c.
DT_WORDS* DTGetWordsFromText | ( | Display * | pDisplay, |
WB_FONTC | pFont, | ||
const char * | szText, | ||
int | iAlignment | ||
) |
Parse 'DT_WORDS' structure from single-line or multi-line text.
pDisplay | A pointer to the display associated with the WB_FONTC |
pFont | The WB_FONTC to be used, or NULL for the system default font set |
szText | A 0-byte terminated UFT8 string containing the text to be rendered |
iAlignment | Alignment flags (typically zero). The only flag that really matters is DTAlignment_UNDERSCORE |
The 'DT_WORDS' structure is intended to be used to cache rendering information, particularly for a large block of text that may be calculation-expensive to re-render. Call 'DTPreRender()' and 'DTRender()' to manage rendering with the DT_WORDS structure.
Header File: draw_text.h
Definition at line 365 of file draw_text.c.
void DTPreRender | ( | Display * | pDisplay, |
WB_FONTC | pFont, | ||
DT_WORDS * | pWords, | ||
int | iTabWidth, | ||
int | iTabOrigin, | ||
WB_RECT * | prcBounds, | ||
int | iAlignment, | ||
int | iStartLine, | ||
int | iEndLine | ||
) |
Pre-render a 'DT_WORDS' structure for subsequent display.
pDisplay | the display that you intend to render on with DTRender(). NULL uses the default display. |
pFont | A WB_FONTC to use for drawing text (NULL implies system default font set) |
pWords | A pointer to the DT_WORDS structure. This structure can be part of a linked list. |
iTabWidth | A positive integer in 'characters', or negative integer in pixels, indicating tab width |
iTabOrigin | An unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character. |
prcBounds | A pointer to the bounding rectangle (advisory with respect to available width and height, based on iAlignment). On return it contains the actual bounding rectangle, calculated from the passed-in value with alignment flags applied. It is important to pass the updated rectangle values when calling DTRender(). |
iAlignment | The desired text alignment, one or more of the DTAlignment bit flags |
iStartLine | The starting line to begin pre-rendering the pWords array (0 is the first line) |
iEndLine | The ending line (inclusive) to end pre-rendering the pWords array. (0 is the first line; -1 implies 'all') |
This function will scan the DT_WORDS structure 'pWords', and using the alignment flags and prcBounds, modify the 'iX' and 'iY' members for each DT_WORD entry in 'pWords' according to their rendered position within the display surface described by 'prcBounds'. It will also calculate the iMaxWidth and iMaxHeight members for 'pWords'.
Since the 'WB_RECT' elements are 32-bit integers, it is possible to create an 'infinite' display area by specifying a value of 0x7fffffffL for the 'right' and 'bottom' members. Then, you can use 'DTRender()' and specify 'iHScrollBy' and 'iVScrollBy' to modify the location of the 'viewport' area using scroll bars.
Header File: draw_text.h
Definition at line 1745 of file draw_text.c.
void DTRender | ( | Display * | pDisplay, |
WB_FONTC | pFont, | ||
const DT_WORDS * | pWords, | ||
WBGC | gc, | ||
Drawable | dw, | ||
int | iHScrollBy, | ||
int | iVScrollBy, | ||
const WB_RECT * | prcBounds, | ||
const WB_RECT * | prcViewport, | ||
int | iAlignment | ||
) |
Using pre-rendered 'DT_WORDS' structure, display.
pDisplay | the display associated with the WBGC and Drawable. |
pFont | A WB_FONTC to use for drawing text (NULL implies system default font set) |
pWords | A pointer to the DT_WORDS structure. This structure can be part of a linked list. |
gc | The graphics context for the Drawable |
dw | The Drawable (Window or Pixmap, typically) |
iHScrollBy | The amount to 'horizontally scroll by' in characters (positive values), or pixels (negative values) |
iVScrollBy | The amount to 'vertically scroll by' in characters (positive values), or pixels (negative values) |
prcBounds | A pointer to the bounding rectangle for pWords, the same rectangle calculated by DTPreRender() |
prcViewport | A pointer to the bounding rectangle for the viewport, for the Drawable 'dw'. |
iAlignment | The desired text alignment, one or more of the DTAlignment bit flags |
This function will scan the DT_WORDS structure 'pWords', and using the other parameters, render the text within the 'prcBounds' rectangle on the specified Drawable.
Header File: draw_text.h
Definition at line 1791 of file draw_text.c.
|
static |
calculate ideal bounds rectangle for text given a font, tab spacing, tab origin, and alignment
pDisplay | the Display associated with the WB_FONT |
pFont | The WB_FONT (NULL implies system default font set) |
pWords | The DT_WORDS structure for the text (this function modifies DT_WORD::iX, DT_WORD::iY) |
iTabWidth | A positive integer in 'characters', or negative integer in pixels, indicating tab width |
iTabOrigin | An unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character. |
prcSource | A pointer to the 'source' bounding rectangle in which the text is intended to fit |
prcDest | A pointer to the 'destination' bounding rectangle, based on the actual text size |
iAlignment | The desired text alignment, one or more of the DTAlignment bit flags |
iStartLine | The starting line for which to calculate ideal bounds (0-based) |
iEndLine | The ending line for which to calculate ideal bounds (0-based). A value of -1 implies "all lines" |
Internal utility to calculate the bounding rectangle for formatted multi-line text, including word wrap, tab aligment, and multiple line feeds. The pre-parsed 'DT_WORDS' contains the text, and 'prcSource' indicates the desired bounding rectangle. This function is CURRENTLY for internal use only, but this may change as code requirements develop
This function is used internally and should not be invoked. It is declared 'static' and not visible outside of the file it's defined in.
Definition at line 688 of file draw_text.c.