PEXGetAncestors(3) — Subroutines

Name

PEXGetAncestors - Get Ancestors

Synopsis

PEXStructurePath ∗PEXGetAncestors(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 ancestors of the specified structure; a null pointer if unsuccessful.

Description

This function returns a list of structure network paths which reference the specified structure. 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 list of 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. A path depth of 2 returns two elements, and so on.

Specifying a path depth of 0 and a path part of PEXTopPart returns the unique top parts of all paths to structure. Specifying a path depth of 1 and a path part of PEXTopPart returns the root structure of all structure networks which contain structure. A path depth of 2 and path part of PEXBottomPart returns all of the structure’s immediate ancestors. Determine the number of references to structure by setting the path depth to 1 and the path part to PEXBottomPart.

PEXlib allocates memory for the returned ancestor 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