In Chapter 3. "Structures" you learned how to define structure content. The graPHIGS API also provides powerful subroutine calls that enable your application to edit the content (elements) of those structures. In addition to discussing those subroutines, this chapter discusses the operations that affect entire structures.
As you read this chapter, keep in mind that structure content editing operations require an open structure. Operations that affect entire structures do not require an open structure.
When an application program opens a structure, the element pointer points to the last element of the structure. In an empty structure, the element pointer points to the null element, conceptually element zero.
Your application can add elements one after another, because the graPHIGS API automatically increments the element pointer to each new element.
In order to edit an element within a structure, your application must position the element pointer. When processing a subroutine call that creates an element, the system either inserts that element into the structure after the current element pointer or replaces the element pointed to by the element pointer. The Set Edit Mode (GPEDMO) subroutine controls whether the elements are inserted or replaced. The default Edit Mode is 1=INSERT_MODE Therefore, to insert an element, your application must position the element pointer at the element immediately before the insertion location.
The graPHIGS API provides the Set Element Pointer GPEP subroutine to position the element pointer at any element position within a structure.
If your application specifies a negative number or a zero, in the GPEP subroutine, the system sets the element pointer at conceptual element zero.
If your application specifies a number in the GPEP subroutine that is greater than the last element's number, the system sets the element pointer at the last element.
The figure, "Inserting Elements," depicts a scenario in which your application inserts two label elements into an existing structure. Notice that your application could have chosen to insert any other valid structure element instead.
The graPHIGS API provides the Insert Label (GPINLB) subroutine in order to create a label element within a structure. Your application assigns an integer identifier to each label. These integer identifiers do not need to be unique.
A label is a type of structure element. It may be used for anything. It has no graphical effect. The graPHIGS API provides labels so your application can more easily edit structure content.
With labels, your application can delineate an element or group of elements, then later find that element or element group by advancing the element pointer to a specified label.
In the figure, "Inserting Elements," your application opens the structure with the GPOPST subroutine. After opening the structure, the current element pointer points to the last element in the structure.
In this scenario, your application uses the GPEP subroutine to position the element pointer immediately before the desired insertion point.
Your application then inserts a label "d", using the GPINLB subroutine. After the insertion, the system positions the current element pointer at the inserted element, and renumbers the following elements.
Next, your application uses the Offset Element Pointer (GPOEP) subroutine to position the element pointer forward or backward in the structure. The system adds the positive or negative offset value specified in the GPOEP subroutine to the current element pointer value. If the resulting value would move the element pointer outside of the structure, the system moves the element pointer to the nearest end of the structure, and issues a warning.
After your application uses the GPINLB subroutine to insert another label "g", the system renumbers the following elements.
Another way to position the element pointer is by using one of the following subroutines:
GPEPLB lets your application position the element pointer at any label element within an open structure. GPEPPK does the same for PICK identifier elements. GPEPCD positions the element pointer for any structure element based on the element's identifier code.
Your application locates a label, PICK identifier, or element code by specifying its integer identifier. The system searches for the next label that has the specified integer identifier, starting at the element immediately after the current element pointer. When it finds the identifier, it moves the element pointer to that position in the structure.
If the system encounters the end of a structure, it resets the element pointer to the first element and continues searching for the integer identifier until it finds it or reaches the start element.
Structures can contain more than one label with the same integer identifier. When they do, invoking GPEPLB advances the element pointer to the next label containing the specified integer identifier. GPEPPK operates in an identical fashion.
The graPHIGS API lets your application program delete elements or groups of elements in the following ways:
Whenever your application deletes an element, or group of elements, the system sets the element pointer to the element before the deleted element or group of elements using method one or two. This lets your application add new elements into the deleted location without moving the element pointer. When using method three, your application can leave the element pointer at either label.
To delete an individual element, your application sets the element pointer to the desired element, then deletes that element using the Delete Element (GPDLE) subroutine. After deletion, the API sets the element pointer to the element preceding the deleted element. The figure, "Deleting One Element," depicts the results of deleting one element.
To delete a range of elements, your application specifies a range of element numbers with the Delete Range (GPDLER) subroutine. The system deletes all elements within the range, including the specified range elements.
If either number specified in the GPDLER subroutine is outside of the structure's range, the system maps that number to the closest end of the structure. For example, if the structure has 20 elements and your application tries to delete the elements between 12 and 30, the system deletes the elements between 12 and 20.
In addition, your application program can specify the numbers in either order. Deleting elements between 12 and 30 has the same effect as deleting elements between 30 and 12.
After deleting the elements, the system moves the element pointer to the element immediately before the deleted range, regardless of element pointer's previous position.
The figure, "Results of Deleting a Range of Elements," depicts the results of deleting a range of elements.
To delete elements between two labels, your application specifies two labels by using a Delete Element Between Labels (GPDELB) or Delete Element Group (GPDLEG) subroutines.
When your application issues a GPDELB subroutine, the system initiates a search for the first occurrence of label one, starting at the element pointer's current position. If the search reaches the end of the structure, it continues from the beginning of the structure. After finding the first label, the system searches for label two in the same manner, including starting at the same original element pointer position. The same label structure element will not match both labels if the same label id is specified.
When the system finds both labels, it deletes all elements between, but not including the labels. Notice that the order in which your application specifies the labels affects the position of the element pointer after the deletion. The system resets the element pointer to the first label specified in the GPDELB subroutine. This allows your application to delete the same range and leave the element pointer in either location.
If the system does not find either label, it reports an error.
The function of the GPDLEG subroutine is similar to the GPDELB subroutine in that two labels are specified to delineate a group of elements to be deleted. GPDLEG differs from GPDELB in the following ways
The figure, "Deleting Elements Between Labels," depicts the results of deleting elements between specified labels using the GPDELB subroutine. In the figure, elements "j" and "m" are labels.
The graPHIGS API lets your application specify duplicate labels within structures. However, you should exercise caution when deleting elements between duplicate labels.
The Copy Structure (GPCPST) subroutine lets your application copy the entire contents of one structure into another. The system copies all of the elements of a specified structure into the currently open structure at the location immediately following the current element pointer. The API then moves the current element pointer to the last inserted element. The figure, "Copying a Structure," depicts how a copy structure instruction from your application is handled. Note that the copied elements are inserted into the structure even if the structure Edit Mode is set to 2=REPLACE_MODE
The Copy Element Range (GPCPER) subroutine copies a range of elements from the specified structure, into the open structure following the current element pointer. The API then moves the current element pointer to the last inserted element.
Using the current element pointer, the Move Element Range (GPMVER) subroutine lets your application move a range of elements to the the location following the element pointer. The API then moves the current element pointer to the last element that was moved.
The graPHIGS API lets your application close an open structure. When your application finishes editing the open structure, it must close the structure before opening another structure. It closes the currently open structure by using the Close Structure (GPCLST) subroutine.
|Modified Sample Program 1
Modifying the sample program according to the following statements will enable you to interactively edit the house structure.
After modifying your sample program, compile and run it. The fourth LPFK should be lit. Press it. The Line Type of the door should change from dashed to solid. Press it again. It should change back to dashed.
The instructions you have added modify the door structure by inquiring the structure element type. The application first opens the structure, then editing mode is set to replace, and then the pointer is located at the label. The pointer is then moved one element down and placed where the Line Type element is. Now the application inquires the element type, SOLID_LINE or DASHED , and replaces the element according to the result of the inquire. The structure is then closed and the workstation updated.
This section discusses operations that affect entire structures. These operations do not require an open structure. In fact, only the empty structure operation can be done in either the structure open or closed state. For your application to delete structures, the system must be in the structure closed state. The figure, "Sample Structure Network Before Empty and Delete Operations," depicts a structure network. The figures, "Results of an Empty Structure (GPEST) subroutine" and "Results of a Delete Structure (GPDLST) subroutine," depict the results of empty and delete operations applied to the structure network in the figure, "Sample Structure Network Before Empty and Delete Operations."
Your application can delete a structure's content by issuing the Empty Structure (GPEST) subroutine. This lets your application empty open or non-opened structures. If the emptied structure is open, the graPHIGS API resets the element pointer to the conceptual element zero.
The figure, "Results of an Empty Structure (GPEST) subroutine," depicts the results of emptying structure 4. Notice that this does not remove the reference to structure 4 from structures 2 and 3. However, it does disconnect structures 5 and 6 from structures 1, 2, 3, and 4.
The graPHIGS API enables your application to delete an individual structure, a group of structures, or all structures.
The Delete Structure (GPDLST) subroutine removes all references to the identified structure, since a structure exists by reference. The figure, "Results of a Delete Structure (GPDLST) subroutine," depicts the results of a Delete Structure subroutine call. Notice that the deletion of structure 4 also implies removing all references to structure 4. Notice also that although structures 5 and 6 still exist, they are no longer connected to structures 1, 2, and 3. Conceptually, deleting an individually identified structure involves deleting "upward" in the hierarchy and also deleting the elements that reference the identified structure.
The Delete Structure Network (GPDLNT) subroutine deletes a specified structure and all structures it references. These include:
The Delete Structure Network Conditionally (GPDLNC) subroutine deletes a specified root structure and conditionally deletes all of the structures referenced, both directly and indirectly, by the root structure. Only those structures which are not referenced directly or indirectly by other root structures will be deleted. For example, suppose your application creates the following structure network:
The Delete All Structures (GPDAST) subroutine causes the system to delete all structures, their identifiers, and their contents.