uiForm

The uiForm component is used to contain a logical group of UI controls (typically serving as the user interface for a specific task in an application). It is responsible for implementing a defaultButton (a uiPushButton instance that is activated when the ENTER key is pressed) and mnemonics (quick access keys). It is otherwise the same as a uiPane container¹⁾.

The main purpose of the uiForm container is to implement a default push button.

var agreeForm:uiForm = new uiForm();
agreeForm.defaultButton = agreeBtn;

The defaultButton property of a uiForm container indicates the uiPushButton instance that should be activated when the ENTER key is pressed while the uiForm container is active. The uiForm container is deemed active when any of its child (or grandchild) object has focus. Notice in the example above, the object in focus is the uiCheckBox instance, but the uiPushButton is rendered in its emphasized state, as a visual cue to the user that it will be activated if the ENTER key is pressed (because it is the default push button).

However, this defaultButton property is not applicable when another uiPushButton instance within the uiForm is focused (because that uiPushButton will catch the ENTER key instead). It is also not applicable when the focus is in a multiline TextField object (because the ENTER key will be used to insert carriage returns instead).

A mnemonic key, also known as an accelerator key, is a readily recognized character key that the user can press to move the focus from one control to another.

Controls contained within a uiForm can have mnemonic keys assigned. When the uiForm container is active (ie one of its child or grandchild objects has focus) and the focus is not in a TextField, pressing a registered mnemonic key moves the focus to the corresponding control.

To register a mnemonic key, use the setMnemonicKey(key,obj) method. The first parameter key indicates the character to register (a single case-insensitive string character). The second parameter obj indicates the corresponding InteractiveObject (a focusable uiComponent instance contained within the uiForm).

In the case of uiLabelButton instances, as well as instances of the subclasses uiCheckBox, uiRadioButton and uiPushButton, the first matching character in the control's text label is underlined to indicate its function as a mnemonic key. For controls with no inherent text labels, such as the uiTextInput or uiSlider controls, you can specify the uiText instance used as the text label in the third (optional) parameter of the setMnemonicKey() method.

import com.ghostwire.ui.containers.uiBox;
import com.ghostwire.ui.containers.uiForm;
import com.ghostwire.ui.controls.uiCheckBox;
import com.ghostwire.ui.controls.uiPushButton;
import com.ghostwire.ui.controls.uiText;
import com.ghostwire.ui.controls.uiStepperInput;
import com.ghostwire.ui.data.uiRange;
 
var ageLabel:uiText = new uiText("Age");
 
var ageInput:uiStepperInput = new uiStepperInput(new uiRange(16,12,20));
 
var subBtn:uiPushButton = new uiPushButton("Submit");
 
var box:uiBox = new uiBox();
box.vertical = true;
box.spacing = 4;
box.addChild(ageLabel);
box.addChild(ageInput);
box.addChild(subBtn);
 
var form:uiForm = new uiForm();
form.setMnemonicKey("a",ageInput,ageLabel);
form.addChild(box);
 
addChild(form);

• “A” in “Age” is underlined (the mnemonic key is case-insentive)
• Since the focus is in a TextField (embedded in uiStepperInput), the default uiPushButton is not active/emphasized (pressing the ENTER key does not activate it).

For more information on the members of the com.ghostwire.ui.containers.uiForm class, please refer to the API Reference.