GPIGuide - Area and Polygon Primitives

An area is one or more closed figures that can be drawn filled, outlined, or filled and outlined. If an area includes more than one figure, those figures can be separate or intersecting.

A polygon , too, is one or more closed figures that can be drawn filled, outlined, or filled and outlined. Polygons, unlike areas, are limited to figures with straight edges. Polygons also can be separate or intersecting.

The following topics are related to information in this chapter:

• Presentation spaces
• Line and arc primitives
• Color and mix attributes
• Fonts
• Bit maps
• Paths

About Area Primitives

Applications can create, outline, and fill areas and can create custom-fill patterns from bit maps or font symbols. Some graphics functions are not valid within an area definition. For example, you cannot include marker, image, or character-string primitives in an area definition.

The following figure is an example of an area.

File:1030 L2 AboutAreaPrimitives 0.png

An Area

This area comprises two hexagons, one completely enclosed by the other. The area is filled with the current area-fill pattern.

Attributes of Area Primitives

The attributes of the area primitive are contained in a data structure called AREABUNDLE. These attributes are:

• Pattern symbol
• Pattern reference point
• Pattern set
• Foreground color
• Background color
• Foreground mix attribute
• Background mix mode

When an application creates a presentation space, the area attributes are set to the default values shown in the following table.

Area Attribute Default Values

Attribute	Default Value	Function that Redefines Attribute
Pattern symbol	solid	GpiSetPattern
Pattern reference point	(0,0)	GpiSetPatternRefPoint
Pattern set	LCID_DEFAULT	GpiSetPatternSet
Foreground color	Black	GpiSetAttrs (ABB_COLOR)
Background color	Clear	GpiSetAttrs (ABB_BACK_COLOR)
Foreground mix	Overpaint	GpiSetAttrs (ABB_MIX_MODE)
Background mix	Leave alone	GpiSetAttrs (ABB_BACK_MIX_MODE)

Note: If the default (LCID_DEFAULT) for pattern set is changed, the base pattern set cannot be reselected with GpiSetPatternSet.

Pattern Symbol Attribute

The current pattern symbol, also called the symbol point code, is selected from the current pattern set with GpiSetPattern. The pattern symbol selected for the specified presentation space is used as the subsequent fill pattern until a new symbol is selected. Applications must not call GpiSetPattern while in an area or a path. If the current pattern set specifies a bit map, this attribute is ignored.

The following table describes the pattern symbols provided by the PM programming interface in a base pattern set. These symbols are not necessarily available from other pattern sets.

The Base Pattern Set

Symbol	Identifier	Long Value
Solid shading decreasing in dots per inch through PATSYM_DENSE8	PATSYM_DENSE1 through PATSYM_DENSE8	1L - 8L
Vertical lines	PATSYM_VERT	9L
Horizontal lines	PATSYM_HORIZ	10L
Lines bottom left to top right	PATSYM_DIAG1	11L
Lines bottom left to middle right	PATSYM_DIAG2	12L
Lines top left to bottom right	PATSYM_DIAG3	13L
Lines top left to middle right	PATSYM_DIAG4	14L
No shading	PATSYM_NOSHADE	15L
Solid shading	PATSYM_SOLID	16L
Alternate pels	PATSYM_HALFTONE	17L
Cartesian grid	PATSYM_HATCH	18L
Diagonal crosshatch	PATSYM_DIAGHATCH	19L
Blank (often called the clear pattern)	PATSYM_BLANK	64L

The default pattern symbol (PATSYM_DEFAULT) is identical to the PATSYM_SOLID symbol, and has a long value of 0L. The error pattern symbol (PATSYM_ERROR) has a long value of -1L.

The following figure shows the patterns from the base pattern symbol set. Applications can determine the current pattern set by calling GpiQueryPattern.

The Base Pattern Symbol Set

Pattern Reference Point Attribute

The pattern reference point is the point from which the area's fill-pattern spreads horizontally and vertically. The lower-left corner of the pattern is aligned on this point. The pattern reference point has a default value of (0,0), and is expressed in world coordinates. Applications can determine the pattern reference point with GpiQueryPatternRefPoint. Applications can specify the pattern reference point with GpiSetPatternRefPoint; however, this should not be done inside an area. The pattern reference point does not have to be within the boundary of the area. The following figure shows an area that was filled using the default pattern reference point.

The Pattern Reference Point

The pattern of diagonal lines is aligned with the pattern reference point (0,0). When the picture is displayed or printed, only the hexagon will be filled.

Use of the default reference point causes the diagonal lines of the pattern to intersect the area boundary at specific points. If you change the reference point to (0,4), for example, the pattern shifts upward, and the points of intersection with the area boundary are different. Although the reference point is outside the area, when an application displays or prints the picture, only the area is filled.

Pattern Set Attribute

When you create a presentation space, the current pattern set and other area attributes are set to the default. The current pattern-a black solid, as described earlier- is specified from the supplied pattern set. (The supplied set of pattern symbols contains image or raster patterns only.) An area primitive is filled by repeating this pattern vertically and horizontally within the area boundary.

Default Pattern Set

The standard pattern set contains patterns of solid shading with decreasing intensity, and patterns of vertical, horizontal, and diagonal lines. If the default pattern set is changed with GpiSetDefAttrs, its patterns are not accessible. The patterns from the default set can be recovered by specifying GpiSetDefAttrs with the value LCID_DEFAULT, (0).

Customizing Pattern Sets

An application can create custom patterns by using bit maps or characters and symbols from an image font. When designing custom patterns, consider that the operating system uses only the first eight bits in the first eight rows, starting with the lower-left corner of the bit map. The cell size of an image font used as a fill pattern might be too large to include the complete character or symbol.

An application can change the appearance of a fill pattern by changing its alignment in an area primitive with GpiSetPatternRefPoint. When the default reference point is set, the operating system aligns the lower-left corner of the fill pattern with the point (0,0) in the application's world space and begins filling the area. If an application adjusts the pattern reference point to (3,2), The operating system aligns the lower-left corner of the fill pattern with the point (3,2) in the application's world space and begins filling the area. By moving the reference point from (0,0) to (3,2), the fill pattern appears shifted up two pels and to the right three pels.

Custom Fill Patterns from a Bit Map

To create a custom pattern from a hard-coded bit map, an application must use the following steps: 1. Create or load a bit map to obtain a bit-map handle; for example, use GpiLoadBitmap. 2. Call GpiSetBitmapId (ID) to tag the bit map with a local identifier (lcid) from 1 to 254. 3. Call GpiSetPatternSet (ID) or GpiSetAttrs (ABB_SET) to set the current fill pattern.

The application can now draw the area.

Custom Fill Patterns from a Font Symbol

To create a custom pattern from a character or a symbol in a font: 1. Create a logical image font and assign it an ID; for example use GpiCreateLogFont. 2. Call GpiSetPatternSet (ID) or GpiSetAttrs (ABB_SET), passing it the local identifier for the font. 3. Call GpiSetPattern, passing the value of the code point for a character or symbol in the font.

The application can now draw the area.