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:

Primitive Type	Description
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:

Attribute	Description
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:

Attribute	Description
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

Character break extra Marker attributes:

Attribute	Description
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):

Attribute	Description
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:

Attribute	Description
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

Error Code (Hex)	Error Description
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);