X11 Work Bench Toolkit  1.0
Text Drawing Utilities

Data Structures

struct  __DT_WORD__
 Structure defining a 'word' for rendering purposes. More...
 
struct  __DT_WORDS__
 A collection of DT_WORD structures along with a pointer to the original text. More...
 

Typedefs

typedef struct __DT_WORD__ DT_WORD
 Structure defining a 'word' for rendering purposes. More...
 
typedef struct __DT_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_SINGLELINE = 0x20000000, DTAlignment_UNDERSCORE = 0x40000000, DTAlignment_PRINTING = 0x80000000
}
 Alignment flags for various 'draw text' API functions. More...
 

Functions

static int InternalCalcIdealBounds (Display *pDisplay, XFontSet fontSet, 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...
 
int DTGetTextWidth (XFontSet fontSet, const char *szUTF8, int nLength)
 XTextWidth equivalent for MBCS and UTF-8 strings. More...
 
XFontStruct * DTCalcIdealFont (XFontStruct *pRefFont, const char *szText, WB_GEOM *geomBounds)
 Calculate the ideal font based on the text and rectangle. More...
 
XFontSet DTCalcIdealFontSet (Display *pDisplay, XFontSet fontSet, 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, XFontSet fontSet, 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 DTDrawSingleLineText0 (XFontStruct *pFont, const char *szText, Display *pDisplay, GC gc, Drawable dw, int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
 draw single-line text More...
 
void DTDrawSingleLineText (XFontSet fontSet, const char *szText, Display *pDisplay, GC gc, Drawable dw, int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
 draw single-line text More...
 
void DTDrawMultiLineText0 (XFontStruct *pFont, const char *szText, Display *pDisplay, GC gc, Drawable dw, int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
 draw multi-line text More...
 
void DTDrawMultiLineText (XFontSet fontSet, const char *szText, Display *pDisplay, GC gc, Drawable dw, int iTabWidth, int iTabOrigin, const WB_RECT *prcBounds, int iAlignment)
 draw multi-line text More...
 
DT_WORDSDTGetWordsFromText0 (XFontStruct *pFont, const char *szText, int iAlignment)
 Parse 'DT_WORDS' structure from single-line or multi-line text. More...
 
DT_WORDSDTGetWordsFromText (Display *pDisplay, XFontSet fontSet, const char *szText, int iAlignment)
 Parse 'DT_WORDS' structure from single-line or multi-line text. More...
 
void DTPreRender (Display *pDisplay, XFontSet fontSet, 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, XFontSet fontSet, const DT_WORDS *pWords, GC 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...
 

Detailed Description

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.

Typedef Documentation

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.

typedef struct __DT_WORD__
{
const char *pText; // pointer to start of word (most likely in the supplied buffer)
// for tabs and white space, it will be NULL
// for OTHER special characters, it points to the character
int nLength; // length of text element (in bytes)
int iWidth; // width of text in pixels (based on font size) (NA for tabs, LF, valid for white space)
int iHeight; // height of text in pixels (based on font size) (NA for tabs, LF, valid for white space)
int iIsTab; // indicates that the text consists of tabs (nLength for number of tabs, pText is NULL)
int iIsLineFeed; // indicates a line feed (CR, CRLF, LF, or LFCR) (nLength for number of line feeds, pText is NULL)
int iIsWhiteSpace; // indicates that it is 'white space' (regular or special character) (nLength, width, height applies)
int iX; // Relative 'X' pixel position for the beginning of this element (when pre-rendered, else -1)
int iY; // Relative 'Y' pixel position for the beginning of this element (when pre-rendered, else -1)

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.

typedef struct __DT_WORDS__
{
struct __DT_WORDS__ *pPrev; // pointer to previous structure in linked list (reserved)
struct __DT_WORDS__ *pNext; // pointer to next structure in linked list (reserved)
int nCount; // number of items in aWords
int nMax; // max number of items in aWords (for memory allocation purposes)
int iMaxWidth; // maximum width of contained text, or -1 if not known
int iMaxHeight; // maximum height of contained text, or -1 if not known
const char *szText; // original text pointer
DT_WORD aWords[1]; // The actual data (self-contained within the memory block)

Enumeration Type Documentation

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_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.

Function Documentation

int DTCalcIdealBounds ( Display *  pDisplay,
XFontSet  fontSet,
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.

Parameters
pDisplayThe Display associated with the XFontSet (NULL implies default display)
fontSetAn XFontSet for which to measure the bounding rectangle (None implies system default font set)
szTextA pointer to a (0-byte terminated) ASCII string that may span multiple lines
iTabWidthA positive integer in 'characters', or negative integer in pixels, indicating tab width
iTabOriginAn unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character.
prcSourceA 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.)
prcDestA pointer to the 'destination' bounding rectangle, based on the actual text size, and fit according to iAlignment flags.
iAlignmentThe desired text alignment, one or more of the DTAlignment bit flags
Returns
zero if the text will fit within prcSource, -1 error, or 1 to indicate that prcDest is larger than prcSource

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 503 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.

Parameters
pFontA pointer to an XFontStruct (NULL implies system default font)
szTextA pointer to a (0-byte terminated) ASCII string that may span multiple lines
iTabWidthA positive integer in 'characters', or negative integer in pixels, indicating tab width
iTabOriginAn unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character.
prcSourceA 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.)
prcDestA pointer to the 'destination' bounding rectangle, based on the actual text size, and fit according to iAlignment flags.
iAlignmentThe desired text alignment, one or more of the DTAlignment bit flags
Returns
zero if the text will fit within prcSource, -1 error, or 1 to indicate that prcDest is larger than prcSource

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

XFontStruct* DTCalcIdealFont ( XFontStruct *  pRefFont,
const char *  szText,
WB_GEOM geomBounds 
)

Calculate the ideal font based on the text and rectangle.

Parameters
pRefFontA pointer to an XFontStruct (NULL implies system default font)
szTextA pointer to a (0-byte terminated) ASCII string that may span multiple lines
geomBoundsA 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

Definition at line 166 of file draw_text.c.

XFontSet DTCalcIdealFontSet ( Display *  pDisplay,
XFontSet  fontSet,
const char *  szText,
WB_GEOM geomBounds 
)

Calculate the ideal font based on the text and rectangle.

Parameters
pDisplayA pointer to the Display associated with the font set
fontSetThe referense XFontSet (None implies system default font set)
szTextA pointer to a (0-byte terminated) ASCII string that may span multiple lines
geomBoundsA 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 180 of file draw_text.c.

void DTDrawMultiLineText ( XFontSet  fontSet,
const char *  szText,
Display *  pDisplay,
GC  gc,
Drawable  dw,
int  iTabWidth,
int  iTabOrigin,
const WB_RECT prcBounds,
int  iAlignment 
)

draw multi-line text

Parameters
fontSetAn XFontSet to use for drawing text (None implies system default font set)
szTextA pointer to a (0-byte terminated) ASCII string that may span multiple lines
pDisplaythe display associated with the GC and Drawable.
gcThe graphics context for the drawable
dwThe Drawable (Window or Pixmap, typically)
iTabWidthThe width of a tab, negative for pixels, positive for avg char width
iTabOriginThe 'origin point' for tabulation corresponding to the first character in the string
prcBoundsA pointer to the bounding rectangle
iAlignmentThe 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 GC, 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 1338 of file draw_text.c.

void DTDrawMultiLineText0 ( XFontStruct *  pFont,
const char *  szText,
Display *  pDisplay,
GC  gc,
Drawable  dw,
int  iTabWidth,
int  iTabOrigin,
const WB_RECT prcBounds,
int  iAlignment 
)

draw multi-line text

Parameters
pFontA pointer to the font to use for drawing text (NULL implies system default font)
szTextA pointer to a (0-byte terminated) ASCII string that may span multiple lines
pDisplaythe display associated with the GC and Drawable.
gcThe graphics context for the drawable
dwThe Drawable (Window or Pixmap, typically)
iTabWidthThe width of a tab, negative for pixels, positive for avg char width
iTabOriginThe 'origin point' for tabulation corresponding to the first character in the string
prcBoundsA pointer to the bounding rectangle
iAlignmentThe 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 GC, 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 1309 of file draw_text.c.

void DTDrawSingleLineText ( XFontSet  fontSet,
const char *  szText,
Display *  pDisplay,
GC  gc,
Drawable  dw,
int  iTabWidth,
int  iTabOrigin,
const WB_RECT prcBounds,
int  iAlignment 
)

draw single-line text

Parameters
fontSetAn XFontSet to use for drawing text (None implies system default font set)
szTextA pointer to a (0-byte terminated) ASCII string that may span multiple lines
pDisplaythe display associated with the GC and Drawable.
gcThe graphics context for the Drawable
dwThe Drawable (Window or Pixmap, typically)
iTabWidthThe width of a tab, negative for pixels, positive for avg char width
iTabOriginThe 'origin point' for tabulation corresponding to the first character in the string
prcBoundsA pointer to the bounding rectangle
iAlignmentThe 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 GC, 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 1282 of file draw_text.c.

void DTDrawSingleLineText0 ( XFontStruct *  pFont,
const char *  szText,
Display *  pDisplay,
GC  gc,
Drawable  dw,
int  iTabWidth,
int  iTabOrigin,
const WB_RECT prcBounds,
int  iAlignment 
)

draw single-line text

Parameters
pFontA pointer to the font to use for drawing text (NULL implies system default font)
szTextA pointer to a (0-byte terminated) ASCII string that may span multiple lines
pDisplaythe display associated with the GC and Drawable.
gcThe graphics context for the Drawable
dwThe Drawable (Window or Pixmap, typically)
iTabWidthThe width of a tab, negative for pixels, positive for avg char width
iTabOriginThe 'origin point' for tabulation corresponding to the first character in the string
prcBoundsA pointer to the bounding rectangle
iAlignmentThe 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 GC, 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 1255 of file draw_text.c.

int DTGetTextWidth ( XFontSet  fontSet,
const char *  szUTF8,
int  nLength 
)

XTextWidth equivalent for MBCS and UTF-8 strings.

Parameters
fontSetThe Font Set for which to query metrics
szUTF8A const pointer to a UTF-8 string
nLengthThe BYTE LENGTH of the UTF-8 string (not character length)
Returns
the text width, in pixels

Use this function in lieu of XTextWidth for MBCS and UTF-8 strings.

Header File: draw_text.h

Definition at line 134 of file draw_text.c.

DT_WORDS* DTGetWordsFromText ( Display *  pDisplay,
XFontSet  fontSet,
const char *  szText,
int  iAlignment 
)

Parse 'DT_WORDS' structure from single-line or multi-line text.

Parameters
pDisplayA pointer to the display associated with the XFontSet
fontSetThe XFontSet to be used, or None for the system default font set
szTextA 0-byte terminated UFT8 string containing the text to be rendered
iAlignmentAlignment flags (typically zero). The only flag that really matters is DTAlignment_UNDERSCORE
Returns
A 'WBAlloc'd pointer to a DT_WORDS structure (variable length). use 'WBFree()' to de-allocate the memory block.

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 289 of file draw_text.c.

DT_WORDS* DTGetWordsFromText0 ( XFontStruct *  pFont,
const char *  szText,
int  iAlignment 
)

Parse 'DT_WORDS' structure from single-line or multi-line text.

Parameters
pFontA pointer to an XFontStruct to be used, or NULL for the system default font
szTextA 0-byte terminated UFT8 string containing the text to be rendered
iAlignmentAlignment flags (typically zero). The only flag that really matters is DTAlignment_UNDERSCORE
Returns
A 'WBAlloc'd pointer to a DT_WORDS structure (variable length). use 'WBFree()' to de-allocate the memory block.

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 266 of file draw_text.c.

void DTPreRender ( Display *  pDisplay,
XFontSet  fontSet,
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.

Parameters
pDisplaythe display that you intend to render on with DTRender(). NULL uses the default display.
fontSetAn XFontSet to use for drawing text (None implies system default font set)
pWordsA pointer to the DT_WORDS structure. This structure can be part of a linked list.
iTabWidthA positive integer in 'characters', or negative integer in pixels, indicating tab width
iTabOriginAn unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character.
prcBoundsA 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().
iAlignmentThe desired text alignment, one or more of the DTAlignment bit flags
iStartLineThe starting line to begin pre-rendering the pWords array (0 is the first line)
iEndLineThe 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 1515 of file draw_text.c.

void DTRender ( Display *  pDisplay,
XFontSet  fontSet,
const DT_WORDS pWords,
GC  gc,
Drawable  dw,
int  iHScrollBy,
int  iVScrollBy,
const WB_RECT prcBounds,
const WB_RECT prcViewport,
int  iAlignment 
)

Using pre-rendered 'DT_WORDS' structure, display.

Parameters
pDisplaythe display associated with the GC and Drawable.
fontSetAn XFontSet to use for drawing text (None implies system default font set)
pWordsA pointer to the DT_WORDS structure. This structure can be part of a linked list.
gcThe graphics context for the Drawable
dwThe Drawable (Window or Pixmap, typically)
iHScrollByThe amount to 'horizontally scroll by' in characters (positive values), or pixels (negative values)
iVScrollByThe amount to 'vertically scroll by' in characters (positive values), or pixels (negative values)
prcBoundsA pointer to the bounding rectangle for pWords, the same rectangle calculated by DTPreRender()
prcViewportA pointer to the bounding rectangle for the viewport, for the Drawable 'dw'.
iAlignmentThe 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 1561 of file draw_text.c.

static int InternalCalcIdealBounds ( Display *  pDisplay,
XFontSet  fontSet,
DT_WORDS pWords,
int  iTabWidth,
unsigned int  iTabOrigin,
const WB_RECT prcSource,
WB_RECT prcDest,
int  iAlignment,
int  iStartLine,
int  iEndLine 
)
static

calculate ideal bounds rectangle for text given a font, tab spacing, tab origin, and alignment

Parameters
pDisplaythe Display associated with the XFontSet
fontSetAn XFontSet (None implies system default font set)
pWordsThe DT_WORDS structure for the text (this function modifies DT_WORD::iX, DT_WORD::iY)
iTabWidthA positive integer in 'characters', or negative integer in pixels, indicating tab width
iTabOriginAn unsigned integer indicating the tab origin, using the same units as iTabWidth, corresponding to the first character.
prcSourceA pointer to the 'source' bounding rectangle in which the text is intended to fit
prcDestA pointer to the 'destination' bounding rectangle, based on the actual text size
iAlignmentThe desired text alignment, one or more of the DTAlignment bit flags
iStartLineThe starting line for which to calculate ideal bounds (0-based)
iEndLineThe ending line for which to calculate ideal bounds (0-based). A value of -1 implies "all lines"
Returns
zero if the text will fit within prcSource, -1 error, or 1 to indicate that prcDest is larger than prcSource

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 612 of file draw_text.c.