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

#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

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

rc = GpiSetAttrMode(hps, lMode);

This example uses the GpiSetAttrMode function to set the attribute mode to preserve.

 
#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             */

Related Functions

• GpiPop
• GpiQueryAttrMode
• GpiQueryAttrs
• GpiResetPS
• GpiSetAttrs
• GpiSetDefAttrs
• GpiSetPS