|
Purpose |
Manipulate a LISTBOX control in order to set/retrieve data. |
|
Syntax |
LISTBOX ADD hDlg,
id&, StrExpr
[TO datav&] |
|
hDlg |
|
|
id& |
The control identifier assigned with CONTROL ADD LISTBOX. |
|
item& |
Position of data in the LISTBOX. First string=1, second=2... |
|
NumExpr |
A
|
|
StrExpr |
A string expression passed as a parameter. |
|
txtv$ |
A
|
|
datav& |
A long integer variable to which result data is assigned. |
|
Remarks |
In each of the following samples and descriptions, the LISTBOX control which is the subject of the statement is identified by the handle of the dialog that owns the LISTBOX (hDlg), and the unique control identifier you gave it upon creation in CONTROL ADD LISTBOX. The value item& refers to the position of the string data item in the LISTBOX, and is always indexed to one. The first string is position 1, the second is position 2, and so forth. LISTBOX ADD hDlg, id&, StrExpr [TO datav&] The string value specified by StrExpr is added to the LISTBOX control. If the LISTBOX has the %LBS_SORT style, the new string is inserted in alphanumeric order; otherwise it is added to the end of the existing list. If the optional TO clause is included, the index position of the added string is assigned to the variable represented by datav&. The index is one for the first string, two for the second, etc. If the index is less than one, an error occurred and no string was added. LISTBOX DELETE hDlg, id&, item& The string at the position specified by item& is deleted from the LISTBOX. The parameter item& is indexed to one (1 for the first string, 2 for the second, and so on). LISTBOX FIND hDlg, id&, item&, StrExpr TO datav& Strings in the LISTBOX are searched to find the first string which begins with the data in StrExpr, regardless of any characters which follow. Comparisons are not case-sensitive. Strings are searched beginning with the string specified by item&, and ending with the last string in the LISTBOX. Searching does not wrap to the beginning of the list. The item number (item&) is indexed to 1 (1=first, 2=second, etc.). To search the entire LISTBOX starting with the first string, item& should be set to one (1). If a matching string is found, the index value of the match is assigned to the variable specified by datav&. If no match is found, the value zero (0) is assigned to it. LISTBOX FIND EXACT hDlg, id&, item&, StrExpr TO datav& Strings in the LISTBOX are searched to find the first string which exactly matches the data in StrExpr. Comparisons are not case-sensitive. Strings are searched beginning with the string specified by item&, and ending with the last string in the LISTBOX. Searching does not wrap to the beginning of the list. The item number (item&) is indexed to 1 (1=first, 2=second, etc.). To search the entire LISTBOX starting with the first string, item& should be set to one (1). If a matching string is found, the index value of the match is assigned to the variable specified by datav&. If no match is found, the value zero (0) is assigned to it. LISTBOX GET COUNT hDlg, id& TO datav& The number of items in the LISTBOX is retrieved, and assigned to the long integer variable specified by datav&. LISTBOX GET SELCOUNT hDlg, id& TO datav& The number of selected items in the LISTBOX is retrieved, and assigned to the long integer variable specified by datav&. LISTBOX GET SELECT hDlg, id& [,item&] TO datav& The LISTBOX is searched to find the first selected item. If the item& parameter is included, searching starts at that position to facilitate retrieving multiple selected items. If item& is omitted, the search starts at the first data item. The index number of the selected item is assigned to the variable designated by datav&. If no item is selected, the value zero (0) is assigned to it. LISTBOX GET STATE hDlg, id&, item& TO datav& A data item is checked to see if it is currently selected. The numeric value item& specifies which user value is to be checked, 1 for the first item, 2 for the second item, etc. If the item is selected, -1 (true) is assigned to the variable specified by datav&. Otherwise, 0 (false) is assigned to it. LISTBOX GET TEXT hDlg, id& [,item&] TO txtv$ Text is retrieved from the LISTBOX and assigned to the string variable specified by txtv$. If the numeric expression item& is included, it determines which text string is returned, 1 for the first item, 2 for the second item, etc. The parameter item& may be omitted, or contain the value zero (0). In the case of a single-selection listbox, the current selected text (if any) is retrieved and assigned to txtv$. With a multiple-selection listbox (%LBS_MULTIPLESEL or %LBS_EXTENDEDSEL style), the text of the first (base) selected item is assigned to txtv$. To retrieve additional selected text items from a multiple-selection listbox, use LISTBOX GET SELECT to retrieve selected item numbers. Then apply the item numbers with LISTBOX GET TEXT to retrieve the string data. LISTBOX GET USER hDlg, id&, item& TO datav& Each item in a LISTBOX may have a long integer user value associated with it at the discretion of the programmer. This user value is retrieved with LISTBOX GET USER. The numeric value item& specifies which user value is requested, 1 for the first item, 2 for the second item, etc. The returned user value is assigned to the long integer variable specified by datav&. LISTBOX user values are assigned with the LISTBOX SET USER statement. In addition to these LISTBOX user values, every DDT control offers an additional eight user values which can be accessed with CONTROL GET USER and CONTROL SET USER. LISTBOX INSERT hDlg, id&, item&, StrExpr [TO datav&] The text for a new data item, specified by StrExpr, is inserted at the location given by item&. The value of item& = 1 for the first item, 2 for the second item, etc. The list of data items is not re-sorted, even if the LISTBOX was created with the style %LBS_SORT. If you wish to sort all of the items, use LISTBOX ADD instead. If the optional TO clause is included, the index position of the inserted string is assigned to the variable represented by datav&. The index is one for the first string, two for the second, etc. If the index is less than one, an error occurred and no string was inserted. LISTBOX RESET hDlg, id& Delete all contents of the specified LISTBOX. LISTBOX SELECT hDlg, id&, item& The string data item specified by item& is chosen as selected text for the LISTBOX control, and the selected text is scrolled into a visible position. The value of item& = 1 for the first item, 2 for the second item, etc. If the value of item& = 0 with a multiple selection listbox, then all string data items are selected. LISTBOX SELECT may be used with both single and multiple selection listboxes. LISTBOX SET TEXT hDlg, id&, item&, StrExpr The text for the data item specified by item& is replaced with the new text in StrExpr. The value of item& = 1 for the first item, 2 for the second item, etc. The list of data items is not re-sorted, even if the LISTBOX was created with the style %LBS_SORT. If you wish to sort the items, use LISTBOX DELETE followed by LISTBOX ADD instead. LISTBOX SET USER hDlg, id&, item&, NumExpr Each item in a LISTBOX may have a long integer user value associated with it at the discretion of the programmer. This user value is assigned with LISTBOX SET USER, and retrieved with LISTBOX GET USER. The numeric value item& specifies which user value is to be accessed, 1 for the first item, 2 for the second item, etc. The value specified by NumExpr is saved for later retrieval. In addition to these LISTBOX user values, every DDT control offers an additional eight user values which can be accessed with CONTROL GET USER and CONTROL SET USER. LISTBOX UNSELECT hDlg, id& [,item&] The string value specified by item& is set to an unselected state for the LISTBOX control. The value of item& = 1 for the first item, 2 for the second item, etc. If item& is missing, or has the value zero, all items are set to an unselected state. LISTBOX UNSELECT may be used with both single and multiple selection listboxes. |
|
Restrictions |
Under Windows 95/98/ME, a list box is limited to 32,767 items. In all versions of Windows, the actual string data contained by the list box is limited only by available memory. |
|
See also |
Dynamic Dialog Tools, CONTROL ADD LISTBOX, CONTROL SET COLOR, CONTROL SET FONT |