> For the complete documentation index, see [llms.txt](https://docs-siticoneframework.gitbook.io/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/progress-and-loading/siticone-radialprogress/advanced-effects-and-readonly-state.md).

# Advanced Effects & Readonly State

A feature that enables enhanced visual and behavioral feedback through advanced effects such as text shadows, range-based coloring, and read-only state responses like shaking and beeping.

## Overview

The Advanced Effects & Readonly State feature offers properties that enhance the control's visual appeal and usability when certain states are active. Developers can configure the control to provide feedback when it is set to a readonly mode, such as triggering a shake or beep on user interaction, and use advanced styling options like text shadow effects and range-based coloring to better communicate progress status.

***

### Sections

#### Key Points

| Aspect                                | Description                                                                                                                             | Example/Notes                                                                                |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| IsReadonly                            | Prevents modifications to the progress value and triggers special visual or audio feedback when an attempt is made to change the value. | `progressBar.IsReadonly = true;`                                                             |
| CanShake                              | Enables a shake effect as feedback when the user attempts to modify the value while the control is readonly.                            | `progressBar.CanShake = true;`                                                               |
| CanBeep                               | Enables an audible beep to signal an attempt to change the value while in readonly mode.                                                | `progressBar.CanBeep = true;`                                                                |
| ReadonlyStartColor & ReadonlyEndColor | Define the gradient colors used when the control is in readonly mode, visually distinguishing it from normal operation.                 | `progressBar.ReadonlyStartColor = Color.Gray;progressBar.ReadonlyEndColor = Color.DarkGray;` |
| EnableTextShadow                      | Activates a drop shadow behind the progress text for added depth and improved legibility.                                               | `progressBar.EnableTextShadow = true;`                                                       |
| EnableRangeBasedColoring              | When enabled, changes the progress arc’s color based on the current value by comparing against defined ranges.                          | `progressBar.EnableRangeBasedColoring = true;`                                               |
| ProgressColorRanges                   | A collection of color range definitions that associate specific colors with progress value intervals.                                   | See sample code for creating and assigning ProgressColorRanges.                              |

***

#### Best Practices

| Recommendation                                                                   | Rationale                                                                                                      | Code Example                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Set IsReadonly when user modifications should be prevented                       | Clearly indicates to users that the control is in a protected state and triggers associated visual/audio cues. | `csharp<br>progressBar.IsReadonly = true;<br>`                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| Use CanShake and CanBeep judiciously for feedback                                | Provides immediate feedback without being intrusive; excessive shaking or beeping may distract the user.       | `csharp<br>progressBar.CanShake = true;<br>progressBar.CanBeep = true;<br>`                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Configure Readonly colors to contrast with normal operation                      | Distinct colors in readonly mode help users immediately identify that the control is non-interactive.          | `csharp<br>progressBar.ReadonlyStartColor = Color.Gray;<br>progressBar.ReadonlyEndColor = Color.DarkGray;<br>`                                                                                                                                                                                                                                                                                                                                                                                 |
| Leverage EnableTextShadow for improved readability                               | Enhances the visual clarity of progress text especially against complex backgrounds.                           | `csharp<br>progressBar.EnableTextShadow = true;<br>`                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| Define clear value ranges with ProgressColorRanges if using range-based coloring | Improves visual feedback by adapting the progress arc’s color to specific progress intervals.                  | `csharp<br>progressBar.EnableRangeBasedColoring = true;<br>progressBar.ProgressColorRanges = new List<SiticoneRadialProgressBar.ProgressColorRange>() {<br> new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 0, Maximum = 33, Color = Color.Green },<br> new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 34, Maximum = 66, Color = Color.Yellow },<br> new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 67, Maximum = 100, Color = Color.Red }<br>};<br>` |

***

#### Common Pitfalls

| Pitfall                                                | Explanation                                                                                                 | How to Avoid                                                                                                                       |
| ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Failing to update readonly state feedback              | Users may not receive the intended visual or audio feedback if CanShake or CanBeep is left disabled.        | Ensure that CanShake and CanBeep are enabled when IsReadonly is set to true.                                                       |
| Inconsistent color schemes between normal and readonly | Using similar colors for both states can confuse users regarding the control's current interactivity state. | Use distinct values for ReadonlyStartColor/ReadonlyEndColor compared to the normal color settings or the gradient animation cycle. |
| Overcomplicating range-based coloring                  | Too many overlapping or narrow ranges may lead to visual clutter and misinterpretation of progress status.  | Define clear and well-spaced ranges in ProgressColorRanges and test them with different progress values.                           |
| Neglecting text shadow configuration                   | Poorly configured text shadow (excessive blur or offset) can reduce readability.                            | Adjust ShadowColor, ShadowOffset, and ShadowBlur to achieve a subtle effect without overpowering the text.                         |

***

#### Usage Scenarios

| Scenario                                    | How Advanced Effects & Readonly State Helps                                                                                                             | Sample Code Example                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Preventing User Modifications               | In scenarios where the progress value should not be altered (e.g., during a final submission), readonly mode prevents changes and provides feedback.    | `csharp<br>progressBar.IsReadonly = true;<br>progressBar.CanShake = true;<br>progressBar.CanBeep = true;<br>// The control now ignores modifications and gives feedback if users try to interact<br>`                                                                                                                                                                                                                                                                                          |
| Differentiating Progress States with Colors | When the progress value represents different status ranges, range-based coloring visually indicates the current status (e.g., safe, warning, critical). | `csharp<br>progressBar.EnableRangeBasedColoring = true;<br>progressBar.ProgressColorRanges = new List<SiticoneRadialProgressBar.ProgressColorRange>() {<br> new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 0, Maximum = 33, Color = Color.Green },<br> new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 34, Maximum = 66, Color = Color.Yellow },<br> new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 67, Maximum = 100, Color = Color.Red }<br>};<br>` |
| Enhancing Text Legibility                   | In complex or dynamic UI backgrounds, text shadows help maintain the legibility of the progress text.                                                   | `csharp<br>progressBar.EnableTextShadow = true;<br>progressBar.ShadowColor = Color.FromArgb(100, Color.Black);<br>progressBar.ShadowOffset = new Point(2, 2);<br>progressBar.ShadowBlur = 5;<br>`                                                                                                                                                                                                                                                                                              |

***

#### Code Examples and Integration Demos

**Example 1: Readonly Mode with Shake and Beep Feedback**

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

public class ReadonlyFeedbackForm : Form
{
    public ReadonlyFeedbackForm()
    {
        var progressBar = new SiticoneRadialProgressBar
        {
            Size = new Size(160, 160),
            Location = new Point(20, 20),
            Minimum = 0,
            Maximum = 100,
            Value = 75,
            TextFormat = "{0}%",
            IsReadonly = true,
            CanShake = true,
            CanBeep = true,
            ReadonlyStartColor = Color.Gray,
            ReadonlyEndColor = Color.DarkGray
        };

        this.Controls.Add(progressBar);
    }

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

**Example 2: Using Range-Based Coloring for Status Indication**

```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using System.Collections.Generic;
using SiticoneNetFrameworkUI;

public class RangeBasedColoringForm : Form
{
    public RangeBasedColoringForm()
    {
        var progressBar = new SiticoneRadialProgressBar
        {
            Size = new Size(180, 180),
            Location = new Point(30, 30),
            Minimum = 0,
            Maximum = 100,
            Value = 45,
            TextFormat = "{0}%",
            EnableRangeBasedColoring = true,
            ProgressColorRanges = new List<SiticoneRadialProgressBar.ProgressColorRange>
            {
                new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 0, Maximum = 33, Color = Color.Green },
                new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 34, Maximum = 66, Color = Color.Yellow },
                new SiticoneRadialProgressBar.ProgressColorRange { Minimum = 67, Maximum = 100, Color = Color.Red }
            }
        };

        this.Controls.Add(progressBar);
    }

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

**Example 3: Enhanced Text Readability with Shadow Effects**

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

public class TextShadowForm : Form
{
    public TextShadowForm()
    {
        var progressBar = new SiticoneRadialProgressBar
        {
            Size = new Size(160, 160),
            Location = new Point(50, 50),
            Value = 60,
            TextFormat = "{0}%",
            ProgressFont = new Font("Segoe UI", 14, FontStyle.Bold),
            EnableTextShadow = true,
            ShadowColor = Color.FromArgb(100, Color.Black),
            ShadowOffset = new Point(2, 2),
            ShadowBlur = 5
        };

        this.Controls.Add(progressBar);
    }

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

***

#### Review

| Review Aspect                  | Discussion                                                                                                                 | Recommendations                                                                       |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| Visual and Audio Feedback      | The combination of readonly state with shake and beep effects provides clear feedback when the control is non-interactive. | Enable CanShake and CanBeep selectively based on user context and application design. |
| Visual Distinction with Colors | Using distinct readonly colors and range-based coloring helps users immediately recognize state differences.               | Test color schemes in various UI backgrounds to ensure clear differentiation.         |
| Enhanced Readability           | Text shadow features significantly improve text clarity in visually busy interfaces.                                       | Adjust shadow properties carefully to balance readability with subtlety.              |

***

#### Summary

The Advanced Effects & Readonly State feature equips the SiticoneRadialProgressBar with advanced visual and behavioral capabilities. By configuring properties like IsReadonly, CanShake, CanBeep, ReadonlyStartColor/ReadonlyEndColor, and enabling features such as text shadows and range-based coloring, developers can provide clear, responsive feedback to users while emphasizing state changes and progress thresholds. The included code examples, best practices, and troubleshooting tips are designed to help integrate these advanced effects seamlessly into your .NET WinForms applications.

***

#### Additional Useful Sections

**Troubleshooting Tips**

| Issue                                             | Potential Cause                                                                             | Suggested Resolution                                                                                 |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| No feedback when interacting in readonly mode     | CanShake and/or CanBeep properties may be disabled.                                         | Ensure both CanShake and CanBeep are set to true when IsReadonly is enabled.                         |
| Readonly colors not distinct from active mode     | Similar color values between ReadonlyStartColor/ReadonlyEndColor and active color settings. | Choose contrasting colors for readonly state to clearly indicate non-interactivity.                  |
| Range-based coloring not reflecting current value | Incorrect or overlapping ranges in ProgressColorRanges.                                     | Verify that ranges in ProgressColorRanges are mutually exclusive and cover the entire progress span. |

**FAQs**

| Question                                                             | Answer                                                                                                                                              |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| What happens when the control is set to readonly?                    | The control ignores value changes and, if enabled, triggers a shake and/or beep effect while displaying designated readonly colors.                 |
| How can I adjust the intensity of the shake or beep effect?          | These effects are built-in; adjust your usage of CanShake and CanBeep based on the desired user feedback level.                                     |
| Can I use range-based coloring alongside normal gradient animations? | Yes, but if EnableRangeBasedColoring is active, the control prioritizes the color ranges defined in ProgressColorRanges over the standard gradient. |

***

This comprehensive documentation for the Advanced Effects & Readonly State feature is intended to provide developers with the insights, best practices, and practical examples needed to leverage advanced feedback mechanisms and visual enhancements in the SiticoneRadialProgressBar control within .NET WinForms applications.