Label & Tooltip Customization

This feature allows developers to customize the progress bar’s textual information and tooltip messages to provide clear, context-sensitive progress updates and enhanced user guidance.

Overview

The Label & Tooltip Customization feature enables the configuration of the progress bar’s text display and tooltips. Developers can toggle between displaying a percentage value or custom text on the progress bar, set the font and color for the label, and enable automatic color adjustments to ensure optimum contrast. Additionally, tooltips dynamically show progress information, offering immediate feedback to the user during mouse hover events.

Properties and Their Details

The table below summarizes the main properties related to label and tooltip customization:

Property

Description

Default Value

ShowPercentage

When true, displays the progress percentage on the progress bar; otherwise, the custom label (if provided) is shown.

true

CustomLabel

Allows setting a custom text label to be displayed on the progress bar instead of the percentage value.

(Empty String)

LabelFont

Defines the font style, size, and weight used for rendering the progress text on the control.

Segoe UI, 10pt, Bold

LabelColor

Sets the color of the text displayed on the progress bar; if AutoLabelColor is enabled, this value is automatically adjusted to ensure contrast.

White

AutoLabelColor

Enables automatic adjustment of the LabelColor based on the background or gradient fill, ensuring optimal readability in different progress states and themes.

true

Note: The tooltip text is automatically generated based on the current progress value or custom label. It displays the progress percentage or the custom text when the mouse hovers over the control.

Key Points

Aspect

Details

Dynamic Text Display

The control can show either a percentage value or a custom message on the progress bar, adapting to the application's messaging requirements.

Automatic Color Adaptation

With AutoLabelColor enabled, the control calculates and applies a contrasting text color based on the progress bar’s current color, ensuring legibility.

Contextual Tooltips

Tooltips provide additional context by displaying the same information as the label (percentage or custom text) when the user hovers over the progress bar.

Best Practices

Practice

Explanation

Use Clear and Readable Fonts

Choose a LabelFont that is legible and consistent with your application's overall typography to ensure that progress information is easy to read.

Leverage AutoLabelColor for Contrast

Keep AutoLabelColor enabled to automatically adjust the text color for optimal visibility, especially when the progress bar uses dynamic gradient backgrounds.

Customize Labels Based on Context

Use CustomLabel to display context-specific messages (e.g., “Loading…” or “Processing…”) when a percentage may not be sufficiently informative.

Test Tooltip Content

Verify that the tooltip text accurately reflects the progress state and provides clear guidance to the user, especially on different screen resolutions.

Common Pitfalls

Pitfall

Explanation

Avoidance Strategy

Inconsistent Text Contrast

Manually setting a LabelColor that clashes with the background or gradient can reduce readability.

Use AutoLabelColor to ensure the text color automatically contrasts with the progress bar's current color.

Overcrowded Label Display

Displaying overly verbose custom text might clutter the progress bar and distract from the actual progress indication.

Limit custom text length or combine it with percentage values to maintain a clear and concise message.

Tooltip Misalignment or Delay

Relying on tooltips without proper testing can result in delays or misaligned display, particularly on high-DPI screens.

Test tooltip behavior across different screen settings and adjust initial delays if necessary.

Usage Scenarios

Scenario

Description

Sample Code Integration

Standard Percentage Display

Use the default percentage display for a straightforward progress indication where numeric feedback is sufficient.

csharp // Initialize a progress bar with percentage display SiticoneHProgressBar progressBar = new SiticoneHProgressBar(); progressBar.ShowPercentage = true; this.Controls.Add(progressBar); 

Custom Text for Specific Operations

Provide a custom message (e.g., "Loading Data...") instead of a percentage when the task context requires descriptive progress messaging.

csharp // Initialize a progress bar with a custom label SiticoneHProgressBar progressBar = new SiticoneHProgressBar(); progressBar.ShowPercentage = false; progressBar.CustomLabel = "Loading Data..."; this.Controls.Add(progressBar); 

Enhanced Readability with Auto-Adjustment

Enable AutoLabelColor to automatically update the text color for optimal contrast, ensuring that the progress label remains legible against dynamic gradient backgrounds.

csharp // Create a progress bar that adapts its label color automatically SiticoneHProgressBar progressBar = new SiticoneHProgressBar(); progressBar.AutoLabelColor = true; progressBar.LabelFont = new Font("Segoe UI", 12, FontStyle.Bold); this.Controls.Add(progressBar); 

Code Example and Demo

Below is an extensive example demonstrating how to integrate and customize the Label & Tooltip Customization feature in a simple WinForms application:

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

namespace LabelTooltipDemo
{
    public class MainForm : Form
    {
        private SiticoneHProgressBar progressBar;
        private Button toggleDisplayButton;
        private Button changeFontButton;
        private bool showPercentage = true;

        public MainForm()
        {
            // Initialize the form
            Text = "Label & Tooltip Customization Demo";
            Size = new Size(600, 300);

            // Initialize the progress bar with default label settings
            progressBar = new SiticoneHProgressBar()
            {
                Location = new Point(50, 50),
                Size = new Size(500, 30),
                Value = 65,
                ShowPercentage = true,  // Display percentage by default
                LabelFont = new Font("Segoe UI", 10, FontStyle.Bold),
                // LabelColor is auto-updated if AutoLabelColor is enabled
                AutoLabelColor = true,
                CustomLabel = ""  // No custom label by default
            };

            // Button to toggle between percentage and custom text display
            toggleDisplayButton = new Button()
            {
                Text = "Toggle Label Mode",
                Location = new Point(50, 100),
                AutoSize = true
            };
            toggleDisplayButton.Click += ToggleDisplayButton_Click;

            // Button to change the label font
            changeFontButton = new Button()
            {
                Text = "Change Label Font",
                Location = new Point(200, 100),
                AutoSize = true
            };
            changeFontButton.Click += ChangeFontButton_Click;

            // Add controls to the form
            Controls.Add(progressBar);
            Controls.Add(toggleDisplayButton);
            Controls.Add(changeFontButton);
        }

        private void ToggleDisplayButton_Click(object sender, EventArgs e)
        {
            // Toggle between displaying percentage and a custom label
            showPercentage = !showPercentage;
            progressBar.ShowPercentage = showPercentage;
            progressBar.CustomLabel = showPercentage ? string.Empty : "Processing Data...";
            progressBar.Invalidate();  // Force redraw to update label
        }

        private void ChangeFontButton_Click(object sender, EventArgs e)
        {
            // Change the label font dynamically
            progressBar.LabelFont = new Font("Arial", 12, FontStyle.Italic);
            progressBar.Invalidate();
        }

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

Review

Aspect

Evaluation

Clarity of Display

The ability to toggle between a percentage display and a custom label provides clear and context-sensitive feedback to the user.

Readability

Automatic text color adjustment ensures that the progress label remains legible against varying backgrounds and gradient fills.

User Guidance

Dynamic tooltips enhance usability by providing immediate progress feedback when the mouse hovers over the control.

Summary

The Label & Tooltip Customization feature empowers developers to control the textual feedback provided by the progress bar. By offering options to display either a percentage or custom message, and by enabling fine-tuning of font and color settings (with automatic adjustments for optimal contrast), this feature ensures that the progress bar can be seamlessly integrated into diverse UI designs while providing clear and accessible progress information.

Additional Sections

Troubleshooting Tips

Tip

Description

Ensure Sufficient Contrast

If custom colors are used for the label, verify that they contrast well with the progress bar’s background or gradient to maintain readability.

Validate Tooltip Consistency

Confirm that the tooltip text accurately mirrors the label information, particularly when toggling between percentage and custom text modes.

Test on Multiple Screen Resolutions

Check the label and tooltip display on different resolutions and DPI settings to ensure consistent and clear text rendering.

Integration Checklist

Checklist Item

Status

Configure ShowPercentage and CustomLabel appropriately

[ ] Done

Set LabelFont and verify legibility

[ ] Done

Enable AutoLabelColor to ensure proper contrast

[ ] Done

Test tooltip behavior on mouse hover

[ ] Done

Validate label updates on progress changes

[ ] Done

This comprehensive documentation should assist developers in understanding, integrating, and leveraging the Label & Tooltip Customization feature of the provided control effectively.

PreviousGradient & Bar Styling NextRead‑Only Mode

Last updated 19 days ago