mirror of
https://github.com/lihop/godot-xterm.git
synced 2025-05-03 12:04:24 +02:00
Move documentation from wiki to main repo
Makes it easier to keep documentation up to date and can deploy with GitHub pages. README.md moved to docs/README.md and is shared with GitHub Pages home page.
This commit is contained in:
Leroy Hopson
parent
66254ea17e
commit
6f89edc14e
36 changed files with 4544 additions and 143 deletions
9
docs/api/api.md
Normal file
9
docs/api/api.md
Normal file
|
|
@ -0,0 +1,9 @@
|
|||
---
|
||||
layout: default
|
||||
title: API
|
||||
nav_order: 3
|
||||
has_children: true
|
||||
permalink: /api
|
||||
---
|
||||
|
||||
# API
|
||||
201
docs/api/pty.md
Normal file
201
docs/api/pty.md
Normal file
|
|
@ -0,0 +1,201 @@
|
|||
---
|
||||
layout: default
|
||||
title: PTY
|
||||
parent: API
|
||||
nav_order: 1
|
||||
permalink: /api/pty
|
||||
---
|
||||
|
||||
# PTY
|
||||
|
||||
**Inherits:** [Node] < [Object]
|
||||
|
||||
*Linux and macOS only.*
|
||||
|
||||
Node for forking processes (e.g. bash, nodejs, python) with pseudoterminal file descriptors.
|
||||
Can be used with the [Terminal] node to get an actual shell.
|
||||
|
||||
Not currently supported on Windows, but it could be in the future using [ConPTY](https://docs.microsoft.com/en-us/windows/console) or [WinPTY](https://github.com/rprichard/winpty).
|
||||
See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
|
||||
<sub>"PTY Diagram" is a derivative of [Termios-script-diagram.svg](https://commons.wikimedia.org/wiki/File:Termios-script-diagram.svg) by [Krishnavedala](https://en.wikipedia.org/wiki/User:Krishnavedala?rdfrom=commons:User:Krishnavedala), used under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/).
|
||||
|
||||
|
||||
## Properties
|
||||
|
||||
| Type | Name | Default |
|
||||
|--------------|--------------------------------------|--------------------------------------------------------|
|
||||
| [NodePath] | [terminal_path](#prop-terminal_path) | None |
|
||||
| [int] | [cols](#prop-cols) | `80` |
|
||||
| [int] | [rows](#prop-rows) | `24` |
|
||||
| [Dictionary] | [env](#prop-env) | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
|
||||
| [bool] | [use_os_env](#prop-use_os_env) | `true` |
|
||||
|
||||
|
||||
## Methods
|
||||
|
||||
| Returns | Signature |
|
||||
|---------|-------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| [Error] | [fork](#mthd-fork) **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)** |
|
||||
| void | [kill](#mthd-kill) **(** [int] signum **)** |
|
||||
| [Error] | [open](#mthd-open) **(** [int] cols=80, [int] rows=24 **)** |
|
||||
| void | [resize](#mthd-resize) **(** [int] cols, [int] rows **)** |
|
||||
| void | [resizev](#mthd-resizev) **(** [Vector2] size **)** |
|
||||
| void | [write](#mthd-write) **(** [String]\|[PoolByteArray] data **)** |
|
||||
|
||||
|
||||
## Signals
|
||||
|
||||
- <a name="sgnl-data_received" /> **data_received** **(** [PoolByteArray] data **)**
|
||||
|
||||
Emitted when data is read from the pseudoterminal master device.
|
||||
|
||||
---
|
||||
|
||||
- <a name="sgnl-exited" /> **exited** **(** [int] exit_code, [int] signum **)**
|
||||
|
||||
Emitted when the child program exits. `exit_code` is the exit status of the child program and `signum` is the number of the signal that terminated the child program.
|
||||
|
||||
## Enumerations
|
||||
|
||||
### <a name="enum-signal" /> enum **Signal**:
|
||||
|
||||
- **SIGHUP** = 1 --- Hangup.
|
||||
- **SIGINT** = 2 --- Terminal interrupt signal.
|
||||
- **SIGQUIT** = 3 --- Terminal quit signal.
|
||||
- **SIGILL** = 4 --- Illegal instruction.
|
||||
- **SIGTRAP** = 5 --- Trace/breakpoint trap.
|
||||
- **SIGABRT** = 6 --- Process abort signal.
|
||||
- **SIGFPE** = 8 --- Erroneous arithmetic operation.
|
||||
- **SIGKILL** = 9 --- Kill (cannot be caught or ignored).
|
||||
- **SIGSEGV** = 11 --- Invalid memory reference.
|
||||
- **SIGPIPE** = 13 --- Write on a pipe with no one to read it.
|
||||
- **SIGALRM** = 14 --- Alarm clock.
|
||||
- **SIGTERM** = 15 --- Termination signal.
|
||||
|
||||
|
||||
## Property Descriptions
|
||||
|
||||
### <a name="prop-terminal_path" /> [NodePath] **terminal_path**
|
||||
|
||||
| | |
|
||||
|-----------|--------------------------|
|
||||
| *Default* | None |
|
||||
| *Setter* | set_terminal_path(value) |
|
||||
| *Getter* | None |
|
||||
|
||||
[NodePath] to a [Terminal]. Setting this path will automatically connect the appropriate signals of both nodes for standard operation. It will also disconnected the signals of the previously set terminal, if any.
|
||||
|
||||
---
|
||||
|
||||
- <a name="prop-cols" /> [int] **cols**
|
||||
|
||||
| | |
|
||||
|-----------|--------------------------|
|
||||
| *Default* | `80` |
|
||||
| *Setter* | set_cols(value) |
|
||||
| *Getter* | None |
|
||||
|
||||
The column size in characters.
|
||||
|
||||
---
|
||||
|
||||
- <a name="prop-rows" /> [int] **rows**
|
||||
|
||||
| | |
|
||||
|-----------|--------------------------|
|
||||
| *Default* | `24` |
|
||||
| *Setter* | set_rows(value) |
|
||||
| *Getter* | None |
|
||||
|
||||
The row size in characters.
|
||||
|
||||
---
|
||||
|
||||
- <a name="prop-env" /> [Dictionary] **env**
|
||||
|
||||
| | |
|
||||
|-----------|--------------------------------------------------------|
|
||||
| *Default* | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
|
||||
| *Setter* | None |
|
||||
| *Getter* | None |
|
||||
|
||||
Environment variables to be set for the child program.
|
||||
|
||||
---
|
||||
|
||||
- <a name="prop-use_os_env" /> [bool] **use_os_env**
|
||||
|
||||
| | |
|
||||
|-----------|--------|
|
||||
| *Default* | `true` |
|
||||
| *Setter* | None |
|
||||
| *Getter* | None |
|
||||
|
||||
If `true` the environment variables from `env` will be merged with the environment variables of the current program (i.e. Godot), with the variables from `env` taking precedence over the environment variables of the current program.
|
||||
|
||||
|
||||
## Method Descriptions
|
||||
|
||||
- <a name="mthd-fork" /> [Error] **fork** **(** [String] file=`$SHELL`, [PoolStringArray] args=[], [String] cwd=`$PWD`, [int] cols=80, [int] rows=24 **)**
|
||||
{ .red }
|
||||
|
||||
Opens a pseudoterminal and starts a new process using the program specified by `file`.
|
||||
`file` defaults to the value of the `SHELL` environment variable, falling back to `sh`.
|
||||
The arguments specified in `args` are passed to the program.
|
||||
`cwd` is the directory in which the program will be executed. Defaults to the working directory of the current program (typically the project directory, when running from editor).
|
||||
`cols` is the initial number of columns and `rows` is the initial number of rows.
|
||||
Returns [OK] if successful.
|
||||
|
||||
See also Godot's [OS.execute()](https://docs.godotengine.org/en/stable/classes/class_os.html#class-os-method-execute) method.
|
||||
|
||||
---
|
||||
|
||||
- <a name="mthd-kill" /> void **kill** **(** [int] signum=1 **)**
|
||||
|
||||
Sends the specified signal (`signum`) to the PTY's child process, if any. Defaults to 1 (SIGHUP).
|
||||
|
||||
See also Godot's [OS.kill()](https://docs.godotengine.org/en/stable/classes/class_os.html#class-os-method-kill) method.
|
||||
|
||||
---
|
||||
|
||||
- <a name="mthd-open" /> [Error] **open** **(** [int] cols=80, [int] rows=24 **)**
|
||||
|
||||
Opens a pseudoterminal but does not start any process. Returns [OK] if successful.
|
||||
|
||||
---
|
||||
|
||||
- <a name="mthd-resize" /> void **resize** **(** [int] cols, [int] rows **)**
|
||||
|
||||
Resizes the dimensions of the pseudoterminal.
|
||||
|
||||
---
|
||||
|
||||
- <a name="mthd-resizev" /> void **resizev** **(** [Vector2] size **)**
|
||||
|
||||
Same as resize, but accepts a [Vector2] where `x` is cols and `y` is rows.
|
||||
|
||||
---
|
||||
|
||||
- <a name="mthd-write" /> void **write** **(** [String] \| [PoolByteArray] data **)**
|
||||
|
||||
Writes data to the pseudoterminal master device.
|
||||
|
||||
|
||||
[Dictionary]: https://docs.godotengine.org/en/stable/classes/class_dictionary.html
|
||||
[Error]: https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#enum-globalscope-error
|
||||
[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html
|
||||
[NodePath]: https://docs.godotengine.org/en/stable/classes/class_nodepath.html
|
||||
[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html
|
||||
[OK]: https://docs.godotengine.org/en/stable/classes/class_%40globalscope.html#class-globalscope-constant-ok
|
||||
[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html
|
||||
[PoolStringArray]: https://docs.godotengine.org/en/stable/classes/class_poolstringarray.html
|
||||
[String]: https://docs.godotengine.org/en/stable/classes/class_string.html
|
||||
[Terminal]: /api/terminal
|
||||
[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html
|
||||
[bool]: https://docs.godotengine.org/en/stable/classes/class_bool.html
|
||||
[int]: https://docs.godotengine.org/en/stable/classes/class_int.html
|
||||
225
docs/api/terminal.md
Normal file
225
docs/api/terminal.md
Normal file
|
|
@ -0,0 +1,225 @@
|
|||
---
|
||||
layout: default
|
||||
title: Terminal
|
||||
parent: API
|
||||
nav_order: 2
|
||||
permalink: /api/terminal
|
||||
---
|
||||
|
||||
# Terminal
|
||||
|
||||
**Inherits:** [Control] < [CanvasItem] < [Node] < [Object]
|
||||
|
||||
A Terminal emulator Control node.
|
||||
|
||||
Supports ANSI and (some) XTerm Control Sequences which can be used to do things such as clear the screen, move the cursor, change printed text color, ring a bell, and so on.
|
||||
For an exhaustive list of terminal control sequences (not all of which are supported by GodotXterm) see ["XTerm Control Sequences"](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html).
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
<sub>"Terminal Flow Diagram" is a derivative of ["computer keyboard 2"](https://openclipart.org/detail/2396/computer-keyboard-2) and ["monitor"](https://openclipart.org/detail/1637/monitor), from U.S. patent drawings, uploaded by [johnny_automatic](https://openclipart.org/artist/johnny_automatic), used under [CC0](https://creativecommons.org/share-your-work/public-domain/cc0/).<sub/>
|
||||
|
||||
### (1) User Input
|
||||
|
||||
The user enters some data into the terminal, typically by typing something on the keyboard.
|
||||
This corresponds to the `_gui_input()` method.
|
||||
|
||||
### (2) Terminal Output
|
||||
|
||||
The user input from (1) is processed by the terminal state machine and converted to the appropriate output.
|
||||
For example, if the user were to press the downwards arrow key (↓), the terminal would then emit `data_sent()`
|
||||
with the value `"\u001b[A"`.
|
||||
|
||||
### (3) Terminal Input
|
||||
|
||||
In the other direction, data can be sent to the terminal. This corresponds to the `write()` method.
|
||||
|
||||
### (4) Draw
|
||||
|
||||
The input from (3) is then interpreted by the terminal state machine and drawn to the screen.
|
||||
For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal, then it would draw a green colored capital letter 'A' on the screen.
|
||||
|
||||
|
||||
## Properties
|
||||
|
||||
| Type | Name | Default |
|
||||
|--------------|--------------------------------------|---------|
|
||||
| [bool] | [bell_muted](#prop-bell_muted) | `false` |
|
||||
| [float] | [bell_cooldown](#prop-bell_cooldown) | `0.1` |
|
||||
| [int] | [cols](#prop-cols) | `2` |
|
||||
| [int] | [rows](#prop-rows) | `2` |
|
||||
| [UpdateMode] | [update_mode](#prop-update_mode) | `AUTO` |
|
||||
|
||||
|
||||
## Methods
|
||||
|
||||
| Returns | Signature |
|
||||
|----------|-----------------------------------------------------------------|
|
||||
| void | [clear](#mthd-clear) **()** |
|
||||
| [String] | [copy_all](#mthd-copy_all) **()** |
|
||||
| [String] | [copy_selection](#mthd-copy_selection) **()** |
|
||||
| void | [write](#mthd-write) **(** [String]\|[PoolByteArray] data **)** |
|
||||
|
||||
|
||||
## Signals
|
||||
|
||||
- <a name="sgnl-bell" /> **bell** **()**
|
||||
|
||||
Emitted when the [bell character](https://en.wikipedia.org/wiki/Bell_character) (`"\u0007"`) is written to the terminal.
|
||||
|
||||
---
|
||||
|
||||
- <a name="sgnl-data_sent" /> **data_sent** **(** [PoolByteArray] data **)**
|
||||
|
||||
Emitted when some data comes out of the terminal.
|
||||
This typically occurs when the user interacts with the terminal by typing on the keyboard.
|
||||
Input can be interpreted differently depending on modifier keys and the terminal's settings/state.
|
||||
|
||||
When connected to a [PTY], this data will be forwarded to it.
|
||||
|
||||
---
|
||||
|
||||
- <a name="sgnl-key_pressed" /> **key_pressed** **(** [String] data, [InputEventKey] event **)**
|
||||
|
||||
Emitted when a key is pressed. `data` is the data that would be emitted by the terminal via the [`data_sent()`](#sgnl-data_sent) signal and may vary based on the terminal's state. `event` is the event captured by Godot in the `_gui_input(event)` method.
|
||||
|
||||
---
|
||||
|
||||
- <a name="sgnl-size_changed"> **size_changed** **(** [Vector2] new_size **)**
|
||||
|
||||
Emitted when the terminal's size changes, typically in response to its `rect_size` changing.
|
||||
`new_size.x` will be the number of columns and `new_size.y` will be the number of rows.
|
||||
This information should be forwarded to a pseudoterminal, if it is connected, so that it can update its size accordingly.
|
||||
|
||||
|
||||
## Enumerations
|
||||
|
||||
<a name="enum-update_mode" /> enum **UpdateMode**:
|
||||
|
||||
- **DISABLED** = **0** --- The terminal's `update()` method will never be called. No new cells will be drawn.
|
||||
- **AUTO** = **1** --- Only changed cells will be drawn after `update()` is called, but will switch to **ALL_NEXT_FRAME** when mass redraws are required.
|
||||
- **ALL** = **2** --- Every cell will be drawn on every `update()` call.
|
||||
- **ALL_NEXT_FRAME** = **3** --- Draws every cell afetr the next `update()` call, then returns to **AUTO**.
|
||||
|
||||
|
||||
## Property Descriptions
|
||||
|
||||
- <a name="prop-rows" /> [int] **rows**
|
||||
|
||||
| | |
|
||||
|-----------|------------|
|
||||
| *Default* | `2` |
|
||||
| *Setter* | None |
|
||||
| *Getter* | None |
|
||||
|
||||
The number of rows in the terminal's rect.
|
||||
When using a monospace font, this is typically the number of characters that can fit from the top to the bottom.
|
||||
It will automatically update as the Control's rect_size changes, and therefore shouldn't be used to set the size of the terminal directly.
|
||||
|
||||
---
|
||||
|
||||
- <a name="prop-cols" /> [int] **cols**
|
||||
|
||||
| | |
|
||||
|-----------|------------|
|
||||
| *Default* | `2` |
|
||||
| *Setter* | None |
|
||||
| *Getter* | None |
|
||||
|
||||
The number of columns in the terminal's rect.
|
||||
When using a monospace font, this is typically the number of characters that can fit from one side to another.
|
||||
It will automatically update as the Control's rect_size changes, and therefore shouldn't be used to set the size of the terminal directly.
|
||||
|
||||
---
|
||||
|
||||
- <a name="prop-bell_muted" /> [bool] **bell_muted**
|
||||
|
||||
| | |
|
||||
|-----------|---------|
|
||||
| *Default* | `false` |
|
||||
| *Setter* | None |
|
||||
| *Getter* | None |
|
||||
|
||||
If muted, no [`bell`](#sgnl-bell) signal will be emitted when the bell character (`"\u0007"`) is written to the terminal.
|
||||
|
||||
---
|
||||
|
||||
- <a name="prop-bell_cooldown" /> [float] **bell_cooldown**
|
||||
|
||||
| | |
|
||||
|-----------|-------|
|
||||
| *Default* | `0.1` |
|
||||
| *Setter* | None |
|
||||
| *Getter* | None |
|
||||
|
||||
The minimum amount of time to wait before emitting another [`bell`](#sgnl-bell) signal on subsequent writes of the bell character.
|
||||
Writing the bell character too frequently, for example by running the command `while true; do echo -e "\a"; done`,
|
||||
can have a negative impact on performance depending on how the signal is connected.
|
||||
This property allows throttling of that signal.
|
||||
|
||||
---
|
||||
|
||||
- <a name="prop-update_mode" /> [UpdateMode] **update_mode**
|
||||
|
||||
| | |
|
||||
|-----------|------------------------|
|
||||
| *Default* | `AUTO` |
|
||||
| *Setter* | set_update_mode(value) |
|
||||
| *Getter* | None |
|
||||
|
||||
Determines which cells of the terminal will be updated when its state changes.
|
||||
By default `AUTO` will only update cells that changed, but will update all cells (i.e. the entire screen) on major changes,
|
||||
such as terminal resize.
|
||||
If you are having trouble with the terminal not updating correctly or exhibiting artifacts, you can try remedying this by setting `update_mode` to `ALL`, however, this will have a negative impact on performance.
|
||||
|
||||
|
||||
## Method Descriptions
|
||||
|
||||
- <a name="mthd-clear" /> void **clear** **()**
|
||||
|
||||
Removes all but the bottommost row of the terminal including scrollback buffer.
|
||||
|
||||
---
|
||||
|
||||
- <a name="mthd-copy_all" /> String **copy_all** **()**
|
||||
|
||||
Copies all of the text in the terminal including scrollback buffer.
|
||||
|
||||
---
|
||||
|
||||
- <a name="mthd-copy_selection" /> String **copy_selection** **()**
|
||||
|
||||
Copies only selected (i.e. highlighted) text in the terminal.
|
||||
Will return an empty string if nothing is highligted.
|
||||
|
||||
---
|
||||
|
||||
- <a name="mthd-write" /> void **write** **(** [String] \| [PoolByteArray] data **)**
|
||||
|
||||
Writes data to the terminal emulator. Accepts either a [String] or [PoolByteArray].
|
||||
Typically it would be connected to the output of a [PTY]'s [`data_received()`](/api/pty#sgnl-data_received) signal.
|
||||
|
||||
Example:
|
||||
```gdscript
|
||||
$Terminal.write("Hello World")
|
||||
$Terminal.write("Hello World".to_utf8())
|
||||
$Terminal.write(PoolByteArray([0x1b, 0x9e])
|
||||
```
|
||||
|
||||
[AudioStream]: https://docs.godotengine.org/en/stable/classes/class_audiostream.html
|
||||
[CanvasItem]: https://docs.godotengine.org/en/stable/classes/class_canvasitem.html
|
||||
[Color]: https://docs.godotengine.org/en/stable/classes/class_color.html
|
||||
[Control]: https://docs.godotengine.org/en/stable/classes/class_control.html
|
||||
[Font]: https://docs.godotengine.org/en/stable/classes/class_font.html
|
||||
[InputEventKey]: https://docs.godotengine.org/en/stable/classes/class_inputeventkey.html
|
||||
[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html
|
||||
[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html
|
||||
[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html
|
||||
[PTY]: /api/pty
|
||||
[String]: https://docs.godotengine.org/en/stable/classes/class_string.html
|
||||
[UpdateMode]: #enum-update_mode
|
||||
[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html
|
||||
[bool]: https://docs.godotengine.org/en/stable/classes/class_bool.html
|
||||
[float]: https://docs.godotengine.org/en/stable/classes/class_float.html
|
||||
[int]: https://docs.godotengine.org/en/stable/classes/class_int.html
|
||||
Loading…
Add table
Add a link
Reference in a new issue