Format phrase

Specifies one or more attributes for a widget.

Syntax

[ `at-phrase` ] [ AS `datatype` \| LIKE `field` ] [ ATTR-SPACE \| NO-ATTR-SPACE ] [ AUTO-RETURN ] [ BGCOLOR `expression` ] [ BLANK ] [ COLON `n` \| TO `n` ] [ COLUMN-LABEL `label` ] [ DEBLANK ] [ DCOLOR `expression` ] [ DISABLE-AUTO-ZAP ] [ FGCOLOR `expression` ] [ FONT `expression` ] [ FORMAT `string` ] [ HELP `string` ] [ LABEL `label` [ , `label` ] ... \| NO-LABELS ] [ NO-TAB-STOP ] [ PFCOLOR `expression` ] [ VALIDATE ( `condition` , `msg-expression` ) ] [ `view-as-phrase` ] [ WIDGET-ID `id-number` ]

[ at-phrase ] 
[ AS datatype | LIKE field ] 
[ ATTR-SPACE | NO-ATTR-SPACE ] 
[ AUTO-RETURN ] 
[ BGCOLOR expression ] 
[ BLANK ] 
[ COLON n | TO n ] 
[ COLUMN-LABEL label  ] 
[ DEBLANK ] 
[ DCOLOR expression ] 
[ DISABLE-AUTO-ZAP ] 
[ FGCOLOR expression ] 
[ FONT expression ] 
[ FORMAT string ] 
[ HELP string ] 
[ LABEL label [ , label ] ... | NO-LABELS ] 
[ NO-TAB-STOP ] 
[ PFCOLOR expression ] 
[ VALIDATE ( condition , msg-expression ) ] 
[ view-as-phrase ] 
[ WIDGET-ID id-number ]

at-phrase

The column, row and column, or x and y pixel location you want the display to start. The AT option does not left justify the data; it simply indicates the placement of the data area.

Syntax
AT { `n` \| { COLUMN `column` \| COLUMN-OF `relative-position` } { ROW `row` \| ROW-OF `relative-position` } [ COLON-ALIGNED \| LEFT-ALIGNED \| RIGHT-ALIGNED ] \| { X `x` \| X-OF `relative-position` } { Y `y` \| Y-OF `relative-position` } [ COLON-ALIGNED \| LEFT-ALIGNED \| RIGHT-ALIGNED ] }

AT {    n 
      | { COLUMN column | COLUMN-OF relative-position } 
         { ROW row | ROW-OF relative-position } 
         [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ] 
      | { X x | X-OF relative-position } 
         { Y y | Y-OF relative-position } 
         [ COLON-ALIGNED | LEFT-ALIGNED | RIGHT-ALIGNED ] 
   }

See the AT phrase reference entry for more information.

AS datatype

Creates a frame field and variable with the data type you specify. This is useful for defining display positions in a frame for use with DISPLAY @ field.

LIKE field

Creates a frame field and variable with the same definition as field.

The LIKE option in a DEFINE VARIABLE statement, DEFINE WORK-TABLE statement, or Format phrase requires that a particular database is connected. Since you can start up an ABL application session without connecting to a database, use the LIKE option with caution.

ATTR-SPACE | NO-ATTR-SPACE

Has no effect; supported only for backward compatibility.

AUTO-RETURN

Causes the AVM to automatically move out of a field as if you pressed RETURN. When you enter the last character in the field, the AVM automatically moves out of the field. If this happens on the last field of a data entry statement, the AVM functions as if you pressed GO.

For the purposes of AUTO-RETURN, entering leading zeros in a numeric field does not count as filling the field. For example, suppose you define a numeric field as follows:


DEFINE VARIABLE x AS INTEGER NO-UNDO FORMAT "99". SET x AUTO-RETURN.

If you enter a 09 into the field, the AVM does not AUTO-RETURN. To get the AUTO-RETURN behavior in this situation, define the field as CHARACTER with a format of "99".

BGCOLOR expression

Specifies the background color of the widget in graphical interfaces. This option is ignored in character interfaces.

BLANK

Displays blanks for the field you are displaying or entering. This is useful for entering passwords.

COLON n

The number (n) of the column in which you want the colon of the label to appear. Use this option with SIDE-LABEL frames where the labels are placed to the left of the data and are separated from the data with a colon.

TO n

The number (n) of the column in which you want to end the display. The TO option does not right justify the data; it indicates the placement of the data area.

COLUMN-LABEL label

Names the label you want to display above the field. If you want the label to use more than one line (stacked labels), use an exclamation point (!) in the label to indicate where to break the line. For example:

r-colbl.p
FOR EACH Customer NO-LOCK: DISPLAY Customer.Name COLUMN-LABEL "Customer!Name" Customer.SalesRep COLUMN-LABEL "Name of!Sales!Representative". END.

The AVM does not display column labels if you use the SIDE-LABELS or the NO-LABELS option with the Frame phrase.

You must enclose the label string in quotation marks. If you want to use the exclamation point (!) as one of the characters in a column label, use two exclamation points (!!).

DEBLANK

Removes leading blanks (for use on input character fields only). Leading blanks in the value before input are not removed unless the user changes the value.

DCOLOR expression

Specifies the display color of the widget in character interfaces. This attribute is ignored in graphical interfaces.

DISABLE-AUTO-ZAP

Specifies whether the value of the AUTO-ZAP attribute will be ignored. See the AUTO-ZAP attribute reference entry. This option only applies to fill-ins.

The following example defines a frame with two fill-ins, both of which specify the DISABLE-AUTO-ZAP option:


DEFINE FRAME frame-a fill-in-1 DISABLE-AUTO-ZAP fill-in-2 DISABLE-AUTO-ZAP button-1 WITH THREE-D SIDE-LABELS.

FGCOLOR expression

Specifies the foreground color of the widget in graphical interfaces. This option is ignored in character interfaces.

FONT expression

Specifies the font of the widget.

FORMAT string

Represents the format in which you want to display the expression. You must enclose string in quotation marks (""). If you do not use the FORMAT option, ABL uses the defaults shown in Table 38.

Table 38: Default display formats
Type of expression	Default format
Field	Format from Dictionary
Variable	Format from variable definition
Constant character	Length of character string
Other	Default format for the data type of the expression

Table 39 lists the default formats for the Other expression.

Table 39: Default data type display formats
Data type	Default display format
CHARACTER	x(8)
CLASS¹	N/A
DATE	99/99/99
DATETIME	99/99/9999 HH:MM:SS.SSS
DATETIME-TZ	99/99/9999 HH:MM:SS.SSS+HH:MM
DECIMAL	->>,>>9.99
HANDLE²	>>>>>>9
INT64	->,>>>,>>9
INTEGER	->,>>>,>>9
LOGICAL	yes/no
MEMPTR³	See the footnote at the end of this table.
RAW³	See the footnote at the end of this table.
RECID	>>>>>>9
ROWID³	See the footnote at the end of this table.

¹If you display a class instance using the MESSAGE statement, ABL automatically invokes the ToString( ) method (provided by the Progress.Lang.Object class) on the object reference. To display a class instance in a frame (for example, using the DISPLAY statement), you must first explicitly convert the object reference to a displayable type using the INT64 function, the INTEGER function, the STRING function, or the ToString( ) method.

²To display a HANDLE, you must first convert it using either the INT64 or INTEGER function and display the result.

³You cannot display a MEMPTR, RAW, or ROWID value directly. However, you can convert it to a character string representation using the STRING function and display the result. A ROWID value converts to a hexadecimal string, “0xhexdigits,” where hexdigits is any number of characters “0" through “9" and “A” through “F”. A MEMPTR or RAW value converts to decimal integer string.

You can use the FORMAT option with the UPDATE and SET statements to store a character string that is longer than the field length you define in the Data Dictionary or in a DEFINE VARIABLE statement. This is possible because ABL stores data in variable-length fields.


DEFINE VARIABLE mychar AS CHARACTER NO-UNDO FORMAT "x(3)". UPDATE mychar FORMAT "x(8)".

You can also use the ASSIGN statement to store data in a field or variable that is longer than the predefined format of that field or variable.


mychar = "abcdefgh".

However, the Data Dictionary load program only loads character data that is no longer than the format you defined in the Dictionary. For more information on data formats, see OpenEdge Getting Started: ABL Essentials.

HELP string

Represents a character string that you want to display whenever the user enters the frame field for the field or variable. When the user leaves the frame field, the AVM removes the help string from the message area. You must enclose the string in quotation marks ("").

If the input source is not the terminal, the AVM disregards any HELP options.

LABEL label [ , label ] . . .

Represents a character string that you want to use as a label for a field, variable, or expression. You must enclose the string in quotation marks (""). Table 40 shows the order ABL uses to determine the label for a field, variable, or expression.

Table 40: Determining labels
	LABEL string	Dictionary label	Field name	LIKE field	Variable name
Field	1	2	3	N/A	N/A
Variable	1	N/A	N/A	2	3
Expression	1	N/A	N/A	N/A	N/A

Note: If you use side labels, Windows allows a user to transfer focus to field-level widgets by pressing ALT and one of the letters in the widget’s label. This is called a mnemonic. Specify the letter by preceding it with an ampersand (&) when specifying the LABEL option. Ending a label with an ampersand might produce undesired behavior. If you want a literal ampersand within a label, enter two ampersands (&&) in label. If you specify more than one widget with the same mnemonic, the AVM transfers focus to each of these in tab order when you make a selection.

NO-LABELS

Prevents the AVM from displaying a label for a field, variable, or expression.

NO-TAB-STOP

Specifies that the widget is not in its parent frame’s tab order.

The following example shows defining a frame with two fill-ins, both of which have the NO-TAB-STOP option specified:


DEFINE FRAME frame-a fill-in-1 fill-in-2 button-1 NO-TAB-STOP WITH THREE-D SIDE-LABELS.

See the TAB-STOP attribute reference entry for related information.

PFCOLOR expression

Specifies the prompt color of the widget in character interfaces. This attribute is ignored in graphical interfaces.

VALIDATE ( condition, msg-expression )

Specifies a value that you want to validate against the data entered into a screen field or variable. The condition is a Boolean expression (a constant, field name, variable name, or expression) whose value is TRUE or FALSE.

When you use the VALIDATE option to validate a specific field, any reference to that field in condition is assumed to be an input field. For example, in the following statement, the AVM assumes the PromiseDate field is an input field:


SET Order.OrderDate Order.PromiseDate VALIDATE(Order.PromiseDate > Order.OrderDate, "Promise date must be later than order date").

The previous statement is equivalent to the following statement:


SET Order.OrderDate Order.PromiseDate VALIDATE(INPUT Order.PromiseDate > Order.OrderDate, "Promise date must be later than order date").

The validation is based on the value of OrderDate prior to the SET statement. If you want to validate the value of PromiseDate against the input value of OrderDate, use this statement:


SET Order.OrderDate Order.PromiseDate VALIDATE(Order.PromiseDate > INPUT Order.OrderDate, "Promise date must be later than order date").

If you try to validate a field whose reference is ambiguous, the AVM tries to resolve the ambiguity by referencing the table that contains the record being updated. In the following example, the SalesRep field is ambiguous because it exists in both the Order table and the Customer table. The AVM resolves the ambiguity by validating the SalesRep field in the Order table, since the Order table is being updated.


FIND FIRST Customer. FIND FIRST Order. UPDATE Order.CustNum Order.SalesRep VALIDATE(LENGTH(Order.SalesRep) > 1, "Invalid sales rep value.").

If the reference is to an array field and has no subscript, the AVM assumes you want to use the subscript of the field that is being prompted.

If the value of condition is FALSE, use msg-expression to display a specific message. You must enclose msg-expression in quotation marks (" ").

The AVM processes validation criteria whenever the user attempts to leave the frame field. If the frame field value is not valid, the AVM displays msg-expression in the message area, causes the terminal to beep, and does not advance out of the frame field.

If you tab a frame field, make no changes, and leave the field, the AVM does not process the validation criteria specified with the VALIDATE option until the you press GO (F1). If you press ENDKEY or END-ERROR, or an error occurs, the AVM does not test the validation criteria specified with the VALIDATE option.

If the input source for the procedure is a table, the AVM validates each input field (except those with a value of "-"). If the result of the validation is FALSE, msg-expression is displayed and the AVM treats the validation as an error.

To suppress the Data Dictionary validation criteria for a field, use this VALIDATE option:


VALIDATE(TRUE,"")

When you use the VALIDATE option in a procedure to specify validation criteria for a field, that validation criteria applies to all other references to that field in the same frame:


FOR EACH Order: UPDATE Order.OrderDate. UPDATE Order.OrderDate VALIDATE(Order.OrderDate LE TODAY, "Can’t be later than today"). END.

In this example, the AVM applies the validation criteria on the second UPDATE statement. The AVM also applies the validation criteria to the first UPDATE statement because both UPDATE statements use the same frame. Scope references to the same field to different frames if you do not want a VALIDATE option to affect all references to that field.

view-as-phrase

Specifies the type of widget. This is the syntax for view-as-phrase:

Syntax
VIEW-AS { `editor-phrase` \| FILL-IN [ NATIVE ] [ `size-phrase` ] \| `radio-set-phrase` \| `selection-list-phrase` \| `slider-phrase` \| TEXT [ `size-phrase` ] \| TOGGLE-BOX [ `size-phrase` ] }

For more information on view-as-phrase, see the VIEW-AS phrase reference entry.

WIDGET-ID id-number

Specifies a widget ID for a field or variable widget 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.

Example

This procedure lets the user update Customer records after entering the password “secret.” The format phrase on the Phone field describes the display format of that field.

r-frmat.p
DEFINE VARIABLE password AS CHARACTER NO-UNDO. UPDATE password FORMAT "x(6)" BLANK VALIDATE(password = "secret", "Sorry, wrong password") HELP "Maybe the password is ’secret’ !" WITH FRAME passw CENTERED SIDE-LABELS. HIDE FRAME passw. REPEAT: PROMPT-FOR Customer.CustNum COLON 20. FIND Customer USING Customer.CustNum. UPDATE Customer.Name LABEL "Customer Name" COLON 20 VALIDATE(Customer.Name NE "", "Please enter a name") Customer.Address HELP "Please enter two lines of address" COLON 20 LABEL "Address" Customer.Address2 NO-LABEL COLON 20 Customer.City COLON 20 Customer.State COLON 20 Customer.PostalCode COLON 20 SKIP(3) Customer.Phone AT 5 FORMAT "(999) 999-9999" Customer.Contact TO 60 WITH CENTERED SIDE-LABELS. END.

r-frmat.p

DEFINE VARIABLE password AS CHARACTER NO-UNDO. 
UPDATE password FORMAT "x(6)" BLANK 
  VALIDATE(password = "secret", "Sorry, wrong password") 
  HELP "Maybe the password is ’secret’ !" 
  WITH FRAME passw CENTERED SIDE-LABELS. 
HIDE FRAME passw. 
REPEAT: 
  PROMPT-FOR Customer.CustNum COLON 20. 
  FIND Customer USING Customer.CustNum. 
  UPDATE 
    Customer.Name LABEL "Customer Name" COLON 20 
      VALIDATE(Customer.Name NE "", "Please enter a name") 
    Customer.Address HELP "Please enter two lines of address" 
      COLON 20 LABEL "Address" 
    Customer.Address2 NO-LABEL COLON 20 
    Customer.City COLON 20 
    Customer.State COLON 20 
    Customer.PostalCode COLON 20 SKIP(3) 
    Customer.Phone AT 5 FORMAT "(999) 999-9999" 
    Customer.Contact TO 60 
    WITH CENTERED SIDE-LABELS. 
END.

Notes

The ATTR-SPACE/NO-ATTR-SPACE designation in a Frame phrase takes precedence over an ATTR-SPACE/NO-ATTR-SPACE designation in a Format phrase. The ATTR-SPACE/NO-ATTR-SPACE designation in a Format phrase takes precedence over an ATTR-SPACE/NO-ATTR-SPACE designation in a COMPILE statement.

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

For SpeedScript, these options are invalid: BGCOLOR, DCOLOR, FGCOLOR, FONT, PFCOLOR, view-as-phrase.

With respect to internationalization, some double-byte and UTF-8 multi-byte characters display and print in one or two columns. Each unit in the format string represents one physical column. To display or print a character that requires two columns, the FORMAT phrase must specify two columns. For more information, see OpenEdge Development: Internationalizing Applications.