The following are the forms and dialogs in the standard component library.


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 at application startup and be owned by the global TApplication Application instance. When a form or any TComponent-descendant component instance is owned, the instance is automatically freed when the owning component is freed. Please see the Visual Client Applications topic for more information on the global Application instance.

The TApplication Run method accepts an optional string parameter that indicates the name of the form that should be treated as the main form for the application. The main form of the application is automatically shown and brought to the front at application startup. If this parameter is not specified or is not a valid form name, then the first form in the list of auto-create forms is considered the main form of the application. For example, the following shows the main program source of an application that has one auto-create form:

project MusicCollection;

contains Main, Album, AddAlbum, Track, SetMediaID;

uses WebForms, WebCtrls;

begin
   Application.CreateForm(TMainForm);
   Application.Run('MainForm');
end.

In this case the form whose Name property is equal to the parameter passed to the Run method will be considered the main form. If no form exists with the name of "MainForm", then the TMainForm form class instance will be 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. The EditFolderDlg variable is declared as a global variable in the interface section of the TEditFolderDlg's unit (EditFolder) and is automatically managed by the design-time environment in the IDE.

uses EditFolder;

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

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 TModalOverlay 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 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.