PivotGridControl.CreateDrillDownDataSourceAsync(Int32, Int32, List<String>, AsyncCompletedHandler) Method

Returns a list of records used to calculate a summary value for the specified cell asynchronously. Allows you to specify the additional columns to return in (server mode) or returned columns in (OLAP mode).

Namespace: DevExpress.XtraPivotGrid

Assembly: DevExpress.XtraPivotGrid.v19.1.dll

Declaration

C#

public void CreateDrillDownDataSourceAsync(
    int columnIndex,
    int rowIndex,
    List<string> customColumns,
    AsyncCompletedHandler asyncCompleted
)

VB.NET

Public Sub CreateDrillDownDataSourceAsync(
    columnIndex As Integer,
    rowIndex As Integer,
    customColumns As List(Of String),
    asyncCompleted As AsyncCompletedHandler
)

Parameters

Name	Type	Description
columnIndex	Int32	A zero-based integer which identifies the visible index of the column. Pass -1 as a column index to obtain the column’s Grand Total.
rowIndex	Int32	A zero-based integer which identifies the visible index of the row. Pass -1 as a row index to obtain the row’s Grand Total.
customColumns	List<String>	The parameter is in effect in server and OLAP modes. It specifies a list of columns to return in addition to visible columns (server mode) or the list of columns to return (OLAP mode).
asyncCompleted	AsyncCompletedHandler	A AsyncCompletedHandler delegate that references a method to be called when the operation is completed. The drill-down data source is passed to this method as a parameter.

Remarks

Important

The customColumns parameter is in effect in Server and OLAP modes only; otherwise, it is ignored.

The CreateDrillDownDataSourceAsync method is asynchronous. It starts executing the related operation in a background thread, and immediately returns control. The primary UI thread is not blocked, allowing the application to continue responding to end-user actions. For more information about the asynchronous mode, see Asynchronous Mode.

The drill-down data source (a PivotDrillDownDataSource instance) is passed to the asyncCompleted delegate via the result parameter. This parameter returns an AsyncOperationResult instance. Use the AsyncOperationResult.Value property to obtain the drill-down data source.

If you use the CreateDrillDownDataSourceAsync method in OLAP, take note of the following limitations:

• For MS SQL Server Analysis Services 2000, the customColumns parameter is ignored. In this instance, the CreateDrillDownDataSourceAsync method returns the granularity attributes.
• A note for MS SQL Server Analysis Services 2005 and 2008. If the customColumns list is null or empty, the CreateDrillDownDataSourceAsync method returns the columns corresponding to the current column, row and data PivotGrid fields. In addition, it returns filter fields if a filter is applied to them. Otherwise, it returns the columns specified by the customColumns list.
• If a filter is applied to a field, then that filter is taken into account if the corresponding drill-down column was returned from the server by the CreateDrillDownDataSourceAsync method.
• The CreateDrillDownDataSourceAsync method is not supported for cells corresponding to calculated measures.
• If multiple filter items are selected in a Filter Field, the drill-down data source cannot be created due to an MS SQL Server Analysis Services limitation. In this instance, the CreateDrillDownDataSourceAsync method throws an exception.

In server and OLAP modes, the CreateDrillDownDataSourceAsync method returns only visible fields if the customColumns parameter is set to null.

Example

This example performs an asynchronous operation that creates a drill-down data source for the selected PivotGrid cell and gets the operation result - the underlying data source.

In this example, the PivotGrid control is bound to the LinqServerModeSource data source and operates in server mode.

The PivotGridControl.CellClick event handler calls the PivotGridControl.CreateDrillDownDataSourceAsync method to generate a drill-down data source for the selected cell. The method parameter specifies the number of records to return. The method also specifies the columns to add to the the data set.

The last item in the method’s parameter list is the AsyncCompletedHandler delegate. The delegate is executed when the operation is complete. The delegate’s result parameter is the AsyncOperationResult instance whose Value property contains the result of the operation.

The operation’s result is cast to the PivotDrillDownDataSource and the GridControl displays the underlying records in the auxiliary DrillDown form.

Note

The complete sample project How to Create the Underlying Data Source (Drill-Down) in an Asynchronous Operation is available in the DevExpress Examples repository.

C#

using DevExpress.XtraPivotGrid;
using System;
using System.Collections.Generic;

namespace XtraPivotGrid_CreateDrillDownDataSourceAsync {
    public partial class Form1 : DevExpress.XtraEditors.XtraForm
    {
        DrillDownForm dForm;
        public Form1()
        {
            InitializeComponent();
            this.Load += Form1_Load;
            pivotGridControl1.CellClick += pivotGridControl1_CellClick;
            // This line of code is generated by Data Source Configuration Wizard
            linqServerModeSource1.QueryableSource = new XtraPivotGrid_CreateDrillDownDataSourceAsync.DataClasses1DataContext().Invoices;
        }
        private void pivotGridControl1_CellClick(object sender, 
            DevExpress.XtraPivotGrid.PivotCellEventArgs e) {
            PivotGridControl pivot = sender as PivotGridControl;
            if (dForm.IsDisposed) LoadDrillDownForm();

            //Check whether an asynchronous operation is in progress.
            if (!pivot.IsAsyncInProgress)

                // Get the record set associated with the clicked cell.
                pivot.CreateDrillDownDataSourceAsync(e.ColumnIndex, e.RowIndex, 25, new List<string> { "ProductName","Quantity" }, result => {
                    // The 'result' parameter of the delegate returns an AsyncOperationResult instance.
                    // The AsyncOperationResult.Value property contains a record set.
                    dForm.DataSource = (PivotDrillDownDataSource)result.Value;
                });
        }
        private void Form1_Load(object sender, EventArgs e)
        {
            LoadDrillDownForm();
        }
        private void LoadDrillDownForm()
        {
            dForm = new DrillDownForm();
            dForm.Show();
        }
    }
}

VB.NET

Imports DevExpress.XtraPivotGrid
Imports System
Imports System.Collections.Generic

Namespace XtraPivotGrid_CreateDrillDownDataSourceAsync
    Partial Public Class Form1
        Inherits DevExpress.XtraEditors.XtraForm

        Private dForm As DrillDownForm
        Public Sub New()
            InitializeComponent()
            AddHandler Me.Load, AddressOf Form1_Load
            AddHandler pivotGridControl1.CellClick, AddressOf pivotGridControl1_CellClick
            ' This line of code is generated by Data Source Configuration Wizard
            linqServerModeSource1.QueryableSource = (New XtraPivotGrid_CreateDrillDownDataSourceAsync.DataClasses1DataContext()).Invoices
        End Sub
        Private Sub pivotGridControl1_CellClick(ByVal sender As Object, ByVal e As DevExpress.XtraPivotGrid.PivotCellEventArgs)
            Dim pivot As PivotGridControl = TryCast(sender, PivotGridControl)
            If dForm.IsDisposed Then
                LoadDrillDownForm()
            End If

            'Check whether an asynchronous operation is in progress.
            If Not pivot.IsAsyncInProgress Then

                ' Get the record set associated with the clicked cell.
                pivot.CreateDrillDownDataSourceAsync(e.ColumnIndex, e.RowIndex, 25, New List(Of String) From {"ProductName", "Quantity"}, Sub(result)
                    ' The 'result' parameter of the delegate returns an AsyncOperationResult instance.
                    ' The AsyncOperationResult.Value property contains a record set.
                    dForm.DataSource = CType(result.Value, PivotDrillDownDataSource)
                End Sub)
            End If
        End Sub
        Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs)
            LoadDrillDownForm()
        End Sub
        Private Sub LoadDrillDownForm()
            dForm = New DrillDownForm()
            dForm.Show()
        End Sub
    End Class
End Namespace