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 { 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 NO-UNDO 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.
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 */
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.
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 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. For more information about the Use Widget ID (-usewidgetid) startup parameter, see OpenEdge Deployment: Startup Command and Parameter Reference.