Frame phrase

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.

Syntax 

 

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 ]

ACCUM [max-length]

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:

 

DEFINE NEW SHARED FRAME x.   FORM field1 field2 WITH FRAME x ACCUM. RUN testb.p.

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.

at-phrase

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:

 

Syntax 

AT { COLUMN column ROW row | X x Y y }

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.

ATTR-SPACE | NO-ATTR-SPACE

Has no effect; supported only for backward compatibility.

CANCEL-BUTTON button-name

Specifies the cancel button for the frame. This is the button chosen when the ESC key code is applied to the frame in Windows. This button might also be chosen when the ESC key code is applied to a frame within the same frame family that does not have a cancel button. In such an event, the AVM searches the frame family in random order. The first cancel button found during this random search is chosen. The button-name argument must be a static button name.

CENTERED

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.

color-specification

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.

 

Syntax 

[ { [ 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.

COLUMN expression

The expression is a constant, field name, variable name or expression whose value is the number of the column, relative to the window or parent frame in which you place the frame. The default value is 1. ABL ignores this option if you use the CENTERED option for the same frame.

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.

n COLUMNS

Formats data fields into a specific number (n) of columns. Truncates labels to 16, 14, and 12 characters when the number of columns is 1, 2, or 3, respectively. ABL reserves a fixed number of positions in each column for labels. For n = 1, 16 positions are allowed for a label; for n = 2, 14 positions are allowed; and for n = 3, 12 positions are allowed. Label positions include room for a colon and a space after the label. Labels are right justified if they are short, and truncated if they are too long. By default, the AVM wraps fields across the frame for as many lines as required, placing labels above the fields.

When you use this option, it implies SIDE-LABELS and overrides any AT, COLON, TO, or SPACE options you might have used in the same Frame phrase.

CONTEXT-HELP

Specifies that context-sensitive help is available for this frame. This option is valid in Windows GUI only.

CONTEXT-HELP-FILE help-file-name

Specifies the complete pathname of a help (.HLP) file associated with this frame. If CONTEXT-HELP-FILE is specified without CONTEXT-HELP, CONTEXT-HELP is assumed. This behavior can be overridden by setting the dialog box’s CONTEXT-HELP attribute to FALSE at run time. This option is valid in Windows GUI only. The pathname can contain Unicode characters. See OpenEdge Development: Internationalizing Applications for more information about Unicode.

DEFAULT-BUTTON button-name

Specifies a default button for the frame. This is the button chosen when the ENTER key code in Windows is invoked for the frame. This button might also be chosen when the ESC key code is applied to a frame within the same frame family that does not have a default button. In such an event, the AVM searches the frame family in random order. The first default button found during this random search is chosen. The button-name argument must be the name of a static button. This button must be defined with the DEFAULT option and cannot display an image.

DROP-TARGET

Indicates whether you want to be able to drop a file onto the object.

[ expression ] DOWN

Specifies that the frame is a down frame. A down frame is a frame that can display multiple occurrences of the set of fields defined in the frame. The expression is a constant, field name, variable name or expression whose value is the number of occurrences you want in the frame. If you specify 1 for expression, the frame is not a down frame.

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.

EXPORT

This option is valid only for SQL.

WIDGET-ID id-number

Specifies a widget ID for a frame widget. 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.

FONT expression

Specifies the font of the frame. All widgets within a frame, except child frames, inherit the font of the frame by default. You can also set the font of each widget individually. By default, the AVM uses the default system font.

FRAME frame

Defines new frames by giving them unique names. Whenever the same frame name is referred to in more than one Frame phrase, ABL combines the characteristics on each Frame phrase naming that frame. ABL also combines any frame characteristics used in data handling statements that name the same frame into the same frame description. This option is redundant for DEFINE FRAME statements. If you do not specify this option, ABL uses the default frame for the current block.

INHERIT-BGCOLOR | NO-INHERIT-BGCOLOR

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.

INHERIT-FGCOLOR | NO-INHERIT-FGCOLOR

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.

KEEP-TAB-ORDER

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.

NO-BOX

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.

NO-HIDE

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.

NO-LABELS

Does not display labels. This option overrides any COLUMN-LABEL option you include in another phrase or statement.

NO-UNDERLINE

Does not underline labels appearing above fields.

USE-DICT-EXPS

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.

NO-VALIDATE

Disregards all validation conditions specified in the Data Dictionary for fields entered in this frame.

NO-AUTO-VALIDATE

Tells ABL to compile into the code all relevant validations it finds in the OpenEdge Data Dictionary, but to run the validations only when the code for the frame or for a field-level child-widget of the frame specifically invokes the VALIDATE() method.

NO-HELP

Disregards all help strings specified in the Data Dictionary for fields entered in this frame.

OVERLAY

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.

PAGE-BOTTOM

Displays the frame at the bottom of the page each time the output ends a page.

PAGE-TOP

Displays the frame each time the output begins on a new page.

Table 42 shows how the PAGE-TOP and PAGE-BOTTOM options work depending on the kind of DISPLAY or VIEW.

 

Table 42:

Using PAGE-TOP and PAGE-BOTTOM frames

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.

RETAIN n

Specifies the number of frame iterations to retain when the frame scrolls on the screen. The n must be a constant. For example, RETAIN 2 causes the AVM to display the last two iterations in a down frame at the top of the frame. If you are using UP to scroll up a window, those two lines are displayed at the bottom of the window. Do not use the SCROLL option in a Frame phrase in which you also use the RETAIN option. By default, the AVM does not retain any iterations in the window that have already been displayed.

ROW expression

The expression is a constant, field name, variable name, function reference, or expression whose value is the row, relative to the window or parent frame in which you place the frame. If you are displaying a frame on a device other than a terminal, this option has no effect. By default, the AVM displays a root frame at the next available row of the window and displays a child frame at row 1 of the parent frame.

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.

[ SCREEN-IO | STREAM-IO ]

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.

SCROLL n

Displays a scrolling frame rather than a paging frame. The value n is a constant that specifies the number of frame iterations to scroll when the frame scrolls in the window. For example, if a procedure uses a DISPLAY or DOWN statement when a scrolling frame is full, the data in the frame scrolls up n iterations (rather than clearing and repainting the frame as it would without the SCROLL option).

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.

SCROLLABLE

If you specify this option, the virtual size of the frame might exceed the physical space allocated for it in the window. If that happens, scrolling is enabled for the frame. If you omit this option, the physical and virtual size of the frame are always the same and scrolling is never enabled for the frame.

SIDE-LABELS

Displays field labels to the left of and centered against the data, separated from the data by a colon (:) and a space. If you do not use the SIDE-LABELS option, the AVM displays labels above their corresponding fields in the frame header and separates the labels from the field values with underlining.

size-phrase

Specifies the size of the frame. This is the syntax for size-phrase:

 

Syntax 

{ SIZE | SIZE-CHARS | SIZE-PIXELS } width BY height

For more information on size-phrase, see the SIZE phrase reference entry.

STREAM stream

Allows you to specify the name of a stream for SQL statements.

STREAM-HANDLE handle

Specifies the handle to a stream. If handle it is not a valid handle to a stream, the AVM generates a run-time error. Note that stream handles are not valid for the unnamed streams. See the chapter on alternate I/O sources in OpenEdge Development: Programming Interfaces for more information on streams and stream handles.

THREE-D

Specifies that the frame and all contained widget appear in three-dimensional format (Windows only). If you specify the THREE-D option for a frame, the default background color is gray rather than the window color. Frames do not inherit the THREE-D setting from a parent window, and child frames do not inherit the THREE-D setting from a parent frame.

title-phrase

Displays a title as part of the top line of the box around a display frame. Following is the syntax for the title-phrase:

 

Syntax 

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.

TOP-ONLY

Indicates that no other frame can overlay this frame. If you do not use this option, other frames that use the OVERLAY option can overlay this frame. If the AVM has to display an OVERLAY frame and by doing so will partially obscure a TOP-ONLY frame, it first hides the TOP-ONLY frame. See also the OVERLAY attribute reference entry.

USE-TEXT

Specifies that the default widget type for all widgets in the frame is TEXT rather than FILL-IN. Thus, all border padding on the widgets is dropped.

V6FRAME [ USE-REVVIDEO | USE-UNDERLINE]

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:

USE-REVVIDEO displays no border around a fill-in field. When a fill-in is enabled for input, the color of the fill-in changes to the color specified with the INPUT setting in the [Colors] section in the current environment. The IBEAM cursor signals that a fill-in field has input focus.

USE-UNDERLINE displays no border around a fill-in widget. When a fill-in is enabled for input, the underline attribute of the font (V6FontNumber) for the fill-in is turned on. The color of a fill-in enabled for input does not change. The IBEAM cursor signals that a fill-in field has input focus.

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.

VIEW-AS DIALOG-BOX

Specifies that the frame is displayed as a dialog box. A dialog box is a modal, one-down frame with many of the properties of a window. Like a window, a dialog box can be moved and programmatically resized, and it acquires scroll bars when it is resized smaller than its original frame dimensions. Unlike a window, it cannot be minimized or maximized; nor can it have a menu bar. As a frame-level widget, it is owned by a window and can contain a frame family, but it cannot be owned by another frame or dialog box. Because it is modal, a dialog box must be disabled before any other widgets in the application can be accessed by the user. For more information on the properties of a dialog box, and to compare them with the properties of a frame, see the “Widget Reference” section.

WIDTH n

Specifies the number (n) of columns in a frame. If you do not use size-phrase or the WIDTH option, the width of the frame is based on the fields you are displaying, the position of the frame, and the width of the current or specified window.

IN WINDOW window

Specifies the window in which the frame is displayed. The value window must be the handle of a window. This option is not allowed in a DISABLE statement. By default, the AVM displays the frame in the current window.

Examples 

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.

Notes 

PAGE-TOP and PAGE-BOTTOM frames are activated based on DISPLAY or VIEW statements as previously described. They are deactivated when the block in which the frames are scoped iterates or ends.

If you use the SIZE phrase for a down frame, then the size you specify determines the number of iterations in the frame. The number of iterations you specify with the DOWN option is ignored.

You can input and output to a frame only when that frame is in full view. Therefore, when you input or output to a frame that is hidden or partially overlayed, the AVM displays the frame first.

An empty WITH clause is valid. If the WITH keyword appears by itself, or in the clause following an earlier WITH, it is ignored. This feature is useful when designing template programs to be called with arguments. For example, a template program with a line like DISPLAY {1} WITH {2} executes correctly even if called with only one argument.

The SIZE phrase and WIDTH options are mutually exclusive. If you specify WIDTH or you specify neither WIDTH nor the SIZE, the height of a frame is based on the fields you are displaying, the position of the frame, and whether or not it is a down frame.

A frame parented by another frame cannot function as a down frame.

If you position a child frame completely outside the virtual area of its parent frame, the AVM raises ERROR at run time when the frame is realized.

If you position a child frame partially within the virtual area of its parent frame or the child frame is larger than the virtual area of the parent frame, the AVM crops the child frame to fit the parent’s virtual area and adds scroll bars to the child.

If you position a child frame partially within the physical area of its parent frame or the child frame is larger than the physical area of the parent frame, the AVM adds scroll bars to the parent.

You cannot specify the VIEW-AS DIALOG-BOX option for a frame used as a DDE frame. For information on DDE frames, see OpenEdge Development: Programming Interfaces.

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.

See OpenEdge Getting Started: ABL Essentials for more information on frames.

For SpeedScript, WebSpeed evaluates the Frame phrase as though you were running a character client. The typical WebSpeed application does not use frames when defining layout. However, if you are using existing ABL code that includes frame layouts, you can iterate through frame children to retrieve validation expressions and help strings. Generally, in SpeedScript programming, the frame serves as a virtual container for widgets. These options are invalid: ATTR-SPACE, NO-ATTR-SPACE, CENTERED, CONTEXT-HELP, CONTEXT-HELP-FILE, DEFAULT-BUTTON, SCROLLBAR VERTICAL, V6FRAME, USE-REVVIDEO, USE-UNDERLINE, VIEW-AS DIALOG-BOX, IN WINDOW.

See also 

DEFINE FRAME statement, FORM statement, Format phrase, FRAME-COL function, FRAME-DOWN function, FRAME-LINE function, FRAME-ROW function, Stream object handle