Back to Contents

The Form class

Summary:

• Basics
• Examples

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

Basics

Purpose:

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

Syntax:

Methods:

Usage:

This 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 groupbox 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. This means, 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. 

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. 

The loadToolBar() method can be used to load a Toolbar XML definition file into the form; for example, in the initialization function.

The loadTopMenu() method can be used to load a Topmenu XML definition file into the form; for example, in the initialization function.

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

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

To change the decoration style of a form element, you can use the setElementStyle() method.

The setElementHidden() method changes the 'hidden' attribute of all form elements identified by a name. Form fields are identified by a full qualified field name in lower case letters ("table.column" or "formonly.field"). You specify an integer value for the 'hidden' attribute as follows:

You can use the setFieldHidden() method to change the 'hidden' attribute of a form field 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.setElementHidden("customer.custid",1)
12      ON ACTION show
13        CALL f.setElementHidden("customer.custid",0)
14    END INPUT
15 END MAIN