TCustomForm.ShowModal

Displays the form as a modal dialog.

Declaration

Source position: forms.pp line 741

Function result

The modal result for the dialog.

Description

Shows the form in a modal state and waits until it is closed by the user or by the program. Modal state means that neither the user nor the program can switch to or display another form before exiting the method.

The form must be Enabled with its Visible property set to False when calling ShowModal. It cannot 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.

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 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 form. mrNone indicates that the form has not been (or should not be) closed. mrCancel indicates the the Cancel button was pressed, the form was closed using a window decoration, or the application has been Terminated.

ShowModal uses the value from 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.