How to: Track Data Export Progress

• Jul 08, 2022
• 3 minutes to read

Multiple DevExpress controls ship with a series of global methods that allow you to export data in multiple formats. Each of these methods has the optional AHandler parameter that accepts a handler object. This object should implement the IcxExportProgress and/or IcxExportBeforeSave interfaces declared in the cxExport unit to be able to track the progress of an export operation and/or perform custom actions before it. This topic describes how to implement the IcxExportProgress interface to display the progress of data export operations in the TcxProgress control placed on a form.

Declare a Progress Tracker Class

Derive a tracker class from the TInterfacedObject class and support the IcxExportProgress interface. Add the private FProgressBar field, the OnProgress procedure declaration, and a constructor as demonstrated in the code example below:

Delphi

MyProgressTracker = class(TInterfacedObject, IcxExportProgress)
  FProgressBar: TcxProgressBar; // Stores a reference to our TcxProgressBar control
  // Initializes a reference to the TcxProgressBar control on the main form
  constructor Create(AProgressBar: TcxProgressBar);
  // Updates the progress bar position during a data export operation
  procedure OnProgress(Sender: TObject; Percent: Integer);
end;

C++

class MyProgressTracker : public TInterfacedObject, IcxExportProgress
{
public:
    // Initializes a pointer to the TcxProgressBar control on the main form
    MyProgressTracker(TcxProgressBar *AProgressBar);
    // Updates the progress bar position during a data export operation
    void __fastcall OnProgress(TObject *Sender, int Percent);
    TcxProgressBar *FProgressBar; // Stores a pointer to our TcxProgressBar control

    HRESULT __stdcall GetClassID(CLSID *pClassID)
    {
        *pClassID = CLSID_SOMEVALUE;
        return S_OK;
    }
    // C++Builder requires us to reimplement methods of the IUnknown interface
    HRESULT __stdcall QueryInterface(const GUID& IID, void **Obj)
    { return GetInterface(IID, Obj) ? S_OK : E_NOINTERFACE; }
    ULONG __stdcall AddRef()  { return TInterfacedObject::_AddRef(); }
    ULONG __stdcall Release() { return TInterfacedObject::_Release(); }
}

Implement the Progress Tracker Class

Delphi

constructor MyProgressTracker.Create(AProgressBar: TcxProgressBar);
begin
  FProgressBar := AProgressBar;
end;

procedure MyProgressTracker.OnProgress(Sender: TObject; Percent: Integer);
begin
  if FProgressBar <> nil then
    FProgressBar.Position := Percent; // Updates the progress bar position
end;

C++

MyProgressTracker::MyProgressTracker(TcxProgressBar *AProgressBar)
{
  FProgressBar = AProgressBar;
}

void __fastcall MyProgressTracker::OnProgress(TObject *Sender, int Percent)
{
    if(FProgressBar != nullptr)
      FProgressBar->Position = Percent; // Updates the progress bar position
}

Invoke a Data Export Method

To pass a progress tracker to a data export method, create a MyProgressTracker class instance and increment the number of references to it. Decrement the reference number after a data export operation when the MyProgressTracker class instance is no longer needed.

Tip

You do not need to manage references to a progress tracker instance manually if you derive the progress tracker class from a form or component.

The following code example creates a progress tracker and passes it to the ExportGridToXLSX procedure to display the export progress in the TcxProgressBar control on the application form:

Delphi

procedure TfrmMasterDetail.ExportClick(Sender: TObject);
var
  AProgressTracker: MyProgressTracker;
begin
  AProgressTracker := MyProgressTracker.Create(cxProgressBar1); // Creates a progress tracker
  AProgressTracker._AddRef; // Increments the number of references to the progress tracker
  ExportGridToXLSX('Employees.xlsx', cxGrid1, True, True, True, 'xlsx', AProgressTracker);
  AProgressTracker._Release; // Decrements the number of references to the progress tracker to release it
end;

C++

void __fastcall TfrmMasterDetail::ExportClick(TObject *Sender)
{
    MyProgressTracker *AProgressTracker = nullptr;
    AProgressTracker = new MyProgressTracker(cxProgressBar1); // Creates a progress tracker
    AProgressTracker->_AddRef(); // Increments a reference to the progress tracker
    ExportGridToXLSX("Employees.xlsx", cxGrid1, true, true, true, "xlsx", AProgressTracker);
    AProgressTracker->Release(); // Decrements a reference to the progress tracker to release it
}