This class is a common base class for several wxRuby controls which
contain several items, such as ListBox and
CheckListBox derived from it, Choice
and ComboBox.
It defines the methods for accessing the controls items and although
each of the derived classes implements them differently, they still all
conform to the same interface. In particular, all these classes include
an each method and include Ruby’s Enumerable
module. Hence, methods such as collect, select and find are available.
The items in a ControlWithItems have (non empty) string labels and,
optionally, item data associated with them. Any ruby object may be set
as item data for an item with a control, allowing linking of core ruby
program objects with GUI code.
Adds the item to the end of the list box.
Integer append(%(arg-type)String% item, Object clientData) Integer append(%(arg-type)String% item, ClientData clientData)Adds the item to the end of the list box, associating the given, typed or
untyped, client data pointer with the item.
Appends several items at once to the control. Notice that calling this method
may be much faster than appending the items one by one if you need to add a lot
of items.
When appending a single item, the return value is the index of the newly added
item which may be different from the last one if the control is sorted (e.g.
has LB_SORT
or CB_SORT
style).
Removes all items from the control.
clear() also deletes the client data of the existing items if it is owned
by the control.
Deletes an item from the control. The client data associated with the item
will be also deleted if it is owned by the control.
Note that it is an error (signalled by an assert failure in debug builds) to
remove an item with the index negative or greater or equal than the number of
items in the control.
Can be used to iterate over all the items contained within the
control. Given a block, it will pass the integer index of each contained
item into that block. For example
Finds an item whose label matches the given string.
The zero-based position of the item, or NOT_FOUND
if the string was
not found.
Returns the number of items in the control.
Returns the ruby object previously set as data for the given item in the
control. If no object has been set as data, then nil
is returned.
Note that in WxWidgets C++, this method is called GetClientData;
therefore get_client_data is an alias in WxRuby for this method. THe
name get_item_data is preferred for clarity and consistency with the
other classes such as TreeCtrl and
ListCtrl which offer a similar feature.
Returns the index of the selected item or NOT_FOUND
if no item is
selected.
The position of the current selection.
This method can be used with single selection list boxes only, you should use
ListBox#get_selections for the list boxes
with LB_MULTIPLE
style.
set_selection, get_string_selection
Returns the label of the item with the given index.
The label of the item or an empty string if the position was invalid.
Returns the label of the selected item or an empty string if no item is
selected.
Inserts the item into the list before pos.
Not valid for LB_SORT
or CB_SORT
styles, use Append instead.
Inserts the item into the list before pos, associating the given, typed or
untyped, client data pointer with the item.
Not valid for LB_SORT
or CB_SORT
styles, use Append instead.
The return value is the index of the newly inserted item. If the
insertion failed for some reason, -1 is returned.
Returns true
if the control is empty or false
if it has some items.
This is the same as set_selection and
exists only because it is slightly more natural for controls which support
multiple selection.
Associates the ruby object with the given item in the control. This
useful feature enables the linking of program data (for example, objects
representing a database record) with the GUI, so that on subsequent
interaction with the control, GUI code can use
get_item_data to determine which program
data object is being interacted with. Any ruby object may be set as item
data, though it may be unwise to use volatile objects such as sockets or
files as item data.
Note that in WxWidgets C++, this method is called SetClientData;
therefore set_client_data is an alias in WxRuby for this method. The
name set_item_data is preferred for clarity and consistency with the
other classes such as TreeCtrl and
ListCtrl which offer a similar feature.
Sets the selection to the given item n or removes the selection entirely
if n == -1.
Note that this does not cause any command events to be emitted nor does it
deselect any other items in the controls which support multiple selections.
set_string, set_string_selection
Sets the label for the given item.
Selects the item with the specified string in the control. This doesn’t cause
any command events being emitted.
true
if the specified string has been selected, false
if it wasn’t
found in the control.
[This page automatically generated from the Textile source at 2023-06-09 00:45:32 +0000]