BeepLabel

Overview

BeepLabel is an enhanced label control that extends the functionality of standard WinForms labels with modern features including SVG image support, subheader text, multi-line text capabilities, automatic sizing, and advanced text formatting with theme integration.

Built on top of the BeepControl base class, BeepLabel inherits all the theming, styling, and animation capabilities while adding label-specific features like image-text relationships, font scaling, and sophisticated text alignment options.

Key Features

Basic Usage

// Create a basic BeepLabel
var label = new BeepLabel
{
    Text = "Welcome to Beep Controls",
    Size = new Size(200, 30),
    Location = new Point(10, 10),
    TextAlign = ContentAlignment.MiddleLeft
};

// Add to form
this.Controls.Add(label);

var imageLabel = new BeepLabel
{
    Text = "Status: Online",
    ImagePath = "icons/status-online.svg",
    TextImageRelation = TextImageRelation.ImageBeforeText,
    MaxImageSize = new Size(20, 20),
    ApplyThemeOnImage = true,
    AutoSize = true
};

var headerLabel = new BeepLabel
{
    Text = "John Doe",
    SubHeaderText = "Software Developer",
    HeaderSubheaderSpacing = 4,
    TextAlign = ContentAlignment.MiddleCenter,
    AutoSize = true
};

Properties

Text Properties

Font Properties

Image Properties

Layout Properties

Events

var label = new BeepLabel
{
    Text = "Clickable Label",
    Cursor = Cursors.Hand
};

// Handle click events for navigation
label.Click += (s, e) => {
    // Navigate to details page
    NavigateToDetails();
};

// Visual feedback on hover
label.MouseEnter += (s, e) => {
    label.ForeColor = Color.Blue;
};

label.MouseLeave += (s, e) => {
    label.ForeColor = SystemColors.ControlText;
};

// Update UI when text changes
label.TextChanged += (s, e) => {
  //  Console.WriteLine($"Label text changed to: {label.Text}");
    UpdateRelatedComponents();
};

Examples

public void CreateStatusLabels()
{
    var onlineStatus = new BeepLabel
    {
        Text = "System Online",
        ImagePath = "icons/status-success.svg",
        TextImageRelation = TextImageRelation.ImageBeforeText,
        MaxImageSize = new Size(16, 16),
        ApplyThemeOnImage = true,
        ForeColor = Color.Green,
        Location = new Point(20, 20),
        AutoSize = true
    };

    var warningStatus = new BeepLabel
    {
        Text = "High CPU Usage",
        SubHeaderText = "Current: 85%",
        ImagePath = "icons/warning.svg",
        TextImageRelation = TextImageRelation.ImageBeforeText,
        MaxImageSize = new Size(16, 16),
        ForeColor = Color.Orange,
        Location = new Point(20, 50),
        AutoSize = true
    };

    var errorStatus = new BeepLabel
    {
        Text = "Database Connection Failed",
        SubHeaderText = "Retrying in 30 seconds...",
        ImagePath = "icons/error.svg",
        TextImageRelation = TextImageRelation.ImageBeforeText,
        MaxImageSize = new Size(16, 16),
        ForeColor = Color.Red,
        Location = new Point(20, 80),
        AutoSize = true
    };

    this.Controls.AddRange(new Control[] { onlineStatus, warningStatus, errorStatus });
}

public BeepLabel CreateUserProfileLabel(User user)
{
    var profileLabel = new BeepLabel
    {
        Text = user.FullName,
        SubHeaderText = $"{user.Title} • {user.Department}",
        ImagePath = user.AvatarPath ?? "icons/user-circle.svg",
        TextImageRelation = TextImageRelation.ImageBeforeText,
        MaxImageSize = new Size(32, 32),
        HeaderSubheaderSpacing = 4,
        TextAlign = ContentAlignment.MiddleLeft,
        Size = new Size(250, 50),
        ApplyThemeOnImage = true,
        Cursor = Cursors.Hand
    };

    // Add click handler for profile viewing
    profileLabel.Click += (s, e) => {
        ShowUserProfile(user.Id);
    };

    // Hover effects
    profileLabel.MouseEnter += (s, e) => {
        profileLabel.BackColor = Color.FromArgb(240, 240, 240);
    };

    profileLabel.MouseLeave += (s, e) => {
        profileLabel.BackColor = Color.Transparent;
    };

    return profileLabel;
}

public BeepLabel CreateDescriptionLabel(string description, int maxWidth)
{
    var descriptionLabel = new BeepLabel
    {
        Text = description,
        Multiline = true,
        TextAlign = ContentAlignment.TopLeft,
        Size = new Size(maxWidth, 100),
        BorderStyle = BorderStyle.None,
        Padding = new Padding(8),
        AutoSize = false // Fixed width, variable height
    };

    // Calculate required height based on text
    using (var graphics = descriptionLabel.CreateGraphics())
    {
        var textSize =  TextUtils.MeasureText(graphics,description, descriptionLabel.Font, maxWidth - 16);
        descriptionLabel.Height = (int)Math.Ceiling(textSize.Height) + 16;
    }

    return descriptionLabel;
}

public class NotificationLabel : BeepLabel
{
    private int _notificationCount;

    public int NotificationCount
    {
        get => _notificationCount;
        set
        {
            _notificationCount = value;
            UpdateBadge();
        }
    }

    public NotificationLabel()
    {
        Text = "Messages";
        ImagePath = "icons/mail.svg";
        TextImageRelation = TextImageRelation.ImageBeforeText;
        AutoSize = true;
        MaxImageSize = new Size(24, 24);
        Margin = new Padding(10);
    }

    private void UpdateBadge()
    {
        if (_notificationCount > 0)
        {
            BadgeText = _notificationCount > 99 ? "99+" : _notificationCount.ToString();
            SubHeaderText = $"{_notificationCount} unread message{(_notificationCount != 1 ? "s" : "")}";
        }
        else
        {
            BadgeText = null;
            SubHeaderText = "No new messages";
        }
    }
}

// Usage
var notificationLabel = new NotificationLabel
{
    Location = new Point(20, 20)
};

// Update notification count
notificationLabel.NotificationCount = 5;

public BeepLabel CreateTitleLabel(string title, Size bounds)
{
    var titleLabel = new BeepLabel
    {
        Text = title,
        UseScaledFont = true,
        TextAlign = ContentAlignment.MiddleCenter,
        Size = bounds,
        BorderStyle = BorderStyle.FixedSingle,
        Font = new Font("Arial", 12, FontStyle.Bold) // Starting font size
    };

    // The font will automatically scale to fit the bounds
    return titleLabel;
}

// Create labels with different sizes
var smallTitle = CreateTitleLabel("Small Title", new Size(150, 30));
var largeTitle = CreateTitleLabel("Large Display Title", new Size(400, 80));

public class StatusLabel : BeepLabel
{
    public enum StatusType
    {
        Success,
        Warning,
        Error,
        Info
    }

    public void SetStatus(StatusType status, string message, string details = null)
    {
        Text = message;
        SubHeaderText = details;

        switch (status)
        {
            case StatusType.Success:
                ImagePath = "icons/check-circle.svg";
                ForeColor = Color.Green;
                break;
            case StatusType.Warning:
                ImagePath = "icons/warning-triangle.svg";
                ForeColor = Color.Orange;
                break;
            case StatusType.Error:
                ImagePath = "icons/x-circle.svg";
                ForeColor = Color.Red;
                break;
            case StatusType.Info:
                ImagePath = "icons/info-circle.svg";
                ForeColor = Color.Blue;
                break;
        }

        ApplyThemeOnImage = true;
        TextImageRelation = TextImageRelation.ImageBeforeText;
        MaxImageSize = new Size(16, 16);
        AutoSize = true;
    }
}

// Usage
var statusLabel = new StatusLabel();
statusLabel.SetStatus(StatusType.Success, "Operation completed", "All files processed successfully");
statusLabel.SetStatus(StatusType.Error, "Connection failed", "Unable to connect to server");
statusLabel.SetStatus(StatusType.Warning, "Low disk space", "Only 2GB remaining");

Theming

BeepLabel supports comprehensive theming through the BeepThemesManager system:

var label = new BeepLabel
{
    Text = "Themed Label",
    Theme = "DarkTheme",
    UseThemeFont = true
};

// Apply theme manually
label.ApplyTheme();

// Theme-specific properties applied:
// - LabelBackColor
// - LabelForeColor
// - LabelHoverBackColor
// - LabelBorderColor
// - LabelSmall font style

Theme-Responsive Features

• Automatic Colors - Background and foreground colors adapt to theme
• Font Inheritance - Fonts follow theme typography scale
• SVG Theming - SVG icons automatically colored with theme colors
• Subheader Styling - Secondary text inherits theme muted colors

// Override theme colors for specific label
var customLabel = new BeepLabel
{
    Text = "Custom Styled Label",
    LabelBackColor = Color.FromArgb(248, 249, 250),
    ForeColor = Color.FromArgb(33, 37, 41),
    SubHeaderForeColor = Color.FromArgb(108, 117, 125),
    IsColorFromTheme = false // Disable theme color inheritance
};

// Apply custom theme after setting properties
customLabel.ApplyTheme();

var themedLabel = new BeepLabel
{
    Text = "Status Message",
    ImagePath = "icons/status.svg",
    ApplyThemeOnImage = true, // SVG will use theme foreground color
    TextImageRelation = TextImageRelation.ImageBeforeText
};

// When theme changes, SVG color automatically updates
BeepThemesManager.SetTheme("DarkTheme");
themedLabel.ApplyTheme(); // SVG now uses dark theme colors

2026 Painter Pipeline Update

BeepLabel now uses a typed render pipeline (`BeepLabelState` + `BeepLabelLayoutContext`) with dedicated layout and painter helpers for more stable spacing, DPI behavior, and rendering consistency.

• Typed render contract: internal state/context objects drive measurement and painting.
• DPI-first geometry: spacing and image/text composition are normalized through helper logic.
• Image rendering: image painting is now routed through StyledImagePainter for tint/opacity consistency.
• Profiles: StyleProfile and ColorProfile provide runtime UX customization.
• Accessibility: accessible name/description and contrast-safe text color updates are deduplicated.
• Designer presets: quick presets are available for text-only, image-left, image-top, and title+subheader patterns.

Best Practices

🎨 UI/UX Guidelines

• Consistent sizing: Use AutoSize for dynamic content, fixed sizes for consistent layouts
• Proper contrast: Ensure sufficient color contrast between text and background
• Image alignment: Use consistent image-text relationships across your application
• Subheader usage: Use subheaders for secondary information, not essential data
• Font hierarchy: Maintain consistent font sizes and weights across similar label types

⚡ Performance

• Image optimization: Use appropriately sized images and prefer SVG for scalability
• Font caching: Let the control manage font creation and disposal
• Auto-sizing: Use sparingly in complex layouts to avoid constant recalculation
• Text measurement: Cache text size calculations for frequently updated labels
• Theme updates: Batch theme changes to avoid excessive redraws

♿ Accessibility

• Meaningful text: Ensure text is descriptive and accessible to screen readers
• Color independence: Don't rely solely on color to convey information
• Font sizes: Use readable font sizes and consider user scaling preferences
• Contrast ratios: Follow WCAG guidelines for text contrast
• Alt text: Provide meaningful descriptions for images

🔧 Technical Considerations

• Layout management: Consider container behavior when using AutoSize
• Text wrapping: Test multi-line behavior with various text lengths
• Image paths: Use relative paths and verify image file existence
• Memory management: Dispose of custom fonts and images properly
• Event handling: Be mindful of performance in frequently triggered events