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.
Integer append(String item)Adds the item to the end of the list box.
Integer append(String item, Object clientData)Integer append(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.
append(ArrayString strings)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).
clear()Removes all items from the control.
clear() also deletes the client data of the existing items if it is owned by the control.
delete(Integer n)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.
each() { | index | ... }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
choice.each do | i |
puts "The label of item #{i} is '#{choice.string(i)}'"
endInteger find_string(String string)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.
Integer get_count()Returns the number of items in the control.
Object get_item_data(Integer n)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.
Integer get_selection()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
String get_string(Integer n)Returns the label of the item with the given index.
The label of the item or an empty string if the position was invalid.
String get_string_selection()Returns the label of the selected item or an empty string if no item is selected.
Integer insert(String item, Integer pos)Inserts the item into the list before pos.
Not valid for LB_SORT or CB_SORT styles, use Append instead.
Integer insert(String item, Integer pos, Object clientData)Integer insert(String item, Integer pos, ClientData clientData)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.
Boolean is_empty()Returns true if the control is empty or false if it has some items.
select(Integer n)This is the same as set_selection and exists only because it is slightly more natural for controls which support multiple selection.
set_item_data(Integer n, Object data)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.
set_selection(Integer n)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
set_string(Integer n, String string)Sets the label for the given item.
Boolean set_string_selection(String string)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 Thu May 01 00:50:34 +0100 2008]