Display & Format Options

This feature allows you to control the on-screen presentation and formatting of the gauge’s value and related information, such as tooltip text and displayed numeric value styling.

Overview

The Display & Format Options feature exposes public properties in the SiticoneGaugeClock control that allow developers to customize the appearance and behavior of textual elements. These include options for showing tooltips with formatted gauge values, displaying the gauge’s numeric value directly on the control, and adjusting the size of that text. These options ensure that the gauge not only conveys the correct data but also integrates seamlessly with your application's visual design.

---

Feature Settings and Customization

The table below outlines the available properties for Display & Format Options, describing their function, typical default values, and a sample usage snippet.

Property	Description	Default Value	Usage Example
ShowTooltip	Determines whether a tooltip is displayed when the user hovers over the gauge, providing formatted value information.	false (by default)	gauge.ShowTooltip = true;
TooltipFormat	Defines the format string used to display the gauge’s value within the tooltip.	"{0:F1}" (or similar default)	gauge.TooltipFormat = "{0:F2}";
ShowGaugeText	Specifies whether the numeric gauge value is displayed directly on the gauge face.	true or false (as set during initialization)	gauge.ShowGaugeText = true;
TextSize	Sets the size of the displayed gauge value text, allowing for adjustments based on gauge size and design requirements.	30f (or as defined in initialization)	gauge.TextSize = 28f;

---

Key Points

The table below summarizes the critical aspects of the Display & Format Options feature.

Aspect	Details
Data Visibility	Provides control over whether numeric data is directly visible on the gauge and through tooltips.
Customizable Formatting	Allows the use of custom format strings to ensure the displayed values meet design and localization requirements.
Adaptability	Enables adjustments of text size to ensure readability on various display sizes and resolutions.

---

Best Practices

The following table outlines best practices to get the most from the Display & Format Options feature.

Practice	Explanation	Code Example
Enable Tooltips for Clarity	When the gauge is small or embedded in a busy UI, displaying a tooltip can help users see precise values.	gauge.ShowTooltip = true; gauge.TooltipFormat = "{0:F1}";
Use Consistent Formatting	Apply a consistent format string that suits the context (e.g., fixed decimal places) to avoid confusion.	gauge.TooltipFormat = "{0:F2}";
Optimize Text Size	Choose a TextSize that ensures the gauge value is legible without interfering with other visual elements.	gauge.TextSize = 26f;
Test Visibility Across Devices	Verify that both the tooltip and gauge text display correctly across different screen resolutions and DPI settings.	(Ensure testing on various hardware configurations.)

---

Common Pitfalls

Be aware of these common pitfalls when configuring display and formatting options.

Pitfall	Description	Recommendation
Overly Complex Tooltip Formats	Using an overly complex format string might confuse users or lead to inconsistent displays.	Keep the format simple and consistent (e.g., using fixed decimal places).
Poor Contrast with Background	Displayed text that does not contrast well with the gauge background may become unreadable.	Choose text colors and sizes that ensure high contrast and readability.
Inconsistent Display Modes	Switching between showing gauge text and relying solely on tooltips can confuse the end user if not handled consistently.	Decide on a unified approach based on application design and stick with it.

---

Usage Scenarios

The table below outlines typical scenarios where Display & Format Options customization is advantageous.

Scenario	Description	Sample Code
Mobile Applications	For smaller displays, tooltips can offer precise value details while the gauge itself may show minimal text.	gauge.ShowTooltip = true; gauge.ShowGaugeText = false;
Desktop Dashboards	Displaying the gauge value directly on the control with clear, large text is beneficial for quick data reference.	gauge.ShowGaugeText = true; gauge.TextSize = 30f;
Localization Requirements	Custom format strings ensure that numeric values adhere to local conventions (e.g., decimal separators).	gauge.TooltipFormat = "{0:F2}";

---

Real Life Usage Scenarios

The table below presents real-world examples demonstrating the application of Display & Format Options.

Real Life Scenario	Description	Code Example
Financial Trading Interface	A gauge displaying stock prices with a tooltip showing values formatted to two decimal places for precision.	gauge.ShowTooltip = true; gauge.TooltipFormat = "{0:F2}";
Medical Monitoring Dashboard	In a critical care environment, displaying a large, clearly formatted gauge value helps caregivers quickly assess conditions.	gauge.ShowGaugeText = true; gauge.TextSize = 32f;
Industrial Control Systems	When gauges are part of a busy control panel, enabling tooltips can declutter the interface while still providing exact values on demand.	gauge.ShowTooltip = true; gauge.ShowGaugeText = false;

---

Troubleshooting Tips

If you encounter issues with the display or formatting of gauge information, consider the following tips.

Issue	Potential Cause	Suggested Resolution
Text Not Readable	The selected TextSize may be too small, or there might be insufficient contrast with the background.	Increase TextSize and/or adjust the gauge's background colors for better contrast.
Tooltip Not Appearing	Tooltip might not appear if ShowTooltip is not enabled or if there is a conflict with other event handlers.	Ensure that ShowTooltip is set to true and that no other control is intercepting the mouse events.
Inconsistent Format Display	The format string might not be correctly defined, causing unexpected value formatting.	Verify that the TooltipFormat string is valid and matches the expected format (e.g., "{0:F1}").

---

Integration Example

Below is a complete code sample showing how to integrate and customize the Display & Format Options in a WinForms application:

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI; // Adjust the namespace to match your project setup

namespace GaugeDemoApp
{
    public class MainForm : Form
    {
        private SiticoneGaugeClock gauge;

        public MainForm()
        {
            InitializeComponent();
            ConfigureDisplayOptions();
        }

        private void InitializeComponent()
        {
            this.gauge = new SiticoneGaugeClock();
            this.SuspendLayout();
            // 
            // gauge
            // 
            this.gauge.Location = new Point(30, 30);
            this.gauge.Size = new Size(300, 300);
            // Display & Format Options customizations
            this.gauge.ShowTooltip = true;
            this.gauge.TooltipFormat = "{0:F2}"; // Displays the gauge value with two decimal places
            this.gauge.ShowGaugeText = true;
            this.gauge.TextSize = 28f;
            // 
            // MainForm
            // 
            this.ClientSize = new Size(360, 360);
            this.Controls.Add(this.gauge);
            this.Text = "Gauge Demo - Display & Format Options";
            this.ResumeLayout(false);
        }

        private void ConfigureDisplayOptions()
        {
            // Further runtime adjustments can be added here if necessary.
        }

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

In this example, the gauge is configured to display both a tooltip and the numeric value directly on its face. The tooltip is set to format the value to two decimal places, and the displayed text size is adjusted for optimal readability.

---

Review

The Display & Format Options feature provides comprehensive control over how the gauge’s data is presented to the user. By offering properties for tooltips, direct text display, and text sizing, it allows for a versatile approach that can adapt to various interface designs and user needs.

---

Summary

The Display & Format Options feature allows developers to fine-tune how numeric information is rendered on the gauge. Through properties like ShowTooltip, TooltipFormat, ShowGaugeText, and TextSize, you can ensure that the gauge displays data in a clear and visually appealing manner. Detailed tables, best practices, usage scenarios, troubleshooting tips, and an integration example have been provided to facilitate seamless integration and effective customization in your WinForms applications.

---

Additional sections such as Key Points, Best Practices, and Real Life Usage Scenarios further assist in optimizing the display and ensuring that your gauge’s formatted output meets both aesthetic and functional requirements.