View source for GPIGuide - Character String Primitives

== Character String Primitives ==

'''Character string primitives''' are printed or displayed text limited to a length of 256 characters by the PM.

The following topics are related to information in this chapter:
* Presentation spaces and device contexts
* Color and mix attributes
* Fonts
* Coordinate spaces and transformations

== About Character String Primitives ==

A PM application must make certain choices about fonts in preparation for text display or printing. Often these choices are driven by selections from a user. After the selections are made, as discussed in [[Fonts]], the application can make additional decisions about the appearance of the individual characters within the font by setting attributes in the CHARBUNDLE data structure. CHARBUNDLE is the lowest of three levels of data structures that define the appearance of displayed or printed text. The other two, FONTMETRICS and FATTRS, are described in [[Fonts]].

A font family—for instance, '''Helvetica''' or '''Courier'''—is a collection of fonts. Fonts within the same family share certain attributes such as '''stroke width''' and '''serif characteristics'''. Stroke width refers to the width of lines used to draw characters and symbols from a font. A serif is a short crossline drawn at the ends of the main strokes that form a character or symbol.

Individual fonts within a family differ from each other in the following ways:
* Height
* Line weight
* Appearance

Height refers to the point size of a font. A common example of line weight is '''boldface'''. A common example of appearance is ''italic''.

The most important factor that affects the CHARBUNDLE attributes is whether the current font is an '''image''' or an '''outline''' font. The following figure shows an example of the difference.

[[File:img17.bmp|thumb|Image and Outline Fonts]]

Outline fonts are composed of characters drawn with straight and curved lines. Image fonts, also called bit map fonts, are composed of pels arranged in certain shapes.

=== Attributes of Character String Primitives ===

Attributes of the character string primitives contained in CHARBUNDLE are as follows:
* Character set
* Character mode
* Character cell
* Character angle
* Character shear
* Character direction
* Character text alignment
* Character extra
* Character break extra
* Foreground color
* Background color
* Foreground mix
* Background mix

When an application creates a presentation space, the character string attributes are set to the default values shown in the following table.

'''Character String Attribute Default Values'''

{| class="wikitable"
|-
! Attribute !! Default Value !! Function that Redefines Attribute
|-
| '''Set''' || LCID_DEFAULT || [[GpiSetCharSet]]
|-
| '''Mode''' || CM_MODE1 || [[GpiSetCharMode]]
|-
| '''Cell''' || Outline font - Defined by device<br>Image font - Defined by font || [[GpiSetCharBox]]
|-
| '''Angle''' || (1,0) || [[GpiSetCharAngle]]
|-
| '''Shear''' || (0,1) || [[GpiSetCharShear]]
|-
| '''Direction''' || Left to right || [[GpiSetCharDirection]]
|-
| '''Text alignment''' || Left || [[GpiSetTextAlignment]]
|-
| '''Extra''' || 0 || [[GpiSetCharExtra]]
|-
| '''Break extra''' || 0 || [[GpiSetCharBreakExtra]]
|-
| '''Foreground color''' || Black || [[GpiSetAttrs]](CBB_COLOR)
|-
| '''Background color''' || Clear || [[GpiSetAttrs]](CBB_BACK_COLOR)
|-
| '''Foreground mix''' || Overpaint || [[GpiSetAttrs]](CBB_MIX_MODE)
|-
| '''Background mix''' || Leave alone || [[GpiSetAttrs]](CBB_BACK_MIX_MODE)
|}

Current character attributes take effect when you send graphics characters to an output device. They have no effect at the time you define a logical font.

==== Character Set ====

'''Character set''' defines the local identifier, '''lcid''', of the current font. The font lcid is set using [[GpiSetCharSet]]. [[GpiCreateLogFont]] associates the font with an lcid.

The value of the current lcid is determined using [[GpiQueryCharSet]].

==== Character Mode ====

Every presentation space has a current '''character mode''', which determines the extent to which a font can be affected by the attributes defined in CHARBUNDLE. The mode affects compatibility issues that are invisible to both the user and the programmer. The following table describes the character modes and their influences on the current font.

An application selects a character mode using [[GpiSetCharMode]]. When a mode is selected, it applies to any font (including the system font) used while the mode is current. The character mode takes effect when you draw character strings; it has no effect at the time you define a logical font.

'''Character Mode Effects on Character Attributes'''

{| class="wikitable"
|-
! Character Mode !! If Image Font... !! If Outline Font...
|-
| '''CM_MODE1''' || Ignores all current character attributes, except character direction. || Affected by all current character attributes.
|-
| '''CM_MODE2''' || Uses the character shear, box, angle, and direction attributes to position the character cell, but the characters themselves are not sheared, rotated, scaled, or reversed. || Affected by all current character attributes.
|-
| '''CM_MODE3''' || Raises an error if you try to draw a character string.<br>'''Note''': Any font used when the current character mode is CM_MODE3 '''must''' be an outline font. || Affected by all current character attributes.
|}

The default character mode (CM_DEFAULT) is identical to CM_MODE1.

==== Character Cell ====

A '''character cell''' is an imaginary rectangular boundary that defines the horizontal and vertical space occupied by a single character from an outline character set.

The PM calculates character cell width and height from the point size. The width value for the character cell is the nominal width of the lowercase characters in the character set. In a '''monospace''' font, the width of all character cells is identical. In a '''proportional''' font, the width of the character cells depends on the character.

In an image font, the height of the character cell is the number of pels in the font. In an outline font, the height of the character cell is the point size of the font.

The characters in a character string are positioned one character per cell. The spacing between adjacent characters in a string is affected by the character cell attribute, except for image characters in CM_MODE1.

'''Cell width''' determines the spacing of consecutive characters along the baseline, as illustrated in the following figure.

[[File:img18.bmp|thumb|Character Cell Measurements]]

Current cell size is specified using [[GpiSetCharBox]]. As input, this function accepts the desired height and width of the character cell in world coordinates. These values are related to certain dimensions in the FONTMETRICS structure that controls font attributes. Heights or widths of 0 are valid input and cause the outline character to be drawn as a point or straight line. Heights or widths of negative values cause certain special effects, for example, reversed lettering.

The character cell value affects both the size and position of characters drawn from an outline font, regardless of the current character mode. Each character is scaled up or down to fit the cell size, as shown in the following figure.

[[File:img19.bmp|thumb|Effect of the Character Cell on an Outline Font]]

The character cell value is ignored if the current font is an image font and the current character mode is CM_MODE1, as shown in the following figure.

'''Note''': It is essential to code the character cell correctly, even if you anticipate using image fonts. In case of a font match failure, an outline font can be substituted for an image font.

[[File:img20.bmp|thumb|Effect of the Character Cell on an Image Font in CM_MODE1]]

Although the character cell has been both increased and decreased, the character string is unaltered.

The character cell value controls the '''positioning''' of image-font characters when the current character mode is CM_MODE2; but it cannot cause the characters to be scaled to fit the cell. This effect is shown in the following figure.

[[File:img21.bmp|thumb|Effect of the Character Cell on an Image Font in CM_MODE2]]

If you increase the character cell size for an image font in CM_MODE2, the characters are more widely spaced, but their size is not changed. If you decrease character cell size, the space between the characters is reduced, and because the characters themselves cannot be scaled, they can overlap.

===== Default Character Cell =====

The default character-cell size is a device-dependent value. You do not need to know this value unless you want to switch back to the initial default value after having specified another value. It is recommended that you save initial default values using [[GpiSavePS]].

The default character cell, like other default attributes, can be set using [[GpiSetDefAttrs]](CBB_BOX). If necessary, you can query the current default value using [[GpiQueryDefAttrs]].

===== Coding a Character Cell =====

The dimensions that an application passes to [[GpiSetCharBox]] and that [[GpiQueryCharBox]] returns are fixed-point values. A '''fixed''' value is a 32-bit value whose high-order 16 bits contain the integral part of the floating-point number and whose low-order 16 bits contain the fractional part. The fractional part is the numerator of a fraction whose denominator is fixed at 65536. The MAKEFIXED macro provides a method for producing fixed values. If, for example, one of the character cell dimensions were 7.635 world units, an application could obtain the corresponding fixed value by using the MAKEFIXED macro, passing 7 as the first argument and 41615 as the second.

The purpose of the character cell is to assist other font metrics to define text lines. For example, if you planned to have an average text line of 60 characters, dividing your output width by 60 would provide your character cell width.

DevQueryCaps can be used to provide information about suitable character cell values. DevQueryCaps returns two sets of values that can influence the character cell:
* '''Default cell values'''
  * CAPS_GRAPHICS_CHAR_WIDTH
  * CAPS_GRAPHICS_CHAR_HEIGHT
* '''Device resolution'''
  * CAPS_HORIZONTAL_FONT_RES
  * CAPS_VERTICAL_FONT_RES

The default cell values return the size of the default character cell in pels. Convert the device resolution into character cell values by multiplying it by the desired point size, then dividing by 72 (72.2818).

==== Character Angle ====

The '''character angle''' is defined by the x-axis and a vector drawn through the origin to a specified point in a Cartesian coordinate system. Neither (0,0) nor the specified point need have any relation to the current position. The operating system then aligns the baseline with this vector.

An application can retrieve the point that defines the character angle vector using [[GpiQueryCharAngle]]. An application can set the character angle using [[GpiSetCharAngle]]. This function accepts as input the x- and y-coordinates of a point that defines the new vector. When you specify an angle, it becomes the current setting. To reset the character angle vector to its default value (parallel to the x-axis), call [[GpiSetCharAngle]] with both '''x''' and '''y''' equal to 0.

The effects of the current character angle vary depending on the current character mode and the current font type. When the current font is an outline font, the current character angle determines the angle of both the whole string and the individual characters in the string, regardless of the current character mode. The baseline of each character cell is drawn parallel to the new baseline, as shown in the following figure.

[[File:img22.bmp|thumb|Effect of the Character Angle on an Outline Font]]

The character string is drawn parallel to the vector drawn from the origin to (10,7). The baseline of each of the character cells also is drawn parallel to this vector.

The character angle value is ignored if the current font is an image font and the current character mode is CM_MODE1, as shown in the following figure.

[[File:img23.bmp|thumb|Effect of the Character Angle on an Image Font in CM_MODE1]]

The angle of the character string is unaltered by [[GpiSetCharAngle]].

When the current font is an image font and the current character mode is CM_MODE2, the current character angle determines the angle of the whole string but does not affect the individual characters in the string. The '''character reference point''', which is the point at which the character baseline intersects the left edge of the character cell, is placed on a line parallel to the new baseline. The baseline of each character cell remains parallel to the x-axis, as shown in the following figure.

[[File:img24.bmp|thumb|Effect of the Character Angle on an Image Font in CM_MODE2]]

The character string is drawn parallel to the vector from (0,0) to (10,7). Each of the characters in the string is drawn with the vertical sides of its character cell parallel to the y-axis, and with the horizontal sides of its character box parallel to the x-axis.

==== Character Shear ====

'''Character shear''' is the angle defined by the x-axis and a vector drawn through the origin to a specified point in a Cartesian coordinate system. Neither (0,0) nor the specified point need have any relation to the current position. The operating system then aligns the vertical sides of the character cell. If the font is an outline font, the operating system also aligns the vertical strokes of the characters with the vector, regardless of the current character mode, as shown in the following figure.

An application can retrieve the point that defines the character shear vector using [[GpiQueryCharShear]]. An application can set the character shear using [[GpiSetCharShear]], which accepts as input the x- and y-coordinates of a point that defines the new vector in a [[POINTL]] structure.

The '''shear''' of a character is the angle formed by the vertical lines of the character cell, and it can affect both the positioning and shape of characters in the character string. By default, the vertical lines of a character cell are parallel to the y-axis of the presentation page. As input to [[GpiSetCharShear]] supply the coordinates of the end point of a vector drawn from the origin (0,0). The effects of the current character shear value vary, depending on the current character mode and font type.

[[File:img25.bmp|thumb|Effect of Character Shear on an Outline Font]]

The character cell is drawn with its vertical lines parallel to the vector from the origin to (5,6). The character is sheared to the same degree.

The character-shear value is ignored if the current font is an image font and the current character mode is CM_MODE1, as shown in the following figure.

[[File:img26.bmp|thumb|Effect of Character Shear on an Image Font in CM_MODE1]]

The character string is unaffected by the character-shear value.

The character-shear value affects the positioning of the characters from an image font in CM_MODE2 only if character direction is CHDIRN_TOPBOTTOM or CHDIRN_BOTTOMTOP. That is, characters drawn vertically do not appear in a vertical line for nonzero shear angle from the vertical. The characters themselves cannot be sheared, as shown in the following figure.

[[File:img27.bmp|thumb|Effect of Character Shear on an Image Font in CM_MODE2]]

The character cell is sheared, and it controls the positioning of the characters; the characters themselves are unchanged.

If the x- and y-coordinate values you specify in GpiSetCharShear are both positive and negative, the characters slant from lower left to upper right. If you supply one negative and one positive value, the characters slant from upper left to lower right, as illustrated in the following figure.

[[Image:img28.png]]

Effect of X- and Y-Values on Character Shear

Character shear, like other attributes, has a default value that can be changed using GpiSetDefAttrs (CBB_SHEAR). To reset the character shear to its default effect of drawing the vertical lines of the character cell parallel to the y-axis, supply a coordinate value of (0,1) on GpiSetCharShear. 



====Character Direction====
====Character Text Alignment====
            Horizontal Alignment of a Character String
            Vertical Alignment of a Character String 
====Character Extra and Break Extra====
====Character Color and Mix ====

==Using Character String Primitives==

    Drawing Text
    Formatting Text
    Positioning Text in World Coordinates 


[[Category:WorkToDo]]