dashboard-403128-winforms-dashboard-winforms-designer-ui-elements-and-customization-create-custom-properties-custom-funnel-item-legend-visibility.md
This topic describes how to use custom properties to add more functionality to a custom item. You can access a custom control that displays a custom item and manage the control’s settings in the Dashboard Designer UI.
This tutorial is based on a custom Funnel item. You will create a custom Boolean property that manages the Funnel legend’s visibility. For this, you add a button to the Ribbon to the Funnel item’s contextual page. You can show or hide the legend when you click the button.
To complete this tutorial you need to create a custom Funnel item first. Follow the step-by-step tutorial to create it: Create an Interactive Data-Aware Item.
You can also download the custom Funnel item’s source code in the TutorialsCustomItems project of the following example:
View Example: WinForms Dashboard - Custom Items
In the FunnelItemMetadata class, declare a public ShowLegend property with GetCustomPropertyValue<T>() and SetCustomPropertyValue(value) methods. Apply ShowLegendCustomAttribute to the ShowLegend property. The attribute implements the ICustomPropertyValueConverterAttribute<T> and ICustomPropertyHistoryAttribute<T> interfaces.
using DevExpress.DashboardCommon;
namespace TutorialsCustomItems {
public class FunnelItemMetadata : CustomItemMetadata {
// ...
[ShowLegendCustom]
public bool ShowLegend {
get { return GetCustomPropertyValue<bool>(); }
set { SetCustomPropertyValue(value); }
}
}
}
Imports DevExpress.DashboardCommon
Namespace TutorialsCustomItems
Public Class FunnelItemMetadata
Inherits CustomItemMetadata
' ...
<ShowLegendCustom>
Public Property ShowLegend() As Boolean
Get
Return GetCustomPropertyValue(Of Boolean)()
End Get
Set(ByVal value As Boolean)
SetCustomPropertyValue(value)
End Set
End Property
End Class
End Namespace
Generate the public ShowLegendCustomAttribute class that implements the ICustomPropertyValueConverterAttribute<T> and ICustomPropertyHistoryAttribute<T> interfaces.
ICustomPropertyValueConverterAttribute<T> Exposes the following methods that convert a custom property value from its original type to a string and vice versa: ConvertToString and ConvertFromString.ICustomPropertyHistoryAttribute<T> Returns the message displayed in the Dashboard Designer’s history when a user changes the custom property value. You can undo/redo this action like other user actions. Call the GetHistoryMessage method and pass a string as a parameter to define this history message.
using DevExpress.DashboardCommon;
namespace TutorialsCustomItems {
public class FunnelItemMetadata : CustomItemMetadata {
// ...
public class ShowLegendCustomAttribute : Attribute, ICustomPropertyValueConverterAttribute<bool>, ICustomPropertyHistoryAttribute<bool>{
public string ConvertToString(bool value){
return value.ToString();
}
public bool ConvertFromString(string strValue){
bool result;
Boolean.TryParse(strValue, out result);
return result;
}
public string GetHistoryMessage(bool newValue, bool oldValue, string dashboardItemName){
return (newValue ? "Enable" : "Disable") + " Legend for the " + dashboardItemName;
}
}
}
}
Imports DevExpress.DashboardCommon
Namespace TutorialsCustomItems
Public Class FunnelItemMetadata
Inherits CustomItemMetadata
' ...
Public Class ShowLegendCustomAttribute
Inherits Attribute
Implements ICustomPropertyValueConverterAttribute(Of Boolean), ICustomPropertyHistoryAttribute(Of Boolean)
Public Function ConvertToString(ByVal value As Boolean) As String
Return value.ToString()
End Function
Public Function ConvertFromString(ByVal strValue As String) As Boolean
Dim result As Boolean = Nothing
Boolean.TryParse(strValue, result)
Return result
End Function
Public Function GetHistoryMessage(ByVal newValue As Boolean, ByVal oldValue As Boolean, ByVal dashboardItemName As String) As String
Return (If(newValue, "Enable", "Disable")) & " Legend for the " & dashboardItemName
End Function
End Class
End Class
End Namespace
In the FunnelItemControlProvider class, update the custom control according to the ShowLegend property’s value in the CustomControlProviderBase.UpdateControl(CustomItemData) method:
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
using DevExpress.XtraCharts;
namespace TutorialsCustomItems {
public class FunnelItemControlProvider : CustomControlProviderBase {
ChartControl chart;
// ...
protected override void UpdateControl(CustomItemData customItemData){
// ...
chart.Legend.Visibility = dashboardItem.Metadata.ShowLegend ? DevExpress.Utils.DefaultBoolean.True : DevExpress.Utils.DefaultBoolean.False;
}
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.XtraCharts
Namespace TutorialsCustomItems
Public Class FunnelItemControlProvider
Inherits CustomControlProviderBase
Private chart As ChartControl
' ...
Protected Overrides Sub UpdateControl(ByVal customItemData As CustomItemData)
' ...
chart.Legend.Visibility = If(dashboardItem.Metadata.ShowLegend, DevExpress.Utils.DefaultBoolean.True, DevExpress.Utils.DefaultBoolean.False)
End Sub
End Class
End Namespace
Create the FunnelItemDesignerModule class and add it to the CustomItems folder that you created earlier. The class adds a button to the Ribbon for custom items of the FunnelItemMetadata type. The AttachDesigner and DetachDesigner methods subscribe to and unsubscribe from events used for button customization.
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
using DevExpress.Utils.Svg;
using DevExpress.XtraBars;
using DevExpress.XtraBars.Ribbon;
using System;
namespace TutorialsCustomItems {
public class FunnelItemDesignerModule {
BarCheckItem showLegendItem;
public DashboardDesigner DashboardDesigner { get; set; }
public CustomDashboardItem<FunnelItemMetadata> SelectedCustomItem => DashboardDesigner.SelectedDashboardItem as CustomDashboardItem<FunnelItemMetadata>;
public FunnelItemDesignerModule(){
}
public void AttachDesigner(DashboardDesigner dashboardDesigner){
DashboardDesigner = dashboardDesigner;
DashboardDesigner.DashboardCustomPropertyChanged += UpdateBarsEventHandler;
DashboardDesigner.DashboardItemSelected += UpdateBarsEventHandler;
InitializeBarItems();
}
public void DetachDesigner(){
DashboardDesigner.DashboardCustomPropertyChanged -= UpdateBarsEventHandler;
DashboardDesigner.DashboardItemSelected -= UpdateBarsEventHandler;
DashboardDesigner = null;
showLegendItem.Dispose();
}
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.Utils.Svg
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Ribbon
Imports System
Namespace TutorialsCustomItems
Public Class FunnelItemDesignerModule
Private showLegendItem As BarCheckItem
Public Property DashboardDesigner() As DashboardDesigner
Public ReadOnly Property SelectedCustomItem() As CustomDashboardItem(Of FunnelItemMetadata)
Get
Return TryCast(DashboardDesigner.SelectedDashboardItem, CustomDashboardItem(Of FunnelItemMetadata))
End Get
End Property
Public Sub New()
End Sub
Public Sub AttachDesigner(ByVal dashboardDesigner As DashboardDesigner)
Me.DashboardDesigner = dashboardDesigner
Me.DashboardDesigner.DashboardCustomPropertyChanged += UpdateBarsEventHandler
Me.DashboardDesigner.DashboardItemSelected += UpdateBarsEventHandler
InitializeBarItems()
End Sub
Public Sub DetachDesigner()
DashboardDesigner.DashboardCustomPropertyChanged -= UpdateBarsEventHandler
DashboardDesigner.DashboardItemSelected -= UpdateBarsEventHandler
DashboardDesigner = Nothing
showLegendItem.Dispose()
End Sub
End Class
End Namespace
The InitializeBarItems method adds the ShowLegend button to the Ribbon. UpdateBarsEventHandler updates the button’s checked state according to the property’s value. For the button’s icon, you can use the SVG ChartShowLegend image from the example: WinForms Dashboard - Custom Items. Make sure the SVG file’s Build Action property is set to Embedded Resource.
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
using DevExpress.Utils.Svg;
using DevExpress.XtraBars;
using DevExpress.XtraBars.Ribbon;
using System;
namespace TutorialsCustomItems {
public class FunnelItemDesignerModule {
void UpdateBarsEventHandler(object sender, EventArgs e){
if (SelectedCustomItem != null){
showLegendItem.Checked = SelectedCustomItem.Metadata.ShowLegend;
}
}
void InitializeBarItems(){
RibbonPage page = DashboardDesigner.Ribbon.GetDashboardRibbonPage(typeof(FunnelItemMetadata), DashboardRibbonPage.Design);
RibbonPageGroup group = page.GetGroupByName("Custom Properties");
if (group == null){
group = new RibbonPageGroup("Custom Properties") { Name = "Custom Properties" };
page.Groups.Add(group);
group.AllowTextClipping = false;
}
showLegendItem = new BarCheckItem(DashboardDesigner.Ribbon.Manager);
showLegendItem.ImageOptions.SvgImage = SvgImage.FromResources("TutorialsCustomItems.Images.ChartShowLegend.svg", this.GetType().Assembly);
showLegendItem.Caption = "Show Legend";
showLegendItem.ItemClick += (s, e) =>
{
if (SelectedCustomItem != null)
SelectedCustomItem.Metadata.ShowLegend = !SelectedCustomItem.Metadata.ShowLegend;
};
group.ItemLinks.Add(showLegendItem);
}
}
}
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.Utils.Svg
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Ribbon
Imports System
Namespace TutorialsCustomItems
Public Class FunnelItemDesignerModule
Private Sub UpdateBarsEventHandler(ByVal sender As Object, ByVal e As EventArgs)
If SelectedCustomItem IsNot Nothing Then
showLegendItem.Checked = SelectedCustomItem.Metadata.ShowLegend
End If
End Sub
Private Sub InitializeBarItems()
Dim page As RibbonPage = DashboardDesigner.Ribbon.GetDashboardRibbonPage(GetType(FunnelItemMetadata), 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)
group.AllowTextClipping = False
End If
showLegendItem = New BarCheckItem(DashboardDesigner.Ribbon.Manager)
showLegendItem.ImageOptions.SvgImage = SvgImage.FromResources("ChartShowLegend.svg", Me.GetType().Assembly)
showLegendItem.Caption = "Show Legend"
AddHandler showLegendItem.ItemClick, Sub(s, e)
If SelectedCustomItem IsNot Nothing Then
SelectedCustomItem.Metadata.ShowLegend = Not SelectedCustomItem.Metadata.ShowLegend
End If
End Sub
group.ItemLinks.Add(showLegendItem)
End Sub
End Class
End Namespace
Attach FunnelItemDesignerModule to the Dashboard Designer:
using System.Windows.Forms;
using TutorialsCustomItems.CustomItems;
namespace TutorialsCustomItems {
public partial class Form1 : Form {
FunnelItemDesignerModule customFunnelDesignerModule;
public Form1(){
InitializeComponent();
dashboardDesigner1.CreateRibbon();
dashboardDesigner1.CreateCustomItemsBars();
customFunnelDesignerModule = new FunnelItemDesignerModule();
customFunnelDesignerModule.AttachDesigner(dashboardDesigner1);
dashboardDesigner1.LoadDashboard(@"..\..\Data\TutorialCustomItems.xml");
}
// ...
}
}
Imports System.Windows.Forms
Imports TutorialsCustomItems.CustomItems
Namespace TutorialsCustomItems
Partial Public Class Form1
Inherits Form
Dim customFunnelDesignerModule As FunnelItemDesignerModule
Public Sub New()
InitializeComponent()
dashboardDesigner1.CreateRibbon()
dashboardDesigner1.CreateCustomItemsBars()
customFunnelDesignerModule = New FunnelItemDesignerModule()
customFunnelDesignerModule.AttachDesigner(dashboardDesigner1)
dashboardDesigner1.LoadDashboard("..\..\Data\TutorialCustomItems.xml")
End Sub
' ...
End Class
End Namespace
The ShowLegend button appears on the Ribbon’s Design page once you have loaded a dashboard. The button switches the legend visibility for each selected custom Funnel item in the dashboard. The action history stores information on the ShowLegend property state, so you can undo or reapply this action later.
Click the button to show or hide the legend for the selected custom Funnel item in a dashboard: