Input, Validation and Read-Only Behavior

Provides control over text editing, validation routines, and modes that prevent modifications.

Overview

This section documents the properties and behaviors related to user input handling, input validation, and managing read-only or disabled states. Developers can customize how input is processed, validated, and how the control visually and functionally responds to user interactions in read-only or disabled conditions.

---

Key Points

Aspect	Description
Input Handling	Manages keyboard and mouse events to update text content, selection, and cursor behavior.
Input Validation	Provides mechanisms to validate text input via custom validation functions, with associated error messages and event triggers.
Read-Only & Disabled	Offers properties and feedback mechanisms (such as shaking or beeping) to indicate that editing is not permitted.
Undo/Redo Functionality	Maintains undo and redo stacks to allow users to revert or reapply text changes.

---

Best Practices

Practice Area	Recommendation
Input Validation	Use the ValidationFunction to enforce input rules and provide clear error messages via ValidationErrorMessage.
Read-Only Feedback	Enable visual and auditory feedback (via CanShake and CanBeep) to inform users when the control is in a read-only state.
Undo/Redo Integration	Implement custom logic for undo and redo operations to enhance user experience without compromising data integrity.
Consistent Behavior	Ensure that input handling and validation behave consistently across different control states (enabled, disabled, read-only).

---

Common Pitfalls

Pitfall	Description
Inconsistent Validation	Failing to set or update the ValidationFunction consistently may lead to unexpected input acceptance or rejection.
Read-Only Feedback Overuse	Excessive shaking or beeping may confuse users; ensure that these feedback mechanisms are used judiciously.
Loss of Undo/Redo History	Improper management of the undo/redo stacks can result in unexpected text loss; always update the state before making significant changes.
Conflicting Input Handling	Overriding default key events without preserving standard behavior (e.g., navigation keys) may lead to a degraded user experience.

---

Real Life Usage Scenarios

Scenario	Description
Data Entry Forms	Use input validation to ensure that the entered text meets business rules and formatting requirements before submission.
Read-Only Data Display	Set the control to read-only mode for data display, while providing visual cues (disabled colors, no editing) to differentiate it from editable fields.
Interactive Command Inputs	Implement undo/redo functionality in command-line interfaces or text editors to allow users to easily correct mistakes.
Secure Input Areas	Use read-only behavior along with input validation to secure sensitive fields where modifications should be prevented.

---

Troubleshooting Tips

Issue	Suggested Solution
Validation Not Triggering	Ensure that the ValidationFunction is assigned and that the text is being processed by the validation logic upon change.
Read-Only Feedback Not Working	Verify that IsReadOnly is correctly set, and check that feedback mechanisms (CanShake, CanBeep) are enabled as desired.
Undo/Redo Operations Failing	Confirm that state changes are properly captured before modifications and that the undo/redo stacks are not cleared unintentionally.
Unexpected Input Behavior	Review the key event handling (e.g., OnKeyDown, OnKeyPress) to ensure that essential keys (such as navigation and editing keys) are not suppressed inadvertently.

---

Property Reference

Below is a reference table of key properties related to input, validation, and read-only behavior:

Property Name	Type	Description
IsReadOnly	bool	Determines whether the control is read-only, preventing text modifications.
IsEnabled	bool	Sets the enabled/disabled state of the control, affecting interactivity and visual feedback.
DisabledBorderColor	Color	Border color when the control is disabled.
DisabledBackColor	Color	Background color when the control is disabled.
DisabledTextColor	Color	Text color when the control is disabled.
ValidationFunction	Func<string, bool>	A delegate that defines a function to validate the text input; returns true if valid.
ValidationErrorMessage	string	The message displayed when the validation function returns false.
Validated	event	Event triggered after validation is performed.
CanShake	bool	Enables a shake animation as feedback when editing is attempted on a read-only control.
CanBeep	bool	Enables an auditory beep as feedback when editing is attempted on a read-only control.
Undo/Redo Stacks	Stack	Internal stacks used to manage undo and redo operations for text changes.

---

Code Examples

Below are several code examples that demonstrate how to use the Input, Validation & Read-Only Behavior properties.

Example 1: Basic Input Validation

This example demonstrates setting up a validation function that only accepts numeric input and displays a custom error message if validation fails.

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

public class ValidationForm : Form
{
    public ValidationForm()
    {
        var customTextBox = new SiticoneTextBox
        {
            Location = new Point(20, 20),
            Size = new Size(250, 40),
            Text = ""
        };

        // Define a validation function that accepts only numeric input
        customTextBox.ValidationFunction = text =>
        {
            foreach (char c in text)
            {
                if (!char.IsDigit(c))
                    return false;
            }
            return true;
        };

        customTextBox.ValidationErrorMessage = "Only numeric input is allowed.";

        // Optional: subscribe to the Validated event
        customTextBox.Validated += (sender, e) =>
        {
            if (!customTextBox.IsValid)
            {
                MessageBox.Show(customTextBox.ValidationErrorMessage, "Validation Error", MessageBoxButtons.OK, MessageBoxIcon.Warning);
            }
        };

        Controls.Add(customTextBox);
        Text = "Input Validation Example";
        Size = new Size(300, 120);
    }

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

---

Example 2: Read-Only Behavior with Feedback

This example shows how to configure the control in read-only mode and enable visual and auditory feedback when an edit is attempted.

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

public class ReadOnlyExampleForm : Form
{
    public ReadOnlyExampleForm()
    {
        var customTextBox = new SiticoneTextBox
        {
            Text = "This field is read-only.",
            IsReadOnly = true,
            Location = new Point(20, 20),
            Size = new Size(300, 40),
            // Read-only specific appearance
            ReadOnlyBorderColor1 = Color.LightGray,
            ReadOnlyBorderColor2 = Color.LightGray,
            ReadOnlyFillColor1 = Color.WhiteSmoke,
            ReadOnlyFillColor2 = Color.WhiteSmoke,
            ReadOnlyPlaceholderColor = Color.DarkGray,
            
            // Enable feedback for read-only attempts
            CanShake = true,
            CanBeep = true
        };

        Controls.Add(customTextBox);
        Text = "Read-Only Behavior Example";
        Size = new Size(360, 120);
    }

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

---

Example 3: Undo and Redo Operations

This example demonstrates the use of the control’s undo and redo functionality in response to user actions.

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

public class UndoRedoExampleForm : Form
{
    private SiticoneTextBox customTextBox;
    private Button undoButton;
    private Button redoButton;

    public UndoRedoExampleForm()
    {
        customTextBox = new SiticoneTextBox
        {
            Text = "Initial text",
            Location = new Point(20, 20),
            Size = new Size(300, 40)
        };

        undoButton = new Button
        {
            Text = "Undo",
            Location = new Point(20, 80),
            Size = new Size(140, 30)
        };
        undoButton.Click += (sender, e) =>
        {
            customTextBox.Undo();
        };

        redoButton = new Button
        {
            Text = "Redo",
            Location = new Point(180, 80),
            Size = new Size(140, 30)
        };
        redoButton.Click += (sender, e) =>
        {
            customTextBox.Redo();
        };

        Controls.Add(customTextBox);
        Controls.Add(undoButton);
        Controls.Add(redoButton);
        Text = "Undo/Redo Example";
        Size = new Size(380, 160);
    }

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

---

Frequently Asked Questions

Question	Answer
How do I enforce input rules using validation?	Assign a function to the ValidationFunction property that returns true for valid input and false for invalid input, and provide a custom message via ValidationErrorMessage.
What feedback is available when the control is read-only?	When the control is read-only, enabling CanShake and CanBeep will trigger a shake animation and an audible beep respectively when editing is attempted.
How can I recover previous text inputs?	Use the undo and redo functionalities, which are internally managed through undo/redo stacks, to revert or reapply changes.
How do I disable user input completely?	Set the IsEnabled property to false; this will disable user interaction and apply the disabled appearance properties (DisabledBorderColor, DisabledBackColor, DisabledTextColor).
Can validation be triggered on every text change?	Yes, validation is automatically triggered on text changes if the ValidationFunction is defined, and the Validated event is raised accordingly.
What happens if validation fails?	If validation fails, the Validated event is triggered and the control can display the ValidationErrorMessage, optionally halting further processing.

---

Integration Checklist

Step	Verification
Input Validation Setup	Confirm that a ValidationFunction is defined and that ValidationErrorMessage is properly set.
Read-Only & Disabled Configuration	Ensure that the control's IsReadOnly and IsEnabled properties are set as intended, and that the corresponding appearance properties are applied.
Feedback Mechanisms	Verify that CanShake and CanBeep are enabled if you want feedback when editing is attempted in read-only mode.
Undo/Redo Functionality	Test the undo and redo operations by making text changes and confirming that the control reverts or reapplies changes appropriately.
Key and Mouse Input Handling	Ensure that input events (such as key presses and mouse events) are correctly processed and do not conflict with validation or read-only states.
Event Trigger Verification	Check that events like Validated are raised as expected during input changes and that they provide the correct feedback.
Accessibility Compliance	Verify that disabled or read-only states have appropriate visual cues (such as different colors) for better accessibility.
Cross-Platform Consistency	Confirm that the control behaves and renders consistently across different Windows versions and DPI settings if applicable.

---

Review

Review Aspect	Details
Input Handling Robustness	The control captures key and mouse events effectively to manage text input and selection, ensuring a smooth user experience.
Validation Integration	Developers can easily integrate custom validation logic with immediate visual and event-based feedback.
Read-Only Mode Functionality	Read-only and disabled states are well-supported, with additional feedback mechanisms to guide user interaction.
Undo/Redo Support	The built-in undo/redo functionality provides a safety net for user mistakes, enhancing usability in text-intensive applications.

---

Summary

The Input, Validation & Read-Only Behavior feature offers comprehensive control over how user input is processed, validated, and presented in different states.

By using these properties and events, developers can ensure that the control meets specific data entry requirements, provides appropriate user feedback, and maintains data integrity through undo/redo functionality.