references/advanced-features.md
# Advanced Features
This guide covers advanced GroupBar features including nested GroupBars, in-place renaming, serialization, localization, and custom control hosting. Master these techniques to build sophisticated navigation interfaces.
## Table of Contents
- [Nested GroupBar Support](#nested-groupbar-support)
- [In-Place Renaming of GroupBarItems](#in-place-renaming-of-groupbaritems)
- [Serialization of Layout State](#serialization-of-layout-state)
- [Localization Support](#localization-support)
- [Link Selection in GroupView](#link-selection-in-groupview)
- [Custom Control Hosting](#custom-control-hosting)
- [Event Handling](#event-handling)
- [AllowCollapse Property](#allowcollapse-property)
- [Complete Advanced Scenarios](#complete-advanced-scenarios)
## Nested GroupBar Support
GroupBar controls can be nested within each other, creating hierarchical navigation structures.
### Creating Nested GroupBars
A nested GroupBar is simply a GroupBar control hosted as the client of a GroupBarItem.
```csharp
// Parent GroupBar
GroupBar parentGroupBar = new GroupBar
{
Dock = DockStyle.Left,
Width = 220
};
// Child GroupBar (nested)
GroupBar childGroupBar = new GroupBar
{
Dock = DockStyle.Fill
};
// Add items to child GroupBar
childGroupBar.GroupBarItems.AddRange(new GroupBarItem[]
{
new GroupBarItem { Text = "Nested Item 1" },
new GroupBarItem { Text = "Nested Item 2" },
new GroupBarItem { Text = "Nested Item 3" }
});
// Create parent item to host child GroupBar
GroupBarItem parentItem = new GroupBarItem
{
Text = "Nested Navigation",
Client = childGroupBar
};
// Add child GroupBar to parent's controls
parentGroupBar.Controls.Add(childGroupBar);
parentGroupBar.GroupBarItems.Add(parentItem);
// Add parent to form
this.Controls.Add(parentGroupBar);
```
**When to use nested GroupBars:**
- Multi-level navigation hierarchies
- Sub-categories within categories
- Department → Team → Project navigation
- Document management with deep folder structures
### Complete Nested GroupBar Example
```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
public class NestedGroupBarForm : Form
{
private GroupBar mainGroupBar;
public NestedGroupBarForm()
{
this.Text = "Nested GroupBar Example";
this.Size = new Size(900, 700);
CreateNestedNavigation();
}
private void CreateNestedNavigation()
{
// Create main GroupBar
this.mainGroupBar = new GroupBar
{
Dock = DockStyle.Left,
Width = 240,
BorderStyle = BorderStyle.Fixed3D,
Font = new Font("Segoe UI", 9F)
};
// Create standard sections
CreateStandardSection("Dashboard");
CreateStandardSection("Reports");
// Create nested section
CreateNestedSection();
// More standard sections
CreateStandardSection("Settings");
this.mainGroupBar.SelectedItem = 0;
this.Controls.Add(this.mainGroupBar);
}
private void CreateStandardSection(string name)
{
GroupBarItem item = new GroupBarItem { Text = name };
Panel panel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White,
Padding = new Padding(10)
};
Label label = new Label
{
Text = $"{name} Content",
Dock = DockStyle.Top,
Font = new Font("Segoe UI", 12F, FontStyle.Bold)
};
panel.Controls.Add(label);
item.Client = panel;
this.mainGroupBar.Controls.Add(panel);
this.mainGroupBar.GroupBarItems.Add(item);
}
private void CreateNestedSection()
{
GroupBarItem parentItem = new GroupBarItem
{
Text = "Organization"
};
// Create nested GroupBar
GroupBar nestedGroupBar = new GroupBar
{
Dock = DockStyle.Fill,
BorderStyle = BorderStyle.None,
Font = new Font("Segoe UI", 8.5F)
};
// Add departments with GroupViews
CreateDepartmentSection(nestedGroupBar, "Sales", new string[]
{
"North Region",
"South Region",
"East Region",
"West Region"
});
CreateDepartmentSection(nestedGroupBar, "Marketing", new string[]
{
"Digital Marketing",
"Content Team",
"Social Media",
"Analytics"
});
CreateDepartmentSection(nestedGroupBar, "Engineering", new string[]
{
"Frontend Team",
"Backend Team",
"DevOps",
"QA Team"
});
// Assign nested GroupBar as client
parentItem.Client = nestedGroupBar;
this.mainGroupBar.Controls.Add(nestedGroupBar);
this.mainGroupBar.GroupBarItems.Add(parentItem);
}
private void CreateDepartmentSection(GroupBar parentBar, string deptName, string[] teams)
{
GroupBarItem deptItem = new GroupBarItem { Text = deptName };
GroupView teamView = new GroupView { Name = $"{deptName}View" };
foreach (string team in teams)
{
teamView.GroupViewItems.Add(new GroupViewItem(team, -1, true, null, team));
}
teamView.GroupViewItemSelected += (s, e) =>
{
GroupView view = s as GroupView;
if (view != null && view.SelectedItem >= 0)
{
string selected = view.GroupViewItems[view.SelectedItem].Text;
MessageBox.Show($"Selected: {deptName} - {selected}", "Team Selection");
}
};
deptItem.Client = teamView;
parentBar.Controls.Add(teamView);
parentBar.GroupBarItems.Add(deptItem);
}
}
```
**Result:** A three-level navigation structure: Main sections → Departments → Teams.
## In-Place Renaming of GroupBarItems
Allow users to rename GroupBarItems at runtime.
### Enabling In-Place Renaming
```csharp
// Trigger rename for specific item
private void RenameItem(int itemIndex)
{
if (itemIndex >= 0 && itemIndex < this.groupBar1.GroupBarItems.Count)
{
this.groupBar1.InplaceRenameItem(itemIndex);
}
}
// Cancel rename operation
private void CancelRename()
{
this.groupBar1.CancelInplaceRenameItem();
}
```
### Handling Rename Events
```csharp
// Wire up rename event
this.groupBar1.GroupBarItemRenamed += GroupBar1_GroupBarItemRenamed;
private void GroupBar1_GroupBarItemRenamed(object sender,
Syncfusion.Windows.Forms.Tools.GroupItemRenamedEventArgs e)
{
int itemIndex = e.Index;
string oldName = e.OldLabel;
string newName = e.NewLabel;
Console.WriteLine($"Item {itemIndex} renamed from '{oldName}' to '{newName}'");
// Validate new name
if (string.IsNullOrWhiteSpace(newName))
{
MessageBox.Show("Item name cannot be empty.", "Invalid Name",
MessageBoxButtons.OK, MessageBoxIcon.Warning);
// Revert to old name
this.groupBar1.GroupBarItems[itemIndex].Text = oldName;
return;
}
// Check for duplicates
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
if (item.Text == newName && this.groupBar1.GroupBarItems.IndexOf(item) != itemIndex)
{
MessageBox.Show("An item with this name already exists.", "Duplicate Name",
MessageBoxButtons.OK, MessageBoxIcon.Warning);
// Revert to old name
this.groupBar1.GroupBarItems[itemIndex].Text = oldName;
return;
}
}
// Save renamed item to database or config
SaveItemName(itemIndex, newName);
}
private void SaveItemName(int index, string name)
{
// Save to database or configuration file
Console.WriteLine($"Saving: Item {index} = {name}");
}
```
### Complete Rename Example
```csharp
public class RenameableNavigationForm : Form
{
private GroupBar groupBar1;
private ContextMenuStrip itemContextMenu;
public RenameableNavigationForm()
{
this.Text = "Renameable Navigation";
this.Size = new Size(800, 600);
SetupRenameableGroupBar();
}
private void SetupRenameableGroupBar()
{
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 220,
Font = new Font("Segoe UI", 9F)
};
// Create items
for (int i = 1; i <= 5; i++)
{
GroupBarItem item = new GroupBarItem
{
Text = $"Category {i}"
};
Panel panel = new Panel { Dock = DockStyle.Fill, BackColor = Color.White };
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
}
// Handle rename event
this.groupBar1.GroupBarItemRenamed += GroupBar1_ItemRenamed;
// Create context menu for rename
CreateRenameContextMenu();
// Enable right-click on items
this.groupBar1.MouseClick += GroupBar1_MouseClick;
this.Controls.Add(this.groupBar1);
}
private void CreateRenameContextMenu()
{
this.itemContextMenu = new ContextMenuStrip();
ToolStripMenuItem renameItem = new ToolStripMenuItem("Rename");
renameItem.Click += (s, e) =>
{
// Rename currently selected item
int selectedIndex = this.groupBar1.SelectedItem;
if (selectedIndex >= 0)
{
this.groupBar1.InplaceRenameItem(selectedIndex);
}
};
this.itemContextMenu.Items.Add(renameItem);
}
private void GroupBar1_MouseClick(object sender, MouseEventArgs e)
{
if (e.Button == MouseButtons.Right)
{
// Show context menu
this.itemContextMenu.Show(this.groupBar1, e.Location);
}
}
private void GroupBar1_ItemRenamed(object sender, GroupItemRenamedEventArgs e)
{
string newName = e.NewLabel;
// Validate
if (string.IsNullOrWhiteSpace(newName))
{
MessageBox.Show("Name cannot be empty.");
this.groupBar1.GroupBarItems[e.Index].Text = e.OldLabel;
return;
}
// Check length
if (newName.Length > 50)
{
MessageBox.Show("Name is too long (max 50 characters).");
this.groupBar1.GroupBarItems[e.Index].Text = e.OldLabel;
return;
}
Console.WriteLine($"Renamed: '{e.OldLabel}' → '{newName}'");
}
}
```
## Serialization of Layout State
Save and restore the GroupBar's layout configuration.
### Saving Layout State
```csharp
using Syncfusion.Runtime.Serialization;
private void SaveGroupBarLayout()
{
// Create storage object
ArrayList layoutData = new ArrayList();
// Save navigation pane items (for stacked mode)
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
if (item.InNavigationPane)
{
int index = this.groupBar1.GroupBarItems.IndexOf(item);
layoutData.Add(index);
}
}
// Save selected item
layoutData.Add(this.groupBar1.SelectedItem);
// Save collapsed state
layoutData.Add(this.groupBar1.Collapsed);
// Save stacked mode
layoutData.Add(this.groupBar1.StackedMode);
// Save dimensions
layoutData.Add(this.groupBar1.Width);
// Serialize to XML file
string configPath = GetConfigFilePath();
Directory.CreateDirectory(Path.GetDirectoryName(configPath));
AppStateSerializer serializer = new AppStateSerializer(
SerializeMode.XMLFile,
configPath
);
serializer.SerializeObject("GroupBarLayout", layoutData);
serializer.PersistNow();
Console.WriteLine($"Layout saved to: {configPath}");
}
private string GetConfigFilePath()
{
string appData = Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);
return Path.Combine(appData, "MyApplication", "GroupBarLayout.xml");
}
```
### Loading Layout State
```csharp
private void LoadGroupBarLayout()
{
try
{
string configPath = GetConfigFilePath();
if (!File.Exists(configPath))
{
Console.WriteLine("No saved layout found");
return;
}
// Deserialize from XML
AppStateSerializer serializer = new AppStateSerializer(
SerializeMode.XMLFile,
configPath
);
ArrayList layoutData = serializer.DeserializeObject("GroupBarLayout") as ArrayList;
if (layoutData == null || layoutData.Count < 5)
{
Console.WriteLine("Invalid layout data");
return;
}
// Restore stacked mode (index count - 3)
bool stackedMode = (bool)layoutData[layoutData.Count - 2];
this.groupBar1.StackedMode = stackedMode;
// Restore width
int width = (int)layoutData[layoutData.Count - 1];
this.groupBar1.Width = width;
// Reset navigation pane items
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
item.InNavigationPane = false;
}
// Restore navigation pane items
int navItemCount = layoutData.Count - 4; // Exclude selectedItem, collapsed, stacked, width
for (int i = 0; i < navItemCount; i++)
{
int itemIndex = (int)layoutData[i];
if (itemIndex >= 0 && itemIndex < this.groupBar1.GroupBarItems.Count)
{
this.groupBar1.GroupBarItems[itemIndex].InNavigationPane = true;
}
}
// Restore selected item
int selectedItem = (int)layoutData[layoutData.Count - 4];
if (selectedItem >= 0 && selectedItem < this.groupBar1.GroupBarItems.Count)
{
this.groupBar1.SelectedItem = selectedItem;
}
// Restore collapsed state
bool collapsed = (bool)layoutData[layoutData.Count - 3];
this.groupBar1.Collapsed = collapsed;
Console.WriteLine("Layout loaded successfully");
}
catch (Exception ex)
{
Console.WriteLine($"Error loading layout: {ex.Message}");
}
}
```
### Auto-Save/Load Pattern
```csharp
private void Form1_Load(object sender, EventArgs e)
{
// Load layout on startup
LoadGroupBarLayout();
}
private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
// Save layout on exit
SaveGroupBarLayout();
}
```
## Localization Support
Localize GroupBar text and tooltips for international users.
### Resource-Based Localization
```csharp
// Create resource files: Strings.resx, Strings.fr-FR.resx, Strings.es-ES.resx
private void ApplyLocalization(string cultureName)
{
// Set culture
System.Threading.Thread.CurrentThread.CurrentUICulture =
new System.Globalization.CultureInfo(cultureName);
// Update item texts from resources
this.groupBarItem1.Text = Properties.Resources.Navigation_Mail;
this.groupBarItem2.Text = Properties.Resources.Navigation_Calendar;
this.groupBarItem3.Text = Properties.Resources.Navigation_Contacts;
this.groupBarItem4.Text = Properties.Resources.Navigation_Tasks;
// Update tooltips
this.groupBar1.NavigationPaneTooltip = Properties.Resources.Tooltip_NavigationPane;
this.groupBar1.ExpandButtonToolTip = Properties.Resources.Tooltip_Expand;
this.groupBar1.MinimizeButtonToolTip = Properties.Resources.Tooltip_Minimize;
Console.WriteLine($"Localized to: {cultureName}");
}
```
### Complete Localization Example
```csharp
public class LocalizedGroupBarForm : Form
{
private GroupBar groupBar1;
private ComboBox languageSelector;
public LocalizedGroupBarForm()
{
this.Text = "Localized Navigation";
this.Size = new Size(800, 600);
CreateLanguageSelector();
CreateLocalizedGroupBar();
}
private void CreateLanguageSelector()
{
this.languageSelector = new ComboBox
{
Dock = DockStyle.Top,
DropDownStyle = ComboBoxStyle.DropDownList
};
this.languageSelector.Items.AddRange(new object[]
{
"English (en-US)",
"French (fr-FR)",
"Spanish (es-ES)",
"German (de-DE)"
});
this.languageSelector.SelectedIndexChanged += (s, e) =>
{
string culture = ExtractCulture(this.languageSelector.SelectedItem.ToString());
ApplyLocalization(culture);
};
this.Controls.Add(this.languageSelector);
this.languageSelector.SelectedIndex = 0;
}
private void CreateLocalizedGroupBar()
{
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 220
};
// Create items (texts will be set by localization)
for (int i = 0; i < 4; i++)
{
GroupBarItem item = new GroupBarItem();
Panel panel = new Panel { Dock = DockStyle.Fill, BackColor = Color.White };
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
}
this.Controls.Add(this.groupBar1);
}
private string ExtractCulture(string text)
{
// Extract culture code from display text
int start = text.IndexOf('(') + 1;
int end = text.IndexOf(')');
return text.Substring(start, end - start);
}
private void ApplyLocalization(string cultureName)
{
// In real application, use resource files
// For demo, use hardcoded translations
Dictionary<string, string[]> translations = new Dictionary<string, string[]>
{
{ "en-US", new[] { "Mail", "Calendar", "Contacts", "Tasks" } },
{ "fr-FR", new[] { "Courrier", "Calendrier", "Contacts", "Tâches" } },
{ "es-ES", new[] { "Correo", "Calendario", "Contactos", "Tareas" } },
{ "de-DE", new[] { "E-Mail", "Kalender", "Kontakte", "Aufgaben" } }
};
if (translations.ContainsKey(cultureName))
{
string[] labels = translations[cultureName];
for (int i = 0; i < labels.Length && i < this.groupBar1.GroupBarItems.Count; i++)
{
this.groupBar1.GroupBarItems[i].Text = labels[i];
}
}
this.Text = $"Localized Navigation - {cultureName}";
}
}
```
## Link Selection in GroupView
Configure how items are selected in GroupView controls.
### Single vs Multiple Selection
```csharp
// Single selection (default)
// Only one item can be selected at a time
// Multiple selection
groupView.MultiSelect = true; // If supported by version
```
### Programmatic Selection
```csharp
// Select item by index
groupView.SelectedItem = 2;
// Clear selection
groupView.SelectedItem = -1;
```
## Custom Control Hosting
Host any .NET control as a GroupBarItem client.
### Hosting DataGridView
```csharp
private void HostDataGridView()
{
GroupBarItem dataItem = new GroupBarItem
{
Text = "Data View"
};
DataGridView grid = new DataGridView
{
Dock = DockStyle.Fill,
AutoGenerateColumns = true,
AllowUserToAddRows = false
};
// Populate with data
DataTable table = CreateSampleData();
grid.DataSource = table;
dataItem.Client = grid;
this.groupBar1.Controls.Add(grid);
this.groupBar1.GroupBarItems.Add(dataItem);
}
private DataTable CreateSampleData()
{
DataTable table = new DataTable();
table.Columns.Add("ID", typeof(int));
table.Columns.Add("Name", typeof(string));
table.Columns.Add("Value", typeof(decimal));
table.Rows.Add(1, "Item 1", 100.50m);
table.Rows.Add(2, "Item 2", 250.75m);
table.Rows.Add(3, "Item 3", 175.25m);
return table;
}
```
### Hosting TreeView
```csharp
private void HostTreeView()
{
GroupBarItem treeItem = new GroupBarItem
{
Text = "Folder Tree"
};
TreeView tree = new TreeView
{
Dock = DockStyle.Fill,
BorderStyle = BorderStyle.None
};
// Build tree structure
TreeNode root = new TreeNode("Documents");
root.Nodes.Add("Personal");
root.Nodes.Add("Work");
root.Nodes.Add("Projects");
tree.Nodes.Add(root);
tree.ExpandAll();
treeItem.Client = tree;
this.groupBar1.Controls.Add(tree);
this.groupBar1.GroupBarItems.Add(treeItem);
}
```
### Hosting Custom UserControl
```csharp
// Assuming you have a custom UserControl
public class DashboardControl : UserControl
{
public DashboardControl()
{
// Custom dashboard implementation
}
}
private void HostCustomUserControl()
{
GroupBarItem dashboardItem = new GroupBarItem
{
Text = "Dashboard"
};
DashboardControl dashboard = new DashboardControl
{
Dock = DockStyle.Fill
};
dashboardItem.Client = dashboard;
this.groupBar1.Controls.Add(dashboard);
this.groupBar1.GroupBarItems.Add(dashboardItem);
}
```
## Event Handling
Comprehensive event handling for advanced scenarios.
### GroupBarItemAdded Event
```csharp
this.groupBar1.GroupBarItemAdded += (s, e) =>
{
GroupBarItem addedItem = e.Item;
Console.WriteLine($"Item added: {addedItem.Text}");
// Initialize new item
if (addedItem.Client == null)
{
Panel panel = new Panel { Dock = DockStyle.Fill, BackColor = Color.White };
addedItem.Client = panel;
this.groupBar1.Controls.Add(panel);
}
};
```
### GroupBarItemRemoved Event
```csharp
this.groupBar1.GroupBarItemRemoved += (s, e) =>
{
GroupBarItem removedItem = e.Item;
Console.WriteLine($"Item removed: {removedItem.Text}");
// Cleanup client control
if (removedItem.Client != null)
{
this.groupBar1.Controls.Remove(removedItem.Client);
removedItem.Client.Dispose();
}
};
```
### GroupBarItemSelectionChanging Event
```csharp
this.groupBar1.GroupBarItemSelectionChanging += (s, e) =>
{
int oldIndex = e.OldSelected;
int newIndex = e.NewSelected;
Console.WriteLine($"Changing selection: {oldIndex} → {newIndex}");
// Validate before allowing change
if (HasUnsavedChanges())
{
DialogResult result = MessageBox.Show(
"You have unsaved changes. Continue?",
"Unsaved Changes",
MessageBoxButtons.YesNo);
if (result == DialogResult.No)
{
e.Cancel = true; // Prevent selection change
}
}
};
private bool HasUnsavedChanges()
{
// Check for unsaved data
return false; // Placeholder
}
```
### ShowContextMenu Event
```csharp
this.groupBar1.ShowContextMenu += (s, e) =>
{
Console.WriteLine("Context menu requested");
// Show custom context menu
ContextMenuStrip menu = new ContextMenuStrip();
menu.Items.Add("Add Item", null, (sender, args) => AddNewItem());
menu.Items.Add("Remove Item", null, (sender, args) => RemoveSelectedItem());
menu.Items.Add(new ToolStripSeparator());
menu.Items.Add("Settings", null, (sender, args) => ShowSettings());
menu.Show(this.groupBar1, this.groupBar1.PointToClient(Cursor.Position));
};
private void AddNewItem()
{
GroupBarItem newItem = new GroupBarItem { Text = $"New Item {DateTime.Now.Ticks}" };
Panel panel = new Panel { Dock = DockStyle.Fill, BackColor = Color.White };
newItem.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(newItem);
}
private void RemoveSelectedItem()
{
int selectedIndex = this.groupBar1.SelectedItem;
if (selectedIndex >= 0)
{
this.groupBar1.GroupBarItems.RemoveAt(selectedIndex);
}
}
private void ShowSettings()
{
MessageBox.Show("Settings dialog would appear here.");
}
```
## AllowCollapse Property
Control whether users can collapse the navigation pane.
```csharp
// Enable collapsing
this.groupBar1.AllowCollapse = true;
// Configure collapse appearance
this.groupBar1.CollapsedWidth = 40;
this.groupBar1.CollapsedText = "Nav";
// Set custom collapse/expand images
this.groupBar1.CollapseImage = Properties.Resources.CollapseIcon;
this.groupBar1.ExpandImage = Properties.Resources.ExpandIcon;
// Handle collapse state changes
this.groupBar1.CollapsedChanged += (s, e) =>
{
bool isCollapsed = this.groupBar1.Collapsed;
Console.WriteLine($"Navigation pane {(isCollapsed ? "collapsed" : "expanded")}");
// Adjust layout accordingly
AdjustContentLayout(isCollapsed);
};
```
## Complete Advanced Scenarios
### Scenario 1: Dynamic Item Management with Serialization
```csharp
public class DynamicItemManagementForm : Form
{
private GroupBar groupBar1;
private ToolStrip toolbar;
public DynamicItemManagementForm()
{
this.Text = "Dynamic Item Management";
this.Size = new Size(900, 700);
CreateToolbar();
CreateDynamicGroupBar();
this.Load += Form_Load;
this.FormClosing += Form_FormClosing;
}
private void CreateToolbar()
{
this.toolbar = new ToolStrip();
ToolStripButton btnAdd = new ToolStripButton("Add Section");
btnAdd.Click += (s, e) => AddNewSection();
ToolStripButton btnRemove = new ToolStripButton("Remove Section");
btnRemove.Click += (s, e) => RemoveCurrentSection();
ToolStripButton btnRename = new ToolStripButton("Rename Section");
btnRename.Click += (s, e) => RenameCurrentSection();
ToolStripButton btnSave = new ToolStripButton("Save Layout");
btnSave.Click += (s, e) => SaveLayout();
this.toolbar.Items.AddRange(new ToolStripItem[]
{
btnAdd, btnRemove, btnRename,
new ToolStripSeparator(),
btnSave
});
this.Controls.Add(this.toolbar);
}
private void CreateDynamicGroupBar()
{
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 220,
Font = new Font("Segoe UI", 9F)
};
// Handle events
this.groupBar1.GroupBarItemAdded += GroupBar1_ItemAdded;
this.groupBar1.GroupBarItemRemoved += GroupBar1_ItemRemoved;
this.groupBar1.GroupBarItemRenamed += GroupBar1_ItemRenamed;
this.Controls.Add(this.groupBar1);
}
private void AddNewSection()
{
string name = Prompt.ShowDialog("Enter section name:", "New Section");
if (string.IsNullOrWhiteSpace(name))
return;
GroupBarItem item = new GroupBarItem { Text = name };
Panel panel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White,
Padding = new Padding(10)
};
Label label = new Label
{
Text = $"Content for {name}",
Dock = DockStyle.Top,
Font = new Font("Segoe UI", 12F)
};
panel.Controls.Add(label);
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
// Select new item
this.groupBar1.SelectedItem = this.groupBar1.GroupBarItems.Count - 1;
}
private void RemoveCurrentSection()
{
int selectedIndex = this.groupBar1.SelectedItem;
if (selectedIndex < 0)
{
MessageBox.Show("No section selected.");
return;
}
string itemName = this.groupBar1.GroupBarItems[selectedIndex].Text;
DialogResult result = MessageBox.Show(
$"Remove section '{itemName}'?",
"Confirm Removal",
MessageBoxButtons.YesNo,
MessageBoxIcon.Question);
if (result == DialogResult.Yes)
{
this.groupBar1.GroupBarItems.RemoveAt(selectedIndex);
}
}
private void RenameCurrentSection()
{
int selectedIndex = this.groupBar1.SelectedItem;
if (selectedIndex >= 0)
{
this.groupBar1.InplaceRenameItem(selectedIndex);
}
}
private void SaveLayout()
{
// Save item names and order
ArrayList layoutData = new ArrayList();
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
layoutData.Add(item.Text);
}
layoutData.Add(this.groupBar1.SelectedItem);
string configPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
"DynamicGroupBar",
"layout.xml");
Directory.CreateDirectory(Path.GetDirectoryName(configPath));
AppStateSerializer serializer = new AppStateSerializer(
SerializeMode.XMLFile,
configPath);
serializer.SerializeObject("Layout", layoutData);
serializer.PersistNow();
MessageBox.Show("Layout saved!", "Success", MessageBoxButtons.OK, MessageBoxIcon.Information);
}
private void LoadLayout()
{
try
{
string configPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
"DynamicGroupBar",
"layout.xml");
if (!File.Exists(configPath))
return;
AppStateSerializer serializer = new AppStateSerializer(
SerializeMode.XMLFile,
configPath);
ArrayList layoutData = serializer.DeserializeObject("Layout") as ArrayList;
if (layoutData == null || layoutData.Count == 0)
return;
// Recreate items
this.groupBar1.GroupBarItems.Clear();
for (int i = 0; i < layoutData.Count - 1; i++)
{
string itemName = layoutData[i].ToString();
GroupBarItem item = new GroupBarItem { Text = itemName };
Panel panel = new Panel { Dock = DockStyle.Fill, BackColor = Color.White };
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
}
// Restore selection
int selectedIndex = (int)layoutData[layoutData.Count - 1];
if (selectedIndex >= 0 && selectedIndex < this.groupBar1.GroupBarItems.Count)
{
this.groupBar1.SelectedItem = selectedIndex;
}
}
catch (Exception ex)
{
Console.WriteLine($"Error loading layout: {ex.Message}");
}
}
private void GroupBar1_ItemAdded(object sender, GroupBarItemEventArgs e)
{
Console.WriteLine($"Item added: {e.Item.Text}");
}
private void GroupBar1_ItemRemoved(object sender, GroupBarItemEventArgs e)
{
Console.WriteLine($"Item removed: {e.Item.Text}");
}
private void GroupBar1_ItemRenamed(object sender, GroupItemRenamedEventArgs e)
{
Console.WriteLine($"Item renamed: {e.OldLabel} → {e.NewLabel}");
}
private void Form_Load(object sender, EventArgs e)
{
LoadLayout();
}
private void Form_FormClosing(object sender, FormClosingEventArgs e)
{
SaveLayout();
}
}
// Simple prompt dialog helper
public static class Prompt
{
public static string ShowDialog(string text, string caption)
{
Form prompt = new Form
{
Width = 400,
Height = 150,
FormBorderStyle = FormBorderStyle.FixedDialog,
Text = caption,
StartPosition = FormStartPosition.CenterScreen
};
Label textLabel = new Label { Left = 20, Top = 20, Text = text, Width = 350 };
TextBox textBox = new TextBox { Left = 20, Top = 50, Width = 350 };
Button confirmation = new Button { Text = "Ok", Left = 250, Width = 100, Top = 80, DialogResult = DialogResult.OK };
confirmation.Click += (sender, e) => { prompt.Close(); };
prompt.Controls.AddRange(new Control[] { textLabel, textBox, confirmation });
prompt.AcceptButton = confirmation;
return prompt.ShowDialog() == DialogResult.OK ? textBox.Text : string.Empty;
}
}
```
**Result:** Complete dynamic item management with add, remove, rename, and layout persistence.
### Scenario 2: Custom Control Hosting Showcase
```csharp
public class CustomControlShowcaseForm : Form
{
private GroupBar groupBar1;
public CustomControlShowcaseForm()
{
this.Text = "Custom Control Showcase";
this.Size = new Size(1100, 750);
CreateShowcaseGroupBar();
}
private void CreateShowcaseGroupBar()
{
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 220,
Font = new Font("Segoe UI", 9F),
StackedMode = true
};
// Host different control types
HostDataGridSection();
HostChartSection();
HostCalendarSection();
HostBrowserSection();
HostRichTextSection();
this.groupBar1.SelectedItem = 0;
this.Controls.Add(this.groupBar1);
}
private void HostDataGridSection()
{
GroupBarItem item = new GroupBarItem { Text = "Data Grid" };
DataGridView grid = new DataGridView
{
Dock = DockStyle.Fill,
AutoGenerateColumns = true,
AllowUserToAddRows = false,
SelectionMode = DataGridViewSelectionMode.FullRowSelect
};
// Sample data
DataTable table = new DataTable();
table.Columns.Add("Product", typeof(string));
table.Columns.Add("Price", typeof(decimal));
table.Columns.Add("Stock", typeof(int));
table.Rows.Add("Laptop", 1299.99m, 45);
table.Rows.Add("Mouse", 29.99m, 150);
table.Rows.Add("Keyboard", 89.99m, 78);
grid.DataSource = table;
item.Client = grid;
this.groupBar1.Controls.Add(grid);
this.groupBar1.GroupBarItems.Add(item);
}
private void HostChartSection()
{
GroupBarItem item = new GroupBarItem { Text = "Charts" };
// Simple chart using panel and graphics
Panel chartPanel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White
};
chartPanel.Paint += (s, e) =>
{
Graphics g = e.Graphics;
g.SmoothingMode = System.Drawing.Drawing2D.SmoothingMode.AntiAlias;
// Draw simple bar chart
int[] values = { 45, 67, 89, 54, 72 };
int barWidth = 50;
int spacing = 20;
int maxHeight = chartPanel.Height - 50;
for (int i = 0; i < values.Length; i++)
{
int x = 50 + i * (barWidth + spacing);
int height = (int)(values[i] / 100.0 * maxHeight);
int y = chartPanel.Height - height - 30;
g.FillRectangle(Brushes.SteelBlue, x, y, barWidth, height);
g.DrawString(values[i].ToString(), this.Font, Brushes.Black, x + 15, y - 20);
}
};
item.Client = chartPanel;
this.groupBar1.Controls.Add(chartPanel);
this.groupBar1.GroupBarItems.Add(item);
}
private void HostCalendarSection()
{
GroupBarItem item = new GroupBarItem { Text = "Calendar" };
MonthCalendar calendar = new MonthCalendar
{
Location = new Point(10, 10),
MaxSelectionCount = 1
};
Panel calendarPanel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White,
Padding = new Padding(10)
};
calendarPanel.Controls.Add(calendar);
item.Client = calendarPanel;
this.groupBar1.Controls.Add(calendarPanel);
this.groupBar1.GroupBarItems.Add(item);
}
private void HostBrowserSection()
{
GroupBarItem item = new GroupBarItem { Text = "Web Browser" };
WebBrowser browser = new WebBrowser
{
Dock = DockStyle.Fill,
Url = new Uri("about:blank")
};
// Simple HTML content
browser.DocumentText = @"
<html>
<body style='font-family: Segoe UI; padding: 20px;'>
<h1>Embedded Web Browser</h1>
<p>This is a WebBrowser control hosted in a GroupBarItem.</p>
<p>You can navigate to any URL or display custom HTML content.</p>
</body>
</html>";
item.Client = browser;
this.groupBar1.Controls.Add(browser);
this.groupBar1.GroupBarItems.Add(item);
}
private void HostRichTextSection()
{
GroupBarItem item = new GroupBarItem { Text = "Rich Text" };
RichTextBox richText = new RichTextBox
{
Dock = DockStyle.Fill,
BorderStyle = BorderStyle.None,
Font = new Font("Segoe UI", 10F)
};
richText.SelectionFont = new Font("Segoe UI", 16F, FontStyle.Bold);
richText.AppendText("Rich Text Editor\n\n");
richText.SelectionFont = new Font("Segoe UI", 10F, FontStyle.Regular);
richText.AppendText("This is a RichTextBox control with formatted text.\n\n");
richText.SelectionColor = Color.Blue;
richText.AppendText("You can apply different colors, ");
richText.SelectionColor = Color.Red;
richText.SelectionFont = new Font("Segoe UI", 10F, FontStyle.Bold);
richText.AppendText("fonts, ");
richText.SelectionColor = Color.Green;
richText.SelectionFont = new Font("Segoe UI", 10F, FontStyle.Italic);
richText.AppendText("and styles ");
richText.SelectionColor = Color.Black;
richText.SelectionFont = new Font("Segoe UI", 10F, FontStyle.Regular);
richText.AppendText("to the text.");
item.Client = richText;
this.groupBar1.Controls.Add(richText);
this.groupBar1.GroupBarItems.Add(item);
}
}
```
**Result:** Showcase of various controls hosted in GroupBarItems including DataGridView, charts, calendar, web browser, and rich text editor.
## Key Takeaways
1. **Nested GroupBars** enable multi-level navigation hierarchies
2. **In-Place Renaming** allows user customization with validation
3. **Serialization** preserves layout state across sessions
4. **Localization** supports international users with resource files
5. **Custom Control Hosting** accepts any .NET control as client
6. **Event Handling** provides hooks for advanced scenarios
7. **AllowCollapse** enables collapsible navigation panes
8. **Combine features** to create sophisticated applications
9. **Validate user input** in rename and event handlers
10. **Persist user preferences** for better UX
references/appearance-customization.md
# Appearance Customization
This guide covers comprehensive appearance customization options for the GroupBar control beyond the built-in themes. Fine-tune colors, fonts, borders, tooltips, and animations to create a unique look that matches your application's design.
## Table of Contents
- [Header Customization](#header-customization)
- [Border Settings](#border-settings)
- [Text Alignment Settings](#text-alignment-settings)
- [Image Display Configuration](#image-display-configuration)
- [Tooltip Settings](#tooltip-settings)
- [Cursor Customization](#cursor-customization)
- [Animation Settings](#animation-settings)
- [Custom Colors and Gradients](#custom-colors-and-gradients)
- [Complete Custom Styling Examples](#complete-custom-styling-examples)
## Header Customization
The header is the top bar of each GroupBarItem. Customize its appearance with colors, fonts, and sizing.
### Header Colors
#### HeaderBackColor Property
Set the background color of GroupBarItem headers:
```csharp
// Solid header color
this.groupBar1.HeaderBackColor = Color.Navy;
// RGB color
this.groupBar1.HeaderBackColor = Color.FromArgb(0, 114, 188);
// Named color
this.groupBar1.HeaderBackColor = Color.LightSteelBlue;
```
**When to customize header back color:**
- Match corporate branding
- Create visual hierarchy
- Distinguish different sections
- Improve readability
#### HeaderForeColor Property
Set the text color of GroupBarItem headers:
```csharp
// White text on dark background
this.groupBar1.HeaderBackColor = Color.Navy;
this.groupBar1.HeaderForeColor = Color.White;
// Dark text on light background
this.groupBar1.HeaderBackColor = Color.LightBlue;
this.groupBar1.HeaderForeColor = Color.DarkBlue;
```
**Color contrast best practices:**
- Ensure sufficient contrast ratio (WCAG AA: 4.5:1 minimum)
- Test readability with actual text
- Consider accessibility requirements
#### Complete Header Color Example
```csharp
private void SetupCustomHeaderColors()
{
// Professional blue theme
this.groupBar1.HeaderBackColor = Color.FromArgb(0, 114, 188);
this.groupBar1.HeaderForeColor = Color.White;
// Alternative: Gradient effect (via custom painting)
this.groupBar1.HeaderBackColor = Color.FromArgb(41, 128, 185);
this.groupBar1.HeaderForeColor = Color.White;
Console.WriteLine("Header colors customized");
}
// Reset to default
private void ResetHeaderColors()
{
this.groupBar1.ResetHeaderBackColor();
this.groupBar1.ResetHeaderForeColor();
}
```
### Header Font
Customize the font used in headers:
```csharp
// Standard font customization
this.groupBar1.Font = new Font("Segoe UI", 10F, FontStyle.Bold);
// Different font family
this.groupBar1.Font = new Font("Arial", 9F, FontStyle.Regular);
// With specific characteristics
this.groupBar1.Font = new Font("Calibri", 11F, FontStyle.Italic);
```
**Font selection guidelines:**
- Use web-safe or system fonts
- Ensure font is available on target systems
- Consider readability at different sizes
- Test with longest item text
#### Complete Font Example
```csharp
private void SetupHeaderFonts()
{
// Modern, clean font
this.groupBar1.Font = new Font("Segoe UI", 10F, FontStyle.Regular);
// Bold headers for emphasis
this.groupBar1.Font = new Font("Segoe UI Semibold", 10F, FontStyle.Bold);
// Compact font for narrow layouts
this.groupBar1.Font = new Font("Segoe UI", 8.5F, FontStyle.Regular);
}
// Reset font
private void ResetHeaderFont()
{
this.groupBar1.ResetHeaderFont();
}
```
### Header Height
Control the height of GroupBarItem headers:
```csharp
// Standard height
this.groupBar1.GroupBarItemHeight = 28;
// Tall headers
this.groupBar1.GroupBarItemHeight = 40;
// Compact headers
this.groupBar1.GroupBarItemHeight = 24;
```
**Height recommendations:**
| Height (px) | Use Case |
|------------|----------|
| 20-24 | Compact, space-saving |
| 26-30 | Standard desktop |
| 32-40 | Large text, touch-friendly |
| 40+ | Extra-large, prominent |
#### Dynamic Header Height Example
```csharp
private void AdjustHeaderHeight(string sizeMode)
{
switch (sizeMode.ToLower())
{
case "compact":
this.groupBar1.GroupBarItemHeight = 24;
this.groupBar1.Font = new Font("Segoe UI", 8.5F);
break;
case "standard":
this.groupBar1.GroupBarItemHeight = 28;
this.groupBar1.Font = new Font("Segoe UI", 9F);
break;
case "large":
this.groupBar1.GroupBarItemHeight = 36;
this.groupBar1.Font = new Font("Segoe UI", 10F);
break;
case "touch":
this.groupBar1.GroupBarItemHeight = 44;
this.groupBar1.Font = new Font("Segoe UI", 11F);
break;
}
}
```
### Complete Header Customization Example
```csharp
private void CreateCustomStyledHeaders()
{
// Configure header appearance
this.groupBar1.HeaderBackColor = Color.FromArgb(25, 25, 25);
this.groupBar1.HeaderForeColor = Color.White;
this.groupBar1.GroupBarItemHeight = 32;
this.groupBar1.Font = new Font("Segoe UI", 10F, FontStyle.Bold);
// Adjust control to show custom headers
this.groupBar1.BorderStyle = BorderStyle.FixedSingle;
this.groupBar1.BackColor = Color.FromArgb(45, 45, 48);
Console.WriteLine("Custom header styling applied");
}
```
**Result:** Dark-themed GroupBar with custom header colors, fonts, and sizing.
## Border Settings
Control the borders of the GroupBar control and its items.
### GroupBar Border Style
Set the outer border style:
```csharp
// No border
this.groupBar1.BorderStyle = BorderStyle.None;
// Single line border
this.groupBar1.BorderStyle = BorderStyle.FixedSingle;
// 3D border
this.groupBar1.BorderStyle = BorderStyle.Fixed3D;
```
**When to use each style:**
- **None** - Seamless integration, custom borders
- **FixedSingle** - Clean, modern appearance
- **Fixed3D** - Traditional, raised appearance
### Client Border Settings
Control borders around GroupBarItem client areas:
```csharp
// Enable client borders
this.groupBar1.DrawClientBorder = true;
// Disable client borders
this.groupBar1.DrawClientBorder = false;
```
### Custom Client Border Colors
Define custom colors for each edge of the client border:
```csharp
// Custom border colors for a specific item
this.groupBarItem1.ClientBorderColors = new Syncfusion.Windows.Forms.Tools.BorderColors(
Color.Red, // Top
Color.Blue, // Left
Color.Green, // Right
Color.Yellow // Bottom
);
```
### Complete Border Example
```csharp
private void SetupCustomBorders()
{
// Configure GroupBar border
this.groupBar1.BorderStyle = BorderStyle.FixedSingle;
// Enable client borders
this.groupBar1.DrawClientBorder = true;
// Custom border colors for each item
BorderColors professionalBorders = new BorderColors(
Color.FromArgb(204, 204, 204), // Top - light gray
Color.FromArgb(204, 204, 204), // Left
Color.FromArgb(204, 204, 204), // Right
Color.FromArgb(204, 204, 204) // Bottom
);
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
item.ClientBorderColors = professionalBorders;
}
Console.WriteLine("Custom borders applied");
}
// Colorful borders for visual distinction
private void SetupColorfulBorders()
{
this.groupBar1.DrawClientBorder = true;
// Different color for each section
this.groupBarItem1.ClientBorderColors = new BorderColors(
Color.FromArgb(0, 114, 188), // Blue
Color.FromArgb(0, 114, 188),
Color.FromArgb(0, 114, 188),
Color.FromArgb(0, 114, 188)
);
this.groupBarItem2.ClientBorderColors = new BorderColors(
Color.FromArgb(0, 176, 80), // Green
Color.FromArgb(0, 176, 80),
Color.FromArgb(0, 176, 80),
Color.FromArgb(0, 176, 80)
);
this.groupBarItem3.ClientBorderColors = new BorderColors(
Color.FromArgb(255, 140, 0), // Orange
Color.FromArgb(255, 140, 0),
Color.FromArgb(255, 140, 0),
Color.FromArgb(255, 140, 0)
);
}
```
## Text Alignment Settings
Control how text is aligned within GroupBarItem headers.
### TextAlign Property
```csharp
// Center alignment (default)
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Center;
// Left alignment
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Left;
// Right alignment
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Right;
```
**When to use each alignment:**
- **Center** - Balanced, symmetric appearance
- **Left** - Western reading direction, text-heavy
- **Right** - Special layouts, RTL languages
### Complete Text Alignment Example
```csharp
private void DemonstrateTextAlignment()
{
// Create alignment selector
RadioButton rbCenter = new RadioButton { Text = "Center", Checked = true };
RadioButton rbLeft = new RadioButton { Text = "Left" };
RadioButton rbRight = new RadioButton { Text = "Right" };
rbCenter.CheckedChanged += (s, e) =>
{
if (rbCenter.Checked)
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Center;
};
rbLeft.CheckedChanged += (s, e) =>
{
if (rbLeft.Checked)
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Left;
};
rbRight.CheckedChanged += (s, e) =>
{
if (rbRight.Checked)
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Right;
};
// Add to form
Panel alignmentPanel = new Panel { Dock = DockStyle.Top, Height = 30 };
alignmentPanel.Controls.AddRange(new Control[] { rbCenter, rbLeft, rbRight });
this.Controls.Add(alignmentPanel);
}
```
## Image Display Configuration
Configure how images appear on GroupBarItems.
### Large Image Mode
Enable display of larger images on headers:
```csharp
// Enable large image mode
this.groupBarItem1.LargeImageMode = true;
this.groupBarItem1.Image = Properties.Resources.LargeIcon; // 32x32 or 48x48
```
### Show Item Image in Header
Display the selected item's image in the stacked mode header:
```csharp
// Enable in stacked mode
this.groupBar1.StackedMode = true;
this.groupBar1.ShowItemImageInHeader = true;
// Set images for items
this.groupBarItem1.Image = Properties.Resources.MailIcon;
this.groupBarItem2.Image = Properties.Resources.CalendarIcon;
```
**Result:** When an item is selected in stacked mode, its icon displays in the header.
### Complete Image Configuration Example
```csharp
private void SetupImageDisplay()
{
// Enable large images
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
item.LargeImageMode = true;
}
// Load and assign images
ImageList largeIcons = new ImageList
{
ImageSize = new Size(32, 32),
ColorDepth = ColorDepth.Depth32Bit
};
largeIcons.Images.Add("mail", LoadImage("mail_32.png"));
largeIcons.Images.Add("calendar", LoadImage("calendar_32.png"));
largeIcons.Images.Add("contacts", LoadImage("contacts_32.png"));
this.groupBarItem1.Image = largeIcons.Images["mail"];
this.groupBarItem2.Image = largeIcons.Images["calendar"];
this.groupBarItem3.Image = largeIcons.Images["contacts"];
// Enable header images for stacked mode
if (this.groupBar1.StackedMode)
{
this.groupBar1.ShowItemImageInHeader = true;
}
}
private Image LoadImage(string fileName)
{
string path = Path.Combine(Application.StartupPath, "Images", fileName);
return Image.FromFile(path);
}
```
## Tooltip Settings
Configure tooltips for GroupBar elements.
### Navigation Pane Tooltip
```csharp
// Set navigation pane tooltip
this.groupBar1.NavigationPaneTooltip = "Show Navigation Options";
```
### Expand Button Tooltip
```csharp
// Set expand button tooltip
this.groupBar1.ExpandButtonToolTip = "Expand Navigation Pane";
```
### Minimize Button Tooltip
```csharp
// Set minimize button tooltip
this.groupBar1.MinimizeButtonToolTip = "Minimize Navigation Pane";
```
### Complete Tooltip Configuration
```csharp
private void SetupTooltips()
{
// Configure all tooltips
this.groupBar1.NavigationPaneTooltip = "Click to show more navigation options";
this.groupBar1.ExpandButtonToolTip = "Expand the navigation pane to full width";
this.groupBar1.MinimizeButtonToolTip = "Minimize the navigation pane to save space";
// Custom tooltip provider (if needed)
ToolTip customToolTip = new ToolTip
{
InitialDelay = 500,
ReshowDelay = 200,
AutoPopDelay = 5000,
IsBalloon = true
};
Console.WriteLine("Tooltips configured");
}
```
## Cursor Customization
Change cursor appearance when hovering over GroupBar elements.
### GroupBar Cursor
Set the cursor for the entire GroupBar control:
```csharp
// Default arrow
this.groupBar1.Cursor = Cursors.Default;
// Hand cursor
this.groupBar1.Cursor = Cursors.Hand;
// Cross cursor
this.groupBar1.Cursor = Cursors.Cross;
```
### GroupBarItem Cursor
Set the cursor when hovering over GroupBarItems:
```csharp
// Hand cursor for clickable items
this.groupBar1.GroupBarItemCursor = Cursors.Hand;
// Help cursor
this.groupBar1.GroupBarItemCursor = Cursors.Help;
// Custom cursor
this.groupBar1.GroupBarItemCursor = new Cursor("custom.cur");
```
### Complete Cursor Example
```csharp
private void SetupCustomCursors()
{
// Hand cursor for items (indicates clickable)
this.groupBar1.GroupBarItemCursor = Cursors.Hand;
// Default cursor for client area
this.groupBar1.Cursor = Cursors.Default;
Console.WriteLine("Custom cursors applied");
}
// Reset cursors to default
private void ResetCursors()
{
this.groupBar1.ResetGroupBarItemCursor();
this.groupBar1.Cursor = Cursors.Default;
}
```
## Animation Settings
Enable smooth animations for GroupBar interactions.
### Animated Selection
Animate transitions when switching between GroupBarItems:
```csharp
// Enable animated selection
this.groupBar1.AnimatedSelection = true;
```
**When to use:**
- Smooth, polished user experience
- Modern application feel
- Transitions between content
- Visual feedback for selections
**When to disable:**
- Performance-sensitive scenarios
- Older hardware
- User preference (accessibility)
- Very fast item switching
### Animate Collapse
Animate the collapse/expand of the navigation pane:
```csharp
// Enable collapse animation
this.groupBar1.AnimateCollapse = true;
```
### Complete Animation Example
```csharp
private void SetupAnimations()
{
// Enable all animations
this.groupBar1.AnimatedSelection = true;
this.groupBar1.AnimateCollapse = true;
// Toggle animations based on user preference
CheckBox chkAnimations = new CheckBox
{
Text = "Enable Animations",
Checked = true,
Dock = DockStyle.Top
};
chkAnimations.CheckedChanged += (s, e) =>
{
bool enabled = chkAnimations.Checked;
this.groupBar1.AnimatedSelection = enabled;
this.groupBar1.AnimateCollapse = enabled;
Console.WriteLine($"Animations {(enabled ? "enabled" : "disabled")}");
};
this.Controls.Add(chkAnimations);
}
```
## Custom Colors and Gradients
Apply custom colors beyond the standard theme colors.
### BackColor and ForeColor
```csharp
// GroupBar background
this.groupBar1.BackColor = Color.FromArgb(250, 250, 250);
// GroupBar foreground (text)
this.groupBar1.ForeColor = Color.FromArgb(50, 50, 50);
```
### FlatLook Property
Enable flat appearance without 3D effects:
```csharp
// Enable flat look
this.groupBar1.FlatLook = true;
```
**Result:** Removes 3D borders and gradients for a modern flat design.
### BarHighlight Property
Enable highlighting effect when hovering over items:
```csharp
// Enable hover highlighting
this.groupBar1.BarHighlight = true;
```
**Result:** Items highlight when mouse hovers over them, providing visual feedback.
### Custom Gradient via ProvideGroupBarItemBrush Event
For advanced gradient customization:
```csharp
// Wire up event
this.groupBar1.ProvideGroupBarItemBrush += GroupBar1_ProvideGroupBarItemBrush;
private void GroupBar1_ProvideGroupBarItemBrush(object sender,
Syncfusion.Windows.Forms.Tools.ProvideGroupBarItemBrushEventArgs e)
{
// Create custom gradient brush
Rectangle bounds = e.Bounds;
LinearGradientBrush brush = new LinearGradientBrush(
bounds,
Color.FromArgb(41, 128, 185), // Start color
Color.FromArgb(109, 213, 250), // End color
90f // Angle
);
// Apply blend for smooth gradient
Blend blend = new Blend
{
Factors = new float[] { 0.0f, 0.5f, 1.0f },
Positions = new float[] { 0.0f, 0.5f, 1.0f }
};
brush.Blend = blend;
// Assign custom brush
e.BackgroundBrush = brush;
}
```
### Complete Custom Colors Example
```csharp
private void ApplyCustomColorScheme()
{
// Define color palette
Color primary = Color.FromArgb(0, 114, 188);
Color secondary = Color.FromArgb(41, 128, 185);
Color accent = Color.FromArgb(52, 152, 219);
Color light = Color.FromArgb(236, 240, 241);
Color dark = Color.FromArgb(44, 62, 80);
// Apply to GroupBar
this.groupBar1.BackColor = light;
this.groupBar1.ForeColor = dark;
this.groupBar1.HeaderBackColor = primary;
this.groupBar1.HeaderForeColor = Color.White;
// Enable modern appearance
this.groupBar1.FlatLook = true;
this.groupBar1.BarHighlight = true;
this.groupBar1.BorderStyle = BorderStyle.FixedSingle;
// Configure borders
this.groupBar1.DrawClientBorder = true;
BorderColors customBorders = new BorderColors(accent, accent, accent, accent);
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
item.ClientBorderColors = customBorders;
}
Console.WriteLine("Custom color scheme applied");
}
```
## Complete Custom Styling Examples
### Example 1: Modern Dark Theme
```csharp
using System;
using System.Drawing;
using System.Drawing.Drawing2D;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
public class ModernDarkThemeForm : Form
{
private GroupBar groupBar1;
public ModernDarkThemeForm()
{
this.Text = "Modern Dark Theme";
this.Size = new Size(900, 650);
this.BackColor = Color.FromArgb(30, 30, 30);
CreateModernDarkGroupBar();
}
private void CreateModernDarkGroupBar()
{
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 250,
BorderStyle = BorderStyle.None,
Font = new Font("Segoe UI", 10F),
// Dark theme colors
BackColor = Color.FromArgb(45, 45, 48),
ForeColor = Color.White,
HeaderBackColor = Color.FromArgb(37, 37, 38),
HeaderForeColor = Color.FromArgb(241, 241, 241),
// Modern appearance
FlatLook = true,
BarHighlight = true,
GroupBarItemHeight = 36,
// Animations
AnimatedSelection = true,
// Borders
DrawClientBorder = true
};
// Custom border colors (subtle)
BorderColors darkBorders = new BorderColors(
Color.FromArgb(63, 63, 70),
Color.FromArgb(63, 63, 70),
Color.FromArgb(63, 63, 70),
Color.FromArgb(63, 63, 70)
);
// Create sections with dark theme
CreateDarkSection("Dashboard", "📊", darkBorders);
CreateDarkSection("Analytics", "📈", darkBorders);
CreateDarkSection("Reports", "📄", darkBorders);
CreateDarkSection("Settings", "⚙️", darkBorders);
this.groupBar1.SelectedItem = 0;
this.Controls.Add(this.groupBar1);
}
private void CreateDarkSection(string name, string icon, BorderColors borders)
{
GroupBarItem item = new GroupBarItem
{
Text = $"{icon} {name}",
ClientBorderColors = borders
};
Panel panel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.FromArgb(37, 37, 38),
Padding = new Padding(15)
};
Label label = new Label
{
Text = $"{name} Content",
Font = new Font("Segoe UI", 14F, FontStyle.Bold),
ForeColor = Color.FromArgb(241, 241, 241),
Dock = DockStyle.Top,
Height = 40
};
panel.Controls.Add(label);
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
}
}
```
**Result:** A modern dark-themed GroupBar with subtle colors, flat design, and smooth animations.
### Example 2: Vibrant Color-Coded Sections
```csharp
public class ColorCodedSectionsForm : Form
{
private GroupBar groupBar1;
public ColorCodedSectionsForm()
{
this.Text = "Color-Coded Sections";
this.Size = new Size(950, 700);
this.BackColor = Color.White;
CreateColorCodedGroupBar();
}
private void CreateColorCodedGroupBar()
{
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 260,
BorderStyle = BorderStyle.FixedSingle,
Font = new Font("Segoe UI", 10F, FontStyle.Bold),
BackColor = Color.White,
GroupBarItemHeight = 40,
FlatLook = true,
BarHighlight = true,
AnimatedSelection = true,
DrawClientBorder = true
};
// Each section has a unique color
CreateColorSection("Sales", Color.FromArgb(231, 76, 60)); // Red
CreateColorSection("Marketing", Color.FromArgb(155, 89, 182)); // Purple
CreateColorSection("Operations", Color.FromArgb(52, 152, 219)); // Blue
CreateColorSection("Finance", Color.FromArgb(46, 204, 113)); // Green
CreateColorSection("HR", Color.FromArgb(241, 196, 15)); // Yellow
this.groupBar1.SelectedItem = 0;
this.Controls.Add(this.groupBar1);
}
private void CreateColorSection(string name, Color accentColor)
{
GroupBarItem item = new GroupBarItem
{
Text = name
};
// Color-coded border
BorderColors colorBorder = new BorderColors(accentColor, accentColor, accentColor, accentColor);
item.ClientBorderColors = colorBorder;
Panel panel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White,
Padding = new Padding(20)
};
// Colored header strip
Panel headerStrip = new Panel
{
Dock = DockStyle.Top,
Height = 5,
BackColor = accentColor
};
Label titleLabel = new Label
{
Text = name,
Font = new Font("Segoe UI", 16F, FontStyle.Bold),
ForeColor = accentColor,
Dock = DockStyle.Top,
Height = 50,
Padding = new Padding(0, 10, 0, 0)
};
Label descLabel = new Label
{
Text = $"Content for {name} department",
Font = new Font("Segoe UI", 10F),
ForeColor = Color.FromArgb(100, 100, 100),
Dock = DockStyle.Top,
Height = 30
};
panel.Controls.Add(descLabel);
panel.Controls.Add(titleLabel);
panel.Controls.Add(headerStrip);
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
}
}
```
**Result:** A vibrant interface where each section has its own color identity with colored borders and headers.
### Example 3: Custom Gradient Styling
```csharp
public class CustomGradientForm : Form
{
private GroupBar groupBar1;
public CustomGradientForm()
{
this.Text = "Custom Gradient Styling";
this.Size = new Size(1000, 700);
CreateGradientStyledGroupBar();
}
private void CreateGradientStyledGroupBar()
{
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 240,
BorderStyle = BorderStyle.FixedSingle,
Font = new Font("Segoe UI", 10F),
GroupBarItemHeight = 38,
AnimatedSelection = true
};
// Wire up custom painting event
this.groupBar1.ProvideGroupBarItemBrush += GroupBar1_ProvideGroupBarItemBrush;
// Create sections
for (int i = 1; i <= 5; i++)
{
GroupBarItem item = new GroupBarItem
{
Text = $"Section {i}",
Tag = i // Store index for gradient variation
};
Panel panel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White
};
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
}
this.groupBar1.SelectedItem = 0;
this.Controls.Add(this.groupBar1);
}
private void GroupBar1_ProvideGroupBarItemBrush(object sender,
ProvideGroupBarItemBrushEventArgs e)
{
// Get item index to vary gradient
int itemIndex = e.Item;
Rectangle bounds = e.Bounds;
// Define gradient colors based on item
Color startColor = GetGradientStartColor(itemIndex);
Color endColor = GetGradientEndColor(itemIndex);
// Create gradient brush
LinearGradientBrush brush = new LinearGradientBrush(
bounds,
startColor,
endColor,
LinearGradientMode.Vertical
);
// Apply smooth blend
Blend blend = new Blend
{
Factors = new float[] { 0.0f, 0.3f, 1.0f },
Positions = new float[] { 0.0f, 0.6f, 1.0f }
};
brush.Blend = blend;
e.BackgroundBrush = brush;
}
private Color GetGradientStartColor(int index)
{
return index switch
{
0 => Color.FromArgb(41, 128, 185),
1 => Color.FromArgb(142, 68, 173),
2 => Color.FromArgb(39, 174, 96),
3 => Color.FromArgb(211, 84, 0),
4 => Color.FromArgb(192, 57, 43),
_ => Color.FromArgb(52, 152, 219)
};
}
private Color GetGradientEndColor(int index)
{
return index switch
{
0 => Color.FromArgb(109, 213, 250),
1 => Color.FromArgb(155, 89, 182),
2 => Color.FromArgb(46, 204, 113),
3 => Color.FromArgb(230, 126, 34),
4 => Color.FromArgb(231, 76, 60),
_ => Color.FromArgb(127, 140, 141)
};
}
}
```
**Result:** GroupBar with custom gradient styling for each item, creating a unique and visually appealing interface.
## Key Takeaways
1. **Header Customization** includes colors, fonts, and heights
2. **Border Settings** control outer borders and client area borders
3. **Text Alignment** affects readability and visual balance
4. **Image Configuration** enables large icons and header images
5. **Tooltips** provide helpful user guidance
6. **Cursor Customization** improves interaction feedback
7. **Animations** create smooth, polished transitions
8. **Custom Colors** enable unique branding and design
9. **ProvideGroupBarItemBrush** event enables advanced gradient customization
10. **Combine properties** to create cohesive custom themes
references/getting-started.md
# Getting Started with GroupBar (Navigation Pane)
This guide covers the essential steps to create and configure a Syncfusion WinForms GroupBar control in your application. The GroupBar provides an Outlook-style navigation interface for organizing and displaying categorized content.
## Prerequisites and Assembly Dependencies
Before using the GroupBar control, ensure you have the required assemblies referenced in your project.
### Required Assembly
- **Syncfusion.Shared.Base.dll** - Contains the GroupBar control and related classes
### NuGet Package Installation
The recommended way to add the GroupBar control is through NuGet Package Manager:
```powershell
Install-Package Syncfusion.Shared.Base
```
**When to use NuGet:**
- New projects starting from scratch
- Need automatic dependency resolution
- Want easy version management and updates
**Alternative:** You can manually reference the assembly from your Syncfusion installation directory (typically `C:\Program Files (x86)\Syncfusion\Essential Studio\<version>\precompiledassemblies\<framework version>`).
## Namespace Declaration
Add the required namespace to your code file:
```csharp
using Syncfusion.Windows.Forms.Tools;
```
This namespace provides access to:
- `GroupBar` - The main navigation container control
- `GroupBarItem` - Individual navigation items
- `GroupView` - Client control for displaying child items
- `GroupViewItem` - Child items within a GroupView
## Creating GroupBar via Designer
The designer approach is ideal for visual development and rapid prototyping.
### Step 1: Add Control from Toolbox
1. Open your Windows Forms project in Visual Studio
2. Locate the **Syncfusion Controls** section in the toolbox
3. Find the **GroupBar** control (under Navigation category)
4. Drag and drop it onto your form
**Result:** The control is added to your form, and the `Syncfusion.Shared.Base` assembly reference is automatically added to your project.
### Step 2: Configure Dock Property
For navigation panes, GroupBar is typically docked to the left side:
```csharp
// Via Properties window: Set Dock = Left
// Or programmatically:
this.groupBar1.Dock = System.Windows.Forms.DockStyle.Left;
```
**When to use different dock styles:**
- **Left** - Classic Outlook-style navigation (most common)
- **Right** - Right-side navigation panel
- **Top** - Horizontal navigation bar
- **Bottom** - Bottom-docked navigation
- **Fill** - Occupies entire container
### Step 3: Add GroupBar Items
Use the GroupBarItems collection editor:
1. Select the GroupBar control
2. In Properties window, click **GroupBarItems** property
3. Click the ellipsis (...) button
4. Click "Add" to create new items
5. Set properties for each item:
- **Text** - Display name
- **Image** - Icon (optional)
- **Client** - Associated control (set later)
**Designer Example:**
```csharp
// This code is generated by the designer
this.groupBarItem1 = new Syncfusion.Windows.Forms.Tools.GroupBarItem();
this.groupBarItem2 = new Syncfusion.Windows.Forms.Tools.GroupBarItem();
this.groupBarItem3 = new Syncfusion.Windows.Forms.Tools.GroupBarItem();
this.groupBarItem1.Text = "Mail";
this.groupBarItem2.Text = "Calendar";
this.groupBarItem3.Text = "Contacts";
this.groupBar1.GroupBarItems.AddRange(new Syncfusion.Windows.Forms.Tools.GroupBarItem[] {
this.groupBarItem1,
this.groupBarItem2,
this.groupBarItem3
});
```
## Creating GroupBar Programmatically
For dynamic scenarios or when you need full control over initialization.
### Complete Code Example: Basic GroupBar Setup
```csharp
using System;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
namespace GroupBarDemo
{
public partial class Form1 : Form
{
private GroupBar groupBar1;
private GroupBarItem groupBarItem1;
private GroupBarItem groupBarItem2;
private GroupBarItem groupBarItem3;
public Form1()
{
InitializeComponent();
CreateGroupBar();
}
private void CreateGroupBar()
{
// Create GroupBar instance
this.groupBar1 = new GroupBar();
// Configure GroupBar properties
this.groupBar1.Dock = DockStyle.Left;
this.groupBar1.Width = 200;
this.groupBar1.BorderStyle = BorderStyle.FixedSingle;
this.groupBar1.BackColor = System.Drawing.Color.White;
// Create GroupBar items
this.groupBarItem1 = new GroupBarItem();
this.groupBarItem1.Text = "Mail";
this.groupBarItem2 = new GroupBarItem();
this.groupBarItem2.Text = "Calendar";
this.groupBarItem3 = new GroupBarItem();
this.groupBarItem3.Text = "Contacts";
// Add items to GroupBar
this.groupBar1.GroupBarItems.AddRange(new GroupBarItem[] {
this.groupBarItem1,
this.groupBarItem2,
this.groupBarItem3
});
// Add GroupBar to form
this.Controls.Add(this.groupBar1);
}
}
}
```
**Result:** A basic GroupBar with three navigation items appears on the left side of the form. Clicking each item switches the active view.
## Setting Up Client Controls
Each GroupBarItem can host a client control that displays when the item is selected.
### Using Panels as Clients
For simple content, use standard Panel controls:
```csharp
private void SetupClientControls()
{
// Create panels for each GroupBar item
Panel mailPanel = new Panel();
mailPanel.BackColor = System.Drawing.Color.AliceBlue;
Label mailLabel = new Label();
mailLabel.Text = "Mail Content Here";
mailLabel.Dock = DockStyle.Top;
mailPanel.Controls.Add(mailLabel);
Panel calendarPanel = new Panel();
calendarPanel.BackColor = System.Drawing.Color.LightYellow;
Label calendarLabel = new Label();
calendarLabel.Text = "Calendar Content Here";
calendarLabel.Dock = DockStyle.Top;
calendarPanel.Controls.Add(calendarLabel);
// Assign panels as clients
this.groupBarItem1.Client = mailPanel;
this.groupBarItem2.Client = calendarPanel;
// Add panels to GroupBar controls collection
this.groupBar1.Controls.Add(mailPanel);
this.groupBar1.Controls.Add(calendarPanel);
}
```
**When to use Panels:**
- Simple content displays
- Custom layouts with multiple controls
- Need to add controls dynamically
### Using GroupView as Clients
For hierarchical navigation (like Outlook folders or Visual Studio toolbox), use GroupView:
```csharp
private void SetupGroupViewClients()
{
// Create GroupView for Mail items
GroupView mailGroupView = new GroupView();
mailGroupView.Name = "MailGroupView";
mailGroupView.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("Inbox", -1, true, null, "Inbox"),
new GroupViewItem("Drafts", -1, true, null, "Drafts"),
new GroupViewItem("Sent Items", -1, true, null, "SentItems"),
new GroupViewItem("Deleted Items", -1, true, null, "DeletedItems")
});
// Create GroupView for Calendar items
GroupView calendarGroupView = new GroupView();
calendarGroupView.Name = "CalendarGroupView";
calendarGroupView.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("My Calendar", -1, true, null, "MyCalendar"),
new GroupViewItem("Team Calendar", -1, true, null, "TeamCalendar"),
new GroupViewItem("Holidays", -1, true, null, "Holidays")
});
// Assign GroupViews as clients
this.groupBarItem1.Client = mailGroupView;
this.groupBarItem2.Client = calendarGroupView;
// Add GroupViews to GroupBar
this.groupBar1.Controls.Add(mailGroupView);
this.groupBar1.Controls.Add(calendarGroupView);
}
```
**When to use GroupView:**
- Need hierarchical navigation (folders, categories)
- Building Outlook-style interfaces
- Creating toolbox-style item lists
## Basic Configuration Options
### Text Alignment
Control how item text is aligned:
```csharp
// Center alignment (default)
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Center;
// Left alignment
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Left;
// Right alignment
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Right;
```
### Initial Selection
Set which item is initially selected:
```csharp
// Select the first item (index 0)
this.groupBar1.SelectedItem = 0;
// Select by item reference
this.groupBar1.SelectedItem = this.groupBar1.GroupBarItems.IndexOf(this.groupBarItem2);
```
### Item Height
Adjust the height of GroupBar item headers:
```csharp
// Default is typically 24
this.groupBar1.GroupBarItemHeight = 32;
```
**When to adjust height:**
- Using larger fonts or icons
- Accommodating touch interfaces
- Matching specific design requirements
## Complete Minimal Working Example
Here's a fully functional GroupBar application:
```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
namespace GroupBarMinimalExample
{
public partial class MainForm : Form
{
private GroupBar groupBar1;
private GroupBarItem mailItem;
private GroupBarItem calendarItem;
private GroupBarItem contactsItem;
private GroupView mailView;
private Panel calendarPanel;
private ListBox contactsListBox;
public MainForm()
{
InitializeComponent();
InitializeGroupBar();
}
private void InitializeGroupBar()
{
// Create and configure GroupBar
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 220,
BorderStyle = BorderStyle.FixedSingle,
BackColor = Color.White,
Font = new Font("Segoe UI", 9F)
};
// Create GroupBar items
this.mailItem = new GroupBarItem { Text = "Mail" };
this.calendarItem = new GroupBarItem { Text = "Calendar" };
this.contactsItem = new GroupBarItem { Text = "Contacts" };
// Create mail GroupView with folders
this.mailView = new GroupView { Name = "MailView" };
this.mailView.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("Inbox (12)", -1, true, null, "Inbox"),
new GroupViewItem("Drafts (3)", -1, true, null, "Drafts"),
new GroupViewItem("Sent Items", -1, true, null, "Sent"),
new GroupViewItem("Deleted Items", -1, true, null, "Deleted")
});
// Create calendar panel
this.calendarPanel = new Panel
{
BackColor = Color.LightYellow,
Dock = DockStyle.Fill
};
MonthCalendar calendar = new MonthCalendar
{
Location = new Point(10, 10)
};
this.calendarPanel.Controls.Add(calendar);
// Create contacts list
this.contactsListBox = new ListBox
{
Dock = DockStyle.Fill,
Items = { "John Doe", "Jane Smith", "Bob Johnson", "Alice Williams" }
};
// Assign clients to items
this.mailItem.Client = this.mailView;
this.calendarItem.Client = this.calendarPanel;
this.contactsItem.Client = this.contactsListBox;
// Add all controls to GroupBar
this.groupBar1.Controls.Add(this.mailView);
this.groupBar1.Controls.Add(this.calendarPanel);
this.groupBar1.Controls.Add(this.contactsListBox);
// Add items to GroupBar
this.groupBar1.GroupBarItems.AddRange(new GroupBarItem[]
{
this.mailItem,
this.calendarItem,
this.contactsItem
});
// Set initial selection
this.groupBar1.SelectedItem = 0;
// Add GroupBar to form
this.Controls.Add(this.groupBar1);
// Handle selection changes
this.groupBar1.GroupBarItemSelected += GroupBar1_GroupBarItemSelected;
}
private void GroupBar1_GroupBarItemSelected(object sender, EventArgs e)
{
int selectedIndex = this.groupBar1.SelectedItem;
string selectedText = this.groupBar1.GroupBarItems[selectedIndex].Text;
this.Text = $"GroupBar Demo - {selectedText}";
}
}
}
```
**Result:** A fully functional Outlook-style navigation pane with Mail (showing folders), Calendar (showing a calendar control), and Contacts (showing a list).
## Common Patterns and Best Practices
### Pattern 1: Dynamic Item Creation
Create items based on runtime data:
```csharp
private void LoadNavigationFromData(List<NavigationCategory> categories)
{
foreach (var category in categories)
{
GroupBarItem item = new GroupBarItem
{
Text = category.Name
};
Panel itemPanel = new Panel();
// ... populate panel based on category data
item.Client = itemPanel;
this.groupBar1.Controls.Add(itemPanel);
this.groupBar1.GroupBarItems.Add(item);
}
}
```
### Pattern 2: Lazy Loading Client Content
Improve performance by loading content only when needed:
```csharp
private void GroupBar1_GroupBarItemSelected(object sender, EventArgs e)
{
GroupBarItem selectedItem = this.groupBar1.GroupBarItems[this.groupBar1.SelectedItem];
// Check if client needs initialization
if (selectedItem.Client == null || selectedItem.Client.Controls.Count == 0)
{
LoadClientContent(selectedItem);
}
}
private void LoadClientContent(GroupBarItem item)
{
// Create and populate client control on demand
if (item.Client == null)
{
Panel panel = new Panel();
item.Client = panel;
this.groupBar1.Controls.Add(panel);
}
// Load data into client
// ... (your loading logic)
}
```
## Troubleshooting Common Issues
### Issue: Client Control Not Displaying
**Problem:** Added client control but nothing shows when item is selected.
**Solution:** Ensure you've done both steps:
```csharp
// Step 1: Assign client
groupBarItem.Client = myControl;
// Step 2: Add to GroupBar controls (easy to forget!)
groupBar1.Controls.Add(myControl);
```
### Issue: Items Appear Cut Off
**Problem:** GroupBar items are too tall or text is truncated.
**Solution:** Adjust item height and GroupBar width:
```csharp
this.groupBar1.GroupBarItemHeight = 30;
this.groupBar1.Width = 250;
```
### Issue: Selection Events Not Firing
**Problem:** GroupBarItemSelected event handler not called.
**Solution:** Ensure event is wired up after GroupBar initialization:
```csharp
this.groupBar1.GroupBarItemSelected += GroupBar1_GroupBarItemSelected;
```
### Issue: Null Reference When Accessing SelectedItem
**Problem:** Exception when accessing `GroupBarItems[SelectedItem]`.
**Solution:** Check if items exist and SelectedItem is valid:
```csharp
if (this.groupBar1.GroupBarItems.Count > 0 &&
this.groupBar1.SelectedItem >= 0 &&
this.groupBar1.SelectedItem < this.groupBar1.GroupBarItems.Count)
{
var item = this.groupBar1.GroupBarItems[this.groupBar1.SelectedItem];
// ... safe to use item
}
```
## Next Steps
Now that you have a basic GroupBar set up, explore these advanced topics:
- **GroupView Integration** - Create hierarchical navigation with child items
- **Stacked Mode** - Enable Outlook-style collapsible navigation pane
- **Visual Styles** - Apply Office themes (2007, 2010, 2016)
- **Appearance Customization** - Customize colors, fonts, and borders
- **Event Handling** - Respond to item selections and state changes
## Key Takeaways
1. **Assembly Required**: Always reference `Syncfusion.Shared.Base.dll`
2. **Namespace**: Import `Syncfusion.Windows.Forms.Tools`
3. **Two-Step Client Setup**: Assign client AND add to Controls collection
4. **Dock Left**: Standard pattern for navigation panes
5. **GroupView for Hierarchy**: Use GroupView when you need child items
6. **Event Handling**: Wire up GroupBarItemSelected for navigation logic
references/groupbar-items-and-structure.md
# GroupBar Items and Structure
This guide covers the structure and configuration of GroupBarItems, which are the individual navigation tabs in the GroupBar control. Understanding GroupBarItem properties and management is essential for building effective navigation interfaces.
## Table of Contents
- [GroupBarItem Overview](#groupbaritem-overview)
- [Creating GroupBarItem Instances](#creating-groupbaritem-instances)
- [Text Property for Item Labels](#text-property-for-item-labels)
- [Image Property for Item Icons](#image-property-for-item-icons)
- [Client Property - Linking to Controls](#client-property---linking-to-controls)
- [GroupBarItems Collection Management](#groupbaritems-collection-management)
- [SelectedItem Property](#selecteditem-property)
- [Item Selection and Navigation](#item-selection-and-navigation)
- [GroupBarItemSelected Event Handling](#groupbaritemselected-event-handling)
- [Complete Examples](#complete-examples)
## GroupBarItem Overview
A **GroupBarItem** represents an individual navigation tab or button in the GroupBar control. Each item:
- Displays a text label and optional icon
- Can host a client control (the content shown when selected)
- Supports selection states and visual feedback
- Can be customized independently
**Container-Client Model:**
The GroupBar follows a container-client architecture where:
- **GroupBar** = Container (holds navigation items)
- **GroupBarItem** = Navigation tab/button
- **Client Control** = Content displayed when item is selected (typically GroupView or Panel)
```csharp
// Basic relationship structure
GroupBar
├── GroupBarItem ("Mail")
│ └── Client: GroupView (mail folders)
├── GroupBarItem ("Calendar")
│ └── Client: Panel (calendar display)
└── GroupBarItem ("Contacts")
└── Client: ListBox (contact list)
```
## Creating GroupBarItem Instances
### Method 1: Via Designer
1. Select GroupBar control
2. Click **GroupBarItems** property in Properties window
3. Click ellipsis (...) to open Collection Editor
4. Click "Add" to create new items
5. Configure properties for each item
### Method 2: Programmatic Creation
```csharp
using Syncfusion.Windows.Forms.Tools;
// Create individual items
GroupBarItem mailItem = new GroupBarItem();
GroupBarItem calendarItem = new GroupBarItem();
GroupBarItem contactsItem = new GroupBarItem();
// Configure basic properties
mailItem.Text = "Mail";
calendarItem.Text = "Calendar";
contactsItem.Text = "Contacts";
// Add to GroupBar
this.groupBar1.GroupBarItems.AddRange(new GroupBarItem[] {
mailItem,
calendarItem,
contactsItem
});
```
**When to use programmatic creation:**
- Loading navigation structure from database or configuration
- Dynamic UI based on user permissions
- Runtime modification of navigation items
- Generating items from data models
### Method 3: Inline Initialization
```csharp
// Create and initialize in one statement
GroupBarItem item = new GroupBarItem
{
Text = "Documents",
Client = new GroupView()
};
```
## Text Property for Item Labels
The **Text** property sets the display label for the GroupBarItem.
### Basic Text Assignment
```csharp
this.groupBarItem1.Text = "Mail";
this.groupBarItem2.Text = "Calendar";
this.groupBarItem3.Text = "Contacts";
```
### Dynamic Text with Counts
Show dynamic information in item labels:
```csharp
private void UpdateMailItemText(int unreadCount)
{
if (unreadCount > 0)
{
this.mailItem.Text = $"Mail ({unreadCount})";
}
else
{
this.mailItem.Text = "Mail";
}
}
// Usage
UpdateMailItemText(12); // Displays "Mail (12)"
```
**When to use dynamic text:**
- Show unread message counts
- Display pending items or notifications
- Indicate data loading status
- Reflect real-time updates
### Text Alignment
Control text alignment across all items:
```csharp
// Left alignment (better for longer text)
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Left;
// Center alignment (default, balanced look)
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Center;
// Right alignment (uncommon, special layouts)
this.groupBar1.TextAlign = Syncfusion.Windows.Forms.Tools.TextAlignment.Right;
```
**Result:** All GroupBarItem text aligns according to the specified setting.
### In-Place Renaming
Allow users to rename items at runtime:
```csharp
// Enable in-place editing for specific item
private void AllowRenameItem(int itemIndex)
{
this.groupBar1.InplaceRenameItem(itemIndex);
}
// Cancel in-place editing
private void CancelRename()
{
this.groupBar1.CancelInplaceRenameItem();
}
// Handle rename event
private void GroupBar1_GroupBarItemRenamed(object sender,
Syncfusion.Windows.Forms.Tools.GroupItemRenamedEventArgs e)
{
Console.WriteLine($"Item at index {e.Index} renamed from '{e.OldLabel}' to '{e.NewLabel}'");
// Validate new name
if (string.IsNullOrWhiteSpace(e.NewLabel))
{
MessageBox.Show("Item name cannot be empty.");
this.groupBar1.GroupBarItems[e.Index].Text = e.OldLabel;
}
}
// Wire up event
this.groupBar1.GroupBarItemRenamed += GroupBar1_GroupBarItemRenamed;
```
**When to use in-place renaming:**
- User-customizable navigation
- Document or project organization tools
- Personalized workspaces
## Image Property for Item Icons
Add visual identity to items with icons.
### Basic Image Assignment
```csharp
// From resources
this.groupBarItem1.Image = Properties.Resources.MailIcon;
this.groupBarItem2.Image = Properties.Resources.CalendarIcon;
this.groupBarItem3.Image = Properties.Resources.ContactsIcon;
```
### Using ImageList
Manage multiple icons efficiently:
```csharp
// Set up ImageList
ImageList imageList = new ImageList();
imageList.ImageSize = new Size(16, 16);
imageList.Images.Add("mail", Properties.Resources.MailIcon);
imageList.Images.Add("calendar", Properties.Resources.CalendarIcon);
imageList.Images.Add("contacts", Properties.Resources.ContactsIcon);
// Assign images from ImageList
this.groupBarItem1.Image = imageList.Images["mail"];
this.groupBarItem2.Image = imageList.Images["calendar"];
this.groupBarItem3.Image = imageList.Images["contacts"];
```
### Large Image Mode
Display larger icons on item headers:
```csharp
// Enable large image mode
this.groupBarItem1.LargeImageMode = true;
this.groupBarItem1.Image = Properties.Resources.LargeMailIcon; // 32x32 or 48x48
```
**When to use large images:**
- Stacked mode (Outlook-style) navigation
- Touch-friendly interfaces
- Emphasis on visual recognition over text
- Modern flat design patterns
### Complete Image Example
```csharp
private void SetupItemImages()
{
// Create and configure ImageList
ImageList smallIcons = new ImageList
{
ImageSize = new Size(16, 16),
ColorDepth = ColorDepth.Depth32Bit
};
ImageList largeIcons = new ImageList
{
ImageSize = new Size(32, 32),
ColorDepth = ColorDepth.Depth32Bit
};
// Load images (from resources, files, or embedded resources)
smallIcons.Images.Add("mail", LoadIcon("mail_16.png"));
smallIcons.Images.Add("calendar", LoadIcon("calendar_16.png"));
largeIcons.Images.Add("mail", LoadIcon("mail_32.png"));
largeIcons.Images.Add("calendar", LoadIcon("calendar_32.png"));
// Assign small images
this.groupBarItem1.Image = smallIcons.Images["mail"];
this.groupBarItem2.Image = smallIcons.Images["calendar"];
// For stacked mode, use large images
this.groupBarItem1.NavigationPaneImage = largeIcons.Images["mail"];
this.groupBarItem2.NavigationPaneImage = largeIcons.Images["calendar"];
}
private Image LoadIcon(string fileName)
{
string iconPath = System.IO.Path.Combine(Application.StartupPath, "Icons", fileName);
return Image.FromFile(iconPath);
}
```
## Client Property - Linking to Controls
The **Client** property links a control to the GroupBarItem. This control is displayed when the item is selected.
### Understanding the Client Property
```csharp
// The Client property accepts any Control
public Control Client { get; set; }
```
**Key Concept:** When a GroupBarItem is selected, its Client control becomes visible in the GroupBar's content area, while other clients are hidden.
### Null Client Handling
```csharp
// Item without client (acts as placeholder or separator)
GroupBarItem placeholderItem = new GroupBarItem
{
Text = "--- Section ---",
Client = null
};
// Check for null client before operations
if (selectedItem.Client != null)
{
// Safe to access client properties
selectedItem.Client.BackColor = Color.White;
}
```
### Common Client Control Types
#### 1. Panel (Simple Content)
```csharp
Panel contentPanel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White,
Padding = new Padding(10)
};
Label label = new Label
{
Text = "Welcome to Mail",
Dock = DockStyle.Top,
Font = new Font("Segoe UI", 14F, FontStyle.Bold)
};
contentPanel.Controls.Add(label);
this.mailItem.Client = contentPanel;
this.groupBar1.Controls.Add(contentPanel);
```
#### 2. GroupView (Hierarchical Navigation)
```csharp
GroupView mailFolders = new GroupView
{
Name = "MailFolders"
};
mailFolders.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("Inbox", -1, true, null, "Inbox"),
new GroupViewItem("Drafts", -1, true, null, "Drafts"),
new GroupViewItem("Sent Items", -1, true, null, "Sent")
});
this.mailItem.Client = mailFolders;
this.groupBar1.Controls.Add(mailFolders);
```
#### 3. Custom User Control
```csharp
// Assuming you have a UserControl named MailViewControl
MailViewControl mailView = new MailViewControl
{
Dock = DockStyle.Fill
};
this.mailItem.Client = mailView;
this.groupBar1.Controls.Add(mailView);
```
#### 4. TreeView (Hierarchical Data)
```csharp
TreeView documentTree = new TreeView
{
Dock = DockStyle.Fill,
BorderStyle = BorderStyle.None
};
TreeNode rootNode = new TreeNode("Documents");
rootNode.Nodes.Add("Recent");
rootNode.Nodes.Add("Shared");
rootNode.Nodes.Add("Archived");
documentTree.Nodes.Add(rootNode);
documentTree.ExpandAll();
this.documentsItem.Client = documentTree;
this.groupBar1.Controls.Add(documentTree);
```
### Critical: Two-Step Client Assignment
**IMPORTANT:** Always perform both steps when assigning a client:
```csharp
// STEP 1: Assign the control as the item's client
groupBarItem.Client = myControl;
// STEP 2: Add the control to GroupBar's Controls collection
groupBar1.Controls.Add(myControl);
// Missing Step 2 is the most common mistake!
```
**Why both steps are required:**
- Step 1: Links the control to the item
- Step 2: Adds control to the form's control hierarchy for rendering
## GroupBarItems Collection Management
The **GroupBarItems** collection contains all navigation items.
### Adding Items
```csharp
// Single item
this.groupBar1.GroupBarItems.Add(newItem);
// Multiple items
this.groupBar1.GroupBarItems.AddRange(new GroupBarItem[] {
item1, item2, item3
});
// Insert at specific position
this.groupBar1.GroupBarItems.Insert(0, firstItem); // Add at beginning
```
### Removing Items
```csharp
// Remove specific item
this.groupBar1.GroupBarItems.Remove(mailItem);
// Remove by index
this.groupBar1.GroupBarItems.RemoveAt(0);
// Remove all items
this.groupBar1.GroupBarItems.Clear();
```
### Accessing Items
```csharp
// By index
GroupBarItem item = this.groupBar1.GroupBarItems[0];
// By iteration
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
Console.WriteLine(item.Text);
}
// Count items
int itemCount = this.groupBar1.GroupBarItems.Count;
// Find item by text
GroupBarItem foundItem = null;
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
if (item.Text == "Mail")
{
foundItem = item;
break;
}
}
```
### Reordering Items
```csharp
// Move item to new position
private void MoveItem(int fromIndex, int toIndex)
{
if (fromIndex >= 0 && fromIndex < this.groupBar1.GroupBarItems.Count &&
toIndex >= 0 && toIndex < this.groupBar1.GroupBarItems.Count)
{
GroupBarItem item = this.groupBar1.GroupBarItems[fromIndex];
this.groupBar1.GroupBarItems.RemoveAt(fromIndex);
this.groupBar1.GroupBarItems.Insert(toIndex, item);
}
}
// Usage: Move first item to last position
MoveItem(0, this.groupBar1.GroupBarItems.Count - 1);
```
## SelectedItem Property
The **SelectedItem** property gets or sets the index of the currently selected item.
### Getting Selected Item
```csharp
// Get selected index
int selectedIndex = this.groupBar1.SelectedItem;
// Get selected GroupBarItem object
if (selectedIndex >= 0 && selectedIndex < this.groupBar1.GroupBarItems.Count)
{
GroupBarItem selectedItem = this.groupBar1.GroupBarItems[selectedIndex];
Console.WriteLine($"Selected: {selectedItem.Text}");
}
```
### Setting Selected Item
```csharp
// Select by index
this.groupBar1.SelectedItem = 0; // Select first item
// Select by finding item
int mailIndex = this.groupBar1.GroupBarItems.IndexOf(this.mailItem);
if (mailIndex >= 0)
{
this.groupBar1.SelectedItem = mailIndex;
}
```
### Handling No Selection
```csharp
// Check if any item is selected (-1 means no selection)
if (this.groupBar1.SelectedItem == -1)
{
// No item selected, set default
this.groupBar1.SelectedItem = 0;
}
```
## Item Selection and Navigation
### Programmatic Navigation
```csharp
// Navigate to next item
private void NavigateNext()
{
int currentIndex = this.groupBar1.SelectedItem;
int nextIndex = currentIndex + 1;
if (nextIndex < this.groupBar1.GroupBarItems.Count)
{
this.groupBar1.SelectedItem = nextIndex;
}
else
{
// Wrap to first item
this.groupBar1.SelectedItem = 0;
}
}
// Navigate to previous item
private void NavigatePrevious()
{
int currentIndex = this.groupBar1.SelectedItem;
int previousIndex = currentIndex - 1;
if (previousIndex >= 0)
{
this.groupBar1.SelectedItem = previousIndex;
}
else
{
// Wrap to last item
this.groupBar1.SelectedItem = this.groupBar1.GroupBarItems.Count - 1;
}
}
```
### Keyboard Navigation
```csharp
// Add keyboard shortcuts for navigation
private void Form1_KeyDown(object sender, KeyEventArgs e)
{
if (e.Control)
{
switch (e.KeyCode)
{
case Keys.D1:
this.groupBar1.SelectedItem = 0;
e.Handled = true;
break;
case Keys.D2:
if (this.groupBar1.GroupBarItems.Count > 1)
this.groupBar1.SelectedItem = 1;
e.Handled = true;
break;
case Keys.D3:
if (this.groupBar1.GroupBarItems.Count > 2)
this.groupBar1.SelectedItem = 2;
e.Handled = true;
break;
case Keys.PageDown:
NavigateNext();
e.Handled = true;
break;
case Keys.PageUp:
NavigatePrevious();
e.Handled = true;
break;
}
}
}
```
## GroupBarItemSelected Event Handling
The **GroupBarItemSelected** event fires when a user selects a different item.
### Basic Event Handling
```csharp
// Wire up event
this.groupBar1.GroupBarItemSelected += GroupBar1_GroupBarItemSelected;
// Event handler
private void GroupBar1_GroupBarItemSelected(object sender, EventArgs e)
{
int selectedIndex = this.groupBar1.SelectedItem;
GroupBarItem selectedItem = this.groupBar1.GroupBarItems[selectedIndex];
Console.WriteLine($"Selected: {selectedItem.Text}");
// Update UI based on selection
this.Text = $"My Application - {selectedItem.Text}";
}
```
### Advanced Selection Handling
```csharp
private void GroupBar1_GroupBarItemSelected(object sender, EventArgs e)
{
int selectedIndex = this.groupBar1.SelectedItem;
// Bounds checking
if (selectedIndex < 0 || selectedIndex >= this.groupBar1.GroupBarItems.Count)
return;
GroupBarItem selectedItem = this.groupBar1.GroupBarItems[selectedIndex];
// Perform actions based on selected item
switch (selectedItem.Text)
{
case "Mail":
LoadMailContent();
break;
case "Calendar":
LoadCalendarContent();
break;
case "Contacts":
LoadContactsContent();
break;
default:
LoadDefaultContent();
break;
}
// Update status bar
UpdateStatusBar($"Viewing: {selectedItem.Text}");
}
private void LoadMailContent()
{
// Lazy load mail data only when needed
if (mailItem.Client != null)
{
GroupView mailView = mailItem.Client as GroupView;
if (mailView != null && mailView.GroupViewItems.Count == 0)
{
// Load mail folders from database
LoadMailFolders(mailView);
}
}
}
```
### Preventing Selection Change
Use the **GroupBarItemSelectionChanging** event to validate or prevent selection changes:
```csharp
this.groupBar1.GroupBarItemSelectionChanging += GroupBar1_GroupBarItemSelectionChanging;
private void GroupBar1_GroupBarItemSelectionChanging(object sender,
Syncfusion.Windows.Forms.Tools.GroupBarItemSelectionChangingEventArgs e)
{
// Check if user has unsaved changes
if (HasUnsavedChanges())
{
DialogResult result = MessageBox.Show(
"You have unsaved changes. Continue?",
"Unsaved Changes",
MessageBoxButtons.YesNo,
MessageBoxIcon.Warning);
if (result == DialogResult.No)
{
// Cancel the selection change
e.Cancel = true;
return;
}
}
Console.WriteLine($"Switching from index {e.OldSelected} to {e.NewSelected}");
}
```
## Complete Examples
### Example 1: Basic Navigation with Three Items
```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
public class BasicNavigationForm : Form
{
private GroupBar groupBar1;
private GroupBarItem mailItem;
private GroupBarItem calendarItem;
private GroupBarItem tasksItem;
private Panel mailPanel;
private Panel calendarPanel;
private Panel tasksPanel;
public BasicNavigationForm()
{
InitializeComponent();
SetupGroupBar();
}
private void SetupGroupBar()
{
// Create GroupBar
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 200,
BorderStyle = BorderStyle.FixedSingle
};
// Create items
this.mailItem = new GroupBarItem { Text = "Mail" };
this.calendarItem = new GroupBarItem { Text = "Calendar" };
this.tasksItem = new GroupBarItem { Text = "Tasks" };
// Create client panels
this.mailPanel = CreateContentPanel("Mail Content", Color.AliceBlue);
this.calendarPanel = CreateContentPanel("Calendar Content", Color.LightYellow);
this.tasksPanel = CreateContentPanel("Tasks Content", Color.LightGreen);
// Assign clients
this.mailItem.Client = this.mailPanel;
this.calendarItem.Client = this.calendarPanel;
this.tasksItem.Client = this.tasksPanel;
// Add clients to GroupBar
this.groupBar1.Controls.AddRange(new Control[] {
this.mailPanel,
this.calendarPanel,
this.tasksPanel
});
// Add items to GroupBar
this.groupBar1.GroupBarItems.AddRange(new GroupBarItem[] {
this.mailItem,
this.calendarItem,
this.tasksItem
});
// Set initial selection
this.groupBar1.SelectedItem = 0;
// Handle selection
this.groupBar1.GroupBarItemSelected += (s, e) =>
{
int index = this.groupBar1.SelectedItem;
string itemText = this.groupBar1.GroupBarItems[index].Text;
this.Text = $"Navigation Demo - {itemText}";
};
// Add to form
this.Controls.Add(this.groupBar1);
}
private Panel CreateContentPanel(string labelText, Color backColor)
{
Panel panel = new Panel
{
Dock = DockStyle.Fill,
BackColor = backColor,
Padding = new Padding(20)
};
Label label = new Label
{
Text = labelText,
Dock = DockStyle.Top,
Font = new Font("Segoe UI", 16F, FontStyle.Bold),
Height = 40
};
panel.Controls.Add(label);
return panel;
}
}
```
**Result:** A simple three-item navigation interface where clicking each item displays a different colored panel with a label.
### Example 2: Multiple Items with GroupView Clients
```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
public class OutlookStyleForm : Form
{
private GroupBar groupBar1;
public OutlookStyleForm()
{
InitializeComponent();
CreateOutlookInterface();
}
private void CreateOutlookInterface()
{
// Create GroupBar
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 220,
BorderStyle = BorderStyle.Fixed3D,
Font = new Font("Segoe UI", 9F)
};
// Create navigation items
CreateMailSection();
CreateCalendarSection();
CreateContactsSection();
CreateTasksSection();
// Set initial selection
this.groupBar1.SelectedItem = 0;
// Handle item selection
this.groupBar1.GroupBarItemSelected += OnNavigationChanged;
// Add to form
this.Controls.Add(this.groupBar1);
this.Text = "Outlook-Style Navigation";
}
private void CreateMailSection()
{
GroupBarItem mailItem = new GroupBarItem
{
Text = "Mail",
Image = Properties.Resources.MailIcon // 16x16 icon
};
GroupView mailView = new GroupView { Name = "MailView" };
mailView.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("Inbox (15)", 0, true, null, "Inbox"),
new GroupViewItem("Drafts (3)", 1, true, null, "Drafts"),
new GroupViewItem("Sent Items", 2, true, null, "Sent"),
new GroupViewItem("Deleted Items", 3, true, null, "Deleted"),
new GroupViewItem("Junk Email", 4, true, null, "Junk"),
new GroupViewItem("Outbox", 5, true, null, "Outbox")
});
// Handle folder selection
mailView.GroupViewItemSelected += (s, e) =>
{
int selectedIndex = mailView.SelectedItem;
if (selectedIndex >= 0)
{
string folderName = mailView.GroupViewItems[selectedIndex].Text;
Console.WriteLine($"Mail folder selected: {folderName}");
}
};
mailItem.Client = mailView;
this.groupBar1.Controls.Add(mailView);
this.groupBar1.GroupBarItems.Add(mailItem);
}
private void CreateCalendarSection()
{
GroupBarItem calendarItem = new GroupBarItem
{
Text = "Calendar",
Image = Properties.Resources.CalendarIcon
};
GroupView calendarView = new GroupView { Name = "CalendarView" };
calendarView.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("My Calendar", 0, true, null, "MyCalendar"),
new GroupViewItem("Team Calendar", 1, true, null, "TeamCalendar"),
new GroupViewItem("Birthdays", 2, true, null, "Birthdays"),
new GroupViewItem("Holidays", 3, true, null, "Holidays")
});
calendarItem.Client = calendarView;
this.groupBar1.Controls.Add(calendarView);
this.groupBar1.GroupBarItems.Add(calendarItem);
}
private void CreateContactsSection()
{
GroupBarItem contactsItem = new GroupBarItem
{
Text = "Contacts",
Image = Properties.Resources.ContactsIcon
};
GroupView contactsView = new GroupView { Name = "ContactsView" };
contactsView.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("All Contacts", 0, true, null, "AllContacts"),
new GroupViewItem("Colleagues", 1, true, null, "Colleagues"),
new GroupViewItem("Friends", 2, true, null, "Friends"),
new GroupViewItem("Family", 3, true, null, "Family")
});
contactsItem.Client = contactsView;
this.groupBar1.Controls.Add(contactsView);
this.groupBar1.GroupBarItems.Add(contactsItem);
}
private void CreateTasksSection()
{
GroupBarItem tasksItem = new GroupBarItem
{
Text = "Tasks",
Image = Properties.Resources.TasksIcon
};
GroupView tasksView = new GroupView { Name = "TasksView" };
tasksView.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("To Do (8)", 0, true, null, "Todo"),
new GroupViewItem("In Progress (4)", 1, true, null, "InProgress"),
new GroupViewItem("Completed", 2, true, null, "Completed"),
new GroupViewItem("Waiting", 3, true, null, "Waiting")
});
tasksItem.Client = tasksView;
this.groupBar1.Controls.Add(tasksView);
this.groupBar1.GroupBarItems.Add(tasksItem);
}
private void OnNavigationChanged(object sender, EventArgs e)
{
int selectedIndex = this.groupBar1.SelectedItem;
if (selectedIndex >= 0 && selectedIndex < this.groupBar1.GroupBarItems.Count)
{
GroupBarItem item = this.groupBar1.GroupBarItems[selectedIndex];
this.Text = $"Outlook-Style Navigation - {item.Text}";
// Update application state based on selection
Console.WriteLine($"Navigated to: {item.Text}");
}
}
}
```
**Result:** A complete Outlook-style navigation interface with Mail, Calendar, Contacts, and Tasks sections, each containing relevant sub-items in a GroupView.
## Key Takeaways
1. **GroupBarItem** represents individual navigation tabs in the GroupBar
2. **Text Property** sets the display label (supports dynamic updates)
3. **Image Property** adds visual icons to items
4. **Client Property** links controls to items (two-step process: assign + add to Controls)
5. **GroupBarItems Collection** manages all items (add, remove, reorder)
6. **SelectedItem** property controls and queries which item is active
7. **GroupBarItemSelected** event handles navigation logic
8. **Container-Client Model** separates navigation (GroupBar/Items) from content (Client controls)
references/groupview-and-child-items.md
# GroupView and Child Items
This guide covers the GroupView control, which serves as the client control for GroupBarItems when you need hierarchical navigation. GroupView displays child items in a list format, similar to the Visual Studio toolbox or Outlook folder list.
## Table of Contents
- [GroupView Overview](#groupview-overview)
- [Creating GroupView Instances](#creating-groupview-instances)
- [GroupViewItem for Child Items](#groupviewitem-for-child-items)
- [GroupViewItem Constructor Parameters](#groupviewitem-constructor-parameters)
- [Adding Items to GroupViewItems Collection](#adding-items-to-groupviewitems-collection)
- [Linking GroupView to GroupBarItem](#linking-groupview-to-groupbaritem)
- [Item Selection in GroupView](#item-selection-in-groupview)
- [GroupViewItemSelected Event Handling](#groupviewitemselected-event-handling)
- [Complete Toolbox-Style Example](#complete-toolbox-style-example)
- [Complete Outlook-Style Example](#complete-outlook-style-example)
## GroupView Overview
**GroupView** is a specialized control designed to work as the client control for GroupBarItems. It provides:
- List-based display of child items
- Single or multiple item selection
- Icon support for items
- Integration with GroupBar navigation
- Event handling for item selection
**When to use GroupView:**
- Building Outlook-style folder hierarchies
- Creating Visual Studio toolbox clones
- Displaying categorized lists (mail folders, document categories, tool palettes)
- Need selectable child items under navigation tabs
**When to use alternatives:**
- Simple content display → Use Panel
- Tree-structured data → Use TreeView
- Grid-based data → Use DataGridView
- Custom layouts → Use custom UserControl
### GroupView vs. Other Controls
| Control | Best For | Selection | Hierarchy |
|---------|----------|-----------|-----------|
| **GroupView** | Flat item lists, Outlook folders | Single/Multi | Single level |
| **TreeView** | Tree structures, nested folders | Single | Multi-level |
| **ListBox** | Simple lists | Single/Multi | None |
| **Panel** | Custom layouts | N/A | N/A |
## Creating GroupView Instances
### Method 1: Programmatic Creation
```csharp
using Syncfusion.Windows.Forms.Tools;
// Create GroupView
GroupView mailFolders = new GroupView();
mailFolders.Name = "MailFolders";
// Configure appearance (optional)
mailFolders.BackColor = System.Drawing.Color.White;
mailFolders.ForeColor = System.Drawing.Color.Black;
```
### Method 2: Designer Creation
1. Drag GroupView control from toolbox onto form
2. Set its properties in Properties window
3. Add GroupViewItems using collection editor
**Note:** When using the designer, GroupView is typically added to the form first, then assigned as a client to a GroupBarItem.
### Method 3: Inline Initialization
```csharp
GroupView folders = new GroupView
{
Name = "DocumentFolders",
BackColor = System.Drawing.Color.WhiteSmoke,
IntegralHeight = true
};
```
## GroupViewItem for Child Items
**GroupViewItem** represents individual items within a GroupView. Each item:
- Displays text and optional icon
- Can be visible or hidden
- Supports selection states
- Can store custom data via Tag property
- Has a unique key for identification
### Basic GroupViewItem Creation
```csharp
// Simple text-only item
GroupViewItem item1 = new GroupViewItem("Inbox");
// Item with all parameters
GroupViewItem item2 = new GroupViewItem(
"Drafts", // text
0, // imageIndex
true, // visible
null, // tag
"DraftsKey" // key
);
```
## GroupViewItem Constructor Parameters
The GroupViewItem constructor accepts five parameters:
```csharp
public GroupViewItem(
string text, // Display text
int imageIndex, // Icon index (-1 for no icon)
bool visible, // Visibility
object tag, // Custom data
string key // Unique identifier
)
```
### Parameter Details
#### 1. Text (string)
The display text for the item.
```csharp
// Basic text
GroupViewItem inbox = new GroupViewItem("Inbox", -1, true, null, "Inbox");
// Text with counts
GroupViewItem inboxWithCount = new GroupViewItem("Inbox (15)", -1, true, null, "Inbox");
// Dynamic text updates
private void UpdateFolderCount(GroupViewItem item, int count)
{
string baseName = item.Key; // e.g., "Inbox"
item.Text = count > 0 ? $"{baseName} ({count})" : baseName;
}
```
**When to include counts in text:**
- Unread message counts (mail folders)
- Pending items (task lists)
- Notification badges (alerts)
#### 2. ImageIndex (int)
Index of the icon in an associated ImageList (-1 means no icon).
```csharp
// Set up ImageList first
ImageList folderIcons = new ImageList();
folderIcons.ImageSize = new Size(16, 16);
folderIcons.Images.Add("inbox", Properties.Resources.InboxIcon);
folderIcons.Images.Add("drafts", Properties.Resources.DraftsIcon);
folderIcons.Images.Add("sent", Properties.Resources.SentIcon);
// Assign ImageList to GroupView
mailFolders.ImageList = folderIcons;
// Create items with image indices
GroupViewItem inbox = new GroupViewItem("Inbox", 0, true, null, "Inbox");
GroupViewItem drafts = new GroupViewItem("Drafts", 1, true, null, "Drafts");
GroupViewItem sent = new GroupViewItem("Sent Items", 2, true, null, "Sent");
// No icon
GroupViewItem separator = new GroupViewItem("---", -1, true, null, "Separator");
```
**Best practices for icons:**
- Use consistent icon size (16x16 for standard, 24x24 for touch)
- Provide visual distinction between item types
- Use recognizable metaphors (envelope for mail, calendar for dates)
#### 3. Visible (bool)
Controls whether the item is displayed.
```csharp
// Always visible
GroupViewItem visible = new GroupViewItem("Always Visible", -1, true, null, "Visible");
// Hidden by default
GroupViewItem hidden = new GroupViewItem("Hidden Folder", -1, false, null, "Hidden");
// Toggle visibility at runtime
private void ToggleItemVisibility(GroupViewItem item)
{
item.Visible = !item.Visible;
}
// Show items based on condition
private void ShowAdvancedFolders(bool show)
{
foreach (GroupViewItem item in mailFolders.GroupViewItems)
{
if (item.Tag is string tag && tag == "Advanced")
{
item.Visible = show;
}
}
}
```
**When to use hidden items:**
- User permission-based visibility
- "Show advanced options" features
- Temporarily disabled features
- Filtering/search results
#### 4. Tag (object)
Stores custom data associated with the item.
```csharp
// Store folder ID
GroupViewItem inbox = new GroupViewItem("Inbox", 0, true, 12345, "Inbox");
// Store custom object
public class FolderInfo
{
public int FolderId { get; set; }
public string Path { get; set; }
public DateTime LastAccessed { get; set; }
}
FolderInfo inboxInfo = new FolderInfo
{
FolderId = 12345,
Path = "/Mail/Inbox",
LastAccessed = DateTime.Now
};
GroupViewItem inboxWithInfo = new GroupViewItem("Inbox", 0, true, inboxInfo, "Inbox");
// Retrieve tag data
private void OnItemSelected(GroupViewItem item)
{
if (item.Tag is FolderInfo folderInfo)
{
LoadFolderContents(folderInfo.FolderId);
Console.WriteLine($"Folder path: {folderInfo.Path}");
}
else if (item.Tag is int folderId)
{
LoadFolderContents(folderId);
}
}
```
**Common uses for Tag:**
- Database IDs
- File paths
- Configuration objects
- State information
#### 5. Key (string)
Unique identifier for the item.
```csharp
// Use descriptive keys
GroupViewItem inbox = new GroupViewItem("Inbox", 0, true, null, "Inbox");
GroupViewItem sent = new GroupViewItem("Sent Items", 0, true, null, "SentItems");
// Find item by key
private GroupViewItem FindItemByKey(GroupView groupView, string key)
{
foreach (GroupViewItem item in groupView.GroupViewItems)
{
if (item.Key == key)
return item;
}
return null;
}
// Usage
GroupViewItem inboxItem = FindItemByKey(mailFolders, "Inbox");
if (inboxItem != null)
{
inboxItem.Text = "Inbox (New Messages)";
}
```
**Key naming conventions:**
- Use CamelCase or PascalCase
- Make keys descriptive
- Avoid spaces and special characters
- Keep keys consistent across application
## Adding Items to GroupViewItems Collection
### Adding Individual Items
```csharp
GroupView mailFolders = new GroupView();
// Create items
GroupViewItem inbox = new GroupViewItem("Inbox", 0, true, null, "Inbox");
GroupViewItem drafts = new GroupViewItem("Drafts", 1, true, null, "Drafts");
// Add one at a time
mailFolders.GroupViewItems.Add(inbox);
mailFolders.GroupViewItems.Add(drafts);
```
### Adding Multiple Items
```csharp
GroupView mailFolders = new GroupView();
// Add array of items
mailFolders.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("Inbox", 0, true, null, "Inbox"),
new GroupViewItem("Drafts", 1, true, null, "Drafts"),
new GroupViewItem("Sent Items", 2, true, null, "Sent"),
new GroupViewItem("Deleted Items", 3, true, null, "Deleted")
});
```
### Inserting Items at Specific Position
```csharp
// Insert at beginning
mailFolders.GroupViewItems.Insert(0, new GroupViewItem("Priority", 0, true, null, "Priority"));
// Insert at end
mailFolders.GroupViewItems.Insert(
mailFolders.GroupViewItems.Count,
new GroupViewItem("Archive", 5, true, null, "Archive")
);
// Insert after specific item
int inboxIndex = FindItemIndex(mailFolders, "Inbox");
if (inboxIndex >= 0)
{
mailFolders.GroupViewItems.Insert(
inboxIndex + 1,
new GroupViewItem("Unread", 0, true, null, "Unread")
);
}
```
### Removing Items
```csharp
// Remove by reference
GroupViewItem itemToRemove = FindItemByKey(mailFolders, "Deleted");
if (itemToRemove != null)
{
mailFolders.GroupViewItems.Remove(itemToRemove);
}
// Remove by index
mailFolders.GroupViewItems.RemoveAt(0);
// Remove all items
mailFolders.GroupViewItems.Clear();
```
### Dynamic Item Management
```csharp
// Load folders from database
private void LoadMailFolders(GroupView groupView)
{
groupView.GroupViewItems.Clear();
// Fetch folder list from database
List<MailFolder> folders = GetMailFoldersFromDatabase();
foreach (var folder in folders)
{
GroupViewItem item = new GroupViewItem(
$"{folder.Name} ({folder.UnreadCount})",
GetIconIndex(folder.Type),
true,
folder.Id,
folder.Name
);
groupView.GroupViewItems.Add(item);
}
}
private int GetIconIndex(string folderType)
{
return folderType switch
{
"Inbox" => 0,
"Drafts" => 1,
"Sent" => 2,
"Deleted" => 3,
_ => -1
};
}
```
## Linking GroupView to GroupBarItem
To display a GroupView when a GroupBarItem is selected, follow the **two-step process**:
### Step 1: Assign GroupView as Client
```csharp
GroupBarItem mailItem = new GroupBarItem();
mailItem.Text = "Mail";
GroupView mailFolders = new GroupView();
// ... add items to mailFolders ...
// Step 1: Set GroupView as the client
mailItem.Client = mailFolders;
```
### Step 2: Add GroupView to GroupBar Controls
```csharp
// Step 2: Add to GroupBar's Controls collection
groupBar1.Controls.Add(mailFolders);
```
### Complete Integration Example
```csharp
private void SetupMailNavigation()
{
// Create GroupBarItem
GroupBarItem mailItem = new GroupBarItem
{
Text = "Mail"
};
// Create GroupView
GroupView mailFolders = new GroupView
{
Name = "MailFolders"
};
// Add folders
mailFolders.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("Inbox (15)", 0, true, null, "Inbox"),
new GroupViewItem("Drafts (3)", 1, true, null, "Drafts"),
new GroupViewItem("Sent Items", 2, true, null, "Sent"),
new GroupViewItem("Deleted Items", 3, true, null, "Deleted"),
new GroupViewItem("Junk Email", 4, true, null, "Junk")
});
// CRITICAL: Both steps required
mailItem.Client = mailFolders; // Step 1
this.groupBar1.Controls.Add(mailFolders); // Step 2
// Add item to GroupBar
this.groupBar1.GroupBarItems.Add(mailItem);
}
```
**Common mistake:** Forgetting Step 2. The GroupView won't display without being added to the Controls collection.
## Item Selection in GroupView
### Getting Selected Item
```csharp
// Get selected item index
int selectedIndex = mailFolders.SelectedItem;
// Get selected GroupViewItem
if (selectedIndex >= 0 && selectedIndex < mailFolders.GroupViewItems.Count)
{
GroupViewItem selectedItem = mailFolders.GroupViewItems[selectedIndex];
Console.WriteLine($"Selected: {selectedItem.Text}");
}
```
### Setting Selected Item
```csharp
// Select by index
mailFolders.SelectedItem = 0; // Select first item (Inbox)
// Select by finding item
GroupViewItem inboxItem = FindItemByKey(mailFolders, "Inbox");
if (inboxItem != null)
{
int index = mailFolders.GroupViewItems.IndexOf(inboxItem);
if (index >= 0)
{
mailFolders.SelectedItem = index;
}
}
// Programmatic selection helper
private void SelectItemByKey(GroupView groupView, string key)
{
for (int i = 0; i < groupView.GroupViewItems.Count; i++)
{
if (groupView.GroupViewItems[i].Key == key)
{
groupView.SelectedItem = i;
break;
}
}
}
```
### Multi-Select Support
GroupView supports selecting multiple items:
```csharp
// Enable multi-selection (if supported by version)
mailFolders.MultiSelect = true;
// Get all selected items
private List<GroupViewItem> GetSelectedItems(GroupView groupView)
{
List<GroupViewItem> selected = new List<GroupViewItem>();
// Implementation depends on control version
// Check documentation for your specific version
return selected;
}
```
## GroupViewItemSelected Event Handling
The **GroupViewItemSelected** event fires when a user clicks an item in the GroupView.
### Basic Event Handling
```csharp
// Wire up event
mailFolders.GroupViewItemSelected += MailFolders_GroupViewItemSelected;
// Event handler
private void MailFolders_GroupViewItemSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view != null)
{
int selectedIndex = view.SelectedItem;
if (selectedIndex >= 0 && selectedIndex < view.GroupViewItems.Count)
{
GroupViewItem item = view.GroupViewItems[selectedIndex];
Console.WriteLine($"Folder selected: {item.Text}");
// Load folder contents
LoadFolderContents(item.Key);
}
}
}
```
### Advanced Event Handling with Tag Data
```csharp
private void MailFolders_GroupViewItemSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view == null) return;
int selectedIndex = view.SelectedItem;
if (selectedIndex < 0 || selectedIndex >= view.GroupViewItems.Count)
return;
GroupViewItem item = view.GroupViewItems[selectedIndex];
// Use Tag to access folder information
if (item.Tag is int folderId)
{
LoadMailMessages(folderId);
}
else if (item.Tag is FolderInfo folderInfo)
{
LoadMailMessages(folderInfo.FolderId);
UpdateRecentFolders(folderInfo);
}
// Update UI
UpdateStatusBar($"Viewing: {item.Text}");
UpdateToolbar(item.Key);
}
private void LoadMailMessages(int folderId)
{
// Query database for messages in this folder
// Display in main content area
Console.WriteLine($"Loading messages for folder ID: {folderId}");
}
```
### Multiple GroupViews Event Handling
When using multiple GroupViews, identify which one fired the event:
```csharp
private void SetupEventHandlers()
{
// Mail folders
mailFolders.GroupViewItemSelected += OnFolderSelected;
mailFolders.Tag = "Mail";
// Calendar views
calendarViews.GroupViewItemSelected += OnFolderSelected;
calendarViews.Tag = "Calendar";
// Contacts categories
contactsCategories.GroupViewItemSelected += OnFolderSelected;
contactsCategories.Tag = "Contacts";
}
private void OnFolderSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view == null) return;
string section = view.Tag as string ?? "Unknown";
int selectedIndex = view.SelectedItem;
if (selectedIndex >= 0 && selectedIndex < view.GroupViewItems.Count)
{
GroupViewItem item = view.GroupViewItems[selectedIndex];
Console.WriteLine($"{section} - {item.Text} selected");
switch (section)
{
case "Mail":
LoadMailFolder(item);
break;
case "Calendar":
LoadCalendarView(item);
break;
case "Contacts":
LoadContactsCategory(item);
break;
}
}
}
```
## Complete Toolbox-Style Example
A Visual Studio toolbox clone with categorized controls:
```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
public class ToolboxForm : Form
{
private GroupBar toolbox;
private Panel contentPanel;
private Label infoLabel;
public ToolboxForm()
{
this.Text = "Control Toolbox";
this.Size = new Size(800, 600);
CreateToolbox();
CreateContentArea();
}
private void CreateToolbox()
{
// Create GroupBar for toolbox
this.toolbox = new GroupBar
{
Dock = DockStyle.Left,
Width = 220,
BorderStyle = BorderStyle.FixedSingle,
Font = new Font("Segoe UI", 9F)
};
// Create control categories
CreateCommonControlsCategory();
CreateContainersCategory();
CreateDataCategory();
CreateDialogsCategory();
// Set initial selection
this.toolbox.SelectedItem = 0;
// Add to form
this.Controls.Add(this.toolbox);
}
private void CreateCommonControlsCategory()
{
GroupBarItem item = new GroupBarItem
{
Text = "Common Controls"
};
GroupView controlsList = new GroupView
{
Name = "CommonControls"
};
controlsList.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("Pointer", -1, true, typeof(Control), "Pointer"),
new GroupViewItem("Button", -1, true, typeof(Button), "Button"),
new GroupViewItem("CheckBox", -1, true, typeof(CheckBox), "CheckBox"),
new GroupViewItem("RadioButton", -1, true, typeof(RadioButton), "RadioButton"),
new GroupViewItem("Label", -1, true, typeof(Label), "Label"),
new GroupViewItem("TextBox", -1, true, typeof(TextBox), "TextBox"),
new GroupViewItem("ListBox", -1, true, typeof(ListBox), "ListBox"),
new GroupViewItem("ComboBox", -1, true, typeof(ComboBox), "ComboBox"),
new GroupViewItem("DateTimePicker", -1, true, typeof(DateTimePicker), "DateTimePicker")
});
controlsList.GroupViewItemSelected += ControlsList_ItemSelected;
item.Client = controlsList;
this.toolbox.Controls.Add(controlsList);
this.toolbox.GroupBarItems.Add(item);
}
private void CreateContainersCategory()
{
GroupBarItem item = new GroupBarItem
{
Text = "Containers"
};
GroupView controlsList = new GroupView
{
Name = "Containers"
};
controlsList.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("Panel", -1, true, typeof(Panel), "Panel"),
new GroupViewItem("GroupBox", -1, true, typeof(GroupBox), "GroupBox"),
new GroupViewItem("TabControl", -1, true, typeof(TabControl), "TabControl"),
new GroupViewItem("FlowLayoutPanel", -1, true, typeof(FlowLayoutPanel), "FlowLayoutPanel"),
new GroupViewItem("TableLayoutPanel", -1, true, typeof(TableLayoutPanel), "TableLayoutPanel"),
new GroupViewItem("SplitContainer", -1, true, typeof(SplitContainer), "SplitContainer")
});
controlsList.GroupViewItemSelected += ControlsList_ItemSelected;
item.Client = controlsList;
this.toolbox.Controls.Add(controlsList);
this.toolbox.GroupBarItems.Add(item);
}
private void CreateDataCategory()
{
GroupBarItem item = new GroupBarItem
{
Text = "Data"
};
GroupView controlsList = new GroupView
{
Name = "Data"
};
controlsList.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("DataGridView", -1, true, typeof(DataGridView), "DataGridView"),
new GroupViewItem("BindingSource", -1, true, typeof(BindingSource), "BindingSource"),
new GroupViewItem("BindingNavigator", -1, true, typeof(BindingNavigator), "BindingNavigator"),
new GroupViewItem("ListView", -1, true, typeof(ListView), "ListView"),
new GroupViewItem("TreeView", -1, true, typeof(TreeView), "TreeView")
});
controlsList.GroupViewItemSelected += ControlsList_ItemSelected;
item.Client = controlsList;
this.toolbox.Controls.Add(controlsList);
this.toolbox.GroupBarItems.Add(item);
}
private void CreateDialogsCategory()
{
GroupBarItem item = new GroupBarItem
{
Text = "Dialogs"
};
GroupView controlsList = new GroupView
{
Name = "Dialogs"
};
controlsList.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("OpenFileDialog", -1, true, typeof(OpenFileDialog), "OpenFileDialog"),
new GroupViewItem("SaveFileDialog", -1, true, typeof(SaveFileDialog), "SaveFileDialog"),
new GroupViewItem("FolderBrowserDialog", -1, true, typeof(FolderBrowserDialog), "FolderBrowserDialog"),
new GroupViewItem("ColorDialog", -1, true, typeof(ColorDialog), "ColorDialog"),
new GroupViewItem("FontDialog", -1, true, typeof(FontDialog), "FontDialog")
});
controlsList.GroupViewItemSelected += ControlsList_ItemSelected;
item.Client = controlsList;
this.toolbox.Controls.Add(controlsList);
this.toolbox.GroupBarItems.Add(item);
}
private void CreateContentArea()
{
this.contentPanel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White,
Padding = new Padding(20)
};
this.infoLabel = new Label
{
Dock = DockStyle.Top,
Height = 100,
Font = new Font("Segoe UI", 12F),
Text = "Select a control from the toolbox"
};
this.contentPanel.Controls.Add(this.infoLabel);
this.Controls.Add(this.contentPanel);
}
private void ControlsList_ItemSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view == null) return;
int selectedIndex = view.SelectedItem;
if (selectedIndex < 0 || selectedIndex >= view.GroupViewItems.Count)
return;
GroupViewItem item = view.GroupViewItems[selectedIndex];
// Get control type from Tag
if (item.Tag is Type controlType)
{
DisplayControlInfo(item.Text, controlType);
}
}
private void DisplayControlInfo(string controlName, Type controlType)
{
string info = $"Control: {controlName}\n\n";
info += $"Type: {controlType.FullName}\n\n";
info += $"Namespace: {controlType.Namespace}\n\n";
info += $"Assembly: {controlType.Assembly.GetName().Name}\n\n";
info += "Click to add this control to your form.";
this.infoLabel.Text = info;
}
}
```
**Result:** A Visual Studio-style toolbox with multiple categories (Common Controls, Containers, Data, Dialogs), each displaying relevant control types.
## Complete Outlook-Style Example
A full Outlook clone with mail folders and rich interaction:
```csharp
using System;
using System.Collections.Generic;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
public class OutlookCloneForm : Form
{
private GroupBar navigationPane;
private Panel contentArea;
private Label titleLabel;
private ListBox messageList;
// Sample data
private Dictionary<string, List<string>> folderContents;
public OutlookCloneForm()
{
this.Text = "Outlook Clone";
this.Size = new Size(1000, 700);
InitializeSampleData();
CreateNavigationPane();
CreateContentArea();
}
private void InitializeSampleData()
{
folderContents = new Dictionary<string, List<string>>
{
{ "Inbox", new List<string> { "Welcome message", "Team meeting update", "Project status", "Budget review" } },
{ "Drafts", new List<string> { "Draft: Reply to client", "Draft: Weekly report" } },
{ "Sent", new List<string> { "RE: Project timeline", "FW: Budget approval" } },
{ "Deleted", new List<string> { "Old newsletter", "Spam message" } }
};
}
private void CreateNavigationPane()
{
this.navigationPane = new GroupBar
{
Dock = DockStyle.Left,
Width = 240,
BorderStyle = BorderStyle.Fixed3D,
Font = new Font("Segoe UI", 9F),
BackColor = Color.FromArgb(245, 246, 247)
};
// Create Mail section
CreateMailSection();
// Create Calendar section
CreateCalendarSection();
// Create Contacts section
CreateContactsSection();
// Create Tasks section
CreateTasksSection();
// Set initial selection
this.navigationPane.SelectedItem = 0;
this.Controls.Add(this.navigationPane);
}
private void CreateMailSection()
{
GroupBarItem mailItem = new GroupBarItem
{
Text = "Mail"
};
GroupView mailFolders = new GroupView
{
Name = "MailFolders",
BackColor = Color.White
};
mailFolders.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("Inbox (15)", -1, true, folderContents["Inbox"], "Inbox"),
new GroupViewItem("Drafts (3)", -1, true, folderContents["Drafts"], "Drafts"),
new GroupViewItem("Sent Items", -1, true, folderContents["Sent"], "Sent"),
new GroupViewItem("Deleted Items (2)", -1, true, folderContents["Deleted"], "Deleted"),
new GroupViewItem("Junk Email", -1, true, new List<string>(), "Junk"),
new GroupViewItem("Outbox", -1, true, new List<string>(), "Outbox"),
new GroupViewItem("Archive", -1, true, new List<string>(), "Archive")
});
mailFolders.GroupViewItemSelected += MailFolders_ItemSelected;
mailItem.Client = mailFolders;
this.navigationPane.Controls.Add(mailFolders);
this.navigationPane.GroupBarItems.Add(mailItem);
}
private void CreateCalendarSection()
{
GroupBarItem calendarItem = new GroupBarItem
{
Text = "Calendar"
};
GroupView calendarViews = new GroupView
{
Name = "CalendarViews",
BackColor = Color.White
};
calendarViews.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("My Calendar", -1, true, null, "MyCalendar"),
new GroupViewItem("Team Calendar", -1, true, null, "TeamCalendar"),
new GroupViewItem("Birthdays", -1, true, null, "Birthdays"),
new GroupViewItem("Holidays", -1, true, null, "Holidays"),
new GroupViewItem("Meetings", -1, true, null, "Meetings")
});
calendarViews.GroupViewItemSelected += CalendarViews_ItemSelected;
calendarItem.Client = calendarViews;
this.navigationPane.Controls.Add(calendarViews);
this.navigationPane.GroupBarItems.Add(calendarItem);
}
private void CreateContactsSection()
{
GroupBarItem contactsItem = new GroupBarItem
{
Text = "Contacts"
};
GroupView contactsCategories = new GroupView
{
Name = "ContactsCategories",
BackColor = Color.White
};
contactsCategories.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("All Contacts (156)", -1, true, null, "AllContacts"),
new GroupViewItem("Colleagues (45)", -1, true, null, "Colleagues"),
new GroupViewItem("Friends (32)", -1, true, null, "Friends"),
new GroupViewItem("Family (18)", -1, true, null, "Family"),
new GroupViewItem("Vendors (12)", -1, true, null, "Vendors")
});
contactsCategories.GroupViewItemSelected += ContactsCategories_ItemSelected;
contactsItem.Client = contactsCategories;
this.navigationPane.Controls.Add(contactsCategories);
this.navigationPane.GroupBarItems.Add(contactsItem);
}
private void CreateTasksSection()
{
GroupBarItem tasksItem = new GroupBarItem
{
Text = "Tasks"
};
GroupView tasksLists = new GroupView
{
Name = "TasksLists",
BackColor = Color.White
};
tasksLists.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("To Do (8)", -1, true, null, "Todo"),
new GroupViewItem("In Progress (4)", -1, true, null, "InProgress"),
new GroupViewItem("Completed (23)", -1, true, null, "Completed"),
new GroupViewItem("Waiting (2)", -1, true, null, "Waiting"),
new GroupViewItem("Deferred", -1, true, null, "Deferred")
});
tasksLists.GroupViewItemSelected += TasksLists_ItemSelected;
tasksItem.Client = tasksLists;
this.navigationPane.Controls.Add(tasksLists);
this.navigationPane.GroupBarItems.Add(tasksItem);
}
private void CreateContentArea()
{
this.contentArea = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White,
Padding = new Padding(0)
};
this.titleLabel = new Label
{
Dock = DockStyle.Top,
Height = 50,
Font = new Font("Segoe UI", 16F, FontStyle.Bold),
Text = "Inbox",
Padding = new Padding(10),
BackColor = Color.FromArgb(230, 235, 240)
};
this.messageList = new ListBox
{
Dock = DockStyle.Fill,
Font = new Font("Segoe UI", 10F),
BorderStyle = BorderStyle.None
};
this.contentArea.Controls.Add(this.messageList);
this.contentArea.Controls.Add(this.titleLabel);
this.Controls.Add(this.contentArea);
}
private void MailFolders_ItemSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view == null) return;
int selectedIndex = view.SelectedItem;
if (selectedIndex < 0 || selectedIndex >= view.GroupViewItems.Count)
return;
GroupViewItem item = view.GroupViewItems[selectedIndex];
this.titleLabel.Text = item.Text;
// Load messages from Tag
if (item.Tag is List<string> messages)
{
this.messageList.Items.Clear();
foreach (string message in messages)
{
this.messageList.Items.Add(message);
}
}
else
{
this.messageList.Items.Clear();
this.messageList.Items.Add($"No messages in {item.Text}");
}
}
private void CalendarViews_ItemSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view == null) return;
int selectedIndex = view.SelectedItem;
if (selectedIndex >= 0 && selectedIndex < view.GroupViewItems.Count)
{
GroupViewItem item = view.GroupViewItems[selectedIndex];
this.titleLabel.Text = item.Text;
this.messageList.Items.Clear();
this.messageList.Items.Add($"Calendar view: {item.Text}");
}
}
private void ContactsCategories_ItemSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view == null) return;
int selectedIndex = view.SelectedItem;
if (selectedIndex >= 0 && selectedIndex < view.GroupViewItems.Count)
{
GroupViewItem item = view.GroupViewItems[selectedIndex];
this.titleLabel.Text = item.Text;
this.messageList.Items.Clear();
this.messageList.Items.Add($"Contacts category: {item.Text}");
}
}
private void TasksLists_ItemSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view == null) return;
int selectedIndex = view.SelectedItem;
if (selectedIndex >= 0 && selectedIndex < view.GroupViewItems.Count)
{
GroupViewItem item = view.GroupViewItems[selectedIndex];
this.titleLabel.Text = item.Text;
this.messageList.Items.Clear();
this.messageList.Items.Add($"Task list: {item.Text}");
}
}
}
```
**Result:** A complete Outlook-style application with Mail, Calendar, Contacts, and Tasks sections. Each section contains relevant sub-items in GroupViews. Clicking a mail folder displays its messages in the content area.
## Key Takeaways
1. **GroupView** displays hierarchical child items for GroupBarItems
2. **GroupViewItem** represents individual child items with text, icons, and data
3. **Five constructor parameters**: text, imageIndex, visible, tag, key
4. **Tag property** stores custom data (IDs, objects, metadata)
5. **Key property** provides unique identifiers for finding items
6. **Two-step integration**: Assign as Client AND add to Controls collection
7. **GroupViewItemSelected** event handles child item selection
8. **Perfect for** Outlook folders, Visual Studio toolbox, categorized lists
references/stacked-mode.md
# Stacked Mode
This guide covers the StackedMode feature of the GroupBar control, which transforms the standard navigation into an Outlook-style collapsible navigation pane with a bottom button bar. Stacked mode provides a compact, professional navigation experience similar to Microsoft Outlook.
## Table of Contents
- [StackedMode Property Overview](#stackedmode-property-overview)
- [Enabling Stacked Mode](#enabling-stacked-mode)
- [Outlook-Style Navigation Pane Behavior](#outlook-style-navigation-pane-behavior)
- [Navigation Pane at Bottom](#navigation-pane-at-bottom)
- [HeaderHeight Property](#headerheight-property)
- [Collapsed and Expanded State](#collapsed-and-expanded-state)
- [Navigation Between Stacked Items](#navigation-between-stacked-items)
- [Serialization Support for Stacked Layout](#serialization-support-for-stacked-layout)
- [Complete Outlook Clone Example](#complete-outlook-clone-example)
## StackedMode Property Overview
The **StackedMode** property enables a compact navigation layout where:
- Selected item displays at the top with full content
- Non-selected items appear as buttons at the bottom
- Navigation pane provides quick access to all items
- Users can customize which items appear in the navigation pane
```csharp
// Enable stacked mode
this.groupBar1.StackedMode = true;
```
**Visual Comparison:**
| Regular Mode | Stacked Mode |
|--------------|--------------|
| All items visible as tabs | Selected item fills space |
| Click to switch items | Bottom navigation buttons |
| Standard layout | Outlook-style layout |
| Fixed item arrangement | Customizable navigation pane |
**When to use Stacked Mode:**
- Building Outlook-style interfaces
- Need more content space
- Want collapsible navigation
- Users benefit from quick-access buttons
- Professional business applications
**When to avoid Stacked Mode:**
- Few navigation items (3 or less)
- Simple, flat navigation preferred
- Touch-first mobile interfaces
- Users unfamiliar with Outlook
## Enabling Stacked Mode
### Basic Activation
```csharp
using Syncfusion.Windows.Forms.Tools;
// Create GroupBar
GroupBar groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 220
};
// Enable stacked mode
groupBar1.StackedMode = true;
```
**Result:** The GroupBar transforms into stacked layout with the selected item at top and navigation buttons at bottom.
### Complete Setup Example
```csharp
private void SetupStackedGroupBar()
{
// Create and configure GroupBar
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 240,
BorderStyle = BorderStyle.Fixed3D,
StackedMode = true, // Enable stacked mode
Font = new Font("Segoe UI", 9F)
};
// Create items
CreateMailItem();
CreateCalendarItem();
CreateContactsItem();
CreateTasksItem();
// Set initial selection
this.groupBar1.SelectedItem = 0;
// Add to form
this.Controls.Add(this.groupBar1);
}
```
### Toggling Stacked Mode at Runtime
Allow users to switch between regular and stacked modes:
```csharp
private void ToggleStackedMode()
{
// Toggle the mode
this.groupBar1.StackedMode = !this.groupBar1.StackedMode;
// Update UI to reflect change
string mode = this.groupBar1.StackedMode ? "Stacked" : "Regular";
Console.WriteLine($"GroupBar mode: {mode}");
}
// Toolbar button or menu item
private void btnToggleMode_Click(object sender, EventArgs e)
{
ToggleStackedMode();
// Update button text
btnToggleMode.Text = this.groupBar1.StackedMode
? "Switch to Regular Mode"
: "Switch to Stacked Mode";
}
```
## Outlook-Style Navigation Pane Behavior
In stacked mode, the GroupBar mimics Microsoft Outlook's navigation pane:
### Navigation Pane Buttons
Items appear as buttons in the navigation pane. Control which items appear:
```csharp
// Set which items appear in navigation pane
this.groupBarItem1.InNavigationPane = true; // Mail - visible
this.groupBarItem2.InNavigationPane = true; // Calendar - visible
this.groupBarItem3.InNavigationPane = true; // Contacts - visible
this.groupBarItem4.InNavigationPane = false; // Tasks - in overflow menu
```
**InNavigationPane = true:** Item shows as button in bottom navigation pane.
**InNavigationPane = false:** Item appears in overflow dropdown menu.
### Navigation Pane Icons
Display icons on navigation buttons:
```csharp
// Load icon images
ImageList navigationIcons = new ImageList
{
ImageSize = new Size(32, 32),
ColorDepth = ColorDepth.Depth32Bit
};
navigationIcons.Images.Add("mail", Properties.Resources.MailIcon32);
navigationIcons.Images.Add("calendar", Properties.Resources.CalendarIcon32);
navigationIcons.Images.Add("contacts", Properties.Resources.ContactsIcon32);
// Assign icons to items
this.groupBarItem1.NavigationPaneIcon = new Icon("mail.ico");
this.groupBarItem2.NavigationPaneIcon = new Icon("calendar.ico");
this.groupBarItem3.NavigationPaneIcon = new Icon("contacts.ico");
// Enable large image mode for navigation pane
this.groupBarItem1.LargeImageMode = true;
this.groupBarItem2.LargeImageMode = true;
this.groupBarItem3.LargeImageMode = true;
```
**Result:** Navigation buttons display with 32x32 icons for clear visual identification.
### Navigation Pane Images
Alternatively, use images instead of icons:
```csharp
// Assign images to navigation pane
this.groupBarItem1.NavigationPaneImage = Properties.Resources.MailImage;
this.groupBarItem2.NavigationPaneImage = Properties.Resources.CalendarImage;
this.groupBarItem3.NavigationPaneImage = Properties.Resources.ContactsImage;
```
### Complete Navigation Pane Setup
```csharp
private void ConfigureNavigationPane()
{
// Create ImageList for navigation icons
ImageList navIcons = new ImageList
{
ImageSize = new Size(32, 32),
ColorDepth = ColorDepth.Depth32Bit
};
// Add icons
navIcons.Images.Add(LoadIcon("mail_32.png"));
navIcons.Images.Add(LoadIcon("calendar_32.png"));
navIcons.Images.Add(LoadIcon("contacts_32.png"));
navIcons.Images.Add(LoadIcon("tasks_32.png"));
// Configure Mail item
this.mailItem.InNavigationPane = true;
this.mailItem.NavigationPaneIcon = navIcons.Images[0];
this.mailItem.LargeImageMode = true;
// Configure Calendar item
this.calendarItem.InNavigationPane = true;
this.calendarItem.NavigationPaneIcon = navIcons.Images[1];
this.calendarItem.LargeImageMode = true;
// Configure Contacts item
this.contactsItem.InNavigationPane = true;
this.contactsItem.NavigationPaneIcon = navIcons.Images[2];
this.contactsItem.LargeImageMode = true;
// Configure Tasks item (in overflow)
this.tasksItem.InNavigationPane = false; // Appears in dropdown
this.tasksItem.NavigationPaneIcon = navIcons.Images[3];
this.tasksItem.LargeImageMode = true;
}
private Icon LoadIcon(string fileName)
{
string iconPath = Path.Combine(Application.StartupPath, "Icons", fileName);
return new Icon(iconPath);
}
```
## Navigation Pane at Bottom
The navigation pane appears at the bottom of the GroupBar in stacked mode.
### Navigation Pane Height
Control the height of the navigation pane:
```csharp
// Set navigation pane height
this.groupBar1.NavigationPaneHeight = 45;
```
**Recommended heights:**
- **35-40**: Compact mode (small icons)
- **45-50**: Standard mode (medium icons)
- **55-65**: Large mode (large icons, touch-friendly)
```csharp
// Different sizes for different scenarios
private void SetNavigationPaneSize(string size)
{
switch (size.ToLower())
{
case "compact":
this.groupBar1.NavigationPaneHeight = 38;
this.groupBar1.NavigationPaneButtonWidth = 38;
break;
case "standard":
this.groupBar1.NavigationPaneHeight = 48;
this.groupBar1.NavigationPaneButtonWidth = 48;
break;
case "large":
this.groupBar1.NavigationPaneHeight = 60;
this.groupBar1.NavigationPaneButtonWidth = 60;
break;
}
}
```
### Navigation Pane Button Width
Control individual button widths:
```csharp
// Set button width
this.groupBar1.NavigationPaneButtonWidth = 50;
```
**When to adjust button width:**
- More items in navigation pane
- Larger icons require more space
- Touch interfaces need bigger targets
- Accommodate longer text labels
### Navigation Pane Tooltips
Set custom tooltips for navigation elements:
```csharp
// Configure tooltips
this.groupBar1.NavigationPaneTooltip = "Show Navigation Options";
this.groupBar1.MinimizeButtonToolTip = "Minimize Navigation Pane";
this.groupBar1.ExpandButtonToolTip = "Expand Navigation Pane";
```
### Complete Navigation Pane Configuration
```csharp
private void SetupNavigationPane()
{
// Enable stacked mode
this.groupBar1.StackedMode = true;
// Configure navigation pane size
this.groupBar1.NavigationPaneHeight = 48;
this.groupBar1.NavigationPaneButtonWidth = 50;
// Show chevron (dropdown for overflow items)
this.groupBar1.ShowChevron = true;
// Configure tooltips
this.groupBar1.NavigationPaneTooltip = "Show more navigation options";
this.groupBar1.MinimizeButtonToolTip = "Minimize the navigation pane";
this.groupBar1.ExpandButtonToolTip = "Expand the navigation pane";
// Set which items appear in navigation pane
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
// First 4 items in pane, rest in overflow
int index = this.groupBar1.GroupBarItems.IndexOf(item);
item.InNavigationPane = (index < 4);
}
}
```
## HeaderHeight Property
The **HeaderHeight** property controls the height of the GroupBar header in stacked mode.
### Setting Header Height
```csharp
// Standard header height
this.groupBar1.HeaderHeight = 30;
// Hide header completely
this.groupBar1.HeaderHeight = 0;
// Tall header for prominence
this.groupBar1.HeaderHeight = 50;
```
**Header Height Guidelines:**
| Height | Use Case |
|--------|----------|
| 0 | Hide header completely |
| 20-25 | Minimal header |
| 28-32 | Standard header |
| 40-50 | Prominent header |
| 60+ | Extra-large header |
### Hiding the Header
```csharp
// Completely hide the header in stacked mode
this.groupBar1.StackedMode = true;
this.groupBar1.HeaderHeight = 0;
```
**When to hide the header:**
- Maximum content space needed
- Header content is redundant
- Minimalist design requirements
- Mobile/tablet layouts
### Dynamic Header Height
Adjust header height based on content or state:
```csharp
private void UpdateHeaderHeight(bool showDetailedHeader)
{
if (showDetailedHeader)
{
this.groupBar1.HeaderHeight = 50;
// Show additional header content
}
else
{
this.groupBar1.HeaderHeight = 30;
// Show compact header
}
}
```
### Header with Custom Content
```csharp
private void SetupHeaderWithImage()
{
// Set header height to accommodate image
this.groupBar1.HeaderHeight = 40;
// Show selected item's image in header
this.groupBar1.ShowItemImageInHeader = true;
// Configure items with images
this.groupBarItem1.Image = Properties.Resources.MailIcon;
this.groupBarItem2.Image = Properties.Resources.CalendarIcon;
}
```
**Result:** Selected item's icon displays in the header, providing visual context.
## Collapsed and Expanded State
In stacked mode, the GroupBar can be collapsed to save space.
### AllowCollapse Property
Enable collapsing functionality:
```csharp
// Allow users to collapse the navigation pane
this.groupBar1.AllowCollapse = true;
```
### Collapsed Property
Get or set the collapsed state:
```csharp
// Check if collapsed
bool isCollapsed = this.groupBar1.Collapsed;
// Programmatically collapse
this.groupBar1.Collapsed = true;
// Programmatically expand
this.groupBar1.Collapsed = false;
```
### Collapsed Width
Control how wide the collapsed pane is:
```csharp
// Set width when collapsed
this.groupBar1.CollapsedWidth = 40;
```
**Typical collapsed widths:**
- **30-35**: Icon only, very compact
- **40-45**: Icon + minimal padding (recommended)
- **50-60**: Icon + some text
- **60+**: Full vertical text
### Collapsed Text
Set text displayed when collapsed:
```csharp
// Set text for collapsed state
this.groupBar1.CollapsedText = "Navigation Pane";
```
**Result:** Text appears vertically along the collapsed pane edge.
### Complete Collapse Configuration
```csharp
private void ConfigureCollapseFeature()
{
// Enable collapsing
this.groupBar1.AllowCollapse = true;
// Set collapsed appearance
this.groupBar1.CollapsedWidth = 42;
this.groupBar1.CollapsedText = "Navigation";
// Set custom collapse/expand button images
this.groupBar1.CollapseImage = Properties.Resources.CollapseIcon;
this.groupBar1.ExpandImage = Properties.Resources.ExpandIcon;
// Handle collapse state changes
this.groupBar1.CollapsedChanged += (s, e) =>
{
bool collapsed = this.groupBar1.Collapsed;
Console.WriteLine($"Navigation pane {(collapsed ? "collapsed" : "expanded")}");
// Adjust main content area if needed
AdjustContentLayout(collapsed);
};
}
private void AdjustContentLayout(bool navPaneCollapsed)
{
// Maximize content area when nav pane is collapsed
if (navPaneCollapsed)
{
// Content gets more space
Console.WriteLine("Content area expanded");
}
else
{
// Standard layout
Console.WriteLine("Standard content layout");
}
}
```
### Toggle Button for Collapse
```csharp
// Add button to toggle collapsed state
private void btnToggleCollapse_Click(object sender, EventArgs e)
{
this.groupBar1.Collapsed = !this.groupBar1.Collapsed;
// Update button text
btnToggleCollapse.Text = this.groupBar1.Collapsed
? "Expand Navigation"
: "Collapse Navigation";
}
```
## Navigation Between Stacked Items
Users navigate between items using the bottom navigation pane buttons.
### Programmatic Navigation
```csharp
// Navigate to specific item by index
this.groupBar1.SelectedItem = 0; // Mail
this.groupBar1.SelectedItem = 1; // Calendar
this.groupBar1.SelectedItem = 2; // Contacts
// Navigate by finding item
private void NavigateToItem(string itemText)
{
for (int i = 0; i < this.groupBar1.GroupBarItems.Count; i++)
{
if (this.groupBar1.GroupBarItems[i].Text == itemText)
{
this.groupBar1.SelectedItem = i;
break;
}
}
}
// Usage
NavigateToItem("Calendar");
```
### Navigation Shortcuts
Implement keyboard shortcuts for quick navigation:
```csharp
private void Form1_KeyDown(object sender, KeyEventArgs e)
{
// Alt + number for quick navigation
if (e.Alt)
{
switch (e.KeyCode)
{
case Keys.D1:
if (this.groupBar1.GroupBarItems.Count > 0)
this.groupBar1.SelectedItem = 0; // Mail
break;
case Keys.D2:
if (this.groupBar1.GroupBarItems.Count > 1)
this.groupBar1.SelectedItem = 1; // Calendar
break;
case Keys.D3:
if (this.groupBar1.GroupBarItems.Count > 2)
this.groupBar1.SelectedItem = 2; // Contacts
break;
case Keys.D4:
if (this.groupBar1.GroupBarItems.Count > 3)
this.groupBar1.SelectedItem = 3; // Tasks
break;
}
e.Handled = true;
}
}
```
### Navigation Pane Dropdown
Handle the dropdown menu for overflow items:
```csharp
// Handle navigation pane dropdown click
this.groupBar1.NavigationPaneDropDownClick += GroupBar1_NavigationPaneDropDownClick;
private void GroupBar1_NavigationPaneDropDownClick(object sender,
Syncfusion.Windows.Forms.Tools.NavigationPaneDropDownClickEventArgs e)
{
Console.WriteLine("Navigation pane dropdown clicked");
// Access context menu provider
var menuProvider = e.ContextMenuProvider;
// You can customize the dropdown menu here
}
```
## Serialization Support for Stacked Layout
Save and restore the navigation pane configuration.
### Saving Layout State
```csharp
using Syncfusion.Runtime.Serialization;
private void SaveNavigationLayout()
{
// Create storage for layout information
ArrayList layoutInfo = new ArrayList();
// Store which items are in navigation pane
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
if (item.InNavigationPane)
{
int index = this.groupBar1.GroupBarItems.IndexOf(item);
layoutInfo.Add(index);
}
}
// Store selected item index
layoutInfo.Add(this.groupBar1.SelectedItem);
// Store collapsed state
layoutInfo.Add(this.groupBar1.Collapsed);
// Persist to XML file
string configPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
"MyApp",
"NavigationLayout.xml"
);
Directory.CreateDirectory(Path.GetDirectoryName(configPath));
AppStateSerializer serializer = new AppStateSerializer(
SerializeMode.XMLFile,
configPath
);
serializer.SerializeObject("NavigationLayout", layoutInfo);
serializer.PersistNow();
Console.WriteLine("Navigation layout saved");
}
```
### Loading Layout State
```csharp
private void LoadNavigationLayout()
{
try
{
string configPath = Path.Combine(
Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData),
"MyApp",
"NavigationLayout.xml"
);
if (!File.Exists(configPath))
{
Console.WriteLine("No saved layout found");
return;
}
// Deserialize layout information
AppStateSerializer serializer = new AppStateSerializer(
SerializeMode.XMLFile,
configPath
);
ArrayList layoutInfo = serializer.DeserializeObject("NavigationLayout") as ArrayList;
if (layoutInfo == null || layoutInfo.Count == 0)
return;
// Reset all items
foreach (GroupBarItem item in this.groupBar1.GroupBarItems)
{
item.InNavigationPane = false;
}
// Restore navigation pane items
for (int i = 0; i < layoutInfo.Count - 2; i++) // Last 2 are selectedItem and collapsed state
{
int itemIndex = (int)layoutInfo[i];
if (itemIndex >= 0 && itemIndex < this.groupBar1.GroupBarItems.Count)
{
this.groupBar1.GroupBarItems[itemIndex].InNavigationPane = true;
}
}
// Restore selected item
int selectedIndex = (int)layoutInfo[layoutInfo.Count - 2];
if (selectedIndex >= 0 && selectedIndex < this.groupBar1.GroupBarItems.Count)
{
this.groupBar1.SelectedItem = selectedIndex;
}
// Restore collapsed state
bool collapsed = (bool)layoutInfo[layoutInfo.Count - 1];
this.groupBar1.Collapsed = collapsed;
Console.WriteLine("Navigation layout loaded");
}
catch (Exception ex)
{
Console.WriteLine($"Error loading layout: {ex.Message}");
}
}
```
### Auto-Save on Exit
```csharp
private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
// Save layout when application closes
SaveNavigationLayout();
}
private void Form1_Load(object sender, EventArgs e)
{
// Load layout when application starts
LoadNavigationLayout();
}
```
## Complete Outlook Clone Example
A full-featured Outlook-style application with stacked mode:
```csharp
using System;
using System.Drawing;
using System.IO;
using System.Windows.Forms;
using System.Collections;
using Syncfusion.Windows.Forms.Tools;
using Syncfusion.Runtime.Serialization;
public class OutlookStackedForm : Form
{
private GroupBar navigationPane;
private Panel contentArea;
private Label titleLabel;
private RichTextBox contentDisplay;
private ToolStrip toolbar;
public OutlookStackedForm()
{
this.Text = "Outlook-Style Application";
this.Size = new Size(1200, 800);
this.StartPosition = FormStartPosition.CenterScreen;
CreateToolbar();
CreateNavigationPane();
CreateContentArea();
this.Load += OutlookStackedForm_Load;
this.FormClosing += OutlookStackedForm_FormClosing;
}
private void CreateToolbar()
{
this.toolbar = new ToolStrip
{
GripStyle = ToolStripGripStyle.Hidden
};
// Add toolbar buttons
ToolStripButton btnToggleNav = new ToolStripButton
{
Text = "Toggle Navigation",
DisplayStyle = ToolStripItemDisplayStyle.Text
};
btnToggleNav.Click += (s, e) =>
{
this.navigationPane.Collapsed = !this.navigationPane.Collapsed;
};
ToolStripButton btnSaveLayout = new ToolStripButton
{
Text = "Save Layout",
DisplayStyle = ToolStripItemDisplayStyle.Text
};
btnSaveLayout.Click += (s, e) => SaveLayout();
this.toolbar.Items.Add(btnToggleNav);
this.toolbar.Items.Add(new ToolStripSeparator());
this.toolbar.Items.Add(btnSaveLayout);
this.Controls.Add(this.toolbar);
}
private void CreateNavigationPane()
{
this.navigationPane = new GroupBar
{
Dock = DockStyle.Left,
Width = 260,
BorderStyle = BorderStyle.Fixed3D,
Font = new Font("Segoe UI", 9F),
BackColor = Color.FromArgb(245, 246, 247),
// Enable stacked mode
StackedMode = true,
// Configure collapse feature
AllowCollapse = true,
CollapsedWidth = 42,
CollapsedText = "Navigation",
// Configure navigation pane
NavigationPaneHeight = 50,
NavigationPaneButtonWidth = 52,
ShowChevron = true,
// Configure header
HeaderHeight = 35,
ShowItemImageInHeader = true
};
// Create navigation sections
CreateMailSection();
CreateCalendarSection();
CreateContactsSection();
CreateTasksSection();
CreateNotesSection();
// Set initial selection
this.navigationPane.SelectedItem = 0;
// Handle item selection
this.navigationPane.GroupBarItemSelected += NavigationPane_GroupBarItemSelected;
this.Controls.Add(this.navigationPane);
}
private void CreateMailSection()
{
GroupBarItem item = new GroupBarItem
{
Text = "Mail",
InNavigationPane = true,
LargeImageMode = true,
NavigationPaneImage = CreateColoredIcon(Color.FromArgb(0, 120, 215), "M")
};
GroupView folders = new GroupView { Name = "MailFolders", BackColor = Color.White };
folders.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("📥 Inbox (24)", -1, true, "inbox", "Inbox"),
new GroupViewItem("📝 Drafts (3)", -1, true, "drafts", "Drafts"),
new GroupViewItem("📤 Sent Items", -1, true, "sent", "Sent"),
new GroupViewItem("🗑️ Deleted Items", -1, true, "deleted", "Deleted"),
new GroupViewItem("⚠️ Junk Email", -1, true, "junk", "Junk"),
new GroupViewItem("📂 Archive", -1, true, "archive", "Archive")
});
folders.GroupViewItemSelected += Folders_ItemSelected;
item.Client = folders;
this.navigationPane.Controls.Add(folders);
this.navigationPane.GroupBarItems.Add(item);
}
private void CreateCalendarSection()
{
GroupBarItem item = new GroupBarItem
{
Text = "Calendar",
InNavigationPane = true,
LargeImageMode = true,
NavigationPaneImage = CreateColoredIcon(Color.FromArgb(208, 69, 37), "C")
};
GroupView views = new GroupView { Name = "CalendarViews", BackColor = Color.White };
views.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("📅 My Calendar", -1, true, "mycal", "MyCalendar"),
new GroupViewItem("👥 Team Calendar", -1, true, "teamcal", "TeamCalendar"),
new GroupViewItem("🎂 Birthdays", -1, true, "birthdays", "Birthdays"),
new GroupViewItem("🏖️ Holidays", -1, true, "holidays", "Holidays")
});
views.GroupViewItemSelected += Folders_ItemSelected;
item.Client = views;
this.navigationPane.Controls.Add(views);
this.navigationPane.GroupBarItems.Add(item);
}
private void CreateContactsSection()
{
GroupBarItem item = new GroupBarItem
{
Text = "Contacts",
InNavigationPane = true,
LargeImageMode = true,
NavigationPaneImage = CreateColoredIcon(Color.FromArgb(122, 159, 60), "P")
};
GroupView categories = new GroupView { Name = "ContactsCategories", BackColor = Color.White };
categories.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("👤 All Contacts (186)", -1, true, "allcontacts", "AllContacts"),
new GroupViewItem("💼 Colleagues (52)", -1, true, "colleagues", "Colleagues"),
new GroupViewItem("👨👩👧👦 Family (18)", -1, true, "family", "Family"),
new GroupViewItem("👥 Friends (34)", -1, true, "friends", "Friends")
});
categories.GroupViewItemSelected += Folders_ItemSelected;
item.Client = categories;
this.navigationPane.Controls.Add(categories);
this.navigationPane.GroupBarItems.Add(item);
}
private void CreateTasksSection()
{
GroupBarItem item = new GroupBarItem
{
Text = "Tasks",
InNavigationPane = true,
LargeImageMode = true,
NavigationPaneImage = CreateColoredIcon(Color.FromArgb(232, 17, 35), "T")
};
GroupView lists = new GroupView { Name = "TasksLists", BackColor = Color.White };
lists.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("✅ To Do (12)", -1, true, "todo", "Todo"),
new GroupViewItem("🔄 In Progress (5)", -1, true, "inprogress", "InProgress"),
new GroupViewItem("✔️ Completed", -1, true, "completed", "Completed"),
new GroupViewItem("⏸️ Waiting (2)", -1, true, "waiting", "Waiting")
});
lists.GroupViewItemSelected += Folders_ItemSelected;
item.Client = lists;
this.navigationPane.Controls.Add(lists);
this.navigationPane.GroupBarItems.Add(item);
}
private void CreateNotesSection()
{
GroupBarItem item = new GroupBarItem
{
Text = "Notes",
InNavigationPane = false, // In overflow menu
LargeImageMode = true,
NavigationPaneImage = CreateColoredIcon(Color.FromArgb(255, 185, 0), "N")
};
GroupView notebooks = new GroupView { Name = "NotesNotebooks", BackColor = Color.White };
notebooks.GroupViewItems.AddRange(new GroupViewItem[]
{
new GroupViewItem("📔 Personal Notes", -1, true, "personal", "Personal"),
new GroupViewItem("💼 Work Notes", -1, true, "work", "Work"),
new GroupViewItem("💡 Ideas", -1, true, "ideas", "Ideas")
});
notebooks.GroupViewItemSelected += Folders_ItemSelected;
item.Client = notebooks;
this.navigationPane.Controls.Add(notebooks);
this.navigationPane.GroupBarItems.Add(item);
}
private void CreateContentArea()
{
this.contentArea = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White
};
this.titleLabel = new Label
{
Dock = DockStyle.Top,
Height = 60,
Font = new Font("Segoe UI", 18F, FontStyle.Bold),
Text = "Inbox",
Padding = new Padding(15),
BackColor = Color.FromArgb(230, 235, 240),
ForeColor = Color.FromArgb(50, 50, 50)
};
this.contentDisplay = new RichTextBox
{
Dock = DockStyle.Fill,
Font = new Font("Segoe UI", 10F),
BorderStyle = BorderStyle.None,
Padding = new Padding(15),
ReadOnly = true,
Text = "Select a folder to view its contents."
};
this.contentArea.Controls.Add(this.contentDisplay);
this.contentArea.Controls.Add(this.titleLabel);
this.Controls.Add(this.contentArea);
}
private Image CreateColoredIcon(Color color, string text)
{
Bitmap bmp = new Bitmap(32, 32);
using (Graphics g = Graphics.FromImage(bmp))
{
g.SmoothingMode = System.Drawing.Drawing2D.SmoothingMode.AntiAlias;
g.Clear(Color.Transparent);
// Draw colored circle
using (SolidBrush brush = new SolidBrush(color))
{
g.FillEllipse(brush, 0, 0, 31, 31);
}
// Draw text
using (Font font = new Font("Segoe UI", 14F, FontStyle.Bold))
{
SizeF textSize = g.MeasureString(text, font);
float x = (32 - textSize.Width) / 2;
float y = (32 - textSize.Height) / 2;
g.DrawString(text, font, Brushes.White, x, y);
}
}
return bmp;
}
private void NavigationPane_GroupBarItemSelected(object sender, EventArgs e)
{
int selectedIndex = this.navigationPane.SelectedItem;
if (selectedIndex >= 0 && selectedIndex < this.navigationPane.GroupBarItems.Count)
{
GroupBarItem item = this.navigationPane.GroupBarItems[selectedIndex];
this.titleLabel.Text = item.Text;
this.contentDisplay.Text = $"Viewing: {item.Text}\n\nSelect a folder to see its contents.";
}
}
private void Folders_ItemSelected(object sender, EventArgs e)
{
GroupView view = sender as GroupView;
if (view == null) return;
int selectedIndex = view.SelectedItem;
if (selectedIndex >= 0 && selectedIndex < view.GroupViewItems.Count)
{
GroupViewItem item = view.GroupViewItems[selectedIndex];
this.titleLabel.Text = item.Text;
this.contentDisplay.Text = $"Contents of: {item.Text}\n\n";
this.contentDisplay.Text += $"Folder Key: {item.Key}\n";
this.contentDisplay.Text += $"Tag Data: {item.Tag}\n\n";
this.contentDisplay.Text += "Folder contents would be displayed here.";
}
}
private void SaveLayout()
{
try
{
ArrayList layoutInfo = new ArrayList();
// Save navigation pane items
foreach (GroupBarItem item in this.navigationPane.GroupBarItems)
{
if (item.InNavigationPane)
{
layoutInfo.Add(this.navigationPane.GroupBarItems.IndexOf(item));
}
}
// Save selected item and collapsed state
layoutInfo.Add(this.navigationPane.SelectedItem);
layoutInfo.Add(this.navigationPane.Collapsed);
// Persist
string appData = Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);
string configPath = Path.Combine(appData, "OutlookClone", "layout.xml");
Directory.CreateDirectory(Path.GetDirectoryName(configPath));
AppStateSerializer serializer = new AppStateSerializer(SerializeMode.XMLFile, configPath);
serializer.SerializeObject("Layout", layoutInfo);
serializer.PersistNow();
MessageBox.Show("Layout saved successfully!", "Save Layout",
MessageBoxButtons.OK, MessageBoxIcon.Information);
}
catch (Exception ex)
{
MessageBox.Show($"Error saving layout: {ex.Message}", "Error",
MessageBoxButtons.OK, MessageBoxIcon.Error);
}
}
private void LoadLayout()
{
try
{
string appData = Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);
string configPath = Path.Combine(appData, "OutlookClone", "layout.xml");
if (!File.Exists(configPath))
return;
AppStateSerializer serializer = new AppStateSerializer(SerializeMode.XMLFile, configPath);
ArrayList layoutInfo = serializer.DeserializeObject("Layout") as ArrayList;
if (layoutInfo == null) return;
// Reset navigation pane
foreach (GroupBarItem item in this.navigationPane.GroupBarItems)
{
item.InNavigationPane = false;
}
// Restore navigation pane items
for (int i = 0; i < layoutInfo.Count - 2; i++)
{
int itemIndex = (int)layoutInfo[i];
if (itemIndex >= 0 && itemIndex < this.navigationPane.GroupBarItems.Count)
{
this.navigationPane.GroupBarItems[itemIndex].InNavigationPane = true;
}
}
// Restore selected item
this.navigationPane.SelectedItem = (int)layoutInfo[layoutInfo.Count - 2];
// Restore collapsed state
this.navigationPane.Collapsed = (bool)layoutInfo[layoutInfo.Count - 1];
}
catch (Exception ex)
{
Console.WriteLine($"Error loading layout: {ex.Message}");
}
}
private void OutlookStackedForm_Load(object sender, EventArgs e)
{
LoadLayout();
}
private void OutlookStackedForm_FormClosing(object sender, FormClosingEventArgs e)
{
SaveLayout();
}
[STAThread]
static void Main()
{
Application.EnableVisualStyles();
Application.SetCompatibleTextRenderingDefault(false);
Application.Run(new OutlookStackedForm());
}
}
```
**Result:** A complete Outlook-style application with:
- Stacked navigation pane with Mail, Calendar, Contacts, Tasks, and Notes
- Collapsible navigation pane with custom width
- Navigation icons with colored backgrounds
- Bottom navigation buttons for quick access
- Overflow menu for additional items
- Layout serialization (saves/restores configuration)
- Toolbar for toggling navigation and saving layout
## Key Takeaways
1. **StackedMode** transforms GroupBar into Outlook-style navigation
2. **InNavigationPane** controls which items appear as bottom buttons
3. **NavigationPaneIcon** and **NavigationPaneImage** provide visual identity
4. **HeaderHeight** controls the top header size (0 to hide)
5. **AllowCollapse** enables collapsible navigation pane
6. **Collapsed/CollapsedWidth/CollapsedText** configure collapsed state
7. **Serialization** preserves user's navigation pane customization
8. **Perfect for** professional business applications mimicking Outlook
references/visual-styles-and-themes.md
# Visual Styles and Themes
This guide covers the comprehensive theming and visual styling options for the GroupBar control. Syncfusion provides professional Office-style themes that make your applications look polished and modern.
## Table of Contents
- [VisualStyle Property Overview](#visualstyle-property-overview)
- [Default Theme](#default-theme)
- [Office2007 Theme](#office2007-theme)
- [Office2007Outlook Theme](#office2007outlook-theme)
- [Office2010 Theme](#office2010-theme)
- [Metro Theme](#metro-theme)
- [Office2016 Themes](#office2016-themes)
- [Managed Colors for Custom Branding](#managed-colors-for-custom-branding)
- [Theme Properties](#theme-properties)
- [Theme Comparison Table](#theme-comparison-table)
- [Setting Themes at Design Time vs Runtime](#setting-themes-at-design-time-vs-runtime)
- [Complete Theme Switching Examples](#complete-theme-switching-examples)
## VisualStyle Property Overview
The **VisualStyle** property controls the overall appearance of the GroupBar control. It provides professionally designed themes that match Microsoft Office applications.
```csharp
// Set visual style
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016Colorful;
```
**Available Visual Styles:**
- **Default** - Standard Windows Forms appearance
- **Office2007** - Office 2007 style with color schemes
- **Office2007Outlook** - Specialized Outlook 2007 style
- **Office2010** - Office 2010 style with color schemes
- **Metro** - Modern flat design
- **Office2016Colorful** - Office 2016 colorful theme
- **Office2016White** - Office 2016 white theme
- **Office2016DarkGray** - Office 2016 dark gray theme
- **Office2016Black** - Office 2016 black theme
**When to choose different styles:**
- **Default** - Simple applications, Windows Forms consistency
- **Office2007/2010** - Professional business applications
- **Metro** - Modern, touch-friendly interfaces
- **Office2016** - Current Office look, modern applications
## Default Theme
The Default theme provides standard Windows Forms appearance without special styling.
### Setting Default Theme
```csharp
// Apply default theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Default;
```
### Complete Default Theme Example
```csharp
private void ApplyDefaultTheme()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Default;
this.groupBar1.BorderStyle = BorderStyle.Fixed3D;
this.groupBar1.BackColor = SystemColors.Control;
Console.WriteLine("Applied: Default theme");
}
```
**When to use Default theme:**
- Internal tools and utilities
- Simple data-entry applications
- Want standard Windows appearance
- Minimal visual styling needed
**Result:** GroupBar displays with standard Windows Forms gray appearance, 3D borders, and system colors.
## Office2007 Theme
The Office2007 theme provides the polished look of Microsoft Office 2007 with multiple color schemes.
### Basic Office2007 Theme
```csharp
// Apply Office 2007 theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007;
```
### Office2007 Color Schemes
Office2007 supports four color schemes: Blue, Black, Silver, and Managed.
#### Blue Color Scheme
```csharp
// Office 2007 Blue theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007;
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Blue;
```
**When to use Blue:**
- Default Office 2007 look
- Professional business applications
- Most universally accepted color scheme
**Result:** GroupBar displays with blue gradients and professional Office 2007 styling.
#### Black Color Scheme
```csharp
// Office 2007 Black theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007;
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Black;
```
**When to use Black:**
- Dramatic, bold appearance
- Media or creative applications
- High-contrast preference
- Modern, sophisticated look
**Result:** GroupBar displays with black backgrounds and silver/gray accents.
#### Silver Color Scheme
```csharp
// Office 2007 Silver theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007;
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Silver;
```
**When to use Silver:**
- Neutral, professional appearance
- Alternative to blue
- Subtle, understated look
**Result:** GroupBar displays with silver/gray gradients and neutral tones.
#### Managed Color Scheme
The Managed scheme allows custom brand colors.
```csharp
// Office 2007 with custom managed colors
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007;
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Managed;
// Apply custom color
Syncfusion.Windows.Forms.Office2007Colors.ApplyManagedColors(this, Color.Red);
```
**When to use Managed:**
- Corporate branding requirements
- Custom color schemes
- Unique application identity
**Result:** GroupBar displays with Office 2007 styling in your custom brand color.
### Complete Office2007 Theme Example
```csharp
private void SetupOffice2007Themes()
{
// Create theme selector
ComboBox themeSelector = new ComboBox
{
DropDownStyle = ComboBoxStyle.DropDownList,
Dock = DockStyle.Top
};
themeSelector.Items.AddRange(new object[]
{
"Blue",
"Black",
"Silver",
"Managed (Red)"
});
themeSelector.SelectedIndexChanged += (s, e) =>
{
ApplyOffice2007Theme(themeSelector.SelectedItem.ToString());
};
this.Controls.Add(themeSelector);
themeSelector.SelectedIndex = 0;
}
private void ApplyOffice2007Theme(string theme)
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007;
switch (theme)
{
case "Blue":
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Blue;
break;
case "Black":
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Black;
break;
case "Silver":
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Silver;
break;
case "Managed (Red)":
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Managed;
Syncfusion.Windows.Forms.Office2007Colors.ApplyManagedColors(this, Color.FromArgb(192, 0, 0));
break;
}
Console.WriteLine($"Applied: Office 2007 {theme}");
}
```
## Office2007Outlook Theme
A specialized theme matching Microsoft Outlook 2007's appearance.
```csharp
// Apply Office 2007 Outlook theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007Outlook;
```
**When to use Office2007Outlook:**
- Building Outlook-style applications
- Email or calendar applications
- Want authentic Outlook appearance
- Stacked mode GroupBar
**Result:** GroupBar displays with authentic Outlook 2007 navigation pane styling, optimized for stacked mode.
### Complete Outlook Theme Example
```csharp
private void CreateOutlookInterface()
{
// Configure for Outlook appearance
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007Outlook;
this.groupBar1.StackedMode = true;
this.groupBar1.AllowCollapse = true;
this.groupBar1.ShowItemImageInHeader = true;
// Configure navigation pane
this.groupBar1.NavigationPaneHeight = 50;
this.groupBar1.ShowChevron = true;
Console.WriteLine("Applied: Office 2007 Outlook theme");
}
```
## Office2010 Theme
The Office2010 theme provides the streamlined look of Microsoft Office 2010.
### Basic Office2010 Theme
```csharp
// Apply Office 2010 theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
```
### Office2010 Color Schemes
Like Office2007, Office2010 supports Blue, Black, Silver, and Managed schemes.
#### Blue Color Scheme
```csharp
// Office 2010 Blue theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Blue;
```
**Result:** Modern Office 2010 blue styling with cleaner lines than Office 2007.
#### Black Color Scheme
```csharp
// Office 2010 Black theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Black;
```
**Result:** Sleek black appearance with Office 2010 design language.
#### Silver Color Scheme
```csharp
// Office 2010 Silver theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Silver;
```
**Result:** Professional silver/gray Office 2010 styling.
#### Managed Color Scheme
```csharp
// Office 2010 with custom managed colors
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Managed;
// Apply custom color (e.g., corporate orange)
Syncfusion.Windows.Forms.Office2010Colors.ApplyManagedColors(this, Color.FromArgb(255, 140, 0));
```
**Result:** Office 2010 styling with your custom brand color.
### Complete Office2010 Theme Example
```csharp
private void SetupOffice2010Themes()
{
// Create theme picker UI
GroupBox themeGroup = new GroupBox
{
Text = "Office 2010 Themes",
Dock = DockStyle.Top,
Height = 100
};
RadioButton rbBlue = new RadioButton { Text = "Blue", Location = new Point(10, 20), Checked = true };
RadioButton rbBlack = new RadioButton { Text = "Black", Location = new Point(10, 45) };
RadioButton rbSilver = new RadioButton { Text = "Silver", Location = new Point(10, 70) };
RadioButton rbManaged = new RadioButton { Text = "Managed (Green)", Location = new Point(100, 20) };
rbBlue.CheckedChanged += (s, e) => { if (rbBlue.Checked) ApplyOffice2010Blue(); };
rbBlack.CheckedChanged += (s, e) => { if (rbBlack.Checked) ApplyOffice2010Black(); };
rbSilver.CheckedChanged += (s, e) => { if (rbSilver.Checked) ApplyOffice2010Silver(); };
rbManaged.CheckedChanged += (s, e) => { if (rbManaged.Checked) ApplyOffice2010Managed(); };
themeGroup.Controls.AddRange(new Control[] { rbBlue, rbBlack, rbSilver, rbManaged });
this.Controls.Add(themeGroup);
ApplyOffice2010Blue();
}
private void ApplyOffice2010Blue()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Blue;
}
private void ApplyOffice2010Black()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Black;
}
private void ApplyOffice2010Silver()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Silver;
}
private void ApplyOffice2010Managed()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Managed;
Syncfusion.Windows.Forms.Office2010Colors.ApplyManagedColors(this, Color.Green);
}
```
## Metro Theme
The Metro theme provides a modern, flat design aesthetic.
```csharp
// Apply Metro theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Metro;
```
**Characteristics:**
- Flat design (no gradients)
- Clean, minimalist appearance
- Bold colors
- Modern Windows 8/10 style
**When to use Metro:**
- Modern, touch-friendly applications
- Windows 8/10 style consistency
- Minimalist design preference
- Tablet or touch-screen interfaces
### Complete Metro Theme Example
```csharp
private void ApplyMetroTheme()
{
// Apply Metro visual style
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Metro;
// Configure for modern flat appearance
this.groupBar1.BorderStyle = BorderStyle.FixedSingle;
this.groupBar1.BackColor = Color.White;
this.groupBar1.ForeColor = Color.FromArgb(60, 60, 60);
// Use flat colors
this.groupBar1.HeaderBackColor = Color.FromArgb(0, 120, 215); // Windows blue
this.groupBar1.HeaderForeColor = Color.White;
Console.WriteLine("Applied: Metro theme");
}
```
**Result:** GroupBar displays with flat, modern Metro styling suitable for touch interfaces.
## Office2016 Themes
Office 2016 provides four contemporary themes matching the latest Office applications.
### Office2016Colorful Theme
```csharp
// Apply Office 2016 Colorful theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016Colorful;
```
**Characteristics:**
- Vibrant accent colors
- Clean, modern design
- Colored headers
- Professional appearance
**When to use:**
- Current Office look
- Vibrant, colorful interface
- Modern professional applications
**Result:** GroupBar displays with colorful Office 2016 styling and vibrant accents.
### Office2016White Theme
```csharp
// Apply Office 2016 White theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016White;
```
**Characteristics:**
- Clean white background
- Subtle gray accents
- Minimalist design
- High contrast
**When to use:**
- Clean, uncluttered appearance
- Document-focused applications
- Lots of white space
- Professional, subtle look
**Result:** GroupBar displays with predominantly white Office 2016 styling.
### Office2016DarkGray Theme
```csharp
// Apply Office 2016 Dark Gray theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016DarkGray;
```
**Characteristics:**
- Dark gray background
- Good contrast
- Modern, professional
- Easy on the eyes
**When to use:**
- Reduced eye strain
- Long working hours
- Professional dark theme
- Code editors, development tools
**Result:** GroupBar displays with dark gray Office 2016 styling.
### Office2016Black Theme
```csharp
// Apply Office 2016 Black theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016Black;
```
**Characteristics:**
- Pure black background
- Maximum contrast
- Modern, bold appearance
- OLED-friendly
**When to use:**
- Maximum contrast needed
- Dark mode preference
- Media applications
- High-end professional tools
**Result:** GroupBar displays with black Office 2016 styling.
### Complete Office2016 Theme Example
```csharp
private void SetupOffice2016ThemeSelector()
{
// Create theme menu
MenuStrip menuStrip = new MenuStrip();
ToolStripMenuItem themesMenu = new ToolStripMenuItem("Office 2016 Themes");
ToolStripMenuItem colorfulItem = new ToolStripMenuItem("Colorful");
ToolStripMenuItem whiteItem = new ToolStripMenuItem("White");
ToolStripMenuItem darkGrayItem = new ToolStripMenuItem("Dark Gray");
ToolStripMenuItem blackItem = new ToolStripMenuItem("Black");
colorfulItem.Click += (s, e) => ApplyOffice2016Colorful();
whiteItem.Click += (s, e) => ApplyOffice2016White();
darkGrayItem.Click += (s, e) => ApplyOffice2016DarkGray();
blackItem.Click += (s, e) => ApplyOffice2016Black();
themesMenu.DropDownItems.AddRange(new ToolStripItem[]
{
colorfulItem, whiteItem, darkGrayItem, blackItem
});
menuStrip.Items.Add(themesMenu);
this.Controls.Add(menuStrip);
// Apply default theme
ApplyOffice2016Colorful();
}
private void ApplyOffice2016Colorful()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016Colorful;
this.BackColor = Color.White;
Console.WriteLine("Applied: Office 2016 Colorful");
}
private void ApplyOffice2016White()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016White;
this.BackColor = Color.White;
Console.WriteLine("Applied: Office 2016 White");
}
private void ApplyOffice2016DarkGray()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016DarkGray;
this.BackColor = Color.FromArgb(62, 62, 66);
Console.WriteLine("Applied: Office 2016 Dark Gray");
}
private void ApplyOffice2016Black()
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016Black;
this.BackColor = Color.FromArgb(37, 37, 38);
Console.WriteLine("Applied: Office 2016 Black");
}
```
## Managed Colors for Custom Branding
Managed colors allow custom brand colors with Office 2007 and Office 2010 themes.
### Applying Managed Colors
```csharp
// Office 2007 with custom color
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2007;
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Managed;
Syncfusion.Windows.Forms.Office2007Colors.ApplyManagedColors(this, Color.Purple);
// Office 2010 with custom color
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Managed;
Syncfusion.Windows.Forms.Office2010Colors.ApplyManagedColors(this, Color.Teal);
```
### Corporate Branding Example
```csharp
private void ApplyCorporateBranding()
{
// Define corporate colors
Color corporatePrimary = Color.FromArgb(0, 114, 188); // Corporate Blue
Color corporateSecondary = Color.FromArgb(255, 140, 0); // Corporate Orange
// Apply to Office 2010 theme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Managed;
Syncfusion.Windows.Forms.Office2010Colors.ApplyManagedColors(this, corporatePrimary);
// Apply form branding
this.BackColor = Color.White;
this.Text = "Corporate Application";
Console.WriteLine($"Applied corporate branding: {corporatePrimary}");
}
```
### Multiple Managed Color Examples
```csharp
private void ShowManagedColorExamples()
{
// Create color picker
ComboBox colorPicker = new ComboBox
{
DropDownStyle = ComboBoxStyle.DropDownList,
Dock = DockStyle.Top
};
colorPicker.Items.AddRange(new object[]
{
"Red", "Blue", "Green", "Purple", "Orange", "Teal"
});
colorPicker.SelectedIndexChanged += (s, e) =>
{
Color selectedColor = GetColorByName(colorPicker.SelectedItem.ToString());
ApplyManagedColor(selectedColor);
};
this.Controls.Add(colorPicker);
colorPicker.SelectedIndex = 1; // Default to Blue
}
private Color GetColorByName(string colorName)
{
return colorName switch
{
"Red" => Color.FromArgb(192, 0, 0),
"Blue" => Color.FromArgb(0, 112, 192),
"Green" => Color.FromArgb(0, 176, 80),
"Purple" => Color.FromArgb(112, 48, 160),
"Orange" => Color.FromArgb(255, 140, 0),
"Teal" => Color.FromArgb(0, 176, 176),
_ => Color.Blue
};
}
private void ApplyManagedColor(Color color)
{
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Managed;
Syncfusion.Windows.Forms.Office2010Colors.ApplyManagedColors(this, color);
Console.WriteLine($"Applied managed color: {color}");
}
```
## Theme Properties
### Office2007Theme Property
```csharp
// Get current Office 2007 theme
Syncfusion.Windows.Forms.Office2007Theme currentTheme = this.groupBar1.Office2007Theme;
// Set Office 2007 theme
this.groupBar1.Office2007Theme = Syncfusion.Windows.Forms.Office2007Theme.Blue;
```
**Available values:**
- `Blue` - Blue color scheme
- `Black` - Black color scheme
- `Silver` - Silver color scheme
- `Managed` - Custom managed colors
### Office2010Theme Property
```csharp
// Get current Office 2010 theme
Syncfusion.Windows.Forms.Office2010Theme currentTheme = this.groupBar1.Office2010Theme;
// Set Office 2010 theme
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Silver;
```
**Available values:**
- `Blue` - Blue color scheme
- `Black` - Black color scheme
- `Silver` - Silver color scheme
- `Managed` - Custom managed colors
## Theme Comparison Table
| Theme | Gradient | Flat Design | Color Schemes | Best For |
|-------|----------|-------------|---------------|----------|
| **Default** | No | Yes | N/A | Simple apps, utilities |
| **Office2007** | Yes | No | 4 (Blue, Black, Silver, Managed) | Professional 2007-era apps |
| **Office2007Outlook** | Yes | No | Fixed | Outlook clones |
| **Office2010** | Subtle | Mostly | 4 (Blue, Black, Silver, Managed) | Modern professional apps |
| **Metro** | No | Yes | N/A | Touch interfaces, modern apps |
| **Office2016Colorful** | No | Yes | Fixed | Current Office look, vibrant |
| **Office2016White** | No | Yes | Fixed | Clean, document-focused |
| **Office2016DarkGray** | No | Yes | Fixed | Dark mode, professional |
| **Office2016Black** | No | Yes | Fixed | Maximum contrast, dramatic |
## Setting Themes at Design Time vs Runtime
### Design Time
1. Select GroupBar control
2. Open Properties window
3. Find **VisualStyle** property
4. Choose from dropdown
5. If Office2007/2010, set **Office2007Theme** or **Office2010Theme**
### Runtime
```csharp
// Set at runtime
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2016Colorful;
// Set with color scheme
this.groupBar1.VisualStyle = Syncfusion.Windows.Forms.VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Syncfusion.Windows.Forms.Office2010Theme.Blue;
```
### Configuration File
Store theme preference in app.config:
```xml
<appSettings>
<add key="Theme" value="Office2016Colorful" />
</appSettings>
```
```csharp
private void LoadThemeFromConfig()
{
string themeName = ConfigurationManager.AppSettings["Theme"] ?? "Office2016Colorful";
if (Enum.TryParse<Syncfusion.Windows.Forms.VisualStyle>(themeName, out var visualStyle))
{
this.groupBar1.VisualStyle = visualStyle;
Console.WriteLine($"Loaded theme from config: {themeName}");
}
}
```
### User Preference Storage
Save user's theme choice:
```csharp
private void SaveThemePreference(string themeName)
{
Properties.Settings.Default.PreferredTheme = themeName;
Properties.Settings.Default.Save();
}
private void LoadThemePreference()
{
string themeName = Properties.Settings.Default.PreferredTheme;
if (!string.IsNullOrEmpty(themeName))
{
if (Enum.TryParse<Syncfusion.Windows.Forms.VisualStyle>(themeName, out var visualStyle))
{
this.groupBar1.VisualStyle = visualStyle;
}
}
}
```
## Complete Theme Switching Examples
### Example 1: Theme Switcher with Dropdown
```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using Syncfusion.Windows.Forms;
using Syncfusion.Windows.Forms.Tools;
public class ThemeSwitcherForm : Form
{
private GroupBar groupBar1;
private ComboBox themeSelector;
private Label previewLabel;
public ThemeSwitcherForm()
{
this.Text = "GroupBar Theme Switcher";
this.Size = new Size(800, 600);
CreateThemeSelector();
CreateGroupBar();
CreatePreviewArea();
}
private void CreateThemeSelector()
{
Panel topPanel = new Panel
{
Dock = DockStyle.Top,
Height = 60,
BackColor = Color.FromArgb(240, 240, 240),
Padding = new Padding(10)
};
Label label = new Label
{
Text = "Select Theme:",
AutoSize = true,
Location = new Point(10, 18),
Font = new Font("Segoe UI", 10F)
};
this.themeSelector = new ComboBox
{
DropDownStyle = ComboBoxStyle.DropDownList,
Location = new Point(120, 15),
Width = 200,
Font = new Font("Segoe UI", 10F)
};
this.themeSelector.Items.AddRange(new object[]
{
"Default",
"Office 2007 Blue",
"Office 2007 Black",
"Office 2007 Silver",
"Office 2007 Outlook",
"Office 2010 Blue",
"Office 2010 Black",
"Office 2010 Silver",
"Metro",
"Office 2016 Colorful",
"Office 2016 White",
"Office 2016 Dark Gray",
"Office 2016 Black"
});
this.themeSelector.SelectedIndexChanged += ThemeSelector_SelectedIndexChanged;
topPanel.Controls.AddRange(new Control[] { label, this.themeSelector });
this.Controls.Add(topPanel);
this.themeSelector.SelectedIndex = 9; // Default to Office 2016 Colorful
}
private void CreateGroupBar()
{
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 220,
BorderStyle = BorderStyle.Fixed3D
};
// Create sample items
for (int i = 1; i <= 5; i++)
{
GroupBarItem item = new GroupBarItem
{
Text = $"Section {i}"
};
Panel panel = new Panel
{
BackColor = Color.White,
Dock = DockStyle.Fill
};
Label label = new Label
{
Text = $"Content for Section {i}",
Dock = DockStyle.Top,
Padding = new Padding(10),
Font = new Font("Segoe UI", 11F)
};
panel.Controls.Add(label);
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
}
this.groupBar1.SelectedItem = 0;
this.Controls.Add(this.groupBar1);
}
private void CreatePreviewArea()
{
this.previewLabel = new Label
{
Dock = DockStyle.Fill,
Font = new Font("Segoe UI", 14F),
Text = "Theme preview area\n\nChange themes to see different styles.",
TextAlign = ContentAlignment.MiddleCenter,
BackColor = Color.White
};
this.Controls.Add(this.previewLabel);
}
private void ThemeSelector_SelectedIndexChanged(object sender, EventArgs e)
{
string selectedTheme = this.themeSelector.SelectedItem.ToString();
ApplyTheme(selectedTheme);
}
private void ApplyTheme(string themeName)
{
switch (themeName)
{
case "Default":
this.groupBar1.VisualStyle = VisualStyle.Default;
this.BackColor = SystemColors.Control;
break;
case "Office 2007 Blue":
this.groupBar1.VisualStyle = VisualStyle.Office2007;
this.groupBar1.Office2007Theme = Office2007Theme.Blue;
this.BackColor = Color.FromArgb(191, 219, 255);
break;
case "Office 2007 Black":
this.groupBar1.VisualStyle = VisualStyle.Office2007;
this.groupBar1.Office2007Theme = Office2007Theme.Black;
this.BackColor = Color.FromArgb(83, 83, 83);
break;
case "Office 2007 Silver":
this.groupBar1.VisualStyle = VisualStyle.Office2007;
this.groupBar1.Office2007Theme = Office2007Theme.Silver;
this.BackColor = Color.FromArgb(223, 223, 234);
break;
case "Office 2007 Outlook":
this.groupBar1.VisualStyle = VisualStyle.Office2007Outlook;
this.BackColor = Color.FromArgb(227, 239, 255);
break;
case "Office 2010 Blue":
this.groupBar1.VisualStyle = VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Office2010Theme.Blue;
this.BackColor = Color.FromArgb(214, 229, 255);
break;
case "Office 2010 Black":
this.groupBar1.VisualStyle = VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Office2010Theme.Black;
this.BackColor = Color.FromArgb(102, 102, 102);
break;
case "Office 2010 Silver":
this.groupBar1.VisualStyle = VisualStyle.Office2010;
this.groupBar1.Office2010Theme = Office2010Theme.Silver;
this.BackColor = Color.FromArgb(214, 214, 214);
break;
case "Metro":
this.groupBar1.VisualStyle = VisualStyle.Metro;
this.BackColor = Color.White;
break;
case "Office 2016 Colorful":
this.groupBar1.VisualStyle = VisualStyle.Office2016Colorful;
this.BackColor = Color.White;
break;
case "Office 2016 White":
this.groupBar1.VisualStyle = VisualStyle.Office2016White;
this.BackColor = Color.White;
break;
case "Office 2016 Dark Gray":
this.groupBar1.VisualStyle = VisualStyle.Office2016DarkGray;
this.BackColor = Color.FromArgb(62, 62, 66);
this.previewLabel.ForeColor = Color.White;
break;
case "Office 2016 Black":
this.groupBar1.VisualStyle = VisualStyle.Office2016Black;
this.BackColor = Color.FromArgb(37, 37, 38);
this.previewLabel.ForeColor = Color.White;
break;
}
this.previewLabel.Text = $"Current Theme:\n{themeName}\n\nExperience the visual styling.";
Console.WriteLine($"Applied theme: {themeName}");
}
}
```
**Result:** A complete theme switcher application allowing users to preview all available GroupBar themes with appropriate background colors.
### Example 2: Corporate Branding with Managed Colors
```csharp
public class CorporateBrandingForm : Form
{
private GroupBar groupBar1;
public CorporateBrandingForm()
{
this.Text = "Corporate Branded Application";
this.Size = new Size(1000, 700);
CreateBrandedInterface();
}
private void CreateBrandedInterface()
{
// Define corporate colors
Color brandPrimary = Color.FromArgb(0, 114, 188); // Corporate Blue
Color brandSecondary = Color.FromArgb(255, 140, 0); // Corporate Orange
Color brandAccent = Color.FromArgb(0, 176, 80); // Corporate Green
// Create GroupBar with corporate branding
this.groupBar1 = new GroupBar
{
Dock = DockStyle.Left,
Width = 240,
BorderStyle = BorderStyle.FixedSingle,
VisualStyle = VisualStyle.Office2010,
Office2010Theme = Office2010Theme.Managed
};
// Apply managed colors
Office2010Colors.ApplyManagedColors(this, brandPrimary);
// Create branded sections
CreateSection("Dashboard", brandPrimary);
CreateSection("Reports", brandSecondary);
CreateSection("Analytics", brandAccent);
CreateSection("Settings", brandPrimary);
this.groupBar1.SelectedItem = 0;
this.Controls.Add(this.groupBar1);
// Set form branding
this.BackColor = Color.White;
}
private void CreateSection(string name, Color accentColor)
{
GroupBarItem item = new GroupBarItem
{
Text = name
};
Panel panel = new Panel
{
Dock = DockStyle.Fill,
BackColor = Color.White,
Padding = new Padding(20)
};
Label titleLabel = new Label
{
Text = name,
Font = new Font("Segoe UI", 16F, FontStyle.Bold),
ForeColor = accentColor,
Dock = DockStyle.Top,
Height = 40
};
panel.Controls.Add(titleLabel);
item.Client = panel;
this.groupBar1.Controls.Add(panel);
this.groupBar1.GroupBarItems.Add(item);
}
}
```
**Result:** A professionally branded application using corporate colors with Office 2010 managed color scheme.
## Key Takeaways
1. **VisualStyle Property** controls overall theme (Default, Office2007, Office2010, Metro, Office2016)
2. **Office2007/2010** themes support four color schemes: Blue, Black, Silver, Managed
3. **Managed Colors** enable custom brand colors with Office themes
4. **Office2016** provides four modern themes: Colorful, White, DarkGray, Black
5. **Metro** offers flat, modern design for touch interfaces
6. **Theme selection** impacts user experience and application perception
7. **ApplyManagedColors** method applies custom colors to Office themes
8. **Design time vs Runtime** theming both supported for flexibility
SKILL.md
---
name: syncfusion-winforms-navigation-pane
description: Guide for implementing Syncfusion GroupBar (Navigation Pane) control in Windows Forms applications. Use when creating Outlook-style navigation, hierarchical sidebar navigation, collapsible group containers, or toolbox-style interfaces. Covers stacked navigation panes, Office 2007/2010/2016 themed navigation, nested GroupBar containers, and categorized control collections for structured navigation layouts.
metadata:
author: "Syncfusion Inc"
version: "34.1.29"
---
# Implementing Navigation Panes (GroupBar) in Syncfusion WinForms
This skill guides you in implementing **Syncfusion.Tools.WinForms** (Navigation Pane) control—an Outlook-style navigation container that displays hierarchical groups with collapsible sections and child item collections.
## When to Use This Skill
Use this skill when the user needs to:
- Implement **Outlook-style navigation panes** (similar to Microsoft Outlook sidebar)
- Create **hierarchical sidebar navigation** with collapsible groups
- Build **toolbox-style interfaces** (like Visual Studio .NET toolbox)
- Add **categorized control collections** with GroupBarItems
- Implement **GroupView** for displaying child items within groups
- Enable **StackedMode** for navigation pane at bottom (Outlook-style)
- Apply **Office 2007/2010/2016 themes** and Metro styles
- Create **nested GroupBar** (GroupBar within GroupBar)
- Add **in-place renaming** of navigation items
- Implement **serialization** to save/restore navigation layout
- Customize **headers, borders, colors, and animations**
- Replace **standard panels** with themed navigation containers
GroupBar is ideal for applications requiring categorized navigation, toolbox-style interfaces, or Outlook-inspired sidebar layouts.
## Component Overview
**GroupBar** (Navigation Pane) is a container control that displays multiple groups (GroupBarItems) where only one selected group's content is visible at a time. It works with **GroupView** to display child items. Key capabilities:
- **GroupBarItem**: Tab-like navigation items (groups/categories)
- **GroupView**: Client control for displaying child items within groups
- **GroupViewItem**: Individual child items within a GroupView
- **StackedMode**: Navigation pane mode (like Outlook) with collapsible stack
- **Office Themes**: Office 2007/2010/2016, Metro, Office2016Colorful/White/DarkGray/Black
- **Nested GroupBar**: Host GroupBar within another GroupBar
- **Serialization**: Save/restore layout state and item positions
- **Customizable Appearance**: Headers, borders, colors, fonts, animations
- **In-Place Renaming**: Edit GroupBarItem names at runtime
- **Localization**: Multi-language support
**Key Difference from Standard Panel/TabControl:**
GroupBar provides Outlook-style navigation with GroupView integration, StackedMode for collapsible navigation pane, Office themes, and hierarchical item display capabilities.
## Additional Resources
**Assembly:** Syncfusion.Shared.Base.dll
**Namespace:** Syncfusion.Windows.Forms.Tools
**NuGet Package:** Syncfusion.Shared.Base
**Minimum .NET Framework:** 4.5
## Documentation and Navigation Guide
### Getting Started and Basic Setup
📄 **Read:** [references/getting-started.md](references/getting-started.md)
Read this reference when users need:
- Assembly dependencies and NuGet package installation
- Namespace: Syncfusion.Windows.Forms.Tools
- Creating GroupBar via designer or code
- Adding GroupBarItems to the control
- Basic GroupBar configuration
- Understanding GroupBar structure
- Complete minimal working example
### GroupBar Items and Structure
📄 **Read:** [references/groupbar-items-and-structure.md](references/groupbar-items-and-structure.md)
Read this reference when users need:
- Creating GroupBarItem instances
- Text property for item labels
- Image property for item icons
- Client property (linking to GroupView)
- GroupBarItems collection management
- Item selection and navigation
- GroupBarItemSelected event handling
- Complete group navigation examples
### GroupView and Child Items
📄 **Read:** [references/groupview-and-child-items.md](references/groupview-and-child-items.md)
Read this reference when users need:
- GroupView overview (client control for groups)
- Creating GroupView instances
- GroupViewItem for child items
- Adding items to GroupViewItems collection
- Linking GroupView to GroupBarItem.Client
- Item selection in GroupView
- GroupViewItem click events
- Building toolbox-style interfaces
### Stacked Mode (Navigation Pane)
📄 **Read:** [references/stacked-mode.md](references/stacked-mode.md)
Read this reference when users need:
- StackedMode property (Outlook-style navigation)
- Navigation pane at bottom
- HeaderHeight property for collapsed state
- Navigation between stacked items
- Expanded/collapsed state management
- Serialization of stacked layout
- Complete Outlook clone example
### Visual Styles and Themes
📄 **Read:** [references/visual-styles-and-themes.md](references/visual-styles-and-themes.md)
Read this reference when users need:
- VisualStyle property overview
- Office2007 theme (Blue, Silver, Black, Managed)
- Office2007Outlook theme
- Office2010 theme (Blue, Silver, Black, Managed)
- Metro theme
- Office2016 themes (Colorful, White, DarkGray, Black)
- Managed colors for custom branding
- Theme comparison and selection
- Applying themes at runtime
### Appearance Customization
📄 **Read:** [references/appearance-customization.md](references/appearance-customization.md)
Read this reference when users need:
- Header customization (colors, fonts, height)
- Border settings (styles, colors)
- Text alignment and settings
- Image display configuration
- Tooltip settings
- Cursor customization
- Animation settings
- Custom colors and gradients
### Advanced Features and Configuration
📄 **Read:** [references/advanced-features.md](references/advanced-features.md)
Read this reference when users need:
- Nested GroupBar support (GroupBar in GroupBar)
- In-place renaming of GroupBarItems
- Serialization of layout state
- Localization support
- Link selection in GroupView
- Custom control hosting
- Event handling (GroupBarItemSelected, etc.)
- Complex navigation scenarios
## Quick Start Example
Here's a minimal example creating a GroupBar with items and child content:
```csharp
using Syncfusion.Windows.Forms.Tools;
using System;
using System.Drawing;
using System.Windows.Forms;
public class GroupBarExample : Form
{
private GroupBar groupBar1;
public GroupBarExample()
{
// Create GroupBar
groupBar1 = new GroupBar();
groupBar1.Dock = DockStyle.Left;
groupBar1.Width = 200;
// Create GroupBarItems
GroupBarItem mailItem = new GroupBarItem();
mailItem.Text = "Mail";
GroupBarItem calendarItem = new GroupBarItem();
calendarItem.Text = "Calendar";
GroupBarItem contactsItem = new GroupBarItem();
contactsItem.Text = "Contacts";
// Add items to GroupBar
groupBar1.GroupBarItems.AddRange(new GroupBarItem[] {
mailItem,
calendarItem,
contactsItem
});
// Add GroupBar to form
this.Controls.Add(groupBar1);
this.Text = "GroupBar Example";
this.Size = new Size(600, 400);
}
}
```
**Result:** A left-docked navigation pane with 3 groups (Mail, Calendar, Contacts) similar to Microsoft Outlook.
## Common Patterns
### Outlook-Style Navigation with GroupView
**Pattern:** Create an Outlook-inspired navigation pane with child items.
```csharp
// Create GroupBar
GroupBar groupBar = new GroupBar();
groupBar.Dock = DockStyle.Left;
groupBar.Width = 220;
groupBar.VisualStyle = VisualStyle.Office2016Colorful;
// Create GroupBarItem
GroupBarItem mailItem = new GroupBarItem();
mailItem.Text = "Mail Folders";
// Create GroupView for child items
GroupView mailView = new GroupView();
mailView.Name = "MailView";
mailView.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("Inbox", 0, true, null, "Inbox"),
new GroupViewItem("Drafts", 1, true, null, "Drafts"),
new GroupViewItem("Sent Items", 2, true, null, "Sent"),
new GroupViewItem("Deleted Items", 3, true, null, "Deleted")
});
// Link GroupView to GroupBarItem
mailItem.Client = mailView;
groupBar.Controls.Add(mailView);
groupBar.GroupBarItems.Add(mailItem);
// Handle item click
mailView.GroupViewItemSelected += (s, e) => {
string folderName = ((sender as GroupView)?.SelectedItem >= 0 ? (sender as GroupView).GroupViewItems[(sender as GroupView).SelectedItem].Text : null)`;
LoadMailFolder(folderName);
};
this.Controls.Add(groupBar);
```
**When:** User needs Outlook-style mail navigation with folder hierarchy.
### Visual Studio Toolbox Clone
**Pattern:** Create a toolbox-style interface with categorized controls.
```csharp
// Create GroupBar for toolbox
GroupBar toolbox = new GroupBar();
toolbox.Dock = DockStyle.Left;
toolbox.Width = 200;
toolbox.VisualStyle = VisualStyle.Office2010;
// Create "Windows Forms" category
GroupBarItem winFormsItem = new GroupBarItem();
winFormsItem.Text = "Windows Forms";
GroupView winFormsView = new GroupView();
winFormsView.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("Button", 0, true, null, "Button"),
new GroupViewItem("TextBox", 1, true, null, "TextBox"),
new GroupViewItem("Label", 2, true, null, "Label"),
new GroupViewItem("ComboBox", 3, true, null, "ComboBox")
});
// Create "Data" category
GroupBarItem dataItem = new GroupBarItem();
dataItem.Text = "Data";
GroupView dataView = new GroupView();
dataView.GroupViewItems.AddRange(new GroupViewItem[] {
new GroupViewItem("DataSet", 0, true, null, "DataSet"),
new GroupViewItem("DataTable", 1, true, null, "DataTable"),
new GroupViewItem("BindingSource", 2, true, null, "BindingSource")
});
// Link and add
winFormsItem.Client = winFormsView;
dataItem.Client = dataView;
toolbox.Controls.Add(winFormsView);
toolbox.Controls.Add(dataView);
toolbox.GroupBarItems.Add(winFormsItem);
toolbox.GroupBarItems.Add(dataItem);
this.Controls.Add(toolbox);
```
**When:** User needs a categorized toolbox with collapsible sections like Visual Studio.
### Stacked Navigation Pane (Outlook Mode)
**Pattern:** Enable Outlook-style stacked navigation with bottom pane.
```csharp
// Create GroupBar in stacked mode
GroupBar navPane = new GroupBar();
navPane.Dock = DockStyle.Left;
navPane.Width = 220;
navPane.StackedMode = true; // Enable Outlook-style navigation
navPane.VisualStyle = VisualStyle.Office2016White;
// Create multiple GroupBarItems
GroupBarItem mailItem = new GroupBarItem();
mailItem.Text = "Mail";
GroupBarItem calendarItem = new GroupBarItem();
calendarItem.Text = "Calendar";
GroupBarItem contactsItem = new GroupBarItem();
contactsItem.Text = "Contacts";
GroupBarItem tasksItem = new GroupBarItem();
tasksItem.Text = "Tasks";
// Add all items
navPane.GroupBarItems.AddRange(new GroupBarItem[] {
mailItem,
calendarItem,
contactsItem,
tasksItem
});
// Handle item selection
navPane.GroupBarItemSelected += (s, e) => {
string selectedSection = ((sender as GroupView)?.SelectedItem >= 0 ? (sender as GroupView).GroupViewItems[(sender as GroupView).SelectedItem].Text : null)`;
LoadSection(selectedSection);
};
this.Controls.Add(navPane);
```
**When:** User needs Outlook-style navigation with stacked items and bottom navigation pane.
## Key Properties
### Core Properties
| Property | Type | Description | When to Use |
|----------|------|-------------|-------------|
| `GroupBarItems` | Collection | Collection of GroupBarItem instances | Add navigation groups |
| `SelectedItem` | GroupBarItem | Currently selected item | Get/set active group |
| `StackedMode` | bool | Enable Outlook-style stacked navigation | Outlook-like layout |
| `VisualStyle` | VisualStyle | Visual theme | Apply Office themes |
| `HeaderHeight` | int | Height of GroupBar header | Customize header size |
### GroupBarItem Properties
| Property | Type | Description | When to Use |
|----------|------|-------------|-------------|
| `Text` | string | Item display text | Set group label |
| `Image` | Image | Item icon image | Add visual identifier |
| `Client` | Control | Client control (typically GroupView) | Link content to item |
| `Selected` | bool | Whether item is selected | Check/set selection |
### GroupView Properties
| Property | Type | Description | When to Use |
|----------|------|-------------|-------------|
| `GroupViewItems` | Collection | Child items in the view | Add child items |
| `SelectedItem` | GroupViewItem | Currently selected child | Get/set selected child |
| `Name` | string | Identifier for the view | Reference the view |
### Styling Properties
| Property | Type | Description | When to Use |
|----------|------|-------------|-------------|
| `VisualStyle` | VisualStyle | Theme (Office2007/2010/2016/Metro) | Apply themes |
| `Office2007Theme` | Office2007Theme | Office2007 color scheme | Blue/Silver/Black/Managed |
| `Office2010Theme` | Office2010Theme | Office2010 color scheme | Blue/Silver/Black/Managed |
| `BorderStyle` | BorderStyle | Border appearance | Customize borders |
| `BackColor` | Color | Background color | Custom backgrounds |
### Advanced Properties
| Property | Type | Description | When to Use |
|----------|------|-------------|-------------|
| `AllowCollapse` | bool | Allow collapsing groups | Enable collapse behavior |
| `AllowInPlaceEditing` | bool | Enable item renaming | Runtime editing |
| `AnimateCollapse` | bool | Animate collapse/expand | Smooth transitions |
| `ShowToolTips` | bool | Display tooltips | Show item descriptions |
## Common Use Cases
### Email Client Navigation
Outlook-style navigation with mail folders:
- Mail folders (Inbox, Drafts, Sent, Deleted)
- Calendar view with appointments
- Contacts list with categories
- Tasks with priority sections
### IDE Toolbox Interfaces
Visual Studio-style toolboxes:
- Categorized control collections
- Component categories (Data, Layout, Controls)
- Collapsible sections
- Drag-drop tool selection
### Document Management Systems
Hierarchical document navigation:
- Document categories and folders
- Project hierarchies
- File type groupings
- Archive sections
### Settings and Configuration Panels
Categorized settings navigation:
- General settings section
- Account preferences
- Advanced options
- Theme customization
## Implementation Checklist
When implementing GroupBar (Navigation Pane), ensure:
- ✅ **Required assemblies** referenced (Syncfusion.Shared.Base.dll)
- ✅ **Namespace** included (Syncfusion.Windows.Forms.Tools)
- ✅ **GroupBar instance** created and configured
- ✅ **GroupBarItems** added to GroupBarItems collection
- ✅ **GroupView** created if displaying child items
- ✅ **Client property** set to link GroupView to GroupBarItem
- ✅ **Visual style** applied (VisualStyle property)
- ✅ **Dock property** set for proper layout (typically DockStyle.Left)
- ✅ **Event handlers** added for item selection
- ✅ **Testing** with multiple items and navigation
## Troubleshooting Quick Reference
**Issue:** GroupBar not visible
- Check if GroupBar is added to form's Controls
- Set Dock property (DockStyle.Left recommended)
- Verify Width property is sufficient (200-250 pixels typical)
- Ensure form has space for docked control
**Issue:** GroupBarItems not appearing
- Verify items are added to GroupBarItems collection
- Check Text property is set on each item
- Ensure GroupBar.Visible = true
- Verify items are not collapsed/hidden
**Issue:** Child items (GroupViewItems) not displaying
- Create GroupView instance
- Add GroupViewItems to GroupView.GroupViewItems collection
- Set GroupBarItem.Client = groupView
- Add GroupView to GroupBar.Controls collection
**Issue:** StackedMode not working
- Set StackedMode = true
- Ensure multiple GroupBarItems exist (need 2+ for stacking)
- Check HeaderHeight property (0 hides header)
- Verify visual style supports stacked mode
**Issue:** Theme not applying
- Set VisualStyle property to desired theme
- For Office2007/2010, set corresponding theme property (Office2007Theme, Office2010Theme)
- For managed colors, call ApplyManagedColors method
- Ensure Syncfusion.Shared.Base assembly is referenced
**Issue:** GroupView selection not working
- Handle GroupViewItemSelected event
- Check GroupView.SelectedItem property
- Ensure GroupViewItems have unique identifiers
- Verify click events are wired up
## Summary
GroupBar (Navigation Pane) provides Outlook-style navigation functionality with:
- **Hierarchical Navigation**: GroupBarItem groups with GroupView child items
- **Stacked Mode**: Outlook-style navigation pane with collapsible sections
- **Office Themes**: Office 2007/2010/2016, Metro, and custom themes
- **Nested Support**: GroupBar within GroupBar capability
- **Serialization**: Save/restore layout state
- **Customizable Appearance**: Headers, borders, colors, animations
Use GroupBar when Outlook-style navigation, toolbox interfaces, categorized hierarchies, or themed navigation containers are needed for creating professional and organized WinForms applications.