TdxSplashFormManager.WaitForm(string) Method

Provides access to a Wait Form by name.

Declaration

class function WaitForm(const AName: string = ''): TdxWaitForm; static;

Parameters

Name	Type	Description
AName	string	Optional. Specifies the target Wait Form name. If you omit the AName parameter, the function returns the default Wait Form (the function uses the DefaultName constant value as the target name).

Returns

Type	Description
TdxWaitForm	Returns the Wait Form with the name passed as the AName parameter (or the default wait form if the optional parameter is omitted). If no form is found, an exception occurs.

Remarks

A Wait Form is designed to indicate that a time-consuming process (such as data import, export, etc.) is currently underway. A Wait Form is particularly useful if a lengthy process is running in the main thread and locks the application UI.

Call SplashForm and WaitForm class functions to access individual Splash Forms in the application by name.

Code Example: Display a Wait Form During Report Export

The following code example exports content of a configured TdxReportControl component to a file in the Portable Document (PDF) format using an intermediary TMemoryStream object:

Delphi

uses
  dxReport.Control,  // Declares the TdxReportControl component
  dxSplashForms,     // Declares the TdxSplashFormManager class and related types
  dxShellDialogs;    // Declares the TdxSaveFileDialog component
// ...

procedure TMyForm.cxButtonExportToPDFClick(Sender: TObject);
var
  AStream: TMemoryStream;
begin
  if not dxSaveFileDialog1.Execute(Handle) then Exit;  // Displays the "Save File" dialog
  AStream := TMemoryStream.Create;       // Creates a stream as an intermediary container
  // Displays a Wait Form before the export operation
  TdxSplashFormManager.WaitForm.Show(dxReportControl1.Parent);
  try
    dxReportControl1.ExportToPDF(AStream);   // Exports content to a stream in the PDF format
    AStream.SaveToFile(dxSaveFileDialog1.FileName);    // Saves PDF stream content to a file
  finally
    AStream.Free;                        // Releases the intermediary memory stream
    TdxSplashFormManager.WaitForm.Hide;  // Hides the Wait Form once the operation is complete
  end;
end;

C++

#include "dxReport.Control.hpp"  // Declares the TdxReportControl component
#include "dxSplashForms.hpp"     // Declares the TdxSplashFormManager class and related types
#include "dxShellDialogs.hpp"    // Declares the TdxSaveFileDialog component

// Add the following linker directives to the corresponding CPP source file:
#pragma link "dxReport.Control"  // Required to use dxReport.Control.hpp declarations
#pragma link "dxSplashForms"     // Required to use dxSplashForms.hpp declarations
#pragma link "dxShellDialogs"    // Required to use dxShellDialogs.hpp declarations
// ...

void __fastcall TMyForm::cxButtonExportToPDFClick(TObject *Sender)
{
  if(!dxSaveFileDialog1->Execute(Handle)) { return; }  // Displays the "Save File" dialog
  TMemoryStream *AStream = new TMemoryStream();  // Creates a stream as an intermediary container
  // Displays a Wait Form before the export operation
  TdxSplashFormManager::WaitForm()->Show(dxReportControl1->Parent);
  try
  {
    dxReportControl1->ExportToPDF(AStream);  // Exports content to a stream in the PDF format
    AStream->SaveToFile(dxSaveFileDialog1->FileName);  // Saves PDF stream content to a file
  }
  __finally
  {
    delete AStream;                              // Releases the intermediary memory stream
    TdxSplashFormManager::WaitForm()->Hide();    // Hides the Wait Form once the operation is complete
  }
}