GreDeviceSetAttributes

GreDeviceSetAttributes sets attributes in the attribute bundle.

This function must be supported by the presentation driver.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GreDeviceSetAttributes(hdc, lBType, flDefsMask, flAttrsMask, pAttrs, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

lBType (LONG) - input

Bundle type.

Device attribute bundle. The following device bundles are defined:

• PRIM_AREA Area (Pattern) attribute bundle see Area (Pattern) Attributes.
• PRIM_CHAR Character attribute bundle see Character Attributes.
• PRIM_IMAGE Image attribute bundle see Image Attributes.
• PRIM_LINE Line attribute bundle (see Line Attributes.
• PRIM_MARKER Marker attribute bundle see Marker Attributes.

All device bundles share a similar format. They consist of two bundles, a bundle of logical attributes and a bundle of device information.

flDefsMask (ULONG) - input

Mask indicating the attributes to be set to their standard default values.

flAttrsMask (ULONG) - input

Mask indicating the attributes to be modified.

pAttrs (PBUNDLE) - input

Pointer to a bundle structure.

Pointer to the DLINEBUNDLE, DCHARBUNDLE, DMARKERBUNDLE, DAREABUNDLE, or DIMAGEBUNDLE structure containing the new attributes.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreDeviceSetAttributes.

Returns

rc (BOOL) - returns

Return Codes.

On completion, the handling routine must return a BOOLEAN value to indicate success or an error.

• 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_COORDINATE_OVERFLOW
• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_EXCEEDS_MAX_SEG_LENGTH
• PMERR_HDC_BUSY
• PMERR_HUGE_FONTS_NOT_SUPPORTED
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_BACKGROUND_COL_ATTR
• PMERR_INV_BACKGROUND_MIX_ATTR
• PMERR_INV_CHAR_DIRECTION_ATTR
• PMERR_INV_CHAR_MODE_ATTR
• PMERR_INV_CODEPAGE
• PMERR_INV_COLOR_ATTR
• PMERR_INV_COORD_SPACE
• PMERR_INV_HDC
• PMERR_INV_LENGTH_OR_COUNT
• PMERR_INV_LINE_TYPE_ATTR
• PMERR_INV_MIX_ATTR
• PMERR_INV_PATTERN_REF_PT_ATTR
• PMERR_INV_PATTERN_SET_ATTR
• PMERR_INV_PATTERN_SET_FONT

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

Sample

#define INCL_GRE_DEVMISC1
#include <os2.h>

HDC        hdc;          /*  Device context handle. */
LONG       lBType;       /*  Bundle type. */
ULONG      flDefsMask;
ULONG      flAttrsMask;  /*  Mask indicating the attributes to be modified. */
PBUNDLE    pAttrs;       /*  Pointer to a bundle structure. */
PVOID      pInstance;    /*  Pointer to instance data. */
ULONG      lFunction;
BOOL       rc;           /*  Return Codes. */

rc = GreDeviceSetAttributes(hdc, lBType, flDefsMask,
       flAttrsMask, pAttrs, pInstance, lFunction);

Remarks

This function sets attributes in the attribute bundle specified by lBType. Pointers to the current attribute bundles are maintained by presentation drivers in the instance data structure. The handling routine for GreDeviceSetAttributes modifies the specified bundle as directed by flAttrsMask and flDefsMask (see "Bundle Masks").

The handling routine must allow any attribute to be set to any value in the defined range for that attribute even when the value cannot be implemented on the device. For example, the presentation driver for a vector hardcopy device must accept BM_XOR background mix. When the hardcopy driver is called to write to the device, it should map values that cannot be implemented to the default value. If this call would set any of the attributes to a value that is not in the defined range of values for that attribute, the handling routine must restore all attributes to the value they had on entry to this routine.

When this function is called for the first time to set the character attributes, the handling routine should set the default font in the usSet parameter of the character attribute bundle (see Character Attributes). If the default font is an engine font, the presentation driver must save the address and flags of the font. This ensures that the default font is restored if the device context is reset (see ResetDCState).

Bundle Masks

The parameters flDefsMask and flAttrsMask are instances of the mask for the specified attribute bundle. Valid flags are listed under the following bundle definitions:

• Line Attributes
• Area (Pattern) Attributes
• Character Attributes
• Image Attributes
• Marker Attributes

Flags set in flAttrsMask identify which fields in the attribute bundle are to be changed. For each flag that is set in flAttrsMask, the state of that flag in flDefsMask determines the source for the new value of the field. If the flag is set in both masks, the corresponding field should be set to its default value. If the flag is set in flAttrsMask and not set in flDefsMask, the corresponding field will be set from the relevant field in the bundle addressed by pAttrs.

In the attribute bundle addressed by pAttrs, the only fields that contain valid values are those that will be used to modify the device context's attribute bundle.

When setting pattern and area attributes, the pattern origin from world coordinates must be converted (in the attributes bundle) to device coordinates (in the DC instance data).