LICENSE
The contents of this file are subject to the Mozilla Public License Version 1.1 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at "http://www.mozilla.org/MPL/"
Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License.
The Original Code is "dkTreeUtils.pas".
The Initial Developer of the Original Code is Dieter Köhler (Heidelberg, Germany, "http://www.philo.de/"). Portions created by the Initial Developer are Copyright (C) 2003-2007 Dieter Köhler. All Rights Reserved.
Alternatively, the contents of this file may be used under the terms of the GNU General Public License Version 2 or later (the "GPL"), in which case the provisions of the GPL are applicable instead of those above. If you wish to allow use of your version of this file only under the terms of the GPL, and not to allow others to use your version of this file under the terms of the MPL, indicate your decision by deleting the provisions above and replace them with the notice and other provisions required by the GPL. If you do not delete the provisions above, a recipient may use your version of this file under the terms of any one of the MPL or the GPL.
The Tree Utilities Library contains general classes to build a hierarchical list of items, a so-called object tree. The original Delphi VCL classes TTreeNodes and TTreeNode were often too specific for my tasks. When I realized that I was repeatedly implementing special purpose trees which more or less do the same job, it was time to look for a more general approach and to implement basic tree-structure classes, which make it easy to derive new specialized ones. The result of this project is the Tree Utilities Library. The latest version of this software is available at <http://www.philo.de/xml/>.
The Tree Utilities Library does not contain any components to be registered. So using it from inside your own projects is very simple: Add "dkTreeUtils" to the uses clause of your unit and make sure that the path to the location of the dkTreeUtils.pas file is included in Delphi's list of library paths. To include it go to the Library section of Delphi's Environment Options dialog (see the menu item: "Tools/Environment Options ...").
All exceptions raised inside the TreeUtils Library are derived from Delphi's EListError exception.
These strings are used for the error messages of the corresponding exceptions.
TCustomOwnedObject is a simple extension of the TPersistent class for maintaining a set of owned objects. The owner of a newly created TCustomOwnedObject object (if any) is specified in the new object's constructor and is then automatically added to the specified TCustomOwnedObject object's list of owned objects. When a TCustomOwnedObject object is freed, all of its owned objects are (recursively) freed too and it is automatically removed from is owner object's list of owned objects. It is also possible to specify nil as the owner parameter of a node's constructor. In this case the node has no owner node and the application is responsibly of correctly freeing it.
Do not create instances of TCustomOwnedObject. Instead use it to define your own descendant classes. Most of the properties and methods defined in TCustomOwnedObject are protected so that you can choose whether to hide or publish them in your own classes.
Lists all owned object. The first item has an index of 0, the second an index of 1, and so on.
The number of owned objects.
Constructs and initializes an instance of TCustomOwnedObject. If an owner node was specified, the new object is added to the specified owner's list of owned objects.
Parameters:
Destroys an instance of TCustomOwnedObject and removes it from its owner's list of owned objects. Do not call Destroy directly in an application. Instead, call Free. Free verifies that the TCustomOwnedObject reference is not nil, and only then calls Destroy.
Adopts an owned object from another owned object to this owned object, i.e. it changes the owner of the specified owned object.
Parameters:
This procedure (recursively) frees all owned objects and removes them from the list of owned objects.
This procedure is called before a new TCustomOwnedObject is attached as an owned object. By default this method does nothing. Descendant classes can override it to implement specific reactions, for example triggering an event or raising an exception.
Parameters:
This function returns the owner of the given object. If the given node has no owner, nil is returned.
Return Value:
TCustomOwnedNode represents a single node in a tree structure which also maintains a list of sub-nodes. Do not create instances of TCustomOwnedNode. Instead use it to define your own descendant classes. Most of the properties and methods defined in TCustomOwnedNode are protected so that you can choose whether to hide or publish them in your own classes.
The design principle behind the memory management of TCustomOwnedNode is to distinguish between owned nodes and child nodes. Each node can be associated with an owner node in its constructor and contains an ordered list of a (virtually) infinite number of direct child nodes. Each node can only be the child of at most one other node. If a node is the direct child of another node the other node is called "the parent node" of the given node. All direct or indirect parent nodes of a given node are called "its ancestors". This list of child nodes is maintained by the Append(), Insert(), and Remove() methods of the given nodes. Each child node must either have the same owner node as its parent node or the parent node must be identical with the owner node, and an attempt to add a node directly or indirectly as a child node is forbidden.
Each node contains a readonly list of owned nodes which is automatically updated when a node is created with the given node as its owner or if an owned node is freed. When a node is freed, it is removed from its parent node (no matter whether the parent node is readonly or not) and all its child nodes and owned nodes are recursively freed, too. Calling the Clear method of a node recursively frees all of its child nodes (but not the given node itself). It is also possible to specify nil as the owner parameter of a node's constructor. In this case the node has no owner node and the application is responsibly of correctly freeing it.
Indicates the number of nodes maintained by the given node.
The first node maintained by the given node or nil if there is no such node.
Lists all nodes maintained by the given node. The first node has an index of 0, the second an index of 1, and so on. Item is the default property for TCustomOwnedNode. So the name of the Item property can be omitted when indexing into the set of nodes.
Provides access to the list of nodes maintained by the given node.
The last node maintained by the given node or nil if there is no such node.
The node immediately following the given node. If there is no such node, nil is returned.
Lists all owned object. The first item has an index of 0, the second an index of 1, and so on.
The number of owned objects.
The parent of the given node or nil if the given node has no parent.
The node immediately preceding the given node. If there is no such node, nil is returned.
Determines whether the given node is readonly. If the node is readonly any attempt to modify the list of child nodes raises an exception.
Constructs and initializes an instance of TCustomOwnedNode. If an owner node was specified, Create internally calls the AttachNode() procedure of the specified owner node. During creation the Initializing property of the given node is 'true'.
Parameters:
Destroys an instance of TCustomOwnedNode. Before a node is destroyed it is removed from its parent node, then it is cleared, and finally the DetachNode() procedure its owner node (if any) is called. Do not call Destroy directly in an application. Instead, call Free. Free verifies that the TCustomOwnedNode reference is not nil, and only then calls Destroy.
Adopts a node from another owned object to this node, i.e. it changes the owner of the specified node and all of its children to this node. If the source node has a parent it is first removed from the child list of its parent.
Parameters:
Exceptions:
Appends a child node to the end of the list of children for this node. If the new child is already in the tree, it is first removed.
Parameters:
Return Value:
Exceptions:
This procedure is called by other methods of TCustomOwnedNode to check whether the specified node is assigned.
Parameters:
Exceptions:
This procedure is called by other methods of TCustomOwnedNode to check whether the specified nodes are different.
Parameters:
Exceptions:
This procedure is called by other methods of TCustomOwnedNode to check whether the specified node is a child of the given node.
Parameters:
Exceptions:
This procedure is called by other methods of TCustomOwnedNode to check whether the specified node is neither an ancestor of the given node nor the given node itself.
Parameters:
Exceptions:
This procedure is called by other methods of TCustomOwnedNode to check whether the given node is not readonly.
Exceptions:
This procedure is called by other methods of TCustomOwnedNode to check whether the parent node of the specified node is not readonly.
Parameters:
Exceptions:
This procedure is called by other methods of TCustomOwnedNode to check whether the specified node has the same owner as the given node or the given node is the owner of the specified node.
Parameters:
Exceptions:
This procedure (recursively) frees all child nodes and all owned objects.
Exceptions:
This procedure is called by other methods of TCustomOwnedNode after a child node was appended or inserted. By default this method does nothing. Descendant classes can override it to implement specific reactions, for example triggering an event.
Parameters:
This procedure is called by other methods of TCustomOwnedNode after the given node was cleared. By default this method does nothing. Descendant classes can override it to implement specific reactions, for example triggering an event.
This procedure is called by other methods of TCustomOwnedNode after a child node was removed. By default this method does nothing. Descendant classes can override it to implement specific reactions, for example triggering an event.
Parameters:
This procedure is called by other methods of TCustomOwnedNode before a child node is appended or inserted. By default this method does nothing. Descendant classes can override it to implement specific reactions, for example triggering an event.
Parameters:
This procedure is called by other methods of TCustomOwnedNode before the given node is cleared. By default this method does nothing. Descendant classes can override it to implement specific reactions, for example triggering an event.
This procedure is called by other methods of TCustomOwnedNode before a child node is removed. By default this method does nothing. Descendant classes can override it to implement specific reactions, for example triggering an event.
Parameters:
This function is called by the Count property to get the number of child nodes maintained by the given node.
Return Value:
This function is called by the FirstChild property to get the first node maintained by the given node or nil if there is no such node.
Return Value:
This function is called by the LastChild property to get the last node maintained by the given node or nil if there is no such node.
Return Value:
This function is called by the NextSibling property to get the node immediately following the given node. If there is no such node, nil is returned.
Return Value:
This function returns the owner of the given node. If the given node has no owner, nil is returned.
Return Value:
This function is called by the Parent property to get the parent of the given node. If the given node has no parent, nil is returned.
Return Value:
This function is called by the PreviousSibling property to get the node immediately preceding the given node. If there is no such node, nil is returned.
Return Value:
This function is called by the ReadOnly property to determine whether the given node is readonly.
Return Value:
This is a convenience method to allow easy determination of whether a node is an ancestor of this node.
Parameters:
Return Value:
This is a convenience method to allow easy determination of whether the given node has any child nodes.
Return Value:
Returns the index of the specified node in the Items list.
Parameters:
Return Value:
Inserts the node NewChild before the existing child node RefChild. If RefChild is nil, NewChild is inserted at the end of the list of children.
Parameters:
Return Value:
Exceptions:
Raises an exception of the specified class. Descendants may override this procedure to implement specific exception handling, for example to raise a different exception than the specified.
Parameters:
Removes the child node indicated by OldChild from the list of children and returns it.
Parameters:
Return Value:
Exceptions:
Replaces the child node OldChild with NewChild in the set of children of the given node, and returns the OldChild node. If NewChild is already in the tree, it is first removed.
Parameters:
Return Value:
Exceptions:
This procedure is called by the ReadOnly property to specify whether the given node is readonly.
Parameters: