Order of Events in the WinForms Viewer

• Sep 28, 2018
• 5 minutes to read

The process of loading/using a dashboard in the WinForms Viewer can be divided into the following steps.

• 1. Loading a Dashboard
• 2. Providing Data
• 3. Setting Up a Filter State
• 4. Customizing a Dashboard/Dashboard Items
• 5. Customizing Underlying Controls
• 6. Using a Dashboard

This topic describes the events that are raised during each operation.

1. Loading a Dashboard

The following table shows the events related to initial dashboard loading.

Event	Description
DashboardViewer.DashboardLoaded	The DashboardViewer.DashboardLoaded is the first event which is raised when the dashboard is being loaded. You can use the DashboardLoadedEventArgs.Dashboard event parameter to customize the dashboard before it is loaded to the Dashboard Viewer.

2. Providing Data

The following table shows the order of events related to data binding.

Event	Description	Note
DashboardViewer.CustomParameters	The DashboardViewer.CustomParameters event is raised before the Dashboard Viewer sends a query to a database server and allows you to specify parameter settings (for instance, specify a parameter value).
DashboardViewer.ConfigureDataConnection	The DashboardViewer.ConfigureDataConnection event allows you to customize settings used to establish a connection to SQL databases, OLAP cubes or Excel Data Sources. Note Note that the DashboardViewer.DataLoading event is fired instead DashboardViewer.ConfigureDataConnection if the dashboard is supplied with data using the Object Data Source.	This event is raised if the dashboard is supplied with data using the SQL/OLAP/Excel data source.
DashboardViewer.ConnectionError	When current connection parameters do not allow you to connect to a data store (for instance, the server name is specified incorrectly), the DashboardViewer.ConnectionError event is raised. Handle the ConnectionError event and override the default behavior in this case.	This event is raised if the dashboard is supplied with data using the SQL/OLAP/Excel data source and the current connection parameters do not allow you to connect to a data store.
DashboardViewer.ValidateCustomSqlQuery	The DashboardViewer.ValidateCustomSqlQuery event allows you to check the validity of the custom SQL query used to supply the dashboard with data.	This event is raised each time the custom SQL query, which is used to supply the dashboard with data, needs to be validated. This is true if the SQL Data Source is used as a dashboard data source and the custom SQL query is used to select data.
DashboardViewer.CustomFilterExpression	The DashboardViewer.CustomFilterExpression event allows you to include WHERE clauses in SQL queries for SQL data sources.	This event is raised if the dashboard is supplied with data using the SQL data source.

3. Setting Up a Filter State

The following table describes the events related to default filter state of filter elements and master filter items.

Event	Description	Note
DashboardViewer.MasterFilterDefaultValues	The DashboardViewer.MasterFilterDefaultValues event allows you to apply default filtering to master filter items.
DashboardViewer.RangeFilterDefaultValue	The DashboardViewer.RangeFilterDefaultValue provides the capability to apply default filtering to a Range Filter dashboard item.	This event is raised if the dashboard contains a Range Filter dashboard item.

4. Customizing a Dashboard/Dashboard Items

The following table describes the events that allow you to customize a dashboard and dashboard items before the dashboard will be opened.

Event	Description	Note
DashboardViewer.DashboardItemElementCustomColor	The DashboardViewer.DashboardItemElementCustomColor event allows you to color the required dashboard item elements (for instance, chart series points, pie segments) using the specified colors.	This event is raised if the dashboard contains one of the following dashboard items. Chart Scatter Chart Pies Treemap
DashboardViewer.DashboardItemVisualInteractivity	The DashboardViewer.DashboardItemVisualInteractivity event allows you to provide custom visual interactivity for data-bound dashboard items that support element selection and highlighting.	This event is raised if the dashboard contains dashboard items that support element selection and highlighting.
DashboardViewer.CustomizeDashboardTitle	The DashboardViewer.CustomizeDashboardTitle event allows you to customize the content displayed within the dashboard title at runtime.
DashboardViewer.CustomizeDashboardItemCaption	The DashboardViewer.CustomizeDashboardItemCaption event allows you to customize the content displayed within the dashboard item caption at runtime.

5. Customizing Underlying Controls

If necessary, you can customize underlying controls used to visualize data within dashboard items using the following events.

Event	Description	Note
DashboardViewer.DashboardItemControlCreated	The DashboardViewer.DashboardItemControlCreated event allows you to access underlying WinForms controls. Handle this event to subscribe to events of the underlying control.	This event is raised if the dashboard contains specific items. To learn more, see Access to Underlying Controls.
DashboardViewer.DashboardItemControlUpdated	The DashboardViewer.DashboardItemControlUpdated event allows you to access underlying WinForms controls and change their settings	This event is raised if the dashboard contains specific items. To learn more, see Access to Underlying Controls.
DashboardViewer.DashboardItemBeforeControlDisposed	The DashboardViewer.DashboardItemBeforeControlDisposed event allows you to unsubscribe from events of the underlying control.	This event is raised if the dashboard contains specific items. To learn more, see Access to Underlying Controls.

6. Using a Dashboard

Note that the DashboardViewer.DashboardChanged event occurs after a dashboard has been opened.

The following table describes the events related to an end-user actions or corresponding API method calls.

Event	Description
DashboardViewer.MasterFilterSet DashboardViewer.MasterFilterCleared DashboardViewer.DashboardItemSelectionChanged	These events are raised when master filter/selection state is changed.
DashboardViewer.DrillDownPerformed DashboardViewer.DrillUpPerformed	These events are raised when drill down/drill up is performed.
DashboardViewer.DashboardItemClick DashboardViewer.DashboardItemDoubleClick DashboardViewer.DashboardItemMouseDown DashboardViewer.DashboardItemMouseUp DashboardViewer.DashboardItemMouseEnter DashboardViewer.DashboardItemMouseLeave DashboardViewer.DashboardItemMouseHover DashboardViewer.DashboardItemMouseMove	These events related to mouse actions performed by an end-user.
DashboardViewer.PopupMenuShowing	The DashboardViewer.PopupMenuShowing event allows you to customize a popup menu invoked by end-users.
DashboardViewer.LayoutChanged	The DashboardViewer.LayoutChanged event is raised after the dashboard layout is changed.