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(%(arg-type)String% item)

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.

append(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)String% item, Integer pos, Object clientData) Integer insert(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)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(%(arg-type)Integer% n, String string)

Sets the label for the given item.

Parameters

ControlWithItems#set_string_selection

Boolean set_string_selection(%(arg-type)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 2023-06-09 00:45:32 +0000]