windowsforms-9578-controls-and-libraries-pivot-grid-asynchronous-mode.md
If the Pivot Grid operates with a large dataset, data-aware operations such as data retrieval, sorting, and filtering may take a long time. In synchronous mode, the entire application does not respond to user actions until the Pivot Grid completes the operations because the main UI thread is busy. Users may notice an application freeze.
In asynchronous mode, only the Pivot Grid is frozen. The application continues to respond to user actions while the control processes data in a background thread. The Pivot Grid displays a loading panel to indicate the control is busy. The control does not respond to user actions until the operation finishes.
The picture below demonstrates asynchronous operations – the window does not freeze and responds to user actions while the Pivot Grid recalculates the data.
PivotGridControl allows the application to stay responsive while the following asynchronous operations are running in the background thread:
After an asynchronous operation starts, the Pivot Grid executes the following actions:
After background calculations are finished, the Pivot Grid does the following:
You can specify how the Pivot Grid processes user actions - synchronously or asynchronously. Set the PivotGridOptionsBehaviorBase.UseAsyncMode property to true to enable asynchronous mode and make all operations initiated with the UI asynchronous.
The PivotGridControl.UserAction property indicates what operation the user executes.
In code, you can execute both synchronous and asynchronous operations, regardless of the UI settings. Use the following techniques to execute operations asynchronously:
Methods with the “Async” postfix All methods with the “Async” postfix are asynchronous. It means that they start operation in a background thread and return the control to the caller.The BeginUpdate – EndUpdateAsync method pair Enclose the code that should be executed asynchronously in the PivotGridControl.BeginUpdate – PivotGridControl.EndUpdateAsync method pair. To ensure that the changes apply in case of an exception, wrap it in a “try .. finally” statement.
The Pivot Grid allows you to call multiple asynchronous operations simultaneously. However, if you need to call asynchronous methods individually and wait for them to complete, use the PivotGridControl.IsAsyncInProgress property. This property determines whether an asynchronous operation is in progress.
Warning
You cannot start a data-aware operation in code while another operation runs in a background thread.
Refer to the following section for asynchronous methods for the Pivot Grid: Related API.
In asynchronous mode, custom painting events occur before the Pivot Grid is displayed. They are handled in the main thread while the Pivot Grid executes background calculations. This behavior applies to the following events:
For thread safety, you cannot directly access event data while an asynchronous operation is being executed. Otherwise, an exception is thrown.
When you handle custom painting events, use the Pivot Grid’s IThreadSafeAccessible.IsAsyncInProgress property to determine whether the Pivot Grid executes background calculations. If this property returns false, you can access event data. Otherwise, you should use the e.ThreadSafeArgs thread-safe event parameter to access event data.
The e.ThreadSafeArgs property gives read-only access to basic event parameter members and allows you to obtain event data when an asynchronous operation is in progress. Event parameter members that cannot be accessed during asynchronous operation do not have corresponding thread-safe event parameter members.
When you handle custom painting events, you cannot use PivotGridControl members to access Pivot Grid’s data. Use the IThreadSafeAccessible interface members implemented by the PivotGridControl class instead. They allow you to obtain field and group collections, as well as text displayed in a field value and data cells.
This section lists the Pivot Grid control’s methods that execute operations asynchronously.
Data Binding
PivotGridControl.RefreshDataAsyncReloads data from the control data source and recalculates summaries asynchronously.PivotGridControl.RetrieveFieldsAsyncCreates PivotGridField objects for all columns in a data source asynchronously.PivotGridControl.SetDataSourceAsyncSets the data source for the Pivot Grid control and loads data asynchronously.PivotGridControl.SetOLAPConnectionStringAsyncSets a connection string to a cube in an MS Analysis Services database, and loads data from the cube asynchronously.
Sorting
PivotGridControl.ChangeFieldSortOrderAsyncToggles the sort order of the specified field asynchronously.PivotGridControl.ClearFieldSortingAsyncClears field sorting asynchronously in OLAP mode.PivotGridControl.SetFieldSortingAsyncSets the sort order for the specified field asynchronously.
Layout Operations
PivotGridControl.ChangeFieldExpandedAsyncExpands or collapses all values of the specified Pivot Grid field asynchronously.PivotGridControl.CollapseAllAsyncCollapses all columns and rows in a Pivot Grid control asynchronously.PivotGridControl.CollapseAllColumnsAsyncCollapses all columns asynchronously.PivotGridControl.CollapseAllRowsAsyncCollapses all rows asynchronously.PivotGridControl.CollapseValueAsyncCollapses the specified column or row asynchronously.PivotGridControl.ExpandAllAsyncExpands all columns and rows in the Pivot Grid control asynchronously.PivotGridControl.ExpandAllColumnsAsyncExpands all columns asynchronously.PivotGridControl.ExpandAllRowsAsyncExpands all rows asynchronously.PivotGridControl.ExpandValueAsyncExpands the specified column or row asynchronously.
Drill-Down Operations
PivotGridControl.CreateDrillDownDataSourceAsyncReturns a list of records used to calculate a summary value for the specified cell asynchronously.
Control Update
PivotGridControl.EndUpdateAsyncUnlocks the Pivot Grid control after the PivotGridControl.BeginUpdate method call, and starts an asynchronous update.
The code snippet below shows how to create a drill-down data source for the selected Pivot Grid cell and display the resulting data source in the DrillDownForm dialog in asynchronous mode.
using DevExpress.XtraEditors;
using DevExpress.XtraPivotGrid;
using System;
using System.Windows.Forms;
namespace DxSampleOLAP {
public partial class OLAPDrillDownUserControl : XtraUserControl {
public OLAPDrillDownUserControl() {
InitializeComponent();
pivotGridControl.OptionsBehavior.UseAsyncMode = true;
// ...
pivotGridControl.CellDoubleClick += async (s, e) => {
try {
pivotGridControl.LoadingPanelVisible = true;
PivotDrillDownDataSource ds = await e.CreateDrillDownDataSourceAsync();
pivotGridControl.LoadingPanelVisible = false;
using(DrillDownForm form = new DrillDownForm(ds))
form.ShowDialog();
} catch(Exception ex) {
pivotGridControl.LoadingPanelVisible = false;
XtraMessageBox.Show(ex.Message);
}
};
}
}
}
Imports DevExpress.XtraEditors
Imports DevExpress.XtraPivotGrid
Imports System
Imports System.Windows.Forms
Namespace DxSampleOLAP
Partial Public Class OLAPDrillDownUserControl
Inherits XtraUserControl
Public Sub New()
InitializeComponent()
pivotGridControl.OptionsBehavior.UseAsyncMode = True
' ...
AddHandler pivotGridControl.CellDoubleClick, Async Sub(s, e)
Try
pivotGridControl.LoadingPanelVisible = True
Dim ds As PivotDrillDownDataSource = Await e.CreateDrillDownDataSourceAsync()
pivotGridControl.LoadingPanelVisible = False
Using form As New DrillDownForm(ds)
form.ShowDialog()
End Using
Catch ex As Exception
pivotGridControl.LoadingPanelVisible = False
XtraMessageBox.Show(ex.Message)
End Try
End Sub
End Sub
End Class
End Namespace