From 04381be2cc4cbc151fc49b393aed8c0a45acfdd4 Mon Sep 17 00:00:00 2001 From: dsiders Date: Mon, 12 Jun 2023 01:10:56 +0100 Subject: [PATCH] Docs: LCL/comctrls. Updates content in TTreeNode topics (various). --- docs/xml/lcl/comctrls.xml | 883 +++++++++++++++++++++++++++++++------- 1 file changed, 738 insertions(+), 145 deletions(-) diff --git a/docs/xml/lcl/comctrls.xml b/docs/xml/lcl/comctrls.xml index 3f3c4ae1c3..f3d1d3629a 100644 --- a/docs/xml/lcl/comctrls.xml +++ b/docs/xml/lcl/comctrls.xml @@ -28168,60 +28168,87 @@ procedure. -DefaultTreeViewSort - returns result of string comparison between -names of Node1 and Node2 +Default routine used to returns a numeric value with the sort order for the +specified tree nodes.

-DefaultTreeViewSort - returns result of string comparison between -names of Node1 and Node2. +DefaultTreeViewSort is the default routine used to compare tree +nodes to determine their sort order. DefaultTreeViewSort is used in the +CustomSort method when a another comparison routine has not been specified in +the argument for the method. It is passed as an argument to the Sort routine +in the implementation section for the unit.

-DefaultTreeViewSort compares the text of two TreeNodes and returns -the following result: +DefaultTreeViewSort checks for an assigned OnCompare event handler in the +TreeView control for the nodes. When assigned, it is signalled to compare the +specified nodes to determine the return value for the method. If TreeView or +its OnCompare handler have not been assigned, the text for the nodes in Node1 +and Node2 are compared to get the return value. The return values contains +the following:

< 0
-
if Node1.Text<Node2.Text.
+
+Node1.Text occurs before Node2.Text in the sort order. +
0
-
if Node1.Text=Node2.Text.
+
+Node1.Text and Node2.Text have the same value in the sort order. +
> 0
-
if Node1.Text>Node2.Text.
+
+Node1.Text occurs after Node2.Text in the sort order. +

-The comparison takes into account ANSI characters, i.e. it takes care of -strange accented characters. Contrary to AnsiCompareText, the comparison is -case sensitive. +On UNIX-like platforms, the CompareStr routine is called to compare the values +for the Text in the nodes. The comparison is case-sensitive. All other +platforms call the AnsiCompareStr routine to compare the Text values. +AnsiCompareStr handles ANSI characters which include accented characters. The +comparison is case-sensitive.

- + + + + + - + +Numeric value with the relative sort order for the compared nodes. + - + +Tree node compared in the method. + - + +Tree node compared in the method. + -DisplayExpandSignLeft - returns the position of the left edge of -the expand / collapse indicator. +Returns the position for the left edge of the expand / collapse indicator. - + +Horizontal coordinate where the left edge of the expand / collapse indicator +is located. + -DisplayExpandSignRect - returns the coordinates of the rectangle -within which the expand sign are displayed. +Returns the coordinates for the rectangle within which the expand / collapse +indicator is displayed. @@ -28234,8 +28261,8 @@ Rectangle with the display area for the expand / collapse indicator. -DisplayExpandSignRight - returns the position of the right edge of -the expand sign (i.e. takes into account the width of the icon etc). +Returns the position for the right edge of the expand / collapse indicator +(accounting for the width of the icon, etc.). @@ -28248,65 +28275,179 @@ Rectangle with the display area for the expand / collapse indicator. -DisplayIconLeft - returns the position of the actual icon for the -expand sign (usually 1 pixel greater than DisplayExpandSignLeft). +Returns the horizontal position for the left edge of the icon displayed for +the tree node. - + +

+The return value accounts for the state icon displayed when StateImages have +been assigned in the TreeView control and StateImageIndex is a valid position +in the image list. The return value is adjusted for the scaled width for the +state image and the default item spacing used on the TreeView control. +

+ - + +Horizontal coordinate where the left edge of the icon for the node is +displayed. + -DisplayRect - returns the coordinates of the rectangle containing -the current entry; if TextOnly is True, returns the -coordinates for the text. +Returns the rectangle where the tree node is displayed on its TreeView control. - - + +

+DisplayRect returns the coordinates for rectangle containing +the content for the tree node. The Left, Top, Right, and Bottom members in the +return value are adjusted for the BorderWidth used on the TreeView control for +the node. +

+

+When TextOnly is set to True, the return value contains the +coordinates where the text for the node is located on the TreeView control. +The Left and Right members in the rectangle are set to the values returned +from the DisplayTextLeft and DisplayTextRight methods. +

+

+The return value contains an empty rectangle (with all members set to 0) if +TreeView has not been assigned for the node. +

+

+DisplayRect is called from methods that include: +

+
    +
  • TCustomTreeview.DoPaintNode
    • +
  • TCustomTreeview.GetInsertMarkAt
    • +
+ + + + + +TRect + - + +TRect instance where the tree node is displayed on its tree view control. + - + +Set to True if the rectangle should contain the display area for its +Text only. + -DisplayStateIconLeft - returns the position of the State Icon. +Returns the horizontal position for the left edge of the State icon on the +tree node. - - + +

+The return value is set to the return value from the DisplayExpandSignRight +method. +

+ + + + - + +Horizontal position for the left edge of the State icon on the tree node. + -DisplayTextLeft - returns the position of the left edge of the -text. +Returns the position for the left edge of the text on the tree node. - - + +

+DisplayTextLeft is a method used to determine the horizontal +coordinate where the Text for the tree node is displayed. If a TCustomTreeview +instance has not been assigned in the tree node, the return value contains the +result from the DisplayIconLeft method. +

+

+Values from the Images and GetImageSize in the TreeView control are used (when +assigned) to adjust the left edge for the Text display area. If an image +position has been assigned in ImageIndex or SelectedIndex, the left edge is +increased by the image size and the default item spacing on the TreeView +control. +

+

+DisplayTextLeft is used in TTreeNode methods like DisplayRect and +DisplayTextRight. It is also used in TCustomTreeView methods including +BeginEditing, GetHitTestInfoAt, and MouseDown. +

+ + + + + + + + + + + + + + + - + +Horizontal coordinate where the Text for the tree node is located. + -DisplayTextRight - returns the position of the right edge of the -text. +Returns the horizontal position for the right edge of the Text on the tree +node. - - + +

+DisplayTextRight is a method used to determine the horizontal +coordinate for the right-hand edge of the Text displayed for the tree node. If +a TCustomTreeview instance has not been assigned in the tree node, the return +value contains the result from the DisplayTextLeft method. Otherwise, the +position is calculated using the left-hand edge for the Text, the width +returned from the TextWidth method in the control Canvas, and padding derived +from the Indent used on the TreeView control. +

+

+DisplayTextRight is used in the DisplayRect method in TTreeNode. It is also +used in TCustomTreeView methods including GetNodeAt, GetNodeWithExpandSignAt, +GetHitTestInfoAt, and MouseDown. +

+ + + + + + + + + + + +TCustomControl.Canvas +TCanvas.TextWidth + - + +Horizontal coordinate where the Text for the tree node ends. + @@ -28425,7 +28566,7 @@ first (or only) node at the current Level.

When a Parent node has been assigned, its GetFirstChild method is used to get the return value. Otherwise, the internal linked list -for the sub-tree is used to get the previous tree node as the return value. +for the subtree is used to get the previous tree node as the return value.

@@ -28487,11 +28628,13 @@ Gets the value for the Handle property.

GetHandle is a THandle function used to get the value for the Handle -property. It is the Handle allocated for the associated TreeView control. +property. It is the Handle allocated for the associated TreeView control, or +zero (0) if the TreeView property has not been assigned for the node.

+ @@ -28500,35 +28643,56 @@ property. It is the Handle allocated for the associated TreeView control. -Gets the last node that is a top-level child node in the subtree. +Gets the last tree node that is a top-level child node in Items. -TTreeNode instance that is the list node in Items. + +TTreeNode instance that is the list node in Items, or Nil if no child +nodes are found. + Gets the last node at the same level as the current node. - + +

+If Parent has been assigned, the return value is set to the last child node in +the Items for the Parent node. If the node is a top-level node (where Parent +is unassigned), the value from GetNextSibling is used. The return value is +Nil if a sibling node is not found for the current tree node. +

+ - + +Last TTreeNode instance at the same level as the current node, or Nil +if a sibling node is not found. + -GetLastSubChild - returns the last sub-child node of this parent. +Returns the last child node or its last descendent node. - + +

+This provides access to the tree node at the deepest level for the node +subtree. +

+ - + +TTreeNode for the last child or its last descendent, or Nil when child +nodes are not found in Items. + @@ -28540,106 +28704,198 @@ Gets the last child node in Items with its Visible property set to - + +Last visible node in Items, or Nil when child nodes are not found or +visible. + -Gets the last child for the current node which is visible and enabled. +Gets the last child for the current node which is both visible and enabled. - + + + + + + - + +Last child tree node with the required settings, or Nil when a visible +and enabled child node is not found. + -Gets the next node in the tree. +Gets the next node in the tree hierarchy. - - + +

+Calls GetFirstChild to begin the search for the next tree node in the +hierarchy. If a child node is not found, the GetNextSkipChildren method is +called to locate the next sibling node in the tree. +

+ + + + + - + +TTreeNode that is a child or sibling of the current node, or Nil when +neither condition is satisfied. + -GetNextChild - returns the next child node of the parent specified -by AValue. +Returns the next child node for the parent node specified in AValue. - - + +

+Calls GetNextSibling to get the return value for the method. Returns +Nil if AValue has not been assigned. +

+ + + + - + +TTreeNode which is the first child node in the specified parent, or Nil +when a node is not assigned to AValue. + - + +Tree node examined to locate its first child node. + -GetNextExpanded - returns the next expanded node. +Returns the next expanded node in the tree node hierarchy. - + +

+Calls GetFirstVisibleChild to start the search for the next expanded tree +node. If the node is assigned and its Expanded property is set to True, +it is used as the return value for the method. If a child node is not found, +the Parent node is searched for a visible sibling node. The return value is +Nil if neither condition is satisfied. +

+ - + +Tree node which is the next expanded child or sibling for the node, or +Nil when a visible and expanded node is not not found. + -Gets the next child or sibling node that is expanded and enabled. +Gets the next child or sibling tree node that is both expanded and enabled. - + + + + + + + - + +TTreeNode instance that satisfies the condition, or Nil when a node is +not found. + -GetNextMultiSelected - returns the next node in a multi-selection. +Returns the next tree node which is included in a multi-selected range of +nodes. - - + +

+The internal members with the values for GetPrevMultiSelected and +GetNextMultiSelected are updated when the value in the MultiSelected property +is changed for the node. +

+ + + + + + + + - + +Next tree node in the list of multi-selected nodes, or Nil when +multi-selections are not present or enabled in the tree view control for the +node(s). + -GetNextSibling - returns the next node in the same level as the -current node. +Returns the next node in the tree hierarchy at the same level as the current +node. - - + +

+The internal member with the return value for the method is updated when the +MoveTo method is called for the tree node. This occurs when the value in Index +is modified. It is also updated when methods in TTreeNode are called to add or +insert a tree node into the node list. +

+ + + + + + + + + + - + +TTreeNode instance which is the next node at the same level as the current node, or Nil if no other nodes are stored at the same level in the +Parent. + -Gets the next sibling node for the current tree node, or Nil when a -sibling does not exist. +Gets the next sibling for the current tree node, or Nil when a sibling +node does not exist. - + +TTreeNode instance which is the next sibling for the current node, or Nil if a +sibling node does not exist. + -Gets the next visible node. +Gets the next visible node child or sibling for the current node.

@@ -28661,7 +28917,7 @@ preceding logic, or when none of the ancestor nodes are visible and expanded. -Next node in the tree node navigation order, or Nil. +Next visible node in the tree node navigation order, or Nil. @@ -28681,23 +28937,60 @@ Child or sibling tree node, or Nil when not enabled and visible. -Gets the next visible node at the same level in the tree. +Gets the next visible node at the same level in the node tree. +

+GetNextVisibleSibling is a TTreeNode function used to +locate the next sibling node that has its Visible property enabled. A sibling +node is one which exists at the same Level as the current node in the node +hierarchy; in other words, it is one of the child nodes in the Parent for the +current node. +

+

+GetNextVisibleSibling calls GetNextSibling to start the search for a visible +sibling node. The node is used in the return value when its Visible property +is set to True. The return value is Nil if there are no sibling +nodes after the current node, or a visible sibling node was not found. +

+

+GetNextVisibleSibling is used in TTreeNode methods like BottomExpanded, +GetNextVisible, GetNextExpanded, and GetFirstVisibleChild. It is also called +from methods like TTreeNodes.MultiSelect and TCustomTreeview.DoPaintNode when +a tree node is selected or drawn on the TreeView control. +

 - + + + + + + + + + + + - + +Next visible sibling node in the tree hierarchy, or Nil when a sibling +node is not found. + -Gets the next sibling node that is visible and enabled. + +Gets the next sibling node that is both visible and enabled. + - + +Next visible and enabled sibling node in the tree hierarchy, or Nil +when a sibling node is not found. + @@ -28717,7 +29010,7 @@ this absolute level. -Gets the previous node in the tree. +Gets the previous node in the tree hierarchy. @@ -28874,14 +29167,46 @@ Modified in LCL version 2.4 to use the PathDelimiter in TCustomTreeView. Returns True if the specified node is a parent for the current node. - - + +

+HasAsParent is Boolean function which indicates whether +the tree node specified in AValue is an ancestor of the current +tree node. +

+

+The return value is True if AValue is the Parent node for the current +class instance. Preceding Parent nodes in the hierarchy are also searched if +needed by calling their HasAsParent method, and the return value is set to +True if any one of them is the node in AValue. +

+

+The return value is set to False when a node is encountered and its +Parent node has not been assigned. +

+

+Strangely enough, the method also returns True if AValue is unassigned +(Nil). +

+

+HasAsParent is called from the MoveTo method and used to enable or disable +change event handlers in the TreeView control when a node is relocated in the +node hierarchy. +

+ + + + - + +True if the specified node is ancestor of the current tree node (also +when the ancestor node is not specified). + - + +Parent node to locate in the ancestor nodes for the class instance. + @@ -28910,14 +29235,32 @@ Ordinal position for the specified child node, or -1 when not a child node. -IndexOfText - returns the index of the node containing the -specified Text string. +Returns the ordinal position for the last child node containing the specified +Text. - - + +

+IndexOfText searches the child nodes in Items to locate a node with +the text specified in the NodeText argument. A case-sensitive comparison is +performed using the equality operator (=). The child nodes are searched in +reverse order, and the return value represent the last node in Items with the +specified value. The return value is -1 if a node is not found in Items with +the specified value. +

+

+IndexOfText is a convenience method; it is not used in the implementation of +TTreeNode, TTreeNodes, or TCustomTreeView. +

+ + + + - + +Ordinal position for the last child node containing the specified node Text, +or -1 when not found in the child nodes. + @@ -28925,11 +29268,36 @@ specified Text string. -Assign - if Source is of correct type, copies details -directly, otherwise calls inherited Assign which probably raises -an exception. +Implements object persistence for the TTreeNode type. - + +

+Assign is an overridden method in TTreeNode used to +implement object persistence for the type. Assign ensures that property values +in Source are copied to the current class instance when it is derived from +TTreeNode. Properties copied from Source include: +

+
    +
  • Text
    • +
  • Data
    • +
  • ImageIndex
    • +
  • SelectedIndex
    • +
  • OverlayIndex
    • +
  • Height
    • +
  • Focused
    • +
  • Cut
    • +
  • HasChildren
    • +
+

+The node cache in the TTreeNodes owner is cleared prior to copying values from +Source (when assigned). +

+

+If Source is not a TTreeNode instance, the inherited method is called to +complete the assignment or raise an EConvertError exception if Source is +unassigned. +

+ TPersistent.Assign @@ -28943,7 +29311,27 @@ an exception. Collapses the current tree node, and optionally collapses any descendent nodes. - + +

+Collapse calls the BeginUpdate and EndUpdate methods in the +TreeView control (when assigned) to reduce the number of updates performed +while one or more of the tree nodes are displayed in the collapsed state. +

+

+Recurse indicates whether child and all descendent nodes are also +collapsed in the method. The default value is False, and causes only +the current node instance to be displayed in the collapsed state. When set to +True, child nodes are visited and recursively collapsed. +

+

+After completion of the method, the affected nodes will have their Expanded +properties set to False and their States flags are updated accordingly. +

+

+Use Expand to reverse the collapse process. Use ExpandParents to expand all +ancestor tree nodes for the current node. +

+ @@ -28954,11 +29342,103 @@ nodes. -ConsistencyCheck - makes sure all references to and from the node -are consistent. +Ensures that node references to or from the current tree node are valid and +consistent. - - + +

+ConsistencyCheck validates properties in the tree node to ensure +that the node is in a valid state for its TTreeNodes container and the +TreeView control where the node is displayed. +

+

+ConsistencyCheck can raise a catchable debugger exception if any of the values +are not consistent or valid. For instance: +

+
    +
  • +The capacity in Items has a negative value. +
    • +
  • +The capacity in Items is smaller than the number of stored child nodes. +
    • +
  • +The number of nodes in Items is a negative value. +
    • +
  • +Items has been assigned but the capacity is zero (0) or a negative value.
    • +
  • +The Height for the node is a negative value. +
    • +
  • +The Top for the node is a negative value. +
    • +
  • +The Parent node is assigned, but does contain the current node in its Items +container. +
    • +
  • +The node has pointers to a previous or next sibling node which does have a +complimentary pointer to the node. +
    • +
  • +The node has a pointer to a previous or successive node in a multi-selection, +but that node does have have the complimentary pointer to the original node. +
    • +
  • +The MultiSelected property is enabled for the node, but it does not appear in +the multi-selection list for the TreeView control. +
    • +
  • +The Selected property is enabled for the node, but MultiSelected is not +enabled and the TreeView has multi-selections enabled in its Options. +
    • +
  • +Items contains a child node with a Nil (or unassigned) value. +
    • +
  • +Items has a child node which does not have the current node as its Parent. +
    • +
  • +There are circular references between the current node, its Parent, or its +previous or next sibling nodes. +
    • +
  • +The first child node has an invalid pointer to a previous sibling node. +
    • +
  • +A child node which is not the first child node does not have a pointer to the +previous sibling or points to the wrong tree node. +
    • +
  • +A child node which is not the last child node does not have a pointer to the +previous sibling or points to the wrong tree node. +
    • +
  • +A child node which is the last node in Items has an invalid pointer to a next +sibling node. +
    • +
  • +A child node has an Index value which does not match its actual position in +Items. +
    • +
+

+The ConsistencyCheck method is called recursively for child nodes as well. +

+

+These exception represent an extraordinary condition. +

+

+ConsistencyCheck is called from the implementation of the ConsistencyCheck +method in TTreeNodes, and occurs when the TreeView instance calls its +ConsistencyCheck method. +

+ + + + + @@ -28967,7 +29447,7 @@ Frees the current tree node when the Deleting property is not True.

-Delete is a method used to remove the tree node from the TTreeNodes +Delete is a method used to remove the tree node from its TTreeNodes container. Delete calls Free to destroy the object instance if the Deleting property is not set to True. No actions are performed when Deleting is True. @@ -28980,21 +29460,52 @@ property is not set to True. No actions are performed when Deleting is -DeleteChildren - remove the descendent Nodes in the tree structure. +Removes all child nodes and descendants in the tree structure. - - + +

+DeleteChildren clears the node cache in the TTreeNodes owner prior +to removing any child nodes in Items. It calls the Collapse method with +recursion to set the child nodes and their descendent nodes to the collapsed +state. The HasChildren property is set to False to update the States +flag values in the node and cause the TreeView control to be redrawn. +

+ + + + + + Ends editing of the tree node in the associated tree view control. - - + +

+EndEdit calls the EndEditing method in TreeView control to apply +the new value in the control Editor to the Text for the node. Cancel indicates +whether the modified text value for the node should be discarded. When set to +False, the modified value is stored in the Text property for the node. +The OnEdited event handler in TreeView is signalled (when assigned) and +Invalidate is called to cause the control to be redrawn. +

+

+No actions are performed in the method if TreeView has not been assigned for +the node. +

+ + + + + + -True if the edited value for Text is discarded. + +True if the edited value for Text is discarded. + @@ -29030,15 +29541,30 @@ routine. Not sure this deserves a version admonition though. -True to expand all descendent nodes for the node. + +True to expand all descendent nodes for the node. + -Expands any tree node which is an ancestor of the current node. +Expands all tree nodes which are an ancestor of the current node. - - + +

+ExpandParents visits each tree node which is used as the +Parent for a node, and sets its Expanded property to True. +

+

+ExpandParents is called from methods like MakeVisible and EnsureNodeIsVisible in TCustomTreeView. +

+ + + + + + + @@ -29053,8 +29579,8 @@ Forces the tree node to become visible.

-Calls the EnsureNodeIsVisible method in the associated TreeView (when -assigned). Otherwise, calls the ExpandParents method. +It calls the EnsureNodeIsVisible method in the associated TreeView (when +assigned). Otherwise, it calls the ExpandParents method.

@@ -29062,8 +29588,8 @@ assigned). Otherwise, calls the ExpandParents method. -MoveTo - method for relocating a node to the specified -Destination using the specified mode of attachment. +Relocates a node to the specified Destination node using the +specified mode of attachment.

@@ -29091,15 +29617,20 @@ Definition of the modes of attachment: - + +Tree node which provides the location where the current is moved using the specified attachment mode. + - + +Specifies where the node is stored relative to the destination node. + -MultiSelectGroup - method for multi-selecting a group of nodes. +Adds the group of nodes between a selected node and the current node to a +multi-selection range. @@ -29110,8 +29641,28 @@ Definition of the modes of attachment: Redraws the associated TreeView control if an update is not already in progress. - - + +

+Update calls the Invalidate method in the TreeView control for the +node and causes the tree view control (and the node) to be redrawn. No actions +are performed in the method if TreeView has not been assigned, or if the +TTreeNodes container is already performing an update. +

+

+Update is called is called when a new value has been assigned to the Text, +Height, or NodeEffect properties in the node. +

+ + + + + + + + + + + @@ -29136,23 +29687,54 @@ debugger output. -AbsoluteIndex - the absolute index of the current node, i.e. -without taking into account the level of ancestry. +The absolute ordinal position for the node, regardless of its level or +ancestry, in the tree node hierarchy. - - + +

+AbsoluteIndex is a read-only Integer property which +contains the absolute ordinal position for the tree node, regardless of its +parent or level, in the hierarchy of tree nodes. For example: +

+
    +
  • +The first node in the tree hierarchy has the absolute index position 0. +
    • +
  • +The first child nodes (in Items) has an index position which is 1 larger than +the AbsoluteIndex for its Parent node. +
    • +
  • +The next sibling node has an absolute index position which is incremented by 1 +plus the SubTreeCount value from its sibling. +
    • +
+ + + + + + + + + + + -The number of nodes where the current node is the parent node. +The number of nodes which have the current node as the Parent node.

Contains the same value as the Count property in Items.

- + + + + @@ -29179,7 +29761,7 @@ Pointer to the custom data for the node.

Data is a Pointer property with a pointer to the custom data for the node. Data can contain any arbitrary data type, and must be cast to the correct -types when used in an application. +type when used in an application.

Setting a new value for the property causes the associated TreeView (when @@ -29521,11 +30103,22 @@ starting at the current node. -True if more than one node has been selected simultaneously (e.g. using -the Shift or Ctrl key while selecting). +Indicates whether the node is one of several nodes selected simultaneously +(e.g. using the Shift or Ctrl key while selecting on a tree view control). - + + + + + + + + + + + +