View source for 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 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==
<PRE>
#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, */
#include &lt;os2.h&gt;

HPS     hps;    /* Presentation-space handle. */
LONG    lMode;  /* Character mode. */
BOOL    rc;     /* Success indicator. */

rc = GpiSetCharMode(hps, lMode);
</PRE>

In this example the GpiSetCharMode call is used to set the character mode to raster or outline when drawing a string.

<pre>
#define INCL_GPIPRIMITIVES
#include &lt;OS2.H&gt;

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. */
</pre>

==Related Functions==
* [[GpiCharString]]
* [[GpiCharStringAt]]
* [[GpiCharStringPos]]
* [[GpiCharStringPosAt]]
* [[GpiPop]]
* [[GpiSetAttrs]]
* [[GpiSetAttrMode]]
* [[GpiSetCharAngle]]
* [[GpiSetCharBox]]
* [[GpiSetCharDirection]]
* [[GpiSetCharSet]]
* [[GpiSetCharShear]]
* [[GpiSetDefAttrs]]
* [[GpiQueryCharMode]]
* [[GpiQueryCharStringPos]]
* [[GpiQueryCharStringPosAt]]

[[Category:Gpi]]