Implementing Tree Navigators (TreeNavigator)

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

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