mirror of
https://github.com/gui-cs/Terminal.Gui.git
synced 2025-12-26 15:57:56 +01:00
* Initial plan * Enable VT processing in WindowsOutput to support hyperlink detection Co-authored-by: tig <585482+tig@users.noreply.github.com> * Address code review feedback - track VT enablement and add error handling Co-authored-by: tig <585482+tig@users.noreply.github.com> * Revert VT processing changes - investigating actual root cause Co-authored-by: tig <585482+tig@users.noreply.github.com> * Implement OSC 8 hyperlink support in Attribute and OutputBase Co-authored-by: tig <585482+tig@users.noreply.github.com> * Implement automatic URL detection with OSC 8 at driver level Co-authored-by: tig <585482+tig@users.noreply.github.com> * Fix OSC 8 URL wrapping to handle ANSI escape sequences properly Co-authored-by: tig <585482+tig@users.noreply.github.com> * Update newinv2.md Terminal.Gui v2 introduces a reimagined architecture, removing redundant and overly complex code from v1. Key changes include: - Added TrueColor support with 24-bit RGB handling. - Introduced modular adornments framework (Margin, Border, Padding). - Enhanced Unicode and wide character support for internationalization. - Simplified API with centralized navigation and modern .NET standards. - Added built-in scrolling via `Viewport` and improved `ScrollBar`. - Introduced new views (Bar, CharMap, ColorPicker, etc.) and enhanced existing ones. - Added `ConfigurationManager` for customizable themes and settings. - Improved visual fidelity with `LineCanvas`, gradients, and borders. - Introduced logging, metrics, and Sixel image support. - Enhanced keyboard and mouse APIs for better interaction handling. - Ensured AOT compatibility for simplified deployment. These changes modernize the library, improve usability, and expand its capabilities for terminal-based applications. * Remove automatic URL detection - reverting to clean state Co-authored-by: tig <585482+tig@users.noreply.github.com> * Revamp View.md documentation for clarity and depth Comprehensively restructured and enhanced the `View.md` documentation for the `Terminal.Gui` library to improve usability and completeness. - Added a Table of Contents for easier navigation. - Rewrote the "View Hierarchy" section to clarify terminology and key properties, with links to relevant API references. - Expanded "View Composition" and "Core Concepts" sections with detailed explanations of layers, adornments, and scrolling. - Detailed the "View Lifecycle" with step-by-step processes and code examples for initialization, layout, drawing, input handling, and disposal. - Reorganized and expanded the "Subsystems" section, covering commands, input handling, layout, drawing, navigation, and scrolling. - Updated the "Modal Views" section with examples for dialogs, wizards, and modal view types. - Introduced a "Common View Patterns" section with practical examples for creating custom views, adding subviews, and implementing scrolling. - Added an "Advanced Topics" section covering diagnostics, view states, and shadow effects. - Included numerous inline code examples to illustrate key concepts. - Concluded with a "See Also" section linking to related deep-dive documentation. These changes significantly improve the structure, clarity, and accessibility of the documentation, making it easier for developers to understand and use the library effectively. * Restore working automatic URL detection with fix for URLs containing ANSI sequences Co-authored-by: tig <585482+tig@users.noreply.github.com> * Fix URL regex to handle underscores and trailing punctuation + add comprehensive tests Co-authored-by: tig <585482+tig@users.noreply.github.com> * Update and expand Configuration Management documentation The document title was updated to "Configuration Management Deep Dive" to reflect its expanded scope. A new Table of Contents was added for improved navigation. The introduction and "Overview" sections were rewritten to provide a clearer explanation of the `ConfigurationManager` class and its key features. New sections were added, including "Getting Started," "Themes and Schemes," "Defining Configuration Properties," "Events," and "Best Practices." These sections provide detailed explanations, examples, and recommendations for using the `ConfigurationManager` effectively. The "Configuration Scopes" and "Configuration Locations and Precedence" sections were restructured and expanded with detailed explanations, diagrams, and examples. Advanced topics such as JSON error handling, runtime configuration, and file system watching were introduced. The document now includes several new examples, such as theme switching and custom application settings, along with references to related topics and UICatalog examples. The content was reorganized for clarity, with redundant sections removed. * Refactor and expand Arrangement system documentation Updated the title to "View Arrangement Deep Dive" and added a Table of Contents for better navigation. Expanded the "Overview" section and restructured "Arrangement Modes" with detailed examples. Added new sections for "Arrange Mode (Interactive)," "Movable Views," "Resizable Views," and "Creating Resizable Splitters," with practical code samples. Enhanced "Tiled vs Overlapped Layouts" and "Modal Views" sections, and introduced "Runnable Views" to explain non-modal behavior. Expanded the "Examples" section with multiple use cases and added advanced topics like Z-order management and arrangement events. Updated `arrangement-lexicon.md` with API links for key terms. Improved formatting and consistency throughout the document to enhance clarity and usability. * Update CONTRIBUTING.md references and add critical note Updated the reference to `CONTRIBUTING.md` to use a relative path (`../CONTRIBUTING.md`) for accurate resolution. Enhanced instructions for AI agents, including CoPilot and Cursor, to strictly follow the updated guidelines. Added a **CRITICAL** note requiring CoPilot to internalize and adhere to the guidelines, including when operating in Agent mode. * Refactor URL handling and add OSC 8 hyperlink support Replaced `UrlRegex` with the new `Osc8UrlLinker` utility to handle URL detection and wrapping with OSC 8 hyperlink sequences, improving modularity and maintainability. Updated `OutputBase` to use `Osc8UrlLinker.WrapOsc8` for URL processing and removed legacy `WrapUrlsWithHyperlinks` logic. Added the `Osc8UrlLinker` class with robust URL parsing, support for allowed schemes, and handling of edge cases like trailing punctuation and ANSI escape sequences. Improved performance with efficient `StringBuilder` usage. Enhanced `AnimationScenario` to ensure URLs with underscores are drawn correctly. Improved code readability by renaming constants, simplifying nullable handling, and updating documentation. Replaced legacy `UrlDetectionTests` with `Osc8UrlLinkerTests`, covering standalone URLs, URLs in text, multiple URLs, and edge cases. Verified hyperlink wrapping correctness and visible content integrity. Updated `Terminal.sln.ToDo.DotSettings` to disable auto-opening of the Stack Trace Explorer. Cleaned up unused code, enabled nullable reference types, and improved XML documentation formatting. --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: tig <585482+tig@users.noreply.github.com> Co-authored-by: Tig <tig@users.noreply.github.com>
This commit is contained in:
Copilot
GitHub
@@ -1,116 +1,691 @@
|
||||
# View Deep Dive
|
||||
|
||||
## Hierarchy
|
||||
[View](~/api/Terminal.Gui.ViewBase.View.yml) is the base class for all visible UI elements in Terminal.Gui. View provides core functionality for layout, drawing, input handling, navigation, and scrolling. All interactive controls, windows, and dialogs derive from View.
|
||||
|
||||
* @Terminal.Gui.View - The base class for implementing higher-level visual/interactive Terminal.Gui elements. Implemented in the @Terminal.Gui.ViewBase.View base class.
|
||||
|
||||
* *SubView* - A View that is contained in another view and will be rendered as part of the containing view's **ContentArea**. SubViews are added to another view via the @"Terminal.Gui.ViewBase.View.Add(Terminal.Gui.View)" method. A View may only be a SubView of a single View. Each View has a @Terminal.Gui.ViewBase.View.SubViews property that is a list of all SubViews that have been added.
|
||||
|
||||
* @Terminal.Gui.View.SuperView - The View that is a container for SubViews. Each View has a @Terminal.Gui.ViewBase.View.SuperView property that references it's SuperView after it has been added.
|
||||
|
||||
* *Child View* - A view that holds a reference to another view in a parent/child relationship. Terminal.Gui uses the terms "Child" and "Parent" sparingly. Generally SubView/SuperView is preferred.
|
||||
|
||||
* *Parent View* - A view that holds a reference to another view in a parent/child relationship, but is NOT a SuperView of the child. Terminal.Gui uses the terms "Child" and "Parent" sparingly. Generally SubView/SuperView is preferred.
|
||||
See the [Views Overview](views.md) for a catalog of all built-in View subclasses.
|
||||
|
||||
## Composition
|
||||
## Table of Contents
|
||||
|
||||
- [View Hierarchy](#view-hierarchy)
|
||||
- [View Composition](#view-composition)
|
||||
- [Core Concepts](#core-concepts)
|
||||
- [View Lifecycle](#view-lifecycle)
|
||||
- [Subsystems](#subsystems)
|
||||
- [Common View Patterns](#common-view-patterns)
|
||||
- [Modal Views](#modal-views)
|
||||
|
||||
---
|
||||
|
||||
## View Hierarchy
|
||||
|
||||
### Terminology
|
||||
|
||||
- **[View](~/api/Terminal.Gui.ViewBase.View.yml)** - The base class for all visible UI elements
|
||||
- **SubView** - A View that is contained in another View and rendered as part of the containing View's content area. SubViews are added via [View.Add](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Add_Terminal_Gui_ViewBase_View_)
|
||||
- **SuperView** - The View that contains SubViews. Each View has a [View.SuperView](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SuperView) property that references its container
|
||||
- **Child View** - A view that holds a reference to another view in a parent/child relationship (used sparingly; generally SubView/SuperView is preferred)
|
||||
- **Parent View** - A view that holds a reference to another view but is NOT a SuperView (used sparingly)
|
||||
|
||||
### Key Properties
|
||||
|
||||
- [View.SubViews](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SubViews) - Read-only list of all SubViews added to this View
|
||||
- [View.SuperView](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SuperView) - The View's container (null if the View has no container)
|
||||
- [View.Id](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Id) - Unique identifier for the View (should be unique among siblings)
|
||||
- [View.Data](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Data) - Arbitrary data attached to the View
|
||||
|
||||
---
|
||||
|
||||
## View Composition
|
||||
|
||||
Views are composed of several nested layers that define how they are positioned, drawn, and scrolled:
|
||||
|
||||
[!INCLUDE [View Composition](~/includes/view-composition.md)]
|
||||
|
||||
### List of Built-In Views
|
||||
### The Layers
|
||||
|
||||
See [List of Built-In Views](views.md)
|
||||
1. **[Frame](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Frame)** - The outermost rectangle defining the View's location and size relative to the SuperView's content area
|
||||
2. **[Margin](~/api/Terminal.Gui.ViewBase.Margin.yml)** - Adornment that provides spacing between the View and other SubViews
|
||||
3. **[Border](~/api/Terminal.Gui.ViewBase.Border.yml)** - Adornment that draws the visual border and title
|
||||
4. **[Padding](~/api/Terminal.Gui.ViewBase.Padding.yml)** - Adornment that provides spacing between the border and the viewport
|
||||
5. **[Viewport](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Viewport)** - Rectangle describing the visible portion of the content area
|
||||
6. **Content Area** - The total area where content can be drawn (defined by [View.GetContentSize](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_GetContentSize))
|
||||
|
||||
See the [Layout Deep Dive](layout.md) for complete details on View composition and layout.
|
||||
|
||||
---
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### Frame vs. Viewport
|
||||
|
||||
- **Frame** - The View's location and size in SuperView-relative coordinates. Frame includes all adornments (Margin, Border, Padding)
|
||||
- **Viewport** - The visible "window" into the View's content, located inside the adornments. Viewport coordinates are always relative to (0,0) of the content area
|
||||
|
||||
```csharp
|
||||
// Frame is SuperView-relative
|
||||
view.Frame = new Rectangle(10, 5, 50, 20);
|
||||
|
||||
// Viewport is content-relative (the visible portal)
|
||||
view.Viewport = new Rectangle(0, 0, 45, 15); // Adjusted for adornments
|
||||
```
|
||||
|
||||
### Content Area and Scrolling
|
||||
|
||||
The **Content Area** is where the View's content is drawn. By default, the content area size matches the Viewport size. To enable scrolling:
|
||||
|
||||
1. Call [View.SetContentSize](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SetContentSize_System_Nullable_System_Drawing_Size__) with a size larger than the Viewport
|
||||
2. Change `Viewport.Location` to scroll the content
|
||||
|
||||
See the [Scrolling Deep Dive](scrolling.md) for complete details.
|
||||
|
||||
### Adornments
|
||||
|
||||
[Adornments](~/api/Terminal.Gui.ViewBase.Adornment.yml) are special Views that surround the content:
|
||||
|
||||
- **[Margin](~/api/Terminal.Gui.ViewBase.Margin.yml)** - Transparent spacing outside the Border
|
||||
- **[Border](~/api/Terminal.Gui.ViewBase.Border.yml)** - Visual frame with [LineStyle](~/api/Terminal.Gui.Drawing.LineStyle.yml), title, and arrangement UI
|
||||
- **[Padding](~/api/Terminal.Gui.ViewBase.Padding.yml)** - Spacing inside the Border, outside the Viewport
|
||||
|
||||
Each adornment has a [Thickness](~/api/Terminal.Gui.Drawing.Thickness.yml) that defines the width of each side (Top, Right, Bottom, Left).
|
||||
|
||||
See the [Layout Deep Dive](layout.md) for complete details on adornments.
|
||||
|
||||
---
|
||||
|
||||
## View Lifecycle
|
||||
|
||||
### Initialization
|
||||
|
||||
Views implement [ISupportInitializeNotification](https://docs.microsoft.com/en-us/dotnet/api/system.componentmodel.isupportinitializenotification):
|
||||
|
||||
1. **Constructor** - Creates the View and sets up default state
|
||||
2. **[BeginInit](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_BeginInit)** - Signals initialization is starting
|
||||
3. **[EndInit](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_EndInit)** - Signals initialization is complete; raises [View.Initialized](~/api/Terminal.Gui.ViewBase.View.yml) event
|
||||
4. **[IsInitialized](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_IsInitialized)** - Property indicating if initialization is complete
|
||||
|
||||
### Disposal
|
||||
|
||||
Views are [IDisposable](https://docs.microsoft.com/en-us/dotnet/api/system.idisposable):
|
||||
|
||||
- Call [View.Dispose](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Dispose) to clean up resources
|
||||
- The [View.Disposing](~/api/Terminal.Gui.ViewBase.View.yml) event is raised when disposal begins
|
||||
- Automatically disposes SubViews, adornments, and scroll bars
|
||||
|
||||
---
|
||||
|
||||
## Subsystems
|
||||
|
||||
View is organized as a partial class across multiple files, each handling a specific subsystem:
|
||||
|
||||
### Commands
|
||||
|
||||
See the [Command Deep Dive](command.md).
|
||||
|
||||
### Input
|
||||
- [View.AddCommand](~/api/Terminal.Gui.ViewBase.View.yml) - Declares commands the View supports
|
||||
- [View.InvokeCommand](~/api/Terminal.Gui.ViewBase.View.yml) - Invokes a command
|
||||
- [Command](~/api/Terminal.Gui.Input.Command.yml) enum - Standard set of commands (Accept, Select, HotKey, etc.)
|
||||
|
||||
See the [Keyboard Deep Dive](keyboard.md) and [Mouse Deep Dive](mouse.md).
|
||||
### Input Handling
|
||||
|
||||
#### Keyboard
|
||||
|
||||
See the [Keyboard Deep Dive](keyboard.md).
|
||||
|
||||
- [View.KeyBindings](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_KeyBindings) - Maps keys to Commands
|
||||
- [View.HotKey](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HotKey) - The hot key for the View
|
||||
- [View.HotKeySpecifier](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HotKeySpecifier) - Character used to denote hot keys in text (default: '_')
|
||||
- Events: `KeyDown`, `KeyUp`, `InvokingKeyBindings`
|
||||
|
||||
#### Mouse
|
||||
|
||||
See the [Mouse Deep Dive](mouse.md).
|
||||
|
||||
- [View.MouseBindings](~/api/Terminal.Gui.ViewBase.View.yml) - Maps mouse events to Commands
|
||||
- [View.WantContinuousButtonPresses](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_WantContinuousButtonPresses) - Enables continuous button press events
|
||||
- [View.Highlight](~/api/Terminal.Gui.ViewBase.View.yml) - Event for visual feedback on mouse hover/click
|
||||
- [View.HighlightStyle](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HighlightStyle) - Visual style when highlighted
|
||||
- Events: `MouseEnter`, `MouseLeave`, `MouseClick`, `MouseEvent`
|
||||
|
||||
### Layout and Arrangement
|
||||
|
||||
See the [Layout Deep Dive](layout.md) and the [Arrangement Deep Dive](arrangement.md).
|
||||
See the [Layout Deep Dive](layout.md) and [Arrangement Deep Dive](arrangement.md).
|
||||
|
||||
#### Position and Size
|
||||
|
||||
- [View.X](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_X) - Horizontal position using [Pos](~/api/Terminal.Gui.Pos.yml)
|
||||
- [View.Y](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Y) - Vertical position using [Pos](~/api/Terminal.Gui.Pos.yml)
|
||||
- [View.Width](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Width) - Width using [Dim](~/api/Terminal.Gui.Dim.yml)
|
||||
- [View.Height](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Height) - Height using [Dim](~/api/Terminal.Gui.Dim.yml)
|
||||
|
||||
#### Layout Features
|
||||
|
||||
- [Dim.Auto](~/api/Terminal.Gui.Dim.yml#Terminal_Gui_Dim_Auto_Terminal_Gui_DimAutoStyle_Terminal_Gui_Dim_Terminal_Gui_Dim_) - Automatic sizing based on content
|
||||
- [Pos.AnchorEnd](~/api/Terminal.Gui.Pos.yml#Terminal_Gui_Pos_AnchorEnd_System_Int32_) - Anchor to right/bottom edges
|
||||
- [Pos.Align](~/api/Terminal.Gui.Pos.yml) - Align views relative to each other
|
||||
- [Pos.Center](~/api/Terminal.Gui.Pos.yml) - Center within SuperView
|
||||
- [Dim.Fill](~/api/Terminal.Gui.Dim.yml) - Fill available space
|
||||
|
||||
#### Arrangement
|
||||
|
||||
- [View.Arrangement](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Arrangement) - Controls if View is movable/resizable
|
||||
- [ViewArrangement](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml) - Flags: Fixed, Movable, Resizable, Overlapped
|
||||
|
||||
#### Events
|
||||
|
||||
- `LayoutStarted` - Before layout begins
|
||||
- `LayoutComplete` - After layout completes
|
||||
- `FrameChanged` - When Frame changes
|
||||
- `ViewportChanged` - When Viewport changes
|
||||
|
||||
### Drawing
|
||||
|
||||
See the [Drawing Deep Dive](drawing.md).
|
||||
|
||||
Views should use viewport-relative coordinates for all drawing operations. The `View.Move(col, row)` method positions the cursor using viewport-relative coordinates. For screen dimensions, use @Terminal.Gui.App.Application.Screen instead of accessing the driver directly.
|
||||
#### Color and Style
|
||||
|
||||
- [View.Scheme](~/api/Terminal.Gui.ViewBase.View.yml) - Color scheme for the View
|
||||
- [View.SetAttribute](~/api/Terminal.Gui.ViewBase.View.yml) - Sets the attribute for subsequent drawing
|
||||
- [View.SetAttributeForRole](~/api/Terminal.Gui.ViewBase.View.yml) - Sets attribute based on [VisualRole](~/api/Terminal.Gui.Drawing.VisualRole.yml)
|
||||
|
||||
See the [Scheme Deep Dive](scheme.md) for details on color theming.
|
||||
|
||||
#### Drawing Methods
|
||||
|
||||
- [View.Draw](~/api/Terminal.Gui.ViewBase.View.yml) - Main drawing method
|
||||
- [View.AddRune](~/api/Terminal.Gui.ViewBase.View.yml) - Draws a single Rune
|
||||
- [View.AddStr](~/api/Terminal.Gui.ViewBase.View.yml) - Draws a string
|
||||
- [View.Move](~/api/Terminal.Gui.ViewBase.View.yml) - Positions the cursor
|
||||
- [View.Clear](~/api/Terminal.Gui.ViewBase.View.yml) - Clears the View's content
|
||||
|
||||
#### Drawing Events
|
||||
|
||||
- `DrawingContent` - Before content is drawn
|
||||
- `DrawingContentComplete` - After content is drawn
|
||||
- `DrawingAdornments` - Before adornments are drawn
|
||||
- `DrawingAdornmentsComplete` - After adornments are drawn
|
||||
|
||||
#### Invalidation
|
||||
|
||||
- [View.SetNeedsDraw](~/api/Terminal.Gui.ViewBase.View.yml) - Marks View as needing redraw
|
||||
- [View.NeedsDraw](~/api/Terminal.Gui.ViewBase.View.yml) - Property indicating if View needs redraw
|
||||
|
||||
### Navigation
|
||||
|
||||
See the [Navigation Deep Dive](navigation.md).
|
||||
|
||||
- [View.CanFocus](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_CanFocus) - Whether the View can receive keyboard focus
|
||||
- [View.HasFocus](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HasFocus) - Whether the View currently has focus
|
||||
- [View.TabStop](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_TabStop) - [TabBehavior](~/api/Terminal.Gui.Input.TabBehavior.yml) for tab navigation
|
||||
- [View.TabIndex](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_TabIndex) - Order in tab navigation
|
||||
- [View.SetFocus](~/api/Terminal.Gui.ViewBase.View.yml) - Gives focus to the View
|
||||
|
||||
Events:
|
||||
- `HasFocusChanging` - Before focus changes (cancellable)
|
||||
- `HasFocusChanged` - After focus changes
|
||||
- `Accepting` - When Command.Accept is invoked (typically Enter key)
|
||||
- `Accepted` - After Command.Accept completes
|
||||
- `Selecting` - When Command.Select is invoked (typically Space or mouse click)
|
||||
- `Selected` - After Command.Select completes
|
||||
|
||||
### Scrolling
|
||||
|
||||
See the [Scrolling Deep Dive](scrolling.md).
|
||||
|
||||
- [View.Viewport](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Viewport) - Visible portion of the content area
|
||||
- [View.GetContentSize](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_GetContentSize) - Returns size of scrollable content
|
||||
- [View.SetContentSize](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SetContentSize_System_Nullable_System_Drawing_Size__) - Sets size of scrollable content
|
||||
- [View.ScrollHorizontal](~/api/Terminal.Gui.ViewBase.View.yml) - Scrolls content horizontally
|
||||
- [View.ScrollVertical](~/api/Terminal.Gui.ViewBase.View.yml) - Scrolls content vertically
|
||||
- [View.VerticalScrollBar](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_VerticalScrollBar) - Built-in vertical scrollbar
|
||||
- [View.HorizontalScrollBar](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HorizontalScrollBar) - Built-in horizontal scrollbar
|
||||
- [View.ViewportSettings](~/api/Terminal.Gui.ViewBase.View.yml) - [ViewportSettingsFlags](~/api/Terminal.Gui.ViewBase.ViewportSettingsFlags.yml) controlling scroll behavior
|
||||
|
||||
### Text
|
||||
|
||||
- [View.Text](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Text) - The View's text content
|
||||
- [View.Title](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Title) - The View's title (shown in Border)
|
||||
- [View.TextFormatter](~/api/Terminal.Gui.ViewBase.View.yml) - Handles text formatting and alignment
|
||||
- [View.TextDirection](~/api/Terminal.Gui.ViewBase.View.yml) - Text direction (LeftRight, RightToLeft, TopToBottom)
|
||||
- [View.TextAlignment](~/api/Terminal.Gui.ViewBase.View.yml) - Text alignment (Left, Centered, Right, Justified)
|
||||
- [View.VerticalTextAlignment](~/api/Terminal.Gui.ViewBase.View.yml) - Vertical alignment (Top, Middle, Bottom, Justified)
|
||||
|
||||
---
|
||||
|
||||
## View Lifecycle
|
||||
|
||||
### 1. Creation
|
||||
|
||||
```csharp
|
||||
View view = new ()
|
||||
{
|
||||
X = Pos.Center(),
|
||||
Y = Pos.Center(),
|
||||
Width = Dim.Percent(50),
|
||||
Height = Dim.Fill()
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Initialization
|
||||
|
||||
When a View is added to a SuperView or when [Application.Run](~/api/Terminal.Gui.App.Application.yml#Terminal_Gui_App_Application_Run_Terminal_Gui_Views_Toplevel_System_Func_System_Exception_System_Boolean__) is called:
|
||||
|
||||
1. [BeginInit](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_BeginInit) is called
|
||||
2. [EndInit](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_EndInit) is called
|
||||
3. [IsInitialized](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_IsInitialized) becomes true
|
||||
4. [Initialized](~/api/Terminal.Gui.ViewBase.View.yml) event is raised
|
||||
|
||||
### 3. Layout
|
||||
|
||||
Layout happens automatically when needed:
|
||||
|
||||
1. [View.SetNeedsLayout](~/api/Terminal.Gui.ViewBase.View.yml) marks View as needing layout
|
||||
2. [View.Layout](~/api/Terminal.Gui.ViewBase.View.yml) calculates position and size
|
||||
3. `LayoutStarted` event is raised
|
||||
4. Frame and Viewport are calculated based on X, Y, Width, Height
|
||||
5. SubViews are laid out
|
||||
6. `LayoutComplete` event is raised
|
||||
|
||||
### 4. Drawing
|
||||
|
||||
Drawing happens automatically when needed:
|
||||
|
||||
1. [View.SetNeedsDraw](~/api/Terminal.Gui.ViewBase.View.yml) marks View as needing redraw
|
||||
2. [View.Draw](~/api/Terminal.Gui.ViewBase.View.yml) renders the View
|
||||
3. `DrawingContent` event is raised
|
||||
4. [View.OnDrawingContent](~/api/Terminal.Gui.ViewBase.View.yml) is called (override to draw custom content)
|
||||
5. `DrawingContentComplete` event is raised
|
||||
6. Adornments are drawn
|
||||
7. SubViews are drawn
|
||||
|
||||
### 5. Input Processing
|
||||
|
||||
Input is processed in this order:
|
||||
|
||||
1. **Keyboard**: Key → KeyBindings → Command → Command Handlers → Events
|
||||
2. **Mouse**: MouseEvent → MouseBindings → Command → Command Handlers → Events
|
||||
|
||||
### 6. Disposal
|
||||
|
||||
```csharp
|
||||
view.Dispose();
|
||||
```
|
||||
|
||||
- Raises [View.Disposing](~/api/Terminal.Gui.ViewBase.View.yml) event
|
||||
- Disposes adornments, scrollbars, SubViews
|
||||
- Cleans up event handlers and resources
|
||||
|
||||
---
|
||||
|
||||
## Subsystems
|
||||
|
||||
### Commands
|
||||
|
||||
See the [Command Deep Dive](command.md) for complete details.
|
||||
|
||||
Views use a command pattern for handling input:
|
||||
|
||||
```csharp
|
||||
// Add a command the view supports
|
||||
view.AddCommand (Command.Accept, () =>
|
||||
{
|
||||
// Handle the Accept command
|
||||
return true;
|
||||
});
|
||||
|
||||
// Bind a key to the command
|
||||
view.KeyBindings.Add (Key.Enter, Command.Accept);
|
||||
|
||||
// Bind a mouse action to the command
|
||||
view.MouseBindings.Add (MouseFlags.Button1Clicked, Command.Select);
|
||||
```
|
||||
|
||||
### Input
|
||||
|
||||
#### Keyboard
|
||||
|
||||
See the [Keyboard Deep Dive](keyboard.md) for complete details.
|
||||
|
||||
The keyboard subsystem processes key presses through:
|
||||
|
||||
1. [View.KeyDown](~/api/Terminal.Gui.ViewBase.View.yml) event (cancellable)
|
||||
2. [View.OnKeyDown](~/api/Terminal.Gui.ViewBase.View.yml) virtual method
|
||||
3. [View.KeyBindings](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_KeyBindings) - Converts keys to commands
|
||||
4. Command handlers (registered via [View.AddCommand](~/api/Terminal.Gui.ViewBase.View.yml))
|
||||
5. [View.KeyUp](~/api/Terminal.Gui.ViewBase.View.yml) event
|
||||
|
||||
#### Mouse
|
||||
|
||||
See the [Mouse Deep Dive](mouse.md) for complete details.
|
||||
|
||||
The mouse subsystem processes mouse events through:
|
||||
|
||||
1. [View.MouseEvent](~/api/Terminal.Gui.ViewBase.View.yml) event (low-level)
|
||||
2. [View.OnMouseEvent](~/api/Terminal.Gui.ViewBase.View.yml) virtual method
|
||||
3. [View.MouseEnter](~/api/Terminal.Gui.ViewBase.View.yml) / [View.MouseLeave](~/api/Terminal.Gui.ViewBase.View.yml) events
|
||||
4. [View.MouseBindings](~/api/Terminal.Gui.ViewBase.View.yml) - Converts mouse actions to commands
|
||||
5. Command handlers
|
||||
6. [View.MouseClick](~/api/Terminal.Gui.ViewBase.View.yml) event (high-level)
|
||||
|
||||
### Layout
|
||||
|
||||
See the [Layout Deep Dive](layout.md) for complete details.
|
||||
|
||||
Layout is declarative using [Pos](~/api/Terminal.Gui.Pos.yml) and [Dim](~/api/Terminal.Gui.Dim.yml):
|
||||
|
||||
```csharp
|
||||
var label = new Label { Text = "Name:" };
|
||||
var textField = new TextField
|
||||
{
|
||||
X = Pos.Right(label) + 1,
|
||||
Y = Pos.Top(label),
|
||||
Width = Dim.Fill()
|
||||
};
|
||||
```
|
||||
|
||||
The layout system automatically:
|
||||
- Calculates Frame based on X, Y, Width, Height
|
||||
- Handles Adornment thickness
|
||||
- Calculates Viewport
|
||||
- Lays out SubViews recursively
|
||||
|
||||
### Drawing
|
||||
|
||||
See the [Drawing Deep Dive](drawing.md) for complete details.
|
||||
|
||||
Views draw themselves using viewport-relative coordinates:
|
||||
|
||||
```csharp
|
||||
protected override bool OnDrawingContent()
|
||||
{
|
||||
// Draw at viewport coordinates (0,0)
|
||||
Move(0, 0);
|
||||
SetAttribute(new Attribute(Color.White, Color.Blue));
|
||||
AddStr("Hello, Terminal.Gui!");
|
||||
|
||||
return true;
|
||||
}
|
||||
```
|
||||
|
||||
Key drawing concepts:
|
||||
- [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml) - For drawing lines with auto-joining
|
||||
- [Attribute](~/api/Terminal.Gui.Drawing.Attribute.yml) - Color and text style
|
||||
- [TextStyle](~/api/Terminal.Gui.Drawing.TextStyle.yml) - Bold, Italic, Underline, etc.
|
||||
- [Gradient](~/api/Terminal.Gui.Drawing.Gradient.yml) / [GradientFill](~/api/Terminal.Gui.Drawing.GradientFill.yml) - Color gradients
|
||||
|
||||
### Navigation
|
||||
|
||||
See the [Navigation Deep Dive](navigation.md) for complete details.
|
||||
|
||||
Navigation controls keyboard focus movement:
|
||||
|
||||
- [View.CanFocus](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_CanFocus) - Whether View can receive focus
|
||||
- [View.TabStop](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_TabStop) - [TabBehavior](~/api/Terminal.Gui.Input.TabBehavior.yml) (NoStop, TabStop, TabGroup)
|
||||
- [View.TabIndex](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_TabIndex) - Tab order within SuperView
|
||||
- [View.SetFocus](~/api/Terminal.Gui.ViewBase.View.yml) - Requests focus
|
||||
- [View.AdvanceFocus](~/api/Terminal.Gui.ViewBase.View.yml) - Moves focus to next/previous View
|
||||
|
||||
### Scrolling
|
||||
|
||||
See the [Scrolling Deep Dive](scrolling.md) for complete details.
|
||||
|
||||
Scrolling is built into every View:
|
||||
|
||||
```csharp
|
||||
// Set content size larger than viewport
|
||||
view.SetContentSize(new Size(100, 100));
|
||||
|
||||
// Scroll the content
|
||||
view.Viewport = view.Viewport with { Location = new Point(10, 10) };
|
||||
|
||||
// Or use helper methods
|
||||
view.ScrollVertical(5);
|
||||
view.ScrollHorizontal(3);
|
||||
|
||||
// Enable scrollbars
|
||||
view.VerticalScrollBar.Visible = true;
|
||||
view.HorizontalScrollBar.Visible = true;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common View Patterns
|
||||
|
||||
### Creating a Custom View
|
||||
|
||||
```csharp
|
||||
public class MyCustomView : View
|
||||
{
|
||||
public MyCustomView()
|
||||
{
|
||||
// Set up default size
|
||||
Width = Dim.Auto();
|
||||
Height = Dim.Auto();
|
||||
|
||||
// Can receive focus
|
||||
CanFocus = true;
|
||||
|
||||
// Add supported commands
|
||||
AddCommand(Command.Accept, HandleAccept);
|
||||
|
||||
// Configure key bindings
|
||||
KeyBindings.Add(Key.Enter, Command.Accept);
|
||||
}
|
||||
|
||||
protected override bool OnDrawingContent()
|
||||
{
|
||||
// Draw custom content using viewport coordinates
|
||||
Move(0, 0);
|
||||
SetAttributeForRole(VisualRole.Normal);
|
||||
AddStr("My custom content");
|
||||
|
||||
return true; // Handled
|
||||
}
|
||||
|
||||
private bool HandleAccept()
|
||||
{
|
||||
// Handle the Accept command
|
||||
// Raise events, update state, etc.
|
||||
return true; // Handled
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adding SubViews
|
||||
|
||||
```csharp
|
||||
var container = new View
|
||||
{
|
||||
Width = Dim.Fill(),
|
||||
Height = Dim.Fill()
|
||||
};
|
||||
|
||||
var button1 = new Button { Text = "OK", X = 2, Y = 2 };
|
||||
var button2 = new Button { Text = "Cancel", X = Pos.Right(button1) + 2, Y = 2 };
|
||||
|
||||
container.Add(button1, button2);
|
||||
```
|
||||
|
||||
### Using Adornments
|
||||
|
||||
```csharp
|
||||
var view = new View
|
||||
{
|
||||
BorderStyle = LineStyle.Double,
|
||||
Title = "My View"
|
||||
};
|
||||
|
||||
// Configure border
|
||||
view.Border.Thickness = new Thickness(1);
|
||||
view.Border.Settings = BorderSettings.Title;
|
||||
|
||||
// Add padding
|
||||
view.Padding.Thickness = new Thickness(1);
|
||||
|
||||
// Add margin
|
||||
view.Margin.Thickness = new Thickness(2);
|
||||
```
|
||||
|
||||
### Implementing Scrolling
|
||||
|
||||
```csharp
|
||||
var view = new View
|
||||
{
|
||||
Width = 40,
|
||||
Height = 20
|
||||
};
|
||||
|
||||
// Set content larger than viewport
|
||||
view.SetContentSize(new Size(100, 100));
|
||||
|
||||
// Enable scrollbars with auto-show
|
||||
view.VerticalScrollBar.AutoShow = true;
|
||||
view.HorizontalScrollBar.AutoShow = true;
|
||||
|
||||
// Add key bindings for scrolling
|
||||
view.KeyBindings.Add(Key.CursorUp, Command.ScrollUp);
|
||||
view.KeyBindings.Add(Key.CursorDown, Command.ScrollDown);
|
||||
view.KeyBindings.Add(Key.CursorLeft, Command.ScrollLeft);
|
||||
view.KeyBindings.Add(Key.CursorRight, Command.ScrollRight);
|
||||
|
||||
// Add command handlers
|
||||
view.AddCommand(Command.ScrollUp, () => { view.ScrollVertical(-1); return true; });
|
||||
view.AddCommand(Command.ScrollDown, () => { view.ScrollVertical(1); return true; });
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Modal Views
|
||||
|
||||
Views can either be Modal or Non-modal. Modal views take over all user input until the user closes the View. Examples of Modal Views are Toplevel, Dialog, and Wizard. Non-modal views can be used to create a new experience in your application, one where you would have a new top-level menu for example. Setting the `Modal` property on a View to `true` makes it modal.
|
||||
Views can run modally (exclusively capturing all input until closed). See [Toplevel](~/api/Terminal.Gui.Views.Toplevel.yml) for details.
|
||||
|
||||
To run any View (but especially Dialogs, Windows, or Toplevels) modally, invoke the `Application.Run` method on a Toplevel. Use the `Application.RequestStop()` method to terminate the modal execution.
|
||||
### Running a View Modally
|
||||
|
||||
```csharp
|
||||
var dialog = new Dialog
|
||||
{
|
||||
Title = "Confirmation",
|
||||
Width = Dim.Percent(50),
|
||||
Height = Dim.Percent(50)
|
||||
};
|
||||
|
||||
// Add content...
|
||||
var label = new Label { Text = "Are you sure?", X = Pos.Center(), Y = 1 };
|
||||
dialog.Add(label);
|
||||
|
||||
// Run modally - blocks until closed
|
||||
Application.Run(dialog);
|
||||
|
||||
// Dialog has been closed
|
||||
```
|
||||
|
||||
There is no return value from running modally, so the modal view must have a mechanism to indicate the reason the modal was closed. In the case above, the `okpressed` value is set to true if the user pressed or selected the `Ok` button.
|
||||
### Modal View Types
|
||||
|
||||
### Dialogs
|
||||
- **[Toplevel](~/api/Terminal.Gui.Views.Toplevel.yml)** - Base class for modal views, can fill entire screen
|
||||
- **[Window](~/api/Terminal.Gui.Views.Window.yml)** - Overlapped container with border and title
|
||||
- **[Dialog](~/api/Terminal.Gui.Views.Dialog.yml)** - Modal Window, centered with button support
|
||||
- **[Wizard](~/api/Terminal.Gui.Views.Wizard.yml)** - Multi-step modal dialog
|
||||
|
||||
[Dialogs](~/api/Terminal.Gui.Views.Dialog.yml) are Modal [Windows](~/api/Terminal.Gui.Views.Window.yml) that are centered in the middle of the screen and are intended to be used modally - that is, they run, and they are expected to return a result before resuming execution of the application.
|
||||
### Dialog Example
|
||||
|
||||
Dialogs expose an API for adding buttons and managing the layout such that buttons are at the bottom of the dialog (e.g. [`AddButton`](https://migueldeicaza.github.io/gui.cs/api/Terminal.Gui.Dialog.yml#Terminal_Gui_Dialog_AddButton_Terminal_Gui_Button_)).
|
||||
[Dialogs](~/api/Terminal.Gui.Views.Dialog.yml) are Modal [Windows](~/api/Terminal.Gui.Views.Window.yml) centered on screen:
|
||||
|
||||
Example:
|
||||
```csharp
|
||||
bool okpressed = false;
|
||||
var ok = new Button() { Title = "Ok" };
|
||||
var cancel = new Button() { Title = "Cancel" };
|
||||
var dialog = new Dialog () { Text = "Are you sure you want to quit?", Title = "Quit", Buttons = { ok, cancel } };
|
||||
bool okPressed = false;
|
||||
var ok = new Button { Text = "Ok" };
|
||||
ok.Accepting += (s, e) => { okPressed = true; Application.RequestStop(); };
|
||||
|
||||
var cancel = new Button { Text = "Cancel" };
|
||||
cancel.Accepting += (s, e) => Application.RequestStop();
|
||||
|
||||
var dialog = new Dialog
|
||||
{
|
||||
Title = "Quit",
|
||||
Width = 50,
|
||||
Height = 10
|
||||
};
|
||||
dialog.Add(new Label { Text = "Are you sure you want to quit?", X = Pos.Center(), Y = 2 });
|
||||
dialog.AddButton(ok);
|
||||
dialog.AddButton(cancel);
|
||||
|
||||
Application.Run(dialog);
|
||||
|
||||
if (okPressed)
|
||||
{
|
||||
// User clicked OK
|
||||
}
|
||||
```
|
||||
|
||||
Which will show something like this:
|
||||
Which displays:
|
||||
|
||||
```
|
||||
+- Quit -----------------------------------------------+
|
||||
| Are you sure you want to quit? |
|
||||
| |
|
||||
| [ Ok ] [ Cancel ] |
|
||||
+------------------------------------------------------+
|
||||
╔═ Quit ═══════════════════════════════════════════╗
|
||||
║ ║
|
||||
║ Are you sure you want to quit? ║
|
||||
║ ║
|
||||
║ ║
|
||||
║ ║
|
||||
║ [ Ok ] [ Cancel ] ║
|
||||
╚══════════════════════════════════════════════════╝
|
||||
```
|
||||
|
||||
### Wizards
|
||||
### Wizard Example
|
||||
|
||||
[Wizards](~/api/Terminal.Gui.Views.Wizard.yml) are Dialogs that let users step through a series of steps to complete a task.
|
||||
[Wizards](~/api/Terminal.Gui.Views.Wizard.yml) let users step through multiple pages:
|
||||
|
||||
```
|
||||
╔╡Gandolf - The last step╞════════════════════════════════════╗
|
||||
║ The wizard is complete! ║
|
||||
║☐ Enable Final Final Step ║
|
||||
║ Press the Finish ║
|
||||
║ button to continue. ║
|
||||
║ ║
|
||||
║ Pressing ESC will ║
|
||||
║ cancel the wizard. ║
|
||||
║ ║
|
||||
║ ║
|
||||
║─────────────────────────────────────────────────────────────║
|
||||
║⟦ Back ⟧ ⟦► Finish ◄⟧║
|
||||
╚═════════════════════════════════════════════════════════════╝
|
||||
```csharp
|
||||
var wizard = new Wizard { Title = "Setup Wizard" };
|
||||
|
||||
var step1 = new WizardStep { Title = "Welcome" };
|
||||
step1.Add(new Label { Text = "Welcome to the wizard!", X = 1, Y = 1 });
|
||||
|
||||
var step2 = new WizardStep { Title = "Configuration" };
|
||||
step2.Add(new TextField { X = 1, Y = 1, Width = 30 });
|
||||
|
||||
wizard.AddStep(step1);
|
||||
wizard.AddStep(step2);
|
||||
|
||||
Application.Run(wizard);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Application Concepts
|
||||
## Advanced Topics
|
||||
|
||||
* *TopLevel* - The v1 term used to describe a view that can have a MenuBar and/or StatusBar. In v2, we will delete the `TopLevel` class and ensure ANY View can have a menu bar and/or status bar (via `Adornments`).
|
||||
* NOTE: There will still be an `Application.Top` which is the [View](~/api/Terminal.Gui.ViewBase.View.yml) that is the root of the `Application`'s view hierarchy.
|
||||
### View Diagnostics
|
||||
|
||||
* *Runnable* - TBD
|
||||
[View.Diagnostics](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Diagnostics) - [ViewDiagnosticFlags](~/api/Terminal.Gui.ViewBase.ViewDiagnosticFlags.yml) for debugging:
|
||||
|
||||
* *Modal* - *Modal* - The term used when describing a [View](~/api/Terminal.Gui.Viewbase.View.yml) that was created using the `Application.Run(view)` or `Application.Run<T>` APIs. When a View is running as a modal, user input is restricted to just that View until `Application.Run` exits. A `Modal` View has its own `RunState`.
|
||||
* In v1, classes derived from `Dialog` were originally thought to only work modally. However, `Wizard` proved that a `Dialog`-based class can also work non-modally.
|
||||
* In v2, we will simplify the `Dialog` class, and let any class be run via `Applicaiton.Run`. The `Modal` property will be set by `Application.Run` so the class can detect it is running modally if it needs to.
|
||||
- `Ruler` - Shows a ruler around the View
|
||||
- `DrawIndicator` - Shows an animated indicator when drawing
|
||||
- `FramePadding` - Highlights the Frame with color
|
||||
|
||||
### View States
|
||||
|
||||
- [View.Enabled](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Enabled) - Whether the View is enabled
|
||||
- [View.Visible](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Visible) - Whether the View is visible
|
||||
- [View.CanFocus](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_CanFocus) - Whether the View can receive focus
|
||||
- [View.HasFocus](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HasFocus) - Whether the View currently has focus
|
||||
|
||||
### Shadow Effects
|
||||
|
||||
[View.ShadowStyle](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_ShadowStyle) - [ShadowStyle](~/api/Terminal.Gui.ViewBase.ShadowStyle.yml) for drop shadows:
|
||||
|
||||
```csharp
|
||||
view.ShadowStyle = ShadowStyle.Transparent;
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- **[Views Overview](views.md)** - Complete list of all built-in Views
|
||||
- **[Layout Deep Dive](layout.md)** - Detailed layout system documentation
|
||||
- **[Drawing Deep Dive](drawing.md)** - Drawing system and color management
|
||||
- **[Keyboard Deep Dive](keyboard.md)** - Keyboard input handling
|
||||
- **[Mouse Deep Dive](mouse.md)** - Mouse input handling
|
||||
- **[Navigation Deep Dive](navigation.md)** - Focus and navigation system
|
||||
- **[Scrolling Deep Dive](scrolling.md)** - Scrolling and viewport management
|
||||
- **[Command Deep Dive](command.md)** - Command pattern and bindings
|
||||
- **[Arrangement Deep Dive](arrangement.md)** - Movable and resizable views
|
||||
- **[Configuration Deep Dive](config.md)** - Configuration and persistence
|
||||
- **[Scheme Deep Dive](scheme.md)** - Color theming
|
||||
|
||||
@@ -1,102 +1,735 @@
|
||||
# View Layout Arrangement
|
||||
# View Arrangement Deep Dive
|
||||
|
||||
Terminal.Gui provides a feature of Layout known as **Arrangement**, which controls how the user can use the mouse and keyboard to arrange views and enables either **Tiled** or **Overlapped** layouts. Arrangement is a sub-topic of [Layout](layout.md).
|
||||
Terminal.Gui provides a powerful **Arrangement** system that enables users to interactively move and resize views using the keyboard and mouse. This system supports both **Tiled** and **Overlapped** layout modes, allowing for flexible UI organization.
|
||||
|
||||
## Arrangement Taxonomy & Lexicon
|
||||
See the [Layout Deep Dive](layout.md) for the broader layout system context.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Arrangement Modes](#arrangement-modes)
|
||||
- [Arrange Mode (Interactive)](#arrange-mode-interactive)
|
||||
- [Tiled vs Overlapped Layouts](#tiled-vs-overlapped-layouts)
|
||||
- [Movable Views](#movable-views)
|
||||
- [Resizable Views](#resizable-views)
|
||||
- [Creating Resizable Splitters](#creating-resizable-splitters)
|
||||
- [Modal Views](#modal-views)
|
||||
- [Runnable Views](#runnable-views)
|
||||
- [Examples](#examples)
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The [View.Arrangement](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Arrangement) property controls how users can arrange views within their [SuperView](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SuperView). The [ViewArrangement](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml) enum provides flags that can be combined to specify arrangement behavior.
|
||||
|
||||
### Arrangement Lexicon
|
||||
|
||||
[!INCLUDE [Arrangement Lexicon](~/includes/arrangement-lexicon.md)]
|
||||
|
||||
## Arrangement
|
||||
### ViewArrangement Flags
|
||||
|
||||
Describes the feature of [Layout](layout.md) which controls how the user can use the mouse and keyboard to arrange views and enables either **Tiled** or **Overlapped** layouts. The @Terminal.Gui.ViewBase.View.Arrangement property controls the arrangement behavior for each view.
|
||||
The [ViewArrangement](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml) enum supports these flags (can be combined):
|
||||
|
||||
## Arrange Mode
|
||||
- **Fixed** (0) - View cannot be moved or resized (default)
|
||||
- **Movable** (1) - View can be moved by the user
|
||||
- **LeftResizable** (2) - Left edge can be resized
|
||||
- **RightResizable** (4) - Right edge can be resized
|
||||
- **TopResizable** (8) - Top edge can be resized
|
||||
- **BottomResizable** (16) - Bottom edge can be resized
|
||||
- **Resizable** (30) - All edges can be resized (combines all resize flags)
|
||||
- **Overlapped** (32) - View overlaps other views (enables Z-order)
|
||||
|
||||
The Arrange Modes are set via the @Terminal.Gui.ViewBase.View.Arrangement property. When a user presses `Ctrl+F5` (configurable via the @Terminal.Gui.App.Application.ArrangeKey property) the application goes into **Arrange Mode**.
|
||||
---
|
||||
|
||||
In this mode, indicators are displayed on an arrangeable view indicating which aspect of the View can be arranged:
|
||||
- If @Terminal.Gui.ViewBase.ViewArrangement.Movable, a `◊` will be displayed in the top-left corner of the @Terminal.Gui.ViewBase.View.Border
|
||||
- If @Terminal.Gui.ViewBase.ViewArrangement.Resizable, pressing `Tab` (or `Shift+Tab`) will cycle to an indicator in the bottom-right corner of the Border
|
||||
## Arrangement Modes
|
||||
|
||||
The up/down/left/right cursor keys will act appropriately. `Esc`, `Ctrl+F5` or clicking outside of the Border will exit Arrange Mode.
|
||||
### Fixed (Default)
|
||||
|
||||
## Modal
|
||||
|
||||
A modal view is one that is run as an "application" via @Terminal.Gui.App.Application.Run(System.Func{System.Exception,System.Boolean},Terminal.Gui.Drivers.IConsoleDriver) where `Modal == true`.
|
||||
|
||||
`Dialog`, `MessageBox`, and `Wizard` are the prototypical examples. When run this way, there IS a `z-order` but it is highly-constrained: the modal view has a z-order of 1 and everything else is at 0.
|
||||
|
||||
## Movable
|
||||
|
||||
Describes a View that can be moved by the user using the keyboard or mouse. **Movable** is enabled on a per-View basis by setting the @Terminal.Gui.ViewBase.ViewArrangement.Movable flag on @Terminal.Gui.ViewBase.View.Arrangement.
|
||||
|
||||
Dragging on the top @Terminal.Gui.ViewBase.View.Border of a View will move such a view. Pressing `Ctrl+F5` will activate **Arrange Mode** letting the user move the view with the up/down/left/right cursor keys.
|
||||
|
||||
## Overlapped
|
||||
|
||||
A form of layout where SubViews of a View are visually arranged such that their Frames overlap. In Overlap view arrangements there is a Z-axis (Z-order) in addition to the X and Y dimension. The Z-order indicates which Views are shown above other views.
|
||||
|
||||
**Overlapped** is enabled on a per-View basis by setting the @Terminal.Gui.ViewBase.ViewArrangement.Overlapped flag on @Terminal.Gui.ViewBase.View.Arrangement.
|
||||
|
||||
## Resizable
|
||||
|
||||
Describes a View that can be sized by the user using the keyboard or mouse. **Resizable** is enabled on a per-View basis by setting the @Terminal.Gui.ViewBase.ViewArrangement.Resizable flag on @Terminal.Gui.ViewBase.View.Arrangement.
|
||||
|
||||
Dragging on the left, right, or bottom @Terminal.Gui.ViewBase.View.Border of a View will size that side of such a view. Pressing `Ctrl+F5` will activate **Arrange Mode** letting the user size the view with the up/down/left/right cursor keys.
|
||||
|
||||
## Tiled
|
||||
|
||||
A form of layout where SubViews of a View are visually arranged such that their Frames do not typically overlap. With **Tiled** views, there is no 'z-order` to the SubViews of a View.
|
||||
|
||||
In most use-cases, subviews do not overlap with each other (the exception being when it's done intentionally to create some visual effect). As a result, the default layout for most TUI apps is "tiled", and by default @Terminal.Gui.ViewBase.View.Arrangement is set to @Terminal.Gui.ViewBase.ViewArrangement.Fixed.
|
||||
|
||||
### Creating a Resizable Splitter
|
||||
|
||||
A common pattern in tiled layouts is to create a resizable splitter between two views. This can be achieved using the @Terminal.Gui.ViewBase.ViewArrangement.LeftResizable, @Terminal.Gui.ViewBase.ViewArrangement.RightResizable, @Terminal.Gui.ViewBase.ViewArrangement.TopResizable, or @Terminal.Gui.ViewBase.ViewArrangement.BottomResizable flags.
|
||||
|
||||
Here's an example of creating a horizontal resizable splitter between two views:
|
||||
Views with [ViewArrangement.Fixed](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml) cannot be moved or resized by the user:
|
||||
|
||||
```csharp
|
||||
var view = new View
|
||||
{
|
||||
Arrangement = ViewArrangement.Fixed // Default
|
||||
};
|
||||
```
|
||||
|
||||
### Movable
|
||||
|
||||
Views with [ViewArrangement.Movable](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml) can be dragged with the mouse or moved with keyboard:
|
||||
|
||||
```csharp
|
||||
var window = new Window
|
||||
{
|
||||
Title = "Movable Window",
|
||||
Arrangement = ViewArrangement.Movable
|
||||
};
|
||||
```
|
||||
|
||||
**User Interaction:**
|
||||
- **Mouse**: Drag the top [Border](~/api/Terminal.Gui.ViewBase.Border.yml)
|
||||
- **Keyboard**: Press `Ctrl+F5` to enter Arrange Mode, use arrow keys to move
|
||||
|
||||
### Resizable
|
||||
|
||||
Views with [ViewArrangement.Resizable](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml) can be resized by the user:
|
||||
|
||||
```csharp
|
||||
var window = new Window
|
||||
{
|
||||
Title = "Resizable Window",
|
||||
Arrangement = ViewArrangement.Resizable
|
||||
};
|
||||
```
|
||||
|
||||
**User Interaction:**
|
||||
- **Mouse**: Drag any border edge
|
||||
- **Keyboard**: Press `Ctrl+F5` to enter Arrange Mode, press `Tab` to cycle resize handles
|
||||
|
||||
### Movable and Resizable
|
||||
|
||||
Combine flags for full desktop-like experience:
|
||||
|
||||
```csharp
|
||||
var window = new Window
|
||||
{
|
||||
Title = "Movable and Resizable",
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable
|
||||
};
|
||||
```
|
||||
|
||||
**Note:** When both `Movable` and `Resizable` are set, the top edge cannot be resized (Movable takes precedence).
|
||||
|
||||
### Individual Edge Resizing
|
||||
|
||||
For fine-grained control, use individual edge flags:
|
||||
|
||||
```csharp
|
||||
// Only bottom edge resizable
|
||||
var view = new View
|
||||
{
|
||||
Arrangement = ViewArrangement.BottomResizable
|
||||
};
|
||||
|
||||
// Left and right edges resizable
|
||||
var view2 = new View
|
||||
{
|
||||
Arrangement = ViewArrangement.LeftResizable | ViewArrangement.RightResizable
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Arrange Mode (Interactive)
|
||||
|
||||
**Arrange Mode** is an interactive mode for arranging views using the keyboard. It is activated by pressing the **Arrange Key** (default: `Ctrl+F5`, configurable via [Application.ArrangeKey](~/api/Terminal.Gui.App.Application.yml#Terminal_Gui_App_Application_ArrangeKey)).
|
||||
|
||||
### Entering Arrange Mode
|
||||
|
||||
When the user presses `Ctrl+F5`:
|
||||
|
||||
1. Visual indicators appear on arrangeable views
|
||||
2. If [ViewArrangement.Movable](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml), a move indicator (`◊`) appears in top-left corner
|
||||
3. If [ViewArrangement.Resizable](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml), pressing `Tab` cycles to resize indicators
|
||||
4. Arrow keys move or resize the view
|
||||
5. Press `Esc`, `Ctrl+F5`, or click outside to exit
|
||||
|
||||
### Arrange Mode Indicators
|
||||
|
||||
The [Border](~/api/Terminal.Gui.ViewBase.Border.yml) shows visual indicators based on arrangement options:
|
||||
|
||||
| Arrangement Flag | Indicator | Location |
|
||||
|------------------|-----------|----------|
|
||||
| Movable | `◊` (Glyphs.Move) | Top-left corner |
|
||||
| Resizable | `⇲` (Glyphs.SizeBottomRight) | Bottom-right corner |
|
||||
| LeftResizable | `↔` (Glyphs.SizeHorizontal) | Left edge, centered |
|
||||
| RightResizable | `↔` (Glyphs.SizeHorizontal) | Right edge, centered |
|
||||
| TopResizable | `↕` (Glyphs.SizeVertical) | Top edge, centered |
|
||||
| BottomResizable | `↕` (Glyphs.SizeVertical) | Bottom edge, centered |
|
||||
|
||||
### Keyboard Controls in Arrange Mode
|
||||
|
||||
- **Arrow Keys** - Move or resize based on active mode
|
||||
- **Tab** - Cycle between move and resize modes (if both available)
|
||||
- **Shift+Tab** - Cycle backwards
|
||||
- **Esc** - Exit Arrange Mode
|
||||
- **Ctrl+F5** - Exit Arrange Mode
|
||||
|
||||
### Requirements for Arrangement
|
||||
|
||||
For a View to be arrangeable:
|
||||
|
||||
1. Must be part of a [SuperView](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SuperView)
|
||||
2. Position and dimensions must be independent of other SubViews
|
||||
3. Must have [View.Arrangement](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Arrangement) flags set
|
||||
4. Typically needs a [Border](~/api/Terminal.Gui.ViewBase.Border.yml) for mouse interaction
|
||||
|
||||
---
|
||||
|
||||
## Tiled vs Overlapped Layouts
|
||||
|
||||
### Tiled Layout
|
||||
|
||||
In **Tiled** layouts, SubViews typically do not overlap. There is no Z-order; all views are at the same layer.
|
||||
|
||||
```csharp
|
||||
var container = new View { Arrangement = ViewArrangement.Fixed };
|
||||
|
||||
var view1 = new View { X = 0, Y = 0, Width = 20, Height = 10 };
|
||||
var view2 = new View { X = 21, Y = 0, Width = 20, Height = 10 };
|
||||
|
||||
container.Add(view1, view2);
|
||||
// Views are side-by-side, non-overlapping
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- Default mode for most TUI applications
|
||||
- Views use [Pos](~/api/Terminal.Gui.Pos.yml) and [Dim](~/api/Terminal.Gui.Dim.yml) for relative positioning
|
||||
- No Z-order management needed
|
||||
- More predictable layout behavior
|
||||
|
||||
### Overlapped Layout
|
||||
|
||||
In **Overlapped** layouts, SubViews can overlap with Z-order determining visual stacking.
|
||||
|
||||
Enable overlapped mode with [ViewArrangement.Overlapped](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml):
|
||||
|
||||
```csharp
|
||||
var container = new View
|
||||
{
|
||||
Arrangement = ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
var window1 = new Window
|
||||
{
|
||||
X = 5, Y = 3, Width = 40, Height = 15,
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
var window2 = new Window
|
||||
{
|
||||
X = 15, Y = 8, Width = 40, Height = 15,
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
container.Add(window1, window2);
|
||||
// window2 will overlap window1
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- Z-order determined by SubViews collection order
|
||||
- Later views appear above earlier views
|
||||
- Tab navigation constrained to current overlapped view
|
||||
- Use `Ctrl+Tab` / `Ctrl+Shift+Tab` to switch between overlapped views
|
||||
|
||||
---
|
||||
|
||||
## Movable Views
|
||||
|
||||
Views with [ViewArrangement.Movable](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml) can be repositioned by the user.
|
||||
|
||||
### Enabling Movable
|
||||
|
||||
```csharp
|
||||
var window = new Window
|
||||
{
|
||||
Title = "Drag Me!",
|
||||
X = 10,
|
||||
Y = 5,
|
||||
Width = 40,
|
||||
Height = 15,
|
||||
Arrangement = ViewArrangement.Movable,
|
||||
BorderStyle = LineStyle.Single
|
||||
};
|
||||
```
|
||||
|
||||
### Moving with Mouse
|
||||
|
||||
- **Click and drag** the top [Border](~/api/Terminal.Gui.ViewBase.Border.yml) to move the view
|
||||
- The view's [Frame](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Frame) updates as it moves
|
||||
- Release the mouse to complete the move
|
||||
|
||||
### Moving with Keyboard
|
||||
|
||||
1. Press `Ctrl+F5` to enter **Arrange Mode**
|
||||
2. A move indicator (`◊`) appears in the top-left corner
|
||||
3. Use **arrow keys** to move the view
|
||||
4. Press `Esc` or `Ctrl+F5` to exit Arrange Mode
|
||||
|
||||
---
|
||||
|
||||
## Resizable Views
|
||||
|
||||
Views with resizable flags can be resized by the user on specific edges.
|
||||
|
||||
### All Edges Resizable
|
||||
|
||||
```csharp
|
||||
var window = new Window
|
||||
{
|
||||
Title = "Resize Me!",
|
||||
Arrangement = ViewArrangement.Resizable,
|
||||
BorderStyle = LineStyle.Single
|
||||
};
|
||||
```
|
||||
|
||||
### Specific Edge Resizable
|
||||
|
||||
```csharp
|
||||
// Only right and bottom edges resizable
|
||||
var view = new View
|
||||
{
|
||||
Arrangement = ViewArrangement.RightResizable | ViewArrangement.BottomResizable,
|
||||
BorderStyle = LineStyle.Single
|
||||
};
|
||||
```
|
||||
|
||||
### Resizing with Mouse
|
||||
|
||||
- **Click and drag** any enabled border edge
|
||||
- Resize indicators appear on hover
|
||||
- The view's [Width](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Width) and [Height](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Height) update
|
||||
|
||||
### Resizing with Keyboard
|
||||
|
||||
1. Press `Ctrl+F5` to enter **Arrange Mode**
|
||||
2. Press `Tab` to cycle to resize mode
|
||||
3. Resize indicator (`⇲`) appears
|
||||
4. Use **arrow keys** to resize
|
||||
5. Press `Esc` or `Ctrl+F5` to exit
|
||||
|
||||
---
|
||||
|
||||
## Creating Resizable Splitters
|
||||
|
||||
A common pattern in tiled layouts is creating a resizable splitter between two panes.
|
||||
|
||||
### Horizontal Splitter (Left/Right Panes)
|
||||
|
||||
```csharp
|
||||
// Create left pane that fills remaining space
|
||||
View leftPane = new ()
|
||||
{
|
||||
X = 0,
|
||||
Y = 0,
|
||||
Width = Dim.Fill (Dim.Func (_ => rightPane.Frame.Width)),
|
||||
Height = Dim.Fill (),
|
||||
CanFocus = true
|
||||
Width = Dim.Fill(Dim.Func(_ => rightPane.Frame.Width)),
|
||||
Height = Dim.Fill(),
|
||||
BorderStyle = LineStyle.Single
|
||||
};
|
||||
|
||||
// Create right pane with resizable left border (acts as splitter)
|
||||
View rightPane = new ()
|
||||
{
|
||||
X = Pos.Right (leftPane) - 1,
|
||||
X = Pos.Right(leftPane) - 1,
|
||||
Y = 0,
|
||||
Width = Dim.Fill (),
|
||||
Height = Dim.Fill (),
|
||||
Width = Dim.Fill(),
|
||||
Height = Dim.Fill(),
|
||||
Arrangement = ViewArrangement.LeftResizable,
|
||||
BorderStyle = LineStyle.Single,
|
||||
SuperViewRendersLineCanvas = true,
|
||||
CanFocus = true
|
||||
SuperViewRendersLineCanvas = true
|
||||
};
|
||||
rightPane.Border!.Thickness = new (1, 0, 0, 0); // Only left border
|
||||
rightPane.Border.Thickness = new Thickness(1, 0, 0, 0); // Only left border
|
||||
|
||||
container.Add (leftPane, rightPane);
|
||||
container.Add(leftPane, rightPane);
|
||||
```
|
||||
|
||||
In this example:
|
||||
- The `rightPane` has `ViewArrangement.LeftResizable` which makes its left border draggable
|
||||
- The left border acts as a splitter that users can drag to resize both panes
|
||||
- The `leftPane` uses `Dim.Fill` with a function that subtracts the `rightPane`'s width to automatically fill the remaining space
|
||||
- The `rightPane` has `SuperViewRendersLineCanvas = true` to ensure the border is rendered properly
|
||||
- Only the left border is shown by setting `Border.Thickness` to `(1, 0, 0, 0)`
|
||||
**How it works:**
|
||||
- `rightPane` has [ViewArrangement.LeftResizable](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml) - its left border is draggable
|
||||
- `leftPane` uses [Dim.Fill](~/api/Terminal.Gui.Dim.yml) with a function to fill remaining space
|
||||
- `SuperViewRendersLineCanvas = true` ensures proper line rendering
|
||||
- Only the left border is visible, acting as the splitter
|
||||
|
||||
For a vertical splitter (top and bottom panes), use `ViewArrangement.TopResizable` or `ViewArrangement.BottomResizable` instead.
|
||||
### Vertical Splitter (Top/Bottom Panes)
|
||||
|
||||
## Runnable
|
||||
```csharp
|
||||
View topPane = new ()
|
||||
{
|
||||
X = 0,
|
||||
Y = 0,
|
||||
Width = Dim.Fill(),
|
||||
Height = Dim.Fill(Dim.Func(_ => bottomPane.Frame.Height)),
|
||||
BorderStyle = LineStyle.Single
|
||||
};
|
||||
|
||||
Today, Overlapped and Runnable are intrinsically linked. A runnable view is one where `Application.Run(Toplevel)` is called. Each *Runnable* view where (`Modal == false`) has it's own `RunState` and is, effectively, a self-contained "application".
|
||||
View bottomPane = new ()
|
||||
{
|
||||
X = 0,
|
||||
Y = Pos.Bottom(topPane) - 1,
|
||||
Width = Dim.Fill(),
|
||||
Height = Dim.Fill(),
|
||||
Arrangement = ViewArrangement.TopResizable,
|
||||
BorderStyle = LineStyle.Single,
|
||||
SuperViewRendersLineCanvas = true
|
||||
};
|
||||
bottomPane.Border.Thickness = new Thickness(1, 0, 0, 0); // Only top border
|
||||
|
||||
`Application.Run()` non-preemptively dispatches events (screen, keyboard, mouse, Timers, and Idle handlers) to the associated `Toplevel`. It is possible for such a `Toplevel` to create a thread and call `Application.Run(someotherToplevel)` on that thread, enabling pre-emptive user-interface multitasking (`BackgroundWorkerCollection` does this).
|
||||
container.Add(topPane, bottomPane);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Modal Views
|
||||
|
||||
**Modal** views run as exclusive applications that capture all user input until closed.
|
||||
|
||||
See the [Multitasking Deep Dive](multitasking.md) for complete details on modal execution.
|
||||
|
||||
### What Makes a View Modal
|
||||
|
||||
A view is modal when:
|
||||
- Run via [Application.Run](~/api/Terminal.Gui.App.Application.yml#Terminal_Gui_App_Application_Run_Terminal_Gui_Views_Toplevel_System_Func_System_Exception_System_Boolean__)
|
||||
- [Toplevel.Modal](~/api/Terminal.Gui.Views.Toplevel.yml#Terminal_Gui_Views_Toplevel_Modal) = `true`
|
||||
|
||||
### Modal Characteristics
|
||||
|
||||
- **Exclusive Input** - All keyboard and mouse input goes to the modal view
|
||||
- **Constrained Z-Order** - Modal view has Z-order of 1, everything else at 0
|
||||
- **Blocks Execution** - `Application.Run` blocks until [Application.RequestStop](~/api/Terminal.Gui.App.Application.yml#Terminal_Gui_App_Application_RequestStop_Terminal_Gui_Views_Toplevel_) is called
|
||||
- **Own RunState** - Each modal view has its own [RunState](~/api/Terminal.Gui.App.RunState.yml)
|
||||
|
||||
### Modal View Types
|
||||
|
||||
- [Dialog](~/api/Terminal.Gui.Views.Dialog.yml) - Centered modal window with button support
|
||||
- [MessageBox](~/api/Terminal.Gui.Views.MessageBox.yml) - Simple message dialogs
|
||||
- [Wizard](~/api/Terminal.Gui.Views.Wizard.yml) - Multi-step modal dialogs
|
||||
|
||||
### Modal Example
|
||||
|
||||
```csharp
|
||||
var dialog = new Dialog
|
||||
{
|
||||
Title = "Confirm",
|
||||
Width = 40,
|
||||
Height = 10
|
||||
};
|
||||
|
||||
var label = new Label
|
||||
{
|
||||
Text = "Are you sure?",
|
||||
X = Pos.Center(),
|
||||
Y = 2
|
||||
};
|
||||
dialog.Add(label);
|
||||
|
||||
var ok = new Button { Text = "OK" };
|
||||
ok.Accepting += (s, e) => Application.RequestStop();
|
||||
dialog.AddButton(ok);
|
||||
|
||||
// Run modally - blocks until closed
|
||||
Application.Run(dialog);
|
||||
|
||||
// Dialog has been closed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Runnable Views
|
||||
|
||||
**Runnable** views are those run via [Application.Run](~/api/Terminal.Gui.App.Application.yml). Each non-modal Runnable view operates as a self-contained "application" with its own [RunState](~/api/Terminal.Gui.App.RunState.yml).
|
||||
|
||||
See the [Multitasking Deep Dive](multitasking.md) for complete details.
|
||||
|
||||
### Non-Modal Runnable Views
|
||||
|
||||
```csharp
|
||||
var toplevel = new Toplevel
|
||||
{
|
||||
Modal = false // Non-modal
|
||||
};
|
||||
|
||||
// Runs as independent application
|
||||
Application.Run(toplevel);
|
||||
```
|
||||
|
||||
**Characteristics:**
|
||||
- Has its own `RunState`
|
||||
- Events dispatched independently
|
||||
- Can run on separate threads
|
||||
- See `BackgroundWorkerCollection` for multi-threaded examples
|
||||
|
||||
### Modal vs Non-Modal Runnable
|
||||
|
||||
| Aspect | Modal | Non-Modal |
|
||||
|--------|-------|-----------|
|
||||
| Input | Exclusive | Shared |
|
||||
| Z-Order | Constrained (1 vs 0) | Full Z-order support |
|
||||
| Blocks Execution | Yes | No |
|
||||
| Use Case | Dialogs, confirmations | Multi-window apps |
|
||||
|
||||
---
|
||||
|
||||
## Tiled vs Overlapped Layouts
|
||||
|
||||
### Tiled Layout (Default)
|
||||
|
||||
SubViews do not overlap, positioned side-by-side or top-to-bottom:
|
||||
|
||||
```csharp
|
||||
var container = new View();
|
||||
|
||||
var left = new View
|
||||
{
|
||||
X = 0,
|
||||
Y = 0,
|
||||
Width = Dim.Percent(50),
|
||||
Height = Dim.Fill()
|
||||
};
|
||||
|
||||
var right = new View
|
||||
{
|
||||
X = Pos.Right(left),
|
||||
Y = 0,
|
||||
Width = Dim.Fill(),
|
||||
Height = Dim.Fill()
|
||||
};
|
||||
|
||||
container.Add(left, right);
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Simpler layout logic
|
||||
- No Z-order management
|
||||
- More predictable behavior
|
||||
- Standard for most TUI applications
|
||||
|
||||
### Overlapped Layout
|
||||
|
||||
SubViews can overlap with Z-order determining which is on top:
|
||||
|
||||
```csharp
|
||||
var container = new View
|
||||
{
|
||||
Arrangement = ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
var window1 = new Window
|
||||
{
|
||||
X = 5,
|
||||
Y = 3,
|
||||
Width = 40,
|
||||
Height = 15,
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
var window2 = new Window
|
||||
{
|
||||
X = 15,
|
||||
Y = 8,
|
||||
Width = 40,
|
||||
Height = 15,
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
container.Add(window1, window2);
|
||||
// window2 appears on top of window1
|
||||
```
|
||||
|
||||
**Z-Order:**
|
||||
- Order in [View.SubViews](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SubViews) determines Z-order
|
||||
- Later views appear above earlier views
|
||||
- Use [View.BringSubviewToFront](~/api/Terminal.Gui.ViewBase.View.yml) to change Z-order
|
||||
|
||||
**Navigation:**
|
||||
- `Tab` / `Shift+Tab` - Navigate within current overlapped view
|
||||
- `Ctrl+Tab` (`Ctrl+PageDown`) - Switch to next overlapped view
|
||||
- `Ctrl+Shift+Tab` (`Ctrl+PageUp`) - Switch to previous overlapped view
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Movable and Resizable Window
|
||||
|
||||
```csharp
|
||||
using Terminal.Gui;
|
||||
|
||||
Application.Init();
|
||||
|
||||
var window = new Window
|
||||
{
|
||||
Title = "Drag and Resize Me! (Ctrl+F5 for keyboard mode)",
|
||||
X = Pos.Center(),
|
||||
Y = Pos.Center(),
|
||||
Width = 50,
|
||||
Height = 15,
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable,
|
||||
BorderStyle = LineStyle.Double
|
||||
};
|
||||
|
||||
var label = new Label
|
||||
{
|
||||
Text = "Try dragging the border with mouse\nor press Ctrl+F5!",
|
||||
X = Pos.Center(),
|
||||
Y = Pos.Center()
|
||||
};
|
||||
window.Add(label);
|
||||
|
||||
Application.Run(window);
|
||||
Application.Shutdown();
|
||||
```
|
||||
|
||||
### Example 2: Horizontal Resizable Splitter
|
||||
|
||||
```csharp
|
||||
Application.Init();
|
||||
|
||||
var top = new Toplevel();
|
||||
|
||||
var leftPane = new FrameView
|
||||
{
|
||||
Title = "Left Pane",
|
||||
X = 0,
|
||||
Y = 0,
|
||||
Width = Dim.Fill(Dim.Func(_ => rightPane.Frame.Width)),
|
||||
Height = Dim.Fill()
|
||||
};
|
||||
|
||||
var rightPane = new FrameView
|
||||
{
|
||||
Title = "Right Pane (drag left edge)",
|
||||
X = Pos.Right(leftPane) - 1,
|
||||
Y = 0,
|
||||
Width = Dim.Fill(),
|
||||
Height = Dim.Fill(),
|
||||
Arrangement = ViewArrangement.LeftResizable,
|
||||
SuperViewRendersLineCanvas = true
|
||||
};
|
||||
rightPane.Border.Thickness = new Thickness(1, 0, 0, 0);
|
||||
|
||||
top.Add(leftPane, rightPane);
|
||||
|
||||
Application.Run(top);
|
||||
Application.Shutdown();
|
||||
```
|
||||
|
||||
### Example 3: Overlapped Windows
|
||||
|
||||
```csharp
|
||||
Application.Init();
|
||||
|
||||
var desktop = new Toplevel
|
||||
{
|
||||
Arrangement = ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
var window1 = new Window
|
||||
{
|
||||
Title = "Window 1",
|
||||
X = 5,
|
||||
Y = 3,
|
||||
Width = 40,
|
||||
Height = 12,
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable | ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
var window2 = new Window
|
||||
{
|
||||
Title = "Window 2 (overlaps Window 1)",
|
||||
X = 15,
|
||||
Y = 8,
|
||||
Width = 40,
|
||||
Height = 12,
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable | ViewArrangement.Overlapped
|
||||
};
|
||||
|
||||
desktop.Add(window1, window2);
|
||||
|
||||
Application.Run(desktop);
|
||||
Application.Shutdown();
|
||||
```
|
||||
|
||||
### Example 4: Custom Arrange Key
|
||||
|
||||
```csharp
|
||||
using Terminal.Gui;
|
||||
using Terminal.Gui.Configuration;
|
||||
|
||||
// Change the arrange key
|
||||
Application.ArrangeKey = Key.F2;
|
||||
|
||||
var window = new Window
|
||||
{
|
||||
Title = "Press F2 to enter arrange mode",
|
||||
Arrangement = ViewArrangement.Movable | ViewArrangement.Resizable
|
||||
};
|
||||
|
||||
Application.Run(window);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Constraints and Limitations
|
||||
|
||||
Arrangement only works when:
|
||||
|
||||
1. **View has a SuperView** - Root views cannot be arranged
|
||||
2. **Independent Position/Size** - Views with [Pos.Align](~/api/Terminal.Gui.Pos.yml) or complex [Dim](~/api/Terminal.Gui.Dim.yml) constraints may not resize properly
|
||||
3. **Border Required** - Mouse-based arrangement requires a visible [Border](~/api/Terminal.Gui.ViewBase.Border.yml)
|
||||
|
||||
### SuperViewRendersLineCanvas
|
||||
|
||||
When creating splitters, set [View.SuperViewRendersLineCanvas](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_SuperViewRendersLineCanvas) = `true`:
|
||||
|
||||
```csharp
|
||||
rightPane.SuperViewRendersLineCanvas = true;
|
||||
```
|
||||
|
||||
This ensures [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml) properly handles line intersections at borders.
|
||||
|
||||
### Z-Order Management
|
||||
|
||||
For overlapped views, manage Z-order with:
|
||||
|
||||
```csharp
|
||||
// Bring a view to the front
|
||||
container.BringSubviewToFront(window1);
|
||||
|
||||
// Send a view to the back
|
||||
container.SendSubviewToBack(window2);
|
||||
|
||||
// Check current order
|
||||
int index = container.SubViews.IndexOf(window1);
|
||||
```
|
||||
|
||||
### Arrangement Events
|
||||
|
||||
Monitor arrangement changes by handling layout events:
|
||||
|
||||
```csharp
|
||||
view.FrameChanged += (s, e) =>
|
||||
{
|
||||
Console.WriteLine($"View moved/resized to {e.NewValue}");
|
||||
};
|
||||
|
||||
view.LayoutComplete += (s, e) =>
|
||||
{
|
||||
// Layout has completed after arrangement change
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- **[Layout Deep Dive](layout.md)** - Overall layout system
|
||||
- **[View Deep Dive](View.md)** - View base class
|
||||
- **[Multitasking Deep Dive](multitasking.md)** - Modal and runnable views
|
||||
- **[Drawing Deep Dive](drawing.md)** - LineCanvas and borders
|
||||
- **[Configuration Deep Dive](config.md)** - Configuring Application.ArrangeKey
|
||||
|
||||
### API Reference
|
||||
|
||||
- [View.Arrangement](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Arrangement)
|
||||
- [ViewArrangement](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml)
|
||||
- [Border](~/api/Terminal.Gui.ViewBase.Border.yml)
|
||||
- [Application.ArrangeKey](~/api/Terminal.Gui.App.Application.yml#Terminal_Gui_App_Application_ArrangeKey)
|
||||
- [Toplevel.Modal](~/api/Terminal.Gui.Views.Toplevel.yml#Terminal_Gui_Views_Toplevel_Modal)
|
||||
|
||||
### UICatalog Examples
|
||||
|
||||
The UICatalog application demonstrates arrangement:
|
||||
|
||||
- **Arrangement Editor** - Interactive arrangement demonstration
|
||||
- **Overlapped** scenario - Shows overlapped window management
|
||||
- **Splitter** examples - Various splitter configurations
|
||||
|
||||
1170
docfx/docs/config.md
1170
docfx/docs/config.md
File diff suppressed because it is too large
Load Diff
@@ -18,17 +18,26 @@ This architectural shift has resulted in the removal of thousands of lines of re
|
||||
## Modern Look & Feel - Technical Details
|
||||
|
||||
### TrueColor Support
|
||||
- **Implementation**: v2 introduces 24-bit color support by extending the @Terminal.Gui.Drawing.Attribute class to handle RGB values, with fallback to 16-color mode for older terminals. This is evident in the @Terminal.Gui.Drivers.IConsoleDriver implementations, which now map colors to the appropriate terminal escape sequences.
|
||||
- **Impact**: Developers can now use a full spectrum of colors without manual palette management, as seen in v1. The @Terminal.Gui.Drawing.Color struct in v2 supports direct RGB input, and drivers handle the translation to terminal capabilities via [IConsoleDriver.SupportsTrueColor](~/api/Terminal.Gui.Drivers.IConsoleDriver.yml#Terminal_Gui_Drivers_IConsoleDriver_SupportsTrueColor).
|
||||
|
||||
See the [Drawing Deep Dive](drawing.md) for complete details on the color system.
|
||||
|
||||
- **Implementation**: v2 introduces 24-bit color support by extending the [Attribute](~/api/Terminal.Gui.Drawing.Attribute.yml) class to handle RGB values, with fallback to 16-color mode for older terminals. This is evident in the [IConsoleDriver](~/api/Terminal.Gui.Drivers.IConsoleDriver.yml) implementations, which now map colors to the appropriate terminal escape sequences.
|
||||
- **Impact**: Developers can now use a full spectrum of colors without manual palette management, as seen in v1. The [Color](~/api/Terminal.Gui.Drawing.Color.yml) struct in v2 supports direct RGB input, and drivers handle the translation to terminal capabilities via [IConsoleDriver.SupportsTrueColor](~/api/Terminal.Gui.Drivers.IConsoleDriver.yml#Terminal_Gui_Drivers_IConsoleDriver_SupportsTrueColor).
|
||||
- **Usage**: See the [ColorPicker](~/api/Terminal.Gui.Views.ColorPicker.yml) view for an example of how TrueColor is leveraged to provide a rich color selection UI.
|
||||
|
||||
### Enhanced Borders and Padding (Adornments)
|
||||
- **Implementation**: v2 introduces a new @Terminal.Gui.ViewBase.Adornment class hierarchy, with @Terminal.Gui.ViewBase.Margin, @Terminal.Gui.ViewBase.Border, and @Terminal.Gui.ViewBase.Padding as distinct view-like entities that wrap content. This is a significant departure from v1, where borders were often hardcoded or required custom drawing.
|
||||
- **Code Change**: In v1, @Terminal.Gui.ViewBase.View had rudimentary border support via properties like `BorderStyle`. In v2, @Terminal.Gui.ViewBase.View has a @Terminal.Gui.ViewBase.View.Border property of type @Terminal.Gui.ViewBase.Border, which is itself a configurable entity with properties like @Terminal.Gui.Drawing.Thickness, [Border.LineStyle](~/api/Terminal.Gui.ViewBase.Border.yml#Terminal_Gui_ViewBase_Border_LineStyle), and [Border.Settings](~/api/Terminal.Gui.ViewBase.Border.yml#Terminal_Gui_ViewBase_Border_Settings).
|
||||
|
||||
See the [Layout Deep Dive](layout.md) for complete details on the adornments system.
|
||||
|
||||
- **Implementation**: v2 introduces a new [Adornment](~/api/Terminal.Gui.ViewBase.Adornment.yml) class hierarchy, with [Margin](~/api/Terminal.Gui.ViewBase.Margin.yml), [Border](~/api/Terminal.Gui.ViewBase.Border.yml), and [Padding](~/api/Terminal.Gui.ViewBase.Padding.yml) as distinct view-like entities that wrap content. This is a significant departure from v1, where borders were often hardcoded or required custom drawing.
|
||||
- **Code Change**: In v1, [View](~/api/Terminal.Gui.ViewBase.View.yml) had rudimentary border support via properties like `BorderStyle`. In v2, [View](~/api/Terminal.Gui.ViewBase.View.yml) has a [View.Border](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Border) property of type [Border](~/api/Terminal.Gui.ViewBase.Border.yml), which is itself a configurable entity with properties like [Thickness](~/api/Terminal.Gui.Drawing.Thickness.yml), [Border.LineStyle](~/api/Terminal.Gui.ViewBase.Border.yml#Terminal_Gui_ViewBase_Border_LineStyle), and [Border.Settings](~/api/Terminal.Gui.ViewBase.Border.yml#Terminal_Gui_ViewBase_Border_Settings).
|
||||
- **Impact**: This allows for consistent border rendering across all views and simplifies custom view development by providing a reusable adornment framework.
|
||||
|
||||
### User Configurable Color Themes and Text Styles
|
||||
- **Implementation**: v2 adds a @Terminal.Gui.Configuration.ConfigurationManager that supports loading and saving color schemes from configuration files. Themes are applied via @Terminal.Gui.Drawing.Scheme objects, which can be customized per view or globally. Each @Terminal.Gui.Drawing.Attribute in a @Terminal.Gui.Drawing.Scheme now includes a [TextStyle](~/api/Terminal.Gui.Drawing.TextStyle.yml) property supporting Bold, Italic, Underline, Strikethrough, Blink, Reverse, and Faint text styles.
|
||||
|
||||
See the [Configuration Deep Dive](config.md) and [Scheme Deep Dive](scheme.md) for complete details.
|
||||
|
||||
- **Implementation**: v2 adds a [ConfigurationManager](~/api/Terminal.Gui.Configuration.ConfigurationManager.yml) that supports loading and saving color schemes from configuration files. Themes are applied via [Scheme](~/api/Terminal.Gui.Drawing.Scheme.yml) objects, which can be customized per view or globally. Each [Attribute](~/api/Terminal.Gui.Drawing.Attribute.yml) in a [Scheme](~/api/Terminal.Gui.Drawing.Scheme.yml) now includes a [TextStyle](~/api/Terminal.Gui.Drawing.TextStyle.yml) property supporting Bold, Italic, Underline, Strikethrough, Blink, Reverse, and Faint text styles.
|
||||
- **Impact**: Unlike v1, where color schemes were static or required manual override, v2 enables end-users to personalize not just colors but also text styling (bold, italic, underline, etc.) without code changes, significantly enhancing accessibility and user preference support.
|
||||
|
||||
### Enhanced Unicode/Wide Character Support
|
||||
@@ -36,14 +45,17 @@ This architectural shift has resulted in the removal of thousands of lines of re
|
||||
- **Impact**: This fixes v1 issues where wide characters (e.g., CJK scripts) could break layout or input handling, making Terminal.Gui v2 suitable for international applications.
|
||||
|
||||
### LineCanvas
|
||||
|
||||
See the [Drawing Deep Dive](drawing.md) for complete details on LineCanvas and the drawing system.
|
||||
|
||||
- **Implementation**: A new [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml) class provides a drawing API for creating lines and shapes using box-drawing characters. It includes logic for auto-joining lines at intersections, selecting appropriate glyphs dynamically.
|
||||
- **Code Example**: In v2, [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml) is used internally by views like @Terminal.Gui.ViewBase.Border and @Terminal.Gui.Views.Line to draw clean, connected lines, a feature absent in v1.
|
||||
- **Code Example**: In v2, [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml) is used internally by views like [Border](~/api/Terminal.Gui.ViewBase.Border.yml) and [Line](~/api/Terminal.Gui.Views.Line.yml) to draw clean, connected lines, a feature absent in v1.
|
||||
- **Impact**: Developers can create complex diagrams or UI elements with minimal effort, improving the visual fidelity of terminal applications.
|
||||
|
||||
## Simplified API - Under the Hood
|
||||
|
||||
### API Consistency and Reduction
|
||||
- **Change**: v2 revisits every public API, consolidating redundant methods and properties. For example, v1 had multiple focus-related methods scattered across @Terminal.Gui.ViewBase.View and @Terminal.Gui.App.Application; v2 centralizes these in [ApplicationNavigation](~/api/Terminal.Gui.App.ApplicationNavigation.yml).
|
||||
- **Change**: v2 revisits every public API, consolidating redundant methods and properties. For example, v1 had multiple focus-related methods scattered across [View](~/api/Terminal.Gui.ViewBase.View.yml) and [Application](~/api/Terminal.Gui.App.Application.yml); v2 centralizes these in [ApplicationNavigation](~/api/Terminal.Gui.App.ApplicationNavigation.yml).
|
||||
- **Impact**: This reduces the learning curve for new developers and minimizes the risk of using deprecated or inconsistent APIs.
|
||||
- **Example**: The v1 `View.MostFocused` property is replaced by `Application.Navigation.GetFocused()`, reducing traversal overhead and clarifying intent.
|
||||
|
||||
@@ -63,48 +75,65 @@ This architectural shift has resulted in the removal of thousands of lines of re
|
||||
- **Impact**: Developers can predict when resources are released, reducing bugs related to dangling references or uninitialized states.
|
||||
|
||||
### Adornments Framework
|
||||
- **Technical Detail**: Adornments are implemented as nested views that surround the content area, each with its own drawing and layout logic. @Terminal.Gui.ViewBase.Border supports multiple @Terminal.Gui.Drawing.LineStyle options (Single, Double, Heavy, Rounded, Dashed, Dotted) with automatic line intersection handling via [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml).
|
||||
- **Code Change**: In v2, @Terminal.Gui.ViewBase.View has properties @Terminal.Gui.ViewBase.View.Margin, @Terminal.Gui.ViewBase.View.Border, and @Terminal.Gui.ViewBase.View.Padding, each configurable independently, unlike v1's limited border support.
|
||||
|
||||
See the [Layout Deep Dive](layout.md) and [View Deep Dive](View.md) for complete details.
|
||||
|
||||
- **Technical Detail**: Adornments are implemented as nested views that surround the content area, each with its own drawing and layout logic. [Border](~/api/Terminal.Gui.ViewBase.Border.yml) supports multiple [LineStyle](~/api/Terminal.Gui.Drawing.LineStyle.yml) options (Single, Double, Heavy, Rounded, Dashed, Dotted) with automatic line intersection handling via [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml).
|
||||
- **Code Change**: In v2, [View](~/api/Terminal.Gui.ViewBase.View.yml) has properties [View.Margin](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Margin), [View.Border](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Border), and [View.Padding](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Padding), each configurable independently, unlike v1's limited border support.
|
||||
- **Impact**: This modular approach allows for reusable UI elements and simplifies creating visually consistent applications.
|
||||
|
||||
### Built-in Scrolling/Virtual Content Area
|
||||
|
||||
See the [Scrolling Deep Dive](scrolling.md) and [Layout Deep Dive](layout.md) for complete details.
|
||||
|
||||
- **v1 Issue**: Scrolling required using `ScrollView` or manual offset management, which was error-prone.
|
||||
- **v2 Solution**: Every @Terminal.Gui.ViewBase.View in v2 has a @Terminal.Gui.ViewBase.View.Viewport rectangle representing the visible portion of a potentially larger content area defined by [View.GetContentSize](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_GetContentSize). Changing `Viewport.Location` scrolls the content.
|
||||
- **v2 Solution**: Every [View](~/api/Terminal.Gui.ViewBase.View.yml) in v2 has a [View.Viewport](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Viewport) rectangle representing the visible portion of a potentially larger content area defined by [View.GetContentSize](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_GetContentSize). Changing `Viewport.Location` scrolls the content.
|
||||
- **Code Example**: In v2, [TextView](~/api/Terminal.Gui.Views.TextView.yml) uses this to handle large text buffers without additional wrapper views.
|
||||
- **Impact**: Simplifies implementing scrollable content and reduces the need for specialized container views.
|
||||
|
||||
### Improved ScrollBar
|
||||
- **Change**: v2 replaces `ScrollBarView` with [ScrollBar](~/api/Terminal.Gui.Views.ScrollBar.yml), a cleaner implementation integrated with the built-in scrolling system. @Terminal.Gui.ViewBase.View.VerticalScrollBar and @Terminal.Gui.ViewBase.View.HorizontalScrollBar properties enable scroll bars with minimal code.
|
||||
- **Change**: v2 replaces `ScrollBarView` with [ScrollBar](~/api/Terminal.Gui.Views.ScrollBar.yml), a cleaner implementation integrated with the built-in scrolling system. [View.VerticalScrollBar](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_VerticalScrollBar) and [View.HorizontalScrollBar](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HorizontalScrollBar) properties enable scroll bars with minimal code.
|
||||
- **Impact**: Developers can add scroll bars to any view without managing separate view hierarchies, a significant usability improvement over v1.
|
||||
|
||||
### DimAuto, PosAnchorEnd, and PosAlign
|
||||
|
||||
See the [Layout Deep Dive](layout.md) and [DimAuto Deep Dive](dimauto.md) for complete details.
|
||||
|
||||
- **[Dim.Auto](~/api/Terminal.Gui.Dim.yml#Terminal_Gui_Dim_Auto_Terminal_Gui_DimAutoStyle_Terminal_Gui_Dim_Terminal_Gui_Dim_)**: Automatically sizes views based on content or subviews, reducing manual layout calculations.
|
||||
- **[Pos.AnchorEnd](~/api/Terminal.Gui.Pos.yml#Terminal_Gui_Pos_AnchorEnd_System_Int32_)**: Allows anchoring to the right or bottom of a superview, enabling flexible layouts not easily achievable in v1.
|
||||
- **[Pos.Align](~/api/Terminal.Gui.Pos.yml)**: Provides alignment options (left, center, right) for multiple views, streamlining UI design.
|
||||
- **Impact**: These features reduce boilerplate layout code and support responsive designs in terminal constraints.
|
||||
|
||||
### View Arrangement
|
||||
- **Technical Detail**: The @Terminal.Gui.ViewBase.View.Arrangement property supports flags like @Terminal.Gui.ViewBase.ViewArrangement.Movable, @Terminal.Gui.ViewBase.ViewArrangement.Resizable, and @Terminal.Gui.ViewBase.ViewArrangement.Overlapped, enabling dynamic UI interactions via keyboard and mouse.
|
||||
- **Code Example**: [Window](~/api/Terminal.Gui.Views.Window.yml) in v2 uses @Terminal.Gui.ViewBase.View.Arrangement to allow dragging and resizing, a feature requiring custom logic in v1.
|
||||
|
||||
See the [Arrangement Deep Dive](arrangement.md) for complete details.
|
||||
|
||||
- **Technical Detail**: The [View.Arrangement](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Arrangement) property supports flags like [ViewArrangement.Movable](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml), [ViewArrangement.Resizable](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml), and [ViewArrangement.Overlapped](~/api/Terminal.Gui.ViewBase.ViewArrangement.yml), enabling dynamic UI interactions via keyboard and mouse.
|
||||
- **Code Example**: [Window](~/api/Terminal.Gui.Views.Window.yml) in v2 uses [View.Arrangement](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Arrangement) to allow dragging and resizing, a feature requiring custom logic in v1.
|
||||
- **Impact**: Developers can create desktop-like experiences in the terminal with minimal effort.
|
||||
|
||||
### Keyboard Navigation Overhaul
|
||||
- **v1 Issue**: Navigation was inconsistent, with coupled concepts like @Terminal.Gui.ViewBase.View.CanFocus and `TabStop` leading to unpredictable focus behavior.
|
||||
- **v2 Solution**: v2 decouples these concepts, introduces @Terminal.Gui.Input.TabBehavior enum for clearer intent (`TabStop`, `TabGroup`, `NoStop`), and centralizes navigation logic in [ApplicationNavigation](~/api/Terminal.Gui.App.ApplicationNavigation.yml).
|
||||
|
||||
See the [Navigation Deep Dive](navigation.md) for complete details on the navigation system.
|
||||
|
||||
- **v1 Issue**: Navigation was inconsistent, with coupled concepts like [View.CanFocus](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_CanFocus) and `TabStop` leading to unpredictable focus behavior.
|
||||
- **v2 Solution**: v2 decouples these concepts, introduces [TabBehavior](~/api/Terminal.Gui.Input.TabBehavior.yml) enum for clearer intent (`TabStop`, `TabGroup`, `NoStop`), and centralizes navigation logic in [ApplicationNavigation](~/api/Terminal.Gui.App.ApplicationNavigation.yml).
|
||||
- **Impact**: Ensures accessibility by guaranteeing keyboard access to all focusable elements, with unit tests enforcing navigation keys on built-in views.
|
||||
|
||||
### Sizable/Movable Views
|
||||
- **Implementation**: Any view can be made resizable or movable by setting @Terminal.Gui.ViewBase.View.Arrangement flags, with built-in mouse and keyboard handlers for interaction.
|
||||
- **Implementation**: Any view can be made resizable or movable by setting [View.Arrangement](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_Arrangement) flags, with built-in mouse and keyboard handlers for interaction.
|
||||
- **Impact**: Enhances user experience by allowing runtime UI customization, a feature limited to specific views like [Window](~/api/Terminal.Gui.Views.Window.yml) in v1.
|
||||
|
||||
## New and Improved Built-in Views - Detailed Analysis
|
||||
|
||||
See the [Views Overview](views.md) for a complete catalog of all built-in views.
|
||||
|
||||
### New Views
|
||||
|
||||
v2 introduces many new View subclasses that were not present in v1:
|
||||
|
||||
- **Bar**: A foundational view for horizontal or vertical layouts of `Shortcut` or other items, used in `StatusBar`, `MenuBarv2`, and `PopoverMenu`.
|
||||
- **CharMap**: A scrollable, searchable Unicode character map with support for the Unicode Character Database (UCD) API, enabling users to browse and select from all Unicode codepoints with detailed character information.
|
||||
- **CharMap**: A scrollable, searchable Unicode character map with support for the Unicode Character Database (UCD) API, enabling users to browse and select from all Unicode codepoints with detailed character information. See [Character Map Deep Dive](CharacterMap.md).
|
||||
- **ColorPicker**: Leverages TrueColor for a comprehensive color selection experience, supporting multiple color models (HSV, RGB, HSL, Grayscale) with interactive color bars.
|
||||
- **DatePicker**: Provides a calendar-based date selection UI with month/year navigation, leveraging v2's improved drawing and navigation systems.
|
||||
- **FlagSelector**: Enables selection of non-mutually-exclusive flags with checkbox-based UI, supporting both dictionary-based and enum-based flag definitions.
|
||||
@@ -124,25 +153,37 @@ Many existing views from v1 have been significantly enhanced in v2:
|
||||
- **FileDialog** (OpenDialog, SaveDialog): Completely modernized with `TreeView` for hierarchical file navigation, Unicode glyphs for icons, search functionality, and history tracking - far surpassing v1's basic file dialogs.
|
||||
- **ScrollBar**: Replaces v1's `ScrollBarView` with a cleaner implementation featuring automatic show/hide, proportional sizing with `ScrollSlider`, and seamless integration with View's built-in scrolling system.
|
||||
- **StatusBar**: Rebuilt on the `Bar` infrastructure, providing more flexible item management, automatic sizing, and better visual presentation.
|
||||
- **TableView**: Massively enhanced with support for generic collections (via `IEnumerableTableSource`), checkboxes with `CheckBoxTableSourceWrapper`, tree structures via `TreeTableSource`, custom cell rendering, and significantly improved performance.
|
||||
- **TableView**: Massively enhanced with support for generic collections (via `IEnumerableTableSource`), checkboxes with `CheckBoxTableSourceWrapper`, tree structures via `TreeTableSource`, custom cell rendering, and significantly improved performance. See [TableView Deep Dive](tableview.md).
|
||||
- **ScrollView**: Deprecated in favor of View's built-in scrolling capabilities, eliminating the need for wrapper views and simplifying scrollable content implementation.
|
||||
|
||||
## Beauty - Visual Enhancements
|
||||
|
||||
### Borders
|
||||
- **Implementation**: Uses the @Terminal.Gui.ViewBase.Border adornment with @Terminal.Gui.Drawing.LineStyle options and [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml) for automatic line intersection handling.
|
||||
|
||||
See the [Drawing Deep Dive](drawing.md) for complete details on borders and LineCanvas.
|
||||
|
||||
- **Implementation**: Uses the [Border](~/api/Terminal.Gui.ViewBase.Border.yml) adornment with [LineStyle](~/api/Terminal.Gui.Drawing.LineStyle.yml) options and [LineCanvas](~/api/Terminal.Gui.Drawing.LineCanvas.yml) for automatic line intersection handling.
|
||||
- **Impact**: Adds visual polish to UI elements, making applications feel more refined compared to v1's basic borders.
|
||||
|
||||
### Gradient
|
||||
|
||||
See the [Drawing Deep Dive](drawing.md) for complete details on gradients and fills.
|
||||
|
||||
- **Implementation**: [Gradient](~/api/Terminal.Gui.Drawing.Gradient.yml) and [GradientFill](~/api/Terminal.Gui.Drawing.GradientFill.yml) APIs allow rendering color transitions across view elements, using TrueColor for smooth effects.
|
||||
- **Impact**: Enables modern-looking UI elements like gradient borders or backgrounds, not possible in v1 without custom drawing.
|
||||
|
||||
## Configuration Manager - Persistence and Customization
|
||||
- **Technical Detail**: @Terminal.Gui.Configuration.ConfigurationManager in v2 uses JSON to persist settings like themes, key bindings, and view properties to disk via @Terminal.Gui.Configuration.SettingsScope and [ConfigLocations](~/api/Terminal.Gui.Configuration.ConfigLocations.yml).
|
||||
|
||||
See the [Configuration Deep Dive](config.md) for complete details on the configuration system.
|
||||
|
||||
- **Technical Detail**: [ConfigurationManager](~/api/Terminal.Gui.Configuration.ConfigurationManager.yml) in v2 uses JSON to persist settings like themes, key bindings, and view properties to disk via [SettingsScope](~/api/Terminal.Gui.Configuration.SettingsScope.yml) and [ConfigLocations](~/api/Terminal.Gui.Configuration.ConfigLocations.yml).
|
||||
- **Code Change**: Unlike v1, where settings were ephemeral or hardcoded, v2 provides a centralized system for loading/saving configurations using the [ConfigurationManagerAttribute](~/api/Terminal.Gui.Configuration.ConfigurationManagerAttribute.yml).
|
||||
- **Impact**: Allows for user-specific customizations and library-wide settings without recompilation, enhancing flexibility.
|
||||
|
||||
## Logging & Metrics - Debugging and Performance
|
||||
|
||||
See the [Logging Deep Dive](logging.md) for complete details on the logging and metrics system.
|
||||
|
||||
- **Implementation**: v2 introduces a multi-level logging system via [Logging](~/api/Terminal.Gui.App.Logging.yml) for internal operations (e.g., rendering, input handling) using Microsoft.Extensions.Logging.ILogger, and metrics for performance tracking via [Logging.Meter](~/api/Terminal.Gui.App.Logging.yml#Terminal_Gui_App_Logging_Meter) (e.g., frame rate, redraw times, iteration timing).
|
||||
- **Impact**: Developers can diagnose issues like slow redraws or terminal compatibility problems using standard .NET logging frameworks (Serilog, NLog, etc.) and metrics tools (dotnet-counters), a capability absent in v1, reducing guesswork in debugging.
|
||||
|
||||
@@ -153,32 +194,36 @@ Many existing views from v1 have been significantly enhanced in v2:
|
||||
|
||||
## Updated Keyboard API - Comprehensive Input Handling
|
||||
|
||||
See the [Keyboard Deep Dive](keyboard.md) and [Command Deep Dive](command.md) for complete details.
|
||||
|
||||
### Key Class
|
||||
- **Change**: Replaces v1's `KeyEvent` struct with a [Key](~/api/Terminal.Gui.Input.Key.yml) class, providing a high-level abstraction over raw key codes with properties for modifiers and key type.
|
||||
- **Impact**: Simplifies keyboard handling by abstracting platform differences, making code more portable and readable.
|
||||
|
||||
### Key Bindings
|
||||
- **Implementation**: v2 introduces a binding system mapping keys to @Terminal.Gui.Input.Command enums via @Terminal.Gui.ViewBase.View.KeyBindings, with scopes (`Application`, `Focused`, `HotKey`) for priority.
|
||||
- **Impact**: Replaces v1's ad-hoc key handling with a structured approach, allowing views to declare supported commands via @Terminal.Gui.ViewBase.View.AddCommand and customize responses easily.
|
||||
- **Implementation**: v2 introduces a binding system mapping keys to [Command](~/api/Terminal.Gui.Input.Command.yml) enums via [View.KeyBindings](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_KeyBindings), with scopes (`Application`, `Focused`, `HotKey`) for priority.
|
||||
- **Impact**: Replaces v1's ad-hoc key handling with a structured approach, allowing views to declare supported commands via [View.AddCommand](~/api/Terminal.Gui.ViewBase.View.yml) and customize responses easily.
|
||||
- **Example**: [TextField](~/api/Terminal.Gui.Views.TextField.yml) in v2 binds `Key.Tab` to text insertion rather than focus change, customizable by developers.
|
||||
|
||||
### Default Close Key
|
||||
- **Change**: Changed from `Ctrl+Q` in v1 to `Esc` in v2 for closing apps or @Terminal.Gui.Views.Toplevel views, accessible via [Application.QuitKey](~/api/Terminal.Gui.App.Application.yml#Terminal_Gui_App_Application_QuitKey).
|
||||
- **Change**: Changed from `Ctrl+Q` in v1 to `Esc` in v2 for closing apps or [Toplevel](~/api/Terminal.Gui.Views.Toplevel.yml) views, accessible via [Application.QuitKey](~/api/Terminal.Gui.App.Application.yml#Terminal_Gui_App_Application_QuitKey).
|
||||
- **Impact**: Aligns with common user expectations, improving UX consistency across terminal applications.
|
||||
|
||||
## Updated Mouse API - Enhanced Interaction
|
||||
|
||||
See the [Mouse Deep Dive](mouse.md) for complete details on mouse handling.
|
||||
|
||||
### MouseEventArgs Class
|
||||
- **Change**: Replaces v1's `MouseEventEventArgs` with [MouseEventArgs](~/api/Terminal.Gui.Input.MouseEventArgs.yml), providing a cleaner structure for mouse data (position, flags via @Terminal.Gui.Input.MouseFlags).
|
||||
- **Change**: Replaces v1's `MouseEventEventArgs` with [MouseEventArgs](~/api/Terminal.Gui.Input.MouseEventArgs.yml), providing a cleaner structure for mouse data (position, flags via [MouseFlags](~/api/Terminal.Gui.Input.MouseFlags.yml)).
|
||||
- **Impact**: Simplifies event handling with a more intuitive API, reducing errors in mouse interaction logic.
|
||||
|
||||
### Granular Mouse Handling
|
||||
- **Implementation**: v2 offers specific events for clicks (@Terminal.Gui.ViewBase.View.MouseClick), double-clicks, and movement, with [MouseFlags](~/api/Terminal.Gui.Input.MouseFlags.yml) for button states.
|
||||
- **Implementation**: v2 offers specific events for clicks ([View.MouseClick](~/api/Terminal.Gui.ViewBase.View.yml)), double-clicks, and movement, with [MouseFlags](~/api/Terminal.Gui.Input.MouseFlags.yml) for button states.
|
||||
- **Impact**: Developers can handle complex mouse interactions (e.g., drag-and-drop) more easily than in v1.
|
||||
|
||||
### Highlight Event and Continuous Button Presses
|
||||
- **Highlight**: Views can visually respond to mouse hover or click via the @Terminal.Gui.ViewBase.View.Highlight event and [View.HighlightStyle](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HighlightStyle) property.
|
||||
- **Continuous Presses**: Setting @Terminal.Gui.ViewBase.View.WantContinuousButtonPresses = true repeats @Terminal.Gui.Input.Command.Accept during button hold, useful for sliders or buttons.
|
||||
- **Highlight**: Views can visually respond to mouse hover or click via the [View.Highlight](~/api/Terminal.Gui.ViewBase.View.yml) event and [View.HighlightStyle](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_HighlightStyle) property.
|
||||
- **Continuous Presses**: Setting [View.WantContinuousButtonPresses](~/api/Terminal.Gui.ViewBase.View.yml#Terminal_Gui_ViewBase_View_WantContinuousButtonPresses) = true repeats [Command.Accept](~/api/Terminal.Gui.Input.Command.yml) during button hold, useful for sliders or buttons.
|
||||
- **Impact**: Enhances interactive feedback, making terminal UIs feel more responsive.
|
||||
|
||||
## AOT Support - Deployment and Performance
|
||||
|
||||
Reference in New Issue
Block a user