GreSetPageUnits

GreSetPageUnits sets the page units controlling the device transform.

This function can be hooked by the presentation driver.

Simulation support: This function is simulated by a handling routine in the graphics engine.

Syntax

 GreSetPageUnits(hdc, ulUnits, lWidth, lHeight, pInstance, lFunction);

Parameters

hdc (HDC) - input: Device context handle.

ulUnits (ULONG) - input: Page units.

Page units, as:

PU_ARBITRARY: Isotropic, arbitrary units defined by lHeight and lWidth. The page viewport is constructed to give equal X and Y spacing on the physical device, with at least one dimension of the page completely filling the corresponding default device dimension (that is, maximized window size and paper size). The origin is at the bottom left.

PU_PELS: Pel coordinates with the origin at the bottom left.

PU_LOMETRIC: Low resolution metric. These are units of 0.1 mm with the origin at the bottom left.

PU_HIMETRIC: High resolution metric. These are units of 0.01 mm with the origin at the bottom left.

PU_LOENGLISH: Units of 0.01 inch with the origin at the bottom left.

PU_HIENGLISH: Units of 0.001 inch with the origin at the bottom left.

PU_TWIPS: Twentieths of an imperial point. These are units of 1/1440 inch with the origin at the bottom left.

Other bits are reserved, and must be preserved and returned by GetPageUnits.

lWidth (LONG) - input: Page width (w).

For PU_ARBITRARY. An IWidth of 0 is set to produce equal X and Y spacing on the physical device, with both dimensions completely filling the default device dimensions. When both are passed as 0, they are set to produce equal X and Y spacing on the physical device.

lWidth and lHeight completely fill the default device dimensions so that one is equal to the corresponding default device dimension, and the other is equal to or greater than its corresponding default device dimension. These dimensions are measured in pels. For other units, a value of 0 for "w" or "h" causes the page to be set to the corresponding default dimension (that is, maximized window size and paper size) in page units or pels for isotropic units.

lHeight (LONG) - input: Page height (h). See previous parameter, IWidth.

pInstance (PVOID) - input: Pointer to instance data.

lFunction (ULONG) - input: High-order WORD=flags; low-order WORD=NGreSetPageUnits.

Return Code

rc (BOOL) - returns: Return codes.

This function returns BOOLEAN (fSuccess).

TRUE Successful
FALSE Error

Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:

PMERR_BASE_ERROR
PMERR_COORDINATE_OVERFLOW
PMERR_DEV_FUNC_NOT_INSTALLED
PMERR_HDC_BUSY
PMERR_INSUFFICIENT_MEMORY
PMERR_INV_IN_AREA
PMERR_INV_IN_PATH
PMERR_INV_LENGTH_OR_COUNT
PMERR_INV_MATRIX_ELEMENT
PMERR_INV_PATTERN_REF_PT_ATTR
PMERR_INV_RECT
PMERR_PATH_LIMIT_EXCEEDED

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Remarks

This function causes the Window/Viewport Transform, Page Viewport, and Device Transform matrixes to be updated as shown below. For PU_LOMETRIC, PU_HIMETRIC, PU_TWIPS, PU_LOENGLISH, PU_HIENGLISH, and PU_PELS:

Window/Viewport Transform Unity Page Viewport (0,0) (sx*lWidth-1, sy*lHeight-1) Device Transform As defined by the mapping from Page Window to Page Viewport

Where "sx" is the horizontal scaling required by page units for the device (or 1 for PU_PELS), and "sy" is the vertical scaling required by page units for the device (or 1 for PU_PELS).

For PU_ARBITRARY:

Window/Viewport Transform Unity Page Viewport (0,0) (X2,Y2) Device Transform As defined by the mapping from Page Window to Page Viewport

Where "Dh" is the default device (maximized window) height in pels, "Dw" is the default device (maximized window) width in pels, and "Par" is the pel (width/height) aspect ratio. X2 and Y2 are integers, determined as follows:

    When (lWidth/lHeight) > Par*(Dw/Dh):
          X2 = Dw-1
          Y2 = Par*Dw * (lWidth/lHeight)-1

    When (lWidth/lHeight) < Par*(Dw/Dh):
          X2 = (1/Par) * Dh * (lWidth/lHeight)-1
          Y2 = Dh-1

    Otherwise, when (lWidth/lHeight) = Par*(Dw/Dh):
          X2 = Dw-1
          Y2 = Dh-1

Declaration

#define INCL_GRE_XFORMS
#include <os2.h>

HDC      hdc;        /*  Device context handle. */
ULONG    ulUnits;    /*  Page units. */
LONG     lWidth;     /*  Page width (w). */
LONG     lHeight;    /*  Page height (h). See previous parameter, IWidth. */
PVOID    pInstance;  /*  Pointer to instance data. */
ULONG    lFunction;  /*  High-order WORD=flags; low-order WORD=NGreSetPageUnits. */
BOOL     rc;         /*  Return codes. */

rc = GreSetPageUnits(hdc, ulUnits, lWidth, lHeight, pInstance, lFunction);