class Iup::List
A List
control presents a list of options to the user. The list may be visible, or a hidden, drop-down list. Optionally, items may be editable.
Note that lists are indexed from 1.
Attributes¶ ↑
- autohide
-
If set, scrollbars are only shown if necessary, values 'yes' / 'no'.
- canfocus
-
If set, the control can gain focus, values 'yes' / 'no'.
- count
-
read-only returns the number of items in the list.
- dragdroplist
-
If yes, enables drag and drop between lists: 'yes' / 'no'.
- dropdown
-
'yes' / 'no', if set, only the selected item is visible.
- editbox
-
'yes' / 'no', if set adds an editable box to the list.
- expand
-
Allows list to fill available space in indicated direction. Values 'no' / 'horizontal' / 'vertical' / 'yes'.
- multiple
-
If set, allows selection of multiple items: values 'yes' / 'no'. Only available if editbox = dropdown = no.
- position
-
read-only returns position in pixels within client window as “x,y”.
- rastersize
-
Size of the list, in pixels, value as “widthxheight”.
- removeitem
-
n / 'all', removes item n or all items from the list.
- screenposition
-
read-only returns position in pixels on screen as “x,y”.
- showdragdrop
-
If set, enables internal drag/drop: values 'yes' / 'no'.
- showdropdown
-
write-only Shows the dropdown list, if dropdown=yes.
- sort
-
Forces items to be sorted alphabetically. Insert/append operations will ignore the index number.
- spacing
-
Space between items, value as a number.
- tip
-
Tooltip string.
- visiblecolumns
-
The minimum number of visible columns, defaults to 5.
- visiblelines
-
The minimum number of visible lines, when dropdown=no.
Attributes (with editbox set)¶ ↑
- append
-
write-only appends given string to end of text.
- caret
-
'col', in single-line mode, or 'lin,col' in multi-line mode.
- caretpos
-
Index of character of the insertion point.
- clipboard
-
'clear' / 'copy' / 'cut' / 'paste', write-only access the clipboard with the current selection.
- insert
-
write-only Places a given string at current caret position, overwriting any current selection.
- mask
-
Defines a mask to filter text input.
- nc
-
Maximum number of characters allowed for keyboard input (0 allows an indefinite number).
- padding
-
Margin in x and y directions, value as “mxn”.
- readonly
-
If set, prevents the user changing contents: values 'yes' / 'no'.
- scrollto
-
write-only '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.
- scrolltopos
-
write-only Scrolls to make character 'number' visible.
- selectedtext
-
Reads or overwrites the current selection. Does nothing if no text is selected.
- selection
-
Selects text as 'col1:col2' (single-line) / 'lin1,col1:lin2,col2' (multi-line) / 'all' / 'none'.
- selectionpos
-
Selects text between character positions: 'pos1:pos2' / 'all' / 'none'.
Public Class Methods
Creates an instance of the list. All options are set through the block.
# File lib/wrapped/list.rb, line 66 def initialize &block @handle = IupLib.IupList nil # run any provided block on instance, to set up further attributes self.instance_eval &block if block_given? end
Public Instance Methods
Action generated when the state of an item in the list is changed. action takes a 3-argument callback: text, item, state
# File lib/wrapped/list.rb, line 222 def action callback unless callback.arity == 3 raise ArgumentError, 'action callback must take 3 arguments: (text, item, state)' end cb = Proc.new do |ih, text, item, state| callback.call text, item, state end define_callback cb, 'ACTION', :sii_i end
Adds given item to end of list.
- text
-
required text label
- image
-
optional image reference / name.
# File lib/wrapped/list.rb, line 80 def appenditem text, image=nil IupLib.IupSetAttribute '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
Action generated when the caret/cursor position is changed. Valid only when EDITBOX=YES. caret_cb
takes a callback which accepts 3 arguments (line, column, position) of caret
# File lib/wrapped/list.rb, line 236 def caret_cb callback unless callback.arity == 3 raise ArgumentError, 'caret_cb callback must take 3 arguments: (line, column, position)' end cb = Proc.new do |ih, lin, col, pos| callback.call lin, col, pos end define_callback cb, 'CARET_CB', :iii_i end
Action generated when the user double click an item. Called only when DROPDOWN=NO. dblclick_cb
takes a callback which accepts 2 arguments (index, text)
# File lib/wrapped/list.rb, line 248 def dblclick_cb callback unless callback.arity == 2 raise ArgumentError, 'dblclick_cb callback must take 2 arguments: index, text' end cb = Proc.new do |ih, index, text| callback.call index, text end define_callback cb, 'DBLCLICK_CB', :is_i end
Action generated when an internal drag and drop is executed. Only active if SHOWDRAGDROP=YES. dragdrop_cb
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.
# File lib/wrapped/list.rb, line 265 def dragdrop_cb callback unless callback.arity == 4 raise ArgumentError, 'dragdrop_cb callback must take 4 arguments: (drag_id, drop_id, isshift, iscontrol)' end cb = Proc.new do |ih, drag_id, drop_id, isshift, iscontrol| callback.call drag_id.to_i, drop_id.to_i, (isshift != 0), (iscontrol != 0) end define_callback cb, 'DRAGDROP_CB', :iiii_i end
Action generated when the list of a dropdown is shown or hidden. Called only when DROPDOWN=YES. dropdown_cb
takes a 1-argument callback, shown is a boolean, true if dropdown visible. dropdown_cb
is only called if dropdown=yes
# File lib/wrapped/list.rb, line 278 def dropdown_cb callback unless callback.arity == 1 raise ArgumentError, 'dropdown_cb callback must take 1 argument, shown' end cb = Proc.new do |ih, state| callback.call (state == 1) end define_callback cb, 'DROPDOWN_CB', :i_i end
Action generated 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. edit_cb
takes a 2-argument callback, the character typed, and the new text value
# File lib/wrapped/list.rb, line 291 def edit_cb callback unless callback.arity == 2 raise ArgumentError, 'edit_cb callback must take 2 arguments: (character, new_value)' end cb = Proc.new do |ih, c, text| callback.call c, text end define_callback cb, 'EDIT_CB', :is_i end
insert item at given index
- index
-
index to add item (1-indexed)
- text
-
required text label
- image
-
optional image reference / name.
# File lib/wrapped/list.rb, line 113 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
If text / image are set, adds a new item to the list. Otherwise, retrieves item at the given index.
- index
-
index to item (1-indexed)
- text
-
optional text label
- image
-
optional image reference / name.
# File lib/wrapped/list.rb, line 135 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 image_name = IupLib.IupGetName(image.handle).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 text end end
Action generated when the mouse is moved. Callback 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.
# File lib/wrapped/list.rb, line 309 def motion_cb callback unless callback.arity == 3 raise ArgumentError, 'motion_cb callback must take 3 arguments: (x, y, state)' end cb = Proc.new do |ih, x, y, state| callback.call x, y, state end define_callback cb, 'MOTION_CB', :iis_i end
Action generated when the state of an item in the multiple selection list is changed. But it is called only when the interaction is over. callback called with two arrays:
-
indices of selected items
-
indices of deselected items
# File lib/wrapped/list.rb, line 324 def multiselect_cb callback unless callback.arity == 2 raise ArgumentError, 'multiselect_cb callback must take 2 arguments, the array of selected and array of deselected items' end cb = Proc.new do |ih, val_ptr| val = FFI::Pointer.new(val_ptr).read_string selected = [] deselected = [] val.split('').each_with_index do |item, index| selected << index+1 if item == '+' deselected << index+1 if item == '-' end callback.call selected, deselected end define_callback cb, 'MULTISELECT_CB', :s_i end
If val is:
- string
-
when editbox is set, sets/gets the text entered by user.
- nil or an 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 +/-
# File lib/wrapped/list.rb, line 186 def value val=nil if val.nil? item_str = IupLib.IupGetAttribute(@handle, 'VALUE').first if multiple == 'YES' result = [] item_str.split('').each_with_index do |item, index| result << index+1 if item == '+' end return result else return item_str end else if multiple == 'YES' result = "" count.to_i.times do |i| if val.include?(i+1) result << '+' else result << '-' end end IupLib.IupSetAttribute @handle, 'VALUE', result else IupLib.IupSetAttribute @handle, 'VALUE', val.to_s end end end
Called after the value was interactively changed by the user. Called when the selection is changed or when the text is edited.
# File lib/wrapped/list.rb, line 343 def valuechanged_cb callback unless callback.arity.zero? raise ArgumentError, 'valuechanged_cb callback must take 0 arguments' end cb = Proc.new do |ih| callback.call end define_callback cb, 'VALUECHANGED_CB', :plain end