# Animation Settings

## **Overview**

The **Animation Settings** feature allows you to tailor various transitions and feedback effects that occur when the toggle state changes. From **fade** and **slide** to more dynamic styles like **bounce** or **spin**, these animations help create a smooth, engaging user experience. Additionally, you can configure shake parameters (amplitude, frequency, duration) and the total animation duration for toggling.

***

### **Key API Members**

The following table outlines the main properties and event related to **Animation Settings**:

| **Property / Event**   | **Type**                      | **Description**                                                                                                      | **Example**                                            |
| ---------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **AnimationStyle**     | `ToggleAnimationStyle` (enum) | Defines the **visual style** of the toggle transition, e.g., `Fade`, `Slide`, `Flip`, `Zoom`, `Bounce`, `Spin`, etc. | `myToggle.AnimationStyle = ToggleAnimationStyle.Fade;` |
| **AnimationDuration**  | `int`                         | Specifies the total **time in milliseconds** for the On/Off toggle animation.                                        | `myToggle.AnimationDuration = 300;`                    |
| **ShakeDuration**      | `int`                         | The **length of time** (in ms) the button shakes for feedback (e.g., when read-only).                                | `myToggle.ShakeDuration = 500;`                        |
| **ShakeAmplitude**     | `float`                       | Determines **how far** the button moves left/right during the shake.                                                 | `myToggle.ShakeAmplitude = 5f;`                        |
| **ShakeFrequency**     | `float`                       | Defines the **number of oscillations** per second during the shake effect.                                           | `myToggle.ShakeFrequency = 15f;`                       |
| **ShakeDampingFactor** | `float`                       | Controls **how quickly** the shake effect diminishes over its duration.                                              | `myToggle.ShakeDampingFactor = 2f;`                    |
| **RippleDuration**     | `int`                         | Sets the **length of time** (in ms) the ripple animation (if enabled) will last.                                     | `myToggle.RippleDuration = 600;`                       |
| **AnimationCompleted** | `event`                       | Fires after the toggle **animation finishes**, allowing you to run code immediately after a successful transition.   | `myToggle.AnimationCompleted += (s, e) => { ... };`    |

**Note:** `ToggleAnimationStyle` is an `enum` that includes various styles like `Fade`, `Slide`, `Zoom`, `Bounce`, `Spin`, and more.

***

### **Key Points to Note**

1. **AnimationStyle vs. AnimationDuration**
   * Changing `AnimationStyle` affects the **visual pattern** of how the toggle transitions.
   * `AnimationDuration` affects **how long** the transition takes to complete, regardless of the style chosen.
2. **Shake Parameters**
   * The button may trigger a shake (if `CanShake` is enabled and `IsReadonly = true`, or you invoke it in custom scenarios).
   * **Amplitude**, **Frequency**, and **DampingFactor** control the shake’s intensity and decay.
3. **Ripple Effect Timing**
   * If `EnableRippleEffect` is `true`, the control uses `RippleDuration` to determine how long the ripple expands and fades after a click.
4. **AnimationCompleted Event**
   * This event provides a convenient spot to update other UI elements or perform any logic that should happen **after** the transition is done.
5. **Read-Only Feedback**
   * If the user attempts to toggle the button when it’s **read-only**, the shake animation parameters (`ShakeDuration`, `ShakeAmplitude`, etc.) can provide immediate feedback (along with an optional beep if `CanBeep` is enabled).

***

### **Usage Example**

#### **Configuring Animation in Code**

```csharp
// Assume you have a SiticoneToggleButton named myToggle

// Set a bounce effect style and 250 ms duration for the toggle transition
myToggle.AnimationStyle = SiticoneToggleButton.ToggleAnimationStyle.Bounce;
myToggle.AnimationDuration = 250;

// Configure shake parameters (for read-only or error feedback scenarios)
myToggle.ShakeDuration = 400;
myToggle.ShakeAmplitude = 6f;
myToggle.ShakeFrequency = 12f;
myToggle.ShakeDampingFactor = 2.5f;

// Optionally, customize the ripple duration if using EnableRippleEffect
myToggle.RippleDuration = 700;

// Hook the AnimationCompleted event
myToggle.AnimationCompleted += (s, e) =>
{
    // Perform some action after the toggle animation completes
    Console.WriteLine("Toggle animation finished!");
};
```

> **Tip:** The actual feel of each animation style can vary significantly based on `AnimationDuration`. Lower values create snappier transitions; higher values offer a more pronounced, detailed effect.

***

### **Best Practices to Create Beautiful UI and Apps**

| **Practice**                                                            | **Reason**                                                                                              |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| Match `AnimationStyle` to the **overall tone** of your app.             | A gentle fade may fit a clean, professional UI; a bouncy or spin effect might suit a more playful vibe. |
| Keep `AnimationDuration` **balanced** (100–300 ms).                     | Too short can feel abrupt; too long can frustrate users.                                                |
| Use **Shake** feedback sparingly.                                       | Reserve it for read-only or error states to emphasize unexpected user actions.                          |
| Combine **AnimationCompleted** with **StateChanged** for complex logic. | Allows you to separate “state changed” reactions from “animation finished” reactions.                   |
| Test accessibility and **performance**.                                 | Heavier animations or many toggles onscreen could affect lower-end systems and user accessibility.      |

***

### **Common Pitfalls and Design Considerations**

| **Pitfall**                                                       | **Mitigation / Recommendation**                                                                                          |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Setting a **very long** `AnimationDuration` (e.g., >1 second).    | May make the UI feel unresponsive; keep transitions snappy for best user experience.                                     |
| Overusing **dramatic** animation styles in a conservative UI.     | Might clash visually with the rest of the design; ensure consistency with your branding and style guidelines.            |
| Not handling the **AnimationCompleted** event properly.           | If you need logic to run after a toggle completes, ensure you’re subscribed to this event rather than purely on `Click`. |
| Misconfiguring **shake** parameters (high frequency + amplitude). | Can produce an unnatural or jarring effect; tune them to achieve subtle feedback.                                        |

***

### **Review and Summary**

* **What You Learned**:\
  How to tweak the button’s toggle transitions (e.g., fade, slide, bounce), manage the duration of animations, and set up shake feedback parameters.
* **Why It’s Important**:\
  Animations can make toggles more intuitive and visually appealing, while providing feedback (like shakes) helps users understand restricted or invalid interactions.
* **How to Move Forward**:\
  Consider combining these animations with well-planned **Appearance & Text**, **Border**, and **Corner Radius** settings to craft polished, engaging toggles. Always balance aesthetics and user experience—too much animation may hinder performance or distract users.

By customizing the **Animation Settings**, you can inject personality and clarity into your toggle control, ensuring both a fun and functional experience for your users.
