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_GPICONTROL
 
BOOL GpiAssociate(hps, hdc)
HPS hps;    /* presentation-space handle */
HDC hdc;    /* device-context handle     */
 
The GpiAssociate function associates a presentation space with a device
context and resets the presentation space. Once a device context is
associated with a presentation space, all subsequent drawing in the
presentation space is copied to the device.
 
Only one device context can be associated with a presentation space at a
time. GpiAssociate cannot associate a new device context with a presentation
space until the current device context is released. The function releases
the current device context from the presentation space if hdc is NULL.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hps        Identifies a normal presentation space. Micro and cached
           presentation spaces cannot be used.
 
hdc        Identifies the device context. Although any type of device
           context may be used, the device context must not be already
           associated with a presentation space.
 
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_DC_IS_ASSOCIATED
      PMERR_INV_HDC
      PMERR_INV_HPS
      PMERR_INV_MICROPS_FUNCTION
      PMERR_PS_BUSY
      PMERR_PS_IS_ASSOCIATED
 
Comments
 
When GpiAssociate resets the presentation space, it sets all attributes to
their default values, sets the model transform to unity, sets the current
position to (0,0), closes any open path, area, or element brackets, closes
any open segment, removes any clip path, viewing limits and clip region, and
enables kerning if the device supports kerning.
 
The GpiCreatePS function can also be used to associate a device context with
a new presentation space.
 
Example
 
This example releases the current device context and associates a new device
context with the presentation space.
 
HPS hps;
HDC hdcPrinter;
GpiAssociate(hps, (HDC) NULL); /* release the current device context */
GpiAssociate(hps, hdcPrinter); /* associate a printer device context */
 
See Also
 
GpiCreatePS, GpiResetPS, WinGetLastError
 
                                      ♦