TCustomTreeView class

In unit ComCtrls

The base class for TTreeView.

Declaration

pascal

TCustomTreeView = class(TCustomControl)

Inheritance

Descends from it: TCustomShellTreeView TTreeView

Description

TCustomTreeView is the base class for TTreeView which displays a collection of nodes using a hierarchical tree structure using a parent / sibling / child arrangement. Each tree node has descriptive text displayed for the item on the tree view control. A node may also include optional images which are displayed for the content or item state. The control can be used to select or navigate between tree nodes using either the mouse or the keyboard.

TCustomTreeView has properties and methods are used to perform actions for the control, like:

Load or Save the tree nodes on the control.
Add or Delete nodes on the control.
Sort tree nodes by their content.
Expand or collapse a tree node with child elements.
Format and display text or arbitrary data for the tree nodes.
Select or de-select one or more nodes in the tree hierarchy.
And much more...

Use the Items property to access and maintain the hierarchical list of tree nodes for the control. Use the OnCustomCreateItem event handler to create instances of a class derived from TTreeNode in the Items property.

Configure the visual aspects for the tree view control using properties including: BackgroundColor, Color, DefaultItemHeight ExpandSignColor, Images, Options, et. al.

An excellent tutorial for using TCustomTreeView / TTreeView, TTreeNodes, and TTreeNode can be found at:

TTreeView Page on the Lazarus Wiki

Please note that Accessibility support in TCustomTreeView might make this control slower if there are a very large number of items, for example: 10,000+ items. If the performance impact is unacceptable, it is possible to turn accessibility off for tree view items by setting the AccessibilityOn property to False. The default value is True.

Properties

`EditingItem`	protected	Contains the tree node being edited in the control.
`States`	protected	Contains the state values in effect for the control.
`AccessibilityOn`	public	Turns accessibility on or off to speed up the control.
`AutoExpand`	protected	Expands a tree node when it is clicked or activated in code.
`BorderStyle`	protected	Line style used to draw the border for the control.
`HideSelection`	protected	Indicates if the highlighting for current selection(s) are hidden when the control loses focus.
`HotTrack`	protected	Enables or disables highlight / underline drawing styles on a tree item when the mouse is hovered over it.
`HotTrackColor`	protected	Font color used to draw the text on a hovered tree node when hot tracking is enabled.
`DisabledFontColor`	protected	Font color used for a tree node when the tree view or the node is not enabled.
`Indent`	protected	Number of pixels used to indent branch levels (child nodes) on the tree view control.
`MultiSelect`	protected	Enables or disables selection of multiple tree nodes at the same time.
`PathDelimiter`	protected	Delimiter used to separate node identifiers in the path to a given tree node.
`ReadOnly`	protected	Indicates whether the text (or caption) for tree nodes can be edited in the control.
`RightClickSelect`	protected	Right-click also selects tree-item. Else it only calls PopupMenu.
`RowSelect`	protected	Paints the selection background over the full width of the control for a selected tree node.
`ScrolledLeft`	protected	Horizontal coordinate for the origin of the visible display area.
`ScrolledTop`	protected	Vertical coordinate for the origin of the visible display area.
`ShowButtons`	protected	Enables an expand/collapse (fold/unfold) icon for nodes with child nodes.
`ShowLines`	protected	Enables or disables the horizontal and vertical lines which join nodes in the tree hierarchy.
`ShowRoot`	protected	Enables or disables drawing the root node for the tree view control.
`ShowSeparators`	protected	Indicates whether horizontal separator lines are drawn between nodes on the tree view control.
`SortType`	protected	Allows items to be sorted by caption, by the Data property, or both.
`ToolTips`	protected	Indicates whether tool tips (hints) are enabled for nodes on the tree view control.
`BackgroundColor`	public	Color of the background area on the control.
`BorderWidth`	public	Width of the line drawn as a border around the control.
`BottomItem`	public	Contains the last visible tree node starting at the TopItem in the control.
`Color`	public	Color used to fill the background on the control display area.
`DefaultItemHeight`	public	Default height for tree nodes in the control.
`DropTarget`	public	DropTarget - the target node for dropping a dragged item.
`ExpandSignColor`	public	Color used to paint expand / collapse (fold / unfold) indicators for tree nodes.
`ExpandSignSize`	public	Size of the expand / collapse (fold / unfold) indicators for tree nodes.
`ExpandSignWidth`	public	Width of the lines drawn for the expand/collapse indicator when using the tvestAngleBracket drawing style.
`ExpandSignType`	public	Sets the drawing style for the expand / collapse (fold/unfold) indicators for tree nodes.
`Images`	public	Image list which holds icons for the tree nodes in Items.
`ImagesWidth`	public	Width for the Images used in the tree view control.
`InsertMarkNode`	public	Node displayed as an insertion mark on the tree view control.
`InsertMarkType`	public	Indicates the default position for an insertion mark relative to a node and its parent or children.
`Items`	public	The container with the TTreeNode instances for the control.
`KeepCollapsedNodes`	public	Indicates whether a node keeps its child nodes when it is collapsed.
`MultiSelectStyle`	public	Multi-selection options enabled for the tree view control.
`Options`	public	The set of options enabled in the tree view control.
`ScrollBars`	public	Specifies the scroll bars displayed for the tree view control.
`Selected`	public	The selected tree node in the control.
`SelectionColor`	public	Color used to paint the background for the selected tree node in the control.
`SelectionCount`	public	Number of selected nodes in the tree view.
`SelectionFontColor`	public	Color used to draw the text for a (multi-)selected item when enabled.
`SelectionFontColorUsed`	public	Indicates if the selection font color is used for selected items.
`Selections`	public	Provides indexed access to the multi-selected tree nodes in the control.
`SeparatorColor`	public	Color used to paint horizontal lines between tree nodes when enabled.
`StateImages`	public	Image list with the bitmaps used to represent the state for nodes in the tree.
`StateImagesWidth`	public	Width for the bitmaps in the StateImages property.
`TopItem`	public	TopItem - the first visible node of the tree.
`TreeLineColor`	public	Color used to draw the lines which connect the nodes in the tree.
`TreeLinePenStyle`	public	Style of the TPen used to draw lines used to connect nodes in the control.
`TabStop`	published	Enables or disables navigation using the Tab key.

Methods

`WSRegisterClass`	protected	Registers this component class with the current WidgetSet.
`GetControlClassDefaultSize`	protected	Gets the default dimensions used for new instances of the class.
`Added`	protected	Performs actions needed when the specified tree node is added to Items.
`EditorEditingDone`	protected	Implements the OnEditingDone event handler for a tree node editor on the control.
`EditorKeyDown`	protected	Implements the OnKeyDown event handler for the editor on the tree view control.
`BeginAutoDrag`	protected	For internal use: user has started dragging the control.
`BeginEditing`	protected	Prepares the control to edit the text for the specified tree node.
`DoDragMsg`	protected	Dispatches a drag message, sent by the DragManager.
`CanChange`	protected	True if the specified tree node can be used in the Selected or Selections properties.
`CanCollapse`	protected	Returns True if a given TreeNode can be collapsed.
`CanEdit`	protected	Returns True if the specified tree node can be edited.
`CanExpand`	protected	True if the specified tree node can be expanded.
`CreateNode`	protected	CreateNode - creates a new node in a TreeView and returns its content.
`CreateNodes`	protected	Creates a TTreeNodes container for the control.
`CustomDraw`	protected	Performs custom drawing using the assigned event handlers for the tree view control.
`CustomDrawItem`	protected	Performs custom drawing for a tree node using the event handlers in the control.
`DefaultItemHeightIsStored`	protected	Implements the storage specifier for the DefaultItemHeight property.
`DoAutoAdjustLayout`	protected	Applies a layout adjustment policy using the specified scaling factors.
`ExpandSignSizeIsStored`	protected	Implements the storage specifier for the ExpandSignSize property.
`GetBuiltinIconSize`	protected	Gets the default size for icons when Images has not been assigned.
`GetDragImages`	protected	Gets the image list with the Drag images for the control.
`GetImageSize`	protected	Gets a TSize instance with the dimensions for images in the control.
`GetMaxLvl`	protected	Not used in the current LCL version.
`GetMaxScrollLeft`	protected	GetMaxScrollLeft - returns maximal extent of scrolling to the left.
`GetMaxScrollTop`	protected	GetMaxScrollTop - returns the maximal extent of scrolling upwards.
`GetNodeAtY`	protected	Gets the expanded tree node at the specified vertical coordinate.
`GetNodeDrawAreaHeight`	protected	Gets the height for the usable drawing area on the tree view control.
`GetNodeDrawAreaWidth`	protected	Gets the width for the usable drawing area on the tree view control.
`IndentIsStored`	protected	Implements the storage specifier for the Indent property.
`IsCustomDrawn`	protected	Returns True if the specified target is custom-drawn.
`IsNodeVisible`	protected	Returns True if the specified tree node and its parent nodes are visible and expanded.
`IsNodeHeightFullVisible`	protected	Indicates whether the full height for the specified tree node is visible on the tree view control.
`IsInsertMarkVisible`	protected	Indicates whether an insertion mark is visible on the tree view control.
`MoveSelection`	protected	Makes the specified node become selected in the tree view control.
`Change`	protected	Performs actions needed when the selection in the control has been changed to include the specified tree node.
`Collapse`	protected	Performs actions needed when the specified tree node is collapsed.
`CreateWnd`	protected	Performs actions needed when the handle for the control is created.
`Click`	protected	Performs actions needed when the Left mouse button is clicked on the tree view control.
`DblClick`	protected	Performs actions needed when the Left mouse button is double clicked on the tree view control.
`TripleClick`	protected	Performs actions needed when the Left mouse is triple clicked on the tree view control.
`QuadClick`	protected	Performs actions needed when the Left mouse is quadruple clicked on the tree view control.
`Delete`	protected	Performs actions needed when the specified tree node is deleted.
`DestroyWnd`	protected	Performs actions needed when the handle for the control is destroyed.
`DoCreateNodeClass`	protected	Signals the OnCreateNodeClass event handler (when assigned).
`DoEndDrag`	protected	Performs actions needed when a drag operation is completed for the control.
`DoMouseWheel`	protected	Handles mouse wheel messages for the tree view control.
`DoMouseWheelHorz`	protected	Performs actions to handle a horizontal mouse wheel message.
`DoPaint`	protected	Implements the Paint method for the control.
`DoPaintNode`	protected	Renders the specified tree node to the canvas for the control.
`DoStartDrag`	protected	Performs actions needed when a drag operation is started for the control.
`DragOver`	protected	Performs actions needed when an object is dragged over the tree view control.
`DrawBuiltinIcon`	protected	Defines a method used to draw a built-in icon for a specified tree node.
`EndEditing`	protected	Updates the specified tree node and hides editor.
`EnsureNodeIsVisible`	protected	Ensures parent nodes are expanded, and the specified node is visible in the control.
`Expand`	protected	Expands the specified tree node and updates the scroll bars for the control.
`GetImageIndex`	protected	Gets the index of the image for the specified node.
`GetSelectedIndex`	protected	Gets the index for the image used for a selected tree node on the control.
`InitializeWnd`	protected	Configures the control when its window handle is (re-)initialized.
`KeyDown`	protected	Handles key down events for the control.
`Loaded`	protected	Performs actions needed when LCL component streaming has been completed.
`MouseDown`	protected	Handles mouse down events for the tree view control.
`MouseMove`	protected	Handles mouse move messages for the control.
`MouseUp`	protected	Handles a mouse up event for the control.
`MouseLeave`	protected	Performs actions needed when the mouse pointer leaves the control.
`NodeChanged`	protected	Performs actions when a property value in the specified tree node has been changed.
`NodeHasChildren`	protected	Determines if the specified tree node has child nodes.
`Notification`	protected	Handles the notification when a component is added to or removed from the class instance.
`Paint`	protected	Renders the tree view control.
`ScrollView`	protected	Scrolls the visible area for the control by the specified horizontal and vertical offsets.
`SetDragMode`	protected	Sets the value for the DragMode property.
`SetOptions`	protected	Sets the value for the Options property.
`UpdateDefaultItemHeight`	protected	Calculates and updates the value in the DefaultItemHeight property.
`UpdateInsertMark`	protected	Sets or removes an insertion mark at the specified position based on the values in Options.
`DoSelectionChanged`	protected	Performs actions needed when the selection for the tree view has been changed.
`WMHScroll`	protected	Handles the LM_HSCROLL message for the control.
`WMVScroll`	protected	Handles the LM_VSCROLL message for the control.
`WMLButtonDown`	protected	Handles the LM_LBUTTONDOWN message for the control.
`WMSetFocus`	protected	Handles the LM_SETFOCUS message for the control.
`WMKillFocus`	protected	Handles the WMKillFocus message for the control.
`Resize`	protected	Resizes the control and updates the scroll bars and the States property.
`GetSelectedChildAccessibleObject`	public	Returns the currently selected child accessible object.
`GetChildAccessibleObjectAtPos`	public	Returns the child accessibility object at the given position for the control.
`Create`	public	Constructor for the class instance.
`Destroy`	public	Destructor for the class instance.
`AlphaSort`	public	Sorts tree nodes using default sort procedure (alphabetic).
`ClearSelection`	public	Clears the selection in the tree view control.
`ConsistencyCheck`	public	Verifies that values are updated and valid for the tree view control.
`CustomSort`	public	If True, the external method specified in SortProc is used for sorting.
`DefaultTreeViewSort`	public	DefaultTreeViewSort - returns result of string comparison between names of Node1 and Node2
`EraseBackground`	public	Has an empty implementation in the current LCL version.
`GetHitTestInfoAt`	public	Returns hit test results for the specified coordinates.
`GetNodeAt`	public	Searches all expanded nodes for the tree node at the specified position.
`GetNodeWithExpandSignAt`	public	Gets the tree node at the specified coordinates which has a visible expand indicator, or Nil.
`GetInsertMarkAt`	public	Determines if there is an insert mark at the specified coordinates.
`SetInsertMark`	public	Places an Insert mark at the specified node in the tree.
`SetInsertMarkAt`	public	Places an insert mark at the specified coordinates.
`Invalidate`	public	Causes the control to be redrawn when a redraw is not already in progress.
`IsEditing`	public	Indicates if the control is currently editing a node in the tree.
`BeginUpdate`	public	Starts an update process for the tree view control.
`EndUpdate`	public	Finishes an update process for the tree view control.
`FullCollapse`	public	Collapses all tree nodes on the tree view control.
`FullExpand`	public	Expands all tree nodes on the tree view control.
`LoadFromFile`	public	Loads tree nodes from the specified file.
`LoadFromStream`	public	Loads tree nodes from the specified stream.
`SaveToFile`	public	Saves the tree nodes in Items to the specified file.
`SaveToStream`	public	Saves the tree nodes in Items to the specified stream.
`WriteDebugReport`	public	Generates a formatted message with information about the tree view control and optionally tree nodes in Items.
`LockSelectionChangeEvent`	public	Increments the internal counter used to lock selection change events for the control.
`UnlockSelectionChangeEvent`	public	Decrements the internal counter used to lock selection change events for the control.
`GetFirstMultiSelected`	public	Returns the first tree node multi-selected on the tree view control.
`GetLastMultiSelected`	public	Gets the last tree node added to a multi-selection in the Items for the controls.
`Select`	public	Makes the specified node(s) become selected in the control.
`SelectionVisible`	public	Indicates whether selected tree node(s) on the control are visible.
`MakeSelectionVisible`	public	Makes a selected tree node visible on the control.
`ClearInvisibleSelection`	public	Clears selected tree node(s) in the control if they are not visible.
`StoreCurrentSelection`	public	Creates and fills a TStringList with the text for each of the tree nodes in the access path to the Selected node on the tree view control.
`SelectionIsHidden`	public	Indicates whether the highlighting for a selection node is actually hidden (not visually displayed) or displayed in a "grayed" or "dim" state when the control loses focus.
`ApplyStoredSelection`	public	Selects the tree node with the access path represented in the specified string list.
`MoveToNextNode`	public	Moves the selection to the next tree node following the last selection in the control.
`MoveToPrevNode`	public	Moves the selection to the visible tree node following prior to the last selection in the control.
`MovePageDown`	public	Moves the selection to the next display page for the control.
`MovePageUp`	public	Moves the selection to the previous display page for the control.
`MoveLeft`	public	Changes the selected tree node on the control.
`MoveRight`	public	Changes the selected tree node on the control.
`MoveExpand`	public	Expands the selected tree node and optionally extends a multi-selection range to include the node.
`MoveCollapse`	public	Collapses the selected tree node and optionally removes it from a multi-selection range.
`MoveHome`	public	Moves to and optionally selects the first visible node in the control.
`MoveEnd`	public	Moves to and optionally selects the last expanded child node in Items.

Events

`OnAddition`	protected	Event handler signalled when a tree node is added to the Items in the tree view control.
`OnAdvancedCustomDraw`	protected	Event handler signalled to custom draw the grid control using drawing stages.
`OnAdvancedCustomDrawItem`	protected	OnAdvancedCustomDrawItem - event handler for advanced custom drawing item.
`OnChange`	protected	Event handler for a change notification in the tree view control.
`OnChanging`	protected	Event handler signalled before the selected node in the tree view control is changed.
`OnCollapsed`	protected	Event handler signalled when a tree node has been collapsed on the control.
`OnCollapsing`	protected	Event handler signalled prior to collapsing a node on the tree view control.
`OnCompare`	protected	Event handler signalled to compare and sort tree nodes in their default order.
`OnCreateNodeClass`	protected	Event handler signalled to get the class reference used to create new tree nodes.
`OnCustomCreateItem`	protected	OnCustomCreateItem - event handler for custom item creation.
`OnCustomDraw`	protected	Event handler signalled to perform custom drawing for the tree view control.
`OnCustomDrawItem`	protected	Event handler signalled to custom draw an item (tree node) on the control.
`OnCustomDrawArrow`	protected	Event handler signalled to custom draw expand / collapse (fold) indicators for a tree node.
`OnDeletion`	protected	Event handler signalled when a node is deleted from the node tree.
`OnEdited`	protected	Event handler signalled when the tree view control has been edited.
`OnEditing`	protected	Event handler signalled to determine whether the editor can be enabled for a tree node.
`OnEditingEnd`	protected	Event handler signalled when EndEditing is called for the control.
`OnExpanded`	protected	Event handler signalled when a node on the tree view control has been expanded.
`OnExpanding`	protected	Event handler signalled prior to expanding a node on the tree view control.
`OnGetImageIndex`	protected	Event handler signalled to get the ordinal position for the image displayed on a tree node.
`OnGetSelectedIndex`	protected	Event handler signalled to get the ordinal position for the image displayed for a selected node on the tree view control.
`OnHasChildren`	protected	Event handler signalled to determine if a given node in the tree view has child nodes.
`OnNodeChanged`	protected	Event handler signalled when the text for a tree node has been changed.
`OnSelectionChanged`	protected	Event handler signalled when the selection in the tree view control is changed.

Fields

`FChangeTimer`	protected	Member with the OnChange timer for the control.
`FEditor`	protected	TEdit used as the editor in the tree view control.
`FFindOptions`	protected

Types and constants

`TFindOption`	protected	Identifies find options that can be enabled in TCustomTreeView.
`TFindOptions`	protected	Set type used to store find options enabled in the class.