PEXGetDescendants(3) — Subroutines

Name

PEXGetDescendants - Get Descendants

Synopsis

PEXStructurePath ∗PEXGetDescendants(Display ∗display, PEXStructure structure, int path_part, unsigned long path_depth, unsigned long ∗count_return)

Arguments

displayA pointer to a display structure returned by a successful XOpenDisplay call.

structureThe resource identifier of the structure.

path_partThe part of the path to return (PEXTopPart or PEXBottomPart).

path_depthThe maximum number of structure network path levels to be returned in each path found.

count_returnReturns the number of paths found.

Returns

An array of structure paths defining the descendants of the specified structure; a null pointer if unsuccessful.

Description

This function returns a list of structure network paths referenced by the specified structure. The elements of the returned array are of type PEXStructurePath. Paths are returned as lists of element references, each of which is represented as a structure resource identifier and an offset that gives the element’s position in the structure. Only unique paths are returned; in other words, there will be no duplicates in the returned paths.

The path part must be either PEXTopPart, which requests that the top of the structure paths be returned, or PEXBottomPart, which requests that the bottom of the structure paths be returned.

The path depth specifies the maximum number of element references to be returned in each path. If the path depth is 0, the entire path is returned. If the path depth is 1, only one element reference is returned for each path, and so on.

For instance, specifying a path depth of 0 and a path part of PEXTopPart returns all paths from structure to leaf nodes in the structure network tree in the order they would be traversed. Specifying a path depth of 1 and a path part of PEXBottomPart determines the bottom-most structures of the structure network rooted at structure.

PEXlib allocates memory for the returned descendant information. PEXFreeStructurePaths should be called to deallocate the memory.

Data Structures

typedef XID             PEXStructure;
typedef struct {
    unsigned long       count;
    PEXElementRef       ∗elements;
} PEXStructurePath;
typedef struct {
    PEXStructure        structure;
    unsigned long       offset;
} PEXElementRef;

Errors

BadPEXStructure
The specified structure resource identifier is invalid.

BadValueThe specified value for path part is invalid.

Museum