> For the complete documentation index, see [llms.txt](https://docs-siticoneframework.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/gauges-and-measurement/siticone-gaugenumeric/gauge-display-and-value.md). # Gauge Display & Value A concise control that manages the displayed value on the gauge—including smooth animated transitions and immediate value resets—to provide dynamic visual feedback in .NET WinForms applications. ## Overview The Gauge Display & Value feature enables developers to set, animate, and reset the gauge’s value. This is achieved through properties such as `Value`, `AnimationSpeed`, and `ShowAnimation`, and methods like `AnimateToValue()` and `ResetValue()`. These elements work together to ensure that value changes are rendered with smooth transitions, providing a polished user experience. *** ### Key Points | Aspect | Description | Code Reference / Example | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Value Property | Represents the current gauge value and supports animated updates when changed. | `public float Value { get => GetTargetValue(); set => SetTargetValue(value); }` | | Animation Control | Smooth value transition can be enabled/disabled and controlled by `AnimationSpeed` and `ShowAnimation` properties. | `public float AnimationSpeed { get => _animationSpeed; set { /* ... */ } }public bool ShowAnimation { get => _showAnimation; set { /* ... */ } }` | | Animation Methods | Methods like `AnimateToValue(float targetValue)` and `ResetValue()` provide programmatic control over the gauge value transitions. | `csharp\n// Animate to a new value\nmyGauge.AnimateToValue(75.5f);\n\n// Reset gauge to minimum value\nmyGauge.ResetValue();` | | Internal Animation Logic | Uses a timer (\_animationTimer) and physics-based spring equations to calculate the smooth transition of values. | See the internal method `HandleValueAnimation()` for details on velocity, spring force, and damping calculations. | *** ### Best Practices | Recommendation | Details | Example / Explanation | | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | Set a Reasonable Animation Speed | Choose an `AnimationSpeed` between 0.1 and 20.0 to ensure smooth transitions without sluggishness. | `csharp\nmyGauge.AnimationSpeed = 5f; // Moderate speed for smooth transitions` | | Enable Animation Only When Needed | Use `ShowAnimation` to disable animations in scenarios where instant updates are preferred. | `csharp\nmyGauge.ShowAnimation = false; // Disable animation for immediate updates` | | Use AnimateToValue for Dynamic Changes | Call `AnimateToValue()` instead of setting the `Value` property directly when an animated transition is desired. | `csharp\n// Preferred for animated transitions\nmyGauge.AnimateToValue(85f);` | | Reset Value Appropriately | Use `ResetValue()` to set the gauge to its minimum value rather than directly setting properties. | `csharp\n// Reset to default minimum value\nmyGauge.ResetValue();` | *** ### Common Pitfalls | Issue | Details | Resolution / Code Example | | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Overly High Animation Speed | Setting `AnimationSpeed` too high may result in erratic or overly fast animations. | `csharp\n// Avoid speeds greater than 20.0\nmyGauge.AnimationSpeed = 25f; // Incorrect -> Clamp to maximum acceptable value` | | Disabling Animation Improperly | Directly setting the Value property while animations are enabled might lead to inconsistent behavior. | Instead of `myGauge.Value = 50;`, prefer using `AnimateToValue(50);` if `ShowAnimation` is true. | | Incorrect Range Values | Setting a gauge value outside the defined `MinValue` and `MaxValue` range will be clamped, possibly causing confusion. | Ensure that any value passed to `SetTargetValue()` lies between `MinValue` and `MaxValue`.Example: If `MinValue` is 0 and `MaxValue` is 100, ensure that the new value is within 0–100. | *** ### Usage Scenarios | Scenario | Description | Sample Code | | -------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | Simple Gauge Update | Update the gauge value with an animated transition upon receiving new data. | `csharp\n// Update gauge with animation\nmyGauge.AnimationSpeed = 6f;\nmyGauge.ShowAnimation = true;\nmyGauge.AnimateToValue(90f);` | | Instant Value Change | For scenarios where immediate feedback is needed, disable animation and set the value directly. | `csharp\n// Immediate update without animation\nmyGauge.ShowAnimation = false;\nmyGauge.Value = 65f;` | | Resetting the Gauge | Reset the gauge to its starting value as part of an initialization routine. | `csharp\n// Reset gauge\nmyGauge.ResetValue();` | *** ### Real Life Usage Scenarios | Scenario | Description | Sample Integration Code | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Dashboard Application | A financial dashboard where real-time metrics (e.g., percentage performance) are updated continuously with smooth animations. | `csharp\n// In a dashboard form update method\nprivate void UpdatePerformance(float performancePercentage) {\n // Ensure value is within gauge range\n myGauge.MinValue = 0f;\n myGauge.MaxValue = 100f;\n myGauge.AnimationSpeed = 4f;\n myGauge.ShowAnimation = true;\n myGauge.AnimateToValue(performancePercentage);\n}` | | Monitoring Tool | A system monitoring tool that uses the gauge to display CPU or memory usage with instant or animated updates depending on user preferences. | `csharp\n// Updating gauge in a system monitoring application\nprivate void OnCpuUsageUpdated(float cpuUsage) {\n // Option to disable animation for critical alerts\n myGauge.ShowAnimation = cpuUsage < 80f;\n myGauge.Value = cpuUsage; // Direct assignment for immediate update if necessary\n}` | *** ### Troubleshooting Tips | Tip | Explanation | Action | | --------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | Check Property Ranges | Ensure that the value provided is within the `MinValue` and `MaxValue` range; values outside will be clamped. | Verify the settings in your code:\`\`\`csharp\nif(newValue < myGauge.MinValue | | Verify Animation Settings | If animations do not appear smooth, experiment with different `AnimationSpeed` and toggle `ShowAnimation`. | Test with:`csharp\nmyGauge.AnimationSpeed = 5f;\nmyGauge.ShowAnimation = true;` | | Use Code Examples for Integration | Follow the provided code samples to ensure proper usage of `AnimateToValue()` and `ResetValue()`. | Compare your implementation with the sample integration code provided above. | *** ### Review | Aspect | Comments | Suggestions | | ------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | Functionality | Provides a smooth visual transition for gauge value changes with options for both animated and instant updates. | Ensure that the gauge’s `MinValue` and `MaxValue` are configured correctly to avoid unexpected clamping. | | Ease of Integration | Simple to use via properties and methods with clear code examples. | Refer to the provided usage scenarios to quickly integrate the feature into your applications. | | Flexibility | Offers both automatic animation and direct value assignment, giving developers full control. | Adjust `AnimationSpeed` and `ShowAnimation` based on the application’s responsiveness requirements. | *** ### Summary | Summary Point | Description | | --------------------- | ------------------------------------------------------------------------------------------------------ | | Feature Overview | Controls the gauge’s display value, supporting animated transitions, direct value setting, and resets. | | Core Properties | `Value`, `AnimationSpeed`, and `ShowAnimation` determine the appearance and transition behavior. | | Methods | `AnimateToValue()` for smooth transitions and `ResetValue()` for returning to the default state. | | Integration and Usage | Ideal for dashboards and monitoring applications where dynamic feedback is essential. | | Best Practices | Use animations selectively, ensure proper value ranges, and follow provided code examples. | | Troubleshooting | Check configuration ranges, animation settings, and refer to code examples for correct integration. | *** ### Additional Sections #### Integration Demo Below is a full sample code snippet to demonstrate how to integrate the Gauge Display & Value feature into a WinForms application: ```csharp using System; using System.Windows.Forms; using SiticoneNetFrameworkUI; // Assuming the namespace from the provided code public class DemoForm : Form { private SiticoneGaugeNumeric myGauge; private Button updateButton; private Button resetButton; private Timer updateTimer; public DemoForm() { // Initialize Gauge myGauge = new SiticoneGaugeNumeric { MinValue = 0f, MaxValue = 100f, Value = 50f, // Starting value AnimationSpeed = 5f, ShowAnimation = true, Size = new System.Drawing.Size(300, 300), Location = new System.Drawing.Point(50, 30) }; // Initialize Update Button updateButton = new Button { Text = "Update Gauge", Location = new System.Drawing.Point(50, 350), Width = 100 }; updateButton.Click += UpdateButton_Click; // Initialize Reset Button resetButton = new Button { Text = "Reset Gauge", Location = new System.Drawing.Point(170, 350), Width = 100 }; resetButton.Click += (s, e) => myGauge.ResetValue(); // Optional: Timer to simulate periodic updates updateTimer = new Timer { Interval = 3000 }; updateTimer.Tick += (s, e) => { Random rand = new Random(); float newValue = (float)(rand.NextDouble() * 100); myGauge.AnimateToValue(newValue); }; updateTimer.Start(); // Add controls to the Form Controls.Add(myGauge); Controls.Add(updateButton); Controls.Add(resetButton); } private void UpdateButton_Click(object sender, EventArgs e) { // Example: Increase gauge value by 10 with animation float newValue = myGauge.Value + 10; if (newValue > myGauge.MaxValue) newValue = myGauge.MaxValue; myGauge.AnimateToValue(newValue); } [STAThread] static void Main() { Application.EnableVisualStyles(); Application.Run(new DemoForm()); } } ``` #### API Reference | Member | Type | Description | | --------------------------- | ----- | --------------------------------------------------------------------- | | Value | float | Gets or sets the current gauge value. | | AnimationSpeed | float | Controls the speed of the animated transition when the value changes. | | ShowAnimation | bool | Enables or disables smooth value animation. | | AnimateToValue(float value) | void | Animates the gauge to the specified value. | | ResetValue() | void | Resets the gauge value to the defined minimum value. | *** This documentation should serve as a complete guide for integrating and using the Gauge Display & Value feature in your WinForms applications. Use the provided examples and tables as a reference for best practices and troubleshooting when customizing the gauge's behavior and appearance.