Manage Dashboard Parameters

  • 3 minutes to read

The DashboardViewer provides a built-in Dashboard Parameters dialog, providing the capability to change dashboard parameter values. This dialog is created automatically, depending on the parameter type and visibility settings.

Standard Parameter Editor

To invoke the Dashboard Parameters dialog in the DashboardViewer, click the Parameters button (the Parameters_ParametersButtonWin_Title icon) in the dashboard title.

Parameters_DashboardParametersDialog_Win

Select the required parameter values in the Dashboard Parameters dialog and click the Submit button to apply the changes. To reset changes to the default values, click the Reset button.

To invoke this dialog in code, use the DashboardViewer.ShowDashboardParametersForm method.

Change Parameter Values in Code

You can change dashboard parameter values in the DashboardViewer using the DashboardViewer.Parameters property.

The DashboardViewer.Parameters property returns the DashboardParameterDescriptor class objects that allow you to obtain the parameter type, the default parameter value, the parameter name settings, etc. For instance, you can forcibly change a parameter value when an end user changes this value in the Dashboard Parameters dialog.

Member Description
DashboardWin.DashboardParameterDescriptor Contains the parameter settings and metadata.
DashboardParameterDescriptor.DefaultValue Gets the default parameter value.
DashboardParameterDescriptor.Type Gets a parameter type.
DashboardParameterDescriptor.Name Gets a parameter name.
DashboardParameterDescriptor.Values Gets possible parameter values.
DashboardParameterDescriptor.Value Obsolete. Gets or sets the current 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();

The DashboardViewer also provides the DashboardViewer.CustomParameters event that allows you to change dashboard parameter values at runtime. For instance, you can forcibly change a parameter value when an end user changes this value in the Dashboard Parameters dialog.

Manage Parameters in the Dashboard State

A dashboard state allows you to set parameters values. The DashboardState.Parameters property provides access to dashboard parameters.

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;
}

See Manage the Dashboard State for more information.

See Also