dashboard-15732-winforms-dashboard-winforms-designer-ui-elements-and-customization-ui-elements-ribbon.md
The Dashboard Designer’s Ribbon toolbar consists of two page categories:
The main pages include:
HomeContains common dashboard commands that allow users to create a new dashboard and add dashboard items, add a title, save the created dashboard, and more.Data SourceContains commands used to create and edit data sources, calculated fields, and more.ViewAllows users to switch between built-in application themes.
Contextual pages contain commands related to a specific dashboard item. For instance, the contextual page commands on the image above are used to filter dashboard item data, execute layout operations, and so on.
The Dashboard Designer’s Ribbon contains the following elements:
The table below lists these elements, their descriptions, and properties that affect element functionality and appearance.
|
Element
|
Description
|
Ribbon API
| | --- | --- | --- | |
|
Allows you to access the most important and frequently used features in the Dashboard Designer.
|
RibbonQuickAccessToolbar.ItemLinks
| |
|
Allows you to access the Dashboard Designer’s main menu.
|
RibbonControl.ShowApplicationButton
RibbonControl.ApplicationButtonDropDownControl
| |
|
Contain common dashboard commands.
|
| |
|
Combines pages related to a specific dashboard item.
|
| |
|
Contain commands related to a specific dashboard item.
|
| |
|
Contain groups of bar item links within a Ribbon Page.
|
| |
|
Visual elements (for instance, command buttons, editors, submenus, and static text) displayed within the Ribbon. A Bar Item link refers to a specific bar item.
|
|
Click the DashboardDesigner‘s smart tag to create and initialize a Ribbon at design time within Visual Studio:
Select Create Ribbon in the invoked context menu to add the following visual and non-visual components:
RibbonControlCreates a Ribbon toolbar with commands grouped into categories, pages, and page groups.BackstageViewControl descendantEmulates a menu found in Microsoft Office 2010-2016 products.DashboardPopupMenu
Allows you to customize Dashboard Designer’s popup menus at design time when you run the Run Designer command.
DashboardBarAndDockingControllerStores the Look and Feel, appearance, and customization settings of the Dashboard Designer. The DashboardBarAndDockingController is a BarAndDockingController descendant. The DashboardDesigner.BarAndDockingController property allows you to access to DashboardBarAndDockingController.DashboardBarControllerSupports the internal infrastructure.TextBoxEditorBarControllerSupports the UI of the Text Box dashboard item in edit mode.
Click the RibbonControl smart tag and choose Run Designer to customize the Ribbon control. For more information on how to customize Ribbon items, the Quick Access Toolbar, popup menus, and more, see the following topic: Ribbon Control Designer.
If your application already contains a Ribbon (for instance, from an earlier version of the Dashboard Designer), you can select the Update Ribbon menu item to update it:
The Update Ribbon command in the smart tag menu updates all elements related to the default ribbon created by the Dashboard Designer. If you customize default elements in the Ribbon and then use the Update Ribbon command, apply the same customizations after the update is complete.
Important
If you are upgrading your project to another major release, you should update the Ribbon.
Use the DashboardDesigner.CreateRibbon method to create and initialize a Ribbon in code. The Ribbon will appear at runtime.
Use the following code to obtain a RibbonControl instance:
using DevExpress.XtraBars.Ribbon;
//...
RibbonControl ribbon = dashboardDesigner.MenuManager as RibbonControl;
Imports DevExpress.XtraBars.Ribbon
//...
Dim ribbon As RibbonControl = TryCast(dashboardDesigner.MenuManager, RibbonControl)
You can add new control elements to the current Ribbon instance. Use the DashboardDesignerBarExtensions class’ static methods to get the current Ribbon instance. The DashboardRibbonPage and DashboardBarItemCategory values specify the button’s position.
This example creates a new Custom Properties group on the Grid’s Design page and adds the Fix Columns button to it:
void AddBarItem(SvgImage svgImage) {
RibbonControl ribbon = designer.Ribbon;
RibbonPage page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.GridTools, DashboardRibbonPage.Design);
RibbonPageGroup group = page.GetGroupByName("Custom Properties");
if(group == null) {
group = new RibbonPageGroup("Custom Properties") { Name = "Custom Properties" };
page.Groups.Add(group);
}
barItem = new BarCheckItem(ribbon.Manager);
barItem.Caption = "Fix Columns";
barItem.ImageOptions.SvgImage = svgImage;
group.ItemLinks.Add(barItem);
page.Groups.Add(group);
}
Private Sub AddBarItem(ByVal svgImage As SvgImage)
Dim ribbon As RibbonControl = designer.Ribbon
Dim page As RibbonPage = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.GridTools, DashboardRibbonPage.Design)
Dim group As RibbonPageGroup = page.GetGroupByName("Custom Properties")
If group Is Nothing Then
group = New RibbonPageGroup("Custom Properties") With {.Name = "Custom Properties"}
page.Groups.Add(group)
End If
barItem = New BarCheckItem(ribbon.Manager)
barItem.Caption = "Fix Columns"
barItem.ImageOptions.SvgImage = svgImage
group.ItemLinks.Add(barItem)
page.Groups.Add(group)
End Sub
Refer to the following article for more information on how to integrate custom property functionality in a Dashboard: Create Custom Properties.
In this example, the Description button is added to the Dashboard group on the Dashboard’s Home page.
void AddBarItem(SvgImage barImage) {
var page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.None, DashboardRibbonPage.Home);
RibbonPageGroup group = page.Groups.GetGroupByText("Dashboard");
barItem = new BarButtonItem(ribbon.Manager, "Dashboard Description");
if(barImage != null)
barItem.ImageOptions.SvgImage = barImage;
group.ItemLinks.Add(barItem);
}
Private Sub AddBarItem(ByVal barImage As SvgImage)
Dim page = ribbon.GetDashboardRibbonPage(DashboardBarItemCategory.None, DashboardRibbonPage.Home)
Dim group As RibbonPageGroup = page.Groups.GetGroupByText("Dashboard")
barItem = New BarButtonItem(ribbon.Manager, "Dashboard Description")
If barImage IsNot Nothing Then
barItem.ImageOptions.SvgImage = barImage
End If
group.ItemLinks.Add(barItem)
End Sub
Refer to the following article for more information on how to integrate custom property functionality in a Dashboard: Create Custom Properties.
Use the DashboardDesigner.CreateCustomItemBars method to add a custom item bar at runtime.
The CreateCustomItemBars method inserts a custom item’s bar into the Ribbon. Before you add a bar, make sure that you have registered the corresponding metadata type and created the Ribbon.
Call the CreateCustomItemBars method to add bars for all custom items whose metadata is registered. To add bars for the corresponding custom items, pass their metadata as the customItemMetadataTypes parameter.
using System.Windows.Forms;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
namespace TutorialsCustomItems {
public partial class Form1 : Form {
public Form1(){
InitializeComponent();
dashboardDesigner1.CreateRibbon();
dashboardDesigner1.CreateCustomItemBars();
}
}
}
Imports System.Windows.Forms
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Namespace CustomItemsSample
Partial Public Class Form1
Inherits Form
Public Sub New()
InitializeComponent()
dashboardDesigner1.CreateRibbon()
dashboardDesigner1.CreateCustomItemBars()
End Sub
End Class
End Namespace
Refer to the following article for more information on how to integrate custom items in a Dashboard: Create a Custom Item.
You can remove items from the Ribbon’s Items collection to hide unnecessary commands. For example, the following code removes the Save As , Open , New , and Treemap commands:
using DevExpress.XtraBars;
using DevExpress.XtraBars.Ribbon;
using System.Collections.Generic;
namespace DXDashboardApp {
public partial class DesignerForm1 : DevExpress.XtraBars.Ribbon.RibbonForm {
public DesignerForm1() {
InitializeComponent();
dashboardDesigner.CreateRibbon();
RemoveBarItems(dashboardDesigner.Ribbon);
}
private void RemoveBarItems(RibbonControl ribbonControl) {
List<BarItem> itemsToRemove = new List<BarItem>();
foreach (BarItem item in ribbonControl.Items) {
if (item is DevExpress.DashboardWin.Bars.FileSaveAsBarItem) itemsToRemove.Add(item);
if (item is DevExpress.DashboardWin.Bars.FileOpenBarItem) itemsToRemove.Add(item);
if (item is DevExpress.DashboardWin.Bars.FileNewBarItem) itemsToRemove.Add(item);
if (item is DevExpress.DashboardWin.Bars.InsertTreemapBarItem) itemsToRemove.Add(item);
}
foreach (BarItem item in itemsToRemove)
ribbonControl.Items.Remove(item);
}
}
}
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Ribbon
Imports System.Collections.Generic
Namespace DXDashboardApp
Public Partial Class DesignerForm1
Inherits DevExpress.XtraBars.Ribbon.RibbonForm
Public Sub New()
InitializeComponent()
dashboardDesigner.CreateRibbon()
RemoveBarItems(dashboardDesigner.Ribbon)
End Sub
Private Sub RemoveBarItems(ByVal ribbonControl As RibbonControl)
Dim itemsToRemove As List(Of BarItem) = New List(Of BarItem)()
For Each item As BarItem In ribbonControl.Items
If TypeOf item Is DevExpress.DashboardWin.Bars.FileSaveAsBarItem Then itemsToRemove.Add(item)
If TypeOf item Is DevExpress.DashboardWin.Bars.FileOpenBarItem Then itemsToRemove.Add(item)
If TypeOf item Is DevExpress.DashboardWin.Bars.FileNewBarItem Then itemsToRemove.Add(item)
If TypeOf item Is DevExpress.DashboardWin.Bars.InsertTreemapBarItem Then itemsToRemove.Add(item)
Next
For Each item As BarItem In itemsToRemove
ribbonControl.Items.Remove(item)
Next
End Sub
End Class
End Namespace
See Also