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

new(&block) click to toggle source

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(callback) click to toggle source

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
appenditem(text, image=nil) click to toggle source

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
caret_cb(callback) click to toggle source

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
dblclick_cb(callback) click to toggle source

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
dragdrop_cb(callback) click to toggle source

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
dropdown_cb(callback) click to toggle source

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

edit_cb(callback) click to toggle source

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
insertitem(index, text, image=nil) click to toggle source

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
item(index, text=nil, image=nil) click to toggle source

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
motion_cb(callback) click to toggle source

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
multiselect_cb(callback) click to toggle source

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
value(val=nil) click to toggle source

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
valuechanged_cb(callback) click to toggle source

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