Skip to content

Node visibility

By default, all newly added nodes are visible in the treeview, but Flexible TreeView allows you to control each node's visibility in a very flexible way.

Below are the main members that are used to control the nodes' visibility:

  • Treeview.Options.Node.FilterMode - enable or disable the nodes' visibility filtering in the whole treeview.
  • Node.Visible - defines the node's explicit visibility state.
  • Node.VisibilityFilter - defines a callback that is called to get the node's visibility state.
  • Treeview.NodeVisibilityFilter - defines an across-treeview callback that is called to get the node's visibility state.

Important

The above properties are evaluated in the order they appear in this list to calculate the node visibility state.

Also, below are the additional members that are used in conjunction with the above main members to invalidate or check the node visibility:

  • Node.InvalidateVisibility - invalidates the specific node visibility state.
  • Treeview.InvalidateNodesVisibility - invalidates the whole treeview nodes' visibility state.
  • Node.IsVisible - gets the specific node's visibility state after applying all its visibility filters.
  • Node.IsNodeVisible - a protected virtual method that evaluates all node visibility filters and returns the node's visibility final state. Called when the node visibility state has changed or is forced to recalculate from outside. Could be overridden to manually override the node's visibility final state.
  • Node.EnsureVisible - makes the node visible within the treeview's view area.

Get started#

By default, all nodes are visible and the Options.Node.FilterMode treeview property is equal to eNodeFilterMode.Disabled. In this state, any changes to nodes visibility won't have any effect.

To start changing nodes visibility, firstly set the Treeview.Options.Node.FilterMode property value to eNodeFilterMode.Enabled.

Each node's visibility state is cached and is not re-evaluated later on without forcing it to do so via the node.InvalidateVisibility and the treeview.InvalidateNodesVisibility methods, or by changing the node's Visible or VisibilityFilter property values.

When the node becomes invisible, it is automatically moved from the parent child nodes list, available via the Nodes property, to a back-buffer where it is stored until it becomes visible or is removed from the parent node. This back buffer with hidden child nodes is available via the parentNode.Nodes.Filtered collection property. Hidden nodes in this collection may be managed as normal nodes, i.e., their Parent or TreeView property values are kept; they could be moved to another parent node without making them visible, or they could be detached from the treeview.

When a node becomes hidden or visible, i.e., when it moves between parentNode.Nodes and parentNode.Nodes.Filtered collections, the NodeInserted and NodeRemoved treeview events are not fired.

The node visibility state is calculated by evaluating the above main members in the order they appear in the list. That is, the Options.Node.FilterMode treeview property value is checked to be eNodeFilterMode.Enabled; if so, the Visible node property is checked to be not null; if so, its value is used; otherwise, the VisibilityFilter node property is checked to be not null; if so, this function is called and its result is used; and finally, the NodeVisibilityFilter treeview callback method is evaluated. If none of these parts has returned a boolean value that defines node visibility, the node is considered visible.

When an invisible node becomes visible, it is restored to the same position in the parent nodes list as it was when it was hidden.

If a node was hidden, the parent nodes collection was changed, and this node was shown, its position in the parent nodes list will be different compared to when it was visible!

To check whether the node is visible or not at the moment, the IsVisible node property should be used.

The nodes visibility changes do not affect the overall treeview performance, but to keep the performance on the same level as when all nodes are visible, read the Performance suggestions section.

Treeview.Options.Node.FilterMode#

The Options.Node.FilterMode treeview property is used to enable or disable the nodes visibility filtering in the treeview. By default, it is set to ARMSoft.FlexibleTreeView.eNodeFilterMode.Disabled, which disables the nodes visibility filtering and all nodes are visible.

To change some node's visibility, firstly set the Options.Node.FilterMode property to ARMSoft.FlexibleTreeView.eNodeFilterMode.Enabled and set the desired node visibility as shown below.

Node node = new Node("Customer name");
node.AttachTo(tree);

tree.Options.Node.FilterMode = ARMSoft.FlexibleTreeView.eNodeFilterMode.Enabled;

node.Visible = false;

Dim node As New Node("Customer name")
node.AttachTo(tree)

tree.Options.Node.FilterMode = ARMSoft.FlexibleTreeView.eNodeFilterMode.Enabled

node.Visible = False

When the Options.Node.FilterMode property changes, Flexible TreeView recalculates the visibility state for all nodes in the treeview and caches this state for each node. The cached visibility state is auto-recalculated only when one of the below actions has happened:

  • node.Visible property value has changed.
  • node.VisibilityFilter property value has changed.
  • node.InvalidateVisibility method has been called.
  • treeview.InvalidateNodesVisibility method has been called.
  • treeview.NodeVisibilityFilter property value has changed.

Node.Visible#

If the nodes visibility filtering is enabled, the Visible node property is the first stage that is evaluated when deciding whether the node is visible or not.

When this property value is null (by default), Flexible TreeView evaluates further stages, as described above. When its value is false or true, the node is considered hidden or visible, respectively.

The Visible property can be changed even if the node is not attached to a treeview. When its value changes, the node visibility state is recalculated and cached again.

Node.VisibilityFilter#

The VisibilityFilter node property is used to define a function that determines the particular node visibility. It differs from the Visible node property in that it is performed at runtime, and the visibility state is decided based on some data now available at compile time.

The VisibilityFilter property can be changed even if the node is not attached to a treeview. When its value changes, the node visibility state is recalculated and cached again.

When some data that was used in this function changes, the InvalidateVisibility node method should be called to reevaluate and cache the node visibility, as shown below.

NodeTextBox textCtrl = new NodeTextBox();
textCtrl.AttachTo(tree);

tree.Options.Node.FilterMode = eNodeFilterMode.Enabled;

Node node = new Node("john lennon");
node.AttachTo(tree);
string nodeFilterText = "john";
// Node will be visible
node.VisibilityFilter = n => { return n.Text.IndexOf(nodeFilterText) != -1; };

// Node will be hidden
nodeFilterText = "smith";
node.InvalidateVisibility();

Dim textCtrl As New NodeTextBox()
textCtrl.AttachTo(tree)

tree.Options.Node.FilterMode = eNodeFilterMode.Enabled

Dim node As New Node("john lennon")
node.AttachTo(tree)
Dim nodeFilterText As String = "john"
' Node will be visible
node.VisibilityFilter = GetNodeVisibility

' Node will be hidden
nodeFilterText = "smith"
node.InvalidateVisibility()

Private Function GetNodeVisibility(node As Node) As Boolean
    Return node.Text.IndexOf(nodeFilterText) <> -1
End Function

Node.InvalidateVisibility#

The node visibility state is calculated only once and cached to keep the treeview performance on a high level. When the VisibilityFilter node or NodeVisibilityFilter treeview properties are used to control the nodes' visibility via callback functions, those functions could use an external data to decide whether the particular node is visible. When this data changes, Flexible TreeView won't know this, as it doesn't call these callbacks each time but only once.

To invalidate the particular node visibility state after an external data changes, the InvalidateVisibility node method should be used. It reevaluates all the node visibility filters, calculates its visibility state, and caches it again.

Below is a sample code that demonstrates how to use the InvalidateVisibility method.

NodeTextBox textCtrl = new NodeTextBox();
textCtrl.AttachTo(tree);

tree.Options.Node.FilterMode = eNodeFilterMode.Enabled;

Node node = new Node("john lennon");
node.AttachTo(tree);
string nodeFilterText = "john";
// Node will be visible
node.VisibilityFilter = n => { return n.Text.IndexOf(nodeFilterText) != -1; };

// Node will be hidden
nodeFilterText = "smith";
node.InvalidateVisibility();

Dim textCtrl As New NodeTextBox()
textCtrl.AttachTo(tree)

tree.Options.Node.FilterMode = eNodeFilterMode.Enabled

Dim node As New Node("john lennon")
node.AttachTo(tree)
Dim nodeFilterText As String = "john"
' Node will be visible
node.VisibilityFilter = GetNodeVisibility

' Node will be hidden
nodeFilterText = "smith"
node.InvalidateVisibility()

Private Function GetNodeVisibility(node As Node) As Boolean
    Return node.Text.IndexOf(nodeFilterText) <> -1
End Function

Treeview.NodeVisibilityFilter#

The NodeVisibilityFilter treeview property does the same as the VisibilityFilter node property, but it is called for all nodes in the treeview when calculating their visibility state.

Because the NodeVisibilityFilter callback is called for each node, be very careful with what you inspect or do in this callback; try don't perform any long-running checks, and use only the cached data if possible, etc.

Treeview.InvalidateNodesVisibility#

The InvalidateNodesVisibility treeview method does the same as the InvalidateVisibility node method, but it recalculates the visibility state for all nodes in the treeview.

Node visibility with data binding#

The nodes visibility control in Flexible TreeView is designed in such a way that it could be enabled for the data-bound treeview in the same way as for a non-data-bound one.

I.e., just set the Options.Node.FilterMode property value to eNodeFilterMode.Enabled and follow the above advice on how to define your node visibility filters.

Node.EnsureVisible#

The Node.EnsureVisible method is used to make an already visible node visible within the treeview view area. It makes the node navigation much faster for the end-user.

The EnsureVisible method supports the nodeAlign optional parameter which, if not specified (by default), forces the treeview to display the node as fast as possible. On the other hand, if the nodeAlign parameter is specified, it forces the treeview to align its view area accordingly, i.e., if nodeAlign is VerticalAlignment.Top, then the specified node will be the first node in the treeview's view area; for VerticalAlignment.Bottom, it will be the last node; and for VerticalAlignment.Center, the specified node will be in the center of the treeview view area.

Performance suggestions#

Below are some tips and suggestions on how to keep your treeview performance high, whether with filtered-out nodes or without them:

  • When changing the visibility of many nodes, call the BeginUpdate treeview method prior to these changes and the EndUpdate after them. It will reduce the treeview repainting overhead a lot.
  • Because the node visibility state is cached and not re-evaluated later again, hiding the node(s) won't decrease the treeview performance in runtime.
  • If you set the NodeVisibilityFilter treeview property with some callback filter and there are a lot of nodes in the treeview, the visibility invalidation process could be quite time-consuming. To speed it up a bit, move the filtering logic from the NodeVisibilityFilter treeview property to the IsNodeVisible treeview virtual method by overriding the latter.
  • If you need to hide a parent node and some of its child nodes, change the child nodes visibility prior to the parent node.