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.
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.
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.
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.
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.
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.
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.
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.
Last updated