RADIO
A RADIO button is a graphical, round button that is filled in with a different color depending upon whether the button is "on" or "off". The label is immediately to the right of the button. Alternately, an image can be used for the button.
A radio button's state turns "on", and stays "on", when the user activates it. Like the push button, the user activates a radio button when he clicks the mouse upon it. Alternately, pressing the SPACE BAR will activate the button which currently has the focus (ie, is highlighted). But, only one radio button in a group can be activated (ie, turned "on") at any given moment. When a particular radio button is activated, any other button that was "on" is automatically turned off, and only the newly activated button is turned "on". In other words, only one button is ever "on" at any given moment, and all others in the Group are "off".
Uses
Radio buttons are used to allow the user to choose one (and only one) item from several available choices. For example, there may several radio buttons, each offering a different "paper size" for a printing job, and the user must choose one size.
Styles
Shortcut | The Shortcut box lets you enter a keyboard shortcut that will automatically select this control whenever the user presses that shortcut. |
A RADIO button must be created with one of the following 3 styles:
Text | Displays a label next to the check box. |
Bitmap | Displays a bitmap next to the check box. |
Icon | Displays an icon next to the check box. |
When you choose Text style, then the button can have a label (ie, caption). If you choose Bitmap or Icon styles, then you instead must choose some Bitmap or Icon resource you have already added to your Window Layout script. This image will be displayed in the button.
A RADIO button may additionally have any, all, or none of the following styles:
Auto | The operating system automatically toggles the radio graphic when the user clicks on the radio button. If AUTO is not specified, the Window Layout script must have a function to handle the CLICK event for the |
Pushlike | The RADIO has the appearance of a PUSH button. When selected, it remains "pushed in". |
Flat | Flat appearance. |
Multiline | (MULTI) Wraps the label to multiple lines if the text is too long to fit on a single line inside the button rectangle. |
Button on right | (RBUTTON) Positions the radio button on the right side of the button rectangle. |
Notify | Causes the Window Layout's DBLCLK, FOCUS, and UNFOCUS subroutines to be called when the button is double-clicked, loses the focus, or gains the focus, respectively. Note that you can always add a function to handle a button's CLICK event regardless of this style. |
No Sibling | (NOSIBLING) Prevents this control from drawing into any overlapping controls. |
Group | Marks this control as the first of a group of controls in which the user can move from one control to the next with the arrow keys. All subsequent controls (after this first control) belong to the same group up to the next control that has its GROUP flag set. (ie, One group ends where the next begins).
Note: In order to make a group of AUTO radio buttons operate correctly, where clicking upon one causes the others to be deselected, the first radio button in the group should have a GROUP style, and the subsequent radio buttons must not have GROUP style. |
Tabstop | The user can move to this control using the TAB key. |
Disabled | Control is initially disabled. You can later enable it with a call to GuiSetCtlPlacement. |
Hide | Control is hidden. You can later make it visible with a call to GuiSetCtlPlacement. |
In addition to the above styles, a RADIO button may have one of the following 3 horizontal alignment styles:
Left | Left-justifies the label, bitmap, or icon. If the RBUTTON style is not specified, the item is left-justified on the right side of the radio button. |
Right | Right-justifies the label, bitmap, or icon. If the RBUTTON style is not specified, the item is right-justified on the right side of the radio button. |
Center | The label, bitmap, or icon is horizontally centered. |
In addition to the above styles, a CHECK button may have one of the following 3 vertical alignment styles:
Top | The label, bitmap, or icon is positioned at the top of the button. |
Bottom | The label, bitmap, or icon is positioned at the bottom of the button. |
Center | (VCENTER) The label, bitmap, or icon is vertically centered. |
Extra styles
A RADIO button can have any, all, or none of the following extra styles:
Quiet | Do not report any events for this control. |
Modal Frame | (MODALFRAME) Has a double border. |
Static Edge | (STATICEDGE) Has a three-dimensional border intended to be used for windows that do not accept user input. |
Client Edge | (CLIENTEDGE) Has a 3D look comprised of a border with a sunken edge. |
Accept files | (FILES) Accepts drag-and-drop files (ie, the WM_DROPFILES event). |
Align text right | (RIGHT) Gives the control generic right-aligned properties (as opposed to the default of left-aligned properties). |
Read right-to-left | (RTLREADING) Displays the window text using right-to-left reading order properties (instead of the default of left-to-right). |
Transparent | The control is to be transparent. Any controls that are beneath this one are not obscured. |
Events
A RADIO button generates the same events as a PUSH button.
REXX Variable
At least the first RADIO button in a group must have a REXX variable associated with it. The remaining RADIO buttons do not need a REXX variable name. Before opening the window which contains the RADIO buttons, you must set the variable's value (for the first RADIO button) to whichever radio button is selected, where 1 is the first button in the group, 2 is the second, etc.
Dynamically add/remove a RADIO button
You can dynamically add a RADIO button to an already open window by calling GuiAddCtl. You must pass a line that describes the control. The format for this line is:
RADIO X, Y, Width, Height, Styles, ExtraStyles, VariableName, Accelerator, LabelX and Y is the position of the top left corner of the control, relative to the window's top left corner.
Width and Height are the size of the control, in pixels.
Styles and ExtraStyles are those listed above, with each style separated by a | character.
VariableName is the variable name to be associated with the control. The first RADIO button in the group must have a variable name. The others do not.
Accelerator is the keyboard shortcut that causes the button to be "pushed".
Label is the (text) label for the control. You can use the two characters \t to represent a TAB character. You can also include multiple lines by using the characters \n to mark the end of a line. If you want to put a \ character in the text, then you must double it up as \\.
If the button has the ICON or BITMAP style, then Label will instead be either the name of a file containing the icon/bitmap image, or the image number if the image is embedded inside of an EXE you created with the Window Editor. In this case, you do not need to initialize the associated REXX variable before calling GuiAddCtl.
You must also pass the button number that this button will be (within the group), where 1 is the first button, 2 is the second button, etc.
Note: The first RADIO button in the group must have a GROUP style. The subsequent buttons in the group must not have a GROUP style.
Before adding a radio button, you should set the associated REXX variable, for the first RADIO button in the group, to the which button number is selected within the group. For example, here we add a RADIO button at an X Y position of 10, 10, with a width and height of 40 and 20, with the styles AUTO, RBUTTON, and GROUP (since this will be the first button), extra styles of CLIENTEDGE and QUIET, a REXX Variable name of MyRadioButton, and a label of Select me. We select the first button in the group.
MyRadioButton = 1 error = GuiAddCtl("RADIO 10,10,40,20, AUTO|RBUTTON|GROUP, CLIENTEDGE|QUIET, MyRadioButton,, Select me", , 1)You can dynamically remove a RADIO button by calling GuiRemoveCtl, and passing the variable name associated with the group, as well as the button number (where 1 is the first button). Here we remove the above button:
error = GuiRemoveCtl("MyRadioButton", , 1)Note: If removing the first button in a group, you do not need to pass the button number.
Change a RADIO button's label.
If the button has the TEXT style, you can dynamically change its label by calling GuiAddCtlText. You pass the REXX variable name for the button's group, the new label, and finally the button number (within the group). Here we change the above (ie, first) button's label to Don't select me:
error = GuiAddCtlText("MyRadioButton", "Don't select me", 1)
Change a RADIO button's image.
If the button has the ICON or BITMAP style, you can dynamically change its image by calling GuiAddCtlText. You pass the REXX variable name for the button, and either the filename of the icon/bitmap, or the image number if the image is embedded in an EXE you created with the Window Editor. Here we change the above button's image to the image in the file named C:/MyIcon.ico:
error = GuiAddCtlText("MyRadioButton", "C:/MyIcon.ico")Note: Use forward (not back) slashes to separate the directory names.
Change which RADIO button is selected
You can dynamically select which RADIO button (within a group) is selected by calling GuiSetCtlValue. You first set its associated REXX variable to the desired button number, and then call GuiSetCtlValue, passing that variable name. For example, here we select the second button in the group:
MyRadioButton = 2 error = GuiSetCtlValue("MyRadioButton")Note: Only one RADIO button within a group may be selected. When you select one button, all other buttons in the same group are automatically unselected.
Query which RADIO button is selected
You can query which button is selected in a group by calling GuiGetCtlValue. This will set its associated REXX variable to the number of the currently selected button. For example, here we query which button in the above group is selected:
error = GuiGetCtlValue("MyRadioButton") IF error == "" THEN DO SAY "Radio button" MyRadioButton "is selected." END