class Iup::Tree

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

Example

tree = Iup::Tree.new

dlg = Iup::Dialog.new(tree) do |d|
  d.title = 'Tree Example'
end.map

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

dlg.show

Note: the contents of the tree can only be created after its containing dialog has been mapped.

Attributes

addexpanded [RW]

‘yes’ / ‘no’, to expand branches when created.

addroot [RW]

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

canfocus [RW]

Enables the control to gain focus. Values ‘yes’ / ‘no’.

count [R]

Returns total number of nodes in the tree.

dragdroptree [RW]

Determines if tree supports dragdrop operations. Values ‘yes’ / ‘no’.

dropequaldrag [RW]

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

expand [RW]

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

expandall [RW]

Expands or contracts all nodes, values ‘yes’ / ‘no’.

hidebuttons [RW]

‘yes’ / ‘no’, to hide expand and create buttons.

hidelines [RW]

‘yes’ / ‘no’, the lines connecting nodes in hierarchy.

imagebranchcollapsed [RW]

Image to be used for all collapsed branches. This can use an actual image object, or the name of an image from IupImageLib.

imagebranchexpanded [RW]

Image to be used for all expanded branches. This can use an actual image object, or the name of an image from IupImageLib.

imageleaf [RW]

Image to be used for all leaf nodes. This can use an actual image object, or the name of an image from IupImageLib.

indentation [RW]

level of indentation in pixels, defaults to 5.

mark [W]

selects a range of nodes: ‘start-end’ / ‘INVERTid’ / ‘block’ / ‘clearall’ / ‘markall’ / ‘invertall’

markednodes [RW]

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

markmode [RW]

‘single’ / ‘multiple’, for selection of nodes.

markstart [RW]

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

position [R]

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

rastersize [RW]

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

screenposition [R]

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

showdragdrop [RW]

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

showtoggle [RW]

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

spacing [RW]

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

topitem [W]

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

value [RW]

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

Public Class Methods

new ()

Source

# File lib/wrapped/tree.rb, line 41
def initialize
  @handle = IupLib.IupTree
end

Creates an instance of Tree. Unusually, does not accept an initialization block, as tree must be placed and mapped within a dialog before setup can take place - see Example.

Public Instance Methods

addbranch (id, val)

Source

# File lib/wrapped/tree.rb, line 407
def addbranch id, val
  IupLib.IupSetAttribute @handle, "ADDBRANCH#{id}", val.to_s
end

Adds new branch after specified node.

id - identifier of a node
val - text label

addleaf (id, val)

Source

# File lib/wrapped/tree.rb, line 414
def addleaf id, val
  IupLib.IupSetAttribute @handle, "ADDLEAF#{id}", val.to_s
end

Adds new leaf after specified node.

id - identifier of a node
val - text label

childcount (id)

Source

# File lib/wrapped/tree.rb, line 147
def childcount id
  IupLib.IupGetAttribute(@handle, "CHILDCOUNT#{id}").first
end

Returns the number of immediate child of given node.

id - identifier of a node

color(id) # retrieves

color(id, val) # sets

Source

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

Accesses text foreground color:

id - identifier of a node
val - “r g b” color

copynode (source_id, target_id)

Source

# File lib/wrapped/tree.rb, line 421
def copynode source_id, target_id
  IupLib.IupSetAttribute @handle, "COPYNODE#{id}", target_id.to_s
end

Copies source node and its children to target.

source_id - identifier of a node
target_id - identifier of a node

delnode (id, val)

Source

# File lib/wrapped/tree.rb, line 432
def delnode id, val
  IupLib.IupSetAttribute @handle, "DELNODE#{id}", val.to_s
end

Delete one or more nodes:

id - identifier of a node
val - one of
- ‘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.

depth (id)

Source

# File lib/wrapped/tree.rb, line 168
def depth id
  IupLib.IupGetAttribute(@handle, "DEPTH#{id}").first
end

Returns the depth of the given node.

id - identifier of a node

image (id, img)

Source

# File lib/wrapped/tree.rb, line 285
def image id, img
  attribute_reference "IMAGE#{id}", ImageWidget, img
end

Sets image to use for given node.

id - identifier of a node
img - image name or reference. This can use an actual image object, or the name of an image from IupImageLib.

imageexpanded (id, img)

Source

# File lib/wrapped/tree.rb, line 292
def imageexpanded id, img
  attribute_reference "IMAGEEXPANDED#{id}", ImageWidget, img
end

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

id - identifier of a node
img - image name or reference. This can use an actual image object, or the name of an image from IupImageLib.

insertbranch (id, val)

Source

# File lib/wrapped/tree.rb, line 444
def insertbranch id, val
  IupLib.IupSetAttribute @handle, "INSERTBRANCH#{id}", val.to_s
end

Inserts new branch after specified node, preserving depth.

id - identifier of a node
val - text label

insertleaf (id, val)

Source

# File lib/wrapped/tree.rb, line 451
def insertleaf id, val
  IupLib.IupSetAttribute @handle, "INSERTLEAF#{id}", val.to_s
end

Inserts new leaf after specified node, preserving depth.

id - identifier of a node
val - text label

kind (id)

Source

# File lib/wrapped/tree.rb, line 174
def kind id
  IupLib.IupGetAttribute(@handle, "KIND#{id}").first
end

Returns kind of given node, as ‘leaf’ or ‘branch’.

id - identifier of a node

marked(id) # retrieves

marked(id, val) # sets

Source

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

Accesses marked state of node:

id - identity of node
val - ‘yes’ / ‘no’

movenode (source_id, target_id)

Source

# File lib/wrapped/tree.rb, line 458
def movenode source_id, target_id
  IupLib.IupSetAttribute @handle, "MOVENODE#{id}", target_id.to_s
end

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

source_id - identifier of a node
target_id - identifier of a node

parent (id)

Source

# File lib/wrapped/tree.rb, line 180
def parent id
  IupLib.IupGetAttribute(@handle, "PARENT#{id}").first
end

Returns identifier of parent of given node.

id - identifier of a node

state(id) # retrieves

state(id, val) # sets

Source

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

Accesses state as ‘collapsed’ or ‘expanded’:

id - identifier of a node
val - value ‘collapsed’ or ‘expanded’.

title(id) # retrieves

title(id, val) # sets

Source

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

Accesses title of given node:

id - identifier of a node
val - title.

titlefont(id) # retrieves

titlefont(id, val) # sets

Source

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

Accesses font of node title:

id - identifier of a node
val - font description.

togglevalue(id) # retrieves

togglevalue(id, val) # sets

Source

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

Accesses toggle state of given node:

id - identifier of a node
val - state as ‘on’ / ‘off’ / ‘notdef’

togglevisible(id) # retrieves

togglevisible(id, val) # sets

Source

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

Accesses toggle visibility of given node:

id - identifier of a node
val - visibility as ‘yes’ / ‘no’.

totalchildcount (id)

Source

# File lib/wrapped/tree.rb, line 261
def totalchildcount id
  IupLib.IupGetAttribute(@handle, "TOTALCHILDCOUNT#{id}").first
end

Returns total number of children for given node.

id - identifier of a node

userdata(id) # retrieves

userdata(id, val) # sets

Source

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

Accesses userdata for given node id.

id - identifier of a node
val - user data (a string)

Callbacks

Attributes

branchclose_cb [W]

Callback called when a branch is collapsed. Callback must respond to call and takes 1 argument: (node_id)

node_id - reference to node closed

branchopen_cb [W]

Callback called when a branch is expanded. Callback must respond to call and takes 1 argument: (node_id)

node_id - reference to node opened

dragdrop_cb [W]

Callback called when an internal drag & drop is executed. Only active if SHOWDRAGDROP=YES. Callback must respond to call and 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.

executeleaf_cb [W]

Callback called when a leaf is to be executed. Callback must respond to call and takes 1 argument: (node_id)

node_id - reference to node

motion_cb [W]

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.

rightclick_cb [W]

Callback called when the right mouse button is pressed over a node. Callback must respond to call and takes 1 argument: (node_id)

node_id - reference to node

selection_cb [W]

Callback called when a node is selected or deselected. Callback must respond to call and takes 2 arguments: (node_id, status)

node_id - reference to node
status - whether node is selected or deselected

togglevalue_cb [W]

Callback called when the toggle’s state was changed. Callback must respond to call and takes 2 arguments: (node_id, status).

node_id - reference to node
status - new state of toggle