TTreeView: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		A TTreeView ![](/wiki-images/a/a3/Ttreeview.png) is a graphical control element that presents a hierarchical view of information. Each item can have a number of subitems.
2	2
3	3		An item can be expanded to reveal subitems, if any exist, and collapsed to hide subitems.
4	4
5	5		## A Short example of using TTreeview
6	6
7	7		Here is a simple example:
8	8
9	9		- Create a new application.
10	10		- Add an empty treeview to the form, a button1 with caption "Add Child" and a button2 with caption "Delete"
11	11		- Assign the following code to the buttons' OnClick events. Compile and run.
12	12
13	13		``` pascal
14	14		procedure TForm1.Button1Click(Sender: TObject);
15	15		var
16	16		n: integer;
17	17		s: string;
18	18		begin
19	19		// If there are no nodes, create a root node with a parent of nil
20	20		if TreeView1.Items.Count = 0 then
21	21		begin
22	22		Treeview1.Items.Add(nil,'Root Node');
23	23		exit;
24	24		end;
25	25
26	26		// Set up a simple text for each new node - "Node1", "Node2" etc
27	27		n := Treeview1.Items.Count;
28	28		s := 'Node ' + IntToStr(n);
29	29
30	30		// Add a new node to the currently selected node
31	31		if TreeView1.Selected <> nil then
32	32		Treeview1.Items.AddChild(Treeview1.Selected, s);
33	33		end;
34	34
35	35		procedure TForm1.Button2Click(Sender: TObject);
36	36
37	37		// A procedure to recursively delete nodes
38	38		procedure DeleteNode(ANode: TTreeNode);
39	39		begin
40	40		while ANode.HasChildren do
41	41		DeleteNode(ANode.GetLastChild);
42	42		TreeView1.Items.Delete(ANode);
43	43		end;
44	44
45	45		begin
46	46		if TreeView1.Selected = nil then
47	47		exit;
48	48
49	49		// If the selected node has child nodes, first ask for confirmation
50	50		if Treeview1.Selected.HasChildren then
51	51		if MessageDlg('Delete node and all children?', mtConfirmation, [mbYes,mbNo], 0 ) <> mrYes then
52	52		exit;
53	53		DeleteNode(TreeView1.Selected);
54	54		end;
55	55		```
56	56
57	57		When running, the treeview is empty. If you click "Add Child", a root node is created. After that a child will be added to any selected node by clicking "Add Child" again.
58	58
59	59		The "Delete" button will delete the currently selected node. If it doesn't have children, it will delete it immediately, but if it has children, it will first ask.
60	60
61	61		## Adding a new item in code
62	62
63	63		To add a sibling node to pre-existing node, use TTreeView.ITems.Add.
64	64
65	65		``` pascal
66	66		TreeView1.Items.Add(ATreeNode, 'Added node');
67	67		```
68	68
69	69		To add the first node, it becomes:
70	70
71	71		``` pascal
72	72		TreeView1.Items.Add(nil, 'First node');
73	73		```
74	74
75	75		Use TTreeView.Items.AddChild or AddChildObject to add child node.
76	76
77	77		``` pascal
78	78		TreeView1.Items.AddChild(ATreeNode, 'Child node');
79	79		```
80	80
81	81		## Creating a TreeView which loads items only when expanding
82	82
83	83		To add the expansion symbol to a node without subitems use:
84	84
85	85		``` pascal
86	86		MyNode.HasChildren := True;
87	87		```
88	88
89	89		And then set an event handler for the OnExpanding event. In this even you should return if the expansion can actually be made or not and when yes, you should add subitems to the node. If the expansion cannot be done, the expansion symbol will be automatically removed even if you have previously set HasChildren to true.
90	90
91	91		## How to move a node in TTreeview
92	92
93	93		Assuming you have UP and Down buttons to move the selected node in the TTreeview, these procedures will achieve moving the selected node.
94	94
95	95		``` pascal
96	96		procedure TForm1.UpBtnClick(Sender: TObject);
97	97		begin
98	98		// Ensure a node is selected
99	99		if(Treeview1.Selected <> nil) then
100	100		// Ensure there is a previous sibling node
101	101		if Treeview1.Selected.GetPrevSibling <> nil then
102	102		// If we have made it this far, move it UP
103	103		Treeview1.Selected.MoveTo(Treeview1.Selected.GetPrevSibling, naInsert);
104	104		end;
105	105
106	106		procedure TForm1.DownBtnClick(Sender: TObject);
107	107		begin
108	108		// Ensure a node is selected
109	109		if(Treeview1.Selected <> nil) then
110	110		// Ensure there is a next sibling node
111	111		if Treeview1.Selected.GetNextSibling <> nil then
112	112		// If we have made it this far, move it DOWN
113	113		Treeview1.Selected.MoveTo(Treeview1.Selected.GetNextSibling, naInsertBehind);
114	114		end;
115	115		```
116	116
117	117		Note: These procedures will only move nodes which are at the same level in the TTreeview.
118	118
119	119		<thead>
120	120
121	121		</thead>
122	122		<tbody>
123	123
124	124		</tbody>
125	125
126	126		## Using multiple node selection
127	127
128	128		To allow multiple selection, you need to set the `tvoAllowMultiSelect` flag of the `Options` property. This will allow you to select additional nodes by `Ctrl`+`Mouse click`.
129	129
130	130		To get a list of selected nodes from code, you can use the `TreeView1.Selections` property:
131	131
132	132		``` pascal
133	133		procedure TForm1.Button1Click(Sender: TObject);
134	134		var
135	135		i: integer;
136	136		begin
137	137		Memo1.Lines.Clear;
138	138		for i := 0 to TreeView1.SelectionCount - 1 do
139	139		Memo1.Lines.Add(TreeView1.Selections[i].GetTextPath);
140	140		end;
141	141		```
142	142
143	143		## Freeing TreeNode Data
144	144
145	145		Use the TreeView's OnDeletion event to free your object.
146	146
147	147		``` pascal
148	148		procedure TForm1.TreeView1Deletion(Sender: TObject; Node: TTreeNode);
149	149		begin
150	150		TMyObject(Node.Data).Free;
151	151		Node.Data := nil;
152	152		end;
153	153		```
154	154
155	155		## Using Drag and Drop in a TreeView
156	156
157	157		If you want to allow a drag and drop function in your treeview, you need to :
158	158
159	159		1. Set to DmAutomatic, the property "Drag Mode" of your treeview
160	160		2. Create events for `onDragDrop` and `OnDragOver`:
161	161
162	162		``` pascal
163	163		...
164	164
165	165		Var
166	166		Node: TTreeNode;
167	167
168	168		...
169	169
170	170		procedure TForm1.TreeView1DragDrop(Sender, Source: TObject; X, Y: Integer);
171	171		begin
172	172		Treeview1 := TTreeView(Sender); { Sender is TreeView where the data is being dropped }
173	173		Node := Treeview1.GetNodeAt(x,y); { x,y are drop coordinates (relative to the Sender) }
174	174		{ since Sender is TreeView we can evaluate }
175	175		{ a tree at the X,Y coordinates }
176	176		if Source = Sender then { drop is happening within a TreeView }
177	177		begin
178	178		if Assigned(Treeview1.Selected) and { check if any node has been selected }
179	179		(Node <> Treeview1.Selected) then { and we're dropping to another node }
180	180		begin
181	181		if Node <> nil then
182	182		Treeview1.Selected.MoveTo(Node, naAddChild) { complete drop, by moving selected node }
183	183		else
184	184		Treeview1.Selected.MoveTo(Node, naAdd); { complete drop, by moving selected node in root }
185	185		end;
186	186		end;
187	187		end;
188	188
189	189		procedure TForm1.TreeView1DragOver(Sender, Source: TObject; X, Y: Integer; State: TDragState; var Accept: Boolean);
190	190		begin
191	191		Accept := true;
192	192		end;
193	193		```
194	194
195	195		## Comments on Events
196	196
197	197		Event handlers are convenient places for developing LCL applications. There are some peculiar events for TTreeview.
198	198
199	199		When selected node is changed
200	200
201	201		``` pascal
202	202		procedure TForm1.TreeView1Change(Sender: TObject; Node: TTreeNode);
203	203		```
204	204
205	205		The `OnChange` event is fired when another node is selected. It can be used in a program to update some data.
206	206
207	207		``` pascal
208	208		procedure TForm1.TreeView1Changing(Sender: TObject; Node: TTreeNode; var AllowChange: Boolean);
209	209		```
210	210
211	211		The `OnChanging` event is called before `OnChange`, which allows you to prevent node selection under certain conditions. To do this, just set `AllowChange` to `false`. It is not necessary to set to `true` as this is the default value.
212	212
213	213		Please note that in Delphi the `Node` variable points to the node that leaves the selection. In Lazarus, the `Node` variable points to the node receiving the selection, but you can use the `Selected` property to find out the "previous" node.
214	214
215	215		In both events, the `Node` and `Selected` can be equal to `nil` (if there was no selection or it is being removed).
216	216
217	217		When a node is inserted
218	218
219	219		When a new node is inserted, related events occur in the following order.
220	220
221		-	~~` 1) OnNodeChanged`\~~
222		-	~~` 2) (OnChanging): This is called if there was a previously selected node.`\~~
223		-	~~` 3) OnSelectionChanged`\~~
224		-	~~` 4) OnChange`~~
	221	+	```text
	222	+	1) OnNodeChanged
	223	+	2) (OnChanging): This is called if there was a previously selected node.
	224	+	3) OnSelectionChanged
	225	+	4) OnChange
	226	+	```
225	227
226	228		When deleting a node
227	229
228	230		When the selected node is deleted, the following events occur.
229	231
230		-	~~` 1) OnDelete`\~~
231		-	~~` 2) OnChanging`\~~
232		-	~~` 3) SelectionChanged`\~~
233		-	~~` 4) OnChange : This is called because when you delete a node, another node is selected. `~~
	232	+	```text
	233	+	1) OnDelete
	234	+	2) OnChanging
	235	+	3) SelectionChanged
	236	+	4) OnChange : This is called because when you delete a node, another node is selected.
	237	+	```
234	238
235	239		If an unselected node is deleted, e.g. programmatically, then only the OnDelete event handler is called.
236	240
237	241		When Form is Closed
238	242
239	243		OnChanging event occurs, as the selected node is "de"selected. But OnChanging eventhander is executed AFTER the form is closed. This means that you cannot access the form's other data (other controls, other variables, etc.) within the OnChanging event handler procedure.
240	244
241	245		When Drag&Drop is done
242	246
243	247		When you drag a node to another node and drop, the following events occur.
244	248
245		-	~~` 1) OnSelectionChanged`\~~
246		-	~~` 2) OnNodeChanged`\~~
247		-	~~` 3) OnChange`~~
	249	+	```text
	250	+	1) OnSelectionChanged
	251	+	2) OnNodeChanged
	252	+	3) OnChange
	253	+	```
248	254
249	255		## See also
250	256
251	257		- [[Drag and Drop sample]]
252	258		- [[doc:/lcl/comctrls/ttreeview.html\|TTreeView doc]]
253	259		- [[TListView]]
254	260		- [[VirtualTreeview]]
255	261
256	262		---
257	263		From the Free Pascal wiki, page "TTreeView", as it stood on 2024-02-24 after a change by N7800, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history