Progress
Language Reference


DEFINE FRAME Statement

Interfaces
OS
SpeedScript
All
All
Yes

Defines and creates a frame or dialog box that can be used within a procedure or shared among several procedures.

SYNTAX

DEFINE [ [ NEW ] SHARED ] FRAME frame
  [ form-item ... ]
  [ DROP-TARGET ]
  [{ HEADER | BACKGROUND } head-item ... ]
  { [ frame-phrase ] } 

DEFINE [ [ NEW ] SHARED ] FRAME frame
  record [ EXCEPT field ... ]
  [ DROP-TARGET ]
  { [ frame-phrase ] } 

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.

SYNTAX
{     field [ format-phrase ]
   |  constant [ at-phrase | { TO n } ] 
       [ BGCOLOR expression ]
       [ DCOLOR expression ]
       [ FGCOLOR expression ] 
       [ FONT expression ]
       [ PFCOLOR expression ]
       [ VIEW-AS TEXT ] 
   |  SPACE [ ( n ) ]
   |  SKIP  [ ( n ) ]
} 

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.

SYNTAX
AT { COLUMN column | COLUMN-OF reference-point } 
   { ROW row | ROW-OF reference-point }
   [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ] 

AT { X x | X-OF reference-point }
   { Y y | Y-OF reference-point } 
   [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ] 

AT n 

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.

SYNTAX
{     expression [ format-phrase ]
   |  constant [ at-phrase | { TO n } ] 
        [ BGCOLOR expression ]
        [ DCOLOR expression ]
        [ FGCOLOR expression ] 
        [ FONT expression ]
        [ VIEW-AS TEXT ] 
   |  SPACE [ ( n ) ]
   |  SKIP  [ ( n ) ]
} 

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.

EXAMPLES

The 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.

r-deffrm.p
DEFINE VARIABLE bal-avail LIKE customer.balance
            COLUMN-LABEL "Available!Credit" NO-UNDO.

DEFINE FRAME cust-bal 
  customer.cust-num
  customer.name FORMAT "X(20)"
  customer.credit-limit LABEL "Limit"
  customer.balance
  bal-avail
  WITH CENTERED ROW 3 TITLE "Available Customer Credit" USE-TEXT.
 
FOR EACH customer NO-LOCK WITH FRAME cust-bal:
  DISPLAY customer.cust-num
          customer.name
          customer.credit-limit
          customer.balance
          customer.credit-limit - customer.balance @ bal-avail.
END. 

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.

r-dffrm1.p
DEFINE BUTTON b_dtl LABEL "Detail".
DEFINE BUTTON b_next LABEL "Next".
DEFINE BUTTON b_quit LABEL "Quit" AUTO-ENDKEY.

DEFINE FRAME cust-info 
  customer.cust-num
  customer.name FORMAT "X(20)"
  customer.phone
  WITH CENTERED ROW 4.

DEFINE FRAME cust-dtl
  customer except customer.cust-num customer.name customer.phone
  WITH CENTERED SIDE-LABELS ROW 9.

DEFINE FRAME butt-frame
  b_dtl b_next b_quit
  WITH ROW 1.
  
ON CHOOSE OF b_dtl
  DISPLAY customer except customer.cust-num customer.name customer.phone
    WITH FRAME cust-dtl.
    
ON CHOOSE OF b_next
DO:
  HIDE FRAME cust-dtl.
  FIND NEXT customer NO-LOCK NO-ERROR.
  IF NOT AVAILABLE customer
  THEN FIND LAST customer NO-LOCK.

  DISPLAY customer.cust-num
          customer.name
          customer.phone
    WITH FRAME cust-info.
END.

ENABLE ALL WITH FRAME butt-frame.

APPLY "CHOOSE" TO b_next IN FRAME butt-frame.

WAIT-FOR CHOOSE OF b_quit. 

The following example uses a set of thin rectangles as lines to create graphic columns within a frame background.

r-bkgrnd.p
DEFINE VARIABLE item-tot AS DECIMAL LABEL "Value" NO-UNDO.

DEFINE RECTANGLE vline1 SIZE .4 BY 5 EDGE-PIXELS 2.
DEFINE RECTANGLE vline2 LIKE vline1.
DEFINE RECTANGLE vline3 LIKE vline1.
DEFINE RECTANGLE vline4 LIKE vline1.
DEFINE RECTANGLE vline5 LIKE vline1.
DEFINE RECTANGLE vline6 LIKE vline1.

DEFINE RECTANGLE hline SIZE 78 BY .1 EDGE-PIXELS 2.

DEFINE FRAME item-info
  item.item-num
  item.item-name
  item.on-hand
  item.re-order
  item.on-order
  item.price
  item-tot
  BACKGROUND skip(1) hline
    vline1 AT 9
    vline2 AT 25
    vline3 AT 33
    vline4 AT 42
    vline5 AT 51
    vline6 AT 65
  WITH TITLE "Inventory Current Value" CENTERED USE-TEXT 5 DOWN.
  
FOR EACH item NO-LOCK WITH FRAME item-info:
  DISPLAY item.item-num
    item.item-name
    item.on-hand
    item.re-order
    item.on-order
    item.price
     item.on-hand * item.price @ item-tot. 

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.

r-shrfrm.p
DEFINE NEW SHARED FRAME cust-frame.
DEFINE NEW SHARED VARIABLE csz AS CHARACTER FORMAT "x(29)".
DEFINE NEW SHARED BUFFER xcust FOR customer.

FOR EACH xcust WHERE  cust-num <=20:

      {r-shrfrm.i}  /* include file for layout of shared frame */

DISPLAY name phone address sales-rep
  city + ", " + st + " " + postal-code @ csz
  credit-limit WITH FRAME cust-frame.

RUN r-updord.p.  /* External procedure to update customer’s orders */
END. 

r-shrfrm.i
FORM  xcust.name         COLON 10
      xcust.phone        COLON 55
      xcust.address      COLON 1
      xcust.sales-rep    COLON 55
      csz NO-LABEL       COLON 10
      xcust.credit-limit COLON 55
      SKIP(2)
      order.order-num    COLON 10    order.order-date   COLON 30
      order.ship-date    COLON 30
      order.promise-date COLON 30  WITH SIDE-LABELS 1 DOWN CENTERED ROW 5
      TITLE   "Customer/Order Form" FRAME cust-frame. 

After the r-shrfrm.p procedure displays the customer information, it calls the r-updord.p procedure.

The r-updord.p procedure defines the variable, frame, and buffer that were originally defined in the r-shrfrm.p procedure. However, in this second reference to the items, the keyword NEW is omitted. The r-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.

r-updord.p
DEFINE SHARED FRAME cust-frame.
DEFINE SHARED VARIABLE csz  AS CHARACTER FORMAT "x(29)".
DEFINE SHARED BUFFER xcust FOR customer.

FOR EACH order OF xcust:

  {r-shrfrm.i }  /* include file for layout of shared frame */

DISPLAY order.order-num WITH FRAME cust-frame.
UPDATE order.order-date order.ship-date order.promise-date
   WITH FRAME cust-frame.
END. 

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).

r-fof1.p
DEFINE QUERY custq FOR customer.
DEFINE BUTTON bprev LABEL "<".
DEFINE BUTTON bnext LABEL ">".
DEFINE FRAME cust-fr SKIP(.5)
    SPACE(8) customer.name customer.cust-num customer.sales-rep
    customer.comments AT COLUMN 6 ROW 13.5
    WITH SIDE-LABELS TITLE "Customer Data" 
        SIZE 80 BY 15 VIEW-AS DIALOG-BOX.
DEFINE FRAME cont-fr SKIP(.5)
    customer.address COLON 17 SKIP
    customer.address2 COLON 17 SKIP
    customer.city COLON 17 SKIP
    customer.state COLON 17 SKIP 
    customer.postal-code COLON 17 SKIP
    customer.country COLON 17 SKIP
    customer.contact COLON 17 SKIP 
    customer.phone COLON 17
    WITH SIDE-LABELS TITLE "Contact Informaion" 
        SIZE 40 BY 10 AT COLUMN 1 ROW 3. 
DEFINE FRAME ctrl-fr SKIP(.12)
    SPACE(4) bprev bnext
    WITH TITLE "PREVIOUS/NEXT"
        SIZE 15 BY 2 AT COLUMN 53 ROW 10.5.
DEFINE FRAME acct-fr SKIP(.5)
    customer.balance COLON 15 SKIP 
    customer.credit-limit COLON 15 SKIP
    customer.discount COLON 15 SKIP 
    customer.terms COLON 15    
    WITH SIDE-LABELS TITLE "Account Information"
        SIZE 38.85 BY 6 AT COLUMN 41 ROW 3.

ON CHOOSE OF bnext DO:
    GET NEXT custq.
    IF NOT AVAILABLE customer THEN GET FIRST custq.
    RUN display-proc IN THIS-PROCEDURE.
END.

ON CHOOSE OF bprev DO:
    GET PREV custq.
    IF NOT AVAILABLE customer THEN GET LAST custq.
    RUN display-proc IN THIS-PROCEDURE.
END.

FRAME cont-fr:FRAME = FRAME cust-fr:HANDLE.
FRAME acct-fr:FRAME = FRAME cust-fr:HANDLE.
FRAME ctrl-fr:FRAME = FRAME cust-fr:HANDLE.

OPEN QUERY custq PRESELECT EACH customer BY customer.name.
GET FIRST custq.
RUN display-proc IN THIS-PROCEDURE.
ENABLE ALL WITH FRAME ctrl-fr.

WAIT-FOR WINDOW-CLOSE OF FRAME cust-fr.

PROCEDURE display-proc:
    DISPLAY 
        customer.name customer.cust-num customer.sales-rep
        customer.comments WITH FRAME cust-fr.
    DISPLAY
        customer.address customer.address2 customer.city customer.state 
        customer.postal-code customer.country customer.contact 
        customer.phone WITH FRAME cont-fr.
    DISPLAY 
        customer.balance customer.credit-limit
        customer.discount customer.terms WITH FRAME acct-fr.
END. 

NOTE

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