class Iup::Tree

A Tree displays a hierarchy of branch and leaf nodes. Each node may display some text and an optional image.

The contents of the tree can only be created after the tree has been located in a dialog, and before the Dialog#show method is called. See the example below:

mainloop do

  tree = Tree.new

  dlg = Dialog.new tree do
    title 'Tree Example'
  end.map

  tree.instance_eval do
    title 'Figures'
    size '80x80'
    font 'Courier, Normal 10'
    title 'Figures'
    addbranch 0, '3D'
    addbranch 0, '2D'
    addleaf 1, 'trapeze'
    addbranch 1, 'parallelogram'
    addleaf 2, 'diamond'
    addleaf 2, 'square'
    addbranch 4, 'triangle'
    addleaf 5, 'scalenus'
    addleaf 5, 'isoceles'
    addleaf 5, 'equilateral'
    value 6
    addexpanded 'no'
  end 

  dlg.show
end

Attributes

addexpanded

'yes' / 'no', to expand branches when created.

addroot

'yes' / 'no', automatically adds an empty branch as the first node, on creation.

canfocus

Enables the control to gain focus. Values 'yes' / 'no'.

count

read-only returns total number of nodes in the tree.

dragdroptree

'yes' / 'no'.

dropequaldrag

'yes' / 'no', if set, allows a drop node to equal drag node.

expand

Allows control to fill available space in indicated direction. Values 'no' / 'horizontal' / 'vertical' / 'yes'.

hidebuttons

'yes' / 'no', to hide expand and create buttons.

hidelines

'yes' / 'no', the lines connecting nodes in hierarchy.

indentation

level of indentation in pixels, defaults to 5.

position

read-only returns position in pixels within client window as “x,y”.

rastersize

Size of the control, in pixels, value as “widthxheight”.

screenposition

read-only returns position in pixels on screen as “x,y”.

showdragdrop

'yes' / 'no', enables internal drag and drop of nodes.

showtoggle

'yes' / 'no' / '3state', enables use of toggles for all nodes of the tree.

spacing

vertical, internal padding for each node, defaults to 3 pixels.

topitem

write-only Positions given node id at the top of tree, or near, to make it visible.

value

When retrieved, returns the identifier of the focussed node. When given a value, moves focus appropriately: 'root' / 'last' / 'next' / 'previous' / 'pgdn' / 'pgup'

mark

<b>write-only> selects a range of nodes: 'start-end' / 'INVERTid' / 'block' / 'clearall' / 'markall' / 'invertall'

markmode

'single' / 'multiple', for selection of nodes.

markstart

Initial node for block marking, used when mark=block.

expandall

Expands or contracts all nodes, values 'yes' / 'no'.

Public Class Methods

new(&block) click to toggle source

Creates an instance of Tree which is set up via the block.

# File lib/wrapped/tree.rb, line 79
def initialize &block
  @handle = IupLib.IupTree

  # run any provided block on instance, to set up further attributes
  self.instance_eval &block if block_given?
end

Public Instance Methods

addbranch(id, val) click to toggle source

Adds new branch after specified node.

id

identifier of a node

val

text label

# File lib/wrapped/tree.rb, line 307
def addbranch id, val
  IupLib.IupSetAttribute @handle, "ADDBRANCH#{id}", val.to_s
end
addleaf(id, val) click to toggle source

Adds new leaf after specified node.

id

identifier of a node

val

text label

# File lib/wrapped/tree.rb, line 314
def addleaf id, val
  IupLib.IupSetAttribute @handle, "ADDLEAF#{id}", val.to_s
end
branchclose_cb(callback) click to toggle source

ction generated when a branch is collapsed.

# File lib/wrapped/tree.rb, line 385
def branchclose_cb callback
  unless callback.arity == 1
    raise ArgumentError, 'branchclose_cb callback must take 1 argument: node_id'
  end
  cb = Proc.new do |ih, id|
    callback.call id
  end
  define_callback cb, 'BRANCHCLOSE_CB', :i_i
end
branchopen_cb(callback) click to toggle source

Action generated when a branch is expanded.

# File lib/wrapped/tree.rb, line 374
def branchopen_cb callback
  unless callback.arity == 1
    raise ArgumentError, 'branchopen_cb callback must take 1 argument: node_id'
  end
  cb = Proc.new do |ih, id|
    callback.call id
  end
  define_callback cb, 'BRANCHOPEN_CB', :i_i
end
childcount(id) click to toggle source

Returns the number of immediate child of given node.

id

identifier of a node

# File lib/wrapped/tree.rb, line 112
def childcount id
  IupLib.IupGetAttribute(@handle, "CHILDCOUNT#{id}").first
end
color(id, val=nil) click to toggle source

Controls text foreground colour: provide a 'val' to set colour, otherwise, current colour returned.

id

identifier of a node

val

optional “r g b” colour

# File lib/wrapped/tree.rb, line 120
def color id, val=nil
  if val.nil?
    IupLib.IupGetAttribute(@handle, "COLOR#{id}").first
  else
    IupLib.IupSetAttribute @handle, "COLOR#{id}", val
  end
end
copynode(source_id, target_id) click to toggle source

Copies source node and its children to target.

source_id

identifier of a node

target_id

identifier of a node

# File lib/wrapped/tree.rb, line 321
def copynode source_id, target_id
  IupLib.IupSetAttribute @handle, "COPYNODE#{id}", target_id.to_s
end
delnode(id, val) click to toggle source

Delete one or more nodes, depending on val:

  • 'all': ignores id and deletes all nodes in tree, including root.

  • 'selected': deletes selected node and its children.

  • 'children': deleted only the children of selected node.

  • 'marked': ignores id and deletes all selected node.

id

identifier of a node

val

one of above values

# File lib/wrapped/tree.rb, line 333
def delnode id, val
  IupLib.IupSetAttribute @handle, "DELNODE#{id}", val.to_s
end
depth(id) click to toggle source

Returns the depth of the given node.

id

identifier of a node

# File lib/wrapped/tree.rb, line 130
def depth id
  IupLib.IupGetAttribute(@handle, "DEPTH#{id}").first
end
dragdrop_cb(callback) click to toggle source

Action generated when an internal drag & 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/tree.rb, line 437
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
executeleaf_cb(callback) click to toggle source

Action generated when a leaf is to be executed

# File lib/wrapped/tree.rb, line 396
def executeleaf_cb callback
  unless callback.arity == 1
    raise ArgumentError, 'executeleaf_cb callback must take 1 argument: node_id'
  end
  cb = Proc.new do |ih, id|
    callback.call id
  end
  define_callback cb, 'EXECUTELEAF_CB', :i_i
end
image(id, img) click to toggle source

Sets image to use for given node.

id

identifier of a node

img

image name or reference

# File lib/wrapped/tree.rb, line 229
def image id, img
  attribute_reference "IMAGE#{id}", ImageWidget, img
end
imagebranchcollapsed(img=nil) click to toggle source

If given, sets image to be used for all collapsed branches, otherwise returns current value.

img

optional image name or reference

# File lib/wrapped/tree.rb, line 250
def imagebranchcollapsed img=nil
  attribute_reference "IMAGEBRANCHCOLLAPSED", ImageWidget, img
end
imagebranchexpanded(img=nil) click to toggle source

If given, sets image to be used for all expanded branches, otherwise returns current value.

img

optional image name or reference

# File lib/wrapped/tree.rb, line 257
def imagebranchexpanded img=nil
  attribute_reference "IMAGEBRANCHEXPANDED", ImageWidget, img
end
imageexpanded(id, img) click to toggle source

Sets image to use for given node, for expanded branches.

id

identifier of a node

img

image name or reference

# File lib/wrapped/tree.rb, line 236
def imageexpanded id, img
  attribute_reference "IMAGEEXPANDED#{id}", ImageWidget, img
end
imageleaf(img=nil) click to toggle source

If given, sets image to be used for all leaf nodes, otherwise returns current value.

img

optional image name or reference

# File lib/wrapped/tree.rb, line 243
def imageleaf img=nil
  attribute_reference "IMAGELEAF", ImageWidget, img
end
insertbranch(id, val) click to toggle source

Inserts new branch after specified node, preserving depth.

id

identifier of a node

val

text label

# File lib/wrapped/tree.rb, line 342
def insertbranch id, val
  IupLib.IupSetAttribute @handle, "INSERTBRANCH#{id}", val.to_s
end
insertleaf(id, val) click to toggle source

Inserts new leaf after specified node, preserving depth.

id

identifier of a node

val

text label

# File lib/wrapped/tree.rb, line 349
def insertleaf id, val
  IupLib.IupSetAttribute @handle, "INSERTLEAF#{id}", val.to_s
end
kind(id) click to toggle source

Returns kind of given node, as 'leaf' or 'branch'.

id

identifier of a node

# File lib/wrapped/tree.rb, line 136
def kind id
  IupLib.IupGetAttribute(@handle, "KIND#{id}").first
end
marked(id, val=nil) click to toggle source

Selection state of specific node returned or, if val given, set.

id

identifier of a node

val

optional 'yes' / 'no'

# File lib/wrapped/tree.rb, line 267
def marked id, val=nil
  if val.nil?
    IupLib.IupGetAttribute(@handle, "MARKED#{id}").first
  else
    IupLib.IupSetAttribute @handle, "MARKED#{id}", val
  end
end
markednodes(val=nil) click to toggle source

Sets/gets selection indices of all marked nodes, when markmode=multiple.

val

optional [ids]

# File lib/wrapped/tree.rb, line 278
def markednodes val=nil
  if val.nil?
    mns = IupLib.IupGetAttribute(@handle, 'MARKEDNODES').first
    result = []
    mns.split('').each_with_index do |item, index|
      result << index+1 if item == '+'
    end
    return result
  else
    result = ""
    count.to_i.times do |i|
      if val.include?(i+1)
        result << '+'
      else
        result << '-'
      end
    end
    IupLib.IupSetAttribute @handle, 'MARKEDNODES', result
  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/tree.rb, line 455
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
movenode(source_id, target_id) click to toggle source

Moves source to target, as a new child or sibling.

source_id

identifier of a node

target_id

identifier of a node

# File lib/wrapped/tree.rb, line 356
def movenode source_id, target_id
  IupLib.IupSetAttribute @handle, "MOVENODE#{id}", target_id.to_s
end
parent(id) click to toggle source

Returns identifier of parent of given node.

id

identifier of a node

# File lib/wrapped/tree.rb, line 142
def parent id
  IupLib.IupGetAttribute(@handle, "PARENT#{id}").first
end
rightclick_cb(callback) click to toggle source

Action generated when the right mouse button is pressed over a node.

# File lib/wrapped/tree.rb, line 407
def rightclick_cb callback
  unless callback.arity == 1
    raise ArgumentError, 'rightclick_cb callback must take 1 argument: node_id'
  end
  cb = Proc.new do |ih, id|
    callback.call id
  end
  define_callback cb, 'RIGHTCLICK_CB', :i_i
end
selection_cb(callback) click to toggle source

Action generated when a node is selected or deselected.

# File lib/wrapped/tree.rb, line 363
def selection_cb callback
  unless callback.arity == 2
    raise ArgumentError, 'selection_cb callback must take 2 arguments: node_id, status'
  end
  cb = Proc.new do |ih, id, status|
    callback.call id, status
  end
  define_callback cb, 'SELECTION_CB', :ii_i
end
state(id, val=nil) click to toggle source

Controls state as 'collapsed' or 'expanded': provide a 'val' to set state, otherwise, current state returned (nil for a leaf).

id

identifier of a node

val

optional value 'collapsed' or 'expanded'.

# File lib/wrapped/tree.rb, line 150
def state id, val=nil
  if val.nil?
    IupLib.IupGetAttribute(@handle, "STATE#{id}").first
  else
    IupLib.IupSetAttribute @handle, "STATE#{id}", val
  end
end
title(id, val=nil) click to toggle source

Controls title of given node: provide a 'val' to set, otherwise, current title returned.

id

identifier of a node

val

optional title.

# File lib/wrapped/tree.rb, line 162
def title id, val=nil
  if val.nil?
    IupLib.IupGetAttribute(@handle, "TITLE#{id}").first
  else
    IupLib.IupSetAttribute @handle, "TITLE#{id}", val
  end
end
titlefont(id, val=nil) click to toggle source

Controls font of node title: provide a 'val' to set font, otherwise, current font returned.

id

identifier of a node

val

optional font description.

# File lib/wrapped/tree.rb, line 174
def titlefont id, val=nil
  if val.nil?
    IupLib.IupGetAttribute(@handle, "TITLEFONT#{id}").first
  else
    IupLib.IupSetAttribute @handle, "TITLEFONT#{id}", val
  end
end
togglevalue(id, val=nil) click to toggle source

Controls toggle state of given node: provide a 'val' to set state, otherwise, current state returned.

id

identifier of a node

val

optional state as 'on' / 'off' / 'notdef'

# File lib/wrapped/tree.rb, line 186
def togglevalue id, val=nil
  if val.nil?
    IupLib.IupGetAttribute(@handle, "TOGGLEVALUE#{id}").first
  else
    IupLib.IupSetAttribute @handle, "TOGGLEVALUE#{id}", val
  end
end
togglevalue_cb(callback) click to toggle source

Action generated when the toggle's state was changed.

# File lib/wrapped/tree.rb, line 418
def togglevalue_cb callback
  unless callback.arity == 2
    raise ArgumentError, 'togglevalue_cb callback must take 2 arguments: node_id, status'
  end
  cb = Proc.new do |ih, id, status|
    callback.call id, status
  end
  define_callback cb, 'TOGGLEVALUE_CB', :ii_i
end
togglevisible(id, val=nil) click to toggle source

Controls toggle visibility of given node: provide a 'val' to set visibility, otherwise, current visibility returned.

id

identifier of a node

val

optional visibility as 'yes' / 'no'.

# File lib/wrapped/tree.rb, line 198
def togglevisible id, val=nil
  if val.nil?
    IupLib.IupGetAttribute(@handle, "TOGGLEVISIBLE#{id}").first
  else
    IupLib.IupSetAttribute @handle, "TOGGLEVISIBLE#{id}", val
  end
end
totalchildcount(id) click to toggle source

Returns total number of children for given node.

id

identifier of a node

# File lib/wrapped/tree.rb, line 208
def totalchildcount id
  IupLib.IupGetAttribute(@handle, "TOTALCHILDCOUNT#{id}").first
end
userdata(id, val=nil) click to toggle source

Controls user data associated with given node: provide a 'val' to set userdata, otherwise, current userdata returned.

id

identifier of a node

val

optional userdata to associate with given node.

# File lib/wrapped/tree.rb, line 216
def userdata id, val=nil
  if val.nil?
    IupLib.IupGetAttribute(@handle, "USERDATA#{id}").first
  else
    IupLib.IupSetAttribute @handle, "USERDATA#{id}", val
  end
end