h1(#wxcontrolwithitems). Wx::ControlWithItems This class is a common base class for several wxRuby controls which contain several items, such as "ListBox":listbox.html and "CheckListBox":checklistbox.html derived from it, "Choice":choice.html and "ComboBox":combobox.html. 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":#ControlWithItems_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. h2. Derived from "Control":control.html "Window":window.html "EvtHandler":evthandler.html "Object":object.html
h2. Methods * "ControlWithItems#append":#ControlWithItems_append * "ControlWithItems#clear":#ControlWithItems_clear * "ControlWithItems#delete":#ControlWithItems_delete * "ControlWithItems#each":#ControlWithItems_each * "ControlWithItems#find_string":#ControlWithItems_findstring * "ControlWithItems#get_count":#ControlWithItems_getcount * "ControlWithItems#get_item_data":#ControlWithItems_getitemdata * "ControlWithItems#get_selection":#ControlWithItems_getselection * "ControlWithItems#get_string":#ControlWithItems_getstring * "ControlWithItems#get_string_selection":#ControlWithItems_getstringselection * "ControlWithItems#insert":#ControlWithItems_insert * "ControlWithItems#is_empty":#ControlWithItems_isempty * "ControlWithItems#number":#ControlWithItems_number * "ControlWithItems#select":#ControlWithItems_select * "ControlWithItems#set_item_data":#ControlWithItems_setitemdata * "ControlWithItems#set_selection":#ControlWithItems_setselection * "ControlWithItems#set_string":#ControlWithItems_setstring * "ControlWithItems#set_string_selection":#ControlWithItems_setstringselection
h3(#ControlWithItems_append). ControlWithItems#append Integer *append*(%(arg-type)String% item) Adds the item to the end of the list box. Integer *append*(%(arg-type)String% item, %(arg-type)Object% clientData) Integer *append*(%(arg-type)String% item, %(arg-type)"ClientData":clientdata.html% 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":arraystring.html% 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. h4. Parameters * _item_ String to add. * _clientData_ Client data to associate with the item. h4. 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). h3(#ControlWithItems_clear). 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. h3(#ControlWithItems_delete). 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. h4. Parameters * _n_ The zero-based item index. h4. See also "clear":controlwithitems.html#ControlWithItems_clear h3(#ControlWithItems_each). 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 h3(#ControlWithItems_findstring). ControlWithItems#find_string Integer *find_string*(%(arg-type)String% string) Finds an item whose label matches the given string. h4. Parameters * _string_ String to find. h4. Return value The zero-based position of the item, or @NOT_FOUND@ if the string was not found. h3(#ControlWithItems_getcount). ControlWithItems#get_count Integer *get_count*() Returns the number of items in the control. h4. See also "is_empty":#ControlWithItems_isempty h3(#ControlWithItems_getitemdata). 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":treectrl.html and "ListCtrl":listctrl.html which offer a similar feature. h4. Parameters * _n_ The zero-based position of the item. h4. See also "set_item_data":#ControlWithItems_setitemdata h3(#ControlWithItems_getselection). ControlWithItems#get_selection Integer *get_selection*() Returns the index of the selected item or @NOT_FOUND@ if no item is selected. h4. Return value The position of the current selection. h4. Remarks This method can be used with single selection list boxes only, you should use "ListBox#get_selections":listbox.html#ListBox_getselections for the list boxes with @LB_MULTIPLE@ style. h4. See also "set_selection":#ControlWithItems_setselection, "get_string_selection":#ControlWithItems_getstringselection h3(#ControlWithItems_getstring). ControlWithItems#get_string String *get_string*(%(arg-type)Integer% n) Returns the label of the item with the given index. h4. Parameters * _n_ The zero-based index. h4. Return value The label of the item or an empty string if the position was invalid. h3(#ControlWithItems_getstringselection). ControlWithItems#get_string_selection String *get_string_selection*() Returns the label of the selected item or an empty string if no item is selected. h4. See also "get_selection":#ControlWithItems_getselection h3(#ControlWithItems_insert). ControlWithItems#insert Integer *insert*(%(arg-type)String% item, %(arg-type)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, %(arg-type)Integer% pos, %(arg-type)Object% clientData) Integer *insert*(%(arg-type)String% item, %(arg-type)Integer% pos, %(arg-type)"ClientData":clientdata.html% 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. h4. Parameters * _item_ String to add. * _pos_ Position to insert item before, zero based. * _clientData_ Client data to associate with the item. h4. Return value The return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned. h3(#ControlWithItems_isempty). ControlWithItems#is_empty Boolean *is_empty*() Returns @true@ if the control is empty or @false@ if it has some items. h4. See also "get_count":#ControlWithItems_getcount h3(#ControlWithItems_select). ControlWithItems#select *select*(%(arg-type)Integer% n) This is the same as "set_selection":#ControlWithItems_setselection and exists only because it is slightly more natural for controls which support multiple selection. h3(#ControlWithItems_setitemdata). ControlWithItems#set_item_data *set_item_data*(%(arg-type)Integer% n, %(arg-type)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":#ControlWithItems_getitemdata 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":treectrl.html and "ListCtrl":listctrl.html which offer a similar feature. h4. Parameters * _n_ The zero-based item index. * _data_ The client data to associate with the item. h3(#ControlWithItems_setselection). 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. h4. Parameters * _n_ The string position to select, starting from zero. h4. See also "set_string":#ControlWithItems_setstring, "set_string_selection":#ControlWithItems_setstringselection h3(#ControlWithItems_setstring). ControlWithItems#set_string *set_string*(%(arg-type)Integer% n, %(arg-type)String% string) Sets the label for the given item. h4. Parameters * _n_ The zero-based item index. * _string_ The label to set. h3(#ControlWithItems_setstringselection). 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. h4. Parameters * _string_ The string to select. h4. Return value @true@ if the specified string has been selected, @false@ if it wasn't found in the control. h4. See also "set_selection":#ControlWithItems_setselection