This class models a recorded button. One does not manually create objects from this class, they are created by CGI::MxScreen when the record_button() routine is called on a screen object to declare a new button.

In order to use the state machine features from CGI::MxScreen, it is necessary to declare all the submit buttons you are going to generate. The declaration routine takes a set of meaningful arguments, and lets the others pass through verbatim (they are recorded to be given back when properties() is called).

The minimal set of arguments to supply are -name and -target (or -dyn_target). You will probably supply -action as well if you wish to perform validation of control fields, or any other processing attached to the pressing of that button.

Some of the callbacks or arguments below are expected to yield states. See "States" in CGI::MxScreen for state representation rules.

The following named arguments may be given to record_button(). Any other argument is simply recorded and will be propagated via properties(). Arguments are all optional but for -name, and one of -target or -dyn_target must be supplied:

The list of action callbacks that should be run when the button is pressed. Those will be run before any state change, since failure of one of those callbacks could mean we stay in the same state.

A trailing CGI::MxScreen::Action_Env object is appended to the list of callback arguments. It can be used to check whether any action callback in the chain as already reported an error. In the last action callback listed, this could be used to execute some processing only if we're about to change state, i.e. when no error occured.

Note: when using the second form of callback specification (i.e. an array ref), double brackets must be used, since the list of callback actions must itself be within brackets:

-action => [['callback', $arg1]], # RIGHT

If you were to write by mistake:

-action => ['callback', $arg1], # WRONG

then that would result in the following actions ($screen is the current screen object where the button is recorded):

When any of the -action callbacks returns a non-OK status, an error flag is raised. By default, the same screen will be re-displayed. When a -dyn_on_error callback is specified, the screen to display is computed dynamically. You may not use this option in conjunction with -on_error.

A trailing CGI::MxScreen::Action_Env object is appended to the callback argument list. This object records the failed action callbacks, in case that could help determine the state to move to. See CGI::MxScreen::Action_Env.

The callback is expected to return a new state specification: it can be a single scalar (the state name), or an array ref (state name as first item, remaining values being display() parameters). See "States" in CGI::MxScreen for details.

When a -dyn_target callback is specified, the next target state is computed dynamically. You may not use this option in conjunction with -target.

The callback is expected to return a new state specification: it can be a single scalar (the state name), or an array ref (state name as first item, remaining values being display() parameters). See "States" in CGI::MxScreen for details.

When any of the -action callbacks returns a non-OK status, an error flag is raised. By default, the same screen will be re-displayed. When an -on_error trap is specified, the screen to display is given by target_state. You cannot use -dyn_on_error in conjunction with this argument.

The target_state can be a single scalar (the state name), or an array ref (state name as first item, remaining values being display() parameters). See "States" in CGI::MxScreen.