Defines and creates a frame or dialog box that is created at compile time for use in one or more procedures, or within a single class.

Syntax

DEFINE {[[ NEW ] SHARED ]|[ PRIVATE ]} FRAME frame
  [form-item...]
  [{ HEADER | BACKGROUND }head-item...]
  {[frame-phrase]}
 
DEFINE {[[ NEW ] SHARED ]|[ PRIVATE ]} FRAME frame
  record[ EXCEPT field...]
  {[frame-phrase]}
NEW SHARED FRAME frame
Defines and identifies 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 and identifies 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.
[ PRIVATE ] FRAME frame

Defines and identifies a frame widget as a class-scoped object. A class-scoped handle-based object is not a member of a class, but provides a resource that is privately available to the class definition similar to a non-shared data element in a procedure definition. The option to specify the PRIVATE access mode is provided for readability. You cannot specify PRIVATE when defining a frame widget as a data element in a method or procedure.

Note: This option is applicable only when defining a class-scoped frame widget in a class definition (.cls) file.
FRAME frame
Defines and identifies a frame widget for access only within the current procedure, class, or method of a class.
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[format-phrase]
   |  constant[ at-phrase | { TO n }] 
       [ BGCOLOR expression]
       [ DCOLOR expression]
       [ FGCOLOR expression] 
       [ FONT expression]
       [ PFCOLOR expression]
       [ VIEW-AS TEXT ] 
       [ WIDGET-ID id-number]
   |  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 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:

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.
WIDGET-ID id-number

Specifies a widget ID for a field-level widget or value to display in a frame. 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.

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, the AVM starts a new line and discards extra spaces. If you do not use this option or you do not use n, the AVM 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 0. If you do not use this option, the AVM 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, the AVM 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 the AVM to display all the fields in the frame except those fields listed in the EXCEPT phrase.
HEADER

Tells the AVM 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. The AVM reevaluates these expressions each time it displays the frame.

When you use the HEADER option, the AVM disregards OpenEdge 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. Following is the syntax for head-item:

{     expression[format-phrase]
   |  constant[at-phrase|{ TO n}] 
        [ BGCOLOR expression]
        [ DCOLOR expression]
        [ FGCOLOR expression] 
        [ FONT expression]
        [ VIEW-AS TEXT ] 
        [ WIDGET-ID id-number]
   |  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.

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.CustNum
  Customer.Name FORMAT "X(20)"
  Customer.CreditLimit 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.CustNum
    Customer.Name
    Customer.CreditLimit
    Customer.Balance
    Customer.CreditLimit - 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.CustNum
  Customer.Name FORMAT "X(20)"
  Customer.Phone
  WITH CENTERED ROW 4.

DEFINE FRAME cust-dtl
  Customer EXCEPT Customer.CustNum Customer.Name Customer.Phone
  WITH SIDE-LABELS ROW 9 WIDTH 100.

DEFINE FRAME butt-frame
  b_dtl b_next b_quit
  WITH ROW 1.  

ON CHOOSE OF b_dtl
  DISPLAY Customer EXCEPT Customer.CustNum 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.CustNum 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 NO-UNDO LABEL "Value".

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.ItemNum
  Item.ItemName
  Item.OnHand
  Item.ReOrder
  Item.OnOrder
  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.ItemNum
    Item.ItemName
    Item.OnHand
    Item.ReOrder
    Item.OnOrder
    Item.Price
    Item.OnHand * 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 xcust.CustNum <=20:
  {r-shrfrm.i}    /* shared frame layout */

  DISPLAY xcust.Name xcust.Phone xcust.Address xcust.SalesRep
    xcust.City + ", " + xcust.State + " " + xcust.PostalCode @ csz
    xcust.CreditLimit WITH FRAME cust-frame.

  RUN r-updord.p. /* Update Customer's orders */
END.

Following is the r-shrfrm.i include file:

r-shrfrm.i 

FORM
  xcust.Name COLON 10
  xcust.Phone COLON 55
  xcust.Address COLON 1
  xcust.SalesRep COLON 55
  csz NO-LABEL COLON 10
  xcust.CreditLimit COLON 55 SKIP(2)
  Order.OrderNum COLON 10 Order.OrderDate COLON 30
  Order.ShipDate COLON 30
  Order.PromiseDate 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 NO-UNDO FORMAT "x(29)".
DEFINE SHARED BUFFER xcust FOR Customer.

FOR EACH Order OF xcust:
  {r-shrfrm.i }  /* shared frame layout */

  DISPLAY Order.OrderNum WITH FRAME cust-frame.
  UPDATE Order.OrderDate Order.ShipDate Order.PromiseDate
    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.CustNum Customer.SalesRep
 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.PostalCode 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.CreditLimit 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.CustNum Customer.SalesRep
    Customer.Comments WITH FRAME cust-fr.
  DISPLAY
    Customer.Address Customer.Address2 Customer.City Customer.State
    Customer.PostalCode Customer.Country Customer.Contact Customer.Phone
    WITH FRAME cont-fr.
  DISPLAY 
    Customer.Balance Customer.CreditLimit Customer.Discount Customer.Terms
    WITH FRAME acct-fr.
END PROCEDURE.

Notes

  • You cannot define a SHARED or NEW SHARED frame widget in a persistent procedure. If you do, ABL raises ERROR on the RUN statement that creates the procedure.
  • You cannot define a SHARED or NEW SHARED frame widget in a class definition (.cls) file. If you do, ABL generates a compilation error.
  • If you do not specify the font for a frame, ABL uses the system default font, not the font of the window. This is because ABL determines the frame layout at compile time when the window's fonts (known at run time) 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, ABL 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.
  • ABL scopes a newly defined frame to the block that first references the frame. (The DEFINE FRAME statement does not count as a reference.) ABL 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 OpenEdge 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. For more information about the Use Widget ID (-usewidgetid) startup parameter, see Startup Command and Parameter Reference.

See also

Class-based data member access, DEFINE BUFFER statement, DEFINE VARIABLE statement, FORM statement, Frame phrase, RUN statement