Progress
Language Reference
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 Progress 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-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.
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 widget 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 AT phrase.
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.
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, Progress starts a new line and discards extra spaces. If you do not use this option or you do not use n, Progress 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, Progress 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, Progress 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 Progress to display all the fields in the frame except those fields listed in the EXCEPT phrase.
HEADER
Tells Progress 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. Progress reevaluates these expressions each time it displays the frame.
When you use the FORM statement with the HEADER option, Progress 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.
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 and VIEW-AS TEXT 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.
EXAMPLESThis procedure lets the user update information on a specific customer. The FORM statement describes a very specific layout for the UPDATE statement to use.
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 Progress 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.
The FORM statement defines a HEADER frame that consists of the text “This is the header - i is” and the value of the variable i. 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 i is not reflected in the header portion of the frame, and you do not see the new value of i 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.
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. Progress 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 the Progress Programming Handbook .
- When Progress 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. Progress adds field and format attributes as it goes through the procedure.
- 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 the Progress External Program Interfaces manual.
SEE ALSO
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |