Using Pop-up Forms in FireMonkey

From RAD Studio
Jump to: navigation, search

Go Up to FireMonkey Application Design

About pop-up forms

FireMonkey supports pop-up forms. Pop-up forms are defined in the TCommonCustomForm class. The most important properties of pop-up forms are FormStyle and ParentForm.

TCommonCustomForm.FormStyle property

The FormStyle property defines the behavior of your form. FormStyle can have one of the following values Normal, StayOnTop, and Popup. The meaning of the Normal and StayOnTop values is rather trivial. Normal defines an ordinary form and StayOnTop defines an ordinary form that always remains on top of the desktop and of all other forms in the application.

Notice that VCL has the similar TCustomForm.FormStyle property having two additional fsMDIChild and fsMDIForm values. Notice that these values are not defined in FireMonkey because these values have a meaning only under Windows platform.
Compare FormStyle with the StyleBook property, which defines the visible style of a form.

The Popup option defines a special pop-up form, which is used in combo list controls and menus. Pop-up forms have the following specific behavior:

  • Pop-up forms cannot be active. All forms of this type belong to the special PopupForms list in the TScreen class. PopupFormCount defines the number of pop-up forms currently created in the application.
  • On mobile platforms, ordinary forms are always shown in full-screen mode, but pop-up forms can occupy only a part of the desktop.
  • Pop-up forms do not stay visible for a long time. If you click a mouse (or tap a touchpad with a finger) outside of the pop-up form, then the pop-up form usually closes. Several pop-up forms can be shown simultaneously; these pop-up forms can have kindred relationships.

Typically pop-up forms have the following properties:

BorderStyle := None; // No visible border (not resizable) 
Transparency := True;  // pop-up form is transparent 

TCommonCustomForm.ParentForm property

The ParentForm property defines the kindred relationship between forms. The value of ParentForm is set when you change the Parent property. If Parent is a form, then ParentForm is set equal to Parent. Otherwise, ParentForm is set equal to the form to which the Parent belongs.

After each changing of the ParentForm form, the system executes the virtual DoParentFormChanged method.

Notice that changing any of the FormStyle, BorderStyle, ParentForm properties, enforces recreating of the current form, of all controls on the form, and of all child forms of the current form. Therefore, we do not recommend to change any of these properties at run time, after a form is already shown in the screen.

Using TCustomPopupForm class

To simplify pop-up form creating, FireMonkey defines the special TCustomPopupForm class. The TPopup (in CreatePopupForm), TComboEdit, TPopupBox, TMenuBar, and other similar classes use TCustomPopupForm.

By default, TCustomPopupForm forms have a transparent background (Transparency := True) and do not have a frame (BorderStyle := None). When a TCustomPopupForm form is closed it is automatically destroyed. When a TCustomPopupForm form is created, the system does not search for a FMX-file keeping the form. That is, the TCustomPopupForm class is designed to be used during run time.

TCustomPopupForm forms use the following constructor:

 constructor Create(AOwner: TComponent; AStyleBook: TStyleBook = nil; APlacementTarget: TControl = nil); reintroduce;

Here AStyleBook specifies styles used by a form, APlacementTarget specifies the control close to which the form should appear.

Important properties of TCustomPopupForm forms

Since TCustomPopupForm forms do not have visible frames and have transparent backgrounds, such forms should not spread out of the screen boundaries. Physical coordinates of a form (Position, Height, Width) are not used for positioning. The positioning of TCustomPopupForm forms is made using other properties: Placement, PlacementTarget, PlacementRectangle, ScreenPlacementRect,Size. You should not change the Position, Height, Width properties explicitly.

PlacementTarget points to a target control relative to which the TCustomPopupForm form is positioned. Here and after we will use the term adhering to specify such relative positioning of the pop-up form close to the target control. If PlacementTarget is specified, then the screen coordinates of a form are executed relatively to this PlacementTarget control.

If PlacementTarget is not set, and the TCustomPopupForm has a ParentForm, then the TCustomPopupForm is positioned relative to its parent. If PlacementTarget and ParentForm are not set, TCustomPopupForm is positioned relative to the top left corner of the screen (main window).

PlacementRectangle defines coordinates of the rectangle relative to which the form adheres. The screen coordinates of PlacementRectangle are calculated relatively to PlacementTarget (if specified). Otherwise, the screen coordinates are calculated relatively to the top left corner of the screen. The following rules are used:

ScreenPlacementRect defines screen coordinates of the rectangle relative to which the form adheres taking into account both PlacementRectangle and PlacementTarget properties.

Placement defines how a pop-up form is positioned relative to a rectangle specified by a property like ScreenPlacementRect, relative to the screen, or relative to the mouse (pointing device) position. TPlacement defines possible values of Placement. The ordinary default value is Bottom defining that the pop-up form is adhered to the bottom of the target rectangle. The following figure demonstrates the TopCenter value:

Screen Placement Rectangle

In the figure, ScreenPlacementRect is the colored Fuchsia rectangle of the Show popup button.

Padding, like in ordinary forms, defines indents from boundaries of client rectangular of a form. All child controls in the form are aligned according to these indents. The default value is 8; it is used to provide that effects (like shadows) do not cut by physical boundaries of a window.

Size defines the size of the working area of the current pop-up form. The rectangle of the physical size of the window, as it is shown with the red dashed frame in the figure, are not interesting. The Size rectangle is shown in the figure by the green dashed frame, specify that dimensions according to which all controls are aligned. Form dimensions (ClientWidth and ClientHeight) are defined automatically based on Size and Padding. If PlacementRectangle is defined and Placement is Absolute, then Size is ignored.

ContentPadding defines indents from the client area of a pop-up form. Adhering of the pop-up form is executed to the boundaries of this indented 'padding rectangle'.

ScreenContentRect defines screen coordinates of the 'padding rectangle' to which boundaries adhering of a pop-up form is implemented.

All useful content of a pop-up form is positioned inside this 'padding rectangle'. Notice that some 'decorative elements', for example, a 'triangular peak' on a side of callout panel can be positioned outside of the padding rectangle. This is demonstrated at the following figure:

Triangular peaks

Offset defines an offset of the 'padding rectangle' relative to the client rectangle of a pop-up form. Defines the number of pixels to displace a pop-up form relative to a form position that is obtained taking into account all positioning properties discussed above. The Offset direction depends upon a Placement value. The Offset property is used, for example, in multi-level menus, when pop-up forms of submenus are placed overlapping a form of a previous level.

Pop-up Form - Offset

DragWithParent specifies whether the current TCustomPopupForm can be dragged after it is shown. For example, if DragWithParent is True, TCustomPopupForm is dragged together with its parent form when the parent form is the target of a drag-and-drop operation. When Placement is Mouse or MouseCenter, then pop-up form moves following the mouse cursor. On mobile devices, after changing of orientation (portrait/landscape) pop-up form can change position in order not to be partially obscured by the screen boundaries.

See Also