beyhan/ClassicAssist.Avalonia
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Beyhan Oğur
2026-09-03 04:45:36 +03:00
commit d5f52cc3d3
1038 changed files with 169579 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.qoder/repowiki/en/content/User Interface Guide/Custom Controls Library/EditTextBlock.md
+227
View File
@@ -0,0 +1,227 @@
# EditTextBlock
<cite>
**Referenced Files in This Document**
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
</cite>
## Table of Contents
1. [Introduction](#introduction)
2. [Project Structure](#project-structure)
3. [Core Components](#core-components)
4. [Architecture Overview](#architecture-overview)
5. [Detailed Component Analysis](#detailed-component-analysis)
6. [Dependency Analysis](#dependency-analysis)
7. [Performance Considerations](#performance-considerations)
8. [Troubleshooting Guide](#troubleshooting-guide)
9. [Conclusion](#conclusion)
## Introduction
This document provides comprehensive documentation for the EditTextBlock control, which combines the visual appearance of a TextBlock with editable text functionality. It explains how to use and customize the control, including properties such as Text, IsReadOnly, MaxLength, and validation rules. It also covers the editing lifecycle, focus management, keyboard navigation behavior, two-way data binding, custom formatting, integration with validation frameworks, styling and template customization, accessibility features, and guidance on when to choose EditTextBlock versus TextBox.
## Project Structure
The EditTextBlock control is implemented in the Avalonia UI project under Controls. The control consists of an Axaml markup file that defines its visual structure and an associated code-behind file that implements its behavior and properties.
```mermaid
graph TB
subgraph "Avalonia Project"
A["Controls/EditTextBlock.axaml"]
B["Controls/EditTextBlock.axaml.cs"]
end
A --> B
```
**Diagram sources**
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
**Section sources**
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
## Core Components
- Visual layer: The Axaml markup defines the control’s visual tree, typically hosting a TextBlock for display and an internal TextBox for editing.
- Behavior layer: The code-behind exposes dependency properties (e.g., Text, IsReadOnly, MaxLength), manages focus transitions between display and edit modes, and handles input events and validation.
Key responsibilities:
- Display mode: Render text using a TextBlock-like appearance.
- Edit mode: Switch to an internal TextBox to allow user input.
- Focus management: Capture and release focus appropriately during edit sessions.
- Validation: Enforce constraints like MaxLength and integrate with validation logic.
- Binding: Support two-way binding to Text and related properties.
**Section sources**
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
## Architecture Overview
At runtime, EditTextBlock toggles between a read-only presentation and an inline editing experience. When the user initiates editing, the control focuses an internal TextBox; when editing completes or is canceled, it returns to the TextBlock-like presentation.
```mermaid
sequenceDiagram
participant User as "User"
participant Control as "EditTextBlock"
participant Display as "TextBlock"
participant Editor as "TextBox"
User->>Control : Click to edit
Control->>Editor : Show editor and set focus
Editor-->>Control : Text changes (two-way binding)
User->>Editor : Finish editing (Enter/blur)
Control->>Display : Update display value
Control->>Editor : Hide editor and clear focus
```
**Diagram sources**
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
## Detailed Component Analysis
### Properties and Data Binding
- Text: Two-way bindable string property representing the current content. Updates propagate both from view model to control and from control to view model.
- IsReadOnly: Boolean flag controlling whether the control allows editing. When true, the control remains in display mode.
- MaxLength: Numeric constraint limiting the number of characters allowed in edit mode.
Binding patterns:
- Use two-way binding to keep the view model synchronized with user edits.
- For read-only scenarios, bind IsReadOnly to a view model state.
Validation integration:
- Apply validation rules by handling change notifications or by wrapping the bound property with validation logic in the view model.
- Enforce MaxLength at the control level to prevent invalid input early.
**Section sources**
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
### Editing Lifecycle
The control follows a predictable lifecycle:
- Entry into edit mode: On user action (e.g., click), the control switches to edit mode, focuses the internal TextBox, and selects existing text if appropriate.
- During editing: The control listens to text changes and updates the backing property via two-way binding.
- Exit from edit mode: On completion (e.g., Enter key or losing focus), the control validates input, applies constraints (like MaxLength), commits changes, and returns to display mode.
```mermaid
flowchart TD
Start(["Edit initiated"]) --> FocusEditor["Focus internal TextBox"]
FocusEditor --> InputLoop["User inputs text"]
InputLoop --> ValidateInput{"Valid?"}
ValidateInput --> |No| Reject["Reject input / show error"]
ValidateInput --> |Yes| Commit["Commit changes"]
Commit --> ExitMode["Exit edit mode"]
ExitMode --> End(["Display updated"])
Reject --> InputLoop
```
**Diagram sources**
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
### Focus Management and Keyboard Navigation
- Focus capture: The control programmatically focuses the internal TextBox when entering edit mode.
- Focus release: The control clears focus when exiting edit mode, returning focus to the logical parent element if needed.
- Keyboard behavior:
- Enter: Commits changes and exits edit mode.
- Escape: Cancels changes and reverts to previous value.
- Tab: Moves focus out of the control, triggering commit or cancel depending on implementation.
- Arrow keys and selection: Standard text editing behaviors are supported within the internal TextBox.
Accessibility considerations:
- Ensure proper AutomationPeer support so screen readers announce the control’s role and state.
- Provide meaningful names and descriptions via accessible properties.
**Section sources**
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
### Styling and Template Customization
- Style targets: You can style the control to match application themes, including fonts, colors, borders, and padding.
- Template customization: Override the control template to replace the default visual tree while preserving behavior. Common customizations include:
- Adding icons or buttons adjacent to the text area.
- Changing layout orientation or alignment.
- Applying different visual states for hover, focus, and disabled.
Best practices:
- Keep the internal TextBox and TextBlock roles intact to preserve editing semantics.
- Avoid removing focus-related elements required for accessibility.
**Section sources**
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
### Integration Examples
#### Two-Way Data Binding
Bind the Text property to a view model property with two-way mode. Changes made in the control update the view model automatically, and updates from the view model reflect in the control.
#### Custom Formatting
Use converters or formatters in bindings to format values for display while preserving raw values for editing. Alternatively, handle formatting in the control’s code-behind around edit entry and exit.
#### Validation Frameworks
Integrate with validation frameworks by:
- Raising validation errors when MaxLength is exceeded.
- Exposing a validation state property that can be bound to error indicators.
- Using INotifyDataErrorInfo or similar patterns in the view model to report validation results.
**Section sources**
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
### When to Use EditTextBlock vs TextBox
- Use EditTextBlock when:
- You want a compact, TextBlock-like appearance most of the time.
- Inline editing is preferred without introducing a full-width TextBox.
- Read-only and editable states need to switch seamlessly.
- Use TextBox when:
- Users frequently enter large amounts of text.
- Complex editing features (multiline, rich editing) are required.
- The UI already emphasizes input fields and does not need a hybrid control.
## Dependency Analysis
EditTextBlock depends on Avalonia’s core controls and binding infrastructure. Its behavior relies on focus events, input handling, and dependency properties.
```mermaid
graph TB
ETB["EditTextBlock.axaml.cs"]
AXAML["EditTextBlock.axaml"]
AV["Avalonia Core"]
BIND["Avalonia Binding"]
FOCUS["Focus System"]
INPUT["Input Handling"]
ETB --> AXAML
ETB --> AV
ETB --> BIND
ETB --> FOCUS
ETB --> INPUT
```
**Diagram sources**
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
**Section sources**
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
- [EditTextBlock.axaml](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml)
## Performance Considerations
- Minimize unnecessary rebinds by avoiding excessive updates to the Text property.
- Debounce heavy validation logic to avoid blocking the UI thread during typing.
- Prefer lightweight templates and styles to reduce layout overhead.
- Reuse resources (brushes, fonts) across instances where possible.
## Troubleshooting Guide
Common issues and resolutions:
- Binding not updating:
- Ensure two-way binding is configured correctly.
- Verify that the view model raises property change notifications.
- Validation not triggering:
- Confirm that validation logic runs on relevant events (text changed, commit).
- Check that error states are exposed and bound to UI indicators.
- Focus problems:
- Ensure the control captures focus on edit entry and releases it on exit.
- Test keyboard navigation across host containers.
- Accessibility concerns:
- Verify that accessible names and roles are set.
- Test with a screen reader to confirm announcements.
**Section sources**
- [EditTextBlock.axaml.cs](file://ClassicAssist.Avalonia/Controls/EditTextBlock.axaml.cs)
## Conclusion
EditTextBlock offers a streamlined way to present and edit text inline, combining the look of a TextBlock with the functionality of a TextBox. By leveraging its properties, lifecycle, and customization options, you can create intuitive interfaces that balance readability and editability. Choose EditTextBlock for compact inline editing scenarios and TextBox for more intensive input tasks.