GpiSetCharMode
This function controls the character mode used when drawing a character string.
Syntax
GpiSetCharMode(hps, lMode)
Parameters
- hps (HPS) - input
- Presentation-space handle.
- lMode (LONG) - input
- Character mode.
- This parameter can have one of the following values:
- CM_DEFAULT
- The default; the same as CM_MODE1 (unless changed with GpiSetDefAttrs).
- CM_MODE1
- The font selected by means of GpiSetCharSet can be either a raster font or an outline font.
- If it is a raster font, the position of characters after the first character is determined by the font metrics information, and by the character direction, character extra, and character break extra attributes. If it is an outline font, the behavior is as if the character mode is CM_MODE3.
- CM_MODE2
- The font selected by means of GpiSetCharSet can be either a raster font or an outline font.
- If it is a raster font, the position of characters after the first character is determined by the font metrics information, and some character attributes, namely, GpiSetCharAngle, GpiSetCharBox, GpiSetCharDirection, GpiSetCharExtra, GpiSetCharBreakExtra, and GpiSetCharShear (the latter is relevant only for character directions of CHDIRN_TOPBOTTOM and CHDIRN_BOTTOMTOP). If it is an outline font, the behavior is as if the character mode is CM_MODE3.
- CM_MODE3
- All character attributes are used for positioning (together with the positioning information in the font), and for scaling, rotating, and shearing the characters.
- The font selected by means of GpiSetCharSet must be an outline font; an error is raised if an attempt is made to draw a character string in CM_MODE3, and the selected font is a raster font.
Return Value
- rc (BOOL) - returns
- Success indicator.
- TRUE
- Successful completion
- FALSE
- Error occurred.
Remarks
The value of the lMode parameter controls whether the character attributes affect the positioning of characters, as follows:
- Use of Character Attributes in each Character Mode
| Character Mode | Font Type | Character Attributes (Angle, Shear, Mode and Box) |
|---|---|---|
| Mode 1 | Raster | Ignored |
| Mode 1 | Outline | Used |
| Mode 2 | Raster | Attribute information is used to position characters; characters are not sheared, rotated, or scaled. |
| Mode 2 | Outline | Used |
| Mode 3 | Raster | An error is raised when an attempt is made to draw a character string. |
| Mode 3 | Outline | Used |
This function must not be issued in an area bracket.
The attribute mode (see GpiSetAttrMode) determines whether the current value of the character-mode attribute is preserved.
Errors
Possible returns from WinGetLastError:
- PMERR_INV_HPS (0x207F)
- An invalid presentation-space handle was specified.
- PMERR_PS_BUSY (0x20F4)
- An attempt was made to access the presentation space from more than one thread simultaneously.
- PMERR_INV_CHAR_MODE_ATTR (0x204D)
- An invalid character mode attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask.
Graphic Elements and Orders
Element Type: OCODE_GSCR This element type is generated if the attribute mode (see GpiSetAttrMode) is set to AM_NOPRESERVE. Order: Set Character Precision Element Type: OCODE_GPSCR This element type is generated if the attribute mode is set to AM_PRESERVE. Order: Push and Set Character Precision
Example Code
#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, */ #include <os2.h> HPS hps; /* Presentation-space handle. */ LONG lMode; /* Character mode. */ BOOL rc; /* Success indicator. */ rc = GpiSetCharMode(hps, lMode);
In this example the GpiSetCharMode call is used to set the character mode to raster or outline when drawing a string.
#define INCL_GPIPRIMITIVES
#include <OS2.H>
HPS hps; /* Presentation space handle */
GpiSetCharMode(hps, CM_MODE3); /* The font selected by */
/* means of */
/* GpiSetCharSet can be */
/* either a raster font or */
/* an outline font. */