# Events and Callbacks

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

```csharp
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.