Finds the next item in a list.
To find the next item |
Use |
|---|---|
In a ListBox, DropDownListBox, PictureListBox, or DropDownPictureListBox |
|
In a ListView control based upon its label |
|
By relative position in a ListView control |
|
By relative position in a TreeView control |
Finds the next item in a ListBox that begins with the specified search text.
ListBox, DropDownListBox, PictureListBox, and DropDownPictureListBox controls
listboxname.FindItem ( text, index )
Argument |
Description |
|---|---|
listboxname |
The name of the ListBox control in which you want to find an item. |
text |
A string whose value is the starting text of the item you want to find. |
index |
The number of the item just before the first item to be searched. To search the whole list, specify 0. |
Integer. Returns the index of the first matching item. To match, the item must start with the specified text; however, the text in the item can be longer than the specified text. If no match is found or if an error occurs, FindItem returns -1. If any argument’s value is null, FindItem returns null.
When FindItem finds the matching item, it returns the index of the item but does not select (highlight) the item. To find and select the item, use the SelectItem function.
Assume the ListBox lb_actions contains the following list:
Index number |
Item text |
|---|---|
1 |
Open files |
2 |
Close files |
3 |
Copy files |
4 |
Delete files |
Then these statements start searching for Delete starting with item 2 (Close files). FindItem sets Index to 4:
integer Index
Index = lb_actions.FindItem("Delete", 1)
Searches for the next item whose label matches the specified search text.
ListView controls
listviewname.FindItem ( startindex, label, partial, wrap )
Argument |
Description |
|---|---|
listviewname |
The ListView control for which you want to search for items |
startindex |
The index number from which you want your search to begin |
label |
The string that is the target of the search |
partial |
If set to true, the search looks for a partial label match |
wrap |
If set to true, the search returns to the first index item after it has finished |
Integer. Returns the index of the item found if it succeeds and -1 if an error occurs.
The search starts from startindex + 1 by default. To search from the beginning, specify 0.
If partial is set to true, the search string matches any label that begins with the specified text. If partial is set to false, the search string must match the entire label.
If wrap is set to true, the search wraps around to the first index item after searching to the end. If wrap is set to false, the search stops at the last index item in the ListView.
FindItem does not select the item it finds. You must use the item’s selected property in conjunction with FindItem to select the resulting match.
This example takes the value from a SingleLineEdit control and passes it to FindItem:
listviewitem l_lvi
integer li_index
string ls_label
ls_label = sle_find.Text
IF ls_label = "" THEN
MessageBox("Error" , &
"Enter the name of a list item")
sle_find.SetFocus()
ELSE
li_index = lv_list.FindItem(0,ls_label, TRUE,TRUE)
END IF
IF li_index = -1 THEN
MessageBox("Error", "Item not found.")
ELSE
lv_list.GetItem (li_index, l_lvi )
l_lvi.HasFocus = TRUE
l_lvi.Selected = TRUE
lv_list.SetItem(li_index,l_lvi)
END IF
Search for the next item relative to a specific location in the ListView control.
ListView controls
listviewname.FindItem ( startindex, direction, focused, selected, cuthighlighted, drophighlighted )
Argument |
Description |
|---|---|
listviewname |
The ListView control for which you want to search for items. |
startindex |
The index number from which you want your search to begin. |
direction |
The direction in which to search. Values are:
|
focused |
If set to true, the search looks for the next ListView item that has focus. |
selected |
If set to true, the search looks for the next ListView item that is selected. |
cuthighlighted |
If set to true, the search looks for the next ListView item that is the target of a cut operation. |
drophighlighted |
If set to true, the search looks for next ListView item that is the target of a drag and drop operation. |
Integer. Returns the index of the item found if it succeeds and -1 if an error occurs.
The search starts from startindex + 1 by default. If you want to search from the beginning, specify 0.
FindItem does not select the item it finds. You must use the item’s selected property in conjunction with FindItem to select the resulting match.
If focused, selected, cuthighlighted, and drophighlighted are set to false, the search finds the next item in the ListView control.
This example uses FindItem to search from the selected ListView item:
listviewitem l_lvi
integer li_index li_startindex
li_startindex = lv_list.SelectedIndex()
li_index = lv_list.FindItem(li_startindex, &
DirectionDown!, FALSE, FALSE ,FALSE, FALSE)
IF li_index = -1 THEN
MessageBox("Error", "Item not found.")
ELSE
lv_list.GetItem (li_index, l_lvi)
l_lvi.HasFocus = TRUE
l_lvi.Selected = TRUE
lv_list.SetItem(li_index,l_lvi)
END IF
Find an item based on its position in a TreeView control.
TreeView controls
treeviewname.FindItem ( navigationcode, itemhandle )
Argument |
Description |
|---|---|
treeviewname |
The name of the TreeView control in which you want to find a specified item. |
navigationcode |
A value of the TreeNavigation enumerated datatype specifying the relationship between itemhandle and the item you want to find. See the table in Usage note for a list of valid values. |
itemhandle |
A long for the handle of an item related via navigationcode to the item for which you are searching. |
Long. Returns the item handle if it succeeds and -1 if an error occurs.
FindItem does not select the item it finds. You must use the item’s selected property in conjunction with FindItem to select the result of the FindItem search.
FindItem never finds a collapsed item, except when looking for ChildTreeItem!, which causes an item to expand. CurrentItem! is not changed until after the clicked event occurs. To return the correct handle for the current item when the user clicks it, create a custom event to return the handle and post it in the clicked event.
If navigationcode is RootTreeItem!, FirstVisibleTreeItem!, CurrentTreeItem!, or DropHighlightTreeItem!, set itemhandle to 0.
The following table shows valid values for the navigationcode argument.
Navigationcode value |
What FindItem finds |
|---|---|
RootTreeItem! |
The first item at level 1. Returns -1 if no items have been inserted into the control. |
NextTreeItem! |
The sibling after itemhandle. A sibling is an item at the same level with the same parent. Returns -1 if there are no more siblings. |
PreviousTreeItem! |
The sibling before itemhandle. Returns -1 if there are no more siblings. |
ParentTreeItem! |
The parent of itemhandle. Returns -1 if the item is at level 1. |
ChildTreeItem! |
The first child of itemhandle. If the item is collapsed, ChildtreeItem! causes the node to expand. Returns -1 if the item has no children or if the item is not populated yet. |
FirstVisibleTreeItem! |
The first item visible in the control, regardless of level. The position of the scrollbar determines the first visible item. |
NextVisibleTreeItem! |
The next expanded item after itemhandle, regardless of level. The NextVisible and PreviousVisible values allow you to walk through all the visible children and branches of an expanded node. Returns -1 if the item is the last expanded item in the control.To scroll to an item that is beyond the reach of the visible area of the control, use FindItem and then SelectItem. |
PreviousVisibleTreeItem! |
The next expanded item before itemhandle, regardless of level. Returns -1 if the item is the first root item. |
CurrentTreeItem! |
The selected item. Returns -1 if the control never had focus and nothing has been selected. |
DropHighlightTreeItem! |
The item whose DropHighlighted property was most recently set. Returns -1 if the property was never set or if it has been set back to false because of other activity in the control. |
To return the correct handle when the current item is clicked, place this code in a custom event that is posted in the item’s clicked event:
long ll_tvi
ll_tvi = tv_list.FindItem(CurrentTreeItem!, 0)
This example finds the first item on the first level of a TreeView control:
long ll_tvi
ll_tvi = tv_list.FindItem(RootTreeItem!, 0)
