Home > Language Reference > Classes

Form Class

  + Object
    + Display
      + UIComponent
        + Form

Description

The Form class implements behaviors common to all forms (see Forms and controls). The form is the main element of an user interface. An HB++ program cannot draw or display anything without having first opened a form. This class is not instantiable nor cloneable; its features are only available through derivation.

Adding a form to your project by selecting 'Project > Add Form' creates both a new resource in your executable file, and a new class deriving from Form. The resource will describe the appearence of the form, as defined in the form editor (type and location of each controls, properties, and so on). The events your code handles in the class will define the behavior of the form (what happens if the user taps a given control, for example).

Opening and closing a form

To display a form at runtime, simply declare and instantiate an object whose type corresponds to the form you wish to open, and call its Show method. For example, a typical application startup code is:

Private Sub Application_NormalLaunch()
  Dim f As New frmMain
  f.Show hbFormModeless+hbFormGoto
End Sub

A form can be either modeless or modal, depending on the value of the parameter passed to the Show method. When opening a modeless form, the Show method returns immediately after the form is displayed. This behavior is typically used when opening background forms, such as your main application form. When opening a modal form, the Show method does not return until the form is closed by calling the Unload function. This behavior is typically used to implement dialog boxes. Note that these behaviors are not related to the Modal property, which only defines the appearence of the form border and caption.

Each time a form is loaded, all form and controls properties are reset to their design time value. Therefore, once a form is closed, you cannot access the values the user entered in controls such as Field or List anymore. Accessing those controls properties would simply reload the form, with default values. So, a typical dialog box code will save any value that will be needed after the form is closed into member variables. For example, a dialog box containing a text field and two buttons labelled 'OK' and 'Cancel' should be implemented as follows:

Public bOK As Boolean
Public sField As String

Private Sub Form_Load()
  Field1.Text = sField
End Sub

Private Sub cmdOK_Click()
  sField = Field1.Text
  bOK = True
  Unload Me
End Sub

Private Sub cmdCancel_Click()
  bOK = False
  Unload Me
End Sub

Invoking this dialog box can be performed using the following code:

Private Sub Button1_Click()
  Dim f As frmDialog

  f.sField="Init Value"
  f.Show hbFormModal+hbFormPopup
  If f.bOk Then
    MsgBox "Entered text: " & f.sField
  End If
End If

Life cycle of forms

As soon as you access one of the form controls, or invoke one of the form properties or methods, or call the Load function on a form, the following happens:

• The relevant resource is loaded and locked, and the Palm OS controls it contains are bound to the HB++ objects.
• Each user control of the form receives a Load event.
• Each user control of the form receives a Resize event, specifying the design time dimensions of the control. It is typically time for your code to allocate bitmaps to perform double buffering, for example.
• The form receives a Load event. It is typically time to perform one-shot actions, such as setting focus, or initializing a timer. Note that changing the DIA state from a handler for this event is not advised, since your form is not displayed yet; affecting a new value to the InputArea property should be done in the Activate event handler.
• The form receives a Resize event, specifying the design time dimensions of the form.

When the form is displayed for the first time, the following happens:

• The form receives an Activate (True) event. It is time for your code to set the DIA state, or to start previously initialized timers.
• If the screen size is not 160x160 and the DIA property is set to 'Enabled (resize)', the form is extended to occupies the whole screen, and a Resize event is raised, specifying the final dimensions of the form. If this operation makes some user controls to be resized, they receive a Resize event as well.
• The form is drawn, then each user control of the form receives a Paint event, and finally the form receives a Paint event.

If any window covers your form (for example a popup list, a dialog box, or a menu), it receives an Activate (False) event. It is typically time to interrupt timers used for animation, for example. When the form is again activated, it receives the same events as if it was displayed for the first time, except that the Paint event may not be raised if the form that is dismissed has its SaveBehind property set to True.

When the form is dismissed, the following happens:

• The form receives an Unload event.
• Each user control of the form receives an Unload event.
• The resource is released, which implies that any value stored in the various controls is lost.

Note: you should not perform any action that causes a form to be loaded from the Initialize method of a form. Doing so may lead to a system crash. Also, you should not try to open another form or a dialog box from while handling a Load event.

Handling common behaviors

It is a common situation to have to handle the exact same events on several forms. For example, you may have an About menu item on some of your forms, and the following code duplicated in each of those forms:

Private Sub mnuAbout_Click()
  Dim f as New frmAbout
  f.Show hbFormModal+hbFormPopup
End Sub

Fortunately, the HB++ object model offers an elegant feature to avoid such a situation. The tip is to use derivation and inheritance to implement that code in a generic class, and to manually declare the relevant controls or menu items to override default processing.

Create a new class in your project, and name it clsGenericForm. Paste the following code into that class:

Public mnuAbout As MenuItem ' Prevent HB++ from declaring this into the derived forms
                            ' and allows the event to be caught below

Private Sub mnuAbout_Click()
  Dim f as New frmAbout
  f.Show hbFormModal+hbFormPopup
End Sub

Then, just make each form that has a mnuAbout menu item derive from this class by entering clsGenericForm into its Extends property.

Note however that this only applies to code; you still have to duplicate the relevant controls and menu items on all the forms.

Members

System requirements