View source for 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.

[[Image: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

{| class="wikitable"
|-
! 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

{| class="wikitable"
|-
! 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.

[[Image:1032_L3_PatternSymbolAttribu_1.png]]

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.

[[Image:1033_L3_PatternReferencePoin_2.png]]

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.

==About Polygon Primitives==

==Using Area and Polygon Primitives==