Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_GPIPRIMITIVES
 
BOOL GpiPop(hps, cAttrs)
HPS hps;        /* presentation-space handle       */
LONG cAttrs;    /* number of attributes to restore */
 
The GpiPop function restores one or more primitive attributes by popping the
previous attribute values from the attribute stack. The system saves the
previous value of a primitive attribute, such as color, line type, and fill
pattern, on the attribute stack whenever an application changes an attribute
while the attribute mode is AM_PRESERVE. The function pops the number of
attributes specified by cAttrs from the stack in last-in, first-out order.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies a presentation space.
 
cAttrs     Specifies the number of attributes to restore.
 
Return Value
 
The return value is GPI_OK if the function is successful or GPI_ERROR if an
error occurred.
 
Errors
 
Use the WinGetLastError function to retrieve the error value, which may be
one of the following:
 
     PMERR_INV_HPS
     PMERR_INV_LENGTH_OR_COUNT
     PMERR_INV_MICROPS_FUNCTION
     PMERR_PRIMITIVE_STACK_EMPTY
     PMERR_PS_BUSY
 
Comments
 
Although GpiPop can be used in an area or path bracket, an application must
ensure that the attribute to be restored is valid within the bracket. Once
an attribute is on the stack, there is no way to check it for validity.
 
The attribute stack is especially useful when you are drawing segments. Any
attributes changed by the segment can be quickly restored by popping the
stack. Note that a segment automatically pops the stack when it returns, so
a call to the GpiPop function is not required.
 
Example
 
This example uses the GpiPop function to restore the fill pattern and color
attribute after painting a path:
 
GpiSetAttrMode(hps, AM_PRESERVE);   /* preserves attributes on stack */
    .
    .
    .
GpiSetColor(hps, CLR_RED);          /* sets color to red             */
GpiSetPattern(hps, PATSYM_DIAG1);   /* sets pattern to a diagonal    */
GpiPaintRegion(hps, 3L);
GpiPop(hps, 2L);       /* restores values of last two attributes set */
 
See Also
 
GpiRestorePS, GpiSavePS, WinGetLastError
 
                                      ♦