TmsTreeView component

| Version 1.0.068 (Last modified December 22, 2006) |

 
 
 

Copyright © mSunSoftware. 2006.
All rights reserved.

E-mail: support@msunsoftware.com
Web: http://www.msunsoftware.com

 
 
 
 
Home english | russian
 
 
 
 

Contents


 
 

Description

The component TmsTreeView has more features than the standard VCL component TTreeView. The component supports: Cut/ Copy/ Paste operations, searching and sorting functions, drag-and-drop operations, errors handler, hot keys for the basis operations, advanced nodes editor (at designtime) and many other functions. It is for the development of the Windows-Applications Interface. List of items consist from the objects, which are the childclasses TmsBaseTreeNode - TmsTreeNode. TmsTreeView has a child - TmsDBTreeView to connect with data.


 
 

Hierarchy

TObject
       |
TPersistent
       |
TComponent
       |
TControl
       |
TWinControl
       |
TmsBaseTreeView
       |
TmsCustomTreeView
       |
TmsTreeView


 
 

Class TmsTVOptions

Properties

  • property AutoSort: Boolean;
    It shows if the tree nodes will be sorted automatically.
    Description:
    If AutoSort is true then the tree nodes will be sorted automatically; if AutoSort is false the tree nodes won't be sorted.
  • property AutoDrag: Boolean;
    It shows if the drag-and-drop process will be fulfilled automatically.
    Description:
    Disable the drag-and-drop capability at runtime by setting the AutoDrag property value to false. Enable automatic dragging by setting AutoDrag to true.
  • property SortDirection: TmsSortDirection;
    It shows the direction of the tree nodes sorting.
    Description:
    If SortDirection is sdAlphabeticOrder then the tree nodes will be sorted in the alphabetic order; if SortDirection is sdInvertedOrder in the inverted alphabetic order.
    Values:
      Parameter Description
      sdAlphabeticOrder sorting in the alphabetic order
      sdInvertedOrder sorting in the inverted alphabetic order

Methods

  • constructor Create(ATreeView: TmsCustomTreeView); virtual;
    Creates and initializes a new TmsTVOptions object.
  • procedure Assign(Source: TPersistent); override;
    Copies the data from the Source to object TmsTVOptions.

 
 

Class TmsTVShortCuts

Properties

  • property scAddNode: TShortCut;
    Use these short keys to execute an operation of the tree node adding.
  • property scDeleteNode: TShortCut;
    Use these short keys to execute an operation of the tree node deleting.
  • property scCutNode: TShortCut;
    Use these short keys to execute an operation of the tree node cutting.
  • property scCopyNode: TShortCut;
    Use these short keys to execute an operation of the tree node copying.
  • property scPasteNode: TShortCut;
    Use these short keys to execute an operation of the tree node pasting.
  • property scFindNode: TShortCut;
    Use these short keys to execute an operation of the tree node searching.
  • property scEditNode: TShortCut;
    Use these short keys to execute an operation of the tree node label editing.

Methods

  • constructor Create; virtual;
    Creates and initializes a new TmsTVShortCuts object.
  • procedure Assign(Source: TPersistent); override;
    Copies the data from the Source to object TmsTVShortCuts.

 
 

Class TmsTreeNode

Methods

  • destructor Destroy; override;
    Frees the memory associated with the TmsTreeNode object.
  • procedure AssignChildNodes(Source: TmsBaseTreeNode); virtual;
    It copies all the child nodes of the Source into the node Self.
    Description:
    Use the AssignChildNodes method to copy the child nodes of the Source into the node Self. For every coping node the Assign method is called.
  • procedure MoveTo(Destination: TmsBaseTreeNode; Mode: TNodeAttachMode); override;
    Moves the node Self to another location in a tree view control.
    Description:
    Use the MoveTo method for moving the node Self into the new position. After moving the node, the MoveTo method calls the TreeView.SortSubTree method, which fulfills the local sorting of the nodes on the level Self.Parent.Level-1 (if the TVOptions.AutoSort property is true).

 
 

Class TmsTreeNodes

Methods

  • function AddNode(Node, Relative: TmsBaseTreeNode; const S: string; Ptr: Pointer; Method: TNodeAttachMode): TmsBaseTreeNode; override;
    Adds a new node to a tree view control.
    Description:
    Use the AddNode method to add a new node into a tree view control. If the process completed successfully, then the AddNode method calls the TreeView.SortSubTree method, which fulfills the local sorting of the nodes on the level Self.Parent.Level-1 (if the TVOptions.AutoSort property is true).
    Note:

    Besides to add a new node, you can use the following methods: Add, AddFirst, Insert, AddChild, AddChildFirst, AddObject, AddObjectFirst, InsertObject, AddChildObject, AddChildObejectFirst.

 
 

Class TmsCustomTreeView - TmsTreeView

Properties

  • property BufferedNode: TmsBaseTreeNode;
    Points to the copied or cut node.
    Description:
    BufferedNode points to the last cut node or copied node. If BufferedNode is nil, there aren't copied or cut nodes and it's impossible to insert the node.
  • property SearchNodeParams: TmsSearchNodeParams;
    Search nodes parameters.
    Description:
    SearchNodeParams includes the search nodes parameters. You can initialize the properties of the given structure in the OnBeforeSearchNode event handler.
    Values:
      Field Description
      Text: string a text of the searching node
      MatchCase: Boolean it's necessary strings match case
      PartialStringMatch: Boolean could be partial string match
      Direction: TmsSearchDirection direction of the searching (forward, upward)
  • property TVOptions: TmsTVOptions;
    Specifies TreeView options.
    Description:
    Look the description of the class TmsTVOptions properties here.
  • property TVShortCuts: TmsTVShortCuts;
    Specifies short keys for TreeView.
    Description:
    Look the description of the class TmsTVShortCuts properties here.

Methods

  • constructor Create(AOwner: TComponent); override;
    Creates and initializes a new TmsTreeView object.
  • destructor Destroy; override;
    Frees the memory associated with the TmsTreeView object.
  • procedure AddNode(AParent: TmsBaseTreeNode = nil); dynamic;
    Adds a new node to a tree view control.
    Description:
    Use the method AddNode to add a new node into a tree view control. If AParent is nil, then a new node will be added as the last child node of the Selected node or as the last child node of the AParent node. After adding the new node it becomes selected and its label can be edited.
    Note:
    If TreeView property ReadOnly is true, you can't add a new node, in this case the SEditTreeError error will be generated.
    Recomendations:
    Best of all, use this method in the event handlers of the menu items and the buttons for rapid adding a new node in TreeView.
  • procedure DeleteNode(ANode: TmsBaseTreeNode = nil); dynamic;
    Deletes a node.
    Description:
    Use the DeleteNode method to delete the node. If ANode is nil, then the Selected node will be deleted, otherwise, ANode will be deleted. If no node's selected and ANode is nil, the error SUnableToSelectNode will be generated.
    Note:
    If TreeView property ReadOnly is true, you can't delete the node, in this case the SEditTreeError error will be generated.
    Recomendations:
    Best of all, use this method in the event handlers of the menu items and the buttons for rapid deleting the node from TreeView.
  • procedure CutNode(ANode: TmsBaseTreeNode = nil); dynamic;
    Cuts a node.
    Description:
    Use the CutNode method to cut the node. If ANode is nil, then the Selected node will be cut, otherwise, ANode will be cut. If no node's selected and ANode is nil, the error SUnableToSelectNode will be generated. This method initializes the BufferedNode property (the given property points to the last cut node or copied node). Also, the CutNode method generates an OnCutting event (in this event handler you can cancel the executing operation, in this case the SCutNodeError error will be generated).
    Note:
    If TreeView property ReadOnly is true, you can't cut the node, in this case the SEditTreeError error will be generated.
  • procedure CopyNode(ANode: TmsBaseTreeNode = nil); dynamic;
    Copies a node.
    Description:
    Use the CopyNode method to copy the node. If ANode is nil, then the Selected node will be cut, otherwise, ANode will be cut. If no node's selected and ANode is nil, the error SUnableToSelectNode will be generated. This method initializes the BufferedNode property (the given property points to the last cut node or copied node). Also, the CopyNode method generates an OnCoping event (in this event handler you can cancel the executing operation, in this case the SCopyNodeError error will be generated).
    Note:
    If TreeView property ReadOnly is true, you can't copy the node, in this case the SEditTreeError error will be generated.
  • procedure PasteNode(ATargetNode: TmsBaseTreeNode = nil); dynamic;
    Pastes a node.
    Description:
    Use the PasteNode method to paste the node. If ATargetNode is nil, then the copied or cut node will be inserted to Selected node, otherwise, will be inserted to ATargetNode. You can't insert the Node into itself, in this case the InsertNodeErrorEx error will be generated. PasteNode inserts the Node with all its child nodes. After successful executing of the operation the pasted node becomes selected and expanded. The PasteNode method generates an OnInserting event (in this event handler you can cancel the executing operation, in this case the SInsertNodeError error will be generated).
    Note:
    If TreeView property ReadOnly is true, you can't paste the node, in this case the SEditTreeError error will be generated.
  • procedure EditNode(ANode: TmsBaseTreeNode = nil); dynamic;
    Sets a node label to edit mode.
    Description:
    Uses the EditNode method to begin edit the node label. If the ANode parameter is nil, then the Selected node label will be set to edit mode, otherwise, ANode label will be set to edit mode. If no node's selected and ANode is nil, the error SUnableToSelectNode will be generated.
    Note:
    If TreeView property ReadOnly is true, you can't edit the node label, in this case the SEditTreeError error will be generated.
  • procedure SelectNode(Node: TmsBaseTreeNode; EditText, Expand: Boolean); dynamic;
    Selects a node, sets a node label to edit mode, expands or collapses a node.
    Description:
    Use the SelectNode method to select a Node. If EditText is true, then the node label is being set in the edit mode, if Expand is true, then the node expands or collapses.
  • procedure InitSearchParams;
    Initializes the start parameters of the search.
    Description:
    Use the InitSearchParams method for initialization the start parameters of the search. The InitSearchParams method generates an OnBeforeSearchNode event (in this event handler you should to initialize the properties of the SearchNodeParams structure). The search begins from the selected node. If no node's selected, the error SUnableToSelectNode will be generated, and the search doesn't start.
  • function FindNextNode: TmsBaseTreeNode;
    Fulfils the search of the next node according parameters SearchNodeParams structure.
    Description:
    Use the FindNextNode method for the search of the next node. The search fulfils from the last found node. In case of the successful search the method returns the found node. The method returns nil, if all the nodes were looked through or no one node match the search parameters. The FindNextNode generates an OnSearchingNode event every time when it selects the next node (in this event handler you can write additional code of testing, its result you should to appropriate to the Accept parameter).
  • function SortSubTree(Node: TmsBaseTreeNode; ARecurse: Boolean = false): Boolean;
    Sorts the child nodes of the Node.
    Description:
    Use the SortSubTree method for sorting the child nodes of the Node. If ARecurse is false, then the nodes are being sorted, which are the children nodes of the Node, otherwise, the method is been called for all the child nodes.
  • function SortTreeNodes(ARecurse: Boolean = false): Boolean;
    Sorts the tree nodes.
    Description:
    Use the SortTreeNodes method for sorting of the tree nodes. If ARecurse is false, then the nodes are being sorted, which are the root nodes (they have Parent = nil), otherwise, all the subtrees are being sorted.

Events

  • TmsTVCuttingEvent = procedure(Sender: TObject; Node: TmsBaseTreeNode; var AllowCut: Boolean) of object;
    property OnCutting: TmsTVCuttingEvent;
    property OnCopying: TmsTVCuttingEvent;

    Occurs when the user cuts or copies a node.
    Description:
    Use an OnCutting event handler to add additional code in time of the cutting or copying a node. The Node parameter points to the copied or cut node. Set the AllowCut parameter to false to prevent the executing of the operation.
  • TmsTVInsertingEvent = procedure(Sender: TObject; BuffedNode, TargetNode: TmsBaseTreeNode; var AllowPaste: Boolean) of object;
    property OnInserting: TmsTVInsertingEvent;

    Occurs when the user inserts a node.
    Description:
    Use an OnInserting event handler to add additional code in time of the inserting a node. The BufferedNode parameter points to the copied or cut node, the TargetNode parameter points to the target node. Set the AllowPaste parameter to false to prevent the executing of the operation.
  • TmsTVProcessErrorEvent = procedure(Sender: TObject; Msg: string) of object;
    property OnProcessError: TmsTVProcessErrorEvent;

    Occurs when the error appears.
    Description:
    Use an OnProcessError event handler to choose a way of informing about the error. The Msg parameter is a description of the error.
  • TmsTVBeforeSearchNodeEvent = procedure(Sender: TObject; var SearchNodeParams: TmsSearchNodeParams) of object;
    property OnBeforeSearchNode: TmsTVBeforeSearchNodeEvent;

    Occurs when the user starts the search.
    Description:
    Use an OnBeforeSearchNode event handler for initialization the start parameters of the search. In this event handler you should to initialize the properties of the SearchNodeParams structure.
  • TmsTVSearchingNodeEvent = procedure(Sender: TObject; Node: TmsBaseTreeNode; var Accept: Boolean) of object;
    property OnSearchingNode: TmsTVSearchingNodeEvent;

    Occurs every time when the next node is being selected in the progress of the searching.
    Description:
    Use an OnSearchingNode event handler for the additional testing of the node. The Node parameter points to the current selected node. The Accept parameter shows if the node satisfies the search parameters or not (default value Accept = the result of the comparing in FindNextNode method).

 

Copyright © mSunSoftware. 2006. All rights reserved.