Title and Item Captions

• Jul 26, 2019
• 3 minutes to read

The Dashboard Title and Dashboard Item Caption are areas located on the dashboard surface and may contain relevant up-to-date information regarding the displayed data and command buttons, which allow end-users to easily perform common activities. Title and captions are already packed with useful indicators and buttons, but you can also deliberately hide built-in items or add your own.

This example demonstrates how to handle the CustomizeDashboardTitle and CustomizeDashboardItemCaption events to add command buttons with custom actions.

Note

The complete sample project How to Add a Command Button to the Dashboard Title and Item Caption is available in the DevExpress Examples repository.

C#

using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;

namespace CommandButtonForTitleAndCaption
{
    public partial class Form1 : DevExpress.XtraEditors.XtraForm
    {
        public Form1()
        {
            InitializeComponent();
            dashboardViewer1.ConfigureDataConnection += DashboardViewer1_ConfigureDataConnection;
            dashboardViewer1.CustomizeDashboardTitle += DashboardViewer1_CustomizeDashboardTitle;
            dashboardViewer1.CustomizeDashboardItemCaption += DashboardViewer1_CustomizeDashboardItemCaption;
            dashboardViewer1.LoadDashboard("DashboardTest.xml");
        }

        private void DashboardViewer1_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e)
        {
            DashboardToolbarItem item = new DashboardToolbarItem(
                (args) =>
                {
                    System.Diagnostics.Process.Start("https://docs.devexpress.com/Dashboard/");
                })
            {
                SvgImage = svgImageCollection1["needassistance"],
                Caption = "Online Help",
                Tooltip = "Navigate to the online Dashboard help"
            };
            e.Items.Add(item);
        }
        private void DashboardViewer1_CustomizeDashboardItemCaption(object sender, CustomizeDashboardItemCaptionEventArgs e)
        {
            DashboardViewer viewer = sender as DashboardViewer;
            GridDashboardItem gridItem = viewer.Dashboard.Items[e.DashboardItemName] as GridDashboardItem;
            if (gridItem != null)
            {
                DashboardToolbarItem cmdButtonItem = new DashboardToolbarItem
                {
                    ClickAction = args => SwitchGridMeasureColumnDisplayMode(gridItem),
                    SvgImage = svgImageCollection1["bluedatabarsolid"],
                    Tooltip = "Switch between bars and numbers"
                };
                e.Items.Insert(0, cmdButtonItem);
            };

        }

        private void SwitchGridMeasureColumnDisplayMode(GridDashboardItem gridItem)
        {
            foreach (var column in gridItem.Columns)
            {
                GridMeasureColumn measureColumn = column as GridMeasureColumn;
                if (measureColumn != null)
                {
                    switch (measureColumn.DisplayMode)
                    {
                        case GridMeasureColumnDisplayMode.Bar:
                            measureColumn.DisplayMode = GridMeasureColumnDisplayMode.Value;
                            break;
                        case GridMeasureColumnDisplayMode.Value:
                            measureColumn.DisplayMode = GridMeasureColumnDisplayMode.Bar;
                            break;
                    }
                }
            }
        }
        private void DashboardViewer1_ConfigureDataConnection(object sender, DashboardConfigureDataConnectionEventArgs e)
        {
            if (e.ConnectionParameters is ExcelDataSourceConnectionParameters connParams)
                connParams.FileName = "SalesPerson.xlsx";
        }
    }
}

VB.NET

Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin

Namespace CommandButtonForTitleAndCaption
    Partial Public Class Form1
        Inherits DevExpress.XtraEditors.XtraForm

        Public Sub New()
            InitializeComponent()
            AddHandler dashboardViewer1.ConfigureDataConnection, AddressOf DashboardViewer1_ConfigureDataConnection
            AddHandler dashboardViewer1.CustomizeDashboardTitle, AddressOf DashboardViewer1_CustomizeDashboardTitle
            AddHandler dashboardViewer1.CustomizeDashboardItemCaption, AddressOf DashboardViewer1_CustomizeDashboardItemCaption
            dashboardViewer1.LoadDashboard("DashboardTest.xml")
        End Sub

        Private Sub DashboardViewer1_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As CustomizeDashboardTitleEventArgs)
            Dim item As DashboardToolbarItem = New DashboardToolbarItem(Sub(args)
                System.Diagnostics.Process.Start("https://docs.devexpress.com/Dashboard/")
            End Sub) With {.SvgImage = svgImageCollection1("needassistance"), .Caption = "Online Help", .Tooltip = "Navigate to the online Dashboard help"}
            e.Items.Add(item)
        End Sub
        Private Sub DashboardViewer1_CustomizeDashboardItemCaption(ByVal sender As Object, ByVal e As CustomizeDashboardItemCaptionEventArgs)
            Dim viewer As DashboardViewer = TryCast(sender, DashboardViewer)
            Dim gridItem As GridDashboardItem = TryCast(viewer.Dashboard.Items(e.DashboardItemName), GridDashboardItem)
            If gridItem IsNot Nothing Then
                Dim cmdButtonItem As DashboardToolbarItem = New DashboardToolbarItem With {.ClickAction = Sub(args) SwitchGridMeasureColumnDisplayMode(gridItem), .SvgImage = svgImageCollection1("bluedatabarsolid"), .Tooltip = "Switch between bars and numbers"}
                e.Items.Insert(0, cmdButtonItem)
            End If

        End Sub

        Private Sub SwitchGridMeasureColumnDisplayMode(ByVal gridItem As GridDashboardItem)
            For Each column In gridItem.Columns
                Dim measureColumn As GridMeasureColumn = TryCast(column, GridMeasureColumn)
                If measureColumn IsNot Nothing Then
                    Select Case measureColumn.DisplayMode
                        Case GridMeasureColumnDisplayMode.Bar
                            measureColumn.DisplayMode = GridMeasureColumnDisplayMode.Value
                        Case GridMeasureColumnDisplayMode.Value
                            measureColumn.DisplayMode = GridMeasureColumnDisplayMode.Bar
                    End Select
                End If
            Next column
        End Sub
        Private Sub DashboardViewer1_ConfigureDataConnection(ByVal sender As Object, ByVal e As DashboardConfigureDataConnectionEventArgs)
            Dim connParams As ExcelDataSourceConnectionParameters = TryCast(e.ConnectionParameters, ExcelDataSourceConnectionParameters)
            If connParams IsNot Nothing Then
                connParams.FileName = "SalesPerson.xlsx"
            End If
        End Sub
    End Class
End Namespace