[Overview][Constants][Types][Classes][Procedures and functions][Index] | Reference for unit 'ComCtrls' (#lcl)

# TCustomTreeView

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

The base class for TTreeView.

## Declaration

Source position: comctrls.pp line 3383

`type TCustomTreeView = class(TCustomControl)`
`protected`
`Type`
`TFindOption = (` |  | Identifies find options that can be enabled in TCustomTreeView.
`foFindIgnoresCase,` |  | Enable case-insensitive comparisons of the text in tree nodes.
`foFindExpands` |  | Causes a tree node to be expanded when it is accessed in a text path.
`);`
`TFindOptions = set of TFindOption;` |  | Set type used to store find options enabled in the class.
`FChangeTimer: TTimer;` |  | Member with the OnChange timer for the control.
`FEditor: TEdit;` |  | TEdit used as the editor in the tree view control.
`FFindOptions: TFindOptions;`
`class procedure WSRegisterClass; override;` |  | Registers this component class with the current WidgetSet.
`class function GetControlClassDefaultSize; override;` |  | Gets the default dimensions used for new instances of the class.
`procedure Added(); virtual;` |  | Performs actions needed when the specified tree node is added to Items.
`procedure EditorEditingDone(); virtual;` |  | Implements the OnEditingDone event handler for a tree node editor on the control.
`procedure EditorKeyDown(); virtual;` |  | Implements the OnKeyDown event handler for the editor on the tree view control.
`procedure BeginAutoDrag; override;` |  | For internal use: user has started dragging the control.
`procedure BeginEditing(); virtual;` |  | Prepares the control to edit the text for the specified tree node.
`function DoDragMsg(); override;` |  | Dispatches a drag message, sent by the DragManager.
`function CanChange(); virtual;` |  | True if the specified tree node can be used in the Selected or Selections properties.
`function CanCollapse(); virtual;` |  | Returns True if a given TreeNode can be collapsed.
`function CanEdit(); virtual;` |  | Returns True if the specified tree node can be edited.
`function CanExpand(); virtual;` |  | True if the specified tree node can be expanded.
`function CreateNode; virtual;` |  | CreateNode - creates a new node in a TreeView and returns its content.
`function CreateNodes; virtual;` |  | Creates a TTreeNodes container for the control.
`function CustomDraw(); virtual;` |  | Performs custom drawing using the assigned event handlers for the tree view control.
`function CustomDrawItem(); virtual;` |  | Performs custom drawing for a tree node using the event handlers in the control.
`function DefaultItemHeightIsStored;` |  | Implements the storage specifier for the DefaultItemHeight property.
`procedure DoAutoAdjustLayout(); override;` |  | Applies a layout adjustment policy using the specified scaling factors.
`function ExpandSignSizeIsStored;` |  | Implements the storage specifier for the ExpandSignSize property.
`function GetBuiltinIconSize; virtual;` |  | Gets the default size for icons when Images has not been assigned.
`function GetDragImages; override;` |  | Gets the image list with the Drag images for the control.
`function GetImageSize;` |  | Gets a TSize instance with the dimensions for images in the control.
`function GetMaxLvl;` |  | Not used in the current LCL version.
`function GetMaxScrollLeft;` |  | GetMaxScrollLeft - returns maximal extent of scrolling to the left.
`function GetMaxScrollTop;` |  | GetMaxScrollTop - returns the maximal extent of scrolling upwards.
`function GetNodeAtY();` |  | Gets the expanded tree node at the specified vertical coordinate.
`function GetNodeDrawAreaHeight;` |  | Gets the height for the usable drawing area on the tree view control.
`function GetNodeDrawAreaWidth;` |  | Gets the width for the usable drawing area on the tree view control.
`function IndentIsStored;` |  | Implements the storage specifier for the Indent property.
`function IsCustomDrawn(); virtual;` |  | Returns True if the specified target is custom-drawn.
`function IsNodeVisible();` |  | Returns True if the specified tree node and its parent nodes are visible and expanded.
`function IsNodeHeightFullVisible();` |  | Indicates whether the full height for the specified tree node is visible on the tree view control.
`function IsInsertMarkVisible; virtual;` |  | Indicates whether an insertion mark is visible on the tree view control.
`procedure MoveSelection();` |  | Makes the specified node become selected in the tree view control.
`procedure Change(); virtual;` |  | Performs actions needed when the selection in the control has been changed to include the specified tree node.
`procedure Collapse(); virtual;` |  | Performs actions needed when the specified tree node is collapsed.
`procedure CreateWnd; override;` |  | Performs actions needed when the handle for the control is created.
`procedure Click; override;` |  | Performs actions needed when the Left mouse button is clicked on the tree view control.
`procedure DblClick; override;` |  | Performs actions needed when the Left mouse button is double clicked on the tree view control.
`procedure TripleClick; override;` |  | Performs actions needed when the Left mouse is triple clicked on the tree view control.
`procedure QuadClick; override;` |  | Performs actions needed when the Left mouse is quadruple clicked on the tree view control.
`procedure Delete(); virtual;` |  | Performs actions needed when the specified tree node is deleted.
`procedure DestroyWnd; override;` |  | Performs actions needed when the handle for the control is destroyed.
`procedure DoCreateNodeClass(); virtual;` |  | Signals the OnCreateNodeClass event handler (when assigned).
`procedure DoEndDrag(); override;` |  | Performs actions needed when a drag operation is completed for the control.
`function DoMouseWheel(); override;` |  | Handles mouse wheel messages for the tree view control.
`function DoMouseWheelHorz(); override;` |  | Performs actions to handle a horizontal mouse wheel message.
`procedure DoPaint; virtual;` |  | Implements the Paint method for the control.
`procedure DoPaintNode(); virtual;` |  | Renders the specified tree node to the canvas for the control.
`procedure DoStartDrag(); override;` |  | Performs actions needed when a drag operation is started for the control.
`procedure DragOver(); override;` |  | Performs actions needed when an object is dragged over the tree view control.
`function DrawBuiltinIcon(); virtual;` |  | Defines a method used to draw a built-in icon for a specified tree node.
`procedure EndEditing(); virtual;` |  | Updates the specified tree node and hides editor.
`procedure EnsureNodeIsVisible();` |  | Ensures parent nodes are expanded, and the specified node is visible in the control.
`procedure Expand(); virtual;` |  | Expands the specified tree node and updates the scroll bars for the control.
`procedure GetImageIndex(); virtual;` |  | Gets the index of the image for the specified node.
`procedure GetSelectedIndex(); virtual;` |  | Gets the index for the image used for a selected tree node on the control.
`procedure InitializeWnd; override;` |  | Configures the control when its window handle is (re-)initialized.
`procedure KeyDown(); override;` |  | Handles key down events for the control.
`procedure Loaded; override;` |  | Performs actions needed when LCL component streaming has been completed.
`procedure MouseDown(); override;` |  | Handles mouse down events for the tree view control.
`procedure MouseMove(); override;` |  | Handles mouse move messages for the control.
`procedure MouseUp(); override;` |  | Handles a mouse up event for the control.
`procedure MouseLeave; override;` |  | Performs actions needed when the mouse pointer leaves the control.
`procedure NodeChanged(); virtual;` |  | Performs actions when a property value in the specified tree node has been changed.
`function NodeHasChildren(); virtual;` |  | Determines if the specified tree node has child nodes.
`procedure Notification(); override;` |  | Handles the notification when a component is added to or removed from the class instance.
`procedure Paint; override;` |  | Renders the tree view control.
`procedure ScrollView();` |  | Scrolls the visible area for the control by the specified horizontal and vertical offsets.
`procedure SetDragMode(); override;` |  | Sets the value for the DragMode property.
`procedure SetOptions(); virtual;` |  | Sets the value for the Options property.
`procedure UpdateDefaultItemHeight; virtual;` |  | Calculates and updates the value in the DefaultItemHeight property.
`procedure UpdateInsertMark(); virtual;` |  | Sets or removes an insertion mark at the specified position based on the values in Options.
`procedure DoSelectionChanged; virtual;` |  | Performs actions needed when the selection for the tree view has been changed.
`procedure WMHScroll(); message;` |  | Handles the LM_HSCROLL message for the control.
`procedure WMVScroll(); message;` |  | Handles the LM_VSCROLL message for the control.
`procedure WMLButtonDown(); message;` |  | Handles the LM_LBUTTONDOWN message for the control.
`procedure WMSetFocus(); message;` |  | Handles the LM_SETFOCUS message for the control.
`procedure WMKillFocus(); message;` |  | Handles the WMKillFocus message for the control.
`procedure Resize; override;` |  | Resizes the control and updates the scroll bars and the States property.
`property EditingItem: TTreeNode; [r]` |  | Contains the tree node being edited in the control.
`property States: TTreeViewStates; [r]` |  | Contains the state values in effect for the control.
`public`
`function GetSelectedChildAccessibleObject; override;` |  | Returns the currently selected child accessible object.
`function GetChildAccessibleObjectAtPos(); override;` |  | Returns the child accessibility object at the given position for the control.
`property AccessibilityOn: Boolean; [rw]` |  | Turns accessibility on or off to speed up the control.
`protected`
`property AutoExpand: Boolean; [rw]` |  | Expands a tree node when it is clicked or activated in code.
`property BorderStyle: TBorderStyle;` |  | Line style used to draw the border for the control.
`property HideSelection: Boolean; [rw]` |  | Indicates if the current selection is hidden when the control loses focus.
`property HotTrack: Boolean; [rw]` |  | Enables or disables highlight / underline drawing styles on a tree item when the mouse is hovered over it.
`property HotTrackColor: TColor; [rw]` |  | Font color used to draw the text on a hovered tree node when hot tracking is enabled.
`property DisabledFontColor: TColor; [rw]` |  | Font color used for a tree node when the tree view or the node is not enabled.
`property Indent: Integer; [rws]` |  | Number of pixels used to indent branch levels (child nodes) on the tree view control.
`property MultiSelect: Boolean; [rw]` |  | Enables or disables selection of multiple tree nodes at the same time.
`property OnAddition: TTVExpandedEvent; [rw]` |  | Event handler signalled when a tree node is added to the Items in the tree view control.
`property OnAdvancedCustomDraw: TTVAdvancedCustomDrawEvent; [rw]` |  | Event handler signalled to custom draw the grid control using drawing stages.
`property OnAdvancedCustomDrawItem: TTVAdvancedCustomDrawItemEvent; [rw]` |  | OnAdvancedCustomDrawItem - event handler for advanced custom drawing item.
`property OnChange: TTVChangedEvent; [rw]` |  | Event handler for a change notification in the tree view control.
`property OnChanging: TTVChangingEvent; [rw]` |  | Event handler signalled before the selected node in the tree view control is changed.
`property OnCollapsed: TTVExpandedEvent; [rw]` |  | Event handler signalled when a tree node has been collapsed on the control.
`property OnCollapsing: TTVCollapsingEvent; [rw]` |  | Event handler signalled prior to collapsing a node on the tree view control.
`property OnCompare: TTVCompareEvent; [rw]` |  | Event handler signalled to compare and sort tree nodes in their default order.
`property OnCreateNodeClass: TTVCreateNodeClassEvent; [rw]` |  | Event handler signalled to get the class reference used to create new tree nodes.
`property OnCustomCreateItem: TTVCustomCreateNodeEvent; [rw]` |  | OnCustomCreateItem - event handler for custom item creation.
`property OnCustomDraw: TTVCustomDrawEvent; [rw]` |  | Event handler signalled to perform custom drawing for the tree view control.
`property OnCustomDrawItem: TTVCustomDrawItemEvent; [rw]` |  | Event handler signalled to custom draw an item (tree node) on the control.
`property OnCustomDrawArrow: TTVCustomDrawArrowEvent; [rw]` |  | Event handler signalled to custom draw expand / collapse (fold) indicators for a tree node.
`property OnDeletion: TTVExpandedEvent; [rw]` |  | Event handler signalled when a node is deleted from the node tree.
`property OnEdited: TTVEditedEvent; [rw]` |  | Event handler signalled when the tree view control has been edited.
`property OnEditing: TTVEditingEvent; [rw]` |  | Event handler signalled to determine whether the editor can be enabled for a tree node.
`property OnEditingEnd: TTVEditingEndEvent; [rw]` |  | Event handler signalled when EndEditing is called for the control.
`property OnExpanded: TTVExpandedEvent; [rw]` |  | Event handler signalled when a node on the tree view control has been expanded.
`property OnExpanding: TTVExpandingEvent; [rw]` |  | Event handler signalled prior to expanding a node on the tree view control.
`property OnGetImageIndex: TTVExpandedEvent; [rw]` |  | Event handler signalled to get the ordinal position for the image displayed on a tree node.
`property OnGetSelectedIndex: TTVExpandedEvent; [rw]` |  | Event handler signalled to get the ordinal position for the image displayed for a selected node on the tree view control.
`property OnHasChildren: TTVHasChildrenEvent; [rw]` |  | Event handler signalled to determine if a given node in the tree view has child nodes.
`property OnNodeChanged: TTVNodeChangedEvent; [rw]` |  | Event handler signalled when the text for a tree node has been changed.
`property OnSelectionChanged: TNotifyEvent; [rw]` |  | Event handler signalled when the selection in the tree view control is changed.
`property PathDelimiter: string; [rw]` |  | Delimiter used to separate node identifiers in the path to a given tree node.
`property ReadOnly: Boolean; [rw]` |  | Indicates whether the text (or caption) for tree nodes can be edited in the control.
`property RightClickSelect: Boolean; [rw]` |  | Right-click also selects tree-item. Else it only calls PopupMenu.
`property RowSelect: Boolean; [rw]` |  | Paints the selection background over the full width of the control for a selected tree node.
`property ScrolledLeft: Integer; [rw]` |  | Horizontal coordinate for the origin of the visible display area.
`property ScrolledTop: Integer; [rw]` |  | Vertical coordinate for the origin of the visible display area.
`property ShowButtons: Boolean; [rw]` |  | Enables an expand/collapse (fold/unfold) icon for nodes with child nodes.
`property ShowLines: Boolean; [rw]` |  | Enables or disables the horizontal and vertical lines which join nodes in the tree hierarchy.
`property ShowRoot: Boolean; [rw]` |  | Enables or disables drawing the root node for the tree view control.
`property ShowSeparators: Boolean; [rw]` |  | Indicates whether horizontal separator lines are drawn between nodes on the tree view control.
`property SortType: TSortType; [rw]` |  | Allows items to be sorted by caption, by the Data property, or both.
`property ToolTips: Boolean; [rw]` |  | Indicates whether tool tips (hints) are enabled for nodes on the tree view control.
`public`
`constructor Create(); override;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`function AlphaSort;` |  | Sorts tree nodes using default sort procedure (alphabetic).
`procedure ClearSelection(); virtual;` |  | Clears the selection in the tree view control.
`procedure ConsistencyCheck;` |  | Verifies that values are updated and valid for the tree view control.
`function CustomSort();` |  | If True, the external method specified in SortProc is used for sorting.
`function DefaultTreeViewSort();` |  | DefaultTreeViewSort - returns result of string comparison between names of Node1 and Node2
`procedure EraseBackground(); override;` |  | Has an empty implementation in the current LCL version.
`function GetHitTestInfoAt();` |  | Returns hit test results for the specified coordinates.
`function GetNodeAt();` |  | Searches all expanded nodes for the tree node at the specified position.
`function GetNodeWithExpandSignAt();` |  | Gets the tree node at the specified coordinates which has a visible expand indicator, or Nil.
`procedure GetInsertMarkAt();` |  | Determines if there is an insert mark at the specified coordinates.
`procedure SetInsertMark();` |  | Places an Insert mark at the specified node in the tree.
`procedure SetInsertMarkAt(); virtual;` |  | Places an insert mark at the specified coordinates.
`procedure Invalidate; override;` |  | Causes the control to be redrawn when a redraw is not already in progress.
`function IsEditing;` |  | Indicates if the control is currently editing a node in the tree.
`procedure BeginUpdate;` |  | Starts an update process for the tree view control.
`procedure EndUpdate;` |  | Finishes an update process for the tree view control.
`procedure FullCollapse;` |  | Collapses all tree nodes on the tree view control.
`procedure FullExpand;` |  | Expands all tree nodes on the tree view control.
`procedure LoadFromFile();` |  | Loads tree nodes from the specified file.
`procedure LoadFromStream();` |  | Loads tree nodes from the specified stream.
`procedure SaveToFile();` |  | Saves the tree nodes in Items to the specified file.
`procedure SaveToStream();` |  | Saves the tree nodes in Items to the specified stream.
`procedure WriteDebugReport();` |  | Generates a formatted message with information about the tree view control and optionally tree nodes in Items.
`procedure LockSelectionChangeEvent;` |  | Increments the internal counter used to lock selection change events for the control.
`procedure UnlockSelectionChangeEvent;` |  | Decrements the internal counter used to lock selection change events for the control.
`function GetFirstMultiSelected;` |  | Returns the first tree node multi-selected on the tree view control.
`function GetLastMultiSelected;` |  | Gets the last tree node added to a multi-selection in the Items for the controls.
`procedure Select();` |  | Makes the specified node(s) become selected in the control.
`function SelectionVisible;` |  | Indicates whether selected tree node(s) on the control are visible.
`procedure MakeSelectionVisible;` |  | Makes a selected tree node visible on the control.
`procedure ClearInvisibleSelection;` |  | Clears selected tree node(s) in the control if they are not visible.
`function StoreCurrentSelection;` |  | 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.
`procedure ApplyStoredSelection();` |  | Selects the tree node with the access path represented in the specified string list.
`procedure MoveToNextNode();` |  | Moves the selection to the next tree node following the last selection in the control.
`procedure MoveToPrevNode();` |  | Moves the selection to the visible tree node following prior to the last selection in the control.
`procedure MovePageDown();` |  | Moves the selection to the next display page for the control.
`procedure MovePageUp();` |  | Moves the selection to the previous display page for the control.
`procedure MoveLeft();` |  | Changes the selected tree node on the control.
`procedure MoveRight();` |  | Changes the selected tree node on the control.
`procedure MoveExpand();` |  | Expands the selected tree node and optionally extends a multi-selection range to include the node.
`procedure MoveCollapse();` |  | Collapses the selected tree node and optionally removes it from a multi-selection range.
`procedure MoveHome();` |  | Moves to and optionally selects the first visible node in the control.
`procedure MoveEnd();` |  | Moves to and optionally selects the last expanded child node in Items.
`property BackgroundColor: TColor; [rws]` |  | Color of the background area on the control.
`property BorderWidth: TBorderWidth;` |  | Width of the line drawn as a border around the control.
`property BottomItem: TTreeNode; [rw]` |  | Contains the last visible tree node starting at the TopItem in the control.
`property Color: TColor;` |  | Color used to fill the background on the control display area.
`property DefaultItemHeight: Integer; [rws]` |  | Default height for tree nodes in the control.
`property DropTarget: TTreeNode; [rw]` |  | DropTarget - the target node for dropping a dragged item.
`property ExpandSignColor: TColor; [rw]` |  | Color used to paint expand / collapse (fold / unfold) indicators for tree nodes.
`property ExpandSignSize: Integer; [rws]` |  | Size of the expand / collapse (fold / unfold) indicators for tree nodes.
`property ExpandSignWidth: Integer; [rw]` |  | Width of the lines drawn for the expand/collapse indicator when using the tvestAngleBracket drawing style.
`property ExpandSignType: TTreeViewExpandSignType; [rw]` |  | Sets the drawing style for the expand / collapse (fold/unfold) indicators for tree nodes.
`property Images: TCustomImageList; [rw]` |  | Image list which holds icons for the tree nodes in Items.
`property ImagesWidth: Integer; [rw]` |  | Width for the Images used in the tree view control.
`property InsertMarkNode: TTreeNode; [rw]` |  | Node displayed as an insertion mark on the tree view control.
`property InsertMarkType: TTreeViewInsertMarkType; [rw]` |  | Indicates the default position for an insertion mark relative to a node and its parent or children.
`property Items: TTreeNodes; [rw]` |  | The container with the TTreeNode instances for the control.
`property KeepCollapsedNodes: Boolean; [rw]` |  | Indicates whether a node keeps its child nodes when it is collapsed.
`property MultiSelectStyle: TMultiSelectStyle; [rw]` |  | Multi-selection options enabled for the tree view control.
`property Options: TTreeViewOptions; [rw]` |  | The set of options enabled in the tree view control.
`property ScrollBars: TScrollStyle; [rw]` |  | Specifies the scroll bars displayed for the tree view control.
`property Selected: TTreeNode; [rw]` |  | The selected tree node in the control.
`property SelectionColor: TColor; [rw]` |  | Color used to paint the background for the selected tree node in the control.
`property SelectionCount: Cardinal; [r]` |  | Number of selected nodes in the tree view.
`property SelectionFontColor: TColor; [rw]` |  | Color used to draw the text for a (multi-)selected item when enabled.
`property SelectionFontColorUsed: Boolean; [rw]` |  | Indicates if the selection font color is used for selected items.
`property Selections []: TTreeNode; [r]` |  | Provides indexed access to the multi-selected tree nodes in the control.
`property SeparatorColor: TColor; [rw]` |  | Color used to paint horizontal lines between tree nodes when enabled.
`property StateImages: TCustomImageList; [rw]` |  | Image list with the bitmaps used to represent the state for nodes in the tree.
`property StateImagesWidth: Integer; [rw]` |  | Width for the bitmaps in the StateImages property.
`property TopItem: TTreeNode; [rw]` |  | TopItem - the first visible node of the tree.
`property TreeLineColor: TColor; [rw]` |  | Color used to draw the lines which connect the nodes in the tree.
`property TreeLinePenStyle: TPenStyle; [rw]` |  | Style of the TPen used to draw lines used to connect nodes in the control.
`published`
`property TabStop: Boolean;` |  | Enables or disables navigation using the Tab key.
`end;`

## Inheritance

`TCustomTreeView` |  | The base class for TTreeView.
`TCustomControl` |  | The base class for windowed controls which paint themselves.
`TWinControl` |  | Implements a windowed control which can contain other child controls.
`TControl` |  | The base class for visible controls.
`TLCLComponent` |  | The base class for LCL components which have an associated widget.
`TComponent`
?
`TObject`

## 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.

## See also

TTreeView |  | TTreeView is a control that displays a hierarchical list of items.
TCustomControl |  | The base class for windowed controls which paint themselves.