TkGS provides basic text output primitives. These primitives are very useful to abstract the many differences between various graphics systems. The TkGS_Font already provides an encapsulated font object that addresses most of these differences.
TkGS also tries to abstract the differences of encodings used by the different systems. Modern operating systems and libraries use Unicode as their primary text encoding. Some still use system-specific encodings. For example:
To address these major differences, TkGS provides several versions of the text drawing primitives, that all accept a specific string format:
It goes without saying that the latter is not portable, since it depends on the underlying system.
Each generic primitive is implemented in three versions, and generic primitives are actually defined as macros that point to the correct version. TkGS also defines a TkGS_String macro that maps to the correct string type. For example, Tcl8.0 will use the system-encoded version with 8bit strings, and Tcl8.1 and above the UTF-8 version. Applications may call either generic of specific versions depending on their needs: Tcl8.1 may need both UTF-8 and Unicode for example.
The following specs only describe the generic primitives. The following table describes how to obtain the specific primitives:
Version | Suffix | TkGS_String | String length parameter |
---|---|---|---|
Unicode | Uni | Tcl_UniChar * | char length |
UTF-8 | Utf | char * | byte length |
System | Sys | System-specific (usually char
* ) | System-specific (usually char length) |
For example, the Unicode version of TkGS_DrawChars is TkGS_DrawCharsUni and expects the character length of the string.
Device drivers may only provide some of the specific primitives. For example, a SVG (Simple Vector Graphics, a XML format) driver may allow only Unicode output, and a PostScript driver only ANSI output. In this case, TkGS will try to convert the given strings to an useable format. This is straightforward when converting between Unicode and UTF-8, but may involve more complex computations when converting from and to system-specific encoding. However, TkGS guarantees that the text will be drawn to the maximum of the driver's possibilities.
int TkGS_MeasureChars( TkGS_Drawable d TkGS_Font font, const TkGS_String string, int length, int maxPixels, int flags, int *lengthPtr );
d
: the TkGS_Drawable
on which to measure the text.
font
: the TkGS_Font in which text
is to be measured.
string
: text to be measured. Need not be null
terminated. Any non-printing meta-characters in the string (such as
tabs, newlines, and other control characters) will be displayed in a
platform-dependent manner.
length
: the maximum string length to consider when measuring
string
. Must be greater than or equal to 0.
maxPixels
: if >= 0, it specifies the longest
permissible line length in pixels. Characters from string are processed
only until this many pixels have been covered. If < 0, then the line
length is unbounded and the flags argument is ignored.
flags
: various flag bits OR-ed together:
lengthPtr
: filled with the computed width, in pixels,
of the portion of the string that was measured.
maxPixels
subject to the conditions described
by flags
. If all characters fit, the return value will be
length
.
void TkGS_DrawChars( TkGS_Drawable d, const TkGS_String string, int length, int x, int y );
d
: the TkGS_Drawable
on which to draw the text.
string
: text to be displayed. Need not be null
terminated. Any non-printing meta-characters in the string (such as
tabs, newlines, and other control characters) will be displayed in a
platform-dependent manner.
length
: the maximum string length to consider when drawing
string
. Must be greater than or equal to 0.
x
, y
: coordinates at which to place the
left edge of the baseline when displaying string.
d
.
void TkGS_UnderlineChars( TkGS_Drawable d, const TkGS_String string, int length, int x, int y, int first, int last );
d
: the TkGS_Drawable
on which to underline the text.
string
: text to underline. Need not be null terminated.
Any non-printing meta-characters in the string (such as tabs, newlines,
and other control characters) will be displayed in a platform-dependent
manner.
length
: the maximum string length to consider when drawing
string
. Must be greater than or equal to 0.
x
, y
: coordinates at which to place the
left edge of the baseline when displaying string.
first
: the string
length after which to underline string
. Underlining
begins at the left edge of this character.
last
: the string length
up to which the underline will be drawn. The character specified by
last
will not itself be underlined.
d
.