How-To: How-to: Creating a Radio Button Group

Many forms use radio button groups to restrict the number of selection options to just one. TX Text Control supports the corresponding behavior and appearance of radion button groups by using CheckFormFields in combination with Conditional Instructions.

As follows a sample with two CheckFormFields (radioButton1 and radioButton2) shows how to implement such a radio button group in four steps:

1. Set radio button appearance

The corresponding CheckFormFields should have the typical radio button appearance. To do this by using the RibbonFormFieldsTab, select the check form field inside the Text Control, go to the RibbonFormFieldsTab's Check Box Properties group and choose the correspnding Checked and Unchecked Symbols.

Image

When creating such a group by code, the corresponding characters must be set to the CheckFormField.CheckedCharacter and CheckFormField.UncheckedCharacter properties:

To create this condition programmatically, use the following code snippet:

// Set radio button appearance
cffRadioButton1.CheckedCharacter = cffRadioButton2.CheckedCharacter = '%c9';
cffRadioButton1.UncheckedCharacter = cffRadioButton2.UncheckedCharacter = '+55';
' Set radio button appearance
cffRadioButton1.CheckedCharacter = Convert.ToChar(Convert.ToInt32("25c9", 16))
cffRadioButton2.CheckedCharacter = Convert.ToChar(Convert.ToInt32("25c9", 16))
cffRadioButton1.UncheckedCharacter = Convert.ToChar(Convert.ToInt32("2b55", 16))
cffRadioButton2.UncheckedCharacter = Convert.ToChar(Convert.ToInt32("2b55", 16))

2. Uncheck all check form fields

In most cases, no radio button is selected when the form is initialized. To uncheck check form fields, select the corresponding check form field and uncheck it by mouse click or pressing the space key. To do this programmatically, the CheckFormField.Checked property must be set to false.

// Uncheck radio button
cffRadioButton1.Checked = false;
cffRadioButton2.Checked = false;
' Uncheck radio button
cffRadioButton1.Checked = False
cffRadioButton2.Checked = False

3. Handle CheckFormField.Checked value is changed to true

One basic behavior of a radio button group is, that when a radio button is chosen, all other radio buttons become deselected. To implement this, for each CheckFormField, that represents a radio button, a Conditional Instruction must be created. That Conditional Instruction contains a condition that is fulfilled, when the radio button is selected. In this case, instructions are executed, that deselect all other radio button.

In this sample, creating such a Conditional Instruction for CheckFormField radioButton1 by dialog looks as follows:

Image

Doing this for radioButton2 the dialog looks like:

Image

The following code snippet shows how to create both Conditional Instructions programmatically:

// Create 'Radio Button 1 Checked'

// Create condition and instruction
Condition cdIsChecked1 = new Condition(cffRadioButton1, true);
Instruction isUncheck2 = new Instruction(cffRadioButton2, Instruction.InstructionTypes.SetValue, false);

// Create conditional instruction
ConditionalInstruction ciRadioButton1Checked = new ConditionalInstruction("Radio Button 1 Checked", new Condition[] { cdIsChecked1 }, new Instruction[] { isUncheck2 });

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton1Checked);


// Create 'Radio Button 2 Checked'

// Create condition and instruction
Condition cdIsChecked2 = new Condition(cffRadioButton2, true);
Instruction isUncheck1 = new Instruction(cffRadioButton1, Instruction.InstructionTypes.SetValue, false);

// Create conditional instruction
ConditionalInstruction ciRadioButton2Checked = new ConditionalInstruction("Radio Button 2 Checked", new Condition[] { cdIsChecked2 }, new Instruction[] { isUncheck1 });

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton2Checked);
' Create 'Radio Button 1 Checked'

' Create condition and instruction
Dim cdIsChecked1 As Condition = New Condition(cffRadioButton1, True)
Dim isUncheck2 As Instruction = New Instruction(cffRadioButton2, Instruction.InstructionTypes.SetValue, False)

' Create conditional instruction
Dim ciRadioButton1Checked As ConditionalInstruction = New ConditionalInstruction("Radio Button 1 Checked", New Condition() { cdIsChecked1 }, New Instruction() { isUncheck2 })

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton1Checked)


' Create 'Radio Button 2 Checked'

' Create condition and instruction
Dim cdIsChecked2 As Condition = New Condition(cffRadioButton2, True)
Dim isUncheck1 As Instruction = New Instruction(cffRadioButton1, Instruction.InstructionTypes.SetValue, False)

' Create conditional instruction
Dim ciRadioButton2Checked As ConditionalInstruction = New ConditionalInstruction("Radio Button 2 Checked", New Condition() { cdIsChecked2 }, New Instruction() { isUncheck1 })

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton2Checked)

4. Handle CheckFormField.Checked value is changed to false

The other basic behavior of a radio button group is, that a radio button cannot be unckecked directly. To implement this, for each radio button a Conditional Instruction must be created, where the condition tests the CheckFormField whether its Checked property changed to false. If that condition is met, the Conditional Instruction executes an instruction, that resets the CheckFormField.Checked property value to true.

Due to the fact, that all Conditional Instructions inside the document are automatically applied when changing the document to write-protected, the corresponding Unchecked Conditional Instruction of a radio button would be fulfilled and applied when initializing the form. This means that, the radio button of the last handled Conditional Instruction is displayed as selected after initializing the form, even if it was set as deselected when creating the document.

To prevent this, the instruction's Advanced Settings dialog must be opened to unckeck the Is initial instruction check box. This disables applying the instruction when the document is changing to write-protected. To implement this programmatically, the Instruction.IsInitialInstruction property must be set to false.

In this sample, creating such a Conditional Instruction for CheckFormField radioButton1 by dialog looks as follows

Image

Doing this for radioButton2 the dialog looks like:

Image

The following code snippet shows how to create both Conditional Instructions programmatically:

// Create 'Radio Button 1 Unchecked'

// Create condition and instruction
Condition cdIsUnchecked1 = new Condition(cffRadioButton1, false);
Instruction isCheck1 = new Instruction(cffRadioButton1, Instruction.InstructionTypes.SetValue, true) { IsInitialInstruction = false };

// Create conditional instruction
ConditionalInstruction ciRadioButton1Unchecked = new ConditionalInstruction("Radio Button 1 Unchecked", new Condition[] { cdIsUnchecked1 }, new Instruction[] { isCheck1 });

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton1Unchecked);


// Create 'Radio Button 2 Unchecked'

// Create condition and instruction
Condition cdIsUnchecked2 = new Condition(cffRadioButton2, false);
Instruction isCheck2 = new Instruction(cffRadioButton2, Instruction.InstructionTypes.SetValue, true) { IsInitialInstruction = false };

// Create conditional instruction
ConditionalInstruction ciRadioButton2Unchecked = new ConditionalInstruction("Radio Button 2 Unchecked", new Condition[] { cdIsUnchecked2 }, new Instruction[] { isCheck2 });

// Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton2Unchecked);
' Create 'Radio Button 1 Unchecked'

' Create condition and instruction
Dim cdIsUnchecked1 As Condition = New Condition(cffRadioButton1, False)
Dim isCheck1 As Instruction = New Instruction(cffRadioButton1, Instruction.InstructionTypes.SetValue, True) With {
    .IsInitialInstruction = False
}

' Create conditional instruction
Dim ciRadioButton1Unchecked As ConditionalInstruction = New ConditionalInstruction("Radio Button 1 Unchecked", New Condition() { cdIsUnchecked1 }, New Instruction() { isCheck1 })

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton1Unchecked)


' Create 'Radio Button 2 Unchecked'

' Create condition and instruction
Dim cdIsUnchecked2 As Condition = New Condition(cffRadioButton2, False)
Dim isCheck2 As Instruction = New Instruction(cffRadioButton2, Instruction.InstructionTypes.SetValue, True) With {
    .IsInitialInstruction = False
}

' Create conditional instruction
Dim ciRadioButton2Unchecked As ConditionalInstruction = New ConditionalInstruction("Radio Button 2 Unchecked", New Condition() { cdIsUnchecked2 }, New Instruction() { isCheck2 })

' Add to the TextControl
textControl1.FormFields.ConditionalInstructions.Add(ciRadioButton2Unchecked)