# Gauge Display & Value

## 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.
