Progress
Language Reference


Frame Phrase

Interfaces
OS
SpeedScript
All
All
Yes

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 ]
     [ [ expression ] DOWN ] [ EXPORT ] [ FONT expression ]
     [ FRAME frame ] [ 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 ] [ 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, as shown in the following examples.

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

/* 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 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. Progress 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

No effect; supported for backward compatibility only.

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 on 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, Progress 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, Progress 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. Progress ignores this option if you use the CENTERED option for the same frame.

Progress 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. Progress 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, Progress 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 for Windows GUI only.

CONTEXT-HELP-FILE help-file-name

Specifies the complete path name 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 for Windows GUI only.

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, Progress 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.

[ 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, Progress displays the first set of data (a record, field, or variable value) as the first occurrence in the frame. After displaying the data, Progress advances to the next occurrence in the frame on the second iteration of the block, and displays the second set of data there. Progress 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. Progress 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, Progress displays as many occurrences as can fit in the current window.

If you do not use the DOWN option, Progress automatically makes certain frames down frames, unless you specify otherwise (1 DOWN). For more information on frames and down frames, see the Progress Programming Handbook .

EXPORT

This option is valid only for SQL.

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, Progress 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, Progress combines the characteristics on each Frame phrase naming that frame. Progress 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, Progress uses the default frame for the current block.

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, Progress 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 to follow.

NO-BOX

Does not display a box around the frame. If you do not use this option, Progress 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, Progress 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 EACH customer:
  DISPLAY cust-num name.
  FOR EACH  order OF customer:
    DISPLAY order.order-num.
    DISPLAY "hello" WITH FRAME b COLUMN 60 NO-HIDE.
  END.
END. 

In this example, Progress 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 Progress 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 Progress 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 the 4GL programmer. 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 Progress to compile into the code all relevant validations it finds in the Progress 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 Progress 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:
  DISPLAY customer WITH 2 COLUMNS 
    TITLE "Customer Information".
  FOR EACH order OF customer:
    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 30 shows how the PAGE-TOP and PAGE-BOTTOM options work depending on the kind of DISPLAY or VIEW.

Table 30: Using PAGE-TOP and PAGE-BOTTOM Frames 
 
OUTPUT To A PAGED File
OUTPUT To 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 Progress 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, Progress 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, Progress displays a root frame at the next available row of the window and displays a child frame at row 1 of the parent frame.

Progress 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 WHERE cust-num <= 50:
   DISPLAY cust-num name credit-limit WITH SCROLL 1 USE-TEXT.
   IF credit-limit >= 50000
   THEN COLOR DISPLAY MESSAGES credit-limit.
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, Progress 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.

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.

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 (""). Progress automatically centers title-string in the top line of the frame box.

You can use the BGCOLOR and FGCOLOR options to specify the background and foreground color of the title in a graphical interface. You can use the DCOLOR option to specify the color of the title in a character interface. The COLOR option is obsolete and is retained only for backward compatibility.

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 Progress has to display an OVERLAY frame and by doing so will partially obscure a TOP-ONLY frame, it first hides the TOP-ONLY frame. For more information, see the OVERLAY Statement 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 for 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.

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" in this manual.

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, Progress displays the frame in the current window.

EXAMPLES

The r-frame.p procedure displays the cust-num, 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:
  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 cust-num name 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:    

  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 cust-num name phone WITH CENTERED.
END.
HIDE FRAME footr.
OUTPUT CLOSE. 

NOTES

SEE ALSO

DEFINE FRAME Statement, FORM Statement, Format Phrase, FRAME-COL Function, FRAME-DOWN Function, FRAME-LINE Function, FRAME-ROW Function


Copyright © 2004 Progress Software Corporation
www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095