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 form elements
  • Changing the image of form elements
  • Changing the style of form elements
  • Hiding or showing form elements
  • Hiding or showing a form field
  • Changing the style of a form field
  • Ensure the visibility of a form field
  • Ensure the visibility of a form element
• Examples
  • Example 1: Implement a global form initialization function
  • Example 2: Hiding form elements dynamically

See also: Classes and Objects, 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.

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. 

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 form elements

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

Note that all elements with this name will be affected.

Changing the image of form elements

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

Note that all elements with this name will be affected.

Changing the style of form elements

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

Note that all elements with this name will be affected.

Hiding or showing form elements

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:

Note that you should not hide all fields of a dialog, otherwise the dialog execution stops (at least one field must get the focus during a dialog execution).

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").

Ensure the visibility of a form field

The ensureFieldVisible() method can be used to make sure that the given form field is visible to the user. This method can for example be used to show a folder page by passing a field that is located in the folder page, even if the field is not used in a dialog.

The form field is identified by a name with an optional prefix ("table.column" or "column").

Understand that this method does not give the focus to the field passed as parameter. The folder page or screen area shown by this method call is temporarily visible and can disappear at the next user interaction, resulting in the field being no longer visible. For example, with a folder having two pages, if the focus is in a field of the first page, and you make the second page visible with a call to the ensureFieldVisible() method by passing a field located in the second page, when the user presses the TAB key, the focus will go to the next field in the first page and thus bring the first page to the top. If you want to show a folder page and give the focus to a specific field in that page, use NEXT FIELD instead.

Ensure the visibility of a form element

The ensureElementVisible() method is similar to ensureFieldVisible(), except that it is designed to make any kind of form element visible, even if it's not a form field, such as a static label or static image.

The form element is identified by its name. As several form elements can have the same name, the first form element found will be selected. 

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