Jump to content

GpiBeginPath: Difference between revisions

From EDM2
← Older edit
No edit summary
No edit summary
 
Line 168: Line 168:


</pre>
</pre>
==Graphic Elements and Orders==
;Element Type: OCODE_GBPTH
:Order: Begin Path


==Related Functions==
==Related Functions==
Line 193: Line 197:
* [[GpiStrokePath]]
* [[GpiStrokePath]]


==Graphic Elements and Orders==
 
;Element Type: OCODE_GBPTH
:Order: Begin Path


[[Category:Gpi]]
[[Category:Gpi]]

Latest revision as of 19:38, 7 April 2025

This function specifies the start of a path.

Syntax

GpiBeginPath(hps, lPath)

Parameters

hps (HPS) - input
Presentation-space handle.
lPath (LONG) - input
Path identifier.
This must be 1.

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_PATH_ID (0x20AE)
An invalid path identifier parameter was specified.
PMERR_ALREADY_IN_PATH (0x2003)
An attempt was made to begin a new path while an existing path bracket was already open.
PMERR_INV_IN_AREA (0x2085)
An attempt was made to issue a function invalid inside an area bracket. This can be detected while the actual drawing mode is draw or draw-and-retain or during segment drawing or correlation functions.

Remarks

Paths can be used for these purposes:

  • To generate lines and curves that have a geometric width (that is, a width that is subject to transformations); see GpiModifyPath and GpiStrokePath.
  • To generate lines and curves that have cosmetic width; see GpiOutlinePath. In particular, if the lines and curves are defined by characters drawn with an outline font, hollow characters are produced. Hollow characters can also be drawn outside paths, using the FATTR_SEL_OUTLINE FATTRS option with the GpiCreateLogFont function.
  • To generate nonrectangular shapes to be used for clipping; see GpiSetClipPath.
  • To generate shapes to be filled; see GpiFillPath. Note: Areas can also be used for filling; see GpiBeginArea.
  • To generate shapes to be converted to regions on which the region-combination function, GpiCombineRegion, can be used; see GpiPathToRegion.

There are two stages in the process of describing a path:

  1. Path specification
  2. Path definition.

Path Specification

A path is specified by a number of figures, within a GpiBeginPath - GpiEndPath pair. Each figure is specified by line functions, or curve functions, or both, and is separated from other figures by one of these functions:

A figure that is terminated by one of the functions in this list is said to be an open figure. A figure can also be terminated by a GpiCloseFigure function. This is said to be a closed figure.

A GpiBox or GpiFullArc function within a path specifies a complete closed figure. These functions must not be used within another figure specification.

GpiBeginPath initializes the path to be empty.

Path specification functions are terminated by GpiEndPath. If there are no primitives between the GpiBeginPath and GpiEndPath functions, a null path is specified. The GpiEndPath that terminates this path specification must occur within the same segment as the GpiBeginPath function.

Path specification functions can occur within a segment bracket.

Path Definition

The process of path definition causes a description of the path to be built in the currently associated device context. This description is used during any subsequent operation on the path. If the definition occurred by the drawing of a retained segment containing specification functions, these may subsequently be edited, with no effect on the path definition, until the segment is drawn again.

If the drawing mode (see GpiSetDrawingMode) is set to draw or draw-and-retain, the path is defined as it is specified. If drawing mode is retain, path definition does not occur until the segment containing the path specification is drawn.

When a path has been defined, the definition cannot be reopened. An attempt to redefine the path results in the definition being replaced.

As the path definition is kept in the device context, association of the presentation space with a new device context means that the definition is lost.

When it has been defined, a path can be used only in a single GpiFillPath, GpiStrokePath, GpiOutlinePath, GpiPathToRegion, or GpiSetClipPath function. Alternatively, a path can be modified once only with a GpiModifyPath function, and then used in a single GpiFillPath, GpiPathToRegion, or GpiSetClipPath function. If a path is required to be reused in a normal (not a micro) presentation space, it can be created in a retained segment (for example, using draw-and-retain mode [see GpiSetDrawingMode]). This segment must be drawn whenever the definition has to be recreated. This may be done even if the application is otherwise nonretained. Otherwise, the application must reissue all the individual functions to reconstruct the path whenever the definition has to be recreated.

A path definition is bound in device coordinates at the time the path is defined. If any transforms (other than the final windowing transform) are subsequently changed, they have no effect on the path itself. However, they affect the thickness if the path is to be stroked using GpiModifyPath, and they affect the pattern reference point if the path is to be filled with GpiFillPath. The transforms affect both the thickness and the pattern reference point if GpiStrokePath is used.

Other Remarks

Line type and line width have no effect on a path. Geometric line width takes effect if the path is stroked with GpiModifyPath or GpiStrokePath.

These functions can be used inside the path bracket (that is, between the GpiBeginPath function and the following GpiEndPath function) to define the path:

The GpiCharString... functions, GpiQueryCharStringPos, GpiQueryCharStringPosAt, and GpiQueryTextBox are allowed only if the current font is an outline font.

You can have no more than 1450 straight line vertices that describe the path. Curves are decomposed into straight lines internally, and the number of resulting vertices are also subject to this limit. The same applies to outline font character strings. If solid-filled outline characters are to be drawn, it is better to do this outside a path definition. GpiModifyPath and GpiStrokePath increase the number of lines in the path, and will cause a path initially containing more than 297 straight lines to exceed the limit of 1450.

It is not valid for this function to occur within an area definition.

Example Code

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

HPS     hps;    /*  Presentation-space handle. */
LONG    lPath;  /*  Path identifier. */
BOOL    rc;     /*  Success indicator. */

rc = GpiBeginPath(hps, lPath);

This example uses the GpiBeginPath function to create a path. The path, an isosceles triangle, is given path identifier 1. After the path bracket is ended using GpiEndPath, a subsequent call to the GpiFillPath function draws and fills the path. 

 
#define INCL_GPIPATHS           /* GPI Path functions           */
#include <os2.h>

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

GpiBeginPath(hps, 1L);                 /* start the path bracket */
GpiMove(hps, &ptlStart);               /* move to starting point */
GpiPolyLine(hps, 2L, ptlTriangle);     /* draw two sides         */
GpiCloseFigure(hps);                   /* close the triangle     */
GpiEndPath(hps);                       /* end the path bracket   */
GpiFillPath(hps, 1L, FPATH_ALTERNATE); /* draw and fill the path */

Graphic Elements and Orders

Element Type
OCODE_GBPTH
Order: Begin Path

Related Functions

Retrieved from "https://www.edm2.com/index.php?title=GpiBeginPath&oldid=84673"