Creating a Set of Radio Buttons

Radio buttons are defined as individual fields, either using the Designer or by calling fld_def() in your code. However, unlike other field types, each radio button field does not have its own data variable; instead, all buttons in a group point to the same data variable. The individual fields are then grouped together to create a single functional radio button group.

Note that although all members of a radio button group point to the same data variable, each member of the group remains an individual field. This means that if you create a set of radio buttons containing three buttons, you have just added three fields (three items) to the data form.

Designer: Individual radio button fields can be created and grouped to form a set of radio buttons using the Designer. See the Designer User's Guide for more information.

If you do not use the Designer to generate your main program, you will need to follow Steps 1 and 2, below, when you write the code for your main().

Code: Radio buttons are defined first as individual fields by calling fld_def(). However, unlike standard field types, each radio button field does not have its own data variable; instead, all buttons in a group point to the same data variable. The fields are then grouped to form a set of radio buttons. Use the following steps to create a set of radio buttons in code.

Step 1: Include the header file vv_radio.h.

Include the radio button header file vv_radio.h in all modules that use radio buttons and in your main() module before vv_main.h.

Step 2: Declare a data variable of type int.

You must declare a single data variable of type int to hold the value of the radio button group. The value of this data variable corresponds to the identity of the selected radio button. The radio buttons in the group are numbered in order of definition, starting with zero. For example, if the value of the integer data variable is zero, then the first radio button in the group is selected (ON). Before the form is displayed, you should initialize this variable.

Step 3: Define each of the radio button fields using fld_def().

Define each field using the field definition function fld_def():

fld_def(prompt_rb, prompt_cb, prompt, fld_cb, picp, fld_type, datap, dfmp)

where picp is the field picture string. The allowed picture control characters for radio button fields are X, A, Z, !, *. The field picture can contain any number of protected characters but only one picture control character. A typical field picture for a radio button field is "(X)". fld_type is the field type (F_RADIO). datap is a pointer to the underlying integer data variable, for example, &button_value.

Note: If you want parentheses ('(' and ')') around the selection character and you want them to be included in the highlight bar, specify the parentheses as protected characters in the field picture. If you want parentheses around the selection character but you do not want them to be included in the highlight bar, add the parentheses as background text on the form.

For more information on defining fields with fld_def() see Chapter 6, "Writing Forms in Code."

Step 4: Group the radio button fields using sf_radgroup().

After defining all the radio button fields, group them together by calling the function sf_radgroup():

void sf_radgroup(first_fldp, last_fldp, dfmp)

DFIELDPTR first_fldp;        /* Pointer to first field in group        */

DFIELDPTR last_fldp;        /* Pointer to last field in group        */

DFORMPTR dfmp;            /* Pointer to data form                */

where first_fldp is a pointer to the first field to be added to the group, last_fldp is a pointer to the last field to be added to the group, and dfmp is a pointer to the data form that contains the radio button fields. All radio button fields that fall between the first and last field in processing order become part of the radio button group.

The following code fragment illustrates Steps 2-4:

int button_value;

DFIELDPTR butn0, butn1, butn2;



butn0 = fld_def(2, 0, "Data Form ", FADJACENT, "(X)",

            F_RADIO, &button_value, dfmp);

butn1 = fld_def(3, 0, "Menu Form ", FADJACENT, "(X)",

            F_RADIO, &button_value, dfmp);

butn2 = fld_def(4, 0, "Window ", FADJACENT, "(X)",

            F_RADIO, &button_value, dfmp);

sf_radgroup(butn0, butn2, dfmp);

button_value = 2;

When the form is displayed, button 2 ("Window") is selected; buttons 0 and 1 are not selected.