FORM statement

Defines the layout and certain processing attributes of a frame for use within a single procedure. If the frame has not been previously scoped, the FORM statement scopes it to the current block. Use the FORM statement if you want to describe a frame in a single statement rather than let ABL construct the frame based on individual data handling statements in a block. You can use the FORM statement to describe a layout for a data iteration and the frame header or background.

Syntax 

 

FORM [ form-item ... ] [ { HEADER | BACKGROUND } head-item ... ] [ frame-phrase ]

 

FORM record [ EXCEPT field ... ] [ frame-phrase ]

form-item

Specifies a field-level widget or value to display in the frame, or a SPACE or SKIP directive. The data specified by all form items are owned by a single field group, duplicated for each data iteration in the frame.

This is the syntax for form-item:

 

Syntax 

field [ format-phrase ]

 

constant [ at-phrase | TO n ] [ BGCOLOR expression ] [ DCOLOR expression ] [ FGCOLOR expression ] [ FONT expression ] [ PFCOLOR expression ] [ VIEW-AS TEXT ]   [ WIDGET-ID id-number ]

 

SPACE [ ( n ) ]

 

SKIP [ ( n ) ]

field

A reference to a field or variable to be displayed in the frame. This value cannot be an expression or a frame. To specify a child frame, you must first define the parent and child frames, then assign the FRAME attribute of the child frame to the handle of the parent frame. The child frame is assigned to the same field group as other form items.

format-phrase

Specifies one or more frame attributes for a field or variable. For more information on format-phrase, see the Format phrase reference entry.

constant

A constant value.

at-phrase

Specifies the location of a value within the frame. The AT phrase does not left justify the data; it simply indicates the placement of the data area. This is the syntax for the AT phrase:

 

Syntax 

AT { n | { COLUMN column | COLUMN-OF relative-position } { ROW row | ROW-OF relative-position } [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ] | { X x | X-OF relative-position } { Y y | Y-OF relative-position } [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ] }

For more information, see the AT phrase reference entry.

TO n

The number (n) of the column in which you want the display to end. The TO option does not right justify the data; it simply indicates the placement of the data area.

BGCOLOR expression

Specifies the background color of the form item in graphical interfaces. This option is ignored in character interfaces.

DCOLOR expression

Specifies the display color of the form item in character interfaces. This option is ignored in graphical interfaces.

FGCOLOR expression

Specifies the foreground color of the form item in graphical interfaces. This option is ignored in character interfaces.

FONT expression

Specifies the font of the form item.

PFCOLOR expression

Specifies the prompt color of the form item in character interfaces. This option is ignored in graphical interfaces.

VIEW-AS TEXT

Specifies that the form item be displayed as a TEXT widget rather than as a FILL-IN widget.

WIDGET-ID id-number

Specifies a widget ID for a field-level widget or value to display in a frame. The value of id-number must be an expression that evaluates to an even integer value between 2 and 65534, inclusive, and must be unique across all widget IDs in the window or dialog box.

If you specify an invalid ID, the compiler displays an error message. This option is supported in graphical interfaces only, and only in Windows.

SPACE ( n )

Identifies the number (n) of blank spaces to insert after the displayed expression. The n can be 0. If the number of spaces you specify is more than the spaces left on the current line of the frame, the AVM starts a new line and discards extra spaces. If you do not use this option or you do not use n, the AVM inserts one space between items in the frame.

SKIP ( n )

Identifies the number (n) of blank lines to insert after the displayed expression. The number of blank lines can be can be 0. If you do not use this option, the AVM does not skip a line between expressions unless the expressions do not fit on one line. If you use the SKIP option but do not specify n, or if n is 0, the AVM starts a new line unless it is already at the beginning of a new line.

record

Represents the name of the record you want to display. Naming a record is shorthand for listing each field individually, as a form item.

EXCEPT field . . .

Tells the AVM to display all the fields in the frame except those fields listed in the EXCEPT phrase.

HEADER

Tells the AVM to place the following items in a header section at the top of the frame in a separate field group from all other data. In addition to fields, variables, and constants, the frame header can contain expressions, images, and rectangles. The AVM reevaluates these expressions each time it displays the frame.

When you use the FORM statement with the HEADER option, ABL disregards Data Dictionary field labels for fields you name in the FORM statement. Use character strings to specify labels for fields you name in the frame header.

BACKGROUND

Specifies that any following frame items display in the frame background, behind the data and header in a separate field group. Typically, this option is used to display images or rectangles behind the data.

head-item

A description of a value to be displayed in the frame header or background, or a SPACE or SKIP directive. This is the syntax for head-item:

 

Syntax 

expression [ format-phrase ]

 

constant [ at-phrase | TO n ] [ BGCOLOR expression ] [ DCOLOR expression ] [ FGCOLOR expression ] [ FONT expression ] [ VIEW-AS TEXT ]   [ WIDGET-ID id-number ]

 

SPACE [ ( n ) ]

 

SKIP [ ( n ) ]

This is exactly the same as the syntax for a form-item, except that a head-item can be an expression and does not include the PFCOLOR option. If you use an expression in a HEADER or BACKGROUND phrase, the expression is evaluated each time the frame is viewed. If you give the PAGE-TOP or PAGE-BOTTOM option for the frame, the expression is evaluated for each page. This allows you, for example, to include a reference to the PAGE-NUMBER function in the frame header.

Note:

If head-item is an expression, any option of the format-phrase may be used with it; if head-item is a constant, only the AT phrase, TO, BGCOLOR, DCOLOR, FGCOLOR, FONT, VIEW-AS TEXT, and WIDGET-ID options are allowed.

frame-phrase

Specifies frame options for the frame associated with the FORM statement. For more information on frame-phrase options, see the Frame phrase reference entry.

Examples 

This procedure lets the user update information on a specific Customer. The FORM statement describes a very specific layout for the UPDATE statement to use.

 

r-form.p

REPEAT FOR Customer:   FORM     Customer.Name COLON 10 Customer.Phone COLON 50     Customer.Address COLON 10 Customer.SalesRep COLON 50 SKIP     Customer.City COLON 10 NO-LABEL Customer.State NO-LABEL       Customer.PostalCode NO-LABEL     WITH SIDE-LABELS 1 DOWN CENTERED.   PROMPT-FOR Customer.CustNum WITH FRAME cnum SIDE-LABELS CENTERED.   FIND Customer USING Customer.CustNum.   UPDATE Customer.Name Customer.Address Customer.City Customer.State     Customer.PostalCode Customer.Phone Customer.SalesRep. END.

When you use the FORM statement to control the order in which fields appear on the screen, remember that this order is independent of the order in which the AVM processes the fields during data entry.

In the example, the above FORM statement displays the customer name first and the phone number second. But the UPDATE statement specifies the phone number after the name, address, city, state, and postal-code. The fields are displayed as described in the FORM statement, but the tab order is determined by the UPDATE statement.

The following example uses the HEADER option:

 

r-eval.p

DEFINE VARIABLE ix AS INTEGER NO-UNDO FORMAT ">9".   FORM HEADER "This is the header - ix is" ix   WITH FRAME a ROW ix COLUMN ix ix DOWN.   DO ix = 1 TO 8 WITH FRAME a DISPLAY ix. PAUSE. END.

The FORM statement defines a HEADER frame that consists of the text “This is the header - ix is” and the value of the variable ix. In addition, it also specifies a screen location where the header is displayed. The FORM statement does not bring the header frame into view.

On the first iteration of the DO block, the DISPLAY statement brings the frame into view. On the second iteration of the DO block, the frame is already in view (it was not hidden during the first iteration), so the header of the frame is not re-evaluated. Thus, the new value of ix is not reflected in the header portion of the frame, and you do not see the new value of ix in the header. You also do not see the position of the frame on the screen change.

In contrast, look at this modified version of the procedure:

 

r-eval2.p

DEFINE VARIABLE ix AS INTEGER NO-UNDO FORMAT ">9".   FORM HEADER "This is the header - ix is" ix   WITH FRAME a ROW ix COLUMN ix ix DOWN.   DO ix = 1 TO 8 WITH FRAME a: DISPLAY ix. HIDE FRAME a. END.

On the first iteration of the DO block, the DISPLAY statement displays the frame. The HIDE statement removes the frame from the window. Therefore, on the second iteration of the DO block, the DISPLAY statement redisplays the frame. The AVM re-evaluates the header of the frame each time the frame is redisplayed. Therefore, the header of the frame reflects the change to i, and the position of the frame in the window also changes.

Notes 

When you use any of the statements that access the screen, you can name a frame or use the default frame for the block where the statements appears. For more information on frame scoping, see OpenEdge Getting Started: ABL Essentials.

When ABL compiles a procedure, it makes a top-to-bottom pass of the procedure to design all the frames for that procedure, including those referenced in FORM statements. ABL adds field and format attributes as it goes through the procedure.

If you have enabled application-defined widget IDs in your ABL GUI application, by specifying the Use Widget ID (–usewidgetid) startup parameter, then the AVM uses the value specified in the WIDGET-ID option to set the WIDGET-ID attribute for this widget when it creates the widget at run time, instead of using the widget ID it normally generates by default. If you have not enabled application-defined widget IDs, then the AVM ignores this option setting at run time.

For more information about the WIDGET-ID attribute, see its reference entry in the “Handle Attributes and Methods Reference” section. For more information about the Use Widget ID (–usewidgetid) startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference.

If you use a single qualified identifier with the FORM statement, the compiler first interprets the reference as dbname.tablename. If the compiler cannot resolve the reference as dbname.tablename, it tries to resolve it as tablename.fieldname. When naming fields in a FORM statement, you must use table names that are different from field names to avoid ambiguous references. See the Record phrase reference entry for more information.

To use the FORM statement to display a record in a table defined for multiple databases, you must qualify the record’s table name with the database name. See the Record phrase reference entry for more information.

If you define a frame to use as a DDE frame, you must realize the frame (display it) before using it as a conversation end-point. If you want the DDE frame to remain invisible during its use in a DDE conversation, set its HIDDEN attribute to TRUE after realizing the frame. For information on DDE frames, see OpenEdge Development: Programming Interfaces.

See also 

DEFINE FRAME statement, Format phrase, Frame phrase