From b4ed0ec6535b7f4d5d887ff8cbd74507b22be29c Mon Sep 17 00:00:00 2001 From: dsiders Date: Thu, 30 Mar 2023 23:24:48 +0100 Subject: [PATCH] Docs: LCL/comctrls. Updates content in TCustomTreeView topics incuding: * TCustomTreeView.DefaultItemHeightIsStored * TCustomTreeView.GetMaxLvl * TCustomTreeView.GetNodeAtY * TCustomTreeView.GetNodeWithExpandSignAt * TCustomTreeView.GetNodeDrawAreaHeight * TCustomTreeView.GetNodeDrawAreaWidth * TCustomTreeView.IsNodeHeightFullVisible * TCustomTreeView.IsInsertMarkVisible * TCustomTreeView.Click * TCustomTreeView.DoEndDrag * TCustomTreeView.DoMouseWheel * TCustomTreeView.DoMouseWheelHorz * TCustomTreeView.DoPaint * TCustomTreeView.GetSelectedIndex * TCustomTreeView.Paint * TCustomTreeView.AccessibilityOn * TCustomTreeView.OnCustomDraw * TCustomTreeView.OnCustomDrawItem * TCustomTreeView.OnCustomDrawArrow * TCustomTreeView.OnEdited * TCustomTreeView.OnEditing * TCustomTreeView.OnExpanded * TCustomTreeView.OnExpanding * TCustomTreeView.OnGetImageIndex * TCustomTreeView.OnGetSelectedIndex * TCustomTreeView.RowSelect * TCustomTreeView.ShowLines * TCustomTreeView.ShowRoot * TCustomTreeView.SortType * TCustomTreeView.ToolTips * TCustomTreeView.OnCustomDrawArrow --- docs/xml/lcl/comctrls.xml | 453 ++++++++++++++++++++++++++++++++------ 1 file changed, 380 insertions(+), 73 deletions(-) diff --git a/docs/xml/lcl/comctrls.xml b/docs/xml/lcl/comctrls.xml index d08284c8b1..ec87ce3a51 100644 --- a/docs/xml/lcl/comctrls.xml +++ b/docs/xml/lcl/comctrls.xml @@ -31344,7 +31344,7 @@ Implements the storage specifier for the DefaultItemHeight property. -True when tvoAutoItemHeight in not in the Options for the control. +True when tvoAutoItemHeight is not in the Options for the control. @@ -31446,14 +31446,13 @@ is called to get the return value. -GetMaxLvl - returns the maximum level of branching of the tree -structure. +Not used in the current LCL version. - - - + +Not used in the current LCL version. + @@ -31480,7 +31479,7 @@ structure. -Gets an expanded node at the specified vertical coordinate. +Gets the expanded tree node at the specified vertical coordinate.

@@ -31499,11 +31498,32 @@ GetInsertMarkAt, and GetHitTestInfoAt methods. -Gets an expanded tree node for the specified screen coordinates. +Gets the tree node with an expand indicator at the specified coordinates.

-Used to implement the EnsureNodeIsVisible method. +Calls GetNodeAtY to determine if the mouse pointer is positioned over a tree +node on the control. The return value contains the TTreeNode instance at the +specified coordinates on the tree view control. +

+

+The return value can contain Nil when: +

+
    +
  • +Y is not positioned over an expanded and visible tree node. +
    • +
  • +X is not over the visible content for a tree node including a fold (expand / +collapse) indicator. +
    • +
  • +In row select mode, the mouse pointer is not over the highlighted content on +the tree view control. +
    • +
+

+Used in MouseDown to get the tree node under the mouse pointer.

@@ -31516,8 +31536,8 @@ node is not found. -Horizontal coordinate used to detected the border, expand indicator, or -display text for the tree node. +Horizontal coordinate used to locate the expand indicator, border (in row +select), or text for the tree node. @@ -31527,8 +31547,15 @@ Vertical coordinate for the expanded node to locate in the node hierarchy. -Gets the height for the usable drawing area in the control. - + +Gets the height for the usable drawing area on the tree view control. + + +

+Calculated using the ClientHeight and BorderWidth for the control. +Used in the implementation of the EnsureNodeIsVisible method. +

+ @@ -31539,9 +31566,13 @@ Calculated usable client height after borders are removed. -Gets the width for the usable drawing area in the control. +Gets the width for the usable drawing area on the tree view control. - + +

+Calculated using the ClientWidth and BorderWidth for the control. +

+ @@ -31606,29 +31637,82 @@ expanded. -IsNodeHeightFullVisible - returns True if the full height -of the specified node is visible in the current view. +Indicates whether the full height for the specified tree node is visible on +the tree view control. - - + +

+IsNodeHeightFullVisible is a Boolean method which +indicates whether the tree node in ANode is fully visible vertically on the +tree view control. +

+

+The return value is True if the Top and Height properties for the tree +node occur within the usable display area on the control. +

+

+The return value is False when: +

+
    +
  • +The tree node in ANode has not been assigned (Nil). +
    • +
  • +The tree node and its Parent nodes are not Visible and/or Expanded. +
    • +
  • +The text displayed for the tree node is clipped (partially visible) at one of +the vertical edges of the control. +
    • +
+

+IsNodeHeightFullVisible is used in the implementation of the +IsNodeHeightFullVisible method in TTreeNode. +

+ + + - + +True if the text for the specified tree node is fully visible within the +vertical bounds for the control. + - + +Tree node examined in the method. + -IsInsertMarkVisible - returns True if an Insert mark is -visible. +Indicates whether an insertion mark is visible on the tree view control. - + +

+What is an "insertion mark"? +

+

+An insertion mark is the visual indicator that identifies where a node added +or moved on the control will be placed. It is like a horizontal editing caret. +It is used during a node drag operation to show where the tree node will be +placed in the node hierarchy. +

+

+IsInsertMarkVisible checks internal members in the tree view to determine +whether a node and an insert mark type (TTreeViewInsertMarkType) have been +assigned for the control. The return value is True when both members have been +assigned and the mark node is visible on the control. When an insertion mark +becomes visible for a node, the tree view control is redrawn. +

+ - + +Returns True if an insertion mark is visible on the tree view control. + @@ -31751,7 +31835,7 @@ scroll bar visibility are reset, and the inherited method is called. -Performs actions needed when the Left mouse is clicked on the tree view +Performs actions needed when the Left mouse button is clicked on the tree view control. @@ -31882,7 +31966,7 @@ Signals the OnCreateNodeClass event handler (when assigned). Class reference used to create the new node instance. - + Performs actions needed when a drag operation is completed for the control. @@ -31909,18 +31993,48 @@ timer is disabled. Tooltips are restored to their previous values. - + + +Handles mouse wheel messages for the tree view control. + + +

+DoMouseWheel is an overridden method in TCustomTreeView. +It calls the inherited method on entry to signal OnMouseWheel handlers (when +assigned). If the event is not handled in the ancestor class, the value in +WheelDelta is used to scroll the visible tree nodes by the corresponding +number of nodes for the default item height. +

+

+Scroll bar positions are updated to reflect the new origin for the tree view +control. The tool tip for the current mouse pointer position is also updated +prior to exit. +

+ + +TControl.DoMouseWheel + + - + +Returns True if the mouse wheel event was handled. + - + +Shift, Ctrl, or Alt modifier for the mouse wheel event. + - + +Number of "clicks" that the mouse wheel was moved. + - + +TPoint instance with the coordinates for the mouse pointer when the mouse +wheel event was detected. + @@ -31931,9 +32045,12 @@ timer is disabled. Tooltips are restored to their previous values. needed to handle a horizontal mouse wheel message. It calls the inherited method to signal the OnMouseWheelHorz event handler (when assigned), or other chtOnMouseWheelHorz handlers registered in the -application. If the message is not handled in the ancestor, the value in +application. +

+

+If the message is not handled in the ancestor, the value in ScrolledLeft is updated to apply the delta value in -WheelDelta. The position for a tool tip (or hint) is also updated +WheelDelta. The position for a tool tip (or hint) is also updated using the coordinates in Mouse.

@@ -31942,20 +32059,31 @@ using the coordinates in Mouse. - + +Returns True if the wheel message was handled in an assigned event +handler or internally in the method. + - + +Shift, Alt, or Ctrl modifier for the mouse wheel message. + - + +Number of "clicks" that the mouse wheel was moved. + - + +Coordinates for the mouse pointer when the wheel event was detected. + -Implements the Paint method for the control. + +Implements the Paint method for the control. +

DoPaint is a method used render the control to its canvas. It @@ -32259,7 +32387,7 @@ Tree node examined in the method (and possibly updated in the event handler). -Gets the index for the image used a selected node in the control. +Gets the index for the image used for a selected tree node on the control.

@@ -32687,8 +32815,10 @@ set to Nil when the component is removed from the class instance. Renders the tree view control.

-Calls DoPaint to render the tree nodes, scroll bars, and decorations for the -control. +Paint is an overridden method in TCustomTreeView. It +calls the DoPaint method to update +the control state, default item height, borders, and scroll bars before +painting the nodes on the control.

@@ -32994,9 +33124,10 @@ object. Turns accessibility on or off to speed up the control.

-This property is provided for the situation where a tree view contains a huge -number of items, lets say 10,000+. In this case accessibility might slow the -tree down, so turning this property off might make things faster. +AccessibilityOn is provided for the situation where a tree view contains a +huge number of items, lets say 10,000+. In this case, accessibility might +affect the responsiveness and drawing performance for the tree view control. +Setting AccessibilityOn to False will likely make things faster.

@@ -33468,28 +33599,174 @@ There is no example use case in either LCL or packages installed in the IDE. -OnCustomDraw - event handler for custom drawing. +Event handler signalled to perform custom drawing for the tree view control. - - + +

+OnCustomDraw is a TTVCustomDrawEvent property with the +event handler signalled to perform custom drawing for the tree view control. +It is signalled (when assigned) from the CustomDraw method, and is used to +perform custom drawing for the control in the cdPrePaint drawing stage. It +occurs during execution of the Paint method. +

+

+An application can implement OnCustomDraw to perform custom drawing for the +overall control including borders and decorations not related to nodes on the +tree view control. +

+

+Arguments to the event handler include: +

+
+
Sender
+
+The tree view control for the event notification. +
+
ARect
+
+The TRect instance with the bounds for the control on its canvas. +
+
DefaultDraw
+
+Boolean variable argument which indicates if Paint processing should be +continued on return from the handler routine. Set DefaultDraw to True +in the handler routine to enable drawing of the tree nodes, fold indicators, +insert marks, and the unused area on the control. Set DefaultDraw to +False to exit the paint process. +
+
+

+The handler routine should use the Canvas for the control to perform drawing +operations on the specified bounds rectangle. +

+

+Use OnAdvancedCustomDraw to perform additional draw operations needed before +the tree nodes on the control is painted. +

+

+Use OnCustomDrawItem and OnAdvancedCustomDrawItem to perform custom drawing +for tree nodes on the control. Use OnCustomDrawArrow to perform custom drawing +for expand/collapse indicators for tree nodes on the control. +

+ + + + + + + + + + + + -OnCustomDrawItem - event handler for custom drawing item. +Event handler signalled to custom draw an item (tree node) on the control. - - + +

+OnCustomDrawItem is a TTVCustomDrawItemEvent property +with the event handler signalled to custom-draw the tree nodes displayed on +the tree view control. OnCustomDrawItem is signalled from the CustomDrawItem +method, and occurs during processing performed in the PaintNode method for the +control. +

+

+Arguments to the event handler include: +

+
+
Sender
+
+The tree view control for the event notification. +
+
Node
+
+The TTreeNode instance with the node custom-drawn in the handler routine. +
+
State
+
+TCustomDrawState value with the drawing state for the tree node. +
+
DefaultDraw
+
+Variable Boolean argument used to indicate whether the PaintNode process can +continue. Set to False in the handler routine to halt further paint +operations for the tree node. +
+
+

+If either OnCustomDrawItem or OnAdvancedCustomDrawItem are assigned, the +IsCustomDrawn method returns True. +

+ + + + + + + + + + + -Event handler signalled to custom draw expand or collapse indicators. +Event handler signalled to custom draw expand / collapse (fold) indicators +for a tree node. - - + +

+OnCustomDrawArrow is a TTVCustomDrawArrowEvent property +with the event handler signalled to custom-draw the expand/collapse (fold) +indicator for a node on the tree view control. +

+

+Arguments to the event handler include: +

+
+
Sender
+
+The tree view control for the event notification. +
+
ARect
+
+TRect instance with the bounds on the drawing area where the indicator should +be drawn. +
+
ACollapsed
+
+Boolean value which indicates which indicator (expanded or collapsed) to to +draw on the tree view control. True indicates that the collapsed arrow +should be drawn. +
+
+

+Use the Canvas for the control to perform drawing operations in the handler +routine. +

+

+OnCustomDrawArrow is signalled (when assigned) from the DoPaintNode method. If +OnCustomDrawArrow has not been assigned, the default drawing routines in the +class are used to paint the indicator using the style in the ExpansSignType, +ExpansSignSize, ExpansSignWidth, and ExpansSignColor properties. +

+ + + + + + + + + + Event handler signalled when a node is deleted from the node tree. @@ -33500,8 +33777,7 @@ Event handler signalled when a node is deleted from the node tree. -OnEdited - specialized event handler when the TreeView has been -edited. +Event handler signalled when the tree view control has been edited. @@ -33509,8 +33785,8 @@ edited. -OnEditing - specialized event handler while a TreeView is being -edited. +Event handler signalled when editing becomes active for a node on the tree +view control. @@ -33526,8 +33802,7 @@ Event handler signalled when EndEditing is called for the control. -OnExpanded - specialized event handler when a TreeView has been -expanded. +Event handler signalled when a node on the tree view control has been expanded. @@ -33535,7 +33810,7 @@ expanded. -OnExpanding - specialized event handler while a TreeView is being +Event handler signalled when a node on the tree view control prior is being expanded. @@ -33544,7 +33819,8 @@ expanded. -OnGetImageIndex - event handler for finding the index of an image. +Event handler signalled to get the ordinal position for the image displayed +for a tree node on the control. @@ -33552,8 +33828,8 @@ expanded. -OnGetSelectedIndex - event handler for finding index of selected -item. +Event handler signalled to get the ordinal position for the image displayed +for a selected node on the tree view control. @@ -33694,7 +33970,8 @@ Right-click also selects tree-item. Else it only calls PopupMenu. -When a tree-item is selected, paint selection background with full width. +Paints the selection background over the full width of the control for a +selected tree node. @@ -33744,8 +34021,8 @@ Enables an expand/collapse (fold/unfold) icon for nodes with child nodes. -Enables the horizontal and vertical lines which join nodes in the tree -hierarchy. +Enables or disables the horizontal and vertical lines which join nodes in the +tree hierarchy. @@ -33753,7 +34030,7 @@ hierarchy. -Enables drawing of the root node indicator for the tree view control. +Enables or disables drawing the root node indicator for the tree view control. @@ -33770,7 +34047,7 @@ view control. -Allows items to be sorted by caption, by Data property, or both. +Allows items to be sorted by caption, by the Data property, or both.

@@ -33784,11 +34061,41 @@ ParentNode.CustomSort(nil) to sort only the child nodes of a single node. -Show tooltip (hint) for a tree-item when the item is too long to fit by width -and mouse is over it. +Indicates whether tool tips (hints) are enabled for nodes on the tree view +control. - - + +

+ToolTips is a Boolean property which indicates whether +tool tips (pop-up hints) are enabled for nodes on the tree view control. A +tool tip is activated when the mouse pointer is hovered over a node. The text +displayed on the tool tip is set to the Text property in the TTreeNode +instance. +

+

+ToolTips is a convenience property; it indicates whether tvoToolTips has been +included in the Options for the control. The default value for the property is +True. Changing the property value causes Options to be updated to include or +exclude tvoToolTips in the set type. +

+

+ToolTips is used (indirectly) in methods which respond to mouse or mouse wheel +events like: DoMouseWheel, DoMouseWheelHorz, and MouseMove. +

+

+ToolTips is temporarily disabled when a drag operation is started for a node +on the tree view control. +

+ + + + + + + + + +