GpiPop

Description

This function restores the primitive attributes that have been saved on the stack.

Syntax

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

HPS     hps;     /*  Presentation-space handle. */
LONG    lCount;  /*  Number of attributes to be restored. */
BOOL    rc;      /*  Success indicator. */

rc = GpiPop(hps, lCount);

Parameters

hps (HPS) - input

Presentation-space handle.

lCount (LONG) - input

Number of attributes to be restored.

It must be greater or equal to 0.

Return Code

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_MICROPS_FUNCTION (0x20A1)

An attempt was made to issue a function that is invalid in a micro presentation space.

PMERR_INV_LENGTH_OR_COUNT (0x2092)

An invalid length or count parameter was specified.

PMERR_SEG_CALL_STACK_EMPTY (0x20FC)

A call stack empty condition was detected when attempting a pop function during GpiPop or segment drawing.

Remarks

Each time a primitive attribute call (such as color, or line type) is issued and the attribute mode is set to AM_PRESERVE, the values are put into a "Last in, First out" stack.

This function can reset the current attribute values (starting with the last one set) to the previous value; this is known as "popping". This allows a called segment to change the values of the attributes, and allows them to be restored on return to the caller (an implicit GpiPop function is performed for each preserved attribute when returning from a called segment).

When inside an area or path definition, this function is only valid if the attribute being popped is valid inside an area or path definition.

Note: It is not possible to check whether the attribute to be popped is valid before issuing this function.

Example Code

This example uses the GpiPop function to restore the fill pattern and color attribute after painting a region.

#define INCL_GPIPRIMITIVES      /* GPI primitive functions      */
#define INCL_GPIREGIONS         /* GPI region functions         */
#include <os2.h>

HPS hps;                /* presentation space handle            */
HRGN hrgn;              /* region handle                        */

/* preserves attributes on stack */
GpiSetAttrMode(hps, AM_PRESERVE);
    .
    .
    .
GpiSetColor(hps, CLR_RED);        /* sets color to red          */
GpiSetPattern(hps, PATSYM_DIAG1); /* sets pattern to a diagonal */
GpiPaintRegion(hps, hrgn);
GpiPop(hps, 2L);  /* restores values of last two attributes set */

Graphic Elements and Orders

Element Type: OCODE_GPOP

Order: Pop 
  lCount of these orders are generated.

Related Functions

• GpiQueryAttrMode
• GpiQueryAttrs
• GpiQueryDefAttrs
• GpiRestorePS
• GpiSetAttrMode
• GpiSetAttrs
• GpiSetDefAttrs