Events and Callbacks

The Siticone RadialButton class exposes several public events that notify subscribing code when specific actions or state transitions occur.

Overview

The SiticoneRadialButton class exposes several public events that notify subscribing code when specific actions or state transitions occur. By handling these events, you can dynamically adapt your application to user input or changes in button status (e.g., toggling, reading system themes, or reacting to read-only interactions).

Below is a quick reference table of all available public events in SiticoneRadialButton, their associated event argument types, and when they typically fire:

Event Name	Event Args	Description
LongPressed	EventArgs	Fires when the user presses and holds (long press) the button for a specified duration.
ToggleChanged	EventArgs	Fires when the button’s toggle state changes (only if IsToggleButton is true).
StateChanged	ButtonStateEventArgs	Fires when the button’s state changes (e.g., from Normal to Hover, Pressed, Disabled, etc.).
AnimationCompleted	AnimationCompletedEventArgs	Fires when an animation effect (e.g., ripple, state transition) completes.
ReadOnlyInteraction	ReadOnlyInteractionEventArgs	Fires when the button is clicked or interacted with while in read-only mode.
AnimationEffectStarted	AnimationEffectEventArgs	Fires just as a new animation effect begins (e.g., ripple, particle effects).
ThemeChanged	ThemeChangedEventArgs	Fires when the custom or system theme of the button changes, providing old and new theme states.
SystemThemeChanged	SystemThemeChangedEventArgs	Fires when the system theme changes (e.g., Windows switches between Light and Dark).

---

Key Points to Note

Key Point	Description
Toggle Behavior	The ToggleChanged event is only meaningful if IsToggleButton = true. In this scenario, the button maintains an on/off state, and changing that state triggers the event.
Read-Only Interactions	When IsReadOnly = true, the control can still fire events like ReadOnlyInteraction if the user attempts to click or press the button. This event allows you to provide custom feedback without performing normal button actions.
Animation Hooks	AnimationEffectStarted and AnimationCompleted allow you to track the lifecycle of visual effects like ripples or particles, enabling you to synchronize other UI updates or sound effects.
Theme Changes	ThemeChanged and SystemThemeChanged are useful if you enable theme monitoring (IsSystemThemeMonitoringEnabled = true). They allow your app to react instantly when the system theme changes or when the control’s own theme properties are updated.
State Changes	The StateChanged event is central for detecting transitions among Normal, Hover, Pressed, Disabled, ReadOnly, and Toggled. It includes a ButtonStateEventArgs object describing old vs. new states and the transition duration.

---

Best Practices to Follow to Create Beautiful UI and Apps

Practice	Description
Use StateChanged to Fine-Tune UI	Synchronize related controls or provide additional visual cues (like highlighting companions) whenever the button state changes.
Combine Animations and Sound	Subscribing to AnimationEffectStarted or AnimationCompleted lets you trigger subtle sound effects or complementary animations in harmony with the button’s built-in effects.
Integrate Theme Events	Combine ThemeChanged and SystemThemeChanged with your theming logic so the UI remains consistent across light/dark mode transitions.
Graceful Handling of Read-Only	In read-only mode, consider providing a tooltip or visual indication when ReadOnlyInteraction fires, so users understand why the button doesn’t proceed with normal click actions.
Modularize Your Handlers	Keep event handlers lean. If you need significant logic, call separate methods from within the event handler. This keeps your code maintainable and efficient.

---

Common Pitfalls and Design Considerations

Pitfall / Consideration	Explanation / Guidance
Forgetting to Unsubscribe	If you dynamically attach event handlers (e.g., in forms that open/close frequently), remember to unsubscribe to prevent memory leaks.
Long Press Overlook	Make sure EnableLongPress is set to true if you want to handle LongPressed. Otherwise, the LongPressed event will never fire.
Ignoring Toggle State	If you set IsToggleButton = true, but never handle ToggleChanged, you might miss crucial toggling logic.
Excessive Animation Effects	Registering heavy logic in AnimationEffectStarted or AnimationCompleted could impact UI performance. Keep it efficient.
System Theme Debounce	The code already includes a debounce interval for system theme changes. Avoid re-triggering theme logic multiple times in quick bursts.
Handler Invocation in Read-Only	ReadOnlyInteraction can still be raised even though the button is not interactive. Always check your logic to handle or ignore.
Thread-Safety	Event handlers are typically invoked on the UI thread. If you spawn or interact with other threads, ensure you manage cross-thread calls properly.

---

Detailed Event References and Examples

Below is a table summarizing event signatures, along with example code snippets to illustrate how to subscribe and handle them in a typical WinForms scenario.

Event Signature Table

Event Name	Signature
LongPressed	public event EventHandler LongPressed;
ToggleChanged	public event EventHandler ToggleChanged;
StateChanged	public event EventHandler<ButtonStateEventArgs> StateChanged;
AnimationCompleted	public event EventHandler<AnimationCompletedEventArgs> AnimationCompleted;
ReadOnlyInteraction	public event EventHandler<ReadOnlyInteractionEventArgs> ReadOnlyInteraction;
AnimationEffectStarted	public event EventHandler<AnimationEffectEventArgs> AnimationEffectStarted;
ThemeChanged	public event EventHandler<ThemeChangedEventArgs> ThemeChanged;
SystemThemeChanged	public event EventHandler<SystemThemeChangedEventArgs> SystemThemeChanged;

Sample: Subscribing to Events

public partial class MyForm : Form
{
    private SiticoneRadialButton myButton;

    public MyForm()
    {
        InitializeComponent();

        // Initialize the button
        myButton = new SiticoneRadialButton
        {
            Text = "Click or Press Me!",
            IsToggleButton = true,
            EnableLongPress = true,
            Location = new Point(50, 50),
            Size = new Size(100, 100)
        };

        // Subscribe to events
        myButton.LongPressed += MyButton_LongPressed;
        myButton.ToggleChanged += MyButton_ToggleChanged;
        myButton.StateChanged += MyButton_StateChanged;
        myButton.AnimationCompleted += MyButton_AnimationCompleted;
        myButton.ReadOnlyInteraction += MyButton_ReadOnlyInteraction;
        myButton.AnimationEffectStarted += MyButton_AnimationEffectStarted;
        myButton.ThemeChanged += MyButton_ThemeChanged;
        myButton.SystemThemeChanged += MyButton_SystemThemeChanged;

        this.Controls.Add(myButton);
    }

    private void MyButton_LongPressed(object sender, EventArgs e)
    {
        MessageBox.Show("Long press detected!");
    }

    private void MyButton_ToggleChanged(object sender, EventArgs e)
    {
        // Toggle state changed
        var btn = sender as SiticoneRadialButton;
        MessageBox.Show($"Button is toggled: {btn.IsToggled}");
    }

    private void MyButton_StateChanged(object sender, SiticoneRadialButton.ButtonStateEventArgs e)
    {
        Console.WriteLine($"State changed from {e.OldState} to {e.NewState}, Animating: {e.IsAnimating}");
    }

    private void MyButton_AnimationCompleted(object sender, SiticoneRadialButton.AnimationCompletedEventArgs e)
    {
        Console.WriteLine($"Animation of type {e.AnimationType} completed after {e.Duration.TotalMilliseconds}ms");
    }

    private void MyButton_ReadOnlyInteraction(object sender, SiticoneRadialButton.ReadOnlyInteractionEventArgs e)
    {
        // If the button is read-only, you might show feedback or beep
        Console.WriteLine($"Read-only interaction at {e.InteractionLocation}, Type: {e.Type}");
        // e.WasHandled = true if you have handled this event manually
    }

    private void MyButton_AnimationEffectStarted(object sender, SiticoneRadialButton.AnimationEffectEventArgs e)
    {
        Console.WriteLine($"Animation effect {e.EffectType} started, expected duration: {e.ExpectedDuration}");
    }

    private void MyButton_ThemeChanged(object sender, SiticoneRadialButton.ThemeChangedEventArgs e)
    {
        Console.WriteLine($"Theme changed from {e.OldTheme} to {e.NewTheme}");
    }

    private void MyButton_SystemThemeChanged(object sender, SiticoneRadialButton.SystemThemeChangedEventArgs e)
    {
        Console.WriteLine($"System theme changed to {e.SystemTheme}");
    }
}

---

Review and Summary

• What We Covered

  • All public events offered by the SiticoneRadialButton control.

  • Their use cases (from toggle state changes, read-only interactions, advanced ripple/animation tracking, to system/theme changes).

  • Code samples on how to subscribe to these events in your own form.

• How This Helps

  • Subscribing to these events allows for responsive, dynamic, and interactive UI design.

  • By reacting to button state changes, you can build intuitive apps that provide meaningful feedback to users.

• Key Takeaway

  • Leverage these events thoughtfully to handle user interaction, manage toggling behavior, track advanced animations, and respond to theme adjustments without adding overhead or complexity to your application.

---

Additional Tips

Tip	Description
Test on Various Themes	If you handle ThemeChanged or SystemThemeChanged, test your UI in both Light and Dark modes to ensure consistent design.
Combine with Accessibility	Because SiticoneRadialButton provides accessibility features (custom accessible name/role), pairing events with accessible feedback creates an inclusive experience.
Performance	Keep long-running tasks out of the UI thread during events like AnimationEffectStarted to maintain smooth animations.

By fully utilizing these public events, you can harness the complete potential of SiticoneRadialButton to craft appealing, interactive, and accessible user experiences.