For a list of all Structure functions and related topics, see Structures.
A structure is a resource which stores output commands for later execution. The PEX client program places output commands in a structure where they are referred to as structure elements. Structures can reference other structures; such a hierarchy of structures is called a structure network. You must be able to represent structure networks as acyclic graphs, therefore structures should not reference structures recursively, either directly or indirectly. Structures in a structure network that have no references to them are called root structures of the network. Structures that contain no references to other structures are called leaf nodes of the network. For many structure network operations, such as drawing a structure network, you select a sub-network of a structure network by designating any structure as the root structure for this subsequent operation. The implementation performs the operation, treating the designated structure as the root structure of a network.
Here is an example of a structure which is also a simple structure network:
Here is an example of a more complex structure network with two root structures of the network. Each structure element that references another structure must be of the type Execute Structure, Conditional Execute Structure, Include Structure, or Conditional Include Structure:
A structure is an X11 resource and carries all the responsibilities and access rights of X11 resources.
You render the structure elements within a structure in one of the following ways:
Use PEXGetStructureInfo to obtain the values of the following structure attributes. You modify the first three attributes directly with functions described later in this chapter. However, you may also change the element pointer implicitly with many of the structure editing functions. You cannot change any of the last three attributes directly. Their values change as you edit the structures by inserting and/or deleting elements.
Create a structure resource by invoking the PEXCreateStructure function. Add structure elements to existing structures simply by calling output command functions with the appropriate structure identifier and a request type of PEXOCStore or PEXOCStoreSingle. For more information on how PEXlib generates PEX requests for storing output commands in a structure, see Rendering and Storing Output Commands.
Delete structure resources by calling the PEXDestroyStructures function. The PEXDestroyStructures function deletes a list of structure resources that you specify and has the side effect of deleting all other structure elements which reference any of the deleted structures.
Other functions exist for dealing with structures. These include functions to change all references to a structure and obtain information about the hierarchy of a structure network. Some of these requests use the concept of an element reference path, which is an arbitrary length list of structure id/element offset pairs. A structure element is referenced with such a structure id/element offset pair. Because structures can invoke other structures, it is helpful to know the organization of the structure network. The element reference path is used to identify a unique path through a structure network.
For instance, if structure "A" is a root of a structure network or sub-network, then an element that lives at element offset 14 in structure "A" has an element reference path equal to {"A":14}. If element 14 in structure "A" is an execute structure output command that references structure "B," then element position zero in "B" has an element reference path of {"A":14, "B":0}. Because it is possible that "B" is also referenced by other structures, there may be alternative paths to the element "B":0. The depth of an element reference path is the number of element references in the path. A path depth of zero requests all unique paths leading to a particular element.