TdxForm Class

The base class for DPI-aware DevExpress application forms.

Declaration

TdxForm = class(
    TForm,
    IdxScaleFactor,
    IdxAutomationElement,
    IdxFormDecorator,
    IdxFormDecoratorParameters
)

Remarks

The TdxForm class is designed to substitute TForm as a form ancestor in DPI-aware applications. An instance of a form class derived from TdxForm (TdxRibbonForm, for instance) automatically updates its scale factor and applies it to all DevExpress controls when your application accepts the WM_DPICHANGED^[1] system message.

Tip

Different supported Embarcadero RAD Studio® IDE versions have different DPI awareness implementations. To ensure the best experience with DevExpress components in multi-monitor mixed-DPI environments regardless of the RAD Studio version, we recommend that you derive all forms in your application project from TdxForm and its descendants.

Form Creation: Derive a DPI-Aware Form from TdxForm

To use the TdxForm class as a direct ancestor class for a form in your application, you need to create a new form in the RAD Studio IDE, add the dxForms unit to the uses clause, and replace TForm with TdxForm in the form class declaration as follows:

Delphi

uses dxForms;  // This unit declares the TdxForm class
// ...
type
  TMyForm = class(TdxForm)
  private
    { Private declarations }
  public
    { Public declarations }
  end;

C++

#include "dxForms.hpp"  // This unit declares the TdxForm class
// ...
class TMyForm : public TdxForm
{
private:
  // Private declarations
public:
  // Public declarations
};

Main API Members

The list below outlines key members of the TdxForm class that allow you to configure a DPI-aware application form.

General Form Settings and Methods

The following public API members are derived from the standard TForm class shipped with the VCL library:

Caption

Specifies the form’s caption.

PixelsPerInch

Specifies the base DPI value for scale factor calculations.

ShowModal

Invokes the form as a modal dialog.

Scaled

Specifies if DPI awareness is enabled for the form.

Visible | Hide | Show

Hide or display the form.

Width | Height | ClientWidth | ClientHeight

Allow you to adjust form and client area dimensions.

Tip

Refer to the TForm class description for detailed information on all standard form API members.

DPI Awareness Implementation

The following API members implement DPI awareness for DevExpress forms regardless of the target Embarcadero RAD Studio® version. You do not need to interact with these API members in your code in the majority of usage scenarios. However, you can override certain methods in custom TdxCustomForm class descendants to change predefined form responses to monitor DPI changes.

ChangeScale

Multiplies the form’s scale factor by the specified scale factor.

ScaleBy

Updates the form’s scale factor.

ScaleFactor

Returns the form’s scale factor that updates every time your application accepts the WM_DPICHANGED system message if the Scaled property is set to True.

You can use this property to identify the current scale factor or call any of the ScaleFactor.Apply functions to apply the scale factor to custom-drawn UI elements within the form.^[1]

ScaleForPPI

Scales the form and components within it according to the specified target DPI.

ScaleFactorChanged

Automatically scales the form when its scale factor changes.

You can override^[2] this procedure in custom TdxForm class descendants to execute custom code when the monitor DPI changes.

UpdateImageLists

Automatically switches between DPI-aware image lists whose stored bitmaps target different monitor DPIs if the dxAutoReplaceImageListReferencesOnDPIChanges global variable is set to True.

You can override this procedure in custom TdxForm class descendants to implement different image list replacement criteria.

Tip

We recommend that you use only SVG images in all projects that target multi-monitor and high-DPI environments.

Other DPI-Aware Form Classes

DevExpress VCL products ship with the following base form classes with support for DPI-awareness:

TdxAlertWindow

An alert window.

TdxRibbonForm

A Ribbon form class.

TdxFluentDesignForm

A Fluent Design application form.

TdxSkinForm

The base class for simple DPI-aware forms that can override global form corner and shadow settings.

Additional Information

Refer to the following help topic for detailed information on how to adapt your application to high-DPI environments: High DPI and Graphics.

Implements

IdxScaleFactor

Inheritance

TObject

TPersistent

TComponent

TControl

TWinControl

TScrollingWinControl

TCustomForm

TForm

TdxForm

Footnotes

1. An application accepts the WM_DPICHANGED system message only if the application manifest includes the permonitor or permonitorv2 item.

2. This API member description includes a code example.