# Read‑Only Mode
## Overview
The Read‑Only Mode feature is designed to disable user modifications to the progress bar while still displaying progress updates. In this mode, the control adjusts its visual styling to indicate that interaction is not permitted by switching to alternative colors and feedback mechanisms. Additionally, optional audio (beep) and visual shake effects are provided to alert users when they attempt to interact with a read‑only progress bar.
***
### Properties and Their Details
| Property | Description | Default Value |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
| IsReadonly | Enables or disables the read‑only state of the control; when true, the progress bar becomes non-interactive. | false |
| ReadonlyFillColor1 | The primary fill color used for the progress bar in read‑only mode, providing a visual cue that the control is inactive. | Gray |
| ReadonlyFillColor2 | The secondary fill color used in gradient fills when the control is in read‑only mode, enhancing visual distinction. | DarkGray |
| ReadonlyBorderColor | The color used to draw the border of the progress bar when it is in read‑only mode. | DimGray |
| ReadonlyForeColor | The color of the text (label) in read‑only mode, ensuring that it remains legible against the modified background. | White |
| CanBeep | Controls whether an audio beep is played when a user attempts to interact with the control while it is in read‑only mode. | true |
| CanShake | Determines whether a shake animation is triggered upon interaction attempts when the control is read‑only, providing visual feedback. | true |
*Note:* In read‑only mode, all interactive features—such as value dragging—are disabled, ensuring that the progress bar remains solely an indicator of progress.
***
### Key Points
| Aspect | Details |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Non-Interactive Feedback | When IsReadonly is enabled, user interactions are blocked, and visual cues (alternative fill and border colors) indicate that the control is locked. |
| Integrated User Alerts | Optional audio beeps (via CanBeep) and shake animations (via CanShake) alert users to the read‑only state if they attempt to modify the control. |
| Consistent Visual Styling | The control automatically applies a distinct color scheme in read‑only mode, ensuring that its state is visually communicated across various contexts. |
***
### Best Practices
| Practice | Explanation |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Clearly Indicate Inactivity | Use distinct read‑only colors (ReadonlyFillColor1, ReadonlyFillColor2, ReadonlyBorderColor, ReadonlyForeColor) to clearly signal to users that the control is not interactive. |
| Use Audio/Visual Feedback Judiciously | Enable CanBeep and CanShake only if the additional user feedback aligns with your application’s UX guidelines, as overuse might become distracting. |
| Disable Unnecessary Interaction Cues | When setting IsReadonly to true, ensure that interactive cues (e.g., drag handles or focus indicators) are disabled to prevent confusion among users. |
***
### Common Pitfalls
| Pitfall | Explanation | Avoidance Strategy |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Inconsistent Visuals | Failing to update all related read‑only properties (fill, border, and text colors) can result in a confusing or inconsistent appearance. | Update all visual properties consistently when toggling read‑only mode. |
| Overuse of Feedback Effects | Excessive use of beep or shake feedback may annoy users, particularly if the control is read‑only for extended periods. | Evaluate the necessity of CanBeep and CanShake based on the application’s context and disable if overly intrusive. |
| Ignoring Accessibility Considerations | In read‑only mode, if the color contrast is insufficient, the label may become hard to read, reducing accessibility. | Test and adjust the ReadonlyForeColor and background fill colors to ensure sufficient contrast for all users. |
***
### Usage Scenarios
| Scenario | Description | Sample Code Integration |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Disabling User Modifications | In applications where progress should be displayed but not modified (e.g., monitoring task progress), enable read‑only mode to prevent accidental changes. | `csharp
// Initialize a read‑only progress bar
SiticoneHProgressBar progressBar = new SiticoneHProgressBar();
progressBar.IsReadonly = true;
progressBar.Value = 80;
this.Controls.Add(progressBar);
` |
| Enhanced User Alerts in Read‑Only Mode | When a user attempts to interact with a read‑only control, use audio and shake feedback to indicate that the control is locked. | `csharp
// Configure read‑only feedback options
SiticoneHProgressBar progressBar = new SiticoneHProgressBar();
progressBar.IsReadonly = true;
progressBar.CanBeep = true;
progressBar.CanShake = true;
this.Controls.Add(progressBar);
// User attempts to click will trigger beep and shake feedback (handled internally by the control)
` |
| Visual Differentiation in Themed Applications | Adjust the read‑only color scheme to match your application's theme, ensuring that read‑only controls are visually distinct yet harmonious with the overall design. | `csharp
// Customize read‑only colors to align with a dark theme
SiticoneHProgressBar progressBar = new SiticoneHProgressBar();
progressBar.IsReadonly = true;
progressBar.ReadonlyFillColor1 = Color.FromArgb(80, 80, 80);
progressBar.ReadonlyFillColor2 = Color.FromArgb(50, 50, 50);
progressBar.ReadonlyBorderColor = Color.Gray;
progressBar.ReadonlyForeColor = Color.LightGray;
this.Controls.Add(progressBar);
` |
***
### Code Example and Demo
Below is an extensive example demonstrating how to integrate and customize the Read‑Only Mode feature in a simple WinForms application:
```csharp
using System;
using System.Drawing;
using System.Windows.Forms;
using SiticoneNetFrameworkUI;
namespace ReadOnlyModeDemo
{
public class MainForm : Form
{
private SiticoneHProgressBar progressBar;
private Button toggleReadOnlyButton;
public MainForm()
{
// Initialize the form
Text = "Read‑Only Mode Demo";
Size = new Size(600, 300);
// Initialize the progress bar with default values
progressBar = new SiticoneHProgressBar()
{
Location = new Point(50, 50),
Size = new Size(500, 30),
Minimum = 0,
Maximum = 100,
Value = 75,
IsReadonly = false, // Initially interactive
// Default read‑only styling
ReadonlyFillColor1 = Color.Gray,
ReadonlyFillColor2 = Color.DarkGray,
ReadonlyBorderColor = Color.DimGray,
ReadonlyForeColor = Color.White,
// Enable beep and shake feedback for interaction attempts in read‑only mode
CanBeep = true,
CanShake = true
};
// Button to toggle the read‑only state
toggleReadOnlyButton = new Button()
{
Text = "Toggle Read‑Only Mode",
Location = new Point(50, 100),
AutoSize = true
};
toggleReadOnlyButton.Click += ToggleReadOnlyButton_Click;
// Add controls to the form
Controls.Add(progressBar);
Controls.Add(toggleReadOnlyButton);
}
private void ToggleReadOnlyButton_Click(object sender, EventArgs e)
{
// Toggle the read‑only state of the progress bar
progressBar.IsReadonly = !progressBar.IsReadonly;
// Optionally adjust the progress value or provide user feedback as needed
MessageBox.Show("Read‑Only Mode is now " + (progressBar.IsReadonly ? "Enabled" : "Disabled"), "State Changed");
}
[STAThread]
public static void Main()
{
Application.EnableVisualStyles();
Application.Run(new MainForm());
}
}
}
```
***
### Review
| Aspect | Evaluation |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| User Interaction Prevention | The IsReadonly property effectively disables user input, ensuring that the progress bar remains unmodifiable during critical operations. |
| Visual Clarity | By switching to dedicated read‑only colors, the control clearly communicates its non-interactive state to users, reducing confusion. |
| Integrated Feedback | Optional beep and shake feedback enhance user awareness when an attempt is made to interact with a read‑only control, aligning with modern UX practices. |
***
### Summary
The Read‑Only Mode feature allows the progress bar to be displayed in a non-interactive state, employing a distinct visual style and optional audio/visual feedback to signal that user modifications are disabled. This ensures that progress indicators remain reliable and consistent in contexts where interaction should be prevented.
***
### Additional Sections
#### Troubleshooting Tips
| Tip | Description |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Validate Color Consistency | Confirm that the read‑only colors (fill, border, and text) are consistently applied across different states to avoid user confusion. |
| Test Feedback Effects | Ensure that the beep and shake effects do not become disruptive by testing them in the context of your application and adjusting as necessary. |
| Monitor Control Interactivity | Verify that when IsReadonly is enabled, all interactive features (such as value dragging) are properly disabled to maintain a true read‑only state. |
#### Integration Checklist
| Checklist Item | Status |
| -------------------------------------------------------------------------------------------- | --------- |
| Set IsReadonly property to true when user modifications should be blocked | \[ ] Done |
| Configure ReadonlyFillColor1, ReadonlyFillColor2, ReadonlyBorderColor, and ReadonlyForeColor | \[ ] Done |
| Enable or disable CanBeep and CanShake based on user feedback requirements | \[ ] Done |
| Test read‑only behavior across different progress values and screen sizes | \[ ] Done |
| Validate user alerts (audio/visual) on attempted interactions | \[ ] Done |
***
This comprehensive documentation should assist developers in understanding, integrating, and leveraging the Read‑Only Mode feature of the provided control effectively.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs-siticoneframework.gitbook.io/home/net-framework-or-net-core-ui/progress-and-loading/siticone-hprogressbar/read-only-mode.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.