|
|
Gestalt Items |
Copyright © 2008, 2009 Arndt Roger Schneider
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.
See the options manual entry for details on the standard options.
-select option. Set and get current selection.
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 /.
The default »-type« for rtl_tree items. The »-type« property can be omitted for the default type.
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.
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).
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).
Boolean value, defines that each child node is visually connected with its parent node.
Call back command, this Tcl-script is called whenever a context menu is displayed, posted.
format string, defines the text format for each node name. Default value is »%s«, the node name.
Boolean value, nodes can be selected by clicking on their attributes.
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.
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.
Call back command, the script »-selectfcn« is whenever a node or leaf is selected.
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 >
Boolean value, activates drag-and-drop inside the rtl_tree window.
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
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.
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«.
Boolean value, disallow the multi selection for items of different type.
Set where the scrollbars are inserted.
Possible values are: »top«, »bottom«, »left«, »right« and combinations thereof.
The scrollbar’s width dimension.
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
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!
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.
The rtl_tree component provides two building processes, build and rebuild.
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).
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.
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.
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.
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:
Returns the current value of the configuration option given by option. Option may have any of the values accepted by the rtl_tree command.
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 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.
Remove a given node complete with its children from the view. Initialize a rebuild when delete was called from outside.
Create a new item and reconfigure its parent node. Revision : 01/12/2009, Roger
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.
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
Walk down the node »v« and remove the visual representation for all its children from the display.
after ilde handling call fcn with args. Note base is insert anywhere. Rewritten : 08/13/2007, Roger -- info behavior under aqua. see also »build«.
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 fractions or all ot the tree’s content.
Used to Open / Close node v, suppress conversion at Open / Close.
Return the cache of the tree’s data.
See also »restore«
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«.
After idle rebuild the view starting with lid (in stream).
Obsolete, can be replaced with »dowhenidle«.
After ilde new build the view.
Obsolete, can be replaced with »dowhenidle«.
Append informative entries to the given node v.
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«.
Wrapper around »delete all«. Pending for reimplementation, in order to allow watermarks, background gradients and similar stuff originating from gstripes.tcl.
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
Deliver information what itemtype was used with this node;
Each visual node in 'stream' will be reconnected to the tree.
Rewritten : 02/06/2008, Roger
Same as insert, but without a rebuild/build call. The goal is to initialize a complete tree; after this call »build« explicitly.
This method is used to reconfigure the given information wich are stored as subpart to node v.
Close the given node »v«. This is the opposite to the »open« method, see above.
Filter attributes! The filter mechanism is currently not used.
Initialize settings for every node displayed in the tree.
Rubber band; draw the selection bounding box.
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 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.
Convert value into internal representation. Rewritten : 02/05/2009, Roger
Hide the given node »v« (this method is called via delete).
Replace fractions or all the content, as defined in the referenced variable »fromVar«.
This variant is faster than »replace«.
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.
Replace the entire internal cache, with the given »array« embodied in »argl«.
See also »dump«. Revision : 02/05/2009, Roger
Retrieve the tag identifying the item »v«. In cases of no available tag "glymna" is returned. Rewritten : 02/05/2009, Roger
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.
Remove the tree item »v« from the hierarchy. All child nodes to this item are removed, too.
Reconverts internal name into real name. Rewritten : 02/05/2009, Roger
Utility used to maintain various lists. Removes en from list elem, which is part of var.
Internal used.
Make initial settings for each component instance.
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 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
Navigate through the hierarchy via keyboard. –Event handler.
Brute-force redraw of the entire canvas.
Internal used.
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«.
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«.