From c2237e38eda16ca343def3a10c8e1e9f35dbcee0 Mon Sep 17 00:00:00 2001 From: dsiders Date: Thu, 30 Mar 2023 03:41:03 +0100 Subject: [PATCH] Docs: LCL/comctrls. Updates content in TTabControlStrings and TCustomTreeView topics, including: TCustomTreeView.MouseUp TCustomTreeView.MouseLeave TCustomTreeView.NodeChanged TCustomTreeView.HotTrack TCustomTreeView.HotTrackColor TCustomTreeView.DisabledFontColor TCustomTreeView.Indent TCustomTreeView.OnAddition TCustomTreeView.OnChange TCustomTreeView.OnChanging TCustomTreeView.OnCustomDraw TCustomTreeView.OnCollapsed TCustomTreeView.OnCollapsing TCustomTreeView.OnCompare TTabControlStrings (various) --- docs/xml/lcl/comctrls.xml | 437 +++++++++++++++++++++++++++++++------- 1 file changed, 359 insertions(+), 78 deletions(-) diff --git a/docs/xml/lcl/comctrls.xml b/docs/xml/lcl/comctrls.xml index 7292acdf2a..d08284c8b1 100644 --- a/docs/xml/lcl/comctrls.xml +++ b/docs/xml/lcl/comctrls.xml @@ -5904,92 +5904,129 @@ TCustomTabControl, where it is defined as a String. - + +Ordinal position for the selected tab sheet on the control. + -SetHotTrack - specifies the status of HotTrack. +Sets the value for the HotTrack property. + - + + + - + +New value for the HotTrack property. + -SetImages - specifies the list of images to be used. +Sets the value for the Images property. + - + + + - + +New value for the Images property. + -SetMultiLine - specifies whether multi-line captions are -used. +Sets the value for the MultiLine property. + - + + + - + +New value for the MultiLine property. + -SetMultiSelect - specifies whether MultiSelection is -available. +Sets the value for the MultiSelect property. + - + + + - + +New value for the MultiSelect property. + -SetOwnerDraw - specifies whether an owner-derived drawing can be -used. +Sets the value for the OwnerDraw property. + - + + + - + +New value for the OwnerDraw property. + -SetRaggedRight - specifies whether ragged-right (as opposed to -right-justified) alignment is to be used. +Sets the value for the RaggedRight property. + - + + + - + +New value for the RaggedRight property. + -SetScrollOpposite - specifies whether scroll bars are to operate -in the opposite sense to normal. +Sets the value for the ScrollOpposite property. + - + + + - + +New value for the ScrollOpposite property. + -SetTabIndex - specifies an index value for a tab. +Sets the value for the TabIndex property. + - + + + - + +New value for the TabIndex property. + @@ -6018,28 +6055,48 @@ all False; Tab height and width to zero -GetHitTestInfoAt - returns the results of a hit test at the -specified location X, Y. - - +Returns hit test results for the specified location at X and Y. + + +

+GetHitTestInfoAt always returns an empty THitTests set in +TTabControlStrings. +

+ + + + + - + +Set of THitTest values for the specified mouse pointer coordinates. + - + +Horizontal coordinate checked in the method. + - + +Vertical coordinate checked in the method. + Gets the size for the String displayed on a tab control. - - + +

+GetSize is an abstract virtual method in +TTabControlStrings. It must be implemented in a descendent class. +

+ - + +Returns a set of THitTest result values for the specified location. + @@ -7775,7 +7832,7 @@ object is drawn. TCustomDrawStage a series of constants to define the drawing -stages. +stages for custom-drawn controls. @@ -32457,31 +32514,86 @@ position. -Handles mouse up events for the control. - + +Handles a mouse up event for the control. + + +

+MouseUp is an overridden method in TCustomTreeView used +to perform actions needed when a mouse up event occurs on the tree view +control. In TCustomTreeView, it ensures that a visible hint window is closed +before handling the mouse up event. It calls the inherited method to signal +the OnMouseUp event handler (when assigned). +

+

+If PopupMenu is assigned, a right-shifted right mouse button click causes +the method to be exited to process the context menu request. (Nota bene: +RShift + RButton specifically; the code does not handle LShift + RButton.) +

+

+For a Left mouse button up event, the control tries to select the tree node +under the pointer or toggle the editor state on a already selected tree node. +Use ReadOnly to enable or disable the tree node editor when the mouse up event +is handled. +

+

+Values in the States property are updated prior to exiting from the method. +

+ TControl.MouseUp - + +Mouse button for the mouse up event. + - + +Shift, Ctrl, or Alt modifier for the mouse up event. + - + +Horizontal coordinate for the mouse pointer in the mouse up event. + - + +Vertical coordinate for the mouse pointer in the mouse up event. + -Performs actions needed when the mouse cursor leaves the control. +Performs actions needed when the mouse pointer leaves the control. - - + +

+MouseLeave is an overridden method in TCustomTreeView. +

+

+It ensures that States is updated to remove click or editing flags included in +the flag values. If a hint window is visible for the control, it is hidden. If +HotTrack has been enabled and included in the Options for the control, the +internal member used to track the hovered tree node is reset. Cursor is +restored to the default cursor shape and the control is redrawn. +

+

+MouseLeave calls the inherited method prior to exit to signal the OnMouseLeave +event handler (when assigned). +

+ + + + + + + +TControl.Cursor +TControl.MouseLeave + @@ -32489,8 +32601,18 @@ Performs actions needed when the mouse cursor leaves the control. Performs actions when a property value in the specified tree node has been changed. - - + +

+Signals the OnNodeChanged event handler (when assigned) for the specified tree +node and change reason. NodeChanged is called when a tree node in Items calls +its Changed method. +

+ + + + + + Tree node with the changed property value. @@ -32946,25 +33068,31 @@ node when the property is changed. -Additionally highlight/underline tree-item when mouse is over it. +Enables or disables highlight / underline drawing styles on a tree item when +the mouse is hovered over it. + TCustomListView.HotTrack -Font color used for the text in a tree node when hot tracking is enabled. +Font color used to draw the text on a hovered tree node when hot tracking is +enabled. - + + + + -Font color used for tree nodes when the tree view is not enabled. +Font color used for a tree node when the tree view or the node is not enabled.

@@ -32976,11 +33104,12 @@ The default value for the property is clGrayText. -Size in pixels by which each nested branching level is to be indented. +Number of pixels used to indent branch levels (child nodes) on the tree view +control.

-Use 0 for auto-sized value. +Use 0 to auto-size the Indent value.

@@ -33030,8 +33159,7 @@ Use ClearMultiSelection to remove all existing nodes in Selections. -Event handler signalled when a tree node is added to the tree node Items in -the control. +Event handler signalled when a tree node is added to the Items in the tree view control.

@@ -33107,10 +33235,26 @@ drawing item. -OnChange - specialized event handler for a change in the TreeView. +Event handler for a change notification in the tree view control. - - + +

+OnChange is a TTVChangedEvent property with the event +handler signalled when a new tree node is selected on the tree view control. +

+

+It is called from the Change method. It occurs when the change timer is +triggered while getting accessibility object information for a newly selected +node on the tree view control. The Sender argument contains the tree view +control for the change notification. The Node argument indicates the tree node +for the change notification. +

+ + + + + + @@ -33142,29 +33286,123 @@ value is assigned to the Selection property. -OnCollapsed - specialized event handler when part of the tree is -collapsed. +Event handler signalled when a tree node has been collapsed on the control. - - + +

+OnCollapsed is a TTVExpandedEvent property with the event handler +signalled when a tree node has been collapsed on the tree view control. It +allows the application to perform actions needed when a tree node has been +collapsed - whether by using the fold indicator on the tree view or by setting +the Expanded property in a TTreeNode to False. +

+

+The Sender argument contains the tree view control for the event notification. +

+

+The Node argument contains the collapsed tree node for the event. +

+

+OnCollapsed is signalled from the Collapse method, and occurs after the +visibility and position in scroll bars have been updated for the control. +

+

+Use OnCollapsing to perform actions needed immediately prior to setting +Expanded to False in a TTreeNode instance. +

+

+Use OnExpanded to perform actions needed when a tree node has been expanded on +the tree view control. +

+ + + + + + + + + -OnCollapsing - specialized event handler while part of the tree is -being collapsed. +Event handler signalled prior to collapsing a node on the tree view control. - - + +

+OnCollapsing is a TTVCollapsingEvent property with the +event handler signalled prior to collapsing a node on the tree view control. +

+

+The Sender argument is the tree view control for the event notification. +

+

+Node contains the TTreeNode instance to be collapsed. +

+

+AllowCollapse is a variable argument which indicates if the tree node can (or +should) be collapsed on the tree view control. +

+

+OnCollapsing is signalled from the CanCollapse method (when assigned), and +occurs when the Expanded property in a tree node is changing from True +to False. The value returned in AllowCollapse is used as the return +value for the CanCollapse method. Setting AllowCollapse to False in the +handler routine prevents the tree node from being collapsed. +

+

+Use OnCollapsed to perform actions needed after a tree node has been collapsed +on the control. +

+ + + + + + + -OnCompare - specialized event handler for comparisons within the -TreeView. +Event handler signalled to compare and sort tree nodes in their default order. - - + +

+OnCompare is a TTVCompareEvent property with the event +handler signalled to compare nodes on the tree view control. It is signalled +(when assigned) to determine the sort order for tree nodes in the +DefaultTreeViewSort method. Arguments to the event handler include: +

+
+
Sender
+
+The tree view control for the event. +
+
Node1, Node2
+
+The tree nodes compared in the handler routine. +
+
Compare
+
+An Integer value with the relative sort order for the compared nodes. <0 +indicates that Node1 comes before Node2 in the sort order. <0 indicates +that Node1 comes after Node2 in the sort order. 0 means that Node1 and Node2 +have the same value in the sort order. +
+
+

+If OnCompare is not assigned, the sort order for tree nodes is determined +using the AnsiCompareStr (on Windows) or CompareStr (on UNIX-like platforms) +routines. +

+ + + + + + @@ -33172,9 +33410,42 @@ TreeView. Event handler signalled to get the class reference used to create new tree nodes. - + +

+OnCreateNodeClass is signalled (when assigned) when the CreateNode +method is executed for the tree view control. +

+

+OnCreateNodeClass occurs after the OnCustomCreateItem event handler has been +signalled to get a TTreeNode for the purpose. If its return value is +Nil, DoCreateNodeClass is called to signal OnCreateNodeClass. It is not +signalled if a return value was assigned in the OnCustomCreateItem handler +routine. +

+

+Sender contains the tree view control for the event handler. +

+

+NodeClass is used to return the class reference needed to create a new node +for the control. +

+

+A new instance of the class type is created and added to the node collection +in Items. +

+ + + + + + + + + + + @@ -33183,7 +33454,16 @@ nodes. OnCustomCreateItem - event handler for custom item creation. - + + +There is no example use case in either LCL or packages installed in the IDE. + + + + + + + @@ -35308,7 +35588,8 @@ expanded state of a TTreeView. The nodes are identified by their Text property.

Usage example:

-// save old expanded state + +// save old expanded state OldExpanded := TTreeNodeExpandedState.Create(ATreeView); // ... change a lot of nodes ... // restore old expanded state