windowsforms-devexpress-dot-xtrabars-dot-navigation.md
An advanced hierarchical navigation menu.
Namespace : DevExpress.XtraBars.Navigation
Assembly : DevExpress.XtraBars.v25.2.dll
NuGet Package : DevExpress.Win.Navigation
[DXLicenseWinForms]
public class AccordionControl :
BaseStyleControl,
IContextItemCollectionOwner,
IContextItemCollectionOptionsOwner,
ISearchControlClient,
IElementCollectionContainer,
ISupportInitialize,
IXtraSerializable,
IXtraSerializableLayout,
ISupportXtraSerializer,
ISupportJsonXtraSerializer,
IToolTipControlClient,
IMouseWheelSupport,
IContextItemProvider,
ISupportDirectCompositionEx,
ISupportDirectComposition,
ISupportAsyncScrollAnimation,
IChildControlsIgnoreMouseWheel,
IFilteringUIProvider,
IOfficeNavigationBarClient,
INavigationBarClient,
IResizableNavigationControl,
ITouchScrollBarOwner,
ISupportImageDragDrop,
ISupportAdornerUIManager,
IWin32Window,
IUpdateAdornerUI
<DXLicenseWinForms>
Public Class AccordionControl
Inherits BaseStyleControl
Implements IContextItemCollectionOwner,
IContextItemCollectionOptionsOwner,
ISearchControlClient,
IElementCollectionContainer,
ISupportInitialize,
IXtraSerializable,
IXtraSerializableLayout,
ISupportXtraSerializer,
ISupportJsonXtraSerializer,
IToolTipControlClient,
IMouseWheelSupport,
IContextItemProvider,
ISupportDirectCompositionEx,
ISupportDirectComposition,
ISupportAsyncScrollAnimation,
IChildControlsIgnoreMouseWheel,
IFilteringUIProvider,
IOfficeNavigationBarClient,
INavigationBarClient,
IResizableNavigationControl,
ITouchScrollBarOwner,
ISupportImageDragDrop,
ISupportAdornerUIManager,
IWin32Window,
IUpdateAdornerUI
The following members return AccordionControl objects:
Accordion Control is a side navigation control that can be used as a replacement for the NavBarControl.
Features include:
You can use the control’s properties (for example, AccordionControl.Appearance, AccordionControlElement.Appearance, and AccordionControlElement.HeaderTemplate) and events (for example, AccordionControl.CustomDrawElement) to customize the contents, layout, and appearance settings of the control’s elements.
AccordionControl allows you to use your knowledge of HTML and CSS markup to render the control’s UI elements. A template’s HTML markup specifies an element’s contents, while the template’s CSS code specifies style, display, and layout settings applied to the element.
AccordionControl exposes a set of properties (accessible from the AccordionControl.HtmlTemplates object) to specify HTML-CSS templates to render the control’s elements:
When you specify templates for AccordionControl elements, you can use the data binding syntax (${PropertyName}) to display text, images, and custom values (AccordionControlElementBase.Tag) of these elements.
${Text} — Inserts an element’s text (AccordionControlElementBase.Text).
${Image} — Inserts an element’s image specified in the AccordionControlElementBase.ImageOptions object. Use the img tag to insert an image, for example, as follows: `
<div class="item_layout">
<div class="item_text">${Text}</div>
</div>
You can also use the ${MyField1} syntax to mark an element as bound to a custom data source. The actual data for this element is set in the QueryHtmlElementData event handler.
<div class="acc_item">${MyField1}</div>
private void OnQueryHtmlElementData(object sender, QueryAccordionHtmlElementDataEventArgs e) {
if (e.FieldName == "MyField1") {
e.Value = "CustomData";
}
}
Private Sub OnQueryHtmlElementData(ByVal sender As Object, ByVal e As QueryAccordionHtmlElementDataEventArgs)
If e.FieldName = "MyField1" Then
e.Value = "CustomData"
End If
End Sub
For more information, refer to the Accordion Control article.
You can display regular and super tooltips for items in an AccordionControl. If the control’s ShowToolTips option is enabled, a tooltip is shown when the mouse pointer hovers an item.
Use an item’s Hint property to specify regular tooltip content.
To assign a super tooltip to an item, use the SuperTip property. Enable the AllowHtmlText property to use HTML tags in the super tooltip.
Set the ToolTipController.ToolTipType property to SuperTip to replace regular tooltips with super tooltips. The controller automatically converts regular tooltips to super tooltips. To access this property, you can use the DefaultToolTipController component or a custom controller assigned to the control’s ToolTipController property. See the following topic for more information: Hints and Tooltips.
This example demonstrates how to use WinForms Accordion and Navigation Frame controls to implement a side navigation.
using System;
using System.Drawing;
using System.Windows.Forms;
using System.Collections.Generic;
using DevExpress.XtraEditors;
using DevExpress.XtraBars.Navigation;
using DevExpress.XtraGrid;
namespace DXApplication {
public partial class Form1 : XtraForm {
NavigationFrame navFrame;
NavigationPage navPage1, navPage2;
AccordionControl accordion;
public Form1() {
InitializeComponent();
navFrame = new NavigationFrame() {
Dock = DockStyle.Fill,
};
accordion = new AccordionControl(){ Dock = DockStyle.Left};
this.Controls.AddRange(new Control[] { navFrame, accordion });
InitNavigationFramePages(navFrame);
InitAccordion(accordion);
accordion.SendToBack();
}
void InitNavigationFramePages(NavigationFrame frame) {
// Initializes the first navigation page.
navPage1 = new NavigationPage(){ Caption = "Tasks" };
navPage1.Controls.Add(new GridControl() {
Dock = DockStyle.Fill,
DataSource = Task.GetSampleData() });
// Initializes the second navigation page.
navPage2 = new NavigationPage() { Caption = "Empty", BackColor = Color.Aqua };
frame.Pages.AddRange(new NavigationPage[] { navPage1, navPage2 });
}
void InitAccordion(AccordionControl accordion) {
AccordionControlElement group = new AccordionControlElement(ElementStyle.Group) {
Name = "accordionGroup1",
Text = "Pages",
Expanded = true
};
AccordionControlElement item1 = new AccordionControlElement(ElementStyle.Item) {
Name = "accordionItem1",
Text = "Page 1"
};
AccordionControlElement item2 = new AccordionControlElement(ElementStyle.Item) {
Name = "accordionItem2",
Text = "Page 2"
};
item1.Click += new EventHandler(this.accordionElement_Click);
item2.Click += new EventHandler(this.accordionElement_Click);
group.Elements.AddRange(new AccordionControlElement[] { item1, item2 });
accordion.Elements.Add(group);
}
void accordionElement_Click(object sender, EventArgs e) {
AccordionControlElement item = sender as AccordionControlElement;
navFrame.SelectedPage = item.Text == "Page 1" ? navPage1 : navPage2;
}
}
public class Task {
int fID;
public Task(int id) {
fID = id;
CreateDate = DateTime.Today;
}
public int ID {
get {
return fID;
}
}
public string Caption { get; set; }
public DateTime CreateDate { get; set; }
public static List<Task> GetSampleData() {
return new List<Task>() {
new Task(0){Caption = "Research", CreateDate = new DateTime(2022, 10, 15)},
new Task(1){Caption = "UI Design", CreateDate = new DateTime(2022, 11, 5)},
new Task(2){Caption = "Environment Setup", CreateDate = new DateTime(2022, 11, 10)},
new Task(3){Caption = "Sprint 1", CreateDate = new DateTime(2022, 11, 11)},
new Task(4){Caption = "Sprint 2", CreateDate = new DateTime(2022, 12, 12)},
new Task(5){Caption = "Sprint 3", CreateDate = new DateTime(2023, 1, 10)},
new Task(6){Caption = "Testing", CreateDate = new DateTime(2022, 2, 10)}
};
}
}
}
Imports System
Imports System.Drawing
Imports System.Windows.Forms
Imports System.Collections.Generic
Imports DevExpress.XtraEditors
Imports DevExpress.XtraBars.Navigation
Imports DevExpress.XtraGrid
Namespace DXApplication
Partial Public Class Form1
Inherits XtraForm
Private navFrame As NavigationFrame
Private navPage1, navPage2 As NavigationPage
Private accordion As AccordionControl
Public Sub New()
InitializeComponent()
navFrame = New NavigationFrame() With {.Dock = DockStyle.Fill}
accordion = New AccordionControl() With {.Dock = DockStyle.Left}
Me.Controls.AddRange(New Control() { navFrame, accordion })
InitNavigationFramePages(navFrame)
InitAccordion(accordion)
accordion.SendToBack()
End Sub
Private Sub InitNavigationFramePages(ByVal frame As NavigationFrame)
' Initializes the first navigation page.
navPage1 = New NavigationPage() With {.Caption = "Tasks"}
navPage1.Controls.Add(New GridControl() With {
.Dock = DockStyle.Fill,
.DataSource = Task.GetSampleData()
})
' Initializes the second navigation page.
navPage2 = New NavigationPage() With {
.Caption = "Empty",
.BackColor = Color.Aqua
}
frame.Pages.AddRange(New NavigationPage() { navPage1, navPage2 })
End Sub
Private Sub InitAccordion(ByVal accordion As AccordionControl)
Dim group As New AccordionControlElement(ElementStyle.Group) With {
.Name = "accordionGroup1",
.Text = "Pages",
.Expanded = True
}
Dim item1 As New AccordionControlElement(ElementStyle.Item) With {
.Name = "accordionItem1",
.Text = "Page 1"
}
Dim item2 As New AccordionControlElement(ElementStyle.Item) With {
.Name = "accordionItem2",
.Text = "Page 2"
}
AddHandler item1.Click, AddressOf accordionElement_Click
AddHandler item2.Click, AddressOf accordionElement_Click
group.Elements.AddRange(New AccordionControlElement() { item1, item2 })
accordion.Elements.Add(group)
End Sub
Private Sub accordionElement_Click(ByVal sender As Object, ByVal e As EventArgs)
Dim item As AccordionControlElement = TryCast(sender, AccordionControlElement)
navFrame.SelectedPage = If(item.Text = "Page 1", navPage1, navPage2)
End Sub
End Class
Public Class Task
Private fID As Integer
Public Sub New(ByVal id As Integer)
fID = id
CreateDate = Date.Today
End Sub
Public ReadOnly Property ID() As Integer
Get
Return fID
End Get
End Property
Public Property Caption() As String
Public Property CreateDate() As Date
Public Shared Function GetSampleData() As List(Of Task)
Return New List(Of Task)() From {
New Task(0) With {
.Caption = "Research",
.CreateDate = New Date(2022, 10, 15)
},
New Task(1) With {
.Caption = "UI Design",
.CreateDate = New Date(2022, 11, 5)
},
New Task(2) With {
.Caption = "Environment Setup",
.CreateDate = New Date(2022, 11, 10)
},
New Task(3) With {
.Caption = "Sprint 1",
.CreateDate = New Date(2022, 11, 11)
},
New Task(4) With {
.Caption = "Sprint 2",
.CreateDate = New Date(2022, 12, 12)
},
New Task(5) With {
.Caption = "Sprint 3",
.CreateDate = New Date(2023, 1, 10)
},
New Task(6) With {
.Caption = "Testing",
.CreateDate = New Date(2022, 2, 10)
}
}
End Function
End Class
End Namespace
This example demonstrates how to create a sample AccordionControl at runtime.
using DevExpress.XtraBars.Navigation;
using DevExpress.XtraEditors;
using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Diagnostics;
using System.Drawing;
using System.Linq;
using System.Text;
using System.Threading.Tasks;
using System.Windows.Forms;
namespace AccordionControl_ex {
public partial class Form1 : Form {
public Form1() {
InitializeComponent();
}
AccordionControl acControl;
private void Form1_Load(object sender, EventArgs e) {
acControl = new AccordionControl();
acControl.Dock = DockStyle.Left;
acControl.Parent = this;
acControl.Width = 200;
InitAccordionControl();
}
private void InitAccordionControl() {
acControl.BeginUpdate();
AccordionControlElement acRootGroupHome = new AccordionControlElement();
AccordionControlElement acItemActivity = new AccordionControlElement();
AccordionControlElement acItemNews = new AccordionControlElement();
AccordionControlElement acRootItemSettings = new AccordionControlElement();
acControl.ElementClick += new ElementClickEventHandler(this.accordionControl1_ElementClick);
//
// Root Group 'Home'
//
acRootGroupHome.Elements.AddRange(new AccordionControlElement[] {
acItemActivity,
acItemNews});
acRootGroupHome.Expanded = true;
acRootGroupHome.ImageOptions.ImageUri.Uri = "Home;Office2013";
acRootGroupHome.Name = "acRootGroupHome";
acRootGroupHome.Text = "Home";
//
// Child Item 'Activity'
//
acItemActivity.Name = "acItemActivity";
acItemActivity.Style = ElementStyle.Item;
acItemActivity.Tag = "idActivity";
acItemActivity.Text = "Activity";
//
// Child Item 'News'
//
acItemNews.Name = "acItemNews";
acItemNews.Style = ElementStyle.Item;
acItemNews.Tag = "idNews";
acItemNews.Text = "News";
//
// Root Item 'Settings' with ContentContainer
//
acRootItemSettings.ImageOptions.ImageUri.Uri = "Customization;Office2013";
acRootItemSettings.Name = "acRootItemSettings";
acRootItemSettings.Style = ElementStyle.Item;
acRootItemSettings.Text = "Settings";
//
// itemSettingsControlContainer
//
AccordionContentContainer itemSettingsControlContainer = new AccordionContentContainer();
HyperlinkLabelControl hyperlinkLabelControl1 = new HyperlinkLabelControl();
ToggleSwitch toggleSwitch1 = new ToggleSwitch();
acControl.Controls.Add(itemSettingsControlContainer);
acRootItemSettings.ContentContainer = itemSettingsControlContainer;
itemSettingsControlContainer.Controls.Add(hyperlinkLabelControl1);
itemSettingsControlContainer.Controls.Add(toggleSwitch1);
itemSettingsControlContainer.Appearance.BackColor = System.Drawing.SystemColors.Control;
itemSettingsControlContainer.Appearance.Options.UseBackColor = true;
itemSettingsControlContainer.Height = 60;
//
// hyperlinkLabelControl1
//
hyperlinkLabelControl1.Location = new System.Drawing.Point(26, 33);
hyperlinkLabelControl1.Size = new System.Drawing.Size(107, 13);
hyperlinkLabelControl1.Text = "www.devexpress.com";
hyperlinkLabelControl1.HyperlinkClick += new DevExpress.Utils.HyperlinkClickEventHandler(this.hyperlinkLabelControl1_HyperlinkClick);
//
// toggleSwitch1
//
toggleSwitch1.EditValue = true;
toggleSwitch1.Location = new System.Drawing.Point(24, 3);
toggleSwitch1.Properties.AllowFocused = false;
toggleSwitch1.Properties.AutoWidth = true;
toggleSwitch1.Properties.OffText = "Offline Mode";
toggleSwitch1.Properties.OnText = "Onlne Mode";
toggleSwitch1.Size = new System.Drawing.Size(134, 24);
toggleSwitch1.Toggled += new System.EventHandler(this.toggleSwitch1_Toggled);
acControl.Elements.AddRange(new DevExpress.XtraBars.Navigation.AccordionControlElement[] {
acRootGroupHome,
acRootItemSettings});
acRootItemSettings.Expanded = true;
acControl.EndUpdate();
}
private void accordionControl1_ElementClick(object sender, DevExpress.XtraBars.Navigation.ElementClickEventArgs e) {
if (e.Element.Style == DevExpress.XtraBars.Navigation.ElementStyle.Group) return;
if (e.Element.Tag == null) return;
string itemID = e.Element.Tag.ToString();
if (itemID == "idNews") {
//...
}
listBoxControl1.Items.Add(itemID + " clicked");
}
private void toggleSwitch1_Toggled(object sender, EventArgs e) {
//...
}
private void hyperlinkLabelControl1_HyperlinkClick(object sender, DevExpress.Utils.HyperlinkClickEventArgs e) {
Process.Start(e.Text);
}
}
}
Imports DevExpress.XtraBars.Navigation
Imports DevExpress.XtraEditors
Imports System
Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Diagnostics
Imports System.Drawing
Imports System.Linq
Imports System.Text
Imports System.Threading.Tasks
Imports System.Windows.Forms
Namespace AccordionControl_ex
Partial Public Class Form1
Inherits Form
Public Sub New()
InitializeComponent()
End Sub
Private acControl As AccordionControl
Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load
acControl = New AccordionControl()
acControl.Dock = DockStyle.Left
acControl.Parent = Me
acControl.Width = 200
InitAccordionControl()
End Sub
Private Sub InitAccordionControl()
acControl.BeginUpdate()
Dim acRootGroupHome As New AccordionControlElement()
Dim acItemActivity As New AccordionControlElement()
Dim acItemNews As New AccordionControlElement()
Dim acRootItemSettings As New AccordionControlElement()
AddHandler acControl.ElementClick, AddressOf accordionControl1_ElementClick
'
' Root Group 'Home'
'
acRootGroupHome.Elements.AddRange(New AccordionControlElement() { acItemActivity, acItemNews})
acRootGroupHome.Expanded = True
acRootGroupHome.ImageOptions.ImageUri.Uri = "Home;Office2013"
acRootGroupHome.Name = "acRootGroupHome"
acRootGroupHome.Text = "Home"
'
' Child Item 'Activity'
'
acItemActivity.Name = "acItemActivity"
acItemActivity.Style = ElementStyle.Item
acItemActivity.Tag = "idActivity"
acItemActivity.Text = "Activity"
'
' Child Item 'News'
'
acItemNews.Name = "acItemNews"
acItemNews.Style = ElementStyle.Item
acItemNews.Tag = "idNews"
acItemNews.Text = "News"
'
' Root Item 'Settings' with ContentContainer
'
acRootItemSettings.ImageOptions.ImageUri.Uri = "Customization;Office2013"
acRootItemSettings.Name = "acRootItemSettings"
acRootItemSettings.Style = ElementStyle.Item
acRootItemSettings.Text = "Settings"
'
' itemSettingsControlContainer
'
Dim itemSettingsControlContainer As New AccordionContentContainer()
Dim hyperlinkLabelControl1 As New HyperlinkLabelControl()
Dim toggleSwitch1 As New ToggleSwitch()
acControl.Controls.Add(itemSettingsControlContainer)
acRootItemSettings.ContentContainer = itemSettingsControlContainer
itemSettingsControlContainer.Controls.Add(hyperlinkLabelControl1)
itemSettingsControlContainer.Controls.Add(toggleSwitch1)
itemSettingsControlContainer.Appearance.BackColor = System.Drawing.SystemColors.Control
itemSettingsControlContainer.Appearance.Options.UseBackColor = True
itemSettingsControlContainer.Height = 60
'
' hyperlinkLabelControl1
'
hyperlinkLabelControl1.Location = New System.Drawing.Point(26, 33)
hyperlinkLabelControl1.Size = New System.Drawing.Size(107, 13)
hyperlinkLabelControl1.Text = "www.devexpress.com"
AddHandler hyperlinkLabelControl1.HyperlinkClick, AddressOf hyperlinkLabelControl1_HyperlinkClick
'
' toggleSwitch1
'
toggleSwitch1.EditValue = True
toggleSwitch1.Location = New System.Drawing.Point(24, 3)
toggleSwitch1.Properties.AllowFocused = False
toggleSwitch1.Properties.AutoWidth = True
toggleSwitch1.Properties.OffText = "Offline Mode"
toggleSwitch1.Properties.OnText = "Onlne Mode"
toggleSwitch1.Size = New System.Drawing.Size(134, 24)
AddHandler toggleSwitch1.Toggled, AddressOf toggleSwitch1_Toggled
acControl.Elements.AddRange(New DevExpress.XtraBars.Navigation.AccordionControlElement() { acRootGroupHome, acRootItemSettings})
acRootItemSettings.Expanded = True
acControl.EndUpdate()
End Sub
Private Sub accordionControl1_ElementClick(ByVal sender As Object, ByVal e As DevExpress.XtraBars.Navigation.ElementClickEventArgs)
If e.Element.Style = DevExpress.XtraBars.Navigation.ElementStyle.Group Then
Return
End If
If e.Element.Tag Is Nothing Then
Return
End If
Dim itemID As String = e.Element.Tag.ToString()
If itemID = "idNews" Then
'...
End If
listBoxControl1.Items.Add(itemID & " clicked")
End Sub
Private Sub toggleSwitch1_Toggled(ByVal sender As Object, ByVal e As EventArgs)
'...
End Sub
Private Sub hyperlinkLabelControl1_HyperlinkClick(ByVal sender As Object, ByVal e As DevExpress.Utils.HyperlinkClickEventArgs)
Process.Start(e.Text)
End Sub
End Class
End Namespace
Object MarshalByRefObject Component Control DevExpress.XtraEditors.XtraControl ControlBase BaseControl BaseStyleControl AccordionControl
See Also