uiRadioButton

uiRadioButton

The uiRadioButton class is used when you want end-users to choose from a list of options that are mutually exclusive¹⁾. Therefore, it only makes sense to use this component in a group of at least two uiRadioButton instances.

Using uiRadioButton

ActionScript 3.0 Example

 1: import com.ghostwire.ui.containers.uiBox;
 2: import com.ghostwire.ui.controls.uiButtonGroup;
 3: import com.ghostwire.ui.controls.uiRadioButton;
 4:
 5: // ** create the radiobuttons **
 6: var genderMale:uiRadioButton    = new uiRadioButton("Male");
 7: var genderFemale:uiRadioButton    = new uiRadioButton("Female");
 8: var genderUnknown:uiRadioButton    = new uiRadioButton("Unknown");
 9:
10: // ** create a box container **
11: var genderBox:uiBox    = new uiBox();
12: genderBox.spacing    = 10;
13:
14: // ** add radiobuttons to container **
15: genderBox.addChild(genderMale);
16: genderBox.addChild(genderFemale);
17: genderBox.addChild(genderUnknown);
18:
19: // ** add to displaylist **
20: addChild(genderBox);
21:
22: // ** create a group and assign the radiobuttons **
23: var genderGroup:uiButtonGroup    = new uiButtonGroup(genderMale,genderFemale,genderUnknown);
24: // ** specify initial selected button
25: genderGroup.selectedButton    = genderMale;

Grouping

You must assign uiRadioButton instances to a uiButtonGroup because only one of the buttons in the group is intended to be selected at any one time. You can do this either by
(i) setting the uiRadioButton instance's group property to an existing uiButtonGroup object, or
(ii) specifying the uiRadioButton instance in the constructor parameter when creating the uiButtonGroup object.
NOTE: If you don't assign the uiRadioButton instance to a group, it will behave just like a uiCheckBox.

Label

A uiRadioButton instance can display next to itself a text, an image (icon), or both as its label.

To display icons in-lieu of text as label in the example above, you would replace Lines 6 to 8 with:

6: var genderMale:uiRadioButton    = new uiRadioButton(null, "maleIcon.png");
7: var genderFemale:uiRadioButton    = new uiRadioButton(null, "femaleIcon.png");
8: var genderUnknown:uiRadioButton    = new uiRadioButton(null, "unknownIcon.png");

The image sources specified in the code above points to external PNG image files that are loaded during run-time from the path “assets/images/” (relative to the SWF). If you have any image embedded into the SWF, you can also use the image by specifying its class name as the image source.

To display both icon and text, you would replace the lines with:

6: var genderMale:uiRadioButton    = new uiRadioButton("Male", "maleIcon.png");
7: var genderFemale:uiRadioButton    = new uiRadioButton("Female", "femaleIcon.png");
8: var genderUnknown:uiRadioButton    = new uiRadioButton("Unknown", "unknownIcon.png");

You can also set or modify the label via the text and/or image properties.

 6: var genderMale:uiRadioButton    = new uiRadioButton();
 7: var genderFemale:uiRadioButton    = new uiRadioButton();
 8: var genderUnknown:uiRadioButton    = new uiRadioButton();
 9: genderMale.text = "Male";
10: genderFemale.text = "Female";
11: genderUnknown.text = "Unknown";
12: genderMale.image = "maleIcon.png";
13: genderFemale.image = "femaleIcon.png";
14: genderUnknown.image = "unknownIcon.png";

Label Position

The default behavior is to position the label (text and/or image) to the right of the radio button. You can change this setting via the labelPosition property. Qualified values for the labelPosition property are POSITION.BOTTOM, POSITION.LEFT, POSITION.RIGHT, and POSITION.TOP²⁾.

genderMale.labelPosition = POSITION.TOP;
genderFemale.labelPosition = POSITION.TOP;
genderUnknown.labelPosition = POSITION.TOP;

Text Position

When displaying both text and image as the label, it is possible that you may want to change the way the text is positioned vis-a-vis the image. The default behavior is to position the text to the right of the image. You can change this setting via the textPosition property. Qualified values for the textPosition property are POSITION.BOTTOM, POSITION.LEFT, POSITION.RIGHT, and POSITION.TOP³⁾.

genderMale.textPosition = POSITION.TOP;
genderFemale.textPosition = POSITION.BOTTOM;
genderUnknown.textPosition = POSITION.LEFT;

User Interaction

The currently selected radio button in the group is included in the tab focus chain (the other members in the group are not). When a radio button is focused, the user can use the following keys to interact with the control:

Key	Action
Left Arrow/Up Arrow	Moves focus to the previous member in the group and selects it.
Right Arrow/Down Arrow	Moves focus to the next member in the group and selects it.
Shift+Tab	Moves focus to previous UI control in the tab focus chain.
Spacebar	Selects the button if it is not yet selected.*
Tab	Moves focus to next UI control in the tab focus chain.

* You would normally set an initial selected button using the uiButtonGroup.selectedButton property. If you do not do so, the first member in the group will be included in the tab focus chain (but not set as selected).

Disabled buttons cannot be focused or selected by the user. Note that if your application disables a button that is already selected, the whole group will not be accessible via the Tab key (but still accessible via the mouse). This is considered an application design flaw rather than a framework bug because it is illogical to disable a radio button that is already selected (on its own). If you need to disable a choice that is already selected, consider setting the selection to another button or clearing the selection first (because a disabled choice is not intended to be selected). If the intention is to disable the whole button group, you can do so by disabling the container containing the buttons thereby disabling all the buttons within.

genderBox.enabled = false;

RadioButtonDemo

ActionScript 3.0 RadioButtonDemo class

 1: package
 2: {
 3:     import com.ghostwire.ui.containers.uiBox;
 4:     import com.ghostwire.ui.controls.uiButtonGroup;
 5:     import com.ghostwire.ui.controls.uiRadioButton;
 6:     import com.ghostwire.ui.controls.uiImage;
 7:     import com.ghostwire.ui.enums.ALIGN;
 8:     import com.ghostwire.ui.enums.POSITION;
 9:     import com.ghostwire.ui.managers.uiSkins;
10:
11:     import flash.display.Sprite;
12:     import flash.events.Event;
13:
14:     public class RadioButtonDemo extends Sprite
15:     {
16:         // ** for displaying the selected item **
17:         private var displayImage:uiImage;
18:
19:         public function RadioButtonDemo()
20:         {
21:             addEventListener(Event.ADDED_TO_STAGE,init);
22:         }
23:
24:         private function init(evt:Event):void
25:         {
26:             // ** optional but recommended **
27:             stage.scaleMode    = "noScale";
28:             stage.align        = "TL";
29:
30:             // ** uncomment to use "classic" theme **
31:             // uiSkins.initialize("classic");
32:
33:             // ** optional but recommended **
34:             // ** let assets preload before starting application **
35:             uiSkins.manager.addEventListener(Event.INIT,main);
36:         }
37:
38:         private function main(evt:Event):void
39:         {
40:             // ** main application code **
41:             // ** create the radiobuttons **
42:             var genderMale:uiRadioButton    = new uiRadioButton("Male", "maleIcon.png");
43:             var genderFemale:uiRadioButton    = new uiRadioButton("Female", "femaleIcon.png");
44:             var genderUnknown:uiRadioButton    = new uiRadioButton("Unknown", "unknownIcon.png");
45:             genderMale.textPosition = POSITION.TOP;
46:             genderFemale.textPosition = POSITION.TOP;
47:             genderUnknown.textPosition = POSITION.TOP;
48:
49:             // ** create a box container **
50:             var genderBox:uiBox    = new uiBox();
51:             genderBox.spacing    = 10;
52:
53:             // ** add radiobuttons to container **
54:             genderBox.addChild(genderMale);
55:             genderBox.addChild(genderFemale);
56:             genderBox.addChild(genderUnknown);
57:
58:             // ** image placeholder **
59:             displayImage        = new uiImage();
60:             // ** align the image center vertically **
61:             displayImage.alignY    = ALIGN.CENTER;
62:             displayImage.background = {border:0x808080,color:0xffffff};
63:
64:             // ** append image to box **
65:             genderBox.addChild(displayImage);
66:
67:             //genderBox.enabled = false;
68:             // ** add to displaylist **
69:             addChild(genderBox);
70:
71:             // ** create a group and assign the radiobuttons **
72:             var genderGroup:uiButtonGroup    = new uiButtonGroup(genderMale,genderFemale,genderUnknown);
73:             // ** set up event handler **
74:             genderGroup.addEventListener(Event.CHANGE,on_genderChange);
75:             // ** specify initial selected button
76:             genderGroup.selectedButton        = genderFemale;
77:         }
78:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
79:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
80:
81:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
82:         // EVENT HANDLERS
83:         // ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
84:         private function on_genderChange(evt:Event):void
85:         {
86:             displayImage.source = uiRadioButton(uiButtonGroup(evt.target).selectedButton).image;
87:         }
88:     }
89: }

RadioButtonDemo.as

API Reference

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

¹⁾ To create a list of options that are not mutually exclusive, use the uiCheckBox component instead.

²⁾ , ³⁾ Import com.ghostwire.ui.enums.POSITION