BUTTONEDIT item type

Defines a line-edit with a push-button that can trigger an action.

BUTTONEDIT item basics

The BUTTONEDIT form item defines an edit field that gets user input, with an additional push button that can fire an action.

This type of form field is typically used to open a secondary window, to let the user choose from a large list of items and set the field value.

Defining a BUTTONEDIT

The IMAGE attribute of a BUTTONEDIT form item defines the picture to be displayed on the button.

By default, the text editor of a BUTTONEDIT allows the user to change the field value. Use the NOTEDITABLE attribute to deny text modification. The field still gets the focus, and the action button remains active, if there is a corresponding action handler in the current dialog.

BUTTONEDIT ...
   IMAGE = "zoom",
   NOTEDITABLE;

The button of BUTTONEDIT form items can inherit action default attributes, to avoid having to specify the IMAGE attributes in all elements bound to the same action. For more details, see Configuring actions.

Most of the attributes described in the EDIT item type can also be used with the BUTTONEDIT.

Front-ends support different presentation and behavior options, which can be controlled by a STYLE attribute. For more details, see Common style attributes and ButtonEdit style attributes.

Detecting BUTTONEDIT button action

The button of a BUTTONEDIT form element acts as an action view for a dialog action, and is bound to the ON ACTION handler by the ACTION attribute.

Important: The BUTTONEDIT button will be ghosted, if the field is not managed by a current dialog, or when the field is disabled. For example, if a MENU defines the ON ACTION lookup handler and the BUTTONEDIT has ACTION=lookup, the button will NOT be active, because the field is not active during a MENU statement. The button is also ghosted when the field is controlled by an non-menu dialog, but is disabled with DIALOG.setFieldActive() or defined as NOENTRY.

In the form, the ACTION attribute of BUTTONEDIT defines the name of the action to be sent to the program when the user clicks on the button. In the program, the action handler is defined with an ON ACTION block:

-- Form file:
BUTTONEDIT ...
   ACTION = open_city_list;

-- Program file:
ON ACTION open_city_list
   -- Open the city pick-list

The button action of a BUTTONEDIT can also be a prefixed with a sub-dialog identifier and/or field name, to define a qualified action view to be used in conjunction with ON ACTION action-name INFIELD field-name. However, for convenience, even if the action is not qualified with a field name, the runtime system considers that action as field-qualified, to make the BUTTONEDIT button always active.

For more details, see Binding action views to action handlers, Field-specific actions (INFIELD clause).

Where to use a BUTTONEDIT

A BUTTONEDIT form item can be defined in different ways:

With an item tag and a BUTTONEDIT item definition in a grid-layout container (GRID, SCROLLGRID and TABLE).
As a BUTTONEDIT stack item in a STACK container.

Defining the widget size

In a grid-based layout, the size of a BUTTONEDIT widget is computed by the layout rules as described in Widget size within hbox tags.

In a stack-based layout, the widget will take the full width available in the parent container.

Field input length

In grid-based layout, the input length in a BUTTONEDIT fields is defined by the item tag and may need to get the SCROLL attribute. For more details, see Input length of form fields.