TCustomForm.ShowModal

Displays the form as a modal dialog.

Declaration

Source position: forms.pp line 737

Function result

The modal result for the dialog.

Description

ShowModal is the method used to show the form in a modal state and wait until it is closed by the user or by the program. Modal state means that neither the user nor the program can switch back to the previously focused form until the method is exited.

Before the dialog form is displayed and executed, the following actions are performed:

• An active drag operation is cancelled.
• An active pop-up menu is closed.
• An active capture is killed and released in the widget instance.

The form must be Enabled with its Visible property set to False when calling ShowModal. It cannot already have fsModal in its FormState property, and it cannot be a MDI Child form. An EInvalidOperation exception is raised if the form cannot be displayed as a modal form for any of these reasons.

ShowModal updates the Application instance by calling its ModalStarted method. This maintains its internal members and signals any OnModalBegin event handlers assigned for the application. The application switches to modal state until ShowModal is completed. The ModalFinished method for the Application is called to end the modal state prior to exit.

ShowModal implements its own message processing loop. It calls AppProcessMessages in the widgetset to process messages and events for the form. If an exception occurs, it is caught in the processing loop. If CaptureExceptions is enabled for the Application instance, its HandleException is called. If CaptureExceptions is not enabled in the application, the exception is re-raised.

ShowModal sets the value in the ModalResult property to indicate the action performed to close the modal dialog form. mrNone indicates that the form has not been (or should not be) closed. mrCancel indicates the Cancel button was pressed, the form was closed using a window decoration, or the application was Terminated while ShowModal was running.

Any value in ModalResult other than mrNone causes DoClose to be called where CloseQuery / OnCloseQuery / OnClose are used to determine whether the dialog can be closed and the close action performed for the form instance. If the close action is caNone, ModalResult is set to mrNone to continue the message processing loop. caFree in the close action causes the Release method to be called to free the form instance. There is no need to call the Release method in application code; it is handled in the message processing loop in the method. The OnClose event can be used to return caFree as the close action which forces the dialog form to be closed.

When the message processing loop has been completed, the form instance is hidden and other enabled forms in the application are restored. The previously focused form is also restored.

ShowModal uses the value in ModalResult as the return value for the method.

Errors

Raises an EInvalidOperation exception if the form cannot be displayed as a modal form.

Version info

Modified in LCL version 3.0.0 to allow the application to handle an exception when its CaptureExceptions property is enabled.

See also