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<br>// Initialize a progress bar with percentage display<br>SiticoneHProgressBar progressBar = new SiticoneHProgressBar();<br>progressBar.ShowPercentage = true;<br>this.Controls.Add(progressBar);<br>
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<br>// Initialize a progress bar with a custom label<br>SiticoneHProgressBar progressBar = new SiticoneHProgressBar();<br>progressBar.ShowPercentage = false;<br>progressBar.CustomLabel = "Loading Data...";<br>this.Controls.Add(progressBar);<br>
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<br>// Create a progress bar that adapts its label color automatically<br>SiticoneHProgressBar progressBar = new SiticoneHProgressBar();<br>progressBar.AutoLabelColor = true;<br>progressBar.LabelFont = new Font("Segoe UI", 12, FontStyle.Bold);<br>this.Controls.Add(progressBar);<br>

---

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.