About Editing Retained Graphics and Graphics Segments

In the OS/2 operating system, applications store retained graphics in segments. One of the advantages of using graphics segments is that segments can be edited, which allows the retained image to be modified without having to re-create the unmodified portion with multiple GPI functions.

Creating and Drawing Retained Graphics described how to create a segment, and store GPI functions within the segment bracket (the GPI functions bracketed by GpiOpenSegment and GpiCloseSegment). To understand how to edit a segment, the underlying structure of a segment is described here in greater detail.

The GPI functions are not inserted directly into a segment bracket. Instead, the operating system converts the GPI functions into graphics orders. A graphics order, also known as a drawing order, is the smallest complete portion of a segment. Once the GPI functions are converted into graphics orders, these orders are stored in the GpiOpenSegment-GpiCloseSegment bracket.

Generally, each of the GPI functions within the segment bracket generates one element of the segment. An element is the smallest portion of a segment that can be edited and is made up of one or more orders. The following figure illustrates the levels of graphic segment construction.

GpiOpenSegment (...);    Graphic Segment
                        ┌───────────────────────┐              element
GpiLine (...);          │ line order            │ element 0   pointer
                        │                       │
GpiBeginElement (...);  │ begin element order   │ element 1
                        │                       │
   GpiBox (...);        │       box order       │
   GpiPolyline (...);   │       polyline order  │
                        │                       │
GpiEndElement (...);    │ end element order     │
                        │                       │
GpiLabel (...);         │ label order           │ element 2
                        │                       │
GpiSetColor (...);      │ set-color order       │ element 3
                        └───────────────────────┘
GpiCloseSegment (...);

Structure of a Graphics Segment

Elements 0, 2, and 3 are each composed of a single order. Element 1 is composed of two orders bracketed by GpiBeginElement and GpiEndElement.