Skip to content

Commit 4b0ff8b

Browse files
YanushevGeorgiyordan-mitev
YanushevGeorgi
and
yordan-mitev
authored
docs(treeview): add drag events documentation (#1724)
* docs(treeview): add drag events documentation * Apply suggestions from code review Co-authored-by: Yordan <[email protected]> * docs(treeview): fix event description and format --------- Co-authored-by: Yordan <[email protected]>
1 parent 31ad827 commit 4b0ff8b

File tree

3 files changed

+259
-9
lines changed

3 files changed

+259
-9
lines changed

‎components/treeview/drag-drop.md

Lines changed: 246 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,15 @@ position: 11
1212

1313
The Drag and Drop functionality for the TreeView allows you to move a node or multitude of nodes between different parents in the same treeview or between different Telerik TreeView instances.
1414

15-
This article will be divided in the following sections:
15+
This article is divided in the following sections:
1616

1717
* [Basics](#basics)
18-
* [OnDrop Event](#ondrop-event)
18+
* [`OnDragStart` Event](#ondragstart-event)
19+
* [`OnDrag` Event](#ondrag-event)
20+
* [`OnDrop` Event](#ondrop-event)
21+
* [`OnDragEnd` Event](#ondragend-event)
1922
* [Examples](#examples)
23+
* [Events Example](#events-example)
2024
* [Drag and Drop between TreeView, Grid, TreeList and Scheduler](#drag-and-drop-between-treeview-grid-treelist-and-scheduler)
2125
* [Flat Data](#flat-data)
2226
* [Hierarchical Data](#hierarchical-data)
@@ -28,12 +32,43 @@ To enable the Drag and Drop functionality:
2832

2933
1. Set the `Draggable` parameter of the `<TelerikTreeView>` to `true`
3034

31-
1. Use the `OnDrop` event to handle the drag and drop operations and modify the data source as per your business logic.
35+
1. Use the Drag events to handle the drag and drop operations and modify the data source as per your business logic.
3236

37+
## OnDragStart Event
38+
39+
The `OnDragStart` event fires when the user starts dragging a node. It provides details for the dragged item and allows you to cancel the event.
40+
41+
### Event Arguments
42+
43+
The `OnDragStart` event handler receives as an argument an object of type `TreeViewDragStartEventArgs` that contains:
44+
45+
| Parameter | Type | Description |
46+
| --- | --- | --- |
47+
| `Item` | `object` | Represents the dragged row. You can cast this object to your model class. |
48+
| `IsCancelled`| `bool` | Whether the event is to be prevented. |
49+
50+
## OnDrag Event
51+
52+
The `OnDrag` event fires continuously while the user is dragging a node.
53+
54+
### Event Arguments
55+
56+
The `OnDrag` event handler receives as an argument an object of type `TreeViewDragEventArgs` that contains:
57+
58+
| Parameter | Type | Description |
59+
| --- | --- | --- |
60+
| `Item` | `object` | Represents the dragged row. You can cast this object to your model class. |
61+
| `DestinationItem` | `object` | Represents the row over which the `Item` is. You can cast this object to your model class. |
62+
| `DestinationTreeView` | `object` | The reference of the TreeView in which the `Item` is dropped. |
63+
| `DestinationIndex` | `string` | The index in the target component where the drop will happen. |
64+
| `DestinationComponentId` | `string` | The `Id` of the target component in which the drop will happen. |
65+
| `DropPosition` | `enum` | Its members allow you to determine the exact position of the dropped item relative to the position of the `DestinationItem`. |
66+
| `PageX` | `double` | Represents the X coordinate of the mouse. |
67+
| `PageY` | `double` | Represents the Y coordinate of the mouse. |
3368

3469
## OnDrop Event
3570

36-
The `OnDrop` event fires when the user drops a node into a new location. It allows you to manipulate your data collection based on where the user dropped the element.
71+
The `OnDrop` event fires when the user drops a node to a new location. It is triggered only if the new location is a Telerik component. The event allows you to manipulate your data collection based on where the user dropped the element.
3772

3873
### Event Arguments
3974

@@ -49,13 +84,215 @@ The `OnDrop` event provides an object of type `TreeViewDropEventArgs` to its eve
4984
| `DestinationIndex` | `string` | The index where the drop will happen in the second component. |
5085
| `DestinationComponentId` | `string` | The `Id` of the second component in which the drop will happen. |
5186

87+
## OnDragEnd Event
88+
89+
The `OnDragEnd` event fires when a drag operation ends. The event is triggered after `OnDrop` and unlike it, `OnDragEnd` will fire even if the drop location is not a Telerik component. In this case, the non-aplicable event arguments will be null.
90+
91+
### Event Arguments
92+
93+
The `OnDragEnd` event handler receives as an argument an object of type `TreeViewDragEndEventArgs` that contains:
94+
95+
| Parameter | Type | Description |
96+
| --- | --- | --- |
97+
| `DestinationItem` | `object` | Represents the row over which the `Item` is. You can cast this object to your model class. |
98+
| `DestinationTreeView` | `object` | The reference of the TreeView in which the `Item` is dropped. |
99+
| `DestinationIndex` | `string` | The index in the target component where the drop will happen. |
100+
| `DestinationComponentId` | `string` | The `Id` of the target component in which the drop will happen. |
101+
| `DropPosition` | `enum` | Its members allow you to determine the exact position of the dropped item relative to the position of the `DestinationItem`. |
102+
52103
## Examples
53104

105+
* [Events Example](#events-example)
54106
* [Drag and Drop between TreeView, Grid, TreeList and Scheduler](#drag-and-drop-between-treeview-grid-treelist-and-scheduler)
55107
* [Flat Data](#flat-data)
56108
* [Hierarchical Data](#hierarchical-data)
57109
* [Between Different TreeViews](#between-different-treeviews)
58110

111+
### TreeView Drag and Drop Events
112+
113+
>caption Handle Blazor TreeView Drag Events
114+
115+
````CSHTML
116+
<div>
117+
Current Item: @CurrentItem
118+
<br />
119+
Current Location: @Location @DestinationItem
120+
<br />
121+
@Hint
122+
</div>
123+
124+
<TelerikTreeView Data="@Data"
125+
Id="TreeView"
126+
@bind-ExpandedItems="@ExpandedItems"
127+
Draggable="true"
128+
OnDrop="@OnItemDrop"
129+
OnDragStart="@OnDragStart"
130+
DragThrottleInterval="150"
131+
OnDrag="@OnDrag"
132+
OnDragEnd="@OnDragEnd">
133+
<TreeViewBindings>
134+
<TreeViewBinding ParentIdField="Parent"></TreeViewBinding>
135+
</TreeViewBindings>
136+
</TelerikTreeView>
137+
138+
@code {
139+
private string CurrentItem { get; set; }
140+
private string DestinationItem { get; set; }
141+
private string Location { get; set; }
142+
private string Hint { get; set; } = "Documents and its children cannot be moved";
143+
private List<TreeItem> Data { get; set; }
144+
private IEnumerable<object> ExpandedItems { get; set; }
145+
146+
public class TreeItem
147+
{
148+
public int Id { get; set; }
149+
public int? Parent { get; set; }
150+
public string Text { get; set; }
151+
public ISvgIcon Icon { get; set; }
152+
public bool HasChildren { get; set; }
153+
154+
public TreeItem(int id, int? parent, string text, ISvgIcon icon, bool hasChildren)
155+
{
156+
Id = id;
157+
Parent = parent;
158+
Text = text;
159+
Icon = icon;
160+
HasChildren = hasChildren;
161+
}
162+
}
163+
164+
private void OnDragStart(TreeViewDragStartEventArgs args)
165+
{
166+
var item = args.Item as TreeItem;
167+
if (item.Parent == 1 || item.Id == 1)
168+
{
169+
args.IsCancelled = true;
170+
}
171+
else
172+
{
173+
CurrentItem = item.Text;
174+
}
175+
}
176+
177+
private void OnDrag(TreeViewDragEventArgs args)
178+
{
179+
if (args.DestinationItem != null)
180+
{
181+
var destination = args.DestinationItem as TreeItem;
182+
DestinationItem = destination.Text;
183+
}
184+
if (args.DropPosition != null)
185+
{
186+
Location = args.DropPosition.Value.ToString().ToLower();
187+
}
188+
else
189+
{
190+
Location = "over";
191+
}
192+
}
193+
194+
private void OnDragEnd(TreeViewDragEndEventArgs args)
195+
{
196+
var destination = args.DestinationItem as TreeItem;
197+
if (args.DestinationComponentId == "TreeView" && args.DropPosition!=null)
198+
{
199+
Hint = "Item was placed successfully";
200+
}
201+
else
202+
{
203+
Hint = "Invalid location";
204+
}
205+
CurrentItem = "";
206+
Location = "";
207+
DestinationItem = "";
208+
}
209+
210+
protected override void OnInitialized()
211+
{
212+
LoadData();
213+
214+
base.OnInitialized();
215+
}
216+
217+
private void OnItemDrop(TreeViewDropEventArgs args)
218+
{
219+
var item = args.Item as TreeItem;
220+
var destinationItem = args.DestinationItem as TreeItem;
221+
222+
if (destinationItem != null && IsChild(item, destinationItem))
223+
{
224+
return;
225+
}
226+
227+
Data.Remove(item);
228+
229+
if (item.Parent != null && !Data.Any(x => item.Parent == x.Parent))
230+
{
231+
Data.FirstOrDefault(x => x.Id == item.Parent).HasChildren = false;
232+
}
233+
234+
if (args.DropPosition == TreeViewDropPosition.Over)
235+
{
236+
item.Parent = destinationItem.Id;
237+
destinationItem.HasChildren = true;
238+
239+
Data.Add(item);
240+
}
241+
else
242+
{
243+
var index = Data.IndexOf(destinationItem);
244+
245+
item.Parent = destinationItem.Parent;
246+
247+
if (args.DropPosition == TreeViewDropPosition.After)
248+
{
249+
index++;
250+
}
251+
252+
Data.Insert(index, item);
253+
}
254+
255+
// Refresh data
256+
Data = new List<TreeItem>(Data);
257+
}
258+
259+
private bool IsChild(TreeItem item, TreeItem destinationItem)
260+
{
261+
if (destinationItem?.Parent == null || item == null)
262+
{
263+
return false;
264+
}
265+
else if (destinationItem.Parent?.Equals(item.Id) == true)
266+
{
267+
return true;
268+
}
269+
270+
var parentDestinationItem = Data.FirstOrDefault(e => e.Id.Equals(destinationItem.Parent));
271+
272+
return IsChild(item, parentDestinationItem);
273+
}
274+
275+
private void LoadData()
276+
{
277+
Data = new List<TreeItem>()
278+
{
279+
new TreeItem(1, null, "Documents", SvgIcon.Folder, true),
280+
new TreeItem(2, 1, "report.xlsx", SvgIcon.FileExcel, false),
281+
new TreeItem(3, 1, "status.docx", SvgIcon.FileWord, false),
282+
new TreeItem(4, 1, "conferences.xlsx", SvgIcon.FileExcel, false),
283+
new TreeItem(5, 1, "performance.pdf", SvgIcon.FilePdf, false),
284+
new TreeItem(6, null, "Pictures", SvgIcon.Folder, true),
285+
new TreeItem(7, 6, "Camera Roll", SvgIcon.Folder, true),
286+
new TreeItem(8, 7, "team.png", SvgIcon.FileImage, false),
287+
new TreeItem(9, 7, "team-building.png", SvgIcon.FileImage, false),
288+
new TreeItem(10, 7, "friends.png", SvgIcon.FileImage, false),
289+
};
290+
ExpandedItems = Data.ToList();
291+
}
292+
293+
}
294+
````
295+
59296
### Drag and Drop between TreeView, Grid, TreeList and Scheduler
60297

61298
The functionality allows dragging items between TreeView, [Grid]({%slug grid-drag-drop-overview%}), [TreeList]({%slug treelist-drag-drop-overview%}) and [Scheduler]({%slug scheduler-overview%}). To achieve it, set the `Draggable`/`RowDraggable` parameter, and implement it through an event - `OnDrop`/`OnRowDrop`.
@@ -99,12 +336,12 @@ The functionality allows dragging items between TreeView, [Grid]({%slug grid-dra
99336
</TelerikTreeView>
100337
101338
@code {
102-
public List<Person> GridData { get; set; }
103-
public TelerikGrid<Person> GridRef { get; set; }
339+
private List<Person> GridData { get; set; }
340+
private TelerikGrid<Person> GridRef { get; set; }
104341
105-
public TelerikTreeView TreeRef { get; set; }
106-
public TreeViewObservableFlatDataService TreeService { get; set; }
107-
public ObservableCollection<BaseFlatItem> TreeData { get; set; }
342+
private TelerikTreeView TreeRef { get; set; }
343+
private TreeViewObservableFlatDataService TreeService { get; set; }
344+
private ObservableCollection<BaseFlatItem> TreeData { get; set; }
108345
109346
protected override async Task OnInitializedAsync()
110347
{

‎components/treeview/events.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ This article explains the events available in the Telerik TreeView for Blazor:
2020
* [OnItemDoubleClick](#onitemdoubleclick)
2121
* [OnItemRender](#onitemrender)
2222
* [SelectedItemsChanged](#selecteditemschanged)
23+
* [Drag Events](#drag-events)
2324

2425
## CheckedItemsChanged
2526

@@ -78,6 +79,17 @@ The event handler receives as an argument an `TreeViewItemRenderEventArgs` objec
7879

7980
The `SelectedItemsChanged` event fires when the [selection]({%slug treeview-selection-overview%}) is enabled and the user clicks on a new item.
8081

82+
## Drag Events
83+
84+
The TreeView implements the Drag and Drop functionality through the following drag events:
85+
86+
* The `OnDragStart` event fires when the user starts dragging a node.
87+
* The `OnDrag` event fires continuously while a node is being dragged by the user.
88+
* The `OnDrop` event fires when the user drops a node into a new location. The event fires only if the new location is a Telerik component.
89+
* The `OnDragEnd` event fires when a drag operation ends. Unlike the `OnDrop` event, `OnDragEnd` will fire even if the new location is not a Telerik component.
90+
91+
For more details and examples, see the [Treeview Drag and Drop]({%slug treeview-drag-drop-overview%}) article.
92+
8193
## Example
8294

8395
>caption Handle Blazor TreeView Events

‎components/treeview/overview.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,7 @@ The following table lists TreeView parameters, which are not related to other fe
135135
| --- | --- | --- |
136136
| `Class` | `string` | The additional CSS class that will be rendered on the `div.k-treeview` element. Use it to apply custom styles or [override the theme]({%slug themes-override%}). |
137137
| `Size` | `string` <br /> `"md"` | Affects the TreeView layout, for example the amount of space between items. The possible valid values are `"lg"` (large), `"md"` (medium) and `"sm"` (small). For easier setting, use the predefined string properties in class [`Telerik.Blazor.ThemeConstants.TreeView.Size`](/blazor-ui/api/Telerik.Blazor.ThemeConstants.TreeView.Size). |
138+
| `DragThrottleInterval` | `int` <br /> (`0`) | The milliseconds between each firing of the `OnDrag` event during the dragging operations. |
138139

139140

140141
## TreeView Reference and Methods

0 commit comments

Comments
 (0)