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.
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:
constant [ at-phrase | TO n] [ BGCOLOR expression] [ DCOLOR expression] [ FGCOLOR expression] [ FONT expression] [ PFCOLOR expression] [ VIEW-AS TEXT ] [ WIDGET-ID id-number] |
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:
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.
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.
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.
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:
constant [ at-phrase | TO n] [ BGCOLOR expression] [ DCOLOR expression] [ FGCOLOR expression] [ FONT expression] [ VIEW-AS TEXT ] [ WIDGET-ID id-number] |
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.
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.
For more information about the WIDGET-ID attribute, see its reference entry in the Handle Attributes and Methods Reference. For more information about the Use Widget ID (-usewidgetid) startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference.