TkGS Specification - Drawing primitives: Text

Introduction

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:

Encoding-specific primitives

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:

VersionSuffixTkGS_StringString length parameter
UnicodeUniTcl_UniChar *char length
UTF-8Utfchar *byte length
SystemSysSystem-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.

Driver considerations

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.

Structures


TkGS_String
Description
This is a macro that is set to the generic string type. See the above table for more details.
Status
Specification complete. Not yet implemented.

Functions


TkGS_MeasureChars
Description
This function is directly adapted from Tk's Tk_MeasureChars. The main difference is that it needs a TkGS_Drawable to be specified, because the result may depend on the drawable's settings (eg point size and coordinates transforms). It is used both to compute the length of a given string and to compute how many characters from a string fit in a given amount of space. *lengthPtr is filled with the computed width, in pixels, of the portion of the string that was measured. For example, if the return value is 5, then *lengthPtr is filled with the distance between the left edge of string[0] and the right edge of string.
Status
Specification complete. Not yet implemented.
Declaration
int TkGS_MeasureChars(
    TkGS_Drawable     d
    TkGS_Font         font,
    const TkGS_String string,
    int               length,
    int               maxPixels,
    int               flags,
    int               *lengthPtr
);
Arguments
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:
  • TKGS_PARTIAL_OK means include a character as long as any part of it fits in the length given by maxPixels; otherwise, a character must fit completely to be considered.
  • TKGS_WHOLE_WORDS means stop on a word boundary, if possible.
  • If TKGS_AT_LEAST_ONE is set, it means return at least one character even if no characters could fit in the length given by maxPixels.
  • If TK_AT_LEAST_ONE is set and TK_WHOLE_WORDS is also set, it means that if not even one word fits on the line, return the first few letters of the word that did fit; if not even one letter of the word fit, then the first letter will still be returned.
lengthPtr: filled with the computed width, in pixels, of the portion of the string that was measured.
Returned value
String length that fits in the space specified by maxPixels subject to the conditions described by flags. If all characters fit, the return value will be length.
Side effects
None.

TkGS_DrawChars
Description
This function is directly adapted from Tk's Tk_DrawChars. The main difference is that it doesn't take a font argument, instead it uses the one currently used in the given drawable (set with TkGS_SetGCValues or TkGS_SetFont). It draws the string at the given location in the given drawable.
Status
Specification complete. Not yet implemented.
Declaration
void TkGS_DrawChars(
    TkGS_Drawable     d,
    const TkGS_String string,
    int               length,
    int               x,
    int               y
);
Arguments
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.
Returned value
None.
Side effects
The primitive is drawn on d.

TkGS_UnderlineChars
Description
This function is directly adapted from Tk's Tk_UnderlineChars. The main difference is that it doesn't take a font argument, instead it uses the one currently used in the given drawable (set with TkGS_SetGCValues or TkGS_SetFont). It underlines the string at the given location in the given drawable.
Status
Specification complete. Not yet implemented.
Declaration
void TkGS_UnderlineChars(
    TkGS_Drawable     d,
    const TkGS_String string,
    int               length,
    int               x,
    int               y,
    int               first,
    int               last
);
Arguments
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.
Returned value
None.
Side effects
The primitive is drawn on d.

TODO