View source for GpiSetAttrMode

This function specifies the current attribute mode.

==Syntax==
 GpiSetAttrMode(hps, lMode)

==Parameters==
;hps (HPS) - input:Presentation-space handle.
;lMode (LONG) - input:Attribute mode.
::AM_PRESERVE - Preserve attributes
::AM_NOPRESERVE - Do not preserve attributes.

==Returns==
;rc (BOOL) - returns:Success indicator.
::TRUE - Successful completion
::FALSE - Error occurred.

==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_ATTR_MODE (0x2043):An invalid mode parameter was specified with GpiSetAttrMode.
;PMERR_INV_MICROPS_FUNCTION (0x20A1):An attempt was made to issue a function that is invalid in a micro presentation space.
;PMERR_INV_DC_TYPE (0x2060):An invalid type parameter was specified with DevOpenDC, or a function was issued that is invalid for a OD_METAFILE_NOQUERY device context.

==Remarks==
The attribute mode is used to specify whether a primitive attribute is to be preserved when set to a new value by a subsequent attribute setting call. The preserved value of an attribute can be restored using the GpiPop function. Any attributes that have been preserved in a called segment are automatically restored on return to the caller. The values of any attributes preserved in a chained segment, however, that are not restored using GpiPop by the end of the segment, are lost.

The following are affected:
:GpiSetArcParams
:GpiSetBackColor (applies individually by primitive type if GpiSetAttrs is used)
:GpiSetBackMix (applies individually by primitive type if GpiSetAttrs is used)
:GpiSetCharAngle
:GpiSetCharBox
:GpiSetCharDirection
:GpiSetCharMode
:GpiSetCharSet
:GpiSetCharShear
:GpiSetColor (applies individually by primitive type if GpiSetAttrs is used)
:GpiSetCurrentPosition
:GpiSetMix (applies individually by primitive type if GpiSetAttrs is used)
:GpiSetLineEnd
:GpiSetLineJoin
:GpiSetLineType
:GpiSetLineWidth
:GpiSetLineWidthGeom
:GpiSetMarkerBox
:GpiSetMarkerSet
:GpiSetMarker
:GpiSetModelTransformMatrix
:GpiSetPattern
:GpiSetPatternRefPoint
:GpiSetPatternSet
:GpiSetTag.

The initial value of the attribute mode, that is, its value before this function is issued, is AM_NOPRESERVE.

Attribute mode applies to attributes passed across the API using GpiSet... calls. What mode to use for a particular GpiSet... call is decided by the attribute mode current at the time the GpiSet... call is passed across the API. The mode may be changed at any time, and does not affect any attribute setting calls that have already been retained in the segment store.

Attribute mode only applies to individual GpiSet... calls (including GpiSetAttrs and calls such as GpiSetColor). It does not apply to any attribute setting calls passed across in bulk, such as GpiPutData, GpiElement, and GpiPlayMetaFile; these already indicate individually whether they should cause the attribute to be preserved.

Attribute mode cannot be set for GPIT_MICRO type presentation spaces, or for presentation spaces associated with OD_METAFILE_NOQUERY type device contexts (see GpiCreatePS and DevOpenDC). In these cases the presentation space behaves as if AM_NOPRESERVE is in operation.

==Example Code==
This example uses the GpiSetAttrMode function to set the attribute mode to preserve.
<pre>
#define INCL_GPIPRIMITIVES
#include <OS2.H>

HPS hps;                   /* Presentation-space handle. */

POINTL ptl[2] = { 50, 50, 100, 100 };

 GpiSetColor(hps, CLR_BLUE);
 GpiSetAttrMode(hps, AM_PRESERVE);/* sets attribute mode to preserve.   */
 GpiSetColor(hps, CLR_GREEN);     /* changes color and saves old color. */
 GpiLine(hps, &ptl[0]);           /* draws green line                   */
 GpiPop(hps, 1L);                 /* pops old attribute from stack.     */
 GpiLine(hps, &ptl[1]);           /* draws blue line                    */
</pre>

==Related Functions==
* GpiPop
* GpiQueryAttrMode
* GpiQueryAttrs
* GpiResetPS
* GpiSetAttrs
* GpiSetDefAttrs
* GpiSetPS

[[Category:Gpi]]