Drawing Graphics: 2.13 Shapes: Text

Programs normally display text with UI gadgetry such as GenText, VisText, and GenGlyph objects. For those times when a geode will display text as part of a graphical display, sometimes it's best to display text using direct calls to the graphics system.

Displaying Text

GrDrawText(), GrDrawTextAtCP(), GrDrawChar(), GrDrawCharAtCP(), GrDrawTextField()

There are several functions that display text. The GrDrawText() routine displays a text string. The passed y position, adjusted by the text mode (see below), determines the vertical position. The passed x position determines where the text will start printing, as normal.

GrDrawText() draws a text string at the desired position using the GState's current text attributes. This text string should contain no carriage returns, line feeds, tabs, or other non-printing characters. GrDrawTextAtCP() draws a text string at the current position. GrDrawChar() and GrDrawCharAtCP() draw a single character, which should not be a non-printing character. GrDrawTextField() draws a field of text--however, this routine is only available in Assembly language.

Special Text Attributes

GrGetTextStyle(), GrSetTextStyle(), GrGetTextMode(), GrSetTextMode(), GrGetTextSpacePad(), GrSetTextSpacePad(), GrGetFont(), GrSetFont(), GrGetTrackKern() GrSetTrackKern(), GrGetFontWeight(), GrSetFontWeight(), GrGetFontWidth(), GrSetFontWidth(), GrGetSuperscriptAttr(), GrSetSuperScriptAttr(), GrGetSubscriptAttr(), GrGetSubscriptAttr()

Applications can display text in a number of ways. Thus the GState has many attributes it keeps track of solely for drawing text.

Text style is a collective set of attributes (bold, italic, etc.) that affects how the text is drawn by the graphics system. GrGetTextStyle() gets the current text style, and GrSetTextStyle() allows a new style to be specified. Styles are expressed as a TextStyle record. Note that some complicated styles which are offered by the text objects are not available here: these styles are available only from the text objects; if you wish to offer these styles without using a text object, you'll have to do the artwork yourself.

Depending on the text mode attribute, text may either be drawn from the bottom of the font box, top of the font box, baseline, or accent line.GrGetTextMode() gets the text mode, returning information about which offset to use when drawing text. GrSetTextMode() allows this information to be reset. The information is stored in a TextMode record. Note that if you will be drawing characters of more than one size or font, and if you want those characters to line up by baseline, you should use GrSetTextMode() to use the TM_DRAW_BASE text mode.

GrSetTextSpacePad() sets the special amount used to pad space characters; GrGetTextSpacePad() retrieves the current space padding.

GrGetFont() returns the current font and type size. The font is identified by its FontID ; the default font has the ID DEFAULT_FONT_ID and size DEFAULT_FONT_SIZE ; these are the values which new GStates will start with. GrSetFont() sets a new font to use. The font's point size may be between MIN_POINT_SIZE and MAX_POINT_SIZE .

Track kerning adjusts the space between characters. A negative kerning value means that characters will be drawn closer together. A large negative kerning value can make characters draw overlapped. A positive kerning value causes characters to draw with more space between them. GrGetTrackKern() returns the present track kerning value. GrSetTrackKern() changes this value. The kerning value must be between MIN_TRACK_KERNING and MAX_TRACK_KERNING; values greater than MAX_TRACK_KERNING will be replaced by MAX_TRACK_KERNING, values less that MIN_TRACK_KERNING will result in MIN_TRACK_KERNING being used. The kerning value will be multiplied as a percentage by the font size to get a number of points to use for kerning; if this multiplied value is greater than the BBFixed (byte-byte fixed point) number MAX_KERN_VALUE or less than MIN_KERN_VALUE then it will be adjusted to fall at the end of this range.

A font's weight determines its boldness. For many fonts, there will be only two weights defined: plain and bold. However, some fonts allow for finer control of weight. To find out the current font weight, call GrGetFontWeight() . To use a different font weight, call GrSetFontWeight() . Some useful weight values are stored in the FontWeight enumerated type. The weight should definitely be between FW_MINIMUM and FW_MAXIMUM.

To make characters draw wider or narrower, adjust the font width. Some fonts come in wide or narrow versions. If the font does not support the requested width, GEOS will simulate the width as best it can. The GrGetFontWidth() routine retrieves the current width; GrSetFontWidth() changes it. Some helpful width values are stored in the FontWidth enumerated type. The width should definitely be between FWI_MINIMUM and FWI_MAXIMUM.

Geodes can control how text will be drawn in superscript and subscript styles. The super- and subscript attributes determine how to scale the characters and how far they should be displaced. There are several standard super- and subscript attributes available, including values for footnote numbers, and chemical inferiors. Typesetting enthusiasts who wish to adjust the width of these characters differently than the height (as in some standard super- and sub- script layouts) should work with the font width. Use GrGetSuperscriptAttr() and GrGetSubscriptAttr() to find out what the present values are. Use GrSetSuperscriptAttr() and GrSetSubscriptAttr() to change these values. Each of these routines works with a word sized value: the top byte is a percentage of the font size to offset sub- or superscript characters; the low byte is the percentage of font size to use for the sub- or superscript character 0x0064 (decimal 100) would be full-sized with no displacement.

Accessing Available Fonts

GrEnumFonts(), GrCheckFontAvail(), GrFindNearestPointsize(), GrGetDefFontID(), GrGetFontName()

To find out which fonts are available in the user's environment, use the GrEnumFonts() command. You specify what sorts of fonts you're interested in by setting a number of flags, and the routine will fill a buffer with the available fonts with their FontID s and names.

The FontEnumFlags record determines which fonts will be returned. At least one of the FEF_OUTLINES and FEF_BITMAPS flags must be set to determine whether outline, bitmap, or both kinds of fonts should be returned.Keep in mind that only outline fonts will result in true WYSIWYG printer output. The FEF_ALPHABETIZE flag will force the returned buffer of fonts to appear in lexical order. The FEF_DOWNCASE flag requests that the font names appear all in lowercase.

The FEF_FAMILY flag asks that the search be limited to a font family. To specify what sort of family you want, use the FontFamily enumerated type.

GrEnumFonts() ignores the FEF__STRING flag; other routines will use this flag to find out whether the font is specified by a FontID or its ASCII name.

The other flags narrow the search: if you set the FEF_FIXED_WIDTH flag, then only fixed-width fonts will be returned. If you set the FEF_USEFUL flag, only those fonts marked as "useful" will be returned.

The font information will be returned as an array of FontEnumStruct structures. Each of these structures will contain a FontID and the ASCII name of the associated font.

There may be up to MAX_FONTS available on the system. If you're not prepared to handle an array large enough to hold this many fonts, be sure to pass an argument specifying how large an array is being provided.

To find out if a given font is available in the user's environment, call either GrCheckFontAvailID() or GrCheckFontAvailName() , depending on whether the font is being identified by its FontID or its ASCII name. If programming in assembly language, use the GrCheckFontAvail() routine no matter how you're identifying the font. You may narrow the search by passing the appropriate FontEnumFlags . Make sure that the FEF_STRING bit is clear when searching by ID and set when searching by name.

Some fonts are available only in certain sizes and styles. Bitmap fonts are examples of this. The GrFindNearestPointsize() routine takes a typeface, size, and style set. It returns the closest available size and style (or returns FID_INVALID if the passed font isn't available).

To get the font which the Generic UI will use by default, call GrGetDefFontID() . This also returns the font size to use, useful if you wish to respect the user's choice of type size.

To find out the ASCII name of a string for which you have the FontID , call GrGetFontName() . If the font isn't available, this function will return false ; otherwise it will fill a passed buffer with the name of the font. The passed buffer should be FID_NAME_LEN bytes long.

Text Metrics

GrTextWidth(), GrTextWidthWWFixed(), GrTextWidthWBFixed(), GrCharWidth(), GrFontMetrics(), GrCharMetrics()

From time to time it may become important to know something about the size of a letter to be drawn. The graphics system has several routines for retrieving this information. GrTextWidth() returns the width, in points, of a string. GrTextWidthWWFixed() does the same thing, but returns a more accurate figure, including a fractional part; note that in assembly, this routine is called GrTextWidthWBFixed() . GrCharWidth() returns the width of a single character. Note that the width of a text string will normally be different than the sum of the widths of the component characters. GrTextWidth() takes track kerning and pairwise kerning into account.

GrFontMetrics() returns information pertaining to a font. The meanings of these metrics are listed below:

Height: The height of the "font box." This is how much vertical space should be allocated for a line of text. Note that when the text is drawn, some characters may go beyond these bounds. Though the height is still the vertical distance to set aside for a line of text, applications should be prepared for characters to have a vertical height equal to the maximum adjusted height, discussed below.
Maximum Adjusted Height: The maximum height required to draw the character. Some fonts contain characters that are meant to go beyond the normal vertical boundaries, perhaps extending into the space occupied by text on the next or previous line. This metric is the minimum height to guarantee being able to display such a character.
Above Box: Normally the top of the font box, the uppermost limit of a font, is 3/4 of the font's height above the baseline. For those fonts which do not follow this rule, the Above Box metric is the number of points by which the true font box extends beyond the normal font box.
Below Box: Normally, the bottom of the font box, the bottommost limit of a font, is 1/4 of the font's height below the baseline. For those fonts which do not follow this rule, the Below Box metric is the number of points by which the true font box extends below the normal font box.
Mean: The height of a typical lower case character. This metric is sometimes called the "x height," since this will be the height of a lower case "x."
Descent: How far descending characters (like "y" and "j") extend below the baseline.
Baseline: The vertical position of the bottoms of nondescending characters. The number referred to as the "baseline" is the distance between the baseline and the top of accent marks. This corresponds to the text mode TM_DRAW_BASE.
Accent: How much space to leave for accent marks. This distance is measured from the top of the accent mark area to the ascent height. This corresponds to the text mode TM_DRAW_ACCENT.
Ascent: Height of capital letters (and some tall lower-case letters, such as "f").
Underline Position: The distance from the top of the accent line to the top of the underline.
Underline Thickness: The width of the underline.
Strikethrough Position: The vertical position of the line used for "strikethrough" text.
Average Width: The average character width. This figure is normally computed as a weighted average width of lower-case characters, said average weighted based on the frequency distribution of the characters.
Maximum Width: Width of the font's widest character.
Leading: The height of the vertical gap between lines of text.
Kern Count: The number of specially kerned pairs in the font. Many fonts allow certain pairs of characters to have special spacing, known as "pair kerning." For example many fonts try to squish "To" so that the "T" and "o" are closer together than normal leading would dictate. Do not confuse kerned pairs with ligatures. A kerned pair just has strange spacing (e.g. "To" vs. "T o"); a ligature is a pair of characters which have been combined into one (e.g. "æ").
Driver: The font driver associated with the font, specified by a member of the FontMaker enumerated type.
First Character: The Char value of the first defined, drawable character.
Last Character: The Char value of the last defined, drawable character.
Default Character: The Char value of the drawable character which will be drawn as a substitute for any undrawable characters.

The GrCharMetrics() routine returns useful measurements for a character. For each of a font's characters, you may request the following information:

Width: While not a metric returned by the GrCharMetrics() routine, the character width is very important. It determines how much space to allow for the character. The metrics that follow don't affect how much space to allow; instead, they give the bounds of the area that will be drawn to. As shown, characters are free to draw beyond the area set aside for them by the width, into the space of the previous or next character.
Minimum X: The character's leftmost bound. If this value is positive, it means that the character will have some extra space before it. If the value is negative, the character may infringe on the space of the previous character. This metric is also called the "left side bearing."
Minimum Y: The character's bottommost bound. This is the character's "descent," the amount it hangs below the baseline.
Maximum X: The character's rightmost drawing bound. This value should be greater than the Minimum X. Do not confuse this metric with the character's width.
Maximum Y: The character's topmost bound. This is the distance the character extends above the baseline. It is sometimes called the character's "ascent."

The GrGetTextBounds() routine computes the drawing bounds for a string of text.

GEOS SDK TechDocs|

2.12 Regions | Next:

3 Shape Attributes