GetTreeItemFromLabel
int GetTreeItemFromLabel (int panelHandle, int controlID, int relation, int relativeIndex, int beginIndex, int direction, int stateCriteria, char itemLabel[], int *item);
Purpose
Searches for an item with the specified label. The search range is defined by the relation and the 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 has the specified label and that meets stateCriteria.
Example Code
The following example code demonstrates how to search for and select tree items that have the specified label text. The example assumes that the Selection Mode for the tree is set to Multiple.
int CVICALLBACK SearchTree (int panel, int control, int event, void *callbackData, int eventData1, int eventData2)
{
char label[256];
int item = 0,
beginIndex = VAL_FIRST,
direction = VAL_NEXT_PLUS_SELF,
firstIteration = 1;
switch (event)
{
case EVENT_COMMIT:
/* Get the search string from the user interface */
GetCtrlVal (panelHandle, PANEL_SEARCH_STRING, label);
/* Iterate from the active tree item until there are no more matches to find */
while (item!=-1)
{
GetTreeItemFromLabel (panelHandle, PANEL_TREE, VAL_ALL, 0, beginIndex, direction, 0, label, &item);
/* On the next iteration, start from current item */
beginIndex = item;
if (item!=-1)
{
/* Select the tree item if its label matches the specified search string */
SetTreeItemAttribute (panelHandle, PANEL_TREE, item, ATTR_SELECTED, 1);
}
/* If the item is not found on the first iteration, pop up a message indicating there are no matches */
else if (firstIteration)
{
MessagePopup ("No match", "The search string does not match any tree item labels.");
}
/* After the first iteration, no longer include the beginIndex item in the search */
if (firstIteration)
{
direction = VAL_NEXT;
firstIteration = 0;
}
}
break;
}
return 0;
}
Supported Controls
You can use GetTreeItemFromLabel with tree controls.
Parameters
| Input | ||||||||||||||||||||||||
| Name | Type | Description | ||||||||||||||||||||||
| panelHandle | int | Specifier for a particular panel that is currently in memory. You can obtain this handle from functions such as LoadPanel and NewPanel. | ||||||||||||||||||||||
| controlID | int | 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 functions such as NewCtrl and DuplicateCtrl. | ||||||||||||||||||||||
| relation | int |
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 | int | Zero-based index of the item whose relatives defined by the relation parameter will be searched. | ||||||||||||||||||||||
| beginIndex | int |
Zero-based index of the item where the search begins. If beginIndex does not equal relativeIndex, the item at beginIndex must be related to the item at relativeIndex as specified by relation. 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 | int |
Defines the direction of the items from beginIndex to search. You can select the following items: 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 | int |
Defines the state of the searched for item. Use any combination of the following masks to define the state of the searched for item:
For example, if you pass (VAL_SELECTED | VAL_MARKED) the function will only search among items that are selected as well as marked. Pass 0 to count items regardless of their state. |
||||||||||||||||||||||
| itemLabel | char [] | The label to search for among the tree items. | ||||||||||||||||||||||
| Output | ||||||||||||||||||||||||
| Name | Type | Description | ||||||||||||||||||||||
| item | int |
The index of the first item in the search range of the tree control that matches the specified label. –1 indicates that no item has the specified label. |
||||||||||||||||||||||
Return Value
| Name | Type | Description |
| status | int | Return value indicating whether the function was successful. A negative number indicates that an error occurred. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 7.0 and later
Example
Refer to userint\treesearch.cws for an example of using the GetTreeItemFromLabel function.