GpiSetDefAttrs

This function sets the default values of attributes for the specified primitive type.

Syntax

GpiSetDefAttrs(hps, lPrimType, flAttrMask, ppbunAttrs)

Parameters

hps (HPS) - input

Presentation-space handle.

lPrimType (LONG) - input

Primitive type.

The primitive type for which default attributes are to be set:

PRIM_LINE

Line and arc primitives

PRIM_CHAR

Character primitives

PRIM_MARKER

Marker primitives

PRIM_AREA

Area primitives

PRIM_IMAGE

Image primitives.

flAttrMask (ULONG) - input

Attributes mask.

Each flag that is set indicates that the ppbunAttrs buffer contains data for the corresponding attribute. If all the flags in flAttrMask are 0, the ppbunAttrs buffer address is not used.

Line attributes:

LBB_COLOR

Line color

LBB_MIX_MODE

Line mix

LBB_WIDTH

Line width

LBB_GEOM_WIDTH

Geometric line width

LBB_TYPE

Line type

LBB_END

Line end

LBB_JOIN

Line join.

Character attributes:

CBB_COLOR

Character color

CBB_BACK_COLOR

Character background color

CBB_MIX_MODE

Character mix

CBB_BACK_MIX_MODE

Character background mix

CBB_SET

Character set

CBB_MODE

Character mode

CBB_BOX

Character box

CBB_ANGLE

Character angle

CBB_SHEAR

Character shear

CBB_DIRECTION

Character direction

CBB_EXTRA

Character extra

CBB_BREAK_EXTRA

Character break extra Marker attributes:

MBB_COLOR

Marker color

MBB_BACK_COLOR

Marker background color

MBB_MIX_MODE

Marker mix

MBB_BACK_MIX_MODE

Marker background mix

MBB_SET

Marker set

MBB_SYMBOL

Marker symbol

MBB_BOX

Marker box.

Pattern attributes (areas):

ABB_COLOR

Area color

ABB_BACK_COLOR

Area background color

ABB_MIX_MODE

Area mix

ABB_BACK_MIX_MODE

Area background mix

ABB_SET

Pattern set

ABB_SYMBOL

Pattern symbol

ABB_REF_POINT

Pattern reference point.

Image attributes:

IBB_COLOR

Image color

IBB_BACK_COLOR

Image background color

IBB_MIX_MODE

Image mix

IBB_BACK_MIX_MODE

Image background mix.

ppbunAttrs (PBUNDLE) - input

Default attribute values.

This is a structure containing default attribute values for each attribute for which the flAttrMask flag is set, at the correct offset as specified below for the particular primitive type.

Line attributes

: ppbunAttrs consists of a LINEBUNDLE structure.

Character attributes

: ppbunAttrs consists of a CHARBUNDLE structure.

Marker attributes

: ppbunAttrs consists of a MARKERBUNDLE structure.

Pattern attributes (areas)

: ppbunAttrs consists of an AREABUNDLE structure.

Image attributes

: ppbunAttrs consists of an IMAGEBUNDLE structure.

Returns

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_PRIMITIVE_TYPE (0x20B9)

       An invalid primitive type parameter was specified with GpiSetAttrs or GpiQueryAttrs. 

PMERR_UNSUPPORTED_ATTR (0x2109)

       An unsupported attribute was specified in the attrmask with GpiSetAttrs or GpiQueryAttrs. 

PMERR_INV_COLOR_ATTR (0x2053)

       An invalid color attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_BACKGROUND_COL_ATTR (0x2044)

       An invalid background color attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_MIX_ATTR (0x20A3)

       An invalid mix attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_LINE_WIDTH_ATTR (0x2096)

       An invalid line width attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_GEOM_LINE_WIDTH_ATTR (0x2078)

       An invalid geometric line width attribute value was specified. 

PMERR_INV_LINE_TYPE_ATTR (0x2095)

       An invalid line type attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_LINE_END_ATTR (0x2093)

       An invalid line end attribute value was specified. 

PMERR_INV_LINE_JOIN_ATTR (0x2094)

       An invalid line join attribute value was specified. 

PMERR_INV_CHAR_SET_ATTR (0x204F)

       An invalid character setid attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. PMERR_INV_CHAR_MODE_ATTR (0x204D)
       An invalid character mode attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. PMERR_INV_CHAR_DIRECTION_ATTR (0x204C)
       An invalid character direction attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_CHAR_SHEAR_ATTR (0x2050)

       An invalid character shear attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. PMERR_INV_CHAR_ANGLE_ATTR (0x204B)
       The default character angle attribute value was explicitly specified with GpiSetAttrs instead of using the defaults mask. 

PMERR_INV_MARKER_SET_ATTR (0x2099)

       An invalid marker set attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. PMERR_INV_MARKER_SYMBOL_ATTR (0x209A)
       An invalid marker symbol attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. PMERR_INV_PATTERN_SET_ATTR (0x20B2)
       An invalid pattern set attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. PMERR_INV_PATTERN_ATTR (0x20B0)
       An invalid pattern symbol attribute value was specified or the default value was explicitly specified with GpiSetAttrs instead of using the defaults mask. PMERR_INV_COORDINATE (0x205B)
       An invalid coordinate value was specified. 

PMERR_UNSUPPORTED_ATTR_VALUE (0x210A)

An attribute value was specified with GpiSetAttrs that is not supported.

PMERR_INV_PATTERN_SET_FONT (0x20B3)

An attempt was made to use an unsuitable font as a pattern set.

PMERR_HUGE_FONTS_NOT_SUPPORTED (0x2035)

An attempt was made using GpiSetCharSet, GpiSetPatternSet, GpiSetMarkerSet, or GpiSetAttrs to select a font that is larger than the maximum size (64Kb) supported by the target device driver.

Remarks

Attributes are reset to their default values at the following times:

• When the presentation space is associated with a device context (see GpiAssociate).
• When GpiResetPS is issued.
• When drawing of a chained segment begins or ends (see GpiOpenSegment and GpiCloseSegment for more details).
• When an attribute-setting function (for example, GpiSetAttrs) that sets an attribute to its default value is issued, or interpreted in a retained segment during a drawing operation.

Each attribute has an initial default value, established when the presentation space is first created. The value of this is given under the appropriate GpiSet.... call. The default value can be changed by GpiSetDefAttrs. Changing the default value takes effect immediately for the current value, if this is set to default at the time.

Each attribute of the primitive type in question is represented by one flag in the flAttrMask parameter. Any attribute for which the appropriate flag is set has its default value updated to the value specified in the ppbunAttrs structure. If the attribute is currently set to take the default value, it is immediately assigned the new default value. The default value of any attribute for which the appropriate flag in flAttrMask is not set is unchanged.

The data in the ppbunAttrs buffer consists of a structure of attribute data. The layout of the structure is fixed for each primitive type. Only data for attributes for which the flag is set in flAttrMask is inspected; any other data is ignored.

Note: The buffer need be no longer than is necessary to contain the data for the highest offset attribute referenced.

If an attempt is made to set an invalid default value by this function, none of the specified default attribute values is changed. Note, however, that some invalid default attribute values (for example, certain color and mix values) may not be detected until the attribute is set to default and used, at which point the implementation optionally defaults them, or causes an error to be logged.

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the Presentation Manager Programming Reference for more information. Also, in a metafile, the default line width (see GpiSetLineWidth) is always rounded to an integer value, as is the default character box (see GpiSetCharBox) for GPIF_SHORT format presentation spaces (see GpiCreatePS).

Example Code

#define INCL_GPIDEFAULTS /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS        hps;         /*  Presentation-space handle. */
LONG       lPrimType;   /*  Primitive type. */
ULONG      flAttrMask;  /*  Attributes mask. */
PBUNDLE    ppbunAttrs;  /*  Default attribute values. */
BOOL       rc;          /*  Success indicator. */

rc = GpiSetDefAttrs(hps, lPrimType, flAttrMask,
       ppbunAttrs);

This function sets the default color of line and arc primitives to blue.

 
#define INCL_GPIDEFAULTS
#define INCL_GPIPRIMITIVES  /* for parameter definitions */
#include <OS2.H>
HPS     hps;    /* Presentation space handle     */
LINEBUNDLE bunAttrs; /* Information for color    */

bunAttrs.lColor = CLR_BLUE;


GpiSetDefAttrs(hps,
               PRIM_LINE,    /* line and arc primitives. */
               LBB_COLOR,    /* color information, which is */
                             /* contained in bunAttrs       */
               &bunAttrs);