The requested page is not available for the requested platform. You are viewing the content for Default platform.

Dashboard Item Caption

  • 5 min to read

Each dashboard item has a caption that is displayed at the top of this item. The caption contains static text and command buttons.

DashboardItem_Caption

To show or hide the caption of a dashboard item, click the Show Caption button in the Design Ribbon tab...

Layout_ShowCaption_Ribbon

...or right-click the item when designing the dashboard, and click the Show Caption menu item.

ItemMenu_ShowCaption

Use the DashboardItem.ShowCaption property to specify whether the caption of the dashboard item is displayed.

Note

The caption of the Range Filter dashboard item is not visible unless explicitly specified.

The caption of the dashboard item contains the following information and buttons, depending on the dashboard item type.

Names

  • Dashboard Item Name - the static text within a dashboard item's caption. Dashboard API provides the DashboardItem.Name property.
  • Data Item Container Name - the name of the data item container. For more information, refer to the Providing Data topic for the corresponding dashboard item. Dashboard API provides the NamedDataItemContainer.Name property.

You can change the name using the Edit Names dialog. To invoke this dialog, right-click the item when designing the dashboard, and click the Edit Names... menu item or click the Edit Names button in the Design Ribbon tab.

Layout_EditNamesDialog_Common

Tip

The string supplied as the Dashboard Item Name can contain HTML Tags. For example, the following string displays bold text: "<b>Caption</b>". Note that img tags are not supported. To insert images in the dashboard item caption use the run-time customization approach.

Interactivity Information

  • Drill-Down value - shows a value or values from the current drill-down hierarchy. For more information, refer to the Drill-Down topic.

Command Buttons

  • Export to button - allows you to print or export a dashboard item. To learn how to print individual dashboard items, see the Printing and Exporting topic.
  • Values button - invokes a drop-down menu that allows you to switch between data layers. The button can be shown for the PieDashboardItem, CardDashboardItem, GaugeDashboardItem and MapDashboardItem. For more information, refer to the Providing Data topic in the particular dashboard item section of the Designing Dashboard Items chapter.
  • Clear Master Filter button - allows you to reset filtering when a dashboard item acts as the Master Filter. To learn more, see the Master Filtering topic in the Interactivity section for the corresponding dashboard item.
  • Drill Up button - allows you to return to the previous detail level when the drill-down capability is enabled for this item. To learn more, see the Drill-Down topic in the Interactivity section for the corresponding dashboard item.
  • Clear Selection button - allows you to clear the selection inside an item.
  • Initial Extent button - restores the map default size and position in the MapDashboardItem..
  • Select Date Time Periods button / menu - allows you to select date-time periods for the RangeFilterDashboardItem.
  • Multi-Select button - allows you to filter data by selecting multiple elements in dashboard items. The button is displayed in Touch UI mode because in that mode the end-user cannot make multiple selections by holding the Ctrl key.
  • Maximize button - expands any dashboard item into the whole dashboard size to examine data in greater detail. Refer to Dashboard Items Layout for more information.
  • Restore button - restores the expanded item to its initial state. Refer to Dashboard Items Layout for more information.
  • Custom buttons - you can create command buttons and drop-down menus by handling the the DashboardDesigner.CustomizeDashboardItemCaption or DashboardViewer.CustomizeDashboardItemCaption event for the Designer/Viewer respectively. However, these buttons are created at runtime, do not persist and cannot be saved in XML dashboard definition files.

Run-time Customization

To customize the dashboard item caption at runtime by changing the displayed text, removing existing buttons and adding custom buttons or command bar items, including drop-down menus, handle the DashboardViewer.CustomizeDashboardItemCaption or DashboardDesigner.CustomizeDashboardItemCaption event.

Note

The complete sample project WinForms Dashboard - How to customize the dashboard title and dashboard item captions is available in the DevExpress Examples repository.

using DevExpress.DashboardCommon;
using Imports DevExpress.DashboardCommon.ViewerData;
using Imports DevExpress.DashboardWin;
// ...
dashboardViewer.CustomizeDashboardItemCaption += DashboardViewer_CustomizeDashboardItemCaption;
// ...
private void DashboardViewer_CustomizeDashboardItemCaption(object sender, CustomizeDashboardItemCaptionEventArgs e)
{
    // Remove the Export button depending on the static variable.
    if (!allowExport)
    {
            if (!e.DashboardItemName.Contains("Map"))
            {
                var exportItem = items.FirstOrDefault(i => i.ButtonType == DashboardButtonType.Export);
                if (exportItem != null)
                {
                    items.Remove(exportItem);
                }
            }
        }
    // 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()));

}