GpiPop

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

Syntax
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. 
 * 1) define INCL_GPIPRIMITIVES     /* GPI primitive functions      */
 * 2) define INCL_GPIREGIONS        /* GPI region functions         */
 * 3) include 

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