Copyright © 2008, 2009 Arndt Roger Schneider

Rtl_tree
Prev Appendix A. Reference Next

Name

rtl_tree — Create and manipulate rtl_tree windows

Synopsis

          package require rtl_tree
        
          rtl_tree pathName ?options ?

Runtime Library Options

-creator

The RTL based option creator is used to instantiate the template rtl_tree with a Tk Window. The used creator window must have a -class property.

Acceptable Tk Windows are: toplevel for floating windows, and frame for embedded windows.

Standard Options

-selectForeground, -selectBackground, -font, -width, -height, -borderwidth, -relief, -background, -highlightBackground, -highlightColor, -highlightThickness, -foreground

See the options manual entry for details on the standard options.

Window-specific Options

Command-Line Name: -select, Database Name: select, Database Class; -

-select option. Set and get current selection.

Command-Line Name: -char, Database Name: char, Database Class; -

String character, defines how a set of raw entries are related to each other. The »-char« is used to transform these raw data into a hierarchical representation, which can be digested by the rtl_tree window.

Example A.11. Rtl_tree Char Transformation

rtl_tree .tree -char :

# Insert nodes:
# Assume, images: »a«, »b« and »c«.
foreach node { :a :b :c :a:b :a:c :b:c :a:b:c } {
    .tree insert $node \
           -text $node \
          -image [lindex [split $node :] end]
}

Default value is /.

Command-Line Name: -type, Database Name: type, Database Class; -

The default »-type« for rtl_tree items. The »-type« property can be omitted for the default type.

Command-Line Name: -indentx, Database Name: indentx, Database Class; -

Dimension, defines the horizontal distance between a node and its children. Default value is 21p (21 points).

Negative values for »-indentx« changes the rtl_tree’s horizontal orientation from left-to-right to right-to-left.

The value 0 is not permitted.

Command-Line Name: -indenty, Database Name: indenty, Database Class; -

Dimension, defines the minimal distance in vertical direction between two neighboring nodes.

The real vertical distance between two neighboring nodes depends on the size requirements of the top node. »-indenty« is ignored by larger nodes.

Default value is 21p (21 points).

Command-Line Name: -root, Database Name: root, Database Class; -

Boolean value, defines that the rtl_tree has a single root node (origin).

A root-less hierarchy will appear as a series of independent hierarchies. A single root node is still needed from the programming side. The independent hierarchies are starting on the second hierarchy level.

Default value is 1 (true).

Command-Line Name: -connect, Database Name: connect, Database Class; -

Boolean value, defines that each child node is visually connected with its parent node.

Command-Line Name: -contextfcn, Database Name: contextfcn, Database Class; -

Call back command, this Tcl-script is called whenever a context menu is displayed, posted.

Command-Line Name: -format, Database Name: format, Database Class; -

format string, defines the text format for each node name. Default value is »%s«, the node name.

Command-Line Name: -columnselect, Database Name: columnselect, Database Class; -

Boolean value, nodes can be selected by clicking on their attributes.

Command-Line Name: -fullwidthselect, Database Name: fullWidthSelect, Database Class; -

Boolean value, defines that the selection encloses all additional attributes of all visible nodes. The selection width is determined by the right-most (longest) attribute.

Former property name »-itemselect«.

The effect of this property cannot normally be observed. The last attribute column is usually opaque and this will obscure the effect of »-fullwidthselect«, the selection will end with the second last attribute.

Command-Line Name: -visible, Database Name: visible, Database Class; -

A list of name position pairs.

»show«, list the visible elements inside the rtl_tree. Each element is called a »fellow« inside rtl_tree. These elements are organized in a separate table beside the hierarchy.

Command-Line Name: -selectfcn, Database Name: selectfcn, Database Class; -

Call back command, the script »-selectfcn« is whenever a node or leaf is selected.


Command-Line Name: -openfcn, Database Name: openfcn, Database Class; -

call back command, the »-openfcn« script is called in response to a double-click-left event on a tree node. The assumed purpose for this action is it to parse the affected tree-branch.

Example A.13. »-openfcn« Signature

proc reparse-the-tree-starting-at-node-of-type \
     <tree>node item<node type >

Command-Line Name: -drag, Database Name: drag, Database Class; -

Boolean value, activates drag-and-drop inside the rtl_tree window.

Command-Line Name: -dragfcn, Database Name: dragfcn, Database Class; -

The »-dragfcn« call back command is called after a drag-and-drop operation is completed.

Example A.14. »-dragfcn« Signature

proc drop-on-target-the-dragged-items \
   <tree> <tree canvas> \ 
   {<target item> <target type>} \
   {{<source item> <type>} ...} \
   x y screenX screenY

Command-Line Name: -haschildrenfcn, Database Name: hasChildrenfcn, Database Class; -

The call back command »-haschildrenfcn« is called to question a closed node , while it is displayed, whether it has leafs. The script must return with an boolean value, where 1 means that the node has children.

Always return 1 on a dummy call back »-haschildrenfcn« command, when questioning isn’t possible. It is also the responsibility of »-requestchildrenfcn«, to remove the open / close indicator.

Command-Line Name: -requestchildrenfcn, Database Name: requestChildrenfcn, Database Class; -

Call back command, this Tcl-Script is called in response to a node open event. The leafs of this node can insert on demand.

See also: »-haschildrenfcn«.

Command-Line Name: -typedsel, Database Name: typedSel, Database Class; -

Boolean value, disallow the multi selection for items of different type.

Command-Line Name: -sides, Database Name: sides, Database Class; -

Set where the scrollbars are inserted.

Possible values are: »top«, »bottom«, »left«, »right« and combinations thereof.

Command-Line Name: -scrollwidth, Database Name: scrollWidth, Database Class; -

The scrollbar’s width dimension.

Command-Line Name: -show, Database Name: show, Database Class; -
Command-Line Name: -glyphs, Database Name: glyphs, Database Class; -

Boolean value, defines that a font glyph shall be used instead of the provided images. The used glyphs are queried from the option database. The provided image name is used to find the glyph used for an icon.

Example A.15. Substituting Images with Glyphs

# Use glyph »F« in place of image »_frame«.
option add *Rtl_tree._frame__glyph F

Description

Figure A.3. rtl_tree


RunTimeLibrary Tree Implementation

Designed for Tk 8.0–8.3, 8.4 and 8.5 Tkpath 0.2 and 0.3

Recommended Tk 8.5 for AQUA with Tkpath 0.2 Tk 8.4 for X11 with Tkpath >0.2.4 < 0.3

Tkpath is not needed by rtl_tree!

Performance

This hierarchy view is able to draw 'nodes' with different sizes and multiple text properties with multiple lines.

The size of each node can only being know after it was draw, thereof results the linear complexity of the hierarchy window. To minimize drawings, the hierarchy is split into three sections: unaffected before, affected, unaffected after. Only the affected nodes are really drawn with before mentioned linear complexity -- one part of the rest is simply moved. After an affected region has been drawn the interconnection between before and after are reconnected.

This tree is able to handle approximately 300 leafs per node on an average 400 MHz machine.

Closing and reopening the root node is performance vise the worst case scenario, because all visual nodes are affected.

Rebuild

The rtl_tree component provides two building processes, build and rebuild.

  • ➊. there are entries, which are not affected by the last drawing.
  • ➋. There are many items following the point which has been changed.
  • ➌. There are points delete or newly created which must initial drawn.

How to handle these 3 parts?

The non affected graphical items are not touched (no redraw is necessary). The second part is more difficult to handle, this part is divided in two contradicting directions; when you want to delete items, each item and its ascendant items are directly destroyed before rebuild is called. Whereas when you display new items rebuild is required to display them. The third part is also splitted into two needed action first the complete graphical items must be moved to the location which is produced by action 2. Each connection with the first part must be deleted and redrawn.

How to determine between this parts ?

Each instance stores the information about its items into a list named stream. Provide the last non affected item, out of stream, when calling rebuild. The list stream must be valid when calling rebuild, this means you must have removed each delete graphic from stream before invoking rebuild. Rebuild itself must calculate the new space from part ➋ to determine how much from part ➌ must be moved. After this, the needed connection are reestablished.

The space from part ➋ and ➌ are calculated in one single direction (the growth direction).

Example A.16. Rebuild

When you have delete 1 item with 10
  sub items –11 items together.

➟ The space between vp1 and vp3 measures 
  11 x indenty.

➟ Rebuild must reduce this space to 1 x indenty;
  this space is 10 x indenty and 0 x indentx.

With minor release 1.1 new performance optimizations are applied to the tree widget. The formal rebuild process isn't changed but the determination for 1,2 and 3 has been optimized. In addition also the delete move actions are now controlled by the deleted or moved parent node (child nodes do have a children tag which refers to the parent node and move and delete operations are working with this tag).

Extensions

Uses TkPath for columns colour, Text, Glyphs (when defined), dragging rectangle, rubberband rectangle.

  • Rubber band selection fixed and activated.

  • Glyphs can be used to substitute 'images'.

  • Table like redesign for columns.

  • Customizable Connection-lines (colour & size).

  • Fixed wrong calculation of image size.

  • Resolution Independence indent (x & y), visible.

  • Resolution Independence for connecting lines.

  • Resolution Independence for any text and glyphs.

  • Resolution Independent open/close marker (not AQUA).

  • Indentx, yields an inverted tree -> opens toward left.

  • Delete All, converted to delete data, allows watermarking.

On-demand Data Acquisition

The Runtime Library Tree widget has a growing list of callback attributes, most callbacks are used to inform/ gather data for a tree widget, the remaining callbacks are used for interaction purposes.

Gathering Data: 

expandfcn <tree> <node> <typeOf node>

This call back will be called each time a given node is opened. expandfcn is a unconditional call. The call to expandfcn will be invoked whether there are children to node or not. 

requestChildrenfcn <tree> <node> <typeOf node>

Similar to expandfcn. In contrast to expandfcn a requestChildrenfcn call is suppressed if there are any children available for the tree.

the call back is responsible to insert the requested children into the given tree widget. Since the current call is invoked from a started open call back, use the stillInsert action to bring the data to the tree widget (don't use replace / rebuild or similar actions!).

The expandfcn callback is prior to the requestChildrenfcn callback. 

hasChildrenfcn <node> <typeOf node>

The hasChildrenfn will be called foreach node without actual children during drawing this item. The caller must return 1 (true) to tell that this node has children which will be inserted on demand if the node is open. hasChildrenfcn is typically combined with expandfcn and / or requestChildrenfcn.

hasChildrenfcn is the only call back which has to deliver something back to tree widget (0 or 1 for false and true).

Interaction Call backs: 

openfcn <tree> <node> <typeOf node>

The openfcn call back is called to inform the application before invoking the open action. Openfcn is called immediately before expandfcn and requestChildrenfcn. Instead of the later two only user interactions are reported due the openfcn call. 

dragfcn <tree> <canvas widget of tree>
<<target node> <typeOf target>>
<<<dragged node1> <typeOf dragged node1>> <...>>
<relative x position> <relative y position>
<absolute x position> <absolute y position>

Called during dropping multiple nodes onto other nodes in the same tree. The signature receives the single target node and a list of dragged nodes (together with their types). 

selectfcn <tree> <selected nodes> \
            <typeOf last selected node>

Called during the selection of a node, the selected nodes are retrievable using the select property of the tree widget and the delivered type reflects the type of the last selected node. Type may not equal for all selected items. 

contextfcn <tree> <node below pointer>
<absolute x> <absolute y>

The contextfcn is called for a <<Context>> event. You have to add a proper event for the virtual <<Context>> event, to take benefit from it. The node for a context event doesn't need to be part of the current selection; use the select property, if you want to display a context menu for the selected nodes.

To Investigate

With TkPath on Aqua ... ptext assumes wrong font metrics therefore the ptext feature is deactivated under Aqua. ➟ tk windowingysytem

–Reported to Mats and fixed in tkpath 0.3 Will remain disabled, though. Reason: Better for large amounts of nodes! There is another issue with ptext, the created items move unexpectedly under aqua –disable solves this, too –tkpath 0.3.

Minor Notes: Usual Control-1 is used to extend the selection; under aqua this is changed to Command-1.

Window Command

A Window created through the rtl_tree command exposes various functions. Using these functions has the following general form: 

          pathName option ?arg arg ...?

PathName is the same as the window path name. Option and the args determine the exact behavior of the command. The following commands are possible for this window:

pathName cget option

Returns the current value of the configuration option given by option. Option may have any of the values accepted by the rtl_tree command.

pathName configure ?option? ?value option value ...?

Query or modify the configuration options of the window. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no value, then the command returns a list describing the one named option (this list will be identical to the corresponding sublist of the value returned if no option is specified). If one or more option-value pairs are specified, then the command modifies the given window option(s) to have the given value(s); in this case the command returns an empty string. Option may have any of the values accepted by the rtl_tree command.

pathName open v ?conv?

Open the given node »v«–if it does exists– and initiate a »redraw« call to the given part of the rtl_tree. Open / Close can also be called from outside, using the conversion facility.

pathName delete v ?rebuild? ?conv?

Remove a given node complete with its children from the view. Initialize a rebuild when delete was called from outside.

pathName createitem v

Create a new item and reconfigure its parent node. Revision : 01/12/2009, Roger

pathName drawOCNode x y text tags command

Called from »drawOpen« and »drawClosed«. This is the message handler for the open / close indicator. Not called under AQUA.

See fixme (Roger) 01/07/2009 :for AQUA, below.

pathName drawfellow v n nb ?iTag? ?xnow? ?ynow? ?correction?

newly draw the informations following the selected node v, v is never redrawn. --- Extension : Roger 07/05/2007 (Notice) Think about sub-editors for certain 'fellow' maybe best seems to use the option database for those elements... The best place for this function is as part of the 'visible' property -- since these sub-editors should act in response to an event on the designated entry. Maybe triggered by a double-click...

Revision : 05/27/2008, Roger - Resolution independence

pathName unmapChildren v

Walk down the node »v« and remove the visual representation for all its children from the display.

pathName connect vp v x1 y1

Undocumented.

pathName dowhenidle fcn ...

after ilde handling call fcn with args. Note base is insert anywhere. Rewritten : 08/13/2007, Roger -- info behavior under aqua. see also »build«.

pathName startSelection x y

Rubber band selection. The best way to deal with rubber band selection and normal (conflicting) selection is possibly to only initiate the rubber band in cases where no node is part of the rubber band...

pathName replace ...

Replace fractions or all ot the tree’s content.

pathName tswitch v

Used to Open / Close node v, suppress conversion at Open / Close.

pathName dump

Return the cache of the tree’s data.

See also »restore«

pathName opencontext x y rx ry

Create the tree context menu for the item underneath the current position »x, y«. The content of this context menu is defined through the »-contextfcn« call back function, which is called from within »opencontext«.

pathName rebuildwhenidle lid

After idle rebuild the view starting with lid (in stream).

Obsolete, can be replaced with »dowhenidle«.

pathName buildwhenidle

After ilde new build the view.

Obsolete, can be replaced with »dowhenidle«.

pathName nextpos n ?direction? ?xnow? ?ynow?

Append informative entries to the given node v.

pathName dummytext ...

Undocumented.

pathName browse x y ?multi?

The item underneath position »x,y«, is to be selected.

A pending Drag-and-Drop operation might be discarded as a side-effect.

This is the prime selection method. A registered »-selectfcn« call back is called from within »browse«.

pathName deleteAll

Wrapper around »delete all«. Pending for reimplementation, in order to allow watermarks, background gradients and similar stuff originating from gstripes.tcl.

pathName drawselection ?movef?

Display complete selected items with highlight colors.

Changes the selected items foreground color and draws a rectangle around them (behind). Rewritten : 02/03/2009, Roger

pathName drawOpen x y tags command

pathName getItemType v

Deliver information what itemtype was used with this node;

pathName reconnect-stream stream

Each visual node in 'stream' will be reconnected to the tree.

Rewritten : 02/06/2008, Roger

pathName stillInsert v ...

Same as insert, but without a rebuild/build call. The goal is to initialize a complete tree; after this call »build« explicitly.

pathName centerOnX ?offset?

Undocumented.

pathName redrawfellow v ...

This method is used to reconfigure the given information wich are stored as subpart to node v.

pathName close v ?conv?

Close the given node »v«. This is the opposite to the »open« method, see above.

pathName filter node

Filter attributes! The filter mechanism is currently not used.

pathName changeOCNode item image text

Undocumented.

pathName connect-stream stream

Undocumented.

pathName inititem v

Initialize settings for every node displayed in the tree.

pathName motionSelection x y

Rubber band; draw the selection bounding box.

pathName setfocus

Set the input focus to the tree internal canvas window. Set focus is ignored when the current focus is set on a tree child window.

Revision : 02/05/2009, Roger

pathName insert v ...

Insert a new node into the rtl_tree view and initiate a rebuild action. New item attributes -after -before and -index; introduced in Patch level 1.

pathName makename value

Convert value into internal representation. Rewritten : 02/05/2009, Roger

pathName drawClosed x y tags command

pathName unmap v

Hide the given node »v« (this method is called via delete).

pathName replaceUseVar fromVar

Replace fractions or all the content, as defined in the referenced variable »fromVar«.

This variant is faster than »replace«.

pathName tkdrawtext x y text tags ?color? ?correction?

Keeps the Tk canvas text element, even when TkPath is present. This version is preferable over ptext, for memory preservation and also to render multi-line text.

pathName drawtext x y text tags ?color? ?correction?

Undocumented.

pathName restore argl

Replace the entire internal cache, with the given »array« embodied in »argl«.

See also »dump«. Revision : 02/05/2009, Roger

pathName getCurrentTag v

Retrieve the tag identifying the item »v«. In cases of no available tag "glymna" is returned. Rewritten : 02/05/2009, Roger

pathName rubberband c x1 y1 x2 y2 colour

Undocumented.

pathName moveChildren v ymove

Moves the children of node »v« in the distance and direction defined by »ymove«.

This function is used when a section in the middle of the tree has changed and the three parts: Unaffected, new and the moved one are reassembled.

Internal used.

pathName deleteItem v

Remove the tree item »v« from the hierarchy. All child nodes to this item are removed, too.

pathName unmakename value

Reconverts internal name into real name. Rewritten : 02/05/2009, Roger

pathName removefrom elem en

Utility used to maintain various lists. Removes en from list elem, which is part of var.

Internal used.

pathName init

Make initial settings for each component instance.

pathName drawSymbol x y symbol tags ?color?

Undocumented.

pathName draw v x y vparent

draw entry v at position x,y if vparent isn't empty the new item will be connected to its parent node. The new node will create all its child nodes using draw.

Written : 1998, Roger Revision :1999 & 2000, Roger Rewritten :2003 - 2007, Roger - seteach, verified, tkpath and error corrections. Rewritten : 02/06/2008, Roger - drawline instead of create line.

pathName rebuild vp ?movef?

Rebuild is used to setup the treeview past a change. Rebuild attempts to minimize the needed redraw actions.

'vp' is the previous node –not necessarily– the parent node.

To-Do : Extend move operation, use an inverted move operation if the tree is currently manipulated in the top section.

Use the build process when drawing the root-item, required to ensure that root is already drawn.

Note : vp need not to be visible, which means stream does not contain vp Revision : 05/20/2008, Roger – Resolution Independence

pathName moveKey ?key?

Navigate through the hierarchy via keyboard. –Event handler.

pathName build

Brute-force redraw of the entire canvas.

pathName drawDragRectangle c bbox color

Undocumented.

pathName rtl_tree ...

Undocumented.

pathName duplicateItem item ...

pathName drawrect bbox sb tags

Undocumented.

pathName moveItem v level ymove ?chflag?

See also »moveChildren«.

Internal used.

pathName drawline c vp x y y2 x2 combined tags

Undocumented.

pathName releaseSelection x y

Remove the current selection.

pathName opencallback x y

An Open request for the node at position »x, y« has occurred (a double-click).

A registered »-openfcn« call back will be evaluated from within »opencallback«.

pathName invertItem item distance

Used for negative »-indentx« values. The symbol and the name of every node –and leaf– must be altered. This function affects »justify«, »anchor« or »textanchor«.

Dependencies

  • rtl

  • rtl_gridwin

  • rtl_tooltip

Prev Up Next
Rtl_mlistbox Home Rtl_chooseFont
SourceForge Logo Gestalt Items