The operating system provides segment editing functions for writing applications that allow users to edit segments or elements in a segment. For example, after performing a correlation operation using your application, a user might need to alter the elements that intersected the pick aperture. Correlation and the pick aperture are explained in in Correlation.
You can edit the contents of any retained segment that has a unique name. You also can edit the contents of a retained zero segment that has not yet been closed. Zero segments cannot be edited after they have been closed, because you cannot refer to a zero segment when it is no longer the current open segment.
Before you can begin editing, you must set the current drawing-mode parameter to DM_RETAIN. You cannot edit a segment if the current drawing-mode parameter is DM_DRAWANDRETAIN or DM_DRAW. To begin editing, call GpiOpenSegment and specify the name of the segment you want to edit. When you are finished editing a segment, close it using GpiCloseSegment.
The operating system has two edit modes: insert mode and replace mode. You can set the edit modes using GpiSetEditMode. You can determine which mode is currently set using GpiQueryEditMode.
The current edit mode applies to all segments in the presentation space until you change it. The edit mode is not an attribute of a particular segment and can be changed at any time. The default edit mode, which is set when you create a presentation space, is insert mode. When you create a graphics segment, you are actually editing it in insert mode.
If the edit mode is set to insert (SEGEM_INSERT) you can insert an element at the current location of the element pointer. The operating system shifts the element that was previously at that location into the next slot, and so on, until the last element is shifted into a new, final slot. The following figure shows a segment before and after a new element is inserted at position 0, the beginning of the segment.
Original Segment New Segment
Element Pointer
┌─────────────┐ │ │ ┌─────────────┐
Position 0 │ │────┘ └─────│ │
│ │ │ │
├─────────────┤ ├─────────────┤
Position 1 │ Element 1 │─ ─ ─ ─ ─ ─ ─ ─ ─ ─┐ │ New element │
│ │ │ │ │
├─────────────┤ │ ├─────────────┤
Position 2 │ Element 2 │─ ─ ─ ─ ─ ─ ─ ─ ─┐ └─ ─ ─│ Element 1 │
│ │ │ │ │
├─────────────┤ │ ├─────────────┤
Position 3 │ Element 3 │─ ─ ─ ─ ─ ─ ─ ─┐ └─ ─ ─ ─│ Element 2 │
│ │ │ │ │
├─────────────┤ │ ├─────────────┤
Position 4 │ Element 4 │─ ─ ─ ─ ─ ─ ─┐ └─ ─ ─ ─ ─│ Element 3 │
│ │ │ │ │
├─────────────┤ │ ├─────────────┤
Position 5 │ Element 5 │─ ─ ─ ─ ─ ─┐ └─ ─ ─ ─ ─ ─│ Element 4 │
│ │ │ │ │
├─────────────┤ │ ├─────────────┤
Position 6 │ Element 6 │─ ─ ─ ─ ─┐ └─ ─ ─ ─ ─ ─ ─│ Element 5 │
│ │ │ │ │
├─────────────┤ │ ├─────────────┤
Position 7 │ Element 7 │─ ─ ─ ─┐ └─ ─ ─ ─ ─ ─ ─ ─│ Element 6 │
│ │ │ │ │
└─────────────┘ │ ├─────────────┤
└─ ─ ─ ─ ─ ─ ─ ─ ─│ Element 7 │
│ │
└─────────────┘
Inserting a New Element in a Segment
The new element is inserted after the current element; then, the element pointer is set to the new element.
If replace mode is set (SEGEM_REPLACE) you can replace the element at the current pointer location with a new element. The following figure shows a segment before and after the third element was replaced.
Original Segment New Segment
┌─────────────┐ ┌─────────────┐
Position 0 │ │ │ │
│ │ │ │
├─────────────┤ ├─────────────┤
Position 1 │ Element 1 │ │ Element 1 │
│ │ │ │
├─────────────┤ ├─────────────┤
Position 2 │ Element 2 │ │ Element 2 │
│ │ Element pointer │ │
├─────────────┤ │ │ ├─────────────┤
Position 3 │ Element 3 │────┘ └─────│ Element 3 │
│ │ │ │
├─────────────┤ ├─────────────┤
Position 4 │ Element 4 │ │ Element 4 │
│ │ │ │
├─────────────┤ ├─────────────┤
Position 5 │ Element 5 │ │ Element 5 │
│ │ │ │
├─────────────┤ ├─────────────┤
Position 6 │ Element 6 │ │ Element 6 │
│ │ │ │
├─────────────┤ ├─────────────┤
Position 7 │ Element 7 │ │ Element 7 │
│ │ │ │
└─────────────┘ └─────────────┘
Replacing an Element with a New Element
The new element overwrites the previous element; the element pointer does not change.
Replacing elements is the recommended technique for redrawing identical primitives with different attributes-for example, color.
You can insert or replace data in an existing segment using any of the functions described in Adding Elements to a New Segment. As mentioned previously, GpiPutData is valid only in insert mode and only when the element pointer is addressing the final element in the segment. That is, when you are editing, you can use GpiPutData only to add data to the end of a segment.
A replace request is not valid when the element pointer is set to 0. If you call GpiOpenSegment to create a new segment without first ensuring that the current edit mode is insert, your first attempt to add an element to the segment might cause an error condition to be raised.