1.175 class tree

Class tree is a subclass of class device which displays its graphical objects formatted as a hierarchy. Class tree fits well in PCE's target domain: graphical interfaces for structured representations (models).

The nodes of a PCE tree may be arbitrary graphical objects (yes, even trees, editors, etc.). Trees allow for multiple inheritance, but the automatically generated layout is often not optimal when multiple inheritance is used intensively. The automatically generated layouts for hierarchies are top-to-bottom, left-to-right (default) or‘indented list’.

Class tree itself is responsible for displaying and formatting the nodes of the hierarchy. The hierarchy is defined by node objects. A node object refers to a graphical (using node<->image), its parent node(s) and its son nodes.

Event-handling for trees may be done in two ways. The first is to define event-handling for each of the individual graphicals representing the nodes. The second is to associate recognisers with the tree object itself. Class tree defines various different recognisers, activation of which depends on the status of the node. See tree->event.

See also

- graphical->layout
- class node

1.175.1 Instance variables

tree <- auto_layout: bool

When @on (default), the tree will recompute its layout on any change to any of its nodes or change to the tree itself. When @off the tree won't automatically recompute the layout.

Sometimes, it is desirable to allow the user to move the nodes of a tree by hand. With tree<-auto_layout: @on this is not possible as the tree will immediately move the node back to the original position.

See also tree->compute and tree->layout.

tree <- collapsed_handlers: chain

@see tree->event

tree <- direction: {horizontal,vertical,list}

Defines the layout:

horizontal

Root at the left, the sons are displayed left-to-right.

vertical

The tree is displayed top-to-bottom.

list

The tree is displayed as an indented list. The line properties of the tree<-link are used to determine the thickness, texture and colour of the lines. Each node will, if it has sons, draw a line from (x + tree<-level_gap/2, bottom side) down to halfway the last son. If to node is not the root, it will draw a line from halfway its height towards the line from its parent. See also node<->collapsed.

Note: the default tree is displayed left-to-right rather than top-to-bottom as the nodes are often much wider than high. Using left-to-right layout allows for displaying much larger hierarchies.

When a large number of items is to be displayed as an indented list, also consider class list_browser. The indentation may be realised using list_browser->tab_stops.

tree <- display_root: node*

Root of the visible part of the tree. This variable is managed using tree->zoom and tree->unzoom.

See also

- tree-root
- tree->zoom

tree <- leaf_handlers: chain

@see tree->event

tree <- level_gap: int

Distance between a node and its parents or sons.

tree <- link: link

Link used to create connections between parent- and son-nodes. Its attributes may be changed to attach arrows or modify one of the line attributes. For example,

send(Tree?link, arrows, first).

will attach an arrow pointing to the root to every relation created after this call has been made.

See also

- tree-link_gap
- tree-parent_handle
- tree-son_handle

tree <- link_gap: int

Distance between the image and the line. Used to define the X- and Y-positions of the tree<-son_handle and tree<-parent_handle.

See also

- tree-parent_handle
- tree-son_handle
- tree-link

tree <- neighbour_gap: int

Distance between two nodes that are at the same level (= distance from the root). The default (0) satisfies when the nodes are represented by text object. For other graphicals a small positive value gives better results.

See also

- tree->level_gap
- tree->neighbour_gap

tree <- node_handlers: chain

@see tree->event

tree <- parent_handle: handle

This handle object is attached to each graphical representing a node. It is the connection-point for a line linking this graphical to its parent.

This handle is automatically updated by tree->direction..

See also

- tree-link_gap
- tree-link
- tree->direction
- tree-son_handle
- class handle

tree <- root: node*

Root node of the tree. Note that the root of the visual part of the tree is represented by tree<-display_root. Class tree delegates messages not understood to its tree<-root node when present.

If the argument is *nil, all nodes are removed from the tree. If the argument is a new root object the behaviour depends on the relink argument. With relink = @off (default), the tree is first cleared using tree->root: @nil, after which the new root is attached. With relink = @on the old root is added as the only node->son of the new root.

See also tree->zoom and tree->unzoom.

See also

tree-display_root

tree <- root_handlers: chain

@see tree->event

tree <- son_handle: handle

Similar to tree<-parent_handle, but is the connection-point for the connection towards son-nodes.

See also

- tree-link_gap
- tree-link
- tree-parent_handle

1.175.2 Send methods

tree ->collapsed_handler: recogniser

Attach a recogniser for all nodes that have node<->collapsed. See tree->event for the interpretation.

See also

- node-collapsed
- tree->event

tree ->compute:

Whenever something changes to the tree that might affect its layout, this is notified using graphical->request_compute. tree->compute recomputes the layout of the tree by invoking tree->layout.

tree ->direction: {horizontal,vertical,list}

@see tree-parent_handle

tree ->event: event

tree->event allows for centralised event-processing for all nodes displayed on the tree. It performs the following steps.

1. Invoke device->event. When successful, succeed.
2. Invoke node->event on the node below the pointer.

• * Finding the Context Arguments The most reliable way to find the various context objects are:

  @event?receiver	Graphical receiving the event
  @event?receiver?node	Node object for this graphical
  @event?receiver?device	The tree object

  See also

  - tree->root_handler
  - tree->node_handler
  - tree->leaf_handler
  - tree->collapsed_handler
  - graphical<-node
  - tree-root_handlers
  - tree-node_handlers
  - tree-leaf_handlers
  - tree-collapsed_handlers

tree ->for_some: code

Run code on all nodes.

tree ->for_all: code

Invokes the message to the tree<-root of the tree, iterating over all nodes of the tree. See also node->for_all, node->for_some and tree<-contains.

See also

- node->for_all
- tree->for_some

tree ->initialise: root=[node]*

Create a tree object and assign it a root. When the root is @nil (default), the tree must be assigned a root using tree->root before any other nodes may be attached.

Note that class node defines a convert method for graphicals that creates a node with the specified graphical as node<-image.

See also

tree->root

tree ->layout:

Recompute the layout of the tree. This method is normally called from tree->compute and sends the following three messages to tree<-display_root:

node->compute_level	Update the node<-level slots
node->compute_size	Compute the sizes of all nodes
node->compute_layout	Place the nodes

tree ->leaf_handler: recogniser

Attach a recogniser for all nodes that have no sons (i.e. are leaves). See tree->event for the interpretation.

See also

tree->event

tree ->level_gap: int

@see tree-neighbour_gap

tree ->neighbour_gap: int

@see tree-neighbour_gap

tree ->node_handler: recogniser

Attach a recogniser for all nodes. See tree->event for the interpretation.

See also

tree->event

tree ->root: root=node*, relink=[bool]

@see !already_has_root @see tree->initialise

tree ->root_handler: recogniser

Attach a recogniser for the tree<-display_root node. See‘tree tree->event’for the interpretation.

See also

tree->event

tree ->unzoom:

Equivalent to:

send(Tree, zoom, Tree?root).

To unzoom only one level, use

send(Tree, zoom, Tree?display_root?parents?head).

Note that this method is ambiguous when the display_root has multiple parents.

See also

- node->unzoom
- tree->zoom

tree ->zoom: node

Zoom in for a particular subtree. The visualisation of the tree will behave as if the argument-node of this method is the root. Sets the variable tree<-display_root.

See also

- node->zoom
- node-displayed
- node-collapsed
- tree->unzoom
- tree-display_root

1.175.3 Get methods

tree <-contains: -> chain

New chain holding all node objects in the tree.

Its device functionality would be to return the chain of graphicals, holding only the graphicals for the displayed nodes and connections.

The contains-hierarchy for trees is defined as follows:

tree
|  node
|   |  image

Image (being a graphical) may contain any number of sub-visuals.

See also

- graphical<-contained_in
- node<-contains
- node<-contained_in