Progress
Language Reference
DEFINE FRAME Statement
Defines and creates a frame or dialog box that can be used within a procedure or shared among several procedures.
SYNTAX
NEW SHARED FRAME frame
Defines a frame to be shared by a procedure called directly or indirectly by the current procedure. The called procedure must name the same frame in a DEFINE SHARED FRAME statement.
SHARED FRAME frame
Defines a frame that was created by another procedure that used the DEFINE NEW SHARED FRAME statement. When you use the DEFINE SHARED FRAME statement, you cannot name any fields or variables in that frame that are not already named in the frame described by the DEFINE NEW SHARED FRAME statement.
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 is owned by a single field group, duplicated for each data iteration in the frame.
This is the syntax for form-item.
field
Specifies a field-level widget 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, and 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 where you want the right edge of the value. 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 displays as a TEXT widget rather than as a FILL-IN.
SPACE ( n )
Identifies the number (n) of blank spaces to insert after the expression displays. 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 expression is displayed. 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 HEADER option, Progress disregards Data Dictionary field labels for fields you name in the DEFINE FRAME statement. Use character strings to specify labels on fields you name in the frame header.
BACKGROUND
Specifies that any following frame items are displayed 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 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 lets you include a reference to the PAGE-NUMBER function in the frame header.
DROP-TARGET
Indicates whether you want to be able to drop a file onto the object.
frame-phrase
Specifies additional options for the frame, including the VIEW-AS DIALOG-BOX option to define the frame as a dialog box. For more information on frame and dialog box options, see the Frame Phrase reference entry.
EXAMPLESThe following example,
r-deffrm.p
, uses the DEFINE FRAME statement to set up the format of a frame. It then scopes that frame to a FOR EACH block.
The following example defines three frames. The cust-info frame is scoped to the trigger for the b_next button where it is first referenced. Similarly, the cust-dtl frame is scoped to the b_dtl trigger. The butt-frame frame is scoped to the outer procedure block.
The following example uses a set of thin rectangles as lines to create graphic columns within a frame background.
The following procedure defines the shared frame cust-frame. It also defines a shared variable and a shared buffer. For each customer whose customer number is less than 20, the procedure displays customer information in the cust-frame. The format for the cust-frame is defined in the
r-shrfrm.i
include file.
After the
r-shrfrm.p
procedure displays the customer information, it calls ther-updord.p
procedure.The
r-updord.p
procedure defines the variable, frame, and buffer that were originally defined in ther-shrfrm.p
procedure. However, in this second reference to the items, the keyword NEW is omitted. Ther-updord.p
procedure displays, and lets you update, the order information for the customer displayed in the cust-frame. The order information is displayed in the same frame.
The following example,
r-fof1.p
, creates a dialog box to display customer information from a query. The dialog box contains three child frames to display customer contact information (FRAME cont-fr), customer account information (FRAME acct-fr), and control buttons for moving through the query results list (FRAME ctrl-fr).
NOTE
- You cannot define a SHARED or NEW SHARED frame widget in a persistent procedure. If you do, Progress raises ERROR on the RUN statement that creates the procedure.
- If you do not specify the font for a frame, Progress uses the system default font, not the font of the window. This is because Progress determines the frame layout at compile time when the window’s fonts (known at runtime) are not yet available.
- You can use just one DEFINE FRAME statement per frame in a procedure.
- If you name variables or parent child frames to a shared frame, Progress does not automatically make those variables and child frames shared. If you want to share the variables and child frames among procedures, you must define each variable and frame using the SHARED option in all the sharing procedures.
- Progress scopes a newly defined frame to the block that first references the frame. (The DEFINE FRAME statement does not count as a reference.) Progress scopes a shared frame outside of the called procedure.
- The frame-phrase options specified in a DEFINE NEW SHARED FRAME statement are carried over to all corresponding DEFINE SHARED FRAME statements and cannot be overridden.
- You can use different field-level help and validation in new shared, and shared frames.
- You must define a shared frame before referencing that frame in a procedure.
- All frame fields and Frame phrase options in a shared frame must first be defined in the initial DEFINE NEW SHARED FRAME statement or an additional FORM statement in the same procedure. Procedures that share this frame only have to define fields that correspond to the fields in the initial definition plus any specified ACCUM option. Other Frame phrase options for the SHARED frames are allowed, but are ignored except for the ACCUM option. This allows you to make use of the same FORM statement in an include file for both the NEW SHARED and matching SHARED frames. See the FORM Statement reference entry for more information.
- If you use an Aggregate phrase to accumulate a value within a shared frame, you must also use the ACCUM option in each procedure that uses the shared frame.
- 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
DEFINE BUFFER Statement, DEFINE VARIABLE Statement, FORM Statement, Frame Phrase, RUN Statement
Copyright © 2004 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095 |