class Iup::List
A dynamic control presenting a list of options to the user. The list may be visible, or a hidden, drop-down list. Optionally, items may be editable.
Example
(1) Simple list, responding to double-click selection:
Iup::List.new do |l| l.item(1, "Java") l.item(2, "Ruby") l.item(3, "Scheme") l.spacing = 4 l.size = "80x100" l.dblclick_cb = ->(index, text) { puts "DBL CLICK ON #{index} with #{text}" Iup::DEFAULT } end
(2) Dropdown list, responding to changes in value:
Iup::List.new do |l| l.item(1, "Java") l.item(2, "Ruby") l.item(3, "Scheme") l.spacing = 4 l.dropdown = 'yes' l.valuechanged_cb = ->{ puts "New value index is #{l.value}, text is #{l.item(l.value)}" Iup::DEFAULT } end
Note that the C implementation of Iup’s list is 1-indexed: this is preserved in the wrapped version, for consistency.
Attributes
(with editbox set) appends given string to end of list.
If set, scrollbars are only shown if necessary, values ‘yes’ / ‘no’.
If set, the control can gain focus, values ‘yes’ / ‘no’.
(with editbox set) ‘col’, in single-line mode, or ‘lin,col’ in multi-line mode.
(with editbox set) Index of character of the insertion point.
(with editbox set) ‘clear’ / ‘copy’ / ‘cut’ / ‘paste’. Access the clipboard with the current selection.
Returns the number of items in the list.
If yes, enables drag and drop between lists: ‘yes’ / ‘no’.
‘yes’ / ‘no’, if set, only the selected item is visible.
Enable or disable the drop of files: ‘no’ / ‘yes’. Automatically set to ‘yes’ if dropfiles_cb is defined when list is mapped.
‘yes’ / ‘no’, if set adds an editable box to the list.
Allows list to fill available space in indicated direction. Values ‘no’ / ‘horizontal’ / ‘vertical’ / ‘yes’.
(with editbox set) Places a given string at current caret position, overwriting any current selection.
(with editbox set) Defines a mask to filter text input. See pre-defined masks.
If set, allows selection of multiple items: values ‘yes’ / ‘no’. Only available if editbox = dropdown = no.
(with editbox set) Maximum number of characters allowed for keyboard input (0 allows an indefinite number).
(with editbox set) Margin in x and y directions, value as “mxn”.
returns position in pixels within client window as “x,y”.
Size of the list, in pixels, value as “widthxheight”.
(with editbox set) If set, prevents the user changing contents: values ‘yes’ / ‘no’.
returns position in pixels on screen as “x,y”.
When in multiline mode, enables a scrollbar. Values ‘vertical’ / ‘horizontal’ / ‘yes’ / ‘no’.
(with editbox set) ‘col’ Scrolls to make given column number visible, in single-line mode. ‘lin/col’ Scrolls to make line and column number visible, in multi-line mode.
(with editbox set) Scrolls to make character ‘number’ visible.
(with editbox set) Reads or overwrites the current selection. Does nothing if no text is selected.
(with editbox set) Selects text as ‘col1:col2’ (single-line) / ‘lin1,col1:lin2,col2’ (multi-line) / ‘all’ / ‘none’.
(with editbox set) Selects text between character positions: ‘pos1:pos2’ / ‘all’ / ‘none’.
If set, enables internal drag/drop: values ‘yes’ / ‘no’.
Shows the dropdown list, if dropdown=yes.
Forces items to be sorted alphabetically. Insert/append operations will ignore the index number.
Space between items, value as a number.
Tooltip string.
If val is:
-
string- when editbox is set, sets/gets the text entered by user. -
nil/ integer - when dropdown = ‘yes’ or multiple = ‘no’, sets/gets index of selected items.
When list is multiple, val is converted to/from array of indices from/to +/-
The minimum number of visible columns, defaults to 5.
The minimum number of visible lines, when dropdown=no.
Public Class Methods
Source
# File lib/wrapped/list.rb, line 71 def initialize @handle = IupLib.IupList(nil) # run any provided block on instance, to set up further attributes yield self if block_given? end
Creates a new instance. If a block is given, the new instance is yielded to it.
Public Instance Methods
Source
# File lib/wrapped/list.rb, line 88 def appenditem(text, image=nil) IupLib.IupSetAttribute(@handle, 'APPENDITEM', text) case image when NilClass ; when String IupLib.SetAttibute(@handle, "IMAGE#{count}", image) when ImageWidget image_name = IupLib.IupGetName(name).first if image_name.nil? or image_name.empty? image_name = SecureRandom.uuid image.assign_handle image_name end IupLib.IupSetAttribute(@handle, "IMAGE#{count}", image_name) end end
Adds given item to end of list.
-
text- required text label -
image- optional image reference / name.
Source
# File lib/wrapped/list.rb, line 174 def insertitem(index, text, image=nil) IupLib.IupSetAttribute @handle, "INSERTITEM#{index}", text case image when NilClass ; when String IupLib.IupSetAttibute @handle, "IMAGE#{index}", image when ImageWidget image_name = IupLib.IupGetName(name).first if image_name.nil? or image_name.empty? image_name = SecureRandom.uuid image.assign_handle image_name end IupLib.IupSetAttribute @handle, "IMAGE#{index}", image_name end end
Insert item at given index.
-
index- index to place item (1-indexed) -
text- required text label -
image- optional image reference / name.
Source
# File lib/wrapped/list.rb, line 200 def item(index, text=nil, image=nil) if text.nil? IupLib.IupGetAttribute(@handle, index.to_s).first else IupLib.IupSetAttribute(@handle, index.to_s, text) case image when NilClass ; when String IupLib.IupSetAttribute(@handle, "IMAGE#{index}", image) when ImageWidget IupLib.IupSetAttributeHandle(@handle, "IMAGE#{index}", image.handle) end text end end
Accesses given index position.
-
index- index of item (1-indexed) -
text- text label (nilto retrieve) -
image- optional image reference / name.
Source
# File lib/wrapped/list.rb, line 258 def removeitem item IupLib.IupSetAttribute(@handle, "REMOVEITEM", item.to_s) end
Removes given item from the list:
-
list- index of item to remove (1-indexed), or ‘all’, to remove all items.
Callbacks
Attributes
Callback called when the state of an item in the list is changed. Callback must respond to call and takes a 3-argument callback: (text, item, state)
-
text- text of the changed item -
item- index of changed item (1-indexed) -
state- 1 if selected; 0 if deselected
Callback called when the caret/cursor position is changed. Valid only when EDITBOX=YES. Callback must respond to call and takes a callback which accepts 3 arguments (line, column, position) of caret
-
line- line number (1-indexed) -
column- column number (1-indexed) -
position- character position (0-indexed)
Callback called when the user double click an item. Called only when DROPDOWN=NO. Callback must respond to call and takes a callback which accepts 2 arguments (index, text)
-
index- index of selected item (1-indexed) -
text- text of selected item
Callback called when an internal drag and drop is executed. Only active if SHOWDRAGDROP=YES. Callback must respond to call and takes a callback which accepts 4 arguments (drag_id, drop_id, isshift, iscontrol)
-
drag_id- is an integer index of dragged item -
drop_id- is an integer index of drop location -
isshift- boolean flag for if shift key held -
iscontrol- boolean flag for if control key held
Callback should return Iup::CONTINUE for item to be moved/copied.
Callback called when the list of a dropdown is shown or hidden. Called only when DROPDOWN=YES. Callback must respond to call and takes a 1-argument callback: (state)
-
state- a boolean, true/false if dropdown visible/hidden.
Callback called when the text in the text box is manually changed by the user, but before its value is actually updated. Valid only when EDITBOX=YES. Callback must respond to call and takes a 2-argument callback: (character, new_value)
-
character- the character typed -
new_value- the new text value
Callback called when the mouse is moved. Callback must respond to call and takes 3 arguments: (x, y, state)
-
x- x position of mouse -
y- y position of mouse -
state- status of mouse buttons and certain keyboard keys at the moment the event was generated.
Callback called when the state of an item in the multiple selection list is changed. But it is called only when the interaction is over. Callback must respond to call and is called with two arrays: (selected, deselected)
-
selected- indices of selected items -
deselected- indices of deselected items
Called after the value was interactively changed by the user. Called when the selection is changed or when the text is edited. Callback must respond to call and takes no arguments.