Back to Devexpress

DashboardViewer.CustomizeDashboardTitle Event

dashboard-devexpress-dot-dashboardwin-dot-dashboardviewer-a8e13cda.md

latest22.5 KB
Original Source

DashboardViewer.CustomizeDashboardTitle Event

Allows you to customize the dashboard title at runtime.

Namespace : DevExpress.DashboardWin

Assembly : DevExpress.Dashboard.v25.2.Win.dll

NuGet Package : DevExpress.Win.Dashboard

Declaration

csharp
public event CustomizeDashboardTitleEventHandler CustomizeDashboardTitle
vb
Public Event CustomizeDashboardTitle As CustomizeDashboardTitleEventHandler

Event Data

The CustomizeDashboardTitle event's data class is CustomizeDashboardTitleEventArgs. The following properties provide information specific to this event:

PropertyDescription
FilterTextGets or sets the text displayed in the dashboard title or in the dashboard item caption. The text identifies a single master filter value applied to the dashboard. Inherited from CustomizeDashboardCaptionBaseEventArgs.
ItemsProvides access to command buttons located in the dashboard title or in the dashboard item’s caption. Inherited from CustomizeDashboardCaptionBaseEventArgs.
TextGets or sets the text displayed in the dashboard title or the dashboard item caption. Inherited from CustomizeDashboardCaptionBaseEventArgs.

Remarks

The DashboardViewer.CustomizeDashboardTitle event is raised when the dashboard is loaded (the DashboardViewer.Dashboard property is changed) or when end-user activities affect the dashboard title. Such activities include applying a master filter, performing drill-down or changing the parameter value.

You can change the displayed text, remove existing buttons, add custom buttons or command bar items, including drop-down menus.

Example

This example demonstrates how to handle the IDashboardControl.CustomizeDashboardItemCaption and IDashboardControl.CustomizeDashboardTitle events to modify dashboard title and dashboard item captions.

The dashboard title displays the dimensions and values by which the dashboard data is filtered. You can use a drop-down menu to selectively hide dashboard item captions. Clicking a custom Support button navigates to this example online.

A dashboard item caption displays the item’s master filter values.

Export buttons are hidden for all dashboard items except the map, and for the entire dashboard, if the displayed data’s Category field contains “Bikes”.

View Example: WinForms Dashboard - How to customize the dashboard title and dashboard item captions

cs
using DevExpress.DashboardCommon;
using DevExpress.DashboardCommon.ViewerData;
using DevExpress.DashboardWin;
using System;
using System.Collections.Generic;
using System.Data;
using System.Linq;

namespace CustomizeDashboardItemCaption_Viewer_Example {
    public partial class ViewerForm1 : DevExpress.XtraEditors.XtraForm {
        private static bool allowExport = false; 
        public ViewerForm1() {
            InitializeComponent();
            dashboardViewer.AllowPrintDashboardItems = true;

            dashboardViewer.CustomizeDashboardTitle += DashboardViewer_CustomizeDashboardTitle;
            dashboardViewer.CustomizeDashboardItemCaption += DashboardViewer_CustomizeDashboardItemCaption;

            dashboardViewer.PopupMenuShowing += DashboardViewer_PopupMenuShowing;
            dashboardViewer.MasterFilterSet += DashboardViewer_MasterFilterSet;

            dashboardViewer.UpdateDashboardTitle();
            UpdateDashboardItemCaptions();
        }

        private void DashboardViewer_CustomizeDashboardTitle(object sender, CustomizeDashboardTitleEventArgs e) {
            DashboardViewer viewer = (DashboardViewer)sender;

            // Display a string of master filter values.
            string filterText = string.Empty;
            foreach (var item in viewer.Dashboard.Items) {
                if (viewer.CanSetMasterFilter(item.ComponentName)) {
                    var filterValues = viewer.GetCurrentFilterValues(item.ComponentName);
                    filterText += GetFilterText(filterValues);
                }
            }
            DashboardToolbarItem toolbarItem = new DashboardToolbarItem();
            toolbarItem.Caption = "Filter: " + filterText;
            e.Items.Insert(0, toolbarItem);

            // Remove the Export button depending on the static variable.
            if (!allowExport) {
                RemoveExportButton(e.Items);
            }

            // Add drop-down menu to show/hide dashboard item captions.
            DashboardToolbarItem toolbarItemRoot = new DashboardToolbarItem();
            toolbarItemRoot.Caption = @"Show/Hide Dashboard Item Captions";
            toolbarItemRoot.SvgImage = svgImageCollection1["title"];
            foreach (var item in viewer.Dashboard.Items) {
                DashboardToolbarMenuItem menuItem = new DashboardToolbarMenuItem(item.ShowCaption, item.Name, 
                    new Action<DashboardToolbarItemClickEventArgs>((args) => {
                        item.ShowCaption = !item.ShowCaption;
                    }));
                menuItem.ImageOptions.SvgImage = svgImageCollection1["title"];
                toolbarItemRoot.MenuItems.Add(menuItem);
            }
            e.Items.Insert(0, toolbarItemRoot);

            // Add a button with an image to navigate to Online Help.
            DashboardToolbarItem infoLinkItem = new DashboardToolbarItem("",
                new Action<DashboardToolbarItemClickEventArgs>((args) => {
                    System.Diagnostics.Process.Start("https://docs.devexpress.com/Dashboard/");
                }));
            // Note that a raster image is proportionally resized to 24 px height when displayed in the Title area.
            infoLinkItem.SvgImage = svgImageCollection1["support"];
            e.Items.Add(infoLinkItem);
        }

        private void DashboardViewer_CustomizeDashboardItemCaption(object sender, CustomizeDashboardItemCaptionEventArgs e) {
            // Remove the Export button depending on the static variable.
            if (!allowExport) {
                if (!e.DashboardItemName.Contains("Map")) {
                    RemoveExportButton(e.Items);
                }
            }

            // Display filter values.
            DashboardViewer viewer = (DashboardViewer)sender;
            var filterValues = viewer.GetCurrentFilterValues(e.DashboardItemName);
            if (filterValues != null)
                if (filterValues.Count > 0)
                    e.FilterText = string.Format(" ( Filter: {0})", string.Concat(filterValues.Select(
                        axp => string.Format("{0} ", axp.GetAxisPoint(axp.AvailableAxisNames[0]).DisplayText)).ToArray()));

        }

        private void DashboardViewer_PopupMenuShowing(object sender, DashboardPopupMenuShowingEventArgs e) {
            // Hide popup menu everywhere except the dashboard title, to hide commands related to the export actions. 
            if (e.DashboardArea == DashboardArea.DashboardItem)
                e.Allow = false;
        }       
        private void DashboardViewer_MasterFilterSet(object sender, MasterFilterSetEventArgs e) {
            if (e.DashboardItemName == "listBoxDashboardItem1")
                allowExport = e.SelectedValues.Select(value => value[0].ToString()).Contains("Bikes") ? false : true;
            UpdateDashboardItemCaptions();
            dashboardViewer.UpdateDashboardTitle();
        }
        private string GetFilterText(IList<AxisPointTuple> filterValues) {
            string filterText = string.Empty;
            if (filterValues.Count > 0) {
                string dimensionName = string.Concat(filterValues.Select(
                    axp => string.Format("{0} ", axp.GetAxisPoint(axp.AvailableAxisNames[0]).Dimension.Name)).Distinct());
                filterText = string.Format(" ({0}:{1})", dimensionName, string.Join(",", filterValues.Select(
                    axp => string.Format(" {0}", axp.GetAxisPoint(axp.AvailableAxisNames[0]).DisplayText)).ToArray()));
            }
            return filterText;
        }
        private void UpdateDashboardItemCaptions() {
            foreach (DashboardItem i in dashboardViewer.Dashboard.Items) {
                dashboardViewer.UpdateDashboardItemCaption(i.ComponentName);
            }
        }
        private void RemoveExportButton(IList<DashboardToolbarItem> items) {
            var exportItem = items.FirstOrDefault(i => i.ButtonType == DashboardButtonType.Export);
            if (exportItem != null) {
                items.Remove(exportItem);
            }
        }
    }
}
vb
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardCommon.ViewerData
Imports DevExpress.DashboardWin
Imports System
Imports System.Collections.Generic
Imports System.Data
Imports System.Linq

Namespace CustomizeDashboardItemCaption_Viewer_Example
    Partial Public Class ViewerForm1
        Inherits DevExpress.XtraEditors.XtraForm

        Private Shared allowExport As Boolean = False

        Public Sub New()
            InitializeComponent()
            dashboardViewer.AllowPrintDashboardItems = True

            AddHandler dashboardViewer.CustomizeDashboardTitle, AddressOf DashboardViewer_CustomizeDashboardTitle
            AddHandler dashboardViewer.CustomizeDashboardItemCaption, AddressOf DashboardViewer_CustomizeDashboardItemCaption

            AddHandler dashboardViewer.PopupMenuShowing, AddressOf DashboardViewer_PopupMenuShowing
            AddHandler dashboardViewer.MasterFilterSet, AddressOf DashboardViewer_MasterFilterSet

            dashboardViewer.UpdateDashboardTitle()
            UpdateDashboardItemCaptions()
        End Sub

        Private Sub DashboardViewer_CustomizeDashboardTitle(ByVal sender As Object, ByVal e As CustomizeDashboardTitleEventArgs)
            Dim viewer As DashboardViewer = DirectCast(sender, DashboardViewer)

            ' Display a string of master filter values.
            Dim filterText As String = String.Empty
            For Each item In viewer.Dashboard.Items
                If viewer.CanSetMasterFilter(item.ComponentName) Then
                    Dim filterValues = viewer.GetCurrentFilterValues(item.ComponentName)
                    filterText &= GetFilterText(filterValues)
                End If
            Next item
            Dim toolbarItem As New DashboardToolbarItem()
            toolbarItem.Caption = "Filter: " & filterText
            e.Items.Insert(0, toolbarItem)

            ' Remove the Export button depending on the static variable.
            If Not allowExport Then
                RemoveExportButton(e.Items)
            End If

            ' Add drop-down menu to show/hide dashboard item captions.
            Dim toolbarItemRoot As New DashboardToolbarItem()
            toolbarItemRoot.Caption = "Show/Hide Dashboard Item Captions"
            toolbarItemRoot.SvgImage = svgImageCollection1("title")
            For Each item In viewer.Dashboard.Items
                Dim menuItem As DashboardToolbarMenuItem = New DashboardToolbarMenuItem(item.ShowCaption, item.Name, New Action(Of DashboardToolbarItemClickEventArgs)(Sub(args)
                    item.ShowCaption = Not item.ShowCaption
                End Sub))
                menuItem.ImageOptions.SvgImage = svgImageCollection1("title")
                toolbarItemRoot.MenuItems.Add(menuItem)
            Next item
            e.Items.Insert(0, toolbarItemRoot)

            ' Add a button with an image to navigate to this example online.
            Dim infoLinkItem As DashboardToolbarItem = New DashboardToolbarItem("", New Action(Of DashboardToolbarItemClickEventArgs)(Sub(args)
                System.Diagnostics.Process.Start("https://www.devexpress.com/Support/Center/Example/Details/T630210/")
            End Sub))
            ' Note that a raster image is proportionally resized to 24 px height when displayed in the Title area.
            infoLinkItem.SvgImage = svgImageCollection1("support")
            e.Items.Add(infoLinkItem)
        End Sub

        Private Sub DashboardViewer_CustomizeDashboardItemCaption(ByVal sender As Object, ByVal e As CustomizeDashboardItemCaptionEventArgs)
            ' Remove the Export button depending on the static variable.
            If Not allowExport Then
                If Not e.DashboardItemName.Contains("Map") Then
                    RemoveExportButton(e.Items)
                End If
            End If

            ' Display filter values.
            Dim viewer As DashboardViewer = DirectCast(sender, DashboardViewer)
            Dim filterValues = viewer.GetCurrentFilterValues(e.DashboardItemName)
            If filterValues IsNot Nothing Then
                If filterValues.Count > 0 Then
                    e.FilterText = String.Format(" ( Filter: {0})", String.Concat(filterValues.Select(Function(axp) String.Format("{0} ", axp.GetAxisPoint(axp.AvailableAxisNames(0)).DisplayText)).ToArray()))
                End If
            End If

        End Sub

        Private Sub DashboardViewer_PopupMenuShowing(ByVal sender As Object, ByVal e As DashboardPopupMenuShowingEventArgs)
            ' Hide popup menu everywhere except the dashboard title, to hide commands related to the export actions. 
            If e.DashboardArea = DashboardArea.DashboardItem Then
                e.Allow = False
            End If
        End Sub
        Private Sub DashboardViewer_MasterFilterSet(ByVal sender As Object, ByVal e As MasterFilterSetEventArgs)
            If e.DashboardItemName = "listBoxDashboardItem1" Then
                allowExport = If(e.SelectedValues.Select(Function(value) value(0).ToString()).Contains("Bikes"), False, True)
            End If
            UpdateDashboardItemCaptions()
            dashboardViewer.UpdateDashboardTitle()
        End Sub
        Private Function GetFilterText(ByVal filterValues As IList(Of AxisPointTuple)) As String
            Dim filterText As String = String.Empty
            If filterValues.Count > 0 Then
                Dim dimensionName As String = String.Concat(filterValues.Select(Function(axp) String.Format("{0} ", axp.GetAxisPoint(axp.AvailableAxisNames(0)).Dimension.Name)).Distinct())
                filterText = String.Format(" ({0}:{1})", dimensionName, String.Join(",", filterValues.Select(Function(axp) String.Format(" {0}", axp.GetAxisPoint(axp.AvailableAxisNames(0)).DisplayText)).ToArray()))
            End If
            Return filterText
        End Function
        Private Sub UpdateDashboardItemCaptions()
            For Each i As DashboardItem In dashboardViewer.Dashboard.Items
                dashboardViewer.UpdateDashboardItemCaption(i.ComponentName)
            Next i
        End Sub
        Private Sub RemoveExportButton(ByVal items As IList(Of DashboardToolbarItem))
            Dim exportItem = items.FirstOrDefault(Function(i) i.ButtonType = DashboardButtonType.Export)
            If exportItem IsNot Nothing Then
                items.Remove(exportItem)
            End If
        End Sub
    End Class
End Namespace

The following code snippets (auto-collected from DevExpress Examples) contain references to the CustomizeDashboardTitle event.

Note

The algorithm used to collect these code examples remains a work in progress. Accordingly, the links and snippets below may produce inaccurate results. If you encounter an issue with code examples below, please use the feedback form on this page to report the issue.

winforms-dashboard-apply-conditional-formatting-to-grid-cells/CS/Dashboard_ConditionalFormatting_Grid/IconRangeConditionForm.cs#L9

csharp
InitializeComponent();
dashboardViewer1.CustomizeDashboardTitle += DashboardViewer1_CustomizeDashboardTitle;
Dashboard dashboard = new Dashboard(); dashboard.LoadFromXml(@"..\..\Data\Dashboard.xml");

winforms-dashboard-designer-bind-a-dashboard-to-a-list-object/CS/Dashboard_BindingToList/Form1.cs#L12

csharp
dashboardViewer1.DataSourceOptions.ObjectDataSourceLoadingBehavior = DocumentLoadingBehavior.LoadAsIs;
    dashboardViewer1.CustomizeDashboardTitle += DashboardViewer1_CustomizeDashboardTitle;
}

winforms-dashboard-viewer-tab-navigation-buttons-tab-animation/CS/DashboardNextPrevTab/ViewerForm.cs#L21

csharp
dashboardViewer.CustomizeDashboardTitle += DashboardViewerCustomizeDashboardTitle;
dashboardViewer.SelectedTabPageChanged += DashboardViewerSelectedTabPageChanged;

winforms-dashboard-apply-master-filter-in-viewer/CS/Dashboard_SetMasterFilter/Form1.cs#L16

csharp
dashboardViewer1.ConfigureDataConnection += DashboardViewer1_ConfigureDataConnection;
dashboardViewer1.CustomizeDashboardTitle += DashboardViewer1_CustomizeDashboardTitle;

winforms-dashboard-create-layout-from-scratch/CS/Dashboard_LayoutCustomization/Form1.cs#L15

csharp
InitializeComponent();
dashboardViewer1.CustomizeDashboardTitle += DashboardViewer1_CustomizeDashboardTitle;
dashboardViewer1.LoadDashboard(@"Data\LayoutUnordered.xml");

winforms-dashboard-apply-conditional-formatting-to-grid-cells/VB/Dashboard_ConditionalFormatting_Grid/GradientRangeConditionForm.vb#L12

vb
InitializeComponent()
AddHandler dashboardViewer1.CustomizeDashboardTitle, AddressOf DashboardViewer1_CustomizeDashboardTitle
Dim dashboard As New Dashboard()

winforms-dashboard-designer-bind-a-dashboard-to-a-list-object/VB/Dashboard_BindingToList/Form1.vb#L14

vb
dashboardViewer1.DataSourceOptions.ObjectDataSourceLoadingBehavior = DocumentLoadingBehavior.LoadAsIs
    AddHandler dashboardViewer1.CustomizeDashboardTitle, AddressOf DashboardViewer1_CustomizeDashboardTitle
End Sub

winforms-dashboard-viewer-tab-navigation-buttons-tab-animation/VB/DashboardNextPrevTab/ViewerForm.vb#L25

vb
InitializeComponent()
AddHandler dashboardViewer.CustomizeDashboardTitle, AddressOf DashboardViewerCustomizeDashboardTitle
AddHandler dashboardViewer.SelectedTabPageChanged, AddressOf DashboardViewerSelectedTabPageChanged

winforms-dashboard-apply-master-filter-in-viewer/VB/Dashboard_SetMasterFilter/Form1.vb#L19

vb
AddHandler dashboardViewer1.ConfigureDataConnection, AddressOf DashboardViewer1_ConfigureDataConnection
AddHandler dashboardViewer1.CustomizeDashboardTitle, AddressOf DashboardViewer1_CustomizeDashboardTitle
dashboardViewer1.LoadDashboard("Dashboard.xml")

winforms-dashboard-create-layout-from-scratch/VB/Dashboard_LayoutCustomization/Form1.vb#L14

vb
InitializeComponent()
AddHandler dashboardViewer1.CustomizeDashboardTitle, AddressOf DashboardViewer1_CustomizeDashboardTitle
dashboardViewer1.LoadDashboard("Data\LayoutUnordered.xml")

Implements

CustomizeDashboardTitle

See Also

Title and Item Captions

DashboardViewer Class

DashboardViewer Members

DevExpress.DashboardWin Namespace