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
- ControlWithItems#clear
- ControlWithItems#delete
- ControlWithItems#each
- ControlWithItems#find_string
- ControlWithItems#get_count
- ControlWithItems#get_item_data
- ControlWithItems#get_selection
- ControlWithItems#get_string
- ControlWithItems#get_string_selection
- ControlWithItems#insert
- ControlWithItems#is_empty
- ControlWithItems#number
- ControlWithItems#select
- ControlWithItems#set_item_data
- ControlWithItems#set_selection
- ControlWithItems#set_string
- ControlWithItems#set_string_selection

### 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

- item String to add.
- clientData Client data to associate with the item.

#### 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

- n The zero-based item index.

#### 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

- string String to find.

#### 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

- n The zero-based position of the item.

#### 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

- n The zero-based index.

#### 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

- item String to add.
- pos Position to insert item before, zero based.
- clientData Client data to associate with the item.

#### 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

- n The zero-based item index.
- data The client data to associate with the item.

### 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

- n The string position to select, starting from zero.

#### 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

- n The zero-based item index.
- string The label to set.

### 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

- string The string to select.

#### 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]