TdxWaitForm Class

A Wait Form you can display during time-consuming operations.

Declaration

TdxWaitForm = class(
    TdxSplashFormBase
)

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.

Note

A Wait Form is not displayed automatically during time-consuming operations. You need to hide or display a Wait Form manually in code as demonstrated in the following code example: Display a Wait Form During Report Export.

In this topic…

• Wait Form Management
• Splash Form Designer
• Main API Members
  • Size & Position
  • Visibility Management
  • Wait Form Widgets
  • General-Purpose API Members
• Code Example: Display a Wait Form During Report Export
• Direct TdxWaitForm Class Reference

Wait Form Management

Use the design-time Project Settings dialog to manage Wait Forms in your project (the Splash Forms tab). A DevExpress project always has at least one (predefined) Wait Form accessible using the TdxSplashFormManager.WaitForm class function.

Splash Form Designer

The Splash Form Designer dialog allows you to configure the layout of a predefined or custom Wait form. Select a Wait form in the Project Settings dialog and click Customize… to display the Splash Form Designer dialog.

Main API Members

The list below outlines key members of the TdxWaitForm class. You can use these members to hide/display a Wait Form and access/customize existing UI elements.

Size & Position

BoundsRect | SetBounds

Specify the form’s bounding rectangle.

Left | Top

Specify the form position (in relation to the target control/form).

Width | Height

Specify Wait Form dimensions.

Visibility Management

Hide

Hides the Wait Form if it is visible.

Preview

Displays the Wait Form for the target control or form in Preview mode. A user can click the target control/form to close the displayed Wait Form.

Show

Displays the Wait Form for the target control or form. Users cannot close the Wait Form in this mode. You need to call the Hide procedure explicitly to hide the displayed form.

Visible

Indicates if the form is visible.

Wait Form Widgets

Splash and Wait Forms use dedicated Splash Form widgets (derived from the TdxSplashFormBase.TContentItem base class) instead of controls (TControl descendants) to avoid excessive dependencies.

Tip

All API members in this section allow you to access and modify existing widgets placed on the Splash Form. If the target widget is not found, an exception occurs.

Use the Splash Form Designer dialog to add new or remove existing widgets.

Animation

Provides access to an Animation/Activity Indicator widget (TdxSplashFormBase.TAnimation) on the form.

GetItem

Provides access to any widget on the form (by type and name).

Image

Provides access to an Image widget (TdxSplashFormBase.TImage) on the form.

Progress

Provides access to a Progress Bar widget (TdxSplashFormBase.TProgress) on the form.

Text

Provides access to a Text/Label widget (TdxSplashFormBase.TText) on the form.

General-Purpose API Members

BeginUpdate | EndUpdate

Allow you to avoid excessive redraw operations during batch appearance setting changes.

Color

Specifies the form background color.

Default

Specifies if the Wait Form is used as default in the application.

Name

Specifies the Wait Form’s name (used in the Splash Form Manager and Project Settings).

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 "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
  }
}

Direct TdxWaitForm Class Reference

The TdxSplashFormManager.WaitForm class function returns a TdxWaitForm object.

Inheritance

TObject

TdxSplashFormBase

TdxWaitForm