| superclass(es) |
control |
| subclass(es) |
- |
| description |
The listBox class is a control in which a list of items can be placed, the
list of items can be sorted automatically and it is possible to select multiple items from
the list.
 |
| see also |
panel - comboBox
|
An instance of the listBox class can be used for
selecting one or more items from a list, if a listbox is created by the method createSorted/6 then the list is sorted alphabetically. In case
of a sorted list the position of an item cannot be determined. It is not possible to
select multiple items in the list of a listbox except when the listbox is created by the
method createMultiple/6.
Items can be added to a listbox control by the methods add/1
or add/2, a list of items can be added by the method addList/1. If only a single item can be selected this item can be
retrieved by firstSelectedString/1.
The listbox control can also be used to display the contents of a drive or
a folder, to add the names of drives call the method addDrives/1.
After the drives have been added to a listbox files can also be added, see the method addFiles/4.
With the callback onSelectionChange/2
it is possible to react to a new current item in the list. |
create( Parent, X, Y, W, H, Output )
| func |
Create a normal listbox control, the parent window is specified by Parent,
The position of the upperleft corner are specified by X and Y, the width and height of the
control are determined by W and H. |
| pre |
Parent must refer to a parent window, X, Y, W and H must contain integer
values. |
| post |
If the listbox control was successfully created Output is assigned true,
else it is assigned false. |
createSorted( Parent, X, Y, W, H, Output )
| func |
Create a listbox control that alphabetically sorts it's items, the
parent window is specified by Parent, The position of the upperleft corner are specified
by X and Y, the width and height of the control are determined by W and H. |
| pre |
Parent must refer to a parent window, X, Y, W and H must contain integer
values. |
| post |
If the sorting listbox control was successfully created Output is assigned
true, else it is assigned false. |
createMultiple( Parent, X, Y, W, H, Output )
| func |
Create a listbox control in which multiple items can be selected,
the parent window is specified by Parent, The position of the upperleft corner are
specified by X and Y, the width and height of the control are determined by W and H. |
| pre |
Parent must refer to a parent window, X, Y, W and H must contain integer
values. |
| post |
If the multiple selection listbox control was successfully created Output
is assigned true, else it is assigned false. |
multiple( Output )
| func |
Check if it is possible to select more than one item in the list of the
listbox. |
| pre |
TRUE. |
| post |
If the listbox is a multiple selection listbox then true is assigned to
Output, else Output is assigned false. |
sorted( Output )
| func |
Check if the listbox automatically sorts the items in the list. |
| pre |
TRUE. |
| post |
If the listbox is a sorting listbox then true is assigned to Output, else
Output is assigned false. |
ownerDrawVarHeight( Output )
| func |
Check if the listbox is an owner draw listbox that permits a different
height for each item. |
| pre |
TRUE. |
| post |
If the listbox is a sorting listbox then true is assigned to Output, else
Output is assigned false. |
itemHeight( Index, Output )
| func |
Get the height of an item in pixels, the index of the first item is 0. |
| pre |
Index must contain an integer value. |
| post |
The height of the item is assigned to the variable Output. |
 |
This method is useful when the listbox is an owner draw listbox with
variable height. |
putItemHeight( Index, Height )
| func |
Set the height of an item of the list in pixels, the index of the first
item is 0. |
| pre |
Index and Height must contain an integer value. The listbox must be an
owner draw listbox with variable height. |
| post |
The height of the item was changed if the listbox was an owner draw
listbox with variable height. |
itemRectangle( Index, rectangle(L, T, B, R) )
| func |
Get the rectangle that an item occupies. |
| pre |
Index contain an integer value. |
| post |
The bounding rectangle of the item was assigned to the structure
rectangle(L, T, B, R), if the item doesn't exist then rectangle(0, 0, 0, 0) was assigned. |
add( String )
| func |
Add an item to the listbox with the text that String refers to. |
| pre |
String must contain a string value. |
| post |
The new item with the value of String was inserted as last in the list of
items. If the listbox sorts it's items then the position of insertion is determined by the
value of String and the strings already present in the list. |
|
see also: add/3 |
add( String, Output )
| func |
Add an item to the listbox with the text that String refers to and get the
position of where the item was inserted. |
| pre |
String must contain a string value. |
| post |
The new item with the value of String was inserted as last in the list of
items. If the listbox sorts it's items then the position of insertion is determined by the
value of String and the strings already present in the list. The position where the item
was inserted is assigned to the variable Output. If there was an error inserting the
string then -1 is assigned to Output. |
|
see also: add/4 |
add( String, Id, ExtraText )
| func |
Add an item to the listbox with the String, Id and ExtraText values. The
values of the Id and ExtraText parameters are not visible to the user, they can be used by
the application for storing extra data per listbox item. |
| pre |
The parameters String and ExtraText must contain a string value. The
parameter Id must contain an integer. |
| post |
The new item with the value of String was inserted as last in the list of
items. If the listbox sorts it's items then the position of insertion is determined by the
value of String and the strings already present in the list. |
|
see also: give/5 |
add( String, Id, ExtraText, Output )
| func |
Add an item to the listbox with the String, Id and ExtraText values. The
values of the Id and ExtraText parameters are not visible to the user, they can be used by
the application for storing extra data per listbox item. The position of the new item in
the listbox is assigned, after insertion, to the parameter Output. |
| pre |
The parameters String and ExtraText must contain a string value. The
parameter Id must contain an integer. |
| post |
The new item with the value of String was inserted as last in the list of
items. If the listbox sorts it's items then the position of insertion is determined by the
value of String and the strings already present in the list. The position where the item
was inserted is assigned to the variable Output. If there was an error inserting the
string then -1 is assigned to Output. |
|
see also: give/5 |
addList( List )
| func |
Add a list of items to the listbox. The list is just a list of atoms or it
can also be a list of item/3 structures. For example: addList( [ 'one', 'two', 'three' ] )
or addList( [ item('one', 0, ''), item('two', 1, ''), item('three', 2, '') ] ). The list
of item/3 structures adds per entry also a hidden integer and string property, see also add/3. |
| pre |
TRUE |
| post |
Each item in the list is added to the list of items. If the listbox sorts
it's items then the position of insertion is determined by the value of the items in the
List and the strings already present in the list. |
insert( Pos, String )
| func |
Insert an item into the listbox with the text that String refers, the
position of inserting is determined by the value of Index. |
| pre |
String must contain a string value and Index must contain an integer
value. The index of the first item in the list is 0. |
| post |
The new item with the value of String was inserted at the specified
position, even if the listbox is a listbox that sorts it's items. |
insert( Pos, String, Id, ExtraText )
| func |
Insert an item into the listbox with the text that String refers, the
position of inserting is determined by the value of Index. The values of the Id and
ExtraText parameters are not visible to the user, they can be used by the application for
storing extra data per listbox item. |
| pre |
The parameters String and ExtraText must contain a string value and Index
must contain an integer value. The index of the first item in the list is 0. The parameter
Id must contain an integer. |
| post |
The new item with the value of String was inserted at the specified
position, even if the listbox is a listbox that sorts it's items. |
delete( Index )
| func |
Delete the item at the specified position. |
| pre |
Index must contain an integer value. The index of the first item in the
list is 0. |
| post |
The specified item was deleted. |
deleteText( String, Result )
| func |
Delete the item with the same text as the value of the parameter String. |
| pre |
String must contain a string value. |
| post |
If an item with the same text was found and deleted then the parameter
Result was unified with the value true, else if no item was deleted the Result parameter
was unified with false. |
putProperties( Pos, Id, ExtraText )
| func |
Change the extra properties of a listbox item. The values of the Id and
ExtraText parameters are not visible to the user, they can be used by the application for
storing extra data per listbox item. The position the item is determined by the value of
the parameter Pos. |
| pre |
The parameters Pos and Id must contain an integer. The parameter ExtraText
must contain a string value. |
| post |
The properties of the item at position Pos were changed. |
|
see also: give/5 |
clear
| func |
Clear the items from the list of the listbox. |
| pre |
TRUE. |
| post |
The item list of the control is empty. |
find( String, Output )
| func |
Find the index of the item with the same text as the variable String
contains. |
| pre |
String must contain a string value. |
| post |
If an item with the same text was found then the index of that item is
assigned to Output, if no item was found with the same string -1 is assigned to Output. |
|
The search for the string is case insensitive. |
findAndSelect( String, Output )
| func |
Find an item with the same text and select the item. This method does not
work for multiple selection list boxes! |
| pre |
String must contain a string value. |
| post |
If an item with the same text was found then the value true is assigned to
Output, else false is assigned to Output. |
|
The search for the string is case insensitive. |
findAndSelectId( Id, Output )
| func |
Find the first item with the same identification value associated with it
as the parameter Id, the first item with the same value is selected. |
| pre |
Id must contain an integer value. |
| post |
If an item with the same identification value was found then the value
true was unified with Output, else was false unified with Output. |
findAndSelectExtraText( String, Output )
| func |
Find an item with the same extra text property as the value of the
parameter String, the first item with the same extra string is selected. |
| pre |
String must contain a string value. |
| post |
If an item with the same extra text was found then the value true is
assigned to Output, else false is assigned to Output. |
length( Index, Output )
| func |
Determine the number of characters that an item has. |
| pre |
Index must contain an integer value. |
| post |
If the item existed then the number of characters was assigned to Output,
else if the item didn't exist -1 is assigned to Output. |
give( Index, String )
| func |
Get the string of the item at the position that the variable Index
contains. The index of the first item is 0. |
| pre |
Index must contain an integer value. |
| post |
If the item existed then the contents of the item was assigned to Output,
else if the item didn't exist no value is assigned to Output. |
give( Index, String, HasProperties, OutputId, OutputString )
| func |
Get the string of the item at the position that the variable Index
contains. The index of the first item is 0. The possible extra properties of an item are
also returned. |
| pre |
Index must contain an integer value. |
| post |
If the item existed then the contents of the item was assigned to Output,
else if the item didn't exist no value is assigned to Output. If the listbox item has
extra properties associated with it then is true unified with the parameter HasProperties,
else false. The values of the possible extra properties are unified with the parameters
OutputId and OutputString. |
|
see also: add/3, add/4 and firstSelectedString/4. |
firstSelectedString( Output )
| func |
Get the string of the first selected item. |
| pre |
TRUE. |
| post |
If the an item was selected then the contents of the first selected item
was assigned to Output. If there was no selected item then no value was assigned to
Output. |
firstSelectedString( Output, HasProperties,
OutputId, OutputExtraText )
| func |
Get the string and extra properties of the first selected item. |
| pre |
TRUE. |
| post |
If the an item was selected then the contents of the first selected item
was assigned to Output. If there was no selected item then no value was assigned to
Output. If there was a selected item with extra properties then the parameter
HasProperties was unified with the value true, else with false. The values of the extra
properties were unified with the parameters OutputId and OutputExtraText. |
selected( Index, Output )
| func |
Determine if a specific item was selected or not. |
| pre |
Index must contain an integer value. |
| post |
If the specified item existed then Output is assigned true if the item was
selected else false was assigned. If the item didn't exist then also false was assigned to
Output. |
numSelected( Output )
| func |
Determine the number of selected items. |
| pre |
TRUE. |
| post |
The number of selected items is assigned to Output. |
selectRange( StartIndex, EndIndex )
| func |
Select an entire range of items. |
| pre |
StartIndex and EndIndex must contain an integer values. |
| post |
For a multiple selection listbox the entire range was selected, items
already selected stay selected. In case of a listbox that cannot select more than 1 item,
the first item of the specified range was selected. |
select( Index )
| func |
Select a single item, selecting an item that was already selected does not
remove the selection. The index of the first item is 0. |
| pre |
Index must contain an integer value. |
| post |
For a multiple selection listbox the item was selected and items already
selected stay selected. In case of a listbox that cannot select more than 1 item, the
specified item was selected. |
contains( Output )
| func |
Determine the number of items in the list of the control. |
| pre |
TRUE. |
| post |
The number of items in the listbox was assigned to the variable Output. |
current( Output )
| func |
Determine the index of the current item in the listbox. |
| pre |
TRUE. |
| post |
The index of the current item was assigned to the variable Output. |
addDrives( Filter )
| func |
Have the listbox insert the names of the drives used by the system. A
filter can be specified, to have all drives inserted use the filter '*'
(including the single quotes). |
| pre |
Filter must contain a string value. |
| post |
The names of the drives were inserted into the list. |
addFiles( Filter, Files, HiddenFiles, Folders )
| func |
Have the listbox insert the names of the selected files. A filter can be
specified to select a subset of all the files, the filter can contain a relative or an
absolute path to select files other than from the current working directory. To select
normal files assign true to the variable Files, to select hidden files assign true to
HiddenFiles and to also select folders assign true to Folders. |
| pre |
Filter must contain a string value. Files, HiddenFiles and Folders must
contain a boolean value. |
| post |
The names of the drives were inserted into the list. |
onSelectionChange( Sender, ItemText )
| func |
Through this callback it is possible to respond to a new selection in the
list of items. |
| pre |
The variable Sender refers to the listbox control sending the event, the
second parameter is the text of the new selected item. |
| post |
TRUE |
onSelectionChangeEx( Sender, ItemText,
HasProperties, Id, ExtraText )
| func |
Through this callback it is also possible to respond to a new selection in
the list of items, the difference between this event and onSelectionChange/2 is that the
extra (hidden) properties of the new selected item are also parameters in the event
structure.
If the new selection in the list has no extra properties then is the value of the
parameter HasProperties 'false' and are Id and ExtraText empty variables. |
| pre |
The variable Sender refers to the listbox control sending the event, the
second parameter is the text of the new selected item. The parameter HasProperties is a
boolean parameter that indicates if the new selection does or does not have any extra
properties associated with it. If the value of HasProperties is true then does the
parameter Id contain the extra integer and the parameter ExtraText the extra text of the
new selected item. |
| post |
TRUE |