Interaction and Control

A feature that provides various input mechanisms to allow users to directly interact with the progress control, such as mouse and keyboard adjustments.

Overview

The Interaction & Control feature exposes properties that enable user interactions with the SiticoneRadialProgressBar. Developers can allow users to change the progress value via mouse clicks, drags, wheel scrolling, and keyboard inputs, making the control responsive and interactive.

---

Sections

Key Points

Aspect	Description	Example/Notes
MouseDragOrClickResponsive	Enables users to click or drag the progress bar to adjust its value interactively.	progressBar.MouseDragOrClickResponsive = true;
MouseWheelResponsive	Allows the progress value to be changed using the mouse wheel.	progressBar.MouseWheelResponsive = true;
MouseWheelStepValue	Specifies the incremental value change when the mouse wheel is scrolled.	progressBar.MouseWheelStepValue = 5;
EnableKeyboardSupport	Enables keyboard arrow key support to adjust the progress value.	progressBar.EnableKeyboardSupport = true;

---

Best Practices

Recommendation	Rationale	Code Example
Enable multiple interaction modes concurrently	Allows users to choose their preferred method of interaction for better usability.	csharp<br>progressBar.MouseDragOrClickResponsive = true;<br>progressBar.MouseWheelResponsive = true;<br>progressBar.EnableKeyboardSupport = true;<br>
Set an appropriate MouseWheelStepValue	Ensure that the step value for mouse wheel scrolling is not too high or too low for smooth adjustments.	csharp<br>progressBar.MouseWheelStepValue = 2;<br>
Provide visual feedback on interaction	Use the control’s built-in animations and tooltips to indicate value changes as the user interacts.	Utilize the default tooltip update logic that shows the current progress value during interaction.

---

Common Pitfalls

Pitfall	Explanation	How to Avoid
Unresponsive control due to disabled properties	Forgetting to enable MouseDragOrClickResponsive, MouseWheelResponsive, or EnableKeyboardSupport.	Verify that the appropriate interaction properties are set to true in your form’s initialization code.
Inconsistent value changes with the mouse wheel	Setting a MouseWheelStepValue that is too large may cause abrupt changes in the progress value.	Choose a moderate MouseWheelStepValue that aligns with the overall progress range and user expectations.
Overriding default behavior unintentionally	Custom mouse or keyboard event handling may conflict with the control’s built-in interaction logic.	Rely on the control’s properties for interaction unless custom behavior is explicitly needed.

---

Usage Scenarios

Scenario	How Interaction & Control Helps	Sample Code Example
Direct Progress Adjustment via Mouse Click/Drag	Users can quickly set or adjust the progress by interacting directly with the control.	csharp<br>// Enable mouse click and drag interaction<br>progressBar.MouseDragOrClickResponsive = true;<br>// When a user clicks or drags, the value updates dynamically<br>
Incremental Progress Control via Mouse Wheel	Users can fine-tune the progress value using the mouse wheel for precise control.	csharp<br>// Enable mouse wheel interaction<br>progressBar.MouseWheelResponsive = true;<br>progressBar.MouseWheelStepValue = 3;<br>
Keyboard-Based Adjustment	Provides accessibility by allowing users to adjust the progress with arrow keys.	csharp<br>// Enable keyboard support for adjusting progress using Up/Down arrows<br>progressBar.EnableKeyboardSupport = true;<br>

---

Code Examples and Integration Demos

Example 1: Mouse Interaction for Value Adjustment

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

public class MouseInteractionForm : Form
{
    public MouseInteractionForm()
    {
        // Initialize and configure the progress bar for mouse interactions
        var progressBar = new SiticoneRadialProgressBar
        {
            Size = new Size(160, 160),
            Location = new Point(20, 20),
            Minimum = 0,
            Maximum = 100,
            Value = 30,
            TextFormat = "{0}%",
            // Enable mouse drag or click responsiveness
            MouseDragOrClickResponsive = true,
            // Enable mouse wheel responsiveness and set the step value
            MouseWheelResponsive = true,
            MouseWheelStepValue = 5
        };

        this.Controls.Add(progressBar);
    }

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

Example 2: Keyboard Interaction for Progress Control

using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;

public class KeyboardInteractionForm : Form
{
    public KeyboardInteractionForm()
    {
        // Initialize the progress bar with keyboard support enabled
        var progressBar = new SiticoneRadialProgressBar
        {
            Size = new Size(160, 160),
            Location = new Point(20, 20),
            Minimum = 0,
            Maximum = 100,
            Value = 50,
            TextFormat = "{0}%",
            // Enable keyboard arrow key support
            EnableKeyboardSupport = true
        };

        this.Controls.Add(progressBar);
        // Focus the control to ensure it receives key events
        progressBar.TabStop = true;
        progressBar.Focus();
    }

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

---

Review

Review Aspect	Discussion	Recommendations
User Interaction Flexibility	The control supports multiple input methods, enhancing the user experience and accessibility.	Enable the appropriate interaction properties based on your application's needs.
Integration Simplicity	Built-in support for mouse and keyboard interactions simplifies the integration process.	Follow the provided code examples and adjust properties as necessary.
Robustness	With safeguards for value boundaries, the control ensures that user interactions do not result in invalid states.	Test the interactions in various scenarios to ensure smooth behavior across devices.

---

Summary

The Interaction & Control feature empowers the SiticoneRadialProgressBar to respond to user input via mouse and keyboard interactions. By configuring properties such as MouseDragOrClickResponsive, MouseWheelResponsive, MouseWheelStepValue, and EnableKeyboardSupport, developers can create interactive and accessible progress controls. This comprehensive documentation, along with code examples and best practices, is designed to help you integrate interactive progress functionality seamlessly into your .NET WinForms applications.

---

Additional Useful Sections

Troubleshooting Tips

Issue	Potential Cause	Suggested Resolution
Control not responding to mouse events	Interaction properties (e.g., MouseDragOrClickResponsive) not enabled.	Ensure that the relevant interaction properties are set to true during initialization.
Keyboard input not affecting the control	The control might not be focused or EnableKeyboardSupport is disabled.	Set EnableKeyboardSupport to true and ensure the control has focus (e.g., by setting TabStop and calling Focus()).
Abrupt value changes with mouse wheel	MouseWheelStepValue is set too high, causing rapid changes.	Adjust MouseWheelStepValue to a lower value for smoother transitions.

FAQs

Question	Answer
How do I enable direct interaction with the progress bar?	Set MouseDragOrClickResponsive to true to allow value adjustments via click or drag.
Can the control handle both mouse wheel and keyboard interactions?	Yes, you can enable both MouseWheelResponsive and EnableKeyboardSupport to support multiple interaction modes.
What is the best way to fine-tune the increment of value changes?	Adjust the MouseWheelStepValue property to define the amount by which the value changes with each interaction.

---

This comprehensive documentation for the Interaction & Control feature provides detailed guidance, best practices, code examples, and troubleshooting tips to help you integrate interactive functionality into the SiticoneRadialProgressBar control, enhancing user experience in your .NET WinForms applications.