GetTreeItem

int GetTreeItem (int panelHandle, int controlID, int relation, int relativeIndex, int beginIndex, int direction, int stateCriteria, int *item);

Purpose

Searches for an item that is relation to relativeIndex. The search starts at beginIndex and proceeds in the direction specified by direction.

Returns in the item parameter the index of the first item that meets stateCriteria.

Parameters

Input
Name Type Description
panelHandle integer Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID integer The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by NewCtrl or DuplicateCtrl.
relation integer Defines the relationship between the relative index and the items to be searched.

You can select the following values.

VAL_ALL—Search all items regardless of their relationship to the relative item.
VAL_SIBLING—Search only items that are siblings of the relative item.
VAL_CHILD—Search only items that are children of the relative item.
VAL_DESCENDENT—Search all items that are descendents of the relative item.
VAL_ANCESTOR—Search all items that are ancestors of the relative item.
relativeIndex integer Zero-based index of the item whose relatives defined by the relation parameter will be searched.
beginIndex integer Zero-based index of the item where the search begins.

The item at beginIndex must meet the relation requirement to the relative index.

Use VAL_FIRST to start at the first item that meets the relation requirement to the relative index. The first ancestor is the parent of the relative item.

Use VAL_LAST to start at the last item that meets the relation requirement to the relative index. The last ancestor is the ancestor of the relative item that is on level zero.
direction integer Defines the direction of the items from beginIndex to search.

You can select the following values:

VAL_NEXT—Include the items below beginIndex in the search.
VAL_NEXT_PLUS_SELF—Include the items below beginIndex, along with the item at beginIndex, in the search.
VAL_PREV—Include the items above beginIndex in the search.
VAL_PREV_PLUS_SELF—Include the items above beginIndex, along with the item at beginIndex, in the search.
stateCriteria integer Defines the state of the searched for item.

Use any combination of the following masks to define the state of the searched for item:
VAL_SELECTED Item that is selected
VAL_UNSELECTED Item that is unselected
VAL_EXPOSED Item with all ancestors expanded
VAL_UNEXPOSED Item with at least one ancestor collapsed
VAL_MARKED Item whose radio button or check box is marked
VAL_UNMARKED Item whose radio button or check box is not marked
VAL_PARTIALLY_MARKED Item whose radio button or check box is partially marked
VAL_EXPANDED Item that has children and is expanded
VAL_COLLAPSED Item that has children and is collapsed
VAL_LEAF Item that does not have children

For example, if you pass (VAL_SELECTED | VAL_MARKED) the function will search for an item that is selected as well as marked.

Pass 0 to count items regardless of their state.
Output
Name Type Description
item integer The index of the first item in the tree control that has the specified relationship with the relative index that also meets the requirements of stateCriteria.

–1 indicates that no item meets the search requirements.

Return Value

Name Type Description
status integer Return value indicating whether the function was successful. A negative number indicates that an error occurred.

Code Error Message String
xx Success