## Presentation Device Driver Reference for OS/2

[prev][next][parent][TOC]

### CHARBUNDLE Mask

This mask is used in calls to GreDeviceSetAttributes to identify fields in the CHARBUNDLE structure. Valid flags and the fields that they identify are :

    /-------------------------------------------------------------\

    |Flag                |Field                                   |

    |--------------------+----------------------------------------|

    |CBB_COLOR           |lColor                                  |

    |--------------------+----------------------------------------|

    |CBB_BACK_COLOR      |lBackColor                              |

    |--------------------+----------------------------------------|

    |CBB_MIX_MODE        |usMixMode                               |

    |--------------------+----------------------------------------|

    |CBB_BACK_MIX_MODE   |usBackMixMode                           |

    |--------------------+----------------------------------------|

    |CBB_SET             |usSet                                   |

    |--------------------+----------------------------------------|

    |CBB_MODE            |usPrecision                             |

    |--------------------+----------------------------------------|

    |CBB_BOX             |sizfxCell                               |

    |--------------------+----------------------------------------|

    |CBB_ANGLE           |ptlAngle                                |

    |--------------------+----------------------------------------|

    |CBB_SHEAR           |ptlShear                                |

    |--------------------+----------------------------------------|

    |CBB_DIRECTION       |usDirection                             |

    |--------------------+----------------------------------------|

    |CBB_TEXT_ALIGN      |usTextAlign                             |

    |--------------------+----------------------------------------|

    |CBB_EXTRA           |fxExtra                                 |

    |--------------------+----------------------------------------|

    |CBB_BREAK_EXTRA     |fxBreakExtra                            |

    \-------------------------------------------------------------/

cbnd The fields of a CHARBUNDLE structure are:

lColor Character foreground color.

lBackColor Character background color.

usMixMode Character foreground mix mode.

usBackMixMode Character background mix mode.

usSet Specifies a local identifier (lcid) for a logical font. If usSet is 0 , the current code page and character precision are used to resolve the selection of the base font. The code page (set by the function GreSetCodePage) identifies two base fonts: an outline font and an image font. The value of usPrecision determines which of these is selected. Valid values for usSet are:

0 Base font.
Nonzero Local identifier for the logical font defined by the cdef.defSet field in the character attributes bundle.

usPrecision Specifies the character mode. The value of usPrecision is used to select output quality from Precision 1 (the lowest) to Precision 3. Presentation drivers normally use Precision 3 except when performance is improved by using the specified precision. For example, the EGA and VGA drivers always use Precision 3 when the current font is an outline font, but switch to the specified precision for an image font.

Valid values for usPrecision are:

CM_MODE1 Precision 1. The selected font can be either an image or an outline font. When an image font is used, the first character is positioned with its reference point at the current position. Subsequent characters are positioned by using FONTMETRICS.

CM_MODE2 Precision 2. The selected font can be either an image or outline font. When an image font is used, the first character is positioned with its reference point at the current position. Subsequent characters are positioned by using the FONTMETRICS, CBB_BOX, CBB_ANGLE, and CBB_SHEAR attributes. This is done by constructing a transformation matrix that transforms the FONTMETRICS values sXDeviceRes and sYDeviceRes to the rotated, scaled, and sheared character box attributes, and translates the reference point of the first character to the current position. The actual character positions are then determined by applying this transform to the character positions found by using the FONTMETRICS.

Notice that the character box attribute is subjected to the rotation, scaling, and shear defined by the current transformations and the other character attributes.

Note: Shear attributes affect only the horizontal position of CM_MODE2 characters when the character direction is CHRDIRN_TOPBOTTOM or CHRDIRN_ BOTTOMTOP.

CM_MODE3 Precision 3. The selected font must be an outline font.

Note: CM_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.

For outline fonts, regardless of mode, all character attributes together with the FONTMETRICS are used for positioning, scaling, rotating, and shearing the characters. This is done by constructing a transformation matrix as described previously for CM_MODE2. The actual character vector stroke coordinates are then determined by applying this transform to the character-definition coordinates suitably modified (for character positioning) by the FONTMETRICS.

As with CM_MODE2, the character box attribute is subjected to the rotation, scaling, and shear defined by the current transformations and the other character attributes.

The character reference point is defined as the intersection of the base line and the left edge of the character. The baseline is defined as an offset, pCellOffset, from the top of the character cell.

sizfxCell Specifies fixed-point numbers for the width and height of a character cell in world-coordinate space. This defines the background area for a character. Each dimension is represented as a signed four-byte integer with a notational binary point between bit 16 and bit 15. Therefore , +2.5 is represented by 00028000h and -2.5 is represented by FFFD8000h.

For CM_MODE1, the cell has no effect when characters are drawn from an image font. For CM_MODE2, the width determines the spacing of consecutive characters along the baseline. Both width and height can be positive, negative, or 0. When either parameter is negative, the spacing occurs in the direction opposite to normal and each character is drawn reflected in CM_MODE3. For example, a negative height in the standard direction in Mode 3 indicates that the characters are drawn upside down, and that the string is drawn below the baseline (assuming no other transformations cause inversion). A zero character width or height is also valid. The string of characters collapses into a line. If both are 0, the string is drawn as a single point in CM_MODE3.

ptlAngle Specifies integer values X and Y for the coordinates of the end of a line starting at the origin (0, 0). The baseline for subsequent character strings is parallel to this line.

For CM_MODE1, the angle has no effect when characters are drawn.

For CM_MODE2, the angle is used to determine the position of each image character. However, the orientation of characters within the character box is inherent in their definitions. The characters are positioned so that the lower-left corners of the character definitions are placed at the lower- left corners of the character boxes.

For CM_MODE3, the angle is observed accurately and the character boxes are rotated to be normal to the character baseline. If the coordinate system is such that one X-axis unit is not physically equal to one Y-axis unit, a rotated character appears to be sheared.

ptlShear Specifies integer values, which identify the end coordinates of a line originating at 0, 0. The vertical strokes in subsequent outline character strings are drawn parallel to the defined line. For CM_MODE1, the shear has no effect when image characters are drawn. For CM_MODE2, the shear affects the height of the character cell. Therefore, the position of characters drawn with CDIRN_TOPBOTTOM or CDIRN_BOTTOMTOP. The top of the character box remains parallel to the character baseline.

If hx=0 and hy=1 (the standard default), upright characters result. If hx and hy are both positive or negative nonzero, the characters slope from bottom left to top right. If hx and hy are of opposite signs, the characters slope from top left to bottom right.

Note: The value for hy cannot be 0 (zero) because this implies an infinite shear.

No character inversion takes place as a result of shear alone. (Inversion can be done with the charCell attribute.)

usDirection Valid values are:

CHDIRN_LEFTRIGHT Left-to-right
CHDIRN_TOPBOTTOM Top-to-bottom
CHDIRN_RIGHTLEFT Right-to-left
CHDIRN_BOTTOMTOP Bottom-to-top

Note: CHDIRN_DEFAULT is the default value at the API. It is a reserved value and is not passed to the presentation driver.

If the specified direction is not valid, the presentation driver uses CHDIRN_LEFTRIGHT as the default.

usTextAlign Specifies the horizontal and vertical alignment of character strings. This alignment defines a reference point within the string, which is positioned on the starting point specified for the string.

The horizontal alignment values are as follows:

TA_NORMAL_HORIZ Normal alignment. This is the initial default. The alignment assumed depends on the current character direction:

CHDIRN_LEFTRIGHT Same as TA_LEFT
CHDIRN_TOPBOTTOM Same as TA_CENTER
CHDIRN_RIGHTLEFT Same as TA_RIGHT
CHDIRN_BOTTOMTOP Same as TA_CENTER

TA_LEFT Left alignment. The string is aligned on the left edge of its leftmost character.

TA_CENTER Center alignment. The string is aligned on the arithmetic mean of Left and Right.

TA_RIGHT Right alignment. The string is aligned on the right edge of its rightmost character.

TA_STANDARD_HORIZ Standard alignment. The alignment assumed depends on the current character direction:

CHDIRN_LEFTRIGHT Same as TA_LEFT
CHDIRN_TOPBOTTOM Same as TA_LEFT
CHDIRN_RIGHTLEFT Same as TA_RIGHT
CHDIRN_BOTTOMTOP Same as TA_LEFT

The vertical alignment values are as follows:

TA_NORMAL_VERT Normal alignment. This is the initial default. The alignment assumed depends on the current character direction:

CHDIRN_LEFTRIGHT Same as TA_BASE
CHDIRN_TOPBOTTOM Same as TA_TOP
CHDIRN_RIGHTLEFT Same as TA_BASE
CHDIRN_BOTTOMTOP Same as TA_BOTTOM

TA_TOP Top alignment. The string is aligned on the top edge of its topmost character.

TA_HALF Half alignment. The string is aligned on the arithmetic mean of Bottom and Top.

TA_BASE Base alignment. The string is aligned on the base of its bottom character.

TA_BOTTOM Bottom alignment. The string is aligned on the bottom edge of its bottom character.

TA_STANDARD Standard alignment. The alignment assumed depends on the current character direction:

CHDIRN_LEFTRIGHT Same as TA_BOTTOM
CHDIRN_TOPBOTTOM Same as TA_TOP
CHDIRN_RIGHTLEFT Same as TA_BOTTOM
CHDIRN_BOTTOMTOP Same as TA_BOTTOM

The current position will also be modified relative to the current character direction as shown:

Horizontal For horizontal character directions:

Horizontal Alignment New X Current Position
TA_LEFT Right
TA_CENTER Center
TA_RIGHT Left

Vertical Alignment New X Current Position
TA_TOP Top
TA_HALF Half
TA_BASE Base
TA_BOTTOM Bottom

Vertical For vertical character directions:

Horizontal Alignment New X Current Position
TA_LEFT Left
TA_CENTER Center
TA_RIGHT Right

Vertical Alignment New X Current Position
TA_TOP Bottom
TA_HALF Half
TA_BASE Base
TA_BOTTOM Top

fxExtra A fixed point world-coordinate distance, which is added between every character as it is being placed.

fxBreakExtra A fixed point world-coordinate distance, which is added to the width of the break character as it is placed.

cdef The fields of a CHARDEFS structure are:

defSet Character set definition. If defSet is passed as 0, the presentation driver must use the default device font (zero is passed only when the driver provides and manages its own default font). Otherwise, the significance of defSet depends upon the state of the CDEF_GENERIC flag, as follows:

If the flag is set, defSet is a pointer to an engine font.
If not set, defSet is a device font identifier defined by the driver.

When defSet is a pointer to an engine font, cdef is a pointer to an instance of the FOCAFONT data structure. The definition of the FOCAFONT data structure is included in the header file.

fFlags Valid flags are:

CDEF_GENERIC Engine font (not device font)
CDEF_BOLD Font must be made bold
CDEF_ITALIC Font must be made italic
CDEF_UNDERLINE Font must be underlined
CDEF_STRIKEOUT Font must be made overstrike

CodePage Current code page. The presentation driver ignores this field when the font is not a multicode page font that needs translating.

charSpacing Character spacing.

See the OS/2 Programming Guide for examples of these attributes.