Jump to content

GpiSetAttrMode: Difference between revisions

From EDM2
Created page with "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 inv..."
 
Ak120 (talk | contribs)
mNo edit summary
Line 1: Line 1:
This function specifies the current attribute mode.  
This function specifies the current attribute mode.


==Syntax==
==Syntax==
  GpiSetAttrMode(hps, lMode);
  GpiSetAttrMode(hps, lMode)


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


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


==Errors==
==Errors==
Possible returns from WinGetLastError
Possible returns from WinGetLastError
;PMERR_INV_HPS (0x207F)
;PMERR_INV_HPS (0x207F):An invalid presentation-space handle was specified.
: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_PS_BUSY (0x20F4)
;PMERR_INV_ATTR_MODE (0x2043):An invalid mode parameter was specified with GpiSetAttrMode.
:An attempt was made to access the presentation space from more than one thread simultaneously.  
;PMERR_INV_MICROPS_FUNCTION (0x20A1):An attempt was made to issue a function that is invalid in a micro presentation space.
;PMERR_INV_ATTR_MODE (0x2043)
;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.
: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==
==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 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:
The following are affected:
 
:GpiSetArcParams
    GpiSetArcParams
:GpiSetBackColor (applies individually by primitive type if GpiSetAttrs is used)
    GpiSetBackColor (applies individually by primitive type if GpiSetAttrs is used)
:GpiSetBackMix (applies individually by primitive type if GpiSetAttrs is used)
    GpiSetBackMix (applies individually by primitive type if GpiSetAttrs is used)
:GpiSetCharAngle
    GpiSetCharAngle
:GpiSetCharBox
    GpiSetCharBox
:GpiSetCharDirection
    GpiSetCharDirection
:GpiSetCharMode
    GpiSetCharMode
:GpiSetCharSet
    GpiSetCharSet
:GpiSetCharShear
    GpiSetCharShear
:GpiSetColor (applies individually by primitive type if GpiSetAttrs is used)
    GpiSetColor (applies individually by primitive type if GpiSetAttrs is used)
:GpiSetCurrentPosition
    GpiSetCurrentPosition
:GpiSetMix (applies individually by primitive type if GpiSetAttrs is used)
    GpiSetMix (applies individually by primitive type if GpiSetAttrs is used)
:GpiSetLineEnd
    GpiSetLineEnd
:GpiSetLineJoin
    GpiSetLineJoin
:GpiSetLineType
    GpiSetLineType
:GpiSetLineWidth
    GpiSetLineWidth
:GpiSetLineWidthGeom
    GpiSetLineWidthGeom
:GpiSetMarkerBox
    GpiSetMarkerBox
:GpiSetMarkerSet
    GpiSetMarkerSet
:GpiSetMarker
    GpiSetMarker
:GpiSetModelTransformMatrix
    GpiSetModelTransformMatrix
:GpiSetPattern
    GpiSetPattern
:GpiSetPatternRefPoint
    GpiSetPatternRefPoint
:GpiSetPatternSet
    GpiSetPatternSet
:GpiSetTag.
    GpiSetTag.  


The initial value of the attribute mode, that is, its value before this function is issued, is AM_NOPRESERVE.
The initial value of the attribute mode, that is, its value before this function is issued, is AM_NOPRESERVE.
Line 72: Line 59:
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 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.  
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==
==Example Code==
<pre>
#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);
</pre>
This example uses the GpiSetAttrMode function to set the attribute mode to preserve.
This example uses the GpiSetAttrMode function to set the attribute mode to preserve.
<pre>  
<pre>  
Line 91: Line 67:
#include <OS2.H>
#include <OS2.H>


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


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


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



Revision as of 11:24, 3 April 2025

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.

 
#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