dashboard-17632-winforms-dashboard-winforms-viewer-manage-dashboard-parameters.md
This topic describes how to specify dashboard parameter values in the UI and in code in the Dashboard Viewer.
The DashboardViewer includes a built-in Dashboard Parameters dialog, which allows users to change dashboard parameter values. This dialog is created automatically depending on the parameter settings. Set the Visible property to true to display the parameter in the Dashboard Parameters dialog.
To invoke the Dashboard Parameters dialog in the DashboardViewer, click the Parameters button in the dashboard title. Change the parameter values in the Dashboard Parameters dialog and click the Submit button to apply the changes.
The following image shows how to invoke the Dashboard Parameters dialog and change the parameter value:
To reset changes to the default values, click the Reset button.
To invoke this dialog in code, use the DashboardViewer.ShowDashboardParametersForm method.
You can create dashboard parameters and specify parameter settings in the Dashboard Viewer.
Use the Dashboard.Parameters property of Dashboard to access a collection of dashboard parameters.
To add a new dashboard parameter in code, create a parameter with the required settings and add it to the collection of dashboard parameters:
Dashboard dashboard = new Dashboard();
dashboard.LoadFromXml(@"Dashboards\dashboard1.xml");
DashboardParameter parameter = new DashboardParameter("CategoryName", typeof(string), "Beverages");
dashboard.Parameters.Add(parameter);
Dim dashboard As New Dashboard()
dashboard.LoadFromXml("Dashboards\dashboard1.xml")
Dim parameter As New DashboardParameter("CategoryName", GetType(String), "Beverages")
dashboard.Parameters.Add(parameter)
The following code snippets show how to create dashboard parameters with different look-up settings.
No Look-Up
DashboardParameter parameter1 = new DashboardParameter("Parameter1", typeof(string), "Beverages", "Select a category:", true, null);
Dim parameter1 As New DashboardParameter("Parameter1", GetType(String), "Beverages", "Select a category:", True, Nothing)
Static List
Use the StaticListLookUpSettings.Values property to specify the list of static values for the dashboard parameter.
StaticListLookUpSettings settings = new StaticListLookUpSettings();
settings.Values = new string[] {"Beverages", "Condiments"};
DashboardParameter parameter2 = new DashboardParameter("Parameter2", typeof(string), "Beverages", "Select a category:", true, settings);
Dim settings As New StaticListLookUpSettings()
settings.Values = New String() {"Beverages", "Condiments"}
Dim parameter2 As New DashboardParameter("Parameter2", GetType(String), "Beverages", "Select a category:", True, settings)
Dynamic List
Use the DynamicListLookUpSettings.DataSource property to specify the data source for the dashboard parameter. Specify the required settings for the dashboard parameter.
DynamicListLookUpSettings settings = new DynamicListLookUpSettings();
settings.DataSource = sqlDataSource;
settings.DataMember = "Categories";
settings.ValueMember = "CategoryID";
settings.DisplayMember = "CategoryName";
settings.SortOrder = DimensionSortOrder.Descending;
DashboardParameter parameter3 = new DashboardParameter("Parameter3", typeof(string), "1", "Select a category:", true, settings);
Dim settings As New DynamicListLookUpSettings()
settings.DataSource = sqlDataSource
settings.DataMember = "Categories"
settings.ValueMember = "CategoryID"
settings.DisplayMember = "CategoryName"
settings.SortOrder = DimensionSortOrder.Descending
Dim parameter3 As New DashboardParameter("Parameter3", GetType(String), "1", "Select a category:", True, settings)
Refer to the following article for information on where dashboard parameters can be used: Reference Dashboard Parameters in WinForms.
Use the DashboardViewer.Parameters property to access dashboard parameters in the DashboardViewer.
The DashboardViewer.Parameters property returns the DashboardParameterDescriptor class objects that allow you to obtain the parameter settings (the type, the default parameter value, the parameter name settings, etc.).
Use the following properties to work with dashboard parameters:
DashboardWin.DashboardParameterDescriptorContains the parameter settings and metadata.DashboardParameterDescriptor.DefaultValueGets the default parameter value.DashboardParameterDescriptor.TypeGets the parameter type.DashboardParameterDescriptor.NameGets the parameter name.DashboardParameterDescriptor.ValuesGets possible parameter values.DashboardParameterDescriptor.SelectedValuesGets or sets a collection of currently selected parameter values.DashboardParameterDescriptor.SelectedValueGets or sets the currently selected parameter value.DashboardViewer.BeginUpdateParameters()Locks the DashboardParameters object until the DashboardViewer.EndUpdateParameters method call.DashboardViewer.EndUpdateParameters()Unlocks the DashboardParameters object after a call to the DashboardViewer.BeginUpdateParameters method and applies changes made to the parameter settings.
The code snippet below shows how to specify values of DateTime parameters using the DashboardViewer API.
dashboardViewer1.BeginUpdateParameters();
dashboardViewer1.Parameters["fromDate"].Value = new DateTime(2015, 4, 1);
dashboardViewer1.Parameters["toDate"].Value = new DateTime(2015, 10, 1);
dashboardViewer1.EndUpdateParameters();
dashboardViewer1.BeginUpdateParameters()
dashboardViewer1.Parameters("fromDate").Value = New DateTime(2015, 4, 1)
dashboardViewer1.Parameters("toDate").Value = New DateTime(2015, 10, 1)
dashboardViewer1.EndUpdateParameters()
Use the DashboardViewer.CustomParameters event to change the dashboard parameter value or add new dashboard parameters before they are passed to the query.
The code sample below shows how to change the countryParameter parameter value before it is passed to the query:
private void DashboardViewer_CustomParameters(object sender, CustomParametersEventArgs e) {
// The countryParameter parameter value is changed to `Brazil`.
var countryParam = e.Parameters.FirstOrDefault(p => p.Name == "countryParameter");
if (countryParam != null) {
countryParam.Value = "Brazil";
}
}
Private Sub DashboardViewer_CustomParameters(ByVal sender As Object, ByVal e As CustomParametersEventArgs)
' The countryParameter parameter value is changed to `Brazil`.
Dim countryParam = e.Parameters.FirstOrDefault(Function(p) p.Name = "countryParameter")
If countryParam IsNot Nothing Then
countryParam.Value = "Brazil"
End If
End Sub
Note that the value specified in the event handler is not displayed in the Dashboard Parameters dialog.
The following code sample shows how to add a new dashboard parameter (countryParameter) and specify its value:
private void DashboardViewer_CustomParameters(object sender, CustomParametersEventArgs e) {
// A new dashboard parameter is created with its value set to the `Brazil` string.
e.Parameters.Add(new DashboardParameter("countryParameter", typeof(string), "Brazil"));
}
Private Sub DashboardViewer_CustomParameters(ByVal sender As Object, ByVal e As CustomParametersEventArgs)
' A new dashboard parameter is created with its value set to the `Brazil` string.
e.Parameters.Add(New DashboardParameter("countryParameter", GetType(String), "Brazil"))
End Sub
Note that the parameter added in the event handler is not displayed in the Dashboard Parameters dialog.
You can also specify the parameter value at runtime in the dashboard state. The value specified in the dashboard state is displayed in the Dashboard Parameters dialog and can be changed by a user.
The following example shows how to override an initial or user-defined dashboard parameter value by changing it in the CustomParameters event handler.
View Example: How to manage dashboard parameters in code
A dashboard state stores the changes resulting from user interactions - selected master filter values, drill-down levels, selected dashboard item layers, and current parameter values. Use the DashboardState.Parameters property to access dashboard parameters.
Refer to the following article for more information: Manage the Dashboard State.
The following example shows how to specify default parameter values when a dashboard is loading.
To do this, handle the DashboardViewer.SetInitialDashboardState event. Create a DashboardParameterState instance and use its Name and Value properties to configure parameter settings. Create a DashboardState object and add the specified dashboard parameter to the DashboardState.Parameters collection. Assign the created DashboardState object to the SetInitialDashboardStateBaseEventArgs.InitialState property to apply specified parameter values when a dashboard is loading.
using System.Collections.Generic;
using DevExpress.DashboardCommon;
using DevExpress.DashboardWin;
using DevExpress.DataAccess.ConnectionParameters;
namespace WinViewer_DefaultParameterValues {
public partial class Form1 : DevExpress.XtraEditors.XtraForm {
public Form1() {
InitializeComponent();
}
private void dashboardViewer1_SetInitialDashboardState(object sender, SetInitialDashboardStateEventArgs e) {
DashboardState state = new DashboardState();
DashboardParameterState parameters = new DashboardParameterState();
parameters.Name = "customerIdParameter";
parameters.Value = new List<string>() { "ALFKI", "AROUT", "BONAP" };
state.Parameters.Add(parameters);
e.InitialState = state;
}
private void dashboardViewer1_ConfigureDataConnection(object sender, DashboardConfigureDataConnectionEventArgs e) {
if (e.DataSourceName == "SQL Data Source 1")
e.ConnectionParameters = new Access97ConnectionParameters(@"..\..\Data\nwind.mdb", "", "");
}
}
}
Imports System.Collections.Generic
Imports DevExpress.DashboardCommon
Imports DevExpress.DashboardWin
Imports DevExpress.DataAccess.ConnectionParameters
Namespace WinViewer_DefaultParameterValues
Partial Public Class Form1
Inherits DevExpress.XtraEditors.XtraForm
Public Sub New()
InitializeComponent()
End Sub
Private Sub dashboardViewer1_SetInitialDashboardState(ByVal sender As Object, ByVal e As SetInitialDashboardStateEventArgs)
Dim state As New DashboardState()
Dim parameters As New DashboardParameterState()
parameters.Name = "customerIdParameter"
parameters.Value = New List(Of String)() From {"ALFKI", "AROUT", "BONAP"}
state.Parameters.Add(parameters)
e.InitialState = state
End Sub
Private Sub dashboardViewer1_ConfigureDataConnection(ByVal sender As Object, ByVal e As DashboardConfigureDataConnectionEventArgs) Handles dashboardViewer1.ConfigureDataConnection
If e.DataSourceName = "SQL Data Source 1" Then
e.ConnectionParameters = New Access97ConnectionParameters("..\..\Data\nwind.mdb", "", "")
End If
End Sub
End Class
End Namespace
View Example: How to Save and Restore the Dashboard State
The following code snippet shows the CreateDashboardState method that adds parameter values to a dashboard state.
The DashboardState object contains states of individual dashboard items and currently selected parameter values. To add a parameter state to the entire dashboard state, use the DashboardState.Parameters property. The DashboardDesigner.SetDashboardState method applies the dashboard state to the loaded dashboard.
using DevExpress.DashboardCommon;
//...
public DashboardState CreateDashboardState() {
DashboardState state = new DashboardState();
//...
state.Parameters.Add(new DashboardParameterState() {
Name = "ParameterCountry",
Value = "UK",
Type = typeof(string)
});
return state;
}
Imports DevExpress.DashboardCommon
'...
Public Function CreateDashboardState() As DashboardState
Dim state As New DashboardState()
'...
state.Parameters.Add(New DashboardParameterState() With {.Name = "ParameterCountry", .Value = "UK", .Type = GetType(String)})
Return state
End Function
See Also
Create a Dashboard Parameter in the WinForms Designer