Class: Iup::List

Inherits:
Widget show all
Includes:
ButtonCallback, DragDropAttributes, InternalDragDropAttributes
Defined in:
lib/wrapped/list.rb

Overview

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’.

Instance Attribute Summary

Attributes inherited from Widget

#handle

Instance Method Summary collapse

Methods included from ButtonCallback

#button_cb

Methods included from AttributeBuilders

#define_attribute, #define_id_attribute, #define_id_readonly, #define_id_writeonly, #define_property_attribute, #define_property_writeonly, #define_readonly, #define_writeonly

Methods included from DragDropAttributes

#dragbegin_cb, #dragdata_cb, #dragdatasize_cb, #dragend_cb, #dropdata_cb, #dropmotion_cb

Methods inherited from Widget

#assign_handle, #enterwindow_cb, #getfocus_cb, #help_cb, #k_any, #killfocus_cb, #leavewindow_cb, #map_cb, #open_controls, #unmap_cb

Methods included from CallbackSetter

#define_callback

Constructor Details

#initialize(&block) ⇒ List

Creates an instance of the list. All options are set through the block.



66
67
68
69
70
71
 
# 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

Instance Method Details

#action(callback) ⇒ Object

Action generated when the state of an item in the list is changed. action takes a 3-argument callback: text, item, state



222
223
224
225
226
227
228
229
230
 
# 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) ⇒ Object

Adds given item to end of list.

text

required text label

image

optional image reference / name.



80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# 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) ⇒ Object

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



236
237
238
239
240
241
242
243
244
 
# 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) ⇒ Object

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)



248
249
250
251
252
253
254
255
256
 
# 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) ⇒ Object

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.



265
266
267
268
269
270
271
272
273
 
# 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) ⇒ Object

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



278
279
280
281
282
283
284
285
286
 
# 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

#edit_cb(callback) ⇒ Object

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



291
292
293
294
295
296
297
298
299
 
# 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) ⇒ Object

insert item at given index

index

index to add item (1-indexed)

text

required text label

image

optional image reference / name.



113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
 
# 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) ⇒ Object

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.



135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# 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) ⇒ Object

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.

– TODO: include functions, as in button_cb



309
310
311
312
313
314
315
316
317
 
# 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) ⇒ Object

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



324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
 
# 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) ⇒ Object

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 +/-



186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
 
# 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) ⇒ Object

Called after the value was interactively changed by the user. Called when the selection is changed or when the text is edited.



343
344
345
346
347
348
349
350
351
 
# 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