Programming Guide:xppguide

Graphic segments Foundation

A graphic segment contains one or more graphic primitives and allows the result of several graphic primitives to be redrawn without having to call the graphic primitives again. Graphic segments can also have a numeric ID and can be found based on a specified point in the coordinate system. For example, this can allow an application to determine which graphic segment a mouse click occurred in. The definition of a graphic segment is initiated using the function GraSegOpen() which returns the numeric ID for the new segment. All subsequent calls to graphic primitives are recorded in the segment until the definition of the graphic segment is completed using GraSegClose().

After the graphic segment is defined, all graphic primitives contained in the segment are redrawn when the function GraSegDraw() is called. The functions used to program graphic segments are listed in the following table:

Functions for graphic segments
Function Description
GraSegOpen() Initiates definition of graphic segment
GraSegClose() Terminates definition of graphic segment
GraSegPriority() Sets drawing order of graphic segment
GraSegDestroy() Releases graphic segment
GraSegDraw() Draws graphic segment
GraSegDrawMode() Specifies drawing mode for graphic segments
GraSegFind() Locates graphic segment based on position
GraSegPickResolution() Sets resolution used in searching for segments

A graphic segment can be viewed as a complex primitive consisting of many graphic primitives that are executed between GraSegOpen() and GraSegClose(). Drawing, or making a graphic segment visible, depends on the drawing mode defined in the presentation space when the segment is opened with GraSegOpen(). There are three different modes that are set using the function GraSegDrawMode():

Drawing modes for graphic segments
Constant Description
GRA_DM_DRAW Primitives between GraSegOpen() and GraSegClose() are drawn but not stored
GRA_DM_RETAIN Primitives between GraSegOpen() and GraSegClose() are stored but not drawn
GRA_DM_DRAWANDRETAIN Primitives between GraSegOpen() and GraSegClose() are drawn and stored

The GRA_DM_DRAW mode draws but does not store the primitives defined in the segment. The segment cannot be redrawn using GraSegDraw(). This mode is only useful when a drawing is to be stored in a metafile (see the sub-section "The metafile - XbpMetaFile()" in the section "Graphic output devices").

The GRA_DM_RETAIN drawing mode stores all graphic primitives in a segment, but does not display them. This allows complex drawings to be defined invisibly to the user step by step, and then made visible all at once using GraSegDraw(). In the third drawing mode, output occurs while the segment is being defined and all graphic primitives are already visible when the segment is closed using GraSegClose(). In this mode, the function GraSegDraw() only has to be called if the segment needs to be redrawn.

If graphic segments are defined for a window, only graphic primitives can be stored in the segment and not the attributes for the graphic primitives. When a segment is drawn, the attributes for points, lines, areas and characters that are set when GraSegDraw() is called are used for the display.

When graphic segments are stored in a metafile, the attributes are also stored.

The defined graphic segments are arranged in priority which increases in the order the segments were defined. The first segment defined has the lowest priority and the last segment defined has the highest priority. The priority determines the order in which graphic segments are drawn. If the function GraSegDraw() is called without parameters, all graphic segments are redrawn. The segment with the lowest priority is drawn first and the segment with the highest priority is drawn last. This is significant when graphic segments overlap each other during drawing. The segments with higher priority paint over segments with lower priority. The result is that segments with high priority appear "in front" and segments with low priority appear "behind" the segments with high priority. The priority can be thought of as the z axis in a three dimensional coordinate system. The higher the priority, the more toward the front the graphic segments appear if they overlap other segments. The function GraSegPriority() raises or lowers the priority of an individual segment in relation to a second segment.

A unique characteristic of graphic segments is the fact that they can be "found" based on their position. This is done using the function GraSegFind() which is passed the coordinates for a point as a parameter and returns an array containing the numeric IDs of all the graphic segments which encompass this point. The graphic segments can then be used for user interaction. After a mouse click, for example, the coordinates of the mouse pointer can be passed to the function GraSegFind() in order to identify all graphic segments that include the point where the mouse was clicked. The function GraSegFind() does not consider the exact coordinates of the mouse pointer (the point at the tip of the mouse pointer), but works with a virtual rectangle which is moved along with the mouse pointer. It is possible to find a graphic segment where the mouse pointer is near the segment but remains just outside. In this case the virtual rectangle around the mouse pointer overlaps the edge of the segment. The size of the virtual rectangle can be set using the function GraSegPickResolution() and determines the preciseness or resolution used by the function GraSegFind() in searching for graphic segments.


If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.