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.


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.


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.


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.


Description

Figure 3.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!

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).


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).

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.

Window Command

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

(option object ?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:

(cget object :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.

(configure object ?: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.

(open object 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.

(delete object v ?rebuild? ?conv? )

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

(createitem object v )

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

(drawOCNode object 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.

(drawfellow object 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

(unmapChildren object v )

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

(connect object vp v x1 y1 )

Undocumented.

(dowhenidle object 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«.

(startSelection object 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...

(replace object ... )

Replace fractions or all ot the tree’s content.

(tswitch object v )

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

(dump object )

Return the cache of the tree’s data.

See also »restore«

(opencontext object 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«.

(rebuildwhenidle object lid )

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

Obsolete, can be replaced with »dowhenidle«.

(buildwhenidle object )

After ilde new build the view.

Obsolete, can be replaced with »dowhenidle«.

(nextpos object n ?direction? ?xnow? ?ynow? )

Append informative entries to the given node v.

(dummytext object ... )

Undocumented.

(browse object 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«.

(deleteAll object )

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

(drawselection object ?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

(drawOpen object x y tags command )

(getItemType object v )

Deliver information what itemtype was used with this node;

(reconnect-stream object stream )

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

Rewritten : 02/06/2008, Roger

(stillInsert object v ... )

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

(centerOnX object ?offset? )

Undocumented.

(redrawfellow object v ... )

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

(close object v ?conv? )

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

(filter object node )

Filter attributes! The filter mechanism is currently not used.

(changeOCNode object item image text )

Undocumented.

(connect-stream object stream )

Undocumented.

(inititem object v )

Initialize settings for every node displayed in the tree.

(motionSelection object x y )

Rubber band; draw the selection bounding box.

(setfocus object )

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

(insert object 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.

(makename object value )

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

(drawClosed object x y tags command )

(unmap object v )

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

(replaceUseVar object fromVar )

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

This variant is faster than »replace«.

(tkdrawtext object 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.

(drawtext object x y text tags ?color? ?correction? )

Undocumented.

(restore object argl )

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

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

(getCurrentTag object v )

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

(rubberband object c x1 y1 x2 y2 colour )

Undocumented.

(moveChildren object 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.

(deleteItem object v )

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

(unmakename object value )

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

(removefrom object elem en )

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

Internal used.

(init object )

Make initial settings for each component instance.

(drawSymbol object x y symbol tags ?color? )

Undocumented.

(draw object 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.

(rebuild object 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

(moveKey object ?key? )

Navigate through the hierarchy via keyboard. –Event handler.

(build object )

Brute-force redraw of the entire canvas.

(drawDragRectangle object c bbox color )

Undocumented.

(rtl_tree object ... )

Undocumented.

(duplicateItem object item ... )

(drawrect object bbox sb tags )

Undocumented.

(moveItem object v level ymove ?chflag? )

See also »moveChildren«.

Internal used.

(drawline object c vp x y y2 x2 combined tags )

Undocumented.

(releaseSelection object x y )

Remove the current selection.

(opencallback object 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«.

(invertItem object 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«.