> 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/interaction-and-tool-tip.md). # Interaction & Tool-tip A control feature that enables interactive modification of the gauge value via mouse input and displays a customizable tool-tip on hover. ## Overview The Interaction & Tooltip feature allows users to directly manipulate the gauge value by clicking and dragging, while providing immediate visual feedback through a tooltip that shows the current value. Key properties include `InteractiveMode`, `ShowTooltip`, and `TooltipFormat`, and the control manages mouse events to update the gauge value dynamically. This feature improves user engagement and clarity by offering both interactive adjustment and context-sensitive tooltips. *** ### Key Points | Aspect | Description | Code Reference / Example | | --------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Interactive Mode | Enables users to change the gauge value using mouse interaction (click-and-drag). | `csharp\nmyGauge.InteractiveMode = true;` | | Tooltip Visibility | Shows or hides a tooltip on hover to display the current gauge value. | `csharp\nmyGauge.ShowTooltip = true;` | | Tooltip Customization | Allows developers to set a custom format for the tooltip text using the `TooltipFormat` property. | `csharp\nmyGauge.TooltipFormat = "{0:F1}"; // e.g., displays value with one decimal place` | *** ### Best Practices | Recommendation | Details | Example / Explanation | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | | Enable Interactive Mode Appropriately | Use `InteractiveMode` when the application benefits from direct user input; otherwise, disable to prevent accidental changes. | `csharp\n// Enable interactive mode for dashboards\nmyGauge.InteractiveMode = true;` | | Use Informative Tooltip Formats | Choose a tooltip format that clearly communicates the gauge value without overwhelming the user. | `csharp\nmyGauge.TooltipFormat = "{0:F1}"; // e.g., displays "45.7" for a value of 45.7` | | Combine with Other Visual Cues | When enabling interactivity, ensure the gauge’s appearance provides clear feedback (e.g., hover states). | Consider updating colors or border effects on hover to signal interactivity. | *** ### Common Pitfalls | Issue | Details | Resolution / Code Example | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Accidental Value Changes | Enabling interactive mode in inappropriate contexts may lead to unintended modifications of the gauge value. | Use interactive mode selectively, e.g., only in dashboards where user input is expected:`csharp\nmyGauge.InteractiveMode = false;` | | Misconfigured Tooltip Format | An incorrect tooltip format string can cause runtime exceptions or display unintended text. | Validate the format string and test it with sample values:`csharp\nmyGauge.TooltipFormat = "{0:F1}";` | | Overly Aggressive Mouse Event Handling | Unmanaged mouse events may result in jittery or unresponsive gauge updates if not handled correctly. | Ensure that the mouse handling logic smoothly calculates and updates the gauge value. Refer to the built-in methods like `UpdateValueFromMousePosition(e.Location)`. | *** ### Usage Scenarios | Scenario | Description | Sample Code | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | | Direct Value Adjustment | Allowing users to modify the gauge value directly through mouse interactions in a control panel or dashboard. | `csharp\n// Enable interactive mode for direct value manipulation\nmyGauge.InteractiveMode = true;` | | Contextual Feedback | Providing immediate feedback with a tooltip when the user hovers over the gauge to see the current value in a precise format. | `csharp\n// Enable tooltip with custom format\nmyGauge.ShowTooltip = true;\nmyGauge.TooltipFormat = "{0:F1}";` | | Mixed-Mode Control | Combine both interactive updates and tooltip displays so that users can both see and modify the gauge value interactively. | `csharp\nmyGauge.InteractiveMode = true;\nmyGauge.ShowTooltip = true;\nmyGauge.TooltipFormat = "{0:F1}";` | *** ### Real Life Usage Scenarios | Scenario | Description | Sample Integration Code | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Data Visualization Dashboard | In a monitoring dashboard, users can click or drag on the gauge to update parameters (e.g., threshold levels) while a tooltip shows the precise current value. | `csharp\n// Configure gauge for interactive threshold adjustment\ndataGauge.InteractiveMode = true;\ndataGauge.ShowTooltip = true;\ndataGauge.TooltipFormat = "{0:F1}";` | | Configuration Panels | In settings screens where users need to fine-tune parameters visually, interactive gauges with tooltips provide intuitive and immediate feedback. | `csharp\n// Settings panel gauge configuration\nsettingsGauge.InteractiveMode = true;\nsettingsGauge.ShowTooltip = true;\nsettingsGauge.TooltipFormat = "{0:F0}"; // Whole number display` | | Educational Applications | In interactive learning modules, users can adjust values to see real-time effects and view detailed numerical information via tooltips. | `csharp\n// Enable interactive and tooltip functionality in an educational tool\neduGauge.InteractiveMode = true;\neduGauge.ShowTooltip = true;\neduGauge.TooltipFormat = "{0:F2}"; // Two decimal places` | *** ### Troubleshooting Tips | Tip | Explanation | Action | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Validate Tooltip Format | Ensure that the format string provided to `TooltipFormat` is valid to avoid runtime errors or incorrect displays. | Test the tooltip format in isolation, e.g., use a test value with `string.Format(myGauge.TooltipFormat, 123.456f)` to verify the output before assigning it to the control. | | Monitor Mouse Event Performance | If the gauge updates lag during rapid mouse movements, consider optimizing the mouse event handling logic. | Review the implementation of `UpdateValueFromMousePosition()` and ensure that it calculates the value efficiently; reduce any unnecessary computations in the event handler. | | Confirm InteractiveMode Impact | If users report unintended gauge value changes, double-check that `InteractiveMode` is enabled only where appropriate. | Limit the use of `InteractiveMode` to specific parts of your application or provide an option to disable it when not needed, for example, by using a toggle button. | *** ### Review | Aspect | Comments | Suggestions | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | Ease of Use | The interactive and tooltip features are straightforward to enable with simple property assignments. | Ensure thorough testing of mouse events and tooltip display on different screen resolutions. | | User Engagement | Provides immediate feedback and control over the gauge value, increasing the overall user experience. | Consider additional visual cues (e.g., hover highlights) to signal interactivity more clearly. | | Integration Complexity | Integration is simple due to clear property settings and event handling; however, performance should be monitored in data-intensive environments. | Test the interactive responsiveness in the context of your application, especially when multiple gauges are used concurrently. | *** ### Summary | Summary Point | Description | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Feature Overview | Allows users to interactively update the gauge value with mouse input and see real-time feedback through customizable tooltips. | | Core Properties | `InteractiveMode`, `ShowTooltip`, and `TooltipFormat` are the key properties that control user interaction and tooltip display. | | Integration and Customization | Enable interactivity for intuitive user input and customize tooltips to match the application's design and data precision requirements. | | Best Practices and Troubleshooting | Use interactive mode judiciously, validate tooltip formats, and optimize mouse event handling to maintain performance and prevent unintended behavior. | *** ### Integration Demo Below is a complete sample code snippet to demonstrate how to integrate and customize the Interaction & Tooltip feature into a WinForms application: ```csharp using System; using System.Drawing; using System.Windows.Forms; using SiticoneNetFrameworkUI; // Use the namespace from your provided code public class InteractionTooltipDemoForm : Form { private SiticoneGaugeNumeric myGauge; private Button toggleInteractionButton; public InteractionTooltipDemoForm() { // Initialize the gauge with interactive and tooltip settings myGauge = new SiticoneGaugeNumeric { MinValue = 0f, MaxValue = 100f, Value = 50f, AnimationSpeed = 5f, ShowAnimation = true, Size = new Size(300, 300), Location = new Point(50, 30), // Enable interactive value modification InteractiveMode = true, // Enable tooltip and set its format (e.g., display one decimal place) ShowTooltip = true, TooltipFormat = "{0:F1}" }; // Button to toggle interactive mode on and off toggleInteractionButton = new Button { Text = "Toggle Interaction", Location = new Point(50, 350), Width = 150 }; toggleInteractionButton.Click += ToggleInteractionButton_Click; // Add controls to the form Controls.Add(myGauge); Controls.Add(toggleInteractionButton); } private void ToggleInteractionButton_Click(object sender, EventArgs e) { // Toggle interactive mode myGauge.InteractiveMode = !myGauge.InteractiveMode; MessageBox.Show("Interactive mode is now " + (myGauge.InteractiveMode ? "enabled" : "disabled") + "."); myGauge.Invalidate(); } [STAThread] static void Main() { Application.EnableVisualStyles(); Application.Run(new InteractionTooltipDemoForm()); } } ``` *** ### API Reference | Member | Type | Description | | --------------- | ------ | -------------------------------------------------------------------------------------- | | InteractiveMode | bool | Enables or disables mouse interaction to modify the gauge value. | | ShowTooltip | bool | Determines whether a tooltip is displayed on mouse hover over the gauge. | | TooltipFormat | string | Gets or sets the format string used to display the current gauge value in the tooltip. | *** This documentation provides a detailed guide for integrating and using the Interaction & Tooltip feature in your WinForms applications. Use the provided code examples, tables, and best practices to ensure that users can interact with the gauge seamlessly while receiving accurate, formatted feedback through tooltips.