wxRuby Documentation Home

Wx::ControlWithItems

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.

Derived from

Control

Window

EvtHandler

Object

Methods

ControlWithItems#append

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.

Parameters

Return value

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).

ControlWithItems#clear

clear()

Removes all items from the control.

clear() also deletes the client data of the existing items if it is owned by the control.

ControlWithItems#delete

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.

Parameters

See also

clear

ControlWithItems#each

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)}'" 
end

ControlWithItems#find_string

Integer find_string(String string)

Finds an item whose label matches the given string.

Parameters

Return value

The zero-based position of the item, or NOT_FOUND if the string was not found.

ControlWithItems#get_count

Integer get_count()

Returns the number of items in the control.

See also

is_empty

ControlWithItems#get_item_data

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.

Parameters

See also

set_item_data

ControlWithItems#get_selection

Integer get_selection()

Returns the index of the selected item or NOT_FOUND if no item is selected.

Return value

The position of the current selection.

Remarks

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.

See also

set_selection, get_string_selection

ControlWithItems#get_string

String get_string(Integer n)

Returns the label of the item with the given index.

Parameters

Return value

The label of the item or an empty string if the position was invalid.

ControlWithItems#get_string_selection

String get_string_selection()

Returns the label of the selected item or an empty string if no item is selected.

See also

get_selection

ControlWithItems#insert

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.

Parameters

Return value

The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned.

ControlWithItems#is_empty

Boolean is_empty()

Returns true if the control is empty or false if it has some items.

See also

get_count

ControlWithItems#select

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.

ControlWithItems#set_item_data

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.

Parameters

ControlWithItems#set_selection

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.

Parameters

See also

set_string, set_string_selection

ControlWithItems#set_string

set_string(Integer n, String string)

Sets the label for the given item.

Parameters

ControlWithItems#set_string_selection

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.

Parameters

Return value

true if the specified string has been selected, false if it wasn’t found in the control.

See also

set_selection

[This page automatically generated from the Textile source at Wed Sep 09 02:21:04 +0100 2009]