GpiBeginArea

This function begins the construction of an area.

Syntax

#define INCL_GPIPRIMITIVES /* Or use INCL_GPI, INCL_PM, Also in COMMON section */
#include <os2.h> 

HPS      hps;
ULONG    flOptions;
BOOL     rc;

rc = GpiBeginArea(hps, flOptions);

Parameters

hps (HPS) - input

Presentation-space handle.

flOptions (ULONG) - input

Area options.

This contains fields of option bits. One value should be selected for each option (unless the default is suitable). These values can be ORed together to determine whether to draw and include boundary lines, as well as the area interior.

Draw boundary lines:

BA_NOBOUNDARY - Does not draw boundary lines.

BA_BOUNDARY - Draws boundary lines (the default).

Construct interior mode:

BA_ALTERNATE - Constructs interior in alternate mode (the default).

BA_WINDING - Constructs interior in winding mode.

Include or exclude boundaries:

BA_INCL - Includes all boundaries in area (the default).

BA_EXCL - Excludes bottom and right boundaries.

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_AREA_CONTROL (0x2041)

An invalid options parameter was specified with GpiBeginArea.

PMERR_INV_IN_PATH (0x208B)

An attempt was made to issue a function invalid inside a path bracket.

PMERR_ALREADY_IN_AREA (0x2001)

An attempt was made to begin a new area while an existing area bracket was already open.

Remarks

The construction is terminated by the GpiEndArea function.

You can use the following list of functions to define an area. They are used between the GpiBeginArea and GpiEndArea functions:

• GpiBeginElement
• GpiBox (with the lControl parameter set to DRO_OUTLINE)
• GpiCallSegmentMatrix
• GpiComment
• GpiElement (containing a valid call)
• GpiEndElement
• GpiFullArc (with the lControl parameter set to DRO_OUTLINE)
• GpiLabel
• GpiLine
• GpiMove
• GpiPartialArc
• GpiPointArc
• GpiPolyFillet
• GpiPolyFilletSharp
• GpiPolyLine
• GpiPolySpline
• GpiPop (that pops a valid call)
• GpiSetArcParams
• GpiSetAttrMode
• GpiSetAttrs (setting valid line attributes only, or foreground color/mix (only) for other primitive types)
• GpiSetColor
• GpiSetCurrentPosition
• GpiSetLineEnd
• GpiSetLineJoin
• GpiSetLineType
• GpiSetLineWidth
• GpiSetMix
• GpiSetModelTransformMatrix

GpiBox and GpiFullArc are valid only in an area bracket (that is, between the GpiBeginArea and GpiEndArea functions with the lControl parameter set to DRO_OUTLINE. Other values of this parameter on these functions cause an implicit area bracket around the function.

Shading of the area is performed using the current pattern, as set by the GpiSetPattern function. The color and color-mixing modes that are current at the time GpiBeginArea is issued define the attributes to be applied to the pattern. The pattern reference point is also subjected to all of the transformations (including the model transformation) in force at the time of GpiBeginArea.

The area boundary consists of one or more closed figures, each constructed by:

GpiBox
    GpiFullArc �
    GpiPointArc �
    GpiLine �
    GpiPartialArc �
    GpiPolyFilletSharp �
    GpiPolyLine �
    GpiPolySpline �
    GpiPolyFillet 

The GpiSetColor and GpiSetMix functions can be used to control how the area boundary is to be colored. The GpiSetLineEnd, GpiSetLineJoin, GpiSetLineType, and GpiSetLineWidth functions can be used to control line attributes as required. GpiSetAttrs can be used as an alternative way of setting these attributes. GpiSetArcParams can be used to control the shape of arcs produced by GpiFullArc, GpiPointArc, and GpiPartialArc.

The start of a new figure is indicated by:

GpiCallSegmentMatrix �
   GpiFullArc �
   GpiMove �
   GpiPop (or end of called segment), which pops current position or a model transform �
   GpiSetCurrentPosition �
   GpiSetModelTransformMatrix 

Note: GpiCloseFigure must not be issued within an area.

A GpiBox or GpiFullArc function called within an area definition generates a complete closed figure. These functions must not be used within another figure definition.

The starting point of each closed figure is the current position when this function is made, or the point specified by the function starting the figure. Figure construction continues until either a new figure is started, or GpiEndArea is called.

Each figure should be closed, that is, the start and end points should be identical. If these points are not identical, they are joined by a straight line to arbitrarily close the figure.

The area interior is constructed either in alternate mode or in winding mode. In alternate mode, whether any point is within the interior is determined by drawing an imaginary line from that point to infinity; if there is an odd number of boundary crossings, the point is inside the area, if there is an even number of crossings, it is not.

In winding mode, the direction of the boundary lines is taken into account. Using the same imaginary line, the number of crossings is counted, as in alternate mode, but boundary lines going in one direction score plus one, and boundary lines going in the other direction score minus one. The point is in the interior if the final score is not zero.

In either mode, all of the boundaries of the area are considered to be part of the interior.

If the flOptions parameter of this function is BA_NOBOUNDARY, the boundary lines are not drawn, but the shading ends at the boundaries. If the flOptions parameter specifies BA_BOUNDARY the boundary lines and any lines added to close the figures are drawn. The lines are drawn using the current line attributes (which can be changed during construction) and shading occurs within the boundaries.

The current position is not changed by this function, but it can be changed by the moves, arcs, fillets, and lines between this function and the GpiEndArea function, including any used to close figures.

Area definitions cannot be nested. This function and the GpiEndArea function for one area must be within the same segment.

You can have no more than 1 450 straight-line vertices that describe the area.

During correlation in nonretained mode, a hit on any function within an area returns GPI_HITS in the GpiEndArea function. GPI_HITS is not returned on any of the primitives that occur within the area definition.

Example Code

This example uses the GpiBeginArea function to draw an area. The area, an isosceles triangle, is drawn with boundary lines and filled using the alternate filling mode.

#define INCL_GPIPRIMITIVES      /* GPI primitive functions      */
#include <os2.h>

HPS hps;                /* presentation space handle            */
POINTL ptlStart = { 0, 0 }; /* first vertex                     */
POINTL ptlTriangle[] = { 100, 100, 200, 0, 0, 0 }; /* vertices  */

GpiMove(hps, &ptlStart);    /* move to starting point (0, 0)     */
GpiBeginArea(hps,           /* start the area bracket            */
    BA_BOUNDARY |           /* draw boundary lines               */
    BA_ALTERNATE);          /* fill interior with alternate mode */
GpiPolyLine(hps, 3L, ptlTriangle);       /* draw the triangle    */
GpiEndArea(hps);                         /* end the area bracket */

Related Functions

• GpiBeginPath
• GpiEndArea
• GpiPop
• GpiSetAttrMode
• GpiSetAttrs
• GpiSetBackColor
• GpiSetBackMix
• GpiSetColor
• GpiSetDefAttrs
• GpiSetMix
• GpiSetPattern
• GpiSetPatternRefPoint
• GpiSetPatternSet

Graphic Elements and Orders

Element Type: OCODE_GBAR

Order: Begin Area