Enables input for one or more field-level and
child frame widgets within a frame.
Syntax
ENABLE [ UNLESS-HIDDEN ]
{ ALL [ EXCEPT field...]
|{ field [ format-phrase ] [ WHEN expression ]
| TEXT ( { field [ format-phrase ]
[ WHEN expression ] } ... )
| constant [ AT n | TO n ]
[ BGCOLOR expression ]
[ DCOLOR expression ]
[ FGCOLOR expression ]
[ FONT expression ]
[ PFCOLOR expression ]
[ VIEW-AS TEXT ]
| SPACE [ ( n ) ]
| SKIP [ ( n ) ]
} ...
}
[ IN WINDOW window ] [ frame-phrase ]
|
- ALL [ EXCEPT field...]
- Specifies that all field-level widgets for a frame are enabled,
except those you list.
- UNLESS-HIDDEN
- Restricts ENABLE to fields whose HIDDEN attribute is FALSE.
-
field
- Specifies the name of the field, variable, or widget you want
to enable. Remember that the ENABLE statement accepts input only
and stores it in the screen buffer. The underlying record buffer
of a field or variable is unaffected unless you ASSIGN the value.
In
array fields, array elements with constant subscripts are treated
just like any other field. Array fields with no subscripts or array
fields in the FORM statement are expanded as though you had entered
the implicit elements. See the DISPLAY statement reference
entry for information on how array fields with expressions as subscripts
are handled.
Note: You cannot enable unfixed indeterminate
array variables.
-
format-phrase
- Specifies one or more frame attributes for a field, variable,
or expression. For more information on format-phrase,
see the Format phrase reference entry.
- WHEN expression
- Enables the field only if expression has a value of TRUE when the
ENABLE statement is executed. Here, expression is a field name,
variable name, or expression that evaluates to a LOGICAL value.
- TEXT
- Defines a group of character fields or variables (including
array elements) to use automatic text-wrap. The TEXT option works
only with character fields. When you insert data in the middle of
a TEXT field, the AVM wraps data that follows into the next TEXT
field, if necessary. If you delete data from the middle of a TEXT
field, the AVM wraps data that follows into the empty area.
If
you enter more characters than the format for the field allows,
the AVM discards the extra characters. The character fields must
have formats in the form x(n). A blank in the first column of a
line marks the beginning of a paragraph. Lines within a paragraph
are treated as a group and will not wrap into other paragraphs.
- constant
[ AT n
| TO n
]
[ BGCOLOR expression
]
[ DCOLOR expression
]
[ FGCOLOR expression
]
[ FONT expression ]
[ PFCOLOR expression
]
[ VIEW-AS TEXT ]
- Specifies a constant (literal) value that you want displayed in the frame. If you use
the AT option, n is the column in which you want to start the
display. If you use the TO option, n is the column in which you want
to end the display. You can use the BGCOLOR and FGCOLOR options in graphical interfaces
to define the foreground and background colors to use when the constant is displayed.
Similarly, you can use the DCOLOR and PFCOLOR options in character interfaces to define
the prompt and display colors to use when the constant is displayed. The font option,
for both character and graphical interfaces, defines the font used. If you use the
VIEW-AS TEXT option, the constant is displayed as a text widget rather than a fill-in
field.
- SPACE [ (n) ]
- Identifies the number (n) of blank spaces to insert after the field
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 any extra spaces. If you do not use this option or n, the
AVM inserts one space between items in the frame.
- SKIP [ (n) ]
- Identifies the number (n) of blank lines to insert after the field
is displays. The n 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.
- ^
- Tells the AVM to ignore an input field when input is being read from a file.
- IN WINDOW window
- Specifies the window in which the widgets are enabled. The window parameter
must be the name of a currently defined window or an expression
that evaluates to the handle for a currently defined window.
- frame-phrase
- The frame that contains the widgets to enable. If you omit frame-phrase,
the default frame for the current block is assumed. For more information
on frame-phrase, see the Frame phrase reference
entry.
Example
The
following example enables the CustNum field and the
Quit button in the main procedure. If you press GO in the CustNum field
and successfully find a record, the trigger disables the CustNum field
and enables the CreditLimit field and the Save
and Undo buttons. If you choose Save or Undo, the CHOOSE trigger
disables the buttons and enables the CustNum field
again. Note that if you choose the Save button, the trigger must
execute an ASSIGN statement to set the value in the underlying database
field.
r-enable.p
DEFINE VARIABLE ok AS LOGICAL NO-UNDO.
DEFINE BUTTON b_quit LABEL "Quit" AUTO-ENDKEY.
DEFINE BUTTON b_save LABEL "Save".
DEFINE BUTTON b_undo LABEL "Undo".
DEFINE FRAME butt-frame
b_save b_undo b_quit
WITH CENTERED ROW SCREEN-LINES - 2.
FORM customer
WITH FRAME cust-info SIDE-LABELS CENTERED
TITLE "Update Customer Credit Limit".
ON CHOOSE OF b_save, b_undo IN FRAME butt-frame DO:
DISABLE b_save b_undo WITH FRAME butt-frame.
DISABLE Customer.CreditLimit WITH FRAME cust-info.
ENABLE Customer.CustNum WITH FRAME cust-info.
IF SELF:LABEL = "save" THEN
ASSIGN FRAME cust-info Customer.CreditLimit.
CLEAR FRAME cust-info NO-PAUSE.
APPLY "ENTRY" TO Customer.CustNum IN FRAME cust-info.
END.
ON GO OF Customer.CustNum IN FRAME cust-info DO:
FIND Customer USING Customer.CustNum EXCLUSIVE NO-ERROR.
IF AVAILABLE Customer THEN DO:
DISABLE Customer.CustNum WITH FRAME cust-info.
ENABLE Customer.CreditLimit WITH FRAME cust-info.
ENABLE ALL WITH FRAME butt-frame.
DISPLAY Customer WITH FRAME cust-info.
END.
ELSE DO:
MESSAGE "No customer record exists for customer number"
INPUT Customer.CustNum ", Please re-enter."
VIEW-AS ALERT-BOX WARNING BUTTONS OK-CANCEL UPDATE OK.
IF NOT ok THEN
APPLY "CHOOSE" TO b_quit IN FRAME butt-frame.
END.
END.
ENABLE Customer.CustNum WITH FRAME cust-info.
ENABLE b_quit WITH FRAME butt-frame.
WAIT-FOR CHOOSE OF b_quit IN FRAME butt-frame
FOCUS Customer.CustNum IN FRAME cust-info.
|
Notes
- For
field representation widgets, the ENABLE statement lets you change
the widget's SCREEN-VALUE. If you want to save changes to the field
itself, you must subsequently use the ASSIGN statement.
During
data entry, a validation expression defined for the field in the database
or in a Format phrase executes only if the widget associated with the
field receives input focus. Use the VALIDATE( ) method
to execute a validation expression defined for a field regardless
of whether it receives input focus or not.
- If you invoke the ENABLE statement for a frame, the AVM brings
the frame into view unless the HIDDEN attribute for the frame or
one of its ancestor frames or windows is TRUE.
- If you invoke the ENABLE statement for the parent frame of a
frame family, the field representation widgets and descendant frames
owned by the parent frame are all enabled. However, the field representation
widgets of the descendant frames remain disabled and visually insensitive.
To enable field representation widgets in the descendant frames
and make them sensitive, you must invoke ENABLE statements for each
of the descendant frames.
- If you specify the KEEP-TAB-ORDER option for a frame, the ENABLE
statement has no affect on the tab order for the frame. Otherwise,
the ENABLE statement can affect the tab order of widgets within
the frame.
- The tab order for fields specified by the ENABLE statement replaces any
conflicting tab order established by previous ENABLE statements
or by previous settings of the FIRST-TAB-ITEM, LAST-TAB-ITEM, MOVE-AFTER-TAB-ITEM,
or MOVE-BEFORE-TAB-ITEM attributes and methods.
- If you specify the ALL option with the ENABLE statement, the
tab order of fields corresponds to the order they are specified
in the frame definition. Also, the Data Dictionary field validations
and help messages are compiled for all fields in the frame, including
view-only fields (for example, text widgets).
- If you specify the ENABLE statement with field parameters, the
specified fields are moved in the tab order to the end of the order specified for the
original frame definition, and the tab order of each field corresponds
to the order in which it is specified in the statement. The following code enables three
widgets (a, b, and c) in frame A with the tab order d, e, f, a, b, and c:
DEFINE FRAME A a b c d e f.
ENABLE a b c WITH FRAME A.
|
Note: Note that widgets d, e, and f are not accessible until their
SENSITIVE attributes are set to TRUE.
- If you use more than one ENABLE statement to enable widgets
within a frame, each widget is added to the end of the tab order
as it is enabled. For example, the following code enables three
widgets in a frame:
ENABLE a.
ENABLE b.
ENABLE c.
|
This code sets the tab order as a b c. Rearranging
the ENABLE statements changes the tab order.
- For SpeedScript, these options are invalid: BGCOLOR, DCOLOR, FGCOLOR,
FONT, IN-WINDOW.