iup-ffi 0.13.0-x86_64-linux

data/lib/wrapped/list.rb

@@ -0,0 +1,567 @@
+module Iup
+
+  # Convenience function to show a modal dialog to select an 
+  # item from a list.
+  #
+  # * +title+ - title for dialog
+  # * +items+ - list of items (strings) to display
+  #
+  # Returns selected item, or +nil+ if cancel clicked.
+  #
+  #   selection = Iup.listdialog('select one', ['C', 'Java', 'Ruby', 'Scheme'])
+  #   puts "Return #{selection}"
+  #
+  # Also see: +List+
+  def self.listdialog(title, items)
+    strptrs = []
+    strptrs << nil
+ 
+    items_ptr = FFI::MemoryPointer.new(:pointer, items.length)
+    items.each_with_index do |item, i|
+      items_ptr[i].put_pointer(0, FFI::MemoryPointer.from_string(item))
+    end
+
+    code = IupLib.IupListDialog(1, title, items.length, items_ptr, 1, 1, 10, nil)
+
+    return (code == -1 ? nil : items[code])
+  end
+
+  # 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.
+  #
+  class List < Iup::Widget
+    include DragDropAttributes
+
+    # Creates a new instance.
+    # If a block is given, the new instance is yielded to it.
+    def initialize 
+      @handle = IupLib.IupList(nil)
+
+      # run any provided block on instance, to set up further attributes
+      yield self if block_given?
+    end
+
+    # -- attributes
+
+    ##
+    # :attr_writer: append
+    # (with editbox set) appends given string to end of list.
+    define_writer :append
+
+    # Adds given item to end of list.
+    # * +text+ - required text label
+    # * +image+ - optional image reference / name.
+    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
+
+    ##
+    # :attr: autohide
+    # If set, scrollbars are only shown if necessary, values 'yes' / 'no'.
+    define_attribute :autohide
+
+    ##
+    # :attr: canfocus
+    # If set, the control can gain focus, values 'yes' / 'no'.
+    define_attribute :canfocus
+
+    ##
+    # :attr: caret
+    # (with editbox set) 'col', in single-line mode, or 'lin,col' in multi-line mode.
+    define_attribute :caret
+
+    ##
+    # :attr: caretpos
+    # (with editbox set) Index of character of the insertion point.
+    define_attribute :caretpos
+
+    ##
+    # :attr_writer: clipboard
+    # (with editbox set) 'clear' / 'copy' / 'cut' / 'paste'.
+    # Access the clipboard with the current selection.
+    define_writer :clipboard
+
+    ##
+    # :attr_reader: count
+    # Returns the number of items in the list.
+    define_reader :count
+
+    ##
+    # :attr: dragdroplist
+    # If yes, enables drag and drop between lists: 'yes' / 'no'.
+    define_attribute :dragdroplist
+
+    ##
+    # :attr: dropfilestarget
+    # Enable or disable the drop of files: 'no' / 'yes'.
+    # Automatically set to 'yes' if +dropfiles_cb+ is defined when list is
+    # mapped.
+    define_attribute :dropfilestarget
+
+    ##
+    # :attr: dropdown
+    # 'yes' / 'no', if set, only the selected item is visible.
+    define_attribute :dropdown
+
+    ##
+    # :attr: editbox
+    # 'yes' / 'no', if set adds an editable box to the list.
+    define_attribute :editbox
+
+    ##
+    # :attr: expand
+    # Allows list to fill available space in indicated direction.
+    # Values 'no' / 'horizontal' / 'vertical' / 'yes'.
+    define_attribute :expand
+
+    ##
+    # :attr_writer: insert
+    # (with editbox set) Places a given string at current caret position, 
+    # overwriting any current selection.
+    define_writer :insert
+
+    # Insert item at given index.
+    # * +index+ - index to place item (1-indexed)
+    # * +text+ - required text label
+    # * +image+ - optional image reference / name.
+    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
+
+    # :call-seq:
+    #   list.item(index)  # retrieves item 
+    #   list.item(index, text) # sets text 
+    #   list.item(index, text, image) # sets text and image 
+    #
+    # Accesses given index position.
+    # * +index+ - index of item (1-indexed)
+    # * +text+ - text label (+nil+ to retrieve)
+    # * +image+ - optional image reference / name.
+    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
+
+    ##
+    # :attr: mask
+    # (with editbox set) Defines a mask to filter text input.
+    # See {pre-defined masks}[../Iup.html#Masks].
+    define_attribute :mask
+
+    ##
+    # :attr: multiple
+    # If set, allows selection of multiple items: values 'yes' / 'no'.
+    # Only available if editbox = dropdown = no.
+    define_attribute :multiple
+
+    ##
+    # :attr: nc
+    # (with editbox set) Maximum number of characters allowed for keyboard
+    # input (0 allows an indefinite number).
+    define_attribute :nc
+
+    ##
+    # :attr: padding
+    # (with editbox set) Margin in x and y directions, value as "mxn".
+    define_attribute :padding
+
+    ##
+    # :attr_reader: position
+    # returns position in pixels within client window as "x,y".
+    define_reader :position
+
+    ##
+    # :attr: rastersize
+    # Size of the list, in pixels, value as "widthxheight".
+    define_attribute :rastersize
+
+    ##
+    # :attr: readonly
+    # (with editbox set) If set, prevents the user changing contents: values
+    # 'yes' / 'no'.
+    define_attribute :readonly
+
+    # Removes given item from the list:
+    # * +list+ - index of item to remove (1-indexed), or 'all', to remove all items.
+    def removeitem item
+      IupLib.IupSetAttribute(@handle, "REMOVEITEM", item.to_s)
+    end
+
+    ##
+    # :attr_reader: screenposition
+    # returns position in pixels on screen as "x,y".
+    define_reader :screenposition
+
+    ##
+    # :attr: scrollbar
+    # When in multiline mode, enables a scrollbar.
+    # Values 'vertical' / 'horizontal' / 'yes' / 'no'.
+    define_attribute :scrollbar
+
+    ##
+    # :attr_writer: scrollto
+    # (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.
+    define_writer :scrollto
+
+    ##
+    # :attr_writer: scrolltopos
+    # (with editbox set) Scrolls to make character 'number' visible.
+    define_writer :scrolltopos
+
+    ##
+    # :attr: selectedtext
+    # (with editbox set) Reads or overwrites the current selection. 
+    # Does nothing if no text is selected.
+    define_attribute :selectedtext
+
+    ##
+    # :attr: selection
+    # (with editbox set) Selects text as 'col1:col2' (single-line) /
+    # 'lin1,col1:lin2,col2' (multi-line) / 'all' / 'none'.
+    define_attribute :selection
+
+    ##
+    # :attr: selectionpos
+    # (with editbox set) Selects text between character positions: 'pos1:pos2'
+    # / 'all' / 'none'.
+    define_attribute :selectionpos
+
+    ##
+    # :attr: showdragdrop
+    # If set, enables internal drag/drop: values 'yes' / 'no'.
+    define_attribute :showdragdrop
+
+    ##
+    # :attr_writer: showdropdown
+    # Shows the dropdown list, if dropdown=yes.
+    define_writer :showdropdown
+
+    define_attribute :showimage
+
+    ##
+    # :attr: sort
+    # Forces items to be sorted alphabetically. 
+    # Insert/append operations will ignore the index number.
+    define_attribute :sort
+
+    ##
+    # :attr: spacing
+    # Space between items, value as a number.
+    define_attribute :spacing
+
+    ##
+    # :attr: tip
+    # Tooltip string.
+    define_attribute :tip
+
+    ##
+    # :attr: value
+    # 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 +/-
+    
+    # --
+    def value 
+      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
+    end
+
+    def value= val # :nodoc:
+      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
+
+    ##
+    # :attr: visiblecolumns
+    # The minimum number of visible columns, defaults to 5.
+    define_attribute :visiblecolumns
+
+    ##
+    # :attr: visiblelines
+    # The minimum number of visible lines, when dropdown=no.
+    define_attribute :visiblelines
+
+    # :section: Callbacks
+
+    ##
+    # :attr_writer: action
+    # 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
+
+    # --
+    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
+
+    include ButtonCallback
+
+    ##
+    # :attr_writer: caret_cb
+    # 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)
+
+    # --
+    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
+
+    ##
+    # :attr_writer: dblclick_cb
+    # 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
+
+    # --
+    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
+
+    ##
+    # :attr_writer: dragdrop_cb
+    # 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.
+
+    # --
+    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
+
+    ##
+    # :attr_writer: dropdown_cb
+    # 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.
+
+    # --
+    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
+
+    ##
+    # :attr_writer: edit_cb
+    # 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
+
+    # --
+    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
+
+    ##
+    # :attr_writer: motion_cb
+    # 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.
+
+    #--
+    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
+
+    ##
+    # :attr_writer: multiselect_cb
+    # 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
+
+    # --
+    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
+
+    ##
+    # :attr_writer: valuechanged_cb
+    # 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.
+
+    # --
+    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
+
+  end
+end