Back to Contents

The Form class

Summary:

• Syntax
• Methods
• Usage
  • Defining the default initializer for all forms
  • Getting the DOM node of the form
  • Loading Action Defaults form the form
  • Loading the form ToolBar
  • Loading the form TopMenu
  • Searching for a specific child node in the form
  • Changing the text of a form element
  • Changing the image of a form element
  • Changing the style of a form element
  • Hiding or showing a form element
  • Hiding or showing a form field
  • Changing the style of a form field
• Examples
  • Example 1: Implement a global form initialization function
  • Example 2: Hiding form elements dynamically

See also: Built-in classes, Window class, Windows and Forms

Syntax

The Form class is a built-in class that provides an interface to the forms used by the program.

Syntax:

Methods:

Usage:

The Form class provides an interface to form objects created by an OPEN WINDOW WITH FORM or DISPLAY FORM instruction.

A form object allows you to manipulate form elements by program, typically to hide some parts of a form with the setElementHidden() method. The runtime system is able to handle hidden fields during a dialog instruction. You can, for example, hide a GRO containing fields and labels.

You can get a ui.Form instance of the current form with the ui.Window.getForm() method.

Warning: The OPEN FORM instruction does not create a ui.Form object; it just declares a handle. It is actually the DISPLAY FORM instruction that instantiates a ui.Form object that will be attached to the current window. When a form is displayed with DISPLAY FORM in different windows, the same form specification file will be used to create different ui.Form objects. 

Defining the default initializer for all forms

With the setDefaultInitializer() method, you can specify a default initialization function to implement global processing when a form is opened. The method takes the name of the initialization function as a parameter. That function will be called with a ui.Form object as a parameter. 

Warning: You must give the initialization function name in lower-case letters to the setDefaultInitializer() method. The BDL syntax allows case-insensitive functions names, but the runtime system must reference functions in lower-case letters internally.

Getting the DOM node of the form

The getNode() method returns the DOM node containing the abstract representation of the window.

Loading Action Defaults for the form

You may want to load form specific Action Defaults at runtime with the loadActionDefaults() method. This method takes the file name as parameter without the .4ad suffix. Existing action defaults will be replaced.

Loading the form ToolBar

The loadToolBar() method can be used to load a Toolbar XML definition file into the form; for example, in the initialization function. If the form already contains a toolbar, it will be replaced by the new toolbar loaded from this function.

Loading the form TopMenu

The loadTopMenu() method can be used to load a Topmenu XML definition file into the form; for example, in the initialization function. If the form alreadycontains a topmenu, it will be replaced by the new topmenu loaded by this function.

Searching for a specific child node in the form

The findNode() method allows you to search for a specific DOM node in the abstract representation of the form. You search for a child node by giving its type and the name of the element (i.e. the tagname and the value of the 'name' attribute).

Changing the text of a form element

You may want to modify the text of a static label or group box during program execution. This can be done with the setElementText() method. You must pass the identifier of the form element (i.e. the element must have a name in the .per file).

Changing the image of a form element

The image of a form element can be changed with the setElementImage() method. You must pass the identifier of the form element (i.e. the element must have a name in the .per file).

Changing the style of a form element

To change the decoration style of a form element, you can use the setElementStyle() method, by passing the identifier of the form element (i.e. the element must have a name in the .per file).

Hiding or showing a form element

The setElementHidden() method changes the 'hidden' attribute of all form elements identified by a name.

You specify an integer value for the 'hidden' attribute as follows:

Hiding or showing a form field

You can use the setFieldHidden() method to change the 'hidden' attribute of a form field. Form fields are identified by a fully qualified field name in lower case letters ("table.column" or "formonly.field").

 You specify an integer value for the 'hidden' attribute as follows:

Changing the style of a form field

To change the style of the view node of a form field, you must use the setFieldStyle() method. The form field is identified by a name with an optional prefix ("table.column" or "column").

Examples

Example 1: Implement a global form initialization function.

01 MAIN
02    CALL ui.Form.setDefaultInitializer("init")
03    OPEN FORM f1 FROM "items"
04    DISPLAY FORM f1 -- Form appears in the default SCREEN window
05    OPEN WINDOW w1 WITH FORM "customer"
06    OPEN WINDOW w2 WITH FORM "orders"
07    DISPLAY FORM f1 -- Form appears in w2 window
08    MENU "Test"
09       COMMAND "exit" EXIT MENU
10    END MENU
11 END MAIN
12 
13 FUNCTION init(f)
14    DEFINE f ui.Form
15    DEFINE n om.DomNode
16    CALL f.loadTopMenu("mymenu")
17    LET n = f.getNode()
18    DISPLAY "Init: ", n.getAttribute("name")
19 END FUNCTION

Example 2: Hiding form elements dynamically.

01 MAIN
02    DEFINE w ui.Window
03    DEFINE f ui.Form
04    DEFINE custid INTEGER
05    DEFINE custname CHAR(10)
06    OPEN WINDOW w1 WITH FORM "customer"
07    LET w = ui.Window.getCurrent()
08    LET f = w.getForm()
09    INPUT BY NAME custid, custname
10      ON ACTION hide
11        CALL f.setFieldHidden("customer.custid",1)
12        CALL f.setElementHidden("label_custid",1)
13      ON ACTION show
14        CALL f.setFieldHidden("customer.custid",0)
15        CALL f.setElementHidden("label_custid",0)
16    END INPUT
17 END MAIN