ENABLE statement

Enables input for one or more field-level and child frame widgets within a frame.

Data movement

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` ]

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.

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.