TdxDashboardControlResolveConnectionEvent Type

The procedural type for manual data connection resolution events in a TdxDashboardControl component.

Declaration

TdxDashboardControlResolveConnectionEvent = procedure(ASender: TdxCustomDashboardControl; const ADisplayName: string; var AConnection: TdxBackendCustomDataConnection) of object;

Parameters

Name	Type	Description
ASender	TdxCustomDashboardControl	Provides access to the Dashboard control that raised the data connection resolution event. Tip Cast the ASender parameter value to the TdxDashboardControl class to access all public API members.
ADisplayName	string	Returns the target data connection name (DisplayName) referenced in the current scope (Viewer or Designer).
AConnection	TdxBackendCustomDataConnection	Specifies the data connection component that corresponds to the currently processed data connection name (ADisplayName) within the current dashboard layout definition. The initial AConnection parameter value provides access to the automatically identified source data connection component for the ADisplayName value. You can use the AConnection parameter to manually select a specific connection component as the data source associated with the processed connection name (ADisplayName) for the current TdxDashboardControl component (ASender). Important ADisplayName and AConnection.DisplayName values must match. Otherwise, an exception is thrown. If you use the AConnection parameter to remap a display name to a different data connection component, assign the ADisplayName parameter value to the AConnection.DisplayName property within the event handler.

Remarks

The TdxDashboardControlResolveConnectionEvent procedural type is designed for manual data connection resolution in a TdxDashboardControl component when two or more data connection components share the same display name.

An application can contain multiple data connection components (TdxBackendCustomDataConnection descendants) with the same DisplayName property value used to address these components in a dashboard layout definition.

Automatic Data Connection Name Resolution

If the manual data connection resolution event is unhandled, the TdxDashboardControl component resolves data component display names automatically:

Unique Component Display Names

The TdxDashboardControl uses data connection components with corresponding display names as data sources.

Multiple Matching Component Display Names

The TdxDashboardControl component iterates through all data connection components and searches the first component with the target display name in the following order:

• On the same form as the TdxDashboardControl.
• On a data module (TDataModule descendant instance).
• Any other data connection with the same display name.

Manual Data Connection Name Resolution/Event Occurrence

The manual data connection resolution event occurs every time a TdxDashboardControl component is about to access available data sources (in the Viewer or Designer scope):

TdxDashboardControl | Dashboard Viewer

Viewer Scope. The manual data connection resolution event occurs when TdxDashboardControl/Dashboard Viewer populates or updates placeholders within the layout definition with data – once per data connection component referenced within the layout.

Dashboard Designer

Designer Scope. The manual data connection resolution event occurs once for each active (that is, available to the Dashboard Designer dialog) data connection component within the application.

In addition, you can assign nil (in Delphi) or nullptr (in C++Builder) to the AConnection parameter to hide the currently processed connection in the Dashboard Designer dialog.

You can assign a data connection component to the AConnection parameter within a TdxDashboardControlResolveConnectionEvent handler to manually map the component to the referred display name for the current data access/load operation.

Note

• The manual data connection resolution event occurs even if the application or template/layout definition contains only one active data connection component (or multiple data connection components with unique DisplayName property values).
• This event never occurs for inactive data access components.

Direct TdxDashboardControlResolveConnectionEvent Type Reference

The TdxCustomDashboardControl.OnResolveConnection event references the TdxDashboardControlResolveConnectionEvent procedural type.