Custom Funnel Item - Legend Visibility
- 6 minutes to read
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.
Prerequisites
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:
Create a Custom Property
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); }
}
}
}
Implement Interfaces
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;
}
}
}
}
Update a Custom Control
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;
}
}
}
Create a Button
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();
}
}
}
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);
}
}
}
Attach the Module
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");
}
// ...
}
}
Result
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:
