Back to Devexpress

AccordionControl Class

windowsforms-devexpress-dot-xtrabars-dot-navigation.md

latest34.2 KB
Original Source

AccordionControl Class

An advanced hierarchical navigation menu.

Namespace : DevExpress.XtraBars.Navigation

Assembly : DevExpress.XtraBars.v25.2.dll

NuGet Package : DevExpress.Win.Navigation

Declaration

csharp
[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
vb
<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:

Remarks

Accordion Control is a side navigation control that can be used as a replacement for the NavBarControl.

Features include:

Customize Appearance Settings

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.

Use HTML-CSS Templates to Render UI 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:

Display Element’s Text, Images, and Custom Data

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>
</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.

html
<div class="acc_item">${MyField1}</div>
csharp
private void OnQueryHtmlElementData(object sender, QueryAccordionHtmlElementDataEventArgs e) {
    if (e.FieldName == "MyField1") {
        e.Value = "CustomData";
    }
}
vb
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.

Tooltips

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.

Example - How to Create Side Navigation

This example demonstrates how to use WinForms Accordion and Navigation Frame controls to implement a side navigation.

csharp
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)}
        };
        }
    }
}
vb
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

Example - How to Create Accordion in Code

This example demonstrates how to create a sample AccordionControl at runtime.

View Example

csharp
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);
        }

    }
}
vb
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

Implements

IXtraResizableControl

Inheritance

Object MarshalByRefObject Component Control DevExpress.XtraEditors.XtraControl ControlBase BaseControl BaseStyleControl AccordionControl

See Also

AccordionControl Members

AccordionControlElement

Accordion Control

DevExpress.XtraBars.Navigation Namespace