Classes: TRadioButton

Inheritance

TObject
TPersistent
TComponent
TControl
TWinControl
TButtonControl

To create a radio button, use the TRadioButton class.

Adding a Radio Button

Because they come in a group, radio buttons should (with emphasis) be organized in a specific container. To implement their mutual exclusiveness, radio buttons should be positioned in either a RadioGroup control, a GroupBox control, or a panel. If you add the radio buttons on this type of container, they will be treated as a group. You should refrain from positioning radio buttons on the form.

At design time, to create a group of radio buttons, first position a container on the form; this could be a RadioGroup control. There are two main ways you can create a group of radio buttons. If you are using a RadioGroup as the container, this control considers its “children”, the radio buttons it hosts, as a list of strings. Therefore, you can type the label of each radio button in the String List Editor. The radio buttons created as a list of strings are not controls to their full extent, although this technique provides the fastest and a very efficient method of creating a group of radio buttons. If you want each radio button to behave like a full control, first position a GroupBox (the better choice) or a panel controls on the form. To add each radio button, from the Standard tab of the Component Palette, click the RadioButton and click inside of the container. 

Radio Button Properties

From the programmer’s standpoint, one of the most important property of any control is its name. This allows you and the compiler refer to the control at any time. If you create your radio buttons using a RadioGroup control, the radio buttons, because they are string objects, would not have names. If you use a GroupBox or a panel, you can name each radio button as you fit, respecting C++ naming rules. To set the name of a control, in the Object Inspector, click Name and type the desired name.

Two properties are of particular importance to both you and the user: the label and the state of the control. The label is text that specifies what a particular radio button is used for. If you decide to use a RadioGroup control, after placing it on the form, on the Object Inspector, click the Items field to reveal its ellipsis button . Click the ellipsis button to call the String List Editor. To create each radio button, type a label and press Enter for each:

After creating the list, click OK. The container will take care of positioning the radio button so they can fit inside the host. If you type too many or too long strings for the host, resize the container. If you have a RadioGroup control on the form but could not or forgot to create a list of radio buttons, you can do so programmatically as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    grpEmplStatus->Items->Add("Part-Time");
    grpEmplStatus->Items->Add("Full-Time");
    grpEmplStatus->Items->Add("Contractor");
    grpEmplStatus->Items->Add("Consultant");
}
//---------------------------------------------------------------------------

If you are using a GroupBox or a panel controls to host the radio buttons, after adding it to the form, on the Component Palette, click the RadioButton and click in the host. To set the label of a radio button, on the Object Inspector, click Caption and type the desired label. Repeat this for each radio button. If you want to change a radio button’s caption at runtime, you can do so programmatically as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
    rdoGender1->Caption = "Man";
}
//---------------------------------------------------------------------------

The second of the most important properties of a radio button is its state: whether it is selected or not. When the user clicks a radio button, it becomes exclusively selected. This is seen by the dot inside its rounded box. When a radio button is selected, it is said to be checked. By default, a newly created radio button is not checked. At design time, if you created the radio buttons using a RadioGroup control, you can set which radio button is selected by changing the integer value of the ItemIndex property. Since not radio button is selected by default, its value is –1. The items in the string are counted starting at 0, then 1, and so on. For example, to set the second radio button as checked, set the ItemIndex property of the RadioGroup control as 1. This property can be change only after the list is created. Therefore, if you create the list programmatically, you can also decide which radio button would be selected when the list shows up:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    grpEmplStatus->Items->Add("Part-Time");
    grpEmplStatus->Items->Add("Full-Time");
    grpEmplStatus->Items->Add("Contractor");
    grpEmplStatus->Items->Add("Consultant");
    grpEmplStatus->ItemIndex = 2;
}
//---------------------------------------------------------------------------

If you create the radio buttons using a GroupBox or a panel controls, you can set a radio button using the Checked property. This same property allows you to decide which button would be selected when the form opens. As a Boolean property, to set the Checked state of a radio button, set this value to true. At runtime, to set a particular radio button as checked, assign a true value to its name:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCheckFemaleClick(TObject *Sender)
{
    rdoFemale->Checked = True;
}
//---------------------------------------------------------------------------

Once one button has been checked in a group, even if there was no selection in the beginning, one radio button is always selected in the group. The user cannot deselect all radio buttons. Only the developer can do this at runtime. By setting the Checked property of a radio button to false, you can remove its selection:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnUnchekDontKnowClick(TObject *Sender)
{
    rdoDontKnow->Checked = False;
}
//---------------------------------------------------------------------------

In the same way you can deselect all radio buttons. If the radio buttons were created using a RadioGroup control, assign a –1 value to its ItemIndex property:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnDeselectEmplClick(TObject *Sender)
{
    grpEmplStatus->ItemIndex = -1;
}
//---------------------------------------------------------------------------

Otherwise, you can assign a false value to the Checked property of each radio button:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnDeselectGenderClick(TObject *Sender)
{
    rdoMan->Checked = False;
    rdoFemale->Checked = False;
    rdoDontKnow->Checked = False;
}
//---------------------------------------------------------------------------

When dessigning your radio buttons, to manage the space, you can distribute them on more than one column. If the radio buttons were created using a RadioGroup control, on the Object Inspector, change the (interger) value of the Columns property. You can also do this at runtime:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
    grpEmplStatus->Items->Add("Part-Time");
    grpEmplStatus->Items->Add("Full-Time");
    grpEmplStatus->Items->Add("Contractor");
    grpEmplStatus->Items->Add("Consultant");
    grpEmplStatus->ItemIndex = 2;
    grpEmplStatus->Columns = 2;
}
//---------------------------------------------------------------------------

If you want to use various columns on a group of radio buttons created using a GroupBox or a panel controls, you can visually position each radio button on the container. Programmatically, you can also change the Left, and Top values of each control as desired.

By default, a radio button is configured so that the label would be positioned on the right side of the rounded box. This is controlled by the Alignment property. If you want the label of the left side, set the radio button’s Alignment property according. The values are: taRightJustify and taLeftJustify.

Radio Buttons Methods

The primary method you will use with a radio button is the TRadioButton constructor. This function is mostly used to dynamically create a radio button. Since all objects in C++ Builder must be called using pointers, to create a radio button, declare an instance of a TRadioButton object and use the new operator to specify the control that owns the radio button. A bad idea would be to assign it to the form. As we have reviewed, you should never (or hardly) position a radio button or a group of radio buttons on a form. Therefore, before creating a radio button, you should have a container on your form. You can add such a host at design time or at run time.

The fastest and most convenient way to dynamically create a group of radio buttons consists of using a RadioGroup control. If you don’t have this control already, either by adding it at design time or by creating anyhow, you can use the new operator to assign an instance of the TRadioGroup to the owner of this control. The compiler needs to know the owner that would have the responsibility of cleaning the RadioGroup once it is not needed anymore. This time, the owner should be the form, unless the RadioGroup control will be hosted by another container. Also, specify the parent of the control. If you will need the radio buttons in just one function or event, you can create the RadioGroup control in that function. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCreateGroupClick(TObject *Sender)
{
    TRadioGroup* Group = new TRadioGroup(Form1);
    Group->Parent = Form1;
}
//---------------------------------------------------------------------------

If you are planning to use the control in more than one location, declare a TRadioGroup object in the private or public sections of the form or unit that would use it:

private:	// User declarations
    TRadioGroup *grpMaritalStatus;
public:		// User declarations
    __fastcall TForm1(TComponent* Owner);

To create the list that represents the radio buttons, use the TStrings::Items property of the RadioGroup control. You can do this in the function where you create the control locally:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCreateGroupClick(TObject *Sender)
{
    TRadioGroup* Group = new TRadioGroup(Form1);
    Group->Parent = Form1;
    Group->Caption = "Membership";
    Group->Items->Add("Senior");
    Group->Items->Add("Adult");
    Group->Items->Add("Tean");
    Group->Items->Add("Child");
    Group->Columns = 2;
    Group->Left = 8;
    Group->Top = 20;
}
//---------------------------------------------------------------------------

If the RadioGroup was created globally, use the appropriate function or event to initialize it:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormDblClick(TObject *Sender)
{
    grpMaritalStatus = new TRadioGroup(Form1);
    grpMaritalStatus->Parent = Form1;
    grpMaritalStatus->Items->Add("Single");
    grpMaritalStatus->Items->Add("Married");
    grpMaritalStatus->Items->Add("Divorced");
    grpMaritalStatus->Items->Add("Widow");
    grpMaritalStatus->Left = 220;
    grpMaritalStatus->Top = 20;
    grpMaritalStatus->Height = 100;
    grpMaritalStatus->Width = 124;
    grpMaritalStatus->Caption = "Marital Status";
}
//---------------------------------------------------------------------------

If you want to create each button as its own object, you will once have to have a container, designed or dynamically created. The bad news is that you will have to create each button individually.