# FTRRadioButton – Customer Usage Guide ## Overview `FTRRadioButton` is a modern Windows Forms radio button designed for selecting one option from a group of related choices. It provides the standard Windows Forms radio-button behavior together with an enhanced visual appearance, including: * Custom-drawn radio circle * Animated selection indicator * Ripple effect when clicked * Focus indicator * Hover-state appearance * Disabled-state appearance * Right-to-left layout support * FTR theme integration * Customizable colors * Configurable radio-circle size The control is available from the **FTR Controls** toolbox. `FTRRadioButton` is based on the standard Windows Forms `RadioButton`, so standard `RadioButton` functionality such as `Checked`, `AutoCheck`, `Text`, `Font`, `ForeColor`, `Enabled`, and `RightToLeft` is available. --- # Adding FTRRadioButton to a Form After adding the FTR Controls assembly to your Windows Forms project, add `FTRRadioButton` to your form from the Visual Studio toolbox. The control can also be created programmatically. ### Basic Example ```csharp var optionA = new FTRRadioButton { Text = "Option A" }; var optionB = new FTRRadioButton { Text = "Option B" }; groupPanel.Controls.Add(optionA); groupPanel.Controls.Add(optionB); ``` Because the control inherits from the standard Windows Forms `RadioButton`, related radio buttons placed in the same container can be used as a group of mutually exclusive choices. --- # Selecting an Option ## Checked The `Checked` property determines whether the option is selected. ### Select an option programmatically ```csharp optionA.Checked = true; ``` ### Check whether an option is selected ```csharp if (optionA.Checked) { // Option A is selected. } ``` When one option in a radio-button group is selected, the other radio buttons in the same group behave according to standard Windows Forms `RadioButton` behavior. --- # AutoCheck `AutoCheck` is inherited from the standard Windows Forms `RadioButton`. When `AutoCheck` is enabled, the control automatically changes its checked state when the user selects it. Example: ```csharp optionA.AutoCheck = true; ``` This is the normal configuration for a radio-button option. If your application needs to control the checked state manually, `AutoCheck` can be configured accordingly. --- # Text The `Text` property specifies the label displayed next to the radio circle. Example: ```csharp var option = new FTRRadioButton { Text = "Enable notifications" }; ``` The label is rendered next to the radio circle automatically. If the available width is insufficient, the text is displayed with an ellipsis rather than overflowing the control. --- # Circle Size ## CircleSize — Premium `CircleSize` controls the diameter of the radio circle. Default: ```text 18 pixels ``` Example: ```csharp option.CircleSize = 22; ``` The minimum supported value is: ```text 12 pixels ``` If a value below `12` is assigned, the control automatically uses `12`. For example: ```csharp option.CircleSize = 8; ``` results in a circle size of `12`. ### Layout impact Changing `CircleSize` also changes the control's minimum supported size. This allows the control to maintain enough space for both the radio circle and its text. `CircleSize` requires an appropriate FTR Controls Premium license. --- # Colors The radio button supports separate colors for its main visual states. ## CheckedColor — Premium Controls the color of the selected radio button. It is used for: * The selected radio border * The selected inner indicator Example: ```csharp option.CheckedColor = Color.DodgerBlue; ``` `CheckedColor` requires a Premium license. --- ## UncheckedColor — Premium Controls the border color when the radio button is not selected and the mouse is not hovering over it. Example: ```csharp option.UncheckedColor = Color.Gray; ``` `UncheckedColor` requires a Premium license. --- ## HoverColor — Premium Controls the border color while the mouse pointer is over an enabled radio button. Example: ```csharp option.HoverColor = Color.DodgerBlue; ``` This allows the control to provide a visual indication that it can be selected. `HoverColor` requires a Premium license. --- ## DisabledColor — Premium Controls the color used when the radio button is disabled. Example: ```csharp option.DisabledColor = Color.LightGray; ``` When: ```csharp option.Enabled = false; ``` the control uses its disabled appearance. `DisabledColor` requires a Premium license. --- ## RippleColor — Premium Controls the color of the ripple animation displayed when the user clicks the control. Example: ```csharp option.RippleColor = Color.DodgerBlue; ``` `RippleColor` requires a Premium license. --- # Ripple Effect When the user presses the left mouse button on an enabled radio button, a ripple effect starts from the radio-circle area. The ripple expands and gradually fades away. This effect is visual only and does not change the standard selection behavior of the radio button. The ripple animation is automatically managed by the control. --- # Selection Animation When the checked state changes, the inner selection indicator is animated. For example: ```csharp option.Checked = true; ``` causes the inner circle to appear with an animation rather than immediately appearing at its final size. Similarly, unchecking the option animates the inner indicator back to its unselected state. The animation is handled automatically; no additional configuration is required. --- # Keyboard Support The control supports keyboard interaction through its inherited Windows Forms `RadioButton` behavior. ## Space Key When the control has keyboard focus, pressing the Space key checks the radio button when it is currently unchecked. For example: ```text Unchecked + Space → Checked ``` If the radio button is already checked, the control does not repeatedly toggle it off through this custom Space-key behavior. This preserves the expected radio-button interaction model. --- # Focus Indicator When the radio button receives keyboard focus, a dotted focus ring is displayed around the radio circle. This provides a visual indication of which option currently has keyboard focus. The focus indicator is displayed only while the control is enabled and focused. Example: ```csharp option.Focus(); ``` The focus indicator is managed automatically by the control. --- # Enabled / Disabled State The standard `Enabled` property controls whether the user can interact with the radio button. ### Enabled ```csharp option.Enabled = true; ``` The control can be selected and displays its normal, hover, and ripple states. ### Disabled ```csharp option.Enabled = false; ``` The control displays its disabled appearance and cannot be interacted with normally. The mouse cursor also changes to the standard disabled/default cursor. --- # Right-to-Left Layout The control supports right-to-left layouts through the standard `RightToLeft` property. ### Left-to-right ```csharp option.RightToLeft = RightToLeft.No; ``` The radio circle is displayed on the left and the text on the right. ### Right-to-left ```csharp option.RightToLeft = RightToLeft.Yes; ``` The radio circle is displayed on the right and the text is positioned accordingly. Example: ```csharp var option = new FTRRadioButton { Text = "گزینه اول", RightToLeft = RightToLeft.Yes }; ``` This is useful for applications that support languages such as Arabic, Persian, or Hebrew. --- # Font Because `FTRRadioButton` inherits from the standard Windows Forms `RadioButton`, the `Font` property can be used to control the appearance of the option text. Example: ```csharp option.Font = new Font("Segoe UI", 11F); ``` The default font configured by the control is approximately: ```text Segoe UI, 10pt ``` --- # ForeColor `ForeColor` controls the color of the radio-button text. Example: ```csharp option.ForeColor = Color.Black; ``` The control also updates `ForeColor` when an FTR theme is applied. --- # Themes `FTRRadioButton` integrates with the FTR Controls theme system. The control supports the FTR theme modes provided by the theme manager, including: * Light * Dark * Color * Duotone Theme colors can affect: * Checked color * Unchecked color * Hover color * Disabled color * Ripple color * Text color The control automatically applies the active theme when it is created. --- # ApplyTheme The control exposes: ```csharp option.ApplyTheme(); ``` This reapplies the currently active FTR theme colors to the radio button. In normal usage, applications do not need to call this method manually because the control listens for theme changes and reapplies its theme automatically. It can be useful when an application needs to explicitly refresh the control's theme appearance. --- # Theme and Licensing The control's theme-color configuration is connected to the FTR Controls licensing system. When the required license is active, the control applies the appropriate FTR theme colors. Without an active license, Premium color customization cannot be changed through the corresponding Premium properties. The standard radio-button functionality remains available. --- # Premium Features The following `FTRRadioButton` properties require an appropriate FTR Controls Premium license: | Property | Purpose | | ---------------- | ------------------------------------ | | `CircleSize` | Changes the radio-circle diameter | | `CheckedColor` | Color of the selected radio button | | `UncheckedColor` | Color of the unselected radio border | | `HoverColor` | Color displayed while hovering | | `DisabledColor` | Color used in the disabled state | | `RippleColor` | Color of the ripple effect | If a Premium property is modified without the required license, the FTR Controls activation prompt is displayed when applicable and the requested property change is not applied. --- # Standard Features The following functionality is available as part of the standard radio-button experience: * `Text` * `Checked` * `AutoCheck` * `Font` * `ForeColor` * `Enabled` * `RightToLeft` * `CheckedChanged` * Keyboard interaction * Radio-button grouping * Focus handling * Selection animation * Ripple interaction --- # CheckedChanged Event `CheckedChanged` is the default event of `FTRRadioButton`. It occurs when the checked state changes. Example: ```csharp optionA.CheckedChanged += OptionA_CheckedChanged; private void OptionA_CheckedChanged(object sender, EventArgs e) { if (optionA.Checked) { ApplyOptionA(); } } ``` This is the recommended way to react to a user's selection. --- # Example: Basic Options A common usage scenario is a group of selectable options. ```csharp var optionA = new FTRRadioButton { Text = "Option A", Checked = true }; var optionB = new FTRRadioButton { Text = "Option B" }; var optionC = new FTRRadioButton { Text = "Option C" }; groupPanel.Controls.Add(optionA); groupPanel.Controls.Add(optionB); groupPanel.Controls.Add(optionC); ``` Then handle the selection: ```csharp optionA.CheckedChanged += (sender, e) => { if (optionA.Checked) { ApplyOptionA(); } }; optionB.CheckedChanged += (sender, e) => { if (optionB.Checked) { ApplyOptionB(); } }; optionC.CheckedChanged += (sender, e) => { if (optionC.Checked) { ApplyOptionC(); } }; ``` --- # Example: Customized Radio Button The following example demonstrates the Premium appearance options: ```csharp var option = new FTRRadioButton { Text = "Premium option", Checked = true, CircleSize = 22, CheckedColor = Color.DodgerBlue, UncheckedColor = Color.Gray, HoverColor = Color.DeepSkyBlue, DisabledColor = Color.LightGray, RippleColor = Color.DodgerBlue }; ``` The Premium properties in this example require an appropriate license. --- # Example: Right-to-Left Option ```csharp var option = new FTRRadioButton { Text = "گزینه مورد نظر", RightToLeft = RightToLeft.Yes, Checked = false }; ``` The control automatically places the radio circle and text according to the selected direction. --- # Example: Responding to Selection ```csharp var optionA = new FTRRadioButton { Text = "Automatic", Checked = true }; optionA.CheckedChanged += (sender, e) => { if (optionA.Checked) { mode = "Automatic"; } }; ``` The `CheckedChanged` event can be used to update application settings, switch UI content, or trigger other application behavior. --- # Layout and Minimum Size The control automatically maintains a minimum size based on `CircleSize`. The default circle size is: ```text 18 × 18 pixels ``` The initial minimum size is: ```text 28 × 22 pixels ``` The minimum size is recalculated when `CircleSize` changes. For example, increasing: ```csharp option.CircleSize = 24; ``` also increases the minimum size required by the control. This prevents the radio circle from being displayed outside the usable control area. --- # Recommended Customer Usage For a normal group of options: 1. Add several `FTRRadioButton` controls to the same appropriate container. 2. Set the `Text` of each option. 3. Set one option as `Checked = true` if a default selection is required. 4. Leave `AutoCheck` enabled for normal radio-button behavior. 5. Handle `CheckedChanged` when the application needs to respond to a selection. 6. Use `RightToLeft` for right-to-left applications. 7. Use Premium appearance properties only when the required FTR Controls license is available. --- # Quick Reference | Property / Event | Type | Default | Premium | | ---------------- | ------------- | ------------------------------- | ------- | | `Text` | `string` | — | No | | `Checked` | `bool` | `false` | No | | `AutoCheck` | `bool` | Standard `RadioButton` behavior | No | | `Font` | `Font` | `Segoe UI, 10pt` | No | | `ForeColor` | `Color` | Theme/default | No | | `Enabled` | `bool` | `true` | No | | `RightToLeft` | `RightToLeft` | Standard behavior | No | | `CircleSize` | `int` | `18` | Yes | | `CheckedColor` | `Color` | `RGB(0,120,215)` | Yes | | `UncheckedColor` | `Color` | `RGB(150,150,150)` | Yes | | `HoverColor` | `Color` | `RGB(0,150,255)` | Yes | | `DisabledColor` | `Color` | `RGB(200,200,200)` | Yes | | `RippleColor` | `Color` | `RGB(0,120,215)` | Yes | | `CheckedChanged` | Event | — | No | --- # Default Configuration When `FTRRadioButton` is created, its main defaults are approximately: ```text CircleSize = 18 Font = Segoe UI, 10pt BackColor = Transparent ForeColor = Black Enabled = true Checked = false ``` The visual colors may subsequently be updated by the active FTR theme when the required license is available. --- # Important Notes * `FTRRadioButton` is a standard Windows Forms `RadioButton` with an enhanced visual implementation. * It does not display the `FTRBaseControl` licensing watermark. * `CircleSize` cannot be smaller than `12`. * Changing `CircleSize` also changes the control's minimum size. * The Space key checks the control when it is currently unchecked and enabled. * The ripple effect is triggered by a left-mouse-button press on an enabled control. * The focus ring is displayed while the enabled control has keyboard focus. * Right-to-left mode changes both the position of the radio circle and the text layout. * `CheckedChanged` is the default event and should normally be used to react to selection changes. * Premium appearance properties require an appropriate FTR Controls license.