Read-only and Feedback

Prevents toggle state changes when IsReadonly is true, providing optional visual and audio feedback to signal a restricted action.

Overview

The Readonly & Feedback Behavior feature ensures the SiticoneToggleButton cannot be toggled in specific scenarios (for instance, when certain settings are locked). When a user attempts to click or tap a read-only toggle, you can optionally trigger a shake animation (CanShake) and/or a beep sound (CanBeep) to indicate the action is disallowed.

---

Key API Members

Below is a table summarizing the primary properties that relate to the read-only functionality and feedback behavior:

Property	Type	Description	Example
IsReadonly	bool	If true, prevents the toggle state from changing when the user tries to click or press the control.	myToggle.IsReadonly = true;
CanShake	bool	When true, the control shakes if a user attempts to toggle while IsReadonly = true.	myToggle.CanShake = true;
CanBeep	bool	If true, the control plays a beep sound if a user attempts to toggle while IsReadonly = true.	myToggle.CanBeep = true;

---

Key Points to Note

1. Locking the Toggle

   • When IsReadonly = true, attempts to set IsToggled via user interaction are ignored (the control remains in its current On/Off state).

   • You can still programmatically change the IsToggled value in code if needed.

2. User Feedback

   • If CanShake is true, the toggle briefly shakes whenever a user tries to toggle a read-only button.

   • If CanBeep is true, a system beep sound plays in the same scenario.

3. Animation & Audio

   • Shake animation respects the parameters set under Animation Settings (e.g., ShakeDuration, ShakeAmplitude, etc.).

   • The beep is a basic system sound (SystemSounds.Beep).

4. No Ripple on Read-Only

   • The code checks IsReadonly; thus, ripple animations (EnableRippleEffect) do not occur if the toggle is read-only.

---

Usage Example

// Assume you have a SiticoneToggleButton named myToggle

// Lock the toggle to prevent state changes by user interaction
myToggle.IsReadonly = true;

// Provide feedback when a user attempts to click the locked toggle
myToggle.CanShake = true;
myToggle.CanBeep = true;

// Suppose we toggle the control programmatically
myToggle.IsToggled = true; // This works in code, even if IsReadonly is true

Note: If both CanShake and CanBeep are true, the control shakes and beeps simultaneously upon a failed toggle attempt.

---

Best Practices to Create Beautiful UI and Apps

Practice	Reason
Clearly indicate read-only visually (e.g., use distinct colors or a lock icon).	Improves user understanding that the toggle is intentionally locked.
Use shake and beep sparingly.	Overuse of these effects can annoy users; reserve them for essential feedback on restricted actions.
If the locked state is critical, disable or dim the control’s appearance.	Provides an immediate visual cue to prevent confusion about toggle availability.
Combine with tooltip or label explaining why it’s read-only.	Enhances clarity, particularly for first-time users.

---

Common Pitfalls and Design Considerations

Pitfall	Mitigation / Recommendation
Assuming IsReadonly blocks all toggling, including code.	IsReadonly only blocks user interactions; you can still change IsToggled programmatically.
Overusing the shake and beep for every read-only scenario.	Use these effects in critical or high-visibility contexts to avoid overwhelming the user.
Not making the button appear visually different in read-only mode.	Might confuse users who expect a locked/disabled style if IsReadonly is true.
Forgetting to match shake parameters with your desired effect.	Ensure ShakeAmplitude, ShakeFrequency, and ShakeDampingFactor are configured for a subtle, not jarring, feel.

---

Review and Summary

• What You Learned: How to lock the toggle control (IsReadonly), provide immediate user feedback with shake and beep effects, and differentiate system-level or user-level restrictions in your UI.

• Why It’s Important: Read-only toggles help preserve settings that users shouldn’t modify, while visual/audio feedback clarifies that interactions are restricted—not simply unresponsive.

• How to Move Forward: Combine Readonly & Feedback Behavior with your Appearance & Text or Border Settings to make locked toggles visually distinct. Proper usage ensures your toggle is both informative and intuitive when certain interactions are disallowed.

By utilizing IsReadonly alongside CanShake and CanBeep, you create a frictionless user experience in situations where toggling is not permitted, making the UI both descriptive and responsive to user intentions.