---
description: >-
  Customize and manage the label displayed alongside the Siticone CheckBox,
  enhancing user interaction and accessibility.
---

# Text Property

## **Overview**

The **Text Property** of the `SiticoneCheckBox` control allows developers to define and update the label associated with the checkbox. This label provides context and information to users, indicating the purpose or meaning of the checkbox within the application's user interface. By setting the **Text** property, developers ensure that the checkbox communicates effectively with users, enhancing usability and accessibility.

#### **Key Property**

The following table outlines the **public property** associated with the Text of the `SiticoneCheckBox`. This property enables comprehensive customization of the checkbox's label based on design and functional requirements.

| **Property** | **Type** | **Description**                                                                                                           |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Text`       | `string` | Overrides the base `Text` property to update the accessible name and adjust the control's size based on the text content. |

#### **Detailed Property Description**

**`Text` (`string`)**

**Description:**\
The `Text` property defines the label displayed alongside the `SiticoneCheckBox`. Overriding the base `Text` property, this implementation ensures that when the text is updated, the control's accessibility features and layout adjust accordingly. Specifically, setting the `Text` property updates the `AccessibleName`, recalculates the control's size to accommodate the new text, and triggers a repaint of the control to reflect the changes visually.

**Usage:**\
Assign a `string` value to define or update the checkbox's label. Changing the `Text` property not only alters the displayed text but also ensures that the control resizes appropriately and maintains accessibility standards.

**Example:**

```csharp
// Set the checkbox text to "Accept Terms and Conditions"
siticoneCheckBox.Text = "Accept Terms and Conditions";

// Update the checkbox text dynamically based on user input or application logic
siticoneCheckBox.Text = "Subscribe to Newsletter";
```

**Implementation Details:**

```csharp
// Override text property to update accessible name
public override string Text
{
    get => base.Text;
    set
    {
        base.Text = value;
        AccessibleName = value;
        UpdateControlSize();
        Invalidate();
    }
}
```

* **AccessibleName:**\
  The `AccessibleName` property is set to the same value as `Text`, ensuring that assistive technologies (e.g., screen readers) can accurately describe the checkbox to users with disabilities.
* **UpdateControlSize():**\
  This method recalculates the control's size based on the new text, ensuring that the label is fully visible and that the checkbox maintains an appropriate layout within its container or parent form.
* **Invalidate():**\
  Triggers a repaint of the control, ensuring that the updated text and any layout changes are rendered immediately on the user interface.

***

#### **Code Examples**

**Example 1: Setting and Updating the Text Property**

```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

public class TextPropertyForm : Form
{
    private SiticoneCheckBox textCheckBox;
    private Button updateTextButton;

    public TextPropertyForm()
    {
        InitializeComponent();
    }

    private void InitializeComponent()
    {
        this.textCheckBox = new SiticoneCheckBox();
        this.updateTextButton = new Button();
        this.SuspendLayout();

        // 
        // textCheckBox
        // 
        this.textCheckBox.Text = "I agree to the terms and conditions";
        this.textCheckBox.Location = new Point(50, 50);
        this.textCheckBox.Size = new Size(250, 35);

        // 
        // updateTextButton
        // 
        this.updateTextButton.Text = "Update Text";
        this.updateTextButton.Location = new Point(50, 100);
        this.updateTextButton.Click += new EventHandler(this.UpdateTextButton_Click);

        // 
        // TextPropertyForm
        // 
        this.ClientSize = new Size(350, 200);
        this.Controls.Add(this.textCheckBox);
        this.Controls.Add(this.updateTextButton);
        this.Text = "SiticoneCheckBox - Text Property Example";
        this.ResumeLayout(false);
    }

    private void UpdateTextButton_Click(object sender, EventArgs e)
    {
        // Update the checkbox text dynamically
        this.textCheckBox.Text = "Subscribe to our newsletter for updates";
    }
}
```

**Explanation:**

* The form contains a `SiticoneCheckBox` initialized with the text `"I agree to the terms and conditions"`.
* A button labeled `"Update Text"` allows users to dynamically change the checkbox's text to `"Subscribe to our newsletter for updates"`.
* When the button is clicked, the `Text` property is updated, triggering `AccessibleName` update, control size recalculation, and repainting of the checkbox to reflect the new label.

***

**Example 2: Ensuring Accessibility with the Text Property**

```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

public class AccessibilityTextForm : Form
{
    private SiticoneCheckBox accessibilityCheckBox;

    public AccessibilityTextForm()
    {
        InitializeComponent();
    }

    private void InitializeComponent()
    {
        this.accessibilityCheckBox = new SiticoneCheckBox();
        this.SuspendLayout();

        // 
        // accessibilityCheckBox
        // 
        this.accessibilityCheckBox.Text = "Enable Voice Commands";
        this.accessibilityCheckBox.Location = new Point(60, 60);
        this.accessibilityCheckBox.Size = new Size(220, 35);
        this.accessibilityCheckBox.FocusColor = Color.Green;
        this.accessibilityCheckBox.FocusBorderWidth = 2;
        this.accessibilityCheckBox.ShowFocusCue = true;

        // 
        // AccessibilityTextForm
        // 
        this.ClientSize = new Size(350, 200);
        this.Controls.Add(this.accessibilityCheckBox);
        this.Text = "SiticoneCheckBox - Accessibility Text Example";
        this.ResumeLayout(false);
    }
}
```

**Explanation:**

* The checkbox is labeled `"Enable Voice Commands"`, providing clear context to users.
* By setting the `Text` property, the `AccessibleName` is also updated, ensuring that screen readers convey the checkbox's purpose accurately.
* The focus appearance properties (`FocusColor`, `FocusBorderWidth`, `ShowFocusCue`) are configured to enhance visibility when the checkbox gains focus, further aiding accessibility.

***

#### **Best Practices**

Adhering to best practices ensures that the **Text Property** enhances the user interface without introducing design inconsistencies or usability issues. The following table outlines key best practices for effectively implementing the Text Property in the `SiticoneCheckBox` control.

| **Best Practice**                                | **Description**                                                                                                                                                      |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use Descriptive Labels**                       | Ensure that the `Text` property clearly describes the purpose of the checkbox, enabling users to understand its function at a glance.                                |
| **Maintain Consistent Text Length**              | Use similar text lengths for checkboxes in the same context to maintain a uniform and organized layout within the application.                                       |
| **Update AccessibleName Appropriately**          | Rely on the overridden `Text` property to automatically update the `AccessibleName`, ensuring accessibility compliance without additional manual steps.              |
| **Adjust Control Size Dynamically**              | Utilize the automatic size recalculation when the `Text` property changes to accommodate different text lengths, preventing text truncation or excessive whitespace. |
| **Ensure Readability**                           | Choose font styles and sizes that make the text easy to read, enhancing overall usability and user experience.                                                       |
| **Avoid Ambiguity**                              | Use clear and unambiguous text to prevent confusion, ensuring that users can accurately interpret the checkbox's intent.                                             |
| **Support Localization**                         | When developing multi-language applications, ensure that the `Text` property can accommodate translations without breaking the layout or design.                     |
| **Leverage Tooltips for Additional Information** | Combine the `Text` property with tooltips to provide supplementary information or guidance without cluttering the UI.                                                |
| **Consistent Alignment**                         | Align checkbox labels consistently (e.g., left-aligned) across the application to maintain a cohesive and professional appearance.                                   |
| **Responsive Design Considerations**             | Ensure that the `Text` property and corresponding layout adjustments respond well to different screen sizes and resolutions, maintaining usability across devices.   |

***

#### **Common Pitfalls and Design Considerations**

Understanding and avoiding common pitfalls ensures that the **Text Property** is implemented effectively, maintaining both functionality and visual appeal. The following tables detail these aspects.

**Common Pitfalls**

| **Pitfall**                  | **Description**                                                                                                                            | **Solution**                                                                                                                                                                                 |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Truncated Text**           | Setting long text without adjusting the control size can lead to text being cut off or overlapping other UI elements.                      | Utilize the overridden `Text` property to automatically adjust the control size based on the text content. Ensure that `MinimumSize` and `Size` properties accommodate varying text lengths. |
| **Inconsistent Text Usage**  | Using different text styles or lengths across similar checkboxes can lead to a disjointed and unprofessional UI.                           | Maintain consistent text properties (font, size, alignment) across similar controls to ensure uniformity.                                                                                    |
| **Neglecting Accessibility** | Failing to update the `AccessibleName` alongside the `Text` property can hinder accessibility for users relying on assistive technologies. | Rely on the overridden `Text` property to automatically update `AccessibleName`, ensuring accessibility compliance.                                                                          |
| **Overcrowded UI**           | Adding too many checkboxes with lengthy text in a confined space can clutter the interface and overwhelm users.                            | Balance the number and length of checkbox labels with the available UI space. Consider grouping related checkboxes or using multi-line labels where appropriate.                             |
| **Ignoring Localization**    | Not accounting for text length variations in different languages can disrupt the layout in localized versions of the application.          | Design layouts to be flexible and accommodate varying text lengths, ensuring that localized text fits without issues.                                                                        |
| **Poor Readability**         | Using fonts or colors that reduce text readability can hinder user comprehension and interaction.                                          | Choose clear, legible fonts and ensure sufficient contrast between the text and background colors.                                                                                           |

***

**Design Considerations**

Designing effective labels involves several key considerations to ensure that the checkbox is both functional and aesthetically pleasing. The following table outlines these considerations.

| **Aspect**                       | **Consideration**                                                                                                                                    | **Implementation Tips**                                                                                                                      |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Clarity and Brevity**          | Ensure that the `Text` property conveys the checkbox's purpose clearly and concisely, avoiding unnecessary complexity.                               | Use straightforward language and avoid overly long labels. Keep text brief while maintaining clarity.                                        |
| **Font Selection**               | Choose fonts that enhance readability and align with the application's overall design language.                                                      | Use standard, legible fonts like Segoe UI, Arial, or the application's primary font. Ensure font size is appropriate for readability.        |
| **Text Alignment**               | Align checkbox labels consistently to maintain a professional and organized appearance.                                                              | Typically, use left-aligned text for checkboxes. Ensure alignment is consistent across all checkbox instances within the application.        |
| **Responsive Layouts**           | Design labels to adapt gracefully to different screen sizes and resolutions, maintaining readability and layout integrity.                           | Utilize dynamic sizing and positioning based on the `Text` property. Test labels on various devices and screen sizes to ensure adaptability. |
| **Contrast and Visibility**      | Ensure that the text color contrasts adequately with the background to enhance readability, especially in different states (e.g., focused, hovered). | Use high-contrast color combinations. Adjust text color based on the checkbox's state to maintain visibility and readability.                |
| **Accessibility Compliance**     | Align label design with accessibility standards, making sure that text is easily readable by users with visual impairments.                          | Use sufficient font sizes, avoid overly stylized fonts, and ensure that text remains clear in all states and themes.                         |
| **Localization Support**         | Design labels to accommodate translations, ensuring that text length variations do not disrupt the layout.                                           | Allow for flexible control sizing. Test labels with longer and shorter text strings to ensure that the layout remains intact.                |
| **Tooltips for Additional Info** | Use tooltips to provide supplementary information or guidance without cluttering the UI.                                                             | Implement tooltips for complex or additional explanations related to the checkbox's purpose. Ensure tooltips are concise and informative.    |

***

#### **Summary and Review**

The **Text Property** of the `SiticoneCheckBox` control offers a straightforward yet powerful way to define and manage the label associated with the checkbox. By overriding the base `Text` property, the control ensures that any updates to the label not only change the displayed text but also enhance accessibility through the `AccessibleName` and maintain layout integrity by adjusting the control's size. This seamless integration of text management facilitates the creation of user-friendly and accessible interfaces.

**Key Takeaways:**

| **Point**                              | **Explanation**                                                                                                                                                |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Seamless Accessibility Integration** | Overriding the `Text` property to automatically update the `AccessibleName` ensures that assistive technologies accurately convey the checkbox's purpose.      |
| **Dynamic Layout Adjustments**         | The `Text` property triggers `UpdateControlSize()` and `Invalidate()`, ensuring that the control resizes and repaints appropriately based on the text content. |
| **Enhanced Usability**                 | Clear and descriptive labels improve user understanding and interaction with the checkbox, enhancing overall usability of the application.                     |
| **Consistency and Uniformity**         | Maintaining consistent text properties across similar controls fosters a cohesive and professional user interface, improving the overall user experience.      |
| **Localization and Flexibility**       | The implementation supports dynamic text changes, facilitating localization and ensuring that labels accommodate varying text lengths without layout issues.   |
| **Performance Optimization**           | Efficiently managing text updates and control repainting ensures that enhanced visual features do not compromise application performance.                      |
| **Customization Flexibility**          | Developers can tailor the checkbox's label to meet specific design requirements and preferences, leveraging the `Text` property for varied use cases.          |
| **Responsive Design Support**          | The `Text` property works in tandem with layout adjustments to maintain consistent appearance and functionality across different devices and screen sizes.     |

By adhering to the best practices and design considerations outlined above, developers can effectively leverage the **Text Property** to create checkboxes that are not only functional but also enhance the overall visual structure and user experience of their applications







