BinaryTreeListView

Creates a tree list view with no columns and no nodes.

The control starts set up as a tree: whole-row selection, no row headers and no cell borders, rows that the user cannot add or delete, columns that fill the width (Fill) and that the user can resize and reorder, and F2 to edit.

Add a BinaryTreeListViewColumn and any other columns to DataGridView.Columns, then add nodes through Nodes.

Gets or sets whether a cell value that cannot be formatted or committed is reported as a DataGridView normally reports it.

With it off, such errors are ignored: DataGridView.DataError is not raised, no error dialog is shown and nothing is thrown.

With it on, the grid's own handling applies: DataGridView.DataError is raised, the grid shows its error dialog when nothing handles the event, and a handler can set ThrowException to have the exception thrown.

Gets or sets whether the grid shows the row for adding a new row at the bottom.

Gets or sets whether the user can delete rows with the Delete key.

Gets or sets whether clicking a column heading sorts the tree by that column: ascending, then descending, then back to the order the nodes were built in.

A plain row sort would scramble a tree, so this is not the grid's own sort – every column stays NotSortable. Siblings are sorted within their parent, at every level, and each parent keeps its children beneath it. The sorted heading shows a chevron pointing up or down. A heading dragged to a new place is moved, not sorted.

Turning it off while the tree is sorted puts the original order back. To sort from code, call SortNodesByColumn; to decide how two values compare, handle DataGridView.SortCompare.

Gets or sets which parts of the grid the built-in renderer paints: the column headings, the row headings, the rows, or a combination.

Applies while UseBuiltInRendering is on. The rows are painted only for BuiltInCustomRenderedTargetElement.Row and BuiltInCustomRenderedTargetElement.All, so those are the settings that show the hover highlight and the cell borders in CellBorderDrawingColor. Row headings are hidden in a tree unless you turn on DataGridView.RowHeadersVisible.

Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the message shown in the middle of the control while HierarchicalDataSource is being bound.

The message, its colours and its font are read each time binding starts. It is not shown by BindToTreeListView.

Gets or sets the background colour of the message shown while HierarchicalDataSource is being bound.

Gets or sets the font of the message shown while HierarchicalDataSource is being bound.

Gets or sets the text colour of the message shown while HierarchicalDataSource is being bound.

Gets or sets the colour of the border round the current cell.

Gets or sets the colour of the cell borders the built-in renderer draws on the rows.

Drawn only when UseBuiltInRendering is on, BuiltInCustomRenderedTargetElement paints the rows (BuiltInCustomRenderedTargetElement.Row or BuiltInCustomRenderedTargetElement.All), and DataGridView.CellBorderStyle is one of Single, SingleHorizontal or SingleVertical. A tree starts with no cell borders (None), so set the border style as well.

Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the width of the border round the current cell.

Gets or sets how the user starts editing a cell. Set this instead of the grid's DataGridView.EditMode.

The control changes DataGridView.EditMode itself while the user works in the tree column, so that a click on a node's glyph or check box never starts an edit, and puts this value back afterwards. A value set on DataGridView.EditMode directly is therefore overwritten; one set here is kept, and applies at once.

Until this is set, or the user first clicks a cell, the grid starts editing on F2 only.

// Only F2 starts an edit, so typing while a row is selected never changes a value by accident.
plan.CellEditingMode = DataGridViewEditMode.EditOnF2;

Gets or sets the image drawn as the collapse glyph of an open node.

Takes effect only when ExpandImage is set as well. The image is drawn 10 by 10 logical pixels. A node's own BinaryTreeListViewNode.CollapseImage takes precedence.

Gets or sets the background colour a tinted column is given back when the pointer, or the current cell, leaves it.

Set it to the column colour you want when nothing is tinted, if that is not the grid's default cell colour.

Gets or sets the colour the column of the current cell is tinted in.

Gets or sets the colour the column under the pointer is tinted in.

Gets or sets the colour of a rule drawn along the bottom of the column headings, parting them from the rows.

Drawn when UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement includes the column headings. The built-in renderer paints its own background over the grid's heading border, so without a rule the headings end wherever their colour stops. Setting it repaints the control.

Gets or sets the colour of the line the built-in renderer draws between column headings.

Drawn when DrawColumnSeparatorWhenUsingBuiltinRendering is on and the built-in renderer paints the column headings. The line runs down the right-hand edge of each heading, two logical pixels short of its top and bottom. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets whether the control works as a tree list view or as a plain grid with this control's appearance features.

Set it before adding columns or rows. In ControlDataDisplayMode.ListView mode a BinaryTreeListViewColumn cannot be added (adding one throws), setting HierarchicalDataSource is ignored, and AllowUserToAddRows and AllowUserToDeleteRows can be turned on.

The settings the constructor makes for a tree – whole-row selection, no row headers, no cell borders – are not undone by switching to ControlDataDisplayMode.ListView; set those grid properties yourself.

Gets the node of the current cell – the row the user is on.

Handle DataGridView.SelectionChanged or DataGridView.CurrentCellChanged to follow it as the user moves.

Gets or sets how many passes binding makes over HierarchicalDataSource to place rows whose parent comes after them in the table.

A table that lists every parent before its children needs one pass; the default allows for a tree up to 25 levels deep listed in any order. Rows not placed after the last pass are left out. ShouldEnableFastCaching overrides it with a single pass.

Setting it binds the data again. With no HierarchicalDataSource set, that removes every node from the control – nodes added in code included – so set it before adding nodes, or only on a bound tree.

Gets or sets whether the built-in renderer draws a line between column headings.

Applies while UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement includes the column headings. The line is drawn in ColumnSeparatorDrawingColor. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets whether the row under the pointer is highlighted.

The highlight is part of the built-in row painting, so it shows only while UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement is BuiltInCustomRenderedTargetElement.Row or BuiltInCustomRenderedTargetElement.All. It is a gradient from GlassBrushTopHalfStartColor to GlassBrushBottomHalfEndColor, in the direction of OrientationAspectForRenderingRow. It is not drawn on selected rows or during a drag.

Gets or sets whether lines are drawn joining each node to its parent and its siblings.

Gets or sets whether the user can rearrange the tree by dragging nodes with the mouse.

With it on, the user presses on a node and drags; the row under the pointer is highlighted in RowSelectionBackColorDuringDragOver and RowSelectionForeColorDuringDragOver, with a line beneath it. Dropping on a node makes the dragged node, and everything beneath it, the last child of that node; dropping on the empty area below the last row makes it the last top-level node. A drop on the node itself or on one of its own descendants does nothing, and Escape cancels the drag.

The branch is moved as a copy: new BinaryTreeListViewNode objects with the same cell values, check state and glyph images replace the old ones, and arrive closed. Look the nodes up again after a drop rather than keeping references to them.

For drag and drop of your own, leave this off, set Control.AllowDrop, and handle ItemDrag.

// Let the user reorganise the plan by dragging tasks under other tasks.
plan.EnableAutomaticBuiltInDragDrop = true;
plan.ExpandTargetDropNodeUponDragDrop = true;
plan.RowSelectionBackColorDuringDragOver = Color.FromArgb(204, 228, 247);
plan.RowSelectionForeColorDuringDragOver = Color.Black;

Gets or sets whether an edit in progress is committed when the user clicks the glyph, check box or image area of a tree cell.

With it on, a click on the left-hand part of a tree cell – the indent, the expand glyph, the check box or the image – ends the current edit and keeps the new value before acting on the click. With it off, the edit stays open.

Gets or sets whether, in a read-only tree, a click anywhere in a node's tree cell opens or closes the node.

It applies when the grid is read-only, or the current cell, its row or its column is. A click on the tree cell of a node that has children then toggles it, wherever in the cell the click lands, and the click goes no further – a check box in that cell does not change.

When nothing is read-only, or this is off, only a click on the expand glyph toggles a node (and a double-click, see ExpandCollapseNodeOnDoubleClick).

Gets or sets the colour at the bottom or right of the gradient the built-in renderer fills the column headings with.

The gradient runs from StartColorForRenderingColumnHeader to EndColorForRenderingColumnHeader in the direction OrientationAspectForRenderingColumnHeader gives; set both to the same colour for a flat fill. It is painted while UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement includes the column headings. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the colour at the bottom or right of the gradient the built-in renderer fills each cell of the rows with.

The gradient runs from StartColorForRenderingRow to EndColorForRenderingRow in the direction OrientationAspectForRenderingRow gives; set both to the same colour for a flat fill. It is painted while UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement includes the rows. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the colour at the bottom or right of the gradient the built-in renderer fills the row headings with.

The gradient runs from StartColorForRenderingRowHeader to EndColorForRenderingRowHeader in the direction OrientationAspectForRenderingRowHeader gives; set both to the same colour for a flat fill. It is painted while UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement includes the row headings. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets whether double-clicking a node's cell in the tree column opens or closes the node.

Only nodes with children respond, and not while the cell is being edited. A click on the expand glyph toggles a node whatever this is set to.

Gets or sets where the focus must be for Shift+Right and Shift+Left to open and close a node.

• ExpandCollapsingOfNodesLevel.Row: the keys work on the current node whichever of its cells has the focus.
• ExpandCollapsingOfNodesLevel.TreeListViewCell: the keys work only while the node's cell in the tree column has the focus, leaving them to the other cells otherwise.
• ExpandCollapsingOfNodesLevel.None: the keyboard does not open or close nodes.

Shift+Right opens a closed node that has children; Shift+Left closes an open one.

Gets or sets the image drawn as the expand glyph of a closed node that has children.

Takes effect only when CollapseImage is set as well; with either one missing, the system glyph is used for both. The image is drawn 10 by 10 logical pixels. A node's own BinaryTreeListViewNode.ExpandImage takes precedence.

plan.ExpandImage = Properties.Resources.ChevronRight;    // shown on a closed node
plan.CollapseImage = Properties.Resources.ChevronDown;   // shown on an open node

Gets or sets whether the node a dragged node is dropped on is opened, with everything beneath it, so that the moved node can be seen in its new place.

Gets or sets the colour of the frame's border.

Used while ShouldDrawFrame is on, and replaced by FrameFocusedBorderColor while the focus is in the control. Setting it repaints the frame at once.

Gets or sets the thickness of the frame's border.

Gets or sets the radius of the frame's rounded corners.

The radius is never drawn larger than half the frame's shorter side. A larger radius also needs more padding to keep the square grid inside the curve; see FramePadding.

Gets or sets the colour of the frame's border while the focus is in the control – on the grid or on a cell's editor.

An accent colour here shows the user which grid the keyboard is in, as a focused text box does.

Gets or sets the space between the frame's border and the grid inside it.

The padding used is never less than three tenths of FrameCornerRadius, which is what keeps the grid's square corners inside the rounded ones. It is filled with DataGridView.BackgroundColor.

Gets or sets the colour of the frame's drop shadow.

The shadow's strength is FrameShadowOpacity, so the colour's own alpha is not used.

Gets or sets how far the frame's shadow spreads.

A third of the depth is also the distance the shadow drops below the frame, so it is deeper at the bottom than at the top.

Gets or sets the strength of the frame's shadow where it is darkest, next to the border.

Gets or sets the colour the hover highlight ends with – at the bottom of the row, or at its right when OrientationAspectForRenderingRow is horizontal.

// A pale blue hover band over plain rows.
plan.BuiltInCustomRenderedTargetElement = BuiltInCustomRenderedTargetElement.All;
plan.GlassBrushTopHalfStartColor = Color.FromArgb(235, 243, 252);
plan.GlassBrushBottomHalfEndColor = Color.FromArgb(214, 230, 248);

Gets or sets a colour kept for compatibility; the hover highlight does not use it.

The highlight is a two-colour gradient from GlassBrushTopHalfStartColor to GlassBrushBottomHalfEndColor.

Gets or sets a value kept for compatibility; the hover highlight does not use it.

The direction of the highlight's gradient follows OrientationAspectForRenderingRow.

Gets or sets a colour kept for compatibility; the hover highlight does not use it.

The highlight is a two-colour gradient from GlassBrushTopHalfStartColor to GlassBrushBottomHalfEndColor.

Gets or sets the colour the hover highlight starts with – at the top of the row, or at its left when OrientationAspectForRenderingRow is horizontal.

Gets or sets a table to build the whole tree from, in place of adding nodes in code.

The table's shape

The first three columns are for the control, and must be named UID, ID and ParentID; the columns after them are the data, matched to the control's columns in order – the table's fourth column fills the control's first column, and so on. Add the control's columns first, at least as many as there are data columns.

Values are compared and shown as text: every cell value becomes a string, so a column of numbers sorts as text unless you handle DataGridView.SortCompare.

Binding

Setting the property removes every node and builds the tree again, showing a busy message (BusyIndicatorText) while it works; the nodes start closed. Later changes to the table are not followed – set the property again to show them. Setting it to null removes every node. With ControlDataDisplayMode set to ControlDataDisplayMode.ListView the property is ignored; bind the grid's own DataGridView.DataSource instead.

Rows are placed in passes, in table order unless ShouldEnableLinkedRelationshipsTuning is on: each pass adds the top-level rows and every row whose parent is already in the tree. List parents before their children and one pass places everything; otherwise up to DepthForPreparingNodesWithChildren passes are made. In pass n (counting from 0), a row not yet placed whose ParentID is n - 1 is added as a top-level row, so a table that lists children before parents should not use small numbers such as 0 and 1 as UIDs of parent rows.

An organisation chart from a table. Each person's ParentID is their manager's UID.

DataTable staff = new DataTable("Staff");
staff.Columns.Add("UID", typeof(int));
staff.Columns.Add("ID", typeof(int));
staff.Columns.Add("ParentID", typeof(int));
staff.Columns.Add("Name", typeof(string));
staff.Columns.Add("Role", typeof(string));
staff.Columns.Add("Location", typeof(string));

staff.Rows.Add(1, 1, -1, "Helen Ward",   "Chief Executive",      "London");
staff.Rows.Add(2, 1,  1, "Marcus Bell",  "Finance Director",     "London");
staff.Rows.Add(3, 2,  1, "Aisha Khan",   "Engineering Director", "Manchester");
staff.Rows.Add(4, 1,  3, "Owen Price",   "Platform Lead",        "Manchester");
staff.Rows.Add(5, 2,  3, "Lena Fischer", "Mobile Lead",          "Berlin");

org.Columns.Add(new BinaryTreeListViewColumn { HeaderText = "Name" });
org.Columns.Add(new DataGridViewTextBoxColumn { HeaderText = "Role" });
org.Columns.Add(new DataGridViewTextBoxColumn { HeaderText = "Location" });

org.HierarchicalDataSource = staff;
org.ExpandAllNodes();

Gets or sets whether only one cell, rather than the whole row, is coloured to show where a dragged node would be dropped.

With it on, only the row's first cell is coloured – the tree cell when the tree column is the first column.

Gets whether a date cell is being edited and its drop-down calendar is open.

Useful in a key or focus handler of your own, to leave the keys to the calendar while it is open.

Gets or sets the colour of the lines that join the nodes.

A colour between the text and the background – Color.Silver on a white grid, for instance – keeps the lines from competing with the data.

Gets or sets the pattern of the lines that join the nodes: solid, dotted, dashed and so on.

Gets or sets the image shown beside every node's text, between the expand glyph and the text.

A node shows the image set on it through BinaryTreeListViewNode.Image if it has one, and this image otherwise. Setting this property also sets the BinaryTreeListViewNode.Image of each top-level node there is at that moment, replacing theirs – so set it before giving top-level nodes images of their own.

The image is drawn at its own pixel size, not scaled; a 16 by 16 image suits the default row height, which is not changed to fit a larger one. A node with a check box or radio button shows that instead.

accounts.NodeImage = Properties.Resources.Ledger16;            // every account
accounts.Nodes[0].Image = Properties.Resources.Bank16;          // except the bank accounts

Gets the top-level nodes. This is where the tree is built.

Add the columns first. BinaryTreeListViewNodesCollection.Add() takes one value per column, in column order, creates the node and returns it; add its children to its own BinaryTreeListViewNode.Nodes in the same way, to any depth. A top-level node is on show as soon as it is added; a child is on show once its parent is open.

Pass a value that is not null for the tree column on every node; Add can throw a NullReferenceException otherwise.

// Columns: Account (the tree column), Code, Balance.
BinaryTreeListViewNode assets = ledger.Nodes.Add("Assets", "1000", 182500.00m);
BinaryTreeListViewNode bank = assets.Nodes.Add("Bank", "1100", 42750.00m);
bank.Nodes.Add("Current account", "1110", 39250.00m);
bank.Nodes.Add("Savings account", "1120", 3500.00m);
assets.Nodes.Add("Equipment", "1500", 139750.00m);
assets.Expand();

Gets the column the tree is sorted by.

Gets the direction the tree is sorted in.

Gets or sets the order of sibling rows in a tree built from HierarchicalDataSource with ShouldEnableLinkedRelationshipsTuning on: ascending or descending by UID.

NodeSortOrder.Descending orders by descending UID; any other value by ascending UID. Without ShouldEnableLinkedRelationshipsTuning, rows keep the table's order and this has no effect.

Setting it binds the data again when the control has columns and a HierarchicalDataSource. Nodes added in code keep the order they were added in; to sort by a column's values, see SortNodesByColumn.

Gets or sets whether layout is suspended while a dropped branch is moved, so that a large branch moves without the grid laying itself out for every row.

Gets or sets the direction of the gradient the built-in renderer fills the column headings with.

Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the direction of the gradient the built-in renderer fills each cell of a row with, and of the hover highlight.

Each cell is filled on its own, so a horizontal gradient repeats in every cell. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the direction of the gradient the built-in renderer fills the row headings with.

Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the background colour of the row a dragged node is over – the node it would be dropped on.

Applies to the built-in drag and drop (EnableAutomaticBuiltInDragDrop). See HighlightOnlyTreeListCellDuringDragOver for whether the whole row or one cell is coloured.

Gets or sets the text colour of the row a dragged node is over.

Gets or sets the row the grid copies for new rows.

Change its Height or DefaultCellStyle to change every new node; replacing it with a row that is not a BinaryTreeListViewNode breaks the tree.

Gets the grid's rows: the nodes that are on show, in display order.

Do not add or remove rows here; the control keeps this collection in step with Nodes as nodes are added and as they open and close. Rows inside a closed node are not in it.

Gets or sets whether the current cell is outlined with a border of its own while it is not being edited.

The border is drawn in CellBorderColor, CellBorderWidth pixels wide, in place of the grid's dotted focus rectangle. With whole-row selection it marks the cell the keyboard is on – the one F2 edits.

plan.ShouldDrawCellBorderWhenSelected = true;
plan.CellBorderColor = Color.SteelBlue;
plan.CellBorderWidth = 2;

Gets or sets whether the column of the current cell is tinted in ColumnBackgroundOnCellSelectionColor.

The tint follows the column of the current cell. In a tree, where a click selects the whole row, that is the column that was clicked – and, before anything has been clicked, the first column, since the grid makes the first cell current when it is filled. When both column tints apply to the same column, the hover tint wins.

Gets or sets whether the column under the pointer is tinted in ColumnBackgroundOnMouseHoverColor.

The tint is set as the column's DataGridViewColumn.DefaultCellStyle back colour, and put back to ColumnBackgroundDefaultCellStyleBackColor as the pointer leaves. It is hidden while the built-in renderer paints the rows, which fills the cells itself.

// Help the eye follow a column down a wide plan.
plan.ColumnBackgroundOnMouseHoverColor = Color.FromArgb(246, 249, 253);
plan.ShouldDrawColumnBackgroundUponMouseHovering = true;

Gets or sets whether the control draws its own frame: a border with rounded corners, an inner padding and, optionally, a soft drop shadow, all inside its bounds.

The frame replaces DataGridView.BorderStyle: turning it on sets that to BorderStyle.None, and turning it off puts back what it was. It is painted in the control's non-client area, so the headings, the rows and the scroll bars all sit inside it and nothing is drawn over the data.

Outside the border – the shadow and the rounded corners – the control paints the background colour of the nearest parent that has an opaque one, so place it on a parent of a single colour. Inside the border, the padding is DataGridView.BackgroundColor.

The border turns FrameFocusedBorderColor while the focus is in the control. The other settings are FrameBorderColor, FrameBorderThickness, FrameCornerRadius, FramePadding, ShouldDrawFrameShadow, FrameShadowColor, FrameShadowDepth and FrameShadowOpacity.

plan.ShouldDrawFrame = true;
plan.FrameCornerRadius = 8;
plan.FrameBorderColor = Color.FromArgb(200, 208, 220);
plan.FrameFocusedBorderColor = Color.FromArgb(0, 120, 212);
plan.FrameShadowDepth = 8;
plan.FrameShadowOpacity = 12;
plan.BackgroundColor = Color.White;      // the padding inside the border

Gets or sets whether the frame casts a soft drop shadow.

The shadow is drawn inside the control's bounds, so it takes room from the grid on every side, about FrameShadowDepth logical pixels.

Gets or sets whether binding makes a single pass over the data, rather than DepthForPreparingNodesWithChildren passes.

One pass places every row whose parent row comes before it, so it is all a table needs when parents are listed before their children (or, with ShouldEnableLinkedRelationshipsTuning, have smaller UIDs). A row the single pass cannot place is left out. It applies the next time the data is bound.

Gets or sets whether rows from HierarchicalDataSource are placed in the order of their UID rather than the order of the table.

With it on, every UID must be a whole number (a FormatException is thrown otherwise); rows are taken in ascending UID order – descending when NodesSortOrder is NodeSortOrder.Descending – so siblings appear in that order, and a row whose UID repeats an earlier one is left out. When every parent has a smaller UID than its children, the whole tree is built in one pass whatever the order of the table.

It applies the next time the data is bound.

Gets or sets whether the top-level nodes show their image.

Setting it sets BinaryTreeListViewNode.ShowNodeImage on each top-level node there is at that moment, and repaints. Nested nodes, and nodes added afterwards, keep their own setting (true unless changed); set BinaryTreeListViewNode.ShowNodeImage on them to hide theirs.

Gets or sets whether cells of the special editing columns show their editor's chrome on every row, not only on the cell being edited.

With it on, a BinaryTreeListViewDatePickerColumn cell draws its drop-down button, a BinaryTreeListViewNumericUpDownColumn cell its up and down buttons, and a BinaryTreeListViewOffice2007ColorPickerColumn cell its border and drop-down button, so the user can see at a glance which cells are editable and how. Each of those columns' DrawStyleIsFlat chooses between a flat chevron and the classic themed button.

With it off, those cells look like plain text cells until they are edited. A colour cell still shows its swatch. The setting is read as the cells paint; call Control.Invalidate after changing it to see the change at once.

Gets or sets the colour at the top or left of the gradient the built-in renderer fills the column headings with.

The gradient runs from StartColorForRenderingColumnHeader to EndColorForRenderingColumnHeader in the direction OrientationAspectForRenderingColumnHeader gives; set both to the same colour for a flat fill. It is painted while UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement includes the column headings. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the colour at the top or left of the gradient the built-in renderer fills each cell of the rows with.

The gradient runs from StartColorForRenderingRow to EndColorForRenderingRow in the direction OrientationAspectForRenderingRow gives; set both to the same colour for a flat fill. It is painted while UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement includes the rows. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets the colour at the top or left of the gradient the built-in renderer fills the row headings with.

The gradient runs from StartColorForRenderingRowHeader to EndColorForRenderingRowHeader in the direction OrientationAspectForRenderingRowHeader gives; set both to the same colour for a flat fill. It is painted while UseBuiltInRendering is on and BuiltInCustomRenderedTargetElement includes the row headings. Changing it does not repaint the control; call Control.Invalidate to see the change at once.

Gets or sets whether the control paints the parts named by BuiltInCustomRenderedTargetElement itself, in gradients of the colours you choose, instead of leaving them to the grid.

Each part is filled with a linear gradient from its start colour to its end colour, in the direction its orientation property gives, and its text and selection are then drawn over it:

Changing it does not repaint the control; call Control.Invalidate to see the change at once.

// Headings in a soft blue gradient with a rule beneath them; rows left to the grid.
plan.UseBuiltInRendering = true;
plan.BuiltInCustomRenderedTargetElement = BuiltInCustomRenderedTargetElement.ColumnHeader;
plan.StartColorForRenderingColumnHeader = Color.FromArgb(244, 248, 252);
plan.EndColorForRenderingColumnHeader = Color.FromArgb(222, 232, 244);
plan.ColumnHeaderBottomBorderColor = Color.FromArgb(160, 180, 205);
plan.Invalidate();

Gets or sets whether the grid asks for cell values as it needs them rather than holding them.

The same as VirtualMode, except that setting it repaints the control. Nodes hold their own values, so a tree has no use for it.

Shows the control's About box as a modal dialog.

It backs the About entry on the control's design-time menu; an application has no need to call it.

Builds the tree from a table now, without setting HierarchicalDataSource.

Every node is removed first. No busy message is shown, and HierarchicalDataSource is left as it was, so a later change to NodesSortOrder or DepthForPreparingNodesWithChildren does not rebind this table.

Removes every node, at every level, and every row from the control.

The columns stay. Use this rather than Nodes.Clear(), which leaves the rows on show.

Closes every node in the tree, at every level, leaving only the top-level nodes on show.

Nested nodes are closed too, so opening a top-level node afterwards shows its children closed. BinaryTreeListViewNodeCollapsing and BinaryTreeListViewNodeCollapsed are raised for each node that was open.

Closes a node and, if asked, every node beneath it.

Always true.

Raises BinaryTreeListViewNodeCollapsing and BinaryTreeListViewNodeCollapsed for each node that was open.

Closes a node, taking its descendants off the grid.

true when the node was closed; false when it was already closed or a BinaryTreeListViewNodeCollapsing handler cancelled it.

Raises BinaryTreeListViewNodeCollapsing and then BinaryTreeListViewNodeCollapsed. Children keep their own open state for when the node is opened again; to close them as well, use CollapseNode().

Releases the nodes' rows and the control's other resources.

Opens every node in the tree, at every level.

Each node is opened through BinaryTreeListViewNode.Expand(), so BinaryTreeListViewNodeExpanding and BinaryTreeListViewNodeExpanded are raised for each one. A node whose opening a handler cancels stays closed.

expandAllButton.Click += (sender, e) => accounts.ExpandAllNodes();
collapseAllButton.Click += (sender, e) => accounts.CollapseAllNodes();

Opens a node and, if asked, every node beneath it.

Always true.

Each node is opened as ExpandNode() opens it, raising BinaryTreeListViewNodeExpanding and BinaryTreeListViewNodeExpanded; a node a handler keeps closed stays closed, and the return value does not report it.

// Open the whole branch the user is on.
if (plan.CurrentNode != null)
    plan.ExpandNode(plan.CurrentNode, true);

Opens a node, showing its children.

true when the node was opened; false when it was already open or a BinaryTreeListViewNodeExpanding handler cancelled it.

Raises BinaryTreeListViewNodeExpanding and then BinaryTreeListViewNodeExpanded. Children that were themselves open before are shown open.

Open a node only when its parent is open, or when it is a top-level node: the children of a node whose parent is closed are placed at the top of the grid. To open a branch at any depth, use ExpandNode(), which works from the top down.

Returns the nodes that share a parent with the given node.

A new list, in the order the nodes appear under their parent. It is empty for a node that is not in a tree.

Gets every node in the tree, at every level, as one flat sequence.

// Tasks not yet finished, at any depth, whether or not their branch is open.
int outstanding = plan.FlattenedNodes
    .Count(n => !n.HasChildren && ((WorkItem)n.Tag).PercentDone < 100);

Returns every node beneath a node, at every level, as one flat sequence.

A new list in tree order: each child followed by its own descendants. Nodes inside closed branches are included. It is empty for a node with no children.

Returns the node shown at a point in the control.

The node whose row is at that point, or null when the point is on the headings, below the last row, or outside the control.

// Right-click a task to get its context menu.
plan.MouseUp += (sender, e) =>
{
    if (e.Button != MouseButtons.Right)
        return;

    BinaryTreeListViewNode node = plan.GetNodeAt(e.Location);
    if (node != null)
    {
        plan.CurrentCell = node.Cells[0];
        taskMenu.Show(plan, e.Location);
    }
};

Raises the DataGridView.CellMouseDoubleClick event, then opens or closes the node when ExpandCollapseNodeOnDoubleClick is on and the cell is in the tree column.

Raises the DataGridView.CellMouseDown event, noting where a pressed column heading stood, so that a heading dragged to a new place is not also taken as a click to sort.

Raises the DataGridView.CellMouseEnter event, and moves the hover highlight to the row the pointer has entered.

Raises the DataGridView.CellMouseLeave event, and clears the hover highlight from the row the pointer has left.

Raises the DataGridView.CellPainting event, then paints the parts the control draws itself: the built-in gradients and hover highlight, the sort glyph and the current cell's border.

A DataGridView.CellPainting handler runs first. A cell it paints and marks handled is painted over by the built-in renderer when that renderer owns the cell.

Raises the DataGridView.ColumnAdded event, after making the new column NotSortable so that sorting is the control's own (see AllowUserToSortColumns).

Raises the DataGridView.ColumnHeaderMouseClick event, after sorting by the column when AllowUserToSortColumns is on.

The sort is done before the event is raised, so a handler sees the new order.

Raises the DataGridView.ColumnWidthChanged event, then paints any part of the control waiting to be painted.

Raises the DataGridView.DataError event when AllowDataErrorExceptionToBeThrown is on; otherwise ignores the error.

Raises the FontChanged event, and resizes rows that still have their default height so that the new font fits them.

Raises the Control.HandleCreated event, and sizes rows that still have the default height to fit the control's font.

Raises the Control.KeyDown event, and handles the control's own keys: Shift+Right and Shift+Left to open and close the current node, F2 to edit the current cell, and Enter to return to whole-row selection.

The base grid's key handling runs twice for each key press, so a Control.KeyDown handler is called twice for the same key. A handler that sets KeyEventArgs.Handled stops the F2 and Enter handling.

Raises the Control.MouseDown event, notes the node under the pointer for ItemDrag, and restores CellEditingMode when the current cell is not in the tree column.

Raises the Control.MouseLeave event, and clears any hover highlight.

The pointer can leave the control without leaving a cell first – across the border, or when the window loses the mouse – so the highlight is cleared here as well.

Raises the Control.MouseMove event, and raises ItemDrag when a node is dragged far enough.

Raises the Control.MouseUp event.

Raises the Control.ParentChanged event, and starts watching the new parent's size so that the scroll bars are laid out again when it changes.

Raises the DataGridView.RowEnter event, and returns the grid to whole-row selection, selecting the row entered.

Raises the DataGridView.RowsAdded event, after giving each node added its indent, and a height to suit the control's font.

Raises the Control.SizeChanged event.

Gives every node now in the tree a check box, a radio button, or neither.

It sets BinaryTreeListViewNode.CellInfoCheckStatus on every node at every level that exists when it is called; nodes added later start with none, so set theirs as you add them. Check boxes and radio buttons are drawn only on nodes without children, in place of the image, and the user changes them by clicking. The control is not repainted by this call – call Control.Invalidate if it is already on show.

// A list of report sections to include, all ticked to begin with.
reports.SetUpNodeControlType(BinaryTreeListView.NodeControlType.CheckBox);
reports.Invalidate();

// Later: the sections still ticked.
List<string> chosen = reports.FlattenedNodes
    .Where(n => n.CellInfoCheckStatus == CellInfoCheckStatus.CheckBoxCheckedNormal)
    .Select(n => (string)n.Tag)
    .ToList();

Sorts the tree by the values in a column – siblings within their parent, at every level, closed branches included – or, with SortOrder.None, puts back the order the nodes were built in.

Values of the same type that can be compared – numbers, dates, strings – compare as that type; anything else compares by its text in the current culture, ignoring case. Empty values sort first in ascending order. Nodes that compare equal keep their order. Handle DataGridView.SortCompare to decide a comparison yourself: the row indices it is given are -1 for a node that is not on show because its parent is closed.

An edit in progress is committed first, the current node stays current, and the scroll position is kept. Nodes added after a sort are not placed by it; sort again to include them. NodesSortColumn and NodesSortDirection report the result, and the column's heading shows the sort glyph.

// Largest balances first, within each branch.
ledger.SortNodesByColumn(ledger.Columns["Balance"], SortOrder.Descending);

// Sort account codes as numbers, although the cells hold text.
ledger.SortCompare += (sender, e) =>
{
    if (e.Column.Name == "Code")
    {
        e.SortResult = int.Parse((string)e.CellValue1).CompareTo(int.Parse((string)e.CellValue2));
        e.Handled = true;
    }
};

Processes the Windows messages sent to the control's window, reserving and painting the frame when ShouldDrawFrame is on.

The frame's ring is taken off the window before the grid lays out its headings, rows and scroll bars in what is left, and is painted after the default non-client painting.

Occurs when the user presses the mouse button on a cell of the tree column, before the control acts on the click.

BinaryTreeListViewCellClickedEventArgs.BinaryTreeListViewCellClickedArea says which part of the cell was clicked: the expand glyph, the check box or radio button, the image, or the text. Set Cancel to stop what would follow – the node opening or closing, a check box changing, or the cell starting an edit.

The event comes before a check box changes, so BinaryTreeListViewNode.CellInfoCheckStatus still holds the old state in the handler. A radio button with no siblings changes before the event; one with siblings changes after it.

// Open a document when its icon is clicked, and do nothing else with that click.
tree.BinaryTreeListViewCellClicked += (sender, e) =>
{
    if (e.BinaryTreeListViewCellClickedArea == BinaryTreeListViewCellClickedArea.Image)
    {
        OpenDocument((string)e.Node.Tag);
        e.Cancel = true;
    }
};

Occurs after a node has closed and the rows beneath it have been taken out of the grid.

A node keeps its own open or closed state for each of its children, so a child that was open is open again when its parent reopens.

Occurs before an open node closes, whether the user closed it or code did; the closing can be cancelled.

Set Cancel to keep the node open; the call that asked for it then returns false. It is not raised for a node that is already closed.

Occurs after a node has opened and its children have been added to the grid.

Raised once per node opened, so ExpandAllNodes raises it for every node that had to open. It is not raised when BinaryTreeListViewNodeExpanding was cancelled.

Occurs before a node opens, whether the user opened it or code did; the opening can be cancelled.

Set Cancel to keep the node closed; the call that asked for it then returns false. Children added to BinaryTreeListViewNodeExpandingEventArgs.Node inside the handler are shown as the node opens, which is the way to load a large tree only as it is explored.

It is raised for every expand request on a closed node, including one with no children.

Loading a folder's contents the first time it is opened. Each folder is added with one placeholder child, so that it shows an expand glyph.

tree.BinaryTreeListViewNodeExpanding += (sender, e) =>
{
    BinaryTreeListViewNode folder = e.Node;
    if (folder.Nodes.Count != 1 || folder.Nodes[0].Tag != null)
        return;                                   // already loaded

    folder.Nodes.RemoveAt(0);                     // the placeholder
    foreach (string path in Directory.GetFileSystemEntries((string)folder.Tag))
    {
        BinaryTreeListViewNode child = folder.Nodes.Add(Path.GetFileName(path), File.GetLastWriteTime(path));
        child.Tag = path;
    }
};

Occurs when the user starts dragging a node, for drag and drop you handle yourself.

It is raised when Control.AllowDrop is on, EnableAutomaticBuiltInDragDrop is off, and the pointer moves beyond the system drag distance with the left button held down over a node. Item is the BinaryTreeListViewNode pressed on. Call Control.DoDragDrop from the handler to start the drag.

accounts.AllowDrop = true;
accounts.ItemDrag += (sender, e) =>
{
    BinaryTreeListViewNode node = (BinaryTreeListViewNode)e.Item;
    accounts.DoDragDrop(node.Tag, DragDropEffects.Copy);   // hand the account object to another window
};