Icon Creating and Showing Forms

Before using any form classes, you must first create an instance of the form class, which you can do at design-time or at run-time:

Creating a Form at Design-Time
The easiest way to create a form is by using the IDE to create a new form. When a form is created at design-time in the IDE, it is automatically designated as an auto-create form in the application project, which means that the form will automatically be created during application startup. The first form in the list of auto-create forms is considered the main form of the application, and will also be shown at application startup. For example, the following shows the main program source of an application that has several auto-create forms:

project FormSubmit;

contains Main, Results;

uses WebForms, WebCtrls;

begin
   Application.Title := 'HTML Form Submittal Example';
   Application.CreateForm(TMainForm);
   Application.CreateForm(TResultsDialog);
   Application.Run;
end.

Because the TMainForm form class is the first form class in the list of auto-create forms, it is considered the main form of the application and will automatically be shown when the Application Run method is executed.

Please see the Adding to an Existing Project topic for more information on adding a new form to a project.

Creating a Form at Run-Time
You can also create a form instance at run-time using code. This is useful for forms that are not used very often and for which having them auto-created would be a waste of memory. The following is an example of creating a form and showing it (modally) at run-time:

uses ProgFrm;

procedure TMainForm.LaunchButtonClick(Sender: TObject);
begin
   ProgressForm:=TProgressForm.Create(nil);
   ProgressForm.ShowModal;
end;

Information In the above example the ProgressForm variable is declared in the interface section of the TProgressForm's unit (ProgFrm).

Showing and Hiding a Form
The TForm Show and ShowModal methods will show a form in a non-modal and modal fashion, respectively. See below for more information on modal forms.

Showing a form will also cause the form to be brought to the front of the visual stacking order via the BringToFront method.

To hide a form, call the TForm Hide method, which simply toggles the visibility of the form. In order to close the form and trigger the TForm OnCloseQuery and OnClose events, call the Close method instead.

Hiding or closing a form will also cause the form to be sent to the back of the visual stacking order via the SendToBack method.

Modal Forms
When a form is shown modally, the application displays a modal overlay over the entire surface and all other forms that prevents any keyboard or mouse input for any form other than the current modal form.

You can use the Application.Surface.ModalOverlay.CloseOnClick property to enable/disable the ability to close all visible modal forms by simply clicking on the modal overlay.

Modal forms behave very differently in a web browser environment than in a Windows desktop environment, requiring modal dialogs/forms be coded differently. To use the above example again, this is what the example would look like in a traditional Windows desktop application when using a product like Delphi:

uses ProgFrm;

procedure TMainForm.LaunchButtonClick(Sender: TObject);
begin
   ProgressForm:=TProgressForm.Create(nil);
   try
      ProgressForm.ShowModal;
   finally
      ProgressForm.Free;
   end;
end;

If you were to run the above code in a web browser, you would probably see a slight flicker as the form was shown and then immediately freed. This is because the ShowModal method, or any method in the JavaScript execution environment, does not cause the code execution to yield. Thus, the ShowModal method is called, and then the Free method is called right after the form is shown.

Because of the lack of the ability to yield execution, such forms must be closed/freed using a technique involving creating an event handler for the TForm OnClose event from the calling form and assigning that event handler to the OnClose event of the form that needs to be responded to. The following example shows how this would be done:

uses ProgFrm;

procedure TMainForm.ProgressFormClose(Sender: TObject);
begin
   ProgressForm.Free;
end;

procedure TMainForm.LaunchButtonClick(Sender: TObject);
begin
   ProgressForm:=TProgressForm.Create(nil);
   ProgressForm.OnClose:=ProgressFormClose;
   ProgressForm.ShowModal;
end;

This is quite a departure from the way that the OnClose event handler is used in desktop applications. With desktop applications, the form's OnClose event is normally assigned an event handler that is defined within the form being closed. If one simply remembers that the TForm OnClose event is a "special" event in this regard, then the concept will be easier to remember and implement properly in one's applications.

Form Events
The TForm OnCreate event is fired while a form is being created and is an ideal place to perform any initialization processing for the form.

The TForm OnCloseQuery event is fired when an attempt to close (hide) the form occurs. To prevent the close from occurring, return False as the result in an event handler for this event.

The TForm OnClose event is fired after the form is closed (hidden).

The TForm OnDestroy event is fired before a form is destroyed, and is an ideal place to dispose of any resources that need to be disposed of before the form is destroyed.
Image