Implementing Tree Navigators (TreeNavigator)

A unique navigation control for Windows Forms that provides in-place tree expansion without consuming additional screen space. Items expand and collapse inline, allowing users to drill down through hierarchical structures by clicking items.

When to Use This Skill

Use this skill when you need to:

• Space-Efficient Navigation: Display hierarchical navigation that expands in-place without growing the control size
• Drill-Down Interface: Allow users to navigate from parent to child items with back button navigation
• File Explorer Style: Create file/folder navigation similar to Windows Explorer breadcrumb navigation
• Menu Hierarchies: Build collapsible menu systems with parent-child relationships
• Breadcrumb Navigation: Implement extended mode with stacked headers showing navigation path
• Settings Navigation: Create category-based settings interfaces with hierarchical organization
• Document Browser: Navigate through document structures, sections, and subsections
• TreeView Alternative: Replace standard TreeView with a more compact, focused navigation experience

Component Overview

The TreeNavigator control provides a unique interface for hierarchical navigation:

• Expands tree structures in-place without taking more screen space
• Items collapse automatically when navigating to child items
• Drill down to sub-items by clicking on parent items
• Navigate back to parent levels using back button
• Two navigation modes: Default (single back button) and Extended (breadcrumb-style headers)

Key Capabilities:

• NavigationMode property for selecting navigation style (Default or Extended)
• Items collection for managing TreeMenuItem objects
• Header configuration for customizing header appearance and behavior
• Style property for applying Office 2016/2019 visual themes
• SelectedItem property for programmatic selection
• Selection events for tracking and controlling navigation

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

When to read: Starting new implementation, setting up dependencies, first-time usage, basic TreeNavigator creation

Topics covered:

• Assembly deployment (Syncfusion.Tools.Windows, Syncfusion.Shared.Base)
• NuGet package installation
• Namespace requirements (Syncfusion.Windows.Forms.Tools)
• Adding TreeNavigator via designer (drag-and-drop from toolbox)
• Adding TreeNavigator programmatically in code
• Adding TreeMenuItem items to Items collection
• Header configuration (HeaderText property)
• Adding items through designer (Smart Tag editor)
• Complete setup example with code
• .NET Core workaround for child items

---

Navigation Modes

📄 Read: references/navigation-modes.md

When to read: Choosing navigation behavior, implementing back button navigation, breadcrumb-style interfaces

Topics covered:

• NavigationMode property overview
• Default Mode (single back button, selected item at top)
• Extended Mode (stacked breadcrumb headers, click any level)
• Navigation behavior differences between modes
• Use cases for each mode (simple vs complex hierarchies)
• Code examples for setting navigation mode
• Visual comparison of Default vs Extended modes

---

Appearance and Styling

📄 Read: references/appearance-styling.md

When to read: Customizing visual appearance, applying themes, styling headers, configuring borders and colors

Topics covered:

• Style property (Office2016Colorful/White/Black/DarkGray, Office2019Colorful, Default)
• Visual theme application and comparison
• Header customization (Height, HeaderBackColor, HeaderForeColor, HeaderText, TextBounds)
• ShowHeader property (hide/show header area)
• Border customization (BorderColor, BorderThickness)
• Item spacing (PadY property for gap between items)
• TreeMenuItem appearance (ItemBackColor, ItemHoverColor, SelectedColor, SelectedItemForeColor)
• Text alignment (TextAlign: Center, Left, Right)
• Complete styling examples with code

---

Tree Menu Items

📄 Read: references/tree-menu-items.md

When to read: Managing items, adding/removing TreeMenuItems, building hierarchies, manipulating item collections

Topics covered:

• TreeMenuItem class overview and properties
• Items collection management (Add, Remove, Clear)
• Adding items programmatically (C# and VB.NET)
• Adding items via designer (Smart Tag collection editor)
• Parent-child item relationships and nesting
• Item properties (Text, ItemBackColor, ItemHoverColor, SelectedColor, SelectedItemForeColor)
• Building multi-level hierarchies
• Dynamic item manipulation at runtime
• Complete examples with nested items

---

Selection and Events

📄 Read: references/selection-events.md

When to read: Handling selection changes, responding to navigation, programmatically selecting items, preventing selection

Topics covered:

• SelectedItem property (get/set currently selected item)
• SelectionChanging event (fires before selection changes, cancellable)
• SelectionStateChangingEventArgs (NewValue, OldValue, Expanded, Cancel properties)
• SelectionChanged event (fires after selection changes)
• SelectionStateChangedEventArgs (SelectedItem, Expanded properties)
• Event handling examples with code
• Cancelling selection changes (validation scenarios)
• Touch scroll behavior (UseTouchScrollBehavior property)
• Complete event workflow examples

---

Quick Start Example

File Explorer-Style Navigation with Office2016 Theme

using Syncfusion.Windows.Forms.Tools;

// Create TreeNavigator
TreeNavigator treeNavigator = new TreeNavigator();
treeNavigator.Size = new Size(250, 400);
treeNavigator.Header.HeaderText = "This PC";
treeNavigator.Style = TreeNavigatorStyle.Office2016Colorful;
treeNavigator.NavigationMode = NavigationMode.Extended;

// Add root items
TreeMenuItem desktop = new TreeMenuItem { Text = "Desktop" };
TreeMenuItem documents = new TreeMenuItem { Text = "Documents" };
TreeMenuItem downloads = new TreeMenuItem { Text = "Downloads" };

// Add items to TreeNavigator
treeNavigator.Items.Add(desktop);
treeNavigator.Items.Add(documents);
treeNavigator.Items.Add(downloads);

// Add child items to Documents
TreeMenuItem workFiles = new TreeMenuItem { Text = "Work Files" };
TreeMenuItem personalFiles = new TreeMenuItem { Text = "Personal Files" };
documents.Items.Add(workFiles);
documents.Items.Add(personalFiles);

this.Controls.Add(treeNavigator);

Imports Syncfusion.Windows.Forms.Tools

' Create TreeNavigator
Dim treeNavigator As New TreeNavigator()
treeNavigator.Size = New Size(250, 400)
treeNavigator.Header.HeaderText = "This PC"
treeNavigator.Style = TreeNavigatorStyle.Office2016Colorful
treeNavigator.NavigationMode = NavigationMode.Extended

' Add root items
Dim desktop As New TreeMenuItem With {.Text = "Desktop"}
Dim documents As New TreeMenuItem With {.Text = "Documents"}
Dim downloads As New TreeMenuItem With {.Text = "Downloads"}

' Add items to TreeNavigator
treeNavigator.Items.Add(desktop)
treeNavigator.Items.Add(documents)
treeNavigator.Items.Add(downloads)

' Add child items to Documents
Dim workFiles As New TreeMenuItem With {.Text = "Work Files"}
Dim personalFiles As New TreeMenuItem With {.Text = "Personal Files"}
documents.Items.Add(workFiles)
documents.Items.Add(personalFiles)

Me.Controls.Add(treeNavigator)

---

Common Patterns

Pattern 1: Settings Navigation with Custom Colors

// Create TreeNavigator for settings
TreeNavigator settingsNav = new TreeNavigator();
settingsNav.Header.HeaderText = "Settings";
settingsNav.Style = TreeNavigatorStyle.Office2016White;
settingsNav.NavigationMode = NavigationMode.Default;

// Customize appearance
settingsNav.Header.HeaderBackColor = Color.FromArgb(0, 120, 215);
settingsNav.Header.HeaderForeColor = Color.White;
settingsNav.ItemBackColor = Color.WhiteSmoke;

// Add settings categories
TreeMenuItem general = new TreeMenuItem { Text = "General" };
TreeMenuItem appearance = new TreeMenuItem { Text = "Appearance" };
TreeMenuItem advanced = new TreeMenuItem { Text = "Advanced" };

settingsNav.Items.Add(general);
settingsNav.Items.Add(appearance);
settingsNav.Items.Add(advanced);

// Add sub-settings
general.Items.Add(new TreeMenuItem { Text = "Language" });
general.Items.Add(new TreeMenuItem { Text = "Startup" });
appearance.Items.Add(new TreeMenuItem { Text = "Theme" });
appearance.Items.Add(new TreeMenuItem { Text = "Colors" });

Pattern 2: Breadcrumb Navigation with Selection Event

// Create breadcrumb-style navigator
TreeNavigator breadcrumbNav = new TreeNavigator();
breadcrumbNav.NavigationMode = NavigationMode.Extended;
breadcrumbNav.Style = TreeNavigatorStyle.Office2016Colorful;

// Handle selection changes
breadcrumbNav.SelectionChanged += (sender, e) => {
    TreeMenuItem selected = e.SelectedItem;
    bool isExpanded = e.Expanded;
    
    // Update content panel based on selection
    MessageBox.Show($"Navigated to: {selected.Text}\nExpanded: {isExpanded}");
};

// Build hierarchy
TreeMenuItem root = new TreeMenuItem { Text = "Home" };
breadcrumbNav.Items.Add(root);
TreeMenuItem level1 = new TreeMenuItem { Text = "Category" };
TreeMenuItem level2 = new TreeMenuItem { Text = "Subcategory" };
root.Items.Add(level1);
level1.Items.Add(level2);

Pattern 3: Compact Navigation Menu with Item Hover Colors

// Create compact navigation
TreeNavigator compactNav = new TreeNavigator();
compactNav.ShowHeader = false; // Hide header for compact look
compactNav.Style = TreeNavigatorStyle.Office2016DarkGray;
compactNav.PadY = 5; // Reduce spacing between items

// Customize item colors
TreeMenuItem dashboard = new TreeMenuItem 
{ 
    Text = "Dashboard",
    ItemBackColor = Color.FromArgb(45, 45, 48),
    ItemHoverColor = Color.FromArgb(62, 62, 66),
    SelectedColor = Color.FromArgb(0, 122, 204)
};

TreeMenuItem reports = new TreeMenuItem 
{ 
    Text = "Reports",
    ItemBackColor = Color.FromArgb(45, 45, 48),
    ItemHoverColor = Color.FromArgb(62, 62, 66)
};

compactNav.Items.Add(dashboard);
compactNav.Items.Add(reports);

// Add report sub-items
reports.Items.Add(new TreeMenuItem { Text = "Sales" });
reports.Items.Add(new TreeMenuItem { Text = "Inventory" });
reports.Items.Add(new TreeMenuItem { Text = "Analytics" });

---

Key Properties

Property	Type	Description
Items	Collection	Collection of TreeMenuItem objects that form the navigation hierarchy
NavigationMode	NavigationMode	Navigation style: Default (back button) or Extended (breadcrumb)
Style	TreeNavigatorStyle	Visual theme: Office2016Colorful/White/Black/DarkGray, Office2019Colorful, Default
SelectedItem	TreeMenuItem	Gets or sets the currently selected item in the current hierarchy level
Header.HeaderText	string	Text displayed in the header area
Header.HeaderBackColor	Color	Background color of the header
Header.HeaderForeColor	Color	Foreground (text) color of the header
Header.Height	int	Height of the header area in pixels
ShowHeader	bool	Shows or hides the header area (true = visible, false = hidden)
BorderColor	Color	Color of the control border
BorderThickness	int	Thickness of the control border in pixels
PadY	int	Vertical spacing (gap) between TreeMenuItem items
ItemBackColor	Color	Background color for all TreeMenuItem items (can be overridden per item)
TextAlign	TextAlignment	Text alignment for items: Center, Left, or Right
UseTouchScrollBehavior	bool	Enables touch-friendly scrolling with auto-hide scrollbar

---

Common Use Cases

1. File/Folder Browser: Navigate through folder hierarchies like Windows Explorer with back button or breadcrumb navigation
2. Settings Interface: Organize application settings into categories and subcategories with drill-down navigation
3. Document Outline: Navigate through document sections, chapters, and subsections
4. Menu Navigation: Create hierarchical menu systems for complex applications with space constraints
5. Product Categories: Browse product catalogs with category → subcategory → product navigation
6. Help System: Organize help topics into categories with easy navigation between topics and back to categories
7. Data Dashboard: Navigate between dashboard sections, reports, and detailed views
8. Workflow Steps: Guide users through multi-step workflows with hierarchical organization

---

Additional Resources

• TreeNavigator Control on Syncfusion Help
• Syncfusion.Windows.Forms.Tools Namespace
• TreeNavigator API Reference
• TreeMenuItem API Reference