Forms and navigation

Forms

Forms

Under Smart, a form is a lot simpler than what we are used to under delphi. The class TW3CustomForm which all forms derive from inherits directly from TW3CustomControl and is basically nothing more than a visual control. It introduces only 3 new members which are:

  • Caption property
  • FormActivated method
  • FormDeactivated method

The method FormActivated() is executed after the form has come into view, and FormDeactivated() before the form move out of view.

When you create a visual application, Smart will create main unit and main form and prepare the code that initializes and displays the main form while the application is being started. This initialization happens in the method TApplication.ApplicationStarting in the main unit.

procedure TApplication.ApplicationStarting;
begin
  //Add code above this line 
  FFormMain := TFormMain.Create(Display.View);
  FFormMain.Name := 'Main';
  RegisterFormInstance(FFormMain, True);

  inherited;
end;

This initialization code creates the form object, sets its name and registers the form object in the internal list.

Creating Secondary Forms

To create additional form, you first have to create it in the IDE by using the Add Form button. This will create new unit which will implement the new form, but will not create the form object and so the form will not be usable. You will have to do it in the code.

You should initialize additional units in the ApplicationStarting method, just like the main form is instantiated. The example below shows how to create and register Help form for the MandlebrotExplorer demo project.

procedure TApplication.ApplicationStarting;
begin
  //Add code above this line 
  FFormMain := TFormMain.Create(Display.View);
  FFormMain.Name := 'Main';
  RegisterFormInstance(FFormMain, True);

  FFormHelp := TFormHelp.Create(Display.View);
  FFormHelp.Name := 'Help';
  RegisterFormInstance(FFormHelp, False);

  inherited;
end;

There’s an important difference between the two RegisterFormInstance calls. When creating main form, second parameter is True and when creating all other forms it must be False.

Navigating Between Forms

Even when created, secondary form is not automatically visible (this makes a lot of sense if you think about it). To display a different form, use Application.GotoForm or Application.GotoFormByRef. They are functionally the same except that the former accepts a form name and the latter a form object.

procedure GotoForm(aName: String; Effect: TFormEntryEffect = feNone);
procedure GotoFormByRef(aForm: TW3CustomForm; 
  Effect: TFormEntryEffect = feNone);

Both take an optional parameter governing how the new form will be displayed. Following effects can be applied:

  • feNone
    No effect, new form just *pops up* over the old form.
  • feFromRight
    New form slides in from the right.
  • feToLeft
    New form slides in from the left.

To return to the primary form you have again to call GotoForm or GotoFormByRef.