Layout and Text

Layout and Text allow developers to control the positioning and appearance of the button's text, ensuring that the content is displayed clearly and consistently within the control.

Overview

The Layout and Text feature of the SiticoneDashboardButton control provides customization options for text positioning and spacing through properties such as TextPadding and the inherited Text property. This enables developers to adjust the horizontal spacing between the button’s edge (or selection indicator) and its text content, as well as define the displayed text with support for multi-line content and automatic ellipsis.

---

Properties Table

Property	Type	Default Value	Description
TextPadding	int	15	Defines the horizontal spacing (in pixels) between the button's edge (or the selection indicator, if enabled) and the text.
Text	string	(empty)	Specifies the text displayed on the button; supports multi-line text with automatic ellipsis when needed.

Note: The Text property overrides the base control’s Text property to ensure that any changes trigger a redraw of the control.

---

Code Examples

Basic Integration

The example below demonstrates how to set up a SiticoneDashboardButton control with customized text and text padding:

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

public class LayoutAndTextDemoForm : Form
{
    public LayoutAndTextDemoForm()
    {
        // Instantiate the SiticoneDashboardButton control
        SiticoneDashboardButton dashboardButton = new SiticoneDashboardButton
        {
            Text = "Click Here to Proceed",
            Size = new Size(250, 45),
            Location = new Point(50, 50),
            // Adjust the text padding to create extra space between the text and the button's edge
            TextPadding = 20
        };

        // Add the button to the form
        Controls.Add(dashboardButton);
    }

    [STAThread]
    public static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new LayoutAndTextDemoForm());
    }
}

Advanced Customization

This example demonstrates dynamic adjustment of text padding based on the state of the control. In this scenario, if the left-side selection indicator is visible, the effective text padding is automatically recalculated to maintain a consistent layout:

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

public class DynamicLayoutForm : Form
{
    private SiticoneDashboardButton dashboardButton;

    public DynamicLayoutForm()
    {
        dashboardButton = new SiticoneDashboardButton
        {
            Text = "Dynamic Layout",
            Size = new Size(250, 45),
            Location = new Point(50, 50),
            TextPadding = 15,
            // Ensure the selection indicator is visible to observe the automatic padding adjustment
            ShowLeftIndicator = true,
            IndicatorWidth = 4
        };

        // Simulate a scenario where text padding is updated on an event (e.g., on button click)
        dashboardButton.Click += (sender, e) =>
        {
            // Increase text padding on each click for demonstration purposes
            dashboardButton.TextPadding += 5;
            if (dashboardButton.TextPadding > 30)
            {
                dashboardButton.TextPadding = 15; // Reset to default if too high
            }
        };

        Controls.Add(dashboardButton);
    }

    [STAThread]
    public static void Main()
    {
        Application.EnableVisualStyles();
        Application.Run(new DynamicLayoutForm());
    }
}

---

Key Points

Aspect	Details
Text Alignment	TextPadding determines the spacing between the text and the control edge, ensuring clear and consistent alignment.
Dynamic Adjustment	When a selection indicator is enabled, the effective text padding is automatically recalculated to account for its width.
Content Flexibility	The Text property supports multi-line text with automatic ellipsis for overflow handling.

---

Best Practices

Practice	Recommendation
Consistent Spacing	Use consistent TextPadding values across similar controls to maintain uniformity in the UI layout.
Responsive Layout	Consider adjusting text padding dynamically when additional UI elements (such as a selection indicator) are enabled.
Readability	Ensure that the text size and padding allow for clear readability, especially in multi-line scenarios.

---

Common Pitfalls

Pitfall	How to Avoid
Overcrowded Text Area	Avoid setting the TextPadding too low, which may lead to text colliding with the control’s borders or other UI elements.
Inconsistent Layout	Maintain a standard TextPadding value across different controls to avoid an inconsistent visual experience.
Ignoring State Dependencies	Remember that the effective text padding may change if the selection indicator is enabled, so test the layout in various states.

---

Usage Scenarios

Scenario	Example Use Case
Button Labeling	Use customized text and padding for primary call-to-action buttons to ensure the text is clear and prominently placed.
Responsive UI Elements	Dynamically adjust text padding in interactive dashboards where additional indicators or icons may be present.
Multi-Line Support	Leverage the multi-line text support to display longer messages or descriptions within the button, with automatic ellipsis.

---

Review

The Layout and Text feature in the SiticoneDashboardButton control offers comprehensive options to customize the text appearance and spacing. Developers can fine-tune the TextPadding property to ensure that the button’s content is displayed in a visually appealing and accessible manner. The provided examples illustrate both static and dynamic scenarios, emphasizing best practices and common pitfalls to guide proper integration.

---

Summary

Layout and Text customization in the SiticoneDashboardButton control enable precise control over text positioning and display. With properties such as TextPadding and the overridden Text property, developers can ensure that the button content is legible, well-aligned, and adaptive to changes in the control's state. Adhering to the best practices outlined in this documentation will help create an intuitive and consistent user interface.

---

Additional Resources

Resource	Description	Link/Reference
Control Source Code	Detailed implementation of text layout and padding customization.	Refer to the provided source code documentation.
.NET WinForms Documentation	Official guidelines on creating and styling WinForms controls.	https://docs.microsoft.com/dotnet/desktop/winforms/

This comprehensive documentation should assist developers in understanding, integrating, and customizing the Layout and Text feature of the SiticoneDashboardButton control in their .NET WinForms applications.