ClassGroup pseudo-property of TDataModule

From RAD Studio
Jump to: navigation, search

Go Up to Creating and Editing Standard Data Modules

Effects of the ClassGroup pseudo-property

System.Classes.TDataModule and its descendant classes, such as Web.HTTPApp.TWebModule, have a pseudo-property named ClassGroup that does the following:

  • Determines the framework affinity for the data module. That is, ClassGroup specifies that the data module is either framework-neutral or is to work with a specific framework (namely, VCL or FMX).
  • Enables framework-specific nonvisual components in the Tool Palette.
    You need to set a framework-specific value for ClassGroup in the Object Inspector in order to enable framework-specific nonvisual components such as the following:
    • TActionList is VCL-only, and so to enable TActionList in the Tool Palette, you must set ClassGroup to the VCL setting.
    • TTimer exists in both FMX and VCL. To enable TTimer for the correct framework, you must set ClassGroup to either FMX or VCL, to match the framework of the parent application.
(TTimer and TActionList are further discussed later in this topic.)

Because the ClassGroup pseudo-property is used only by the IDE and is not a compiler-generated property (hence, 'pseudo-property'), ClassGroup is not documented in the compiler-generated Libraries Reference. The page you are reading is the documentation for ClassGroup.

Note: The two frameworks, VCL and FMX, are not mutually compatible. For this reason, combining VCL and FMX in an application is not supported. See FireMonkey Application Platform.

ClassGroup Values

Following are the ClassGroup values you can choose in the Object Inspector, including the framework and the RTL elements that can be used with each framework-specific choice:

ClassGroup Associated Framework Run-Time Library

System.Classes.TPersistent

None (Framework-neutral)

Delphi RTL

(excluding unsupported framework-specific elements)

Vcl.Controls.TControl

VCL framework

Delphi RTL

(excluding unsupported framework-specific elements)

FMX.Controls.TControl

FMX framework

Delphi RTL

(excluding unsupported framework-specific elements)

TDataModule is Initially Framework-Neutral; You Set Framework Affinity with ClassGroup

When you create a data module, the unit file initially contains a directive that sets the ClassGroup pseudo-property to a framework-neutral base value (System.Classes.TPersistent), as follows:

Delphi:

 {%CLASSGROUP 'System.Classes.TPersistent'}

C++:

 #pragma classgroup "System.Classes.TPersistent"
Note: This directive is used only by the IDE and indicates the data module's relationship with a particular component framework, if any. Then the IDE enforces the kinds of components that you can drop on the data module.

When you change the ClassGroup value, the directive is automatically changed in your code.

Because TDataModule is initially framework-neutral, you can use a data module with either the VCL or the FireMonkey framework. This also means that framework-specific classes and members (such as Vcl.ActnList.TActionList and FMX.Types.TTimer) are not available in the Tool Palette for a framework-neutral data module. You can include the appropriate framework-specific classes and members by going to the Object Inspector and setting the ClassGroup property of your data module to indicate your correct framework, as one of the following:

  • Vcl.Controls.TControl
  • FMX.Controls.TControl (OS X)

Examples of Framework-Specific Nonvisual Components

  • TActionList is a VCL nonvisual component and as such it does not appear in the Tool Palette for a data module whose ClassGroup pseudo-property is System.Classes.TPersistent (framework-neutral) rather than Vcl.Controls.TControl (framework-specific). Likewise, TActionList is not available if the ClassGroup is set to FMX.Controls.TControl.
  • TTimer has two framework-specific implementations, as follows:
    In both cases, TTimer is only available in the Tool Palette when the ClassGroup property is set to a framework-specific value, rather than the framework-neutral System.Classes.TPersistent. But because TTimer has both a VCL and an FMX implementation, make sure that you select the correct ClassGroup value for your data module, to match the application framework, or errors can occur.

After you select the Classgroup you want, you might need to switch to the Edit tab and back to the Design tab in order to refresh the Tool Palette to reflect your Classgroup choice.

Troubleshooting Error Situations

If you create a data module inside a Windows VCL Application and set an FMX value for the ClassGroup property, the following message is displayed when you try to drop an FMX component on the data module:

Class <classname> is not applicable to this module.

This message occurs when the ClassGroup value of the data module does not match the framework of the application.

A similar message appears if you create a FireMonkey application, add a data module, select the ClassGroup value Vcl.Controls.TControl, and try to drop a TTimer on the data module, because the Vcl.ExtCtrls.TTimer nonvisual component is not compatible with the FireMonkey framework.

The following message might also be displayed by the IDE:

The following component(s) are not available in the specified class group.
This is likely to cause compile or runtime errors.
FMX.Types.TTimer

If you try to compile a project that has a ClassGroup value that is not compatible with the application framework, you might see compile errors for elements that are not supported in the current framework. Possible errors you might encounter include the following:

See Also