TdxDashboardParameters Class

Declaration

TdxDashboardParameters = class(
    TdxBackendCustomParameters<TdxDashboardParameter>
)

Remarks

Dashboard parameters are dynamic values that can replace constants in filter criteria, expressions, and calculated fields. The TdxDashboardParameters class implements a collection of dashboard parameters.

The TdxReportParameters collection is automatically populated and updated from the current dashboard layout definition. The list of parameter is read-only. You can only access and modify parameter properties.

Main API Members

The list below outlines key members of the TdxDashboardParameters class. These members allow you to access and modify parameters in a dashboard:

BeginUpdate | EndUpdate: Allow you to avoid excessive notifications and improve performance during batch changes.

Tip
Every individual dashboard parameter change updates the parent dashboard’s State property value. Enclose multiple dashboard parameter changes between BeginUpdate and EndUpdate calls to avoid excessive state updates.
Count: Returns the number of parameters stored in the collection.
FindParam: Returns the stored parameter with the specified name or returns nil / nullptr if the collection does not contain the target parameter. Use this method to safely search for a parameter that may not exist.
Items: Returns the stored parameter by its index in the collection.
ParamByName: Returns the stored parameter with the specified name or raises an exception if the collection does not contain the target parameter.
Note
You can omit ParamByName and use only the parameter name in square brackets (for example, dxControl1.Parameters['ParameterName'] instead of dxControl1.Parameters.ParamByName['ParameterName']).

Code Examples

uses
  dxDashboard.Control,      // Declares the TdxDashboardControl class
  dxDashboard.Parameters,   // Declares the TdxDashboardParameter class
  dxMessageDialog,          // Declares the TdxMessageDialogForm class
  System.StrUtils;          // Provides advanced string management routines

procedure TForm1.cxButton1Click(Sender: TObject);
var
  AList: TStringList;
  AParameter: TdxDashboardParameter;
begin
  // Create a TStringList instance
  AList := TStringList.Create;
  try
    // Iterate through dashboard parameters
    for AParameter in dxDashboardControl1.Parameters do
      AList.Add(Format('- %s', [
        // Use the parameter Name if Description is missing
        IfThen(AParameter.Description <> '', AParameter.Description, AParameter.Name)
      ]));
    // Display the parameter list or a notification message if the list is empty
    if AList.Count > 0 then
      dxShowMessage(AList.Text)
    else
      dxShowMessage('The dashboard has no parameters.');
  finally
    AList.Free;
  end;
end;

#include "dxDashboard.Control.hpp"      // Declares the TdxDashboardControl class
#include "dxDashboard.Parameters.hpp"   // Declares the TdxDashboardParameter class
#include "dxMessageDialog.hpp"          // Declares the TdxMessageDialogForm class

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxDashboard.Control"   // Required to use dxDashboard.Control.hpp declarations

void __fastcall TForm1::cxButton1Click(TObject* Sender) {
  TStringList* AList = new TStringList();
  try {
    // Iterate through dashboard parameters
    for (int i = 0; i < dxDashboardControl1->Parameters->Count; i++) {
      TdxDashboardParameter* AParameter = dxDashboardControl1->Parameters->Items[i];
      UnicodeString ALabel;
      // Use the parameter Name if Description is missing
      if (AParameter->Description.IsEmpty())
        ALabel = AParameter->Name;
      else
        ALabel = AParameter->Description;
      AList->Add(Format(L"- %s", ARRAYOFCONST((ALabel))));
    }
    // Display the parameter list or a notification message if the list is empty
    if (AList->Count > 0)
      dxShowMessage(AList->Text);
    else
      dxShowMessage(L"The dashboard has no parameters.");
  }
  __finally {
    delete AList;
  }
}

View Example: Pass a Hidden Dashboard Parameter to a SQL Query