Specifies the overall layout and processing properties of a frame for frame definition (DEFINE FRAME and FORM), block header (DO, FOR EACH, and REPEAT), and data handling (DISPLAY, SET, etc.) statements. When used on block header statements, the Frame phrase also specifies the default frame for data handling statements within the block. Frame phrases can also be used on individual data handling statements to indicate the specific frame where the statement applies.
WITH [ ACCUM [ max-length ]] [ at-phrase ][ ATTR-SPACE | NO-ATTR-SPACE ] [ CANCEL-BUTTON button-name][ CENTERED ] [ color-specification] [ COLUMN expression][n COLUMNS ] [ CONTEXT-HELP ][ CONTEXT-HELP-FILE help-file-name] [ DEFAULT-BUTTON button-name] [ DROP-TARGET ] [[expression] DOWN ][ EXPORT ] [ WIDGET-ID id-number][ FONT expression] [ FRAME frame] [ INHERIT-BGCOLOR | NO-INHERIT-BGCOLOR ] [ INHERIT-FGCOLOR | NO-INHERIT-FGCOLOR ] [ KEEP-TAB-ORDER ][ NO-BOX ] [ NO-HIDE ][ NO-LABELS ][ USE-DICT-EXPS ] [ NO-VALIDATE ][ NO-AUTO-VALIDATE ] [ NO-HELP ][ NO-UNDERLINE ] [ OVERLAY ][ PAGE-BOTTOM | PAGE-TOP ][ RETAIN n] [ ROW expression][ SCREEN-IO | STREAM-IO ] [ SCROLL n][ SCROLLABLE ][ SIDE-LABELS ] [ size-phrase][ STREAM stream| STREAM-HANDLE handle][ THREE-D ] [ title-phrase][ TOP-ONLY ][ USE-TEXT ] [ V6FRAME [ USE-REVVIDEO | USE-UNDERLINE ]] [ VIEW-AS DIALOG-BOX ][ WIDTH n][ IN WINDOW window] |
The ACCUM option lets you use aggregate functions (such as MAX, MIN, TOTAL, and SUBTOTAL) to accumulate values within shared frames. With the ACCUM option, aggregate values can be shared among procedures through shared frames. You must include the ACCUM option in the FORM statement or DEFINE FRAME statement of each procedure that uses the shared frame.
The following procedure defines a new shared frame:
The following procedure uses the shared frame:
/* testb.p */ DEFINE SHARED FRAME x. FORM field1 field2 WITH FRAME x ACCUM. FOR EACH table1: DISPLAY field1 field2 (TOTAL) WITH FRAME x. END. |
When you specify a user-defined aggregate label, use the max-length parameter of the ACCUM option to specify a maximum aggregate label length in the frame phrases of shared frames. For more information, see the Aggregate phrase reference entry.
Specifies the position of the frame (upper-left corner) within a window or parent frame. This is the syntax for the AT phrase for a frame:
Note that for a frame parented by a window, you must specify an absolute position relative to the display area of the window. For a frame parented by another frame, you must specify a position relative to the display area of the parent frame. The default value for all AT phrase parameters is 1. ABL ignores the COLUMN or X option if you use the CENTERED option for the same frame. For more information on at-phrase, see the AT phrase reference entry.
Centers the frame horizontally in the window or frame to which it is parented (or the terminal display, in character mode). If you use the CENTERED option and are sending output to a device other than the terminal, the AVM centers the frame for the terminal. This might result in a non-centered frame on the alternate output device.
You can also use the AT phrase or COLUMN option to specify the position of the frame.
For a graphical user interface, specifies the foreground and background color of the frame; for a character interface, specifies the display and prompt colors for the frame.
[ { [ BGCOLOR expression]
[ DCOLOR expression]
[ FGCOLOR expression]
[ PFCOLOR expression]
}
|{ COLOR [ DISPLAY ]color-phrase
[ PROMPT color-phrase]
}
]
|
For graphical interfaces, the FGCOLOR and BGCOLOR options specify the foreground and background color of the frame. These options are not supported in character interfaces. For character interfaces, use the DCOLOR and PFCOLOR options (which are not supported in graphical interfaces) to specify the display color and prompt color of the frame.
The COLOR option is obsolete, but is retained for backward compatibility.
Widgets (except child frames) within the frame inherit the colors of the frame by default. You can also set the colors of each widget individually.
The AVM evaluates expression each time the frame comes into view or is printed at the top or bottom of a page (if the frame is a PAGE-TOP or PAGE-BOTTOM frame). For more information, see the expression option of the FORM statement.
When you use this option, it forces SIDE-LABELS and overrides any AT, COLON, TO, or SPACE options you might have used in the same Frame phrase.
Down frames are typically specified for iterative blocks. On the first iteration of the block, the AVM displays the first set of data (a record, field, or variable value) as the first occurrence in the frame. After displaying the data, the AVM advances to the next occurrence in the frame on the second iteration of the block, and displays the second set of data there. The AVM continues advancing and displaying data for the number of occurrences specified by expression, and prompts to continue with another set of occurrences until all the data has been displayed. The AVM evaluates expression each time the frame comes into view or is printed at the top or bottom of a page (if the frame is a PAGE-TOP or PAGE-BOTTOM frame). If you do not specify expression, the AVM displays as many occurrences as can fit in the current window.
If you do not use the DOWN option, ABL automatically makes certain frames down frames, unless you specify otherwise (1 DOWN). For more information on frames and down frames, see OpenEdge Getting Started: ABL Essentials.
If you specify an invalid ID, the compiler displays an error message. This option is supported in graphical interfaces only, and only in Windows.
Specifies whether the following field-level widgets in the frame inherit the frame's background color: BROWSE, COMBO-BOX (all types), EDITOR, FILL-IN (NATIVE and Enabled), and SELECTION-LIST.
Specify the INHERIT-BGCOLOR option to allow field-level widgets in the frame to inherit the frame's background color. Specify the NO-INHERIT-BGCOLOR option to prevent field-level widgets in the frame from inheriting the frame's background color.
Specifying either of these options overrides the INHERIT-BGCOLOR attribute setting for the session. Setting the frame's INHERIT-BGCOLOR attribute overrides the INHERIT-BGCOLOR option on the frame. Setting the BGCOLOR attribute for a field-level widget within the frame overrides any INHERIT-BGCOLOR attribute or option settings.
Specifies whether the following field-level widgets in the frame inherit the frame's foreground color: BROWSE, COMBO-BOX (all types), EDITOR, FILL-IN (NATIVE and Enabled), and SELECTION-LIST.
Specify the INHERIT-FGCOLOR option to allow field-level widgets in the frame to inherit the frame's foreground color. Specify the NO-INHERIT-FGCOLOR option to prevent field-level widgets in the frame from inheriting the frame's foreground color.
Specifying either of these options overrides the INHERIT-FGCOLOR attribute setting for the session. Setting the frame's INHERIT-FGCOLOR attribute overrides the INHERIT-FGCOLOR option on the frame. Setting the FGCOLOR attribute for a field-level widget within the frame overrides any INHERIT-FGCOLOR attribute or option settings.
Prevents the frame-oriented I/O statements, ENABLE, UPDATE, SET, and PROMPT-FOR, from changing the tab order of your widgets in the frame. The tab order always remains the same as the order in which you first specify widgets in the frame. If you do not specify this option, ABL creates a new tab order based on the order specified in each frame-oriented I/O statement.
All attributes and methods that affect tab order (such as FIRST-TAB-ITEM and MOVE-AFTER-TAB), continue to change the tab order whether or not you specify this option. If you specify the option, these attributes and methods specify a new tab order for all frame-oriented I/O statements that follow.
Does not display a box around the frame. If you do not use this option, the AVM displays a box around the data you are displaying.
If you are sending data to a device other than a terminal and you do not use this option, the AVM omits the sides and bottom line of the box and replaces the top line with blanks.
Suppress the automatic hiding of the frame (when the block where the frame is scoped iterates). The frame is hidden only if space is needed to display other frames.
NO-HIDE suppresses hiding for a frame only when the block where that frame is scoped iterates. For example:
FOR EACH Customer NO-LOCK:
DISPLAY Customer.CustNum Customer.Name.
FOR EACH Order OF Customer NO-LOCK:
DISPLAY Order.OrderNum.
DISPLAY "hello" WITH FRAME b COLUMN 60 NO-HIDE.
END.
END.
|
In this example, the AVM does not hide frame b when the inner block iterates. However, it does hide frame b when the outer block iterates. If you want the frame to stay in view during iterations of the outer block, scope the frame to that block.
Ensures that validation expressions and help strings from the Data Dictionary are compiled into the application. Typically, when the ABL compiler encounters a field reference in an input statement, Data Dictionary help and validation expressions are compiled in for that field, unless the field has a HELP or VALIDATE option (format phrase) attached in the input statement (or earlier in the procedure). In this case, the custom help or validation expression is used.
In Progress Version 7 and later, there are two syntax constructs that can enable a field for input without the compiler specifically knowing about it: ENABLE ALL and widget-name:SENSITIVE = YES.
When ABL encounters an ENABLE ALL statement, every field in the associated frame has Data Dictionary validation expressions and help strings compiled into the application. This closes any possible validation or help hole. As a side-effect, validation expressions and help strings that are not required might be compiled, but this will not affect the application.
This behavior places two important conditions on you. First, adding a field to a frame after the first ENABLE ALL is not desirable. Data Dictionary validation and help will not be compiled for this field. Second, any custom validation or help must come before the first ENABLE ALL. A good practice is to include these in the DEFINE FRAME or FORM statements.
In the case of widget-name:SENSITIVE = YES, there is more potential for validation and help holes. Since the compiler cannot predict whether these statements are used, in effect, as input statements, no help or validation is compiled. USE-DICT-EXPS explicitly compiles in all validation expressions and help strings for a frame. For each frame that you use widget-name:SENSITIVE = YES, specify USE-DICT-EXPS. This closes any potential validation or help holes. To provide custom help or validation when using USE-DICT-EXPS, the HELP or VALIDATE option must appear in the first reference to that field. Typically, this is in the DEFINE FRAME or FORM statement.
Indicates that the frame can overlay any other frame that does not use the TOP-ONLY option. If you do not use this option, the frame you are using cannot overlay other frames. If the AVM needs to display an OVERLAY frame and doing so will partially obscure a TOP-ONLY frame, it first hides the TOP-ONLY frame. Any frame parented by another frame is an OVERLAY frame within the parent frame.
This procedure uses the OVERLAY option on the Frame phrase:
r-ovrlay.p
FOR EACH Customer NO-LOCK:
DISPLAY Customer WITH 2 COLUMNS
TITLE "Customer Information".
FOR EACH Order OF Customer NO-LOCK:
DISPLAY Order WITH 2 COLUMNS OVERLAY
TITLE "Customer's Orders" ROW 7 COLUMN 10.
END.
END.
|
The procedure above displays customer information in one frame. The procedure then displays order information for the customer in a second frame that overlays the first.
Displays the frame each time the output begins on a new page.
The following table shows how the PAGE-TOP and PAGE-BOTTOM options work depending on the kind of DISPLAY or VIEW.
| Pseudo-code | OUTPUT to a PAGED file | OUTPUT to the screen or an UNPAGED file |
|---|---|---|
| DISPLAY a PAGE-TOP Frame | The frame is written to the file and put on a list of frames to be written at the top of each page. | The frame is written to the file or displayed on the screen. |
| VIEW a PAGE-TOP Frame | The frame is put on a list of frames to be written at the top of each page. | The frame is written to the file or displayed on the screen. |
| DISPLAY a PAGE-BOTTOM Frame | The frame is written to the file and put on a list of frames to be written at the bottom of each page. | The frame is written to the file or displayed on the screen. |
| VIEW a PAGE-BOTTOM Frame | The frame is put on a list of frames to be written at the bottom of each page. | The frame is written to the file or displayed on the screen. |
| HIDE Either Type | The frame is removed from the appropriate list. | The frame is removed from the screen. |
The AVM evaluates expression each time the frame comes into view or is printed at the top or bottom of a page (if the frame is a PAGE-TOP or PAGE-BOTTOM frame).
For more info, see the expression option of the FORM statement.
If you specify STREAM-IO for a frame, the USE-TEXT option is assumed and all font specifications are ignored. The frame is formatted using a fixed font in a manner appropriate for streaming to a text file or printer. In particular, all border padding for FILL-IN widgets is dropped and the default system font is used.
If you use the STREAM-IO option on the COMPILE statement, this behavior is the default for all frames in the procedure. In this case, you can override that option by specifying SCREEN-IO for an individual frame.
This procedure uses the SCROLL option to scroll the display one line at a time:
r-fphrsc.p
FOR EACH Customer NO-LOCK WHERE Customer.CustNum <= 50: DISPLAY Customer.CustNum Customer.Name Customer.CreditLimit WITH SCROLL 1 USE-TEXT. IF Customer.CreditLimit >= 50000 THEN COLOR DISPLAY MESSAGES Customer.CreditLimit. END. |
Do not use the RETAIN option in a Frame phrase in which you also use the SCROLL option.
For more information on size-phrase, see the SIZE phrase reference entry.
TITLE
[ { [ BGCOLOR expression ]
[ DCOLOR expression ]
[ FGCOLOR expression ]
}
| COLOR color-phrase ]
[ FONT expression ] title-string
|
The title-string is a constant, field name, variable name, or expression whose result is a character value. The expression is the value you want to display as a title. If title-string is a constant character string, it must be surrounded by quotes (""). The AVM automatically centers title-string in the top line of the frame box.
The BGCOLOR, FGCOLOR, COLOR, and FONT options have no effect and are supported for backward compatibility only.
You can use the DCOLOR option to specify the color of the title in a character interface.
The V6FRAME option is designed specifically to compile and run Progress Version 6 applications with Progress Version 7 or later in Windows. This option uses the V6FontNumber setting in the [Startup] section of the current environment to calculate the height and width of a character unit and then set the layout grid used to compile frames for display in Progress Version 7 or later.
At run time, the FONT attribute for a frame compiled with the V6FRAME option is set to the font number specified with the V6FontNumber setting. The default setting for the V6FontNumber setting is 3.
By default, V6FRAME displays a border around a fill-in field. This means that your code requires more space on the screen than in Progress Version 6. You can override this behavior with one of the following options:
The V6FRAME option also limits the vertical size of a frame title to one character unit based upon the layout grid. The text of the frame title is in the font specified with the V6FontNumber setting in the [Startup] section of the current environment.
The V6FRAME option governs the appearance of screen output only. Use the STREAM-IO option to compile procedures that output to files and printers. If you specify the V6FRAME and STREAM-IO options in the same frame phrase, the STREAM-IO option overrides the V6FRAME option.
For more information on the environment for an ABL session, see OpenEdge Deployment: Managing ABL Applications.
The r-frame.p procedure displays the CustNum, Name, and Phone number for each Customer record. The frame phrase (starting with the word WITH) describes the frame being used to display that information.
r-frame.p
FOR EACH Customer NO-LOCK:
FORM HEADER
"No-box, No-Underline, No-labels, 5 DOWN" SKIP
"Centered" SKIP(2)
WITH NO-BOX NO-UNDERLINE NO-LABELS CENTERED 5 DOWN.
DISPLAY Customer.CustNum Customer.Name Customer.Phone.
END.
|
The r-frame2.p procedure produces a Customer report, using Customer List as the header for each page of the report and using Customer List Continued On Next Page as the footer for each page of the report. The OUTPUT TO statement directs all output to the file phone.lst. After running the r-frame2.p procedure, you can press GET then type the name of the file to view the contents of phone.lst.
r-frame2.p
OUTPUT TO phone.lst PAGED PAGE-SIZE 20.
FOR EACH Customer NO-LOCK:
FORM HEADER "Customer List" AT 1 PAGE-NUMBER TO 60
WITH FRAME hdr PAGE-TOP CENTERED NO-BOX.
VIEW FRAME hdr.
FORM "Customer List Continued On Next Page"
WITH FRAME footr PAGE-BOTTOM CENTERED.
VIEW FRAME footr.
DISPLAY Customer.CustNum Customer.Name Customer.Phone WITH CENTERED.
END.
HIDE FRAME footr.
OUTPUT CLOSE.
|
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.