Git_Mirror/Terminal.Gui
1
0
Fork 0
mirror of https://github.com/gui-cs/Terminal.Gui.git synced 2025-12-26 15:57:56 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated conceptual API documentation; added mouse.md

Browse Source
This commit is contained in:
Tig
2024-04-09 22:44:45 -04:00
parent 6b80b23340
commit 62f015645a
3 changed files with 60 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
Terminal.Gui/View/Layout/ViewLayout.cs
View File

@@ -50,8 +50,8 @@ public partial class View
/// <para>
/// Setting Frame will set <see cref="X"/>, <see cref="Y"/>, <see cref="Width"/>, and <see cref="Height"/> to the
/// values of the corresponding properties of the <paramref name="value"/> parameter.
/// This causes <see cref="LayoutStyle"/> to be <see cref="LayoutStyle.Absolute"/>.
/// </para>
/// <para>This causes <see cref="LayoutStyle"/> to be <see cref="LayoutStyle.Absolute"/>.</para>
/// <para>
/// Altering the Frame will eventually (when the view hierarchy is next laid out via see
/// cref="LayoutSubviews"/>) cause <see cref="LayoutSubview(View, Size)"/> and
@@ -120,19 +120,41 @@ public partial class View
/// <returns>The coordinate relative to the <see cref="SuperView"/>'s <see cref="Viewport"/>.</returns>
/// <param name="x">Screen-relative column.</param>
/// <param name="y">Screen-relative row.</param>
public virtual Point ScreenToFrame (int x, int y)
{
Point superViewViewportOffset = SuperView?.GetViewportOffsetFromFrame () ?? Point.Empty;
//public virtual Point ScreenToFrame (int x, int y)
//{
// Point superViewViewportOffset = SuperView?.GetViewportOffsetFromFrame () ?? Point.Empty;
// if (SuperView is null)
// {
// superViewViewportOffset.Offset (x - Frame.X, y - Frame.Y);
// return superViewViewportOffset;
// }
// superViewViewportOffset.Offset (-SuperView.Viewport.X, -SuperView.Viewport.Y);
// Point frame = SuperView.ScreenToFrame (x - superViewViewportOffset.X, y - superViewViewportOffset.Y);
// frame.Offset (-Frame.X, -Frame.Y);
// return frame;
//}
public virtual Point ScreenToFrame (/*Point point*/int x, int y)
{
Point point = new (x, y);
if (SuperView is null)
{
superViewViewportOffset.Offset (x - Frame.X, y - Frame.Y);
return superViewViewportOffset;
return new Point (point.X - Frame.X, point.Y - Frame.Y);
}
superViewViewportOffset.Offset (-SuperView.Viewport.X, -SuperView.Viewport.Y);
Point frame = SuperView.ScreenToFrame (x - superViewViewportOffset.X, y - superViewViewportOffset.Y);
frame.Offset (-Frame.X, -Frame.Y);
Point superViewViewportOffset = SuperView.GetViewportOffsetFromFrame ();
superViewViewportOffset.X -= SuperView.Viewport.X;
superViewViewportOffset.Y -= SuperView.Viewport.Y;
point.X -= superViewViewportOffset.X;
point.Y -= superViewViewportOffset.Y;
Point frame = SuperView.ScreenToFrame (point);
frame.X -= Frame.X;
frame.Y -= Frame.Y;
return frame;
}

4
docfx/docs/drawing.md
View File

@@ -1,4 +1,4 @@
# Drawing (Text and Color)
# Drawing (Text, Lines, and Color)
Terminal.Gui provides a set of APIs for formatting text, line drawing, and character-based graphing. The fundamental concept is a `Cell` which ocupises a particular row and column in the terminal. A Cell includes the character (glyph) that should be rendred by the terminal, and attributes that indicate how the glphy should be rendered (e.g. the foreground and background color).
@@ -65,6 +65,8 @@ Color schemes support defining colors for various states of a view. The followin
* HotFocus - The color of text indicating a hot key, when the view has focus.
* Disabled - The state of a view when it is disabled.
Change the colors of a view by setting the `View.ColorScheme` property.
## Text Formatting
Terminal.Gui supports text formatting using the [TextFormatter]() class. The `TextFormatter` class provides methods for formatting text using the following formatting options:

111
docfx/docs/index.md
View File

@@ -10,14 +10,15 @@
* **[Extensible Widgets](https://gui-cs.github.io/Terminal.GuiV2Docs/api/Terminal.Gui.View.html)** - All visible UI elements are subclasses of the `View` class, and these in turn can contain an arbitrary number of sub-views. Dozens of [Built-in Views](views.md) are provided.
* **[Flexible Layout](layout.md)** - *Computed Layout* makes it easy to lay out controls relative to each other and enables dynamic terminal UIs. *Absolute Layout* allows for precise control over the position and size of controls.
* **[Clipboard support](https://gui-cs.github.io/Terminal.GuiV2Docs/api/Terminal.Gui.Clipboard.html)** - Cut, Copy, and Paste is provided through the [`Clipboard`] class.
* **Advanced App Features** - The [Mainloop](https://gui-cs.github.io/Terminal.GuiV2Docs/api/Terminal.Gui.MainLoop.html) supports processing events, idle handlers, and timers. Most classes are safe for threading.
* **Multi-tasking** - The [Mainloop](https://gui-cs.github.io/Terminal.GuiV2Docs/api/Terminal.Gui.MainLoop.html) supports processing events, idle handlers, and timers. Most classes are safe for threading.
* **[Reactive Extensions](https://github.com/dotnet/reactive)** - Use reactive extensions and benefit from increased code readability, and the ability to apply the MVVM pattern and [ReactiveUI](https://www.reactiveui.net/) data bindings. See the [source code](https://github.com/gui-cs/Terminal.GuiV2Docs/tree/master/ReactiveExample) of a sample app.
## Conceptual Documentation
* [List of Views](views.md)
* [Keyboard Event Processing](keyboard.md)
* [Event Processing and the Application Main Loop](mainloop.md)
* [Keyboard API](keyboard.md)
* [Mouse API](mouse.md)
* [Multi-tasking and the Application Main Loop](mainloop.md)
* [Cross-platform Driver Model](drivers.md)
* [Configuration and Theme Manager](config.md)
* [TableView Deep Dive](tableview.md)
@@ -45,14 +46,17 @@ The [Application](~/api/Terminal.Gui.Application.yml) class additionally creates
using Terminal.Gui;
Application.Init ();
var label = new Label ("Hello World") {
var label = new Label () {
Title = "Hello World",
X = Pos.Center (),
Y = Pos.Center (),
Height = 1,
};
Application.Top.Add (label);
Application.Run ();
var app = new Toplevel ();
app.Add (label);
Application.Run (app);
app.Dispose ();
Application.Shutdown ();
```
@@ -70,7 +74,8 @@ var menu = new MenuBar (new MenuBarItem [] {
}),
});
var button = new Button ("_Hello") {
var button = new Button () {
Title = "_Hello",
X = 0,
Y = Pos.Bottom (menu),
Width = Dim.Fill (),
@@ -80,9 +85,11 @@ button.Clicked += () => {
MessageBox.Query (50, 5, "Hi", "Hello World! This is a message box", "Ok");
};
var app = new Toplevel ();
// Add both menu and win in a single call
Application.Top.Add (menu, button);
Application.Run ();
top.Add (menu, button);
Application.Run (top);
top.Dispose ();
Application.Shutdown ();
```
@@ -99,7 +106,8 @@ Every view can contain an arbitrary number of child views, called `SubViews`. Ca
```csharp
void SetupMyView (View myView)
{
var label = new Label ("Username: ") {
var label = new Label () {
Title = "_Username:"
X = 1,
Y = 1,
Width = 20,
@@ -107,8 +115,8 @@ void SetupMyView (View myView)
};
myView.Add (label);
var username = new TextField ("") {
X = 1,
var username = new TextField () {
X = Pos.Right (label) + 1,
Y = 2,
Width = 30,
Height = 1
@@ -117,19 +125,7 @@ void SetupMyView (View myView)
}
```
The container of a given view is called the `SuperView` and it is a property of every
View.
## Layout
Terminal.Gui v2 supports the following View layout systems (controlled by the [View.LayoutStyle](~/api/Terminal.Gui.LayoutStyle.yml)):
* **Absolute** - Used to have the View positioned exactly in a location, with a fixed size. Absolute layout is accomplished by constructing a View with an argument of type [Rect](~/api/Terminal.Gui.Rect.yml) or directly changing the `Frame` property on the View.
* **Computed** - The Computed Layout system provides automatic aligning of Views with other Views, automatic centering, and automatic sizing. To use Computed layout set the
`X`, `Y`, `Width` and `Height` properties after the object has been created. Views laid out using the Computed Layout system can be resized with the mouse or keyboard, enabling tiled window managers and dynamic terminal UIs.
* **Overlapped** - New in V2 (But not yet) - Overlapped layout enables views to be positioned on top of each other. Overlapped Views are movable and sizable with both the keyboard and the mouse.
See the full [Layout documentation here](layout.md).
The container of a given view is called the `SuperView` and it is a property of every View.
## Modal Views
@@ -157,6 +153,7 @@ dialog.Add (entry);
Application.Run (dialog);
if (okpressed)
Console.WriteLine ("The user entered: " + entry.Text);
dialog.Dispose ();
```
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.
@@ -174,9 +171,9 @@ Dialogs expose an API for adding buttons and managing the layout such that butto
Example:
```csharp
bool okpressed = false;
var ok = new Button("Ok");
var cancel = new Button("Cancel");
var dialog = new Dialog ("Quit", ok, cancel) { Text = "Are you sure you want to quit?" };
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 } };
```
Which will show something like this:
@@ -208,61 +205,3 @@ Which will show something like this:
║⟦ Back ⟧ ⟦► Finish ◄⟧║
╚═════════════════════════════════════════════════════════════╝
```
## Input Handling
Every view has a focused view, and if that view has nested SubViews, one of those is
the focused view. This is called the focus chain, and at any given time, only one
View has the [Focus]().
The library provides a default focus mechanism that can be used to navigate the focus chain. The default focus mechanism is based on the Tab key, and the Shift-Tab key combination
Keyboard processing details are available on the [Keyboard Event Processing](keyboard.md) document.
## Colors and Color Schemes
All views have been configured with a color scheme that will work both in color
terminals as well as the more limited black and white terminals.
The various styles are captured in the [Colors](~/api/Terminal.Gui.Colors.yml) class which defines color schemes for Toplevel, the normal views (Base), the menu bar, dialog boxes, and error UI::
* `Colors.Toplevel`
* `Colors.Base`
* `Colors.Menu`
* `Colors.Dialog`
* `Colors.Error`
You can use them for example like this to set the colors for a new Window:
```
var w = new Window ("Hello");
w.ColorScheme = Colors.Error
```
ColorSchemes can be configured with the [Configuration and Theme Manager](config.md).
The [ColorScheme](~/api/Terminal.Gui.ColorScheme.yml) represents
four values, the color used for Normal text, the color used for normal text when
a view is focused an the colors for the hot-keys both in focused and unfocused modes.
By using `ColorSchemes` you ensure that your application will work correctbly both
in color and black and white terminals.
Some views support setting individual color attributes, you create an
attribute for a particular pair of Foreground/Background like this:
```
var myColor = Application.Driver.MakeAttribute (Color.Blue, Color.Red);
var label = new Label (...);
label.TextColor = myColor
```
Learn more about colors in the [Drawing](drawing.md) overview.
## MainLoop, Threads and Input Handling
The Main Loop, threading, and timers are described on the [Event Processing and the Application Main Loop](~/docs/mainloop.md) document.
## Cross-Platform Drivers
See [Cross-platform Driver Model](drivers.md).