Jasima/godot-xterm
1
0
Fork 0
mirror of https://github.com/lihop/godot-xterm.git synced 2025-05-03 12:04:24 +02:00
Code Issues Projects Releases Packages Wiki Activity

Add pre-commit config and auto-format files

Browse source
This commit is contained in:
Leroy Hopson 2024-02-13 09:50:18 +13:00
parent 6ce0e6d01c
commit e8650c5bc2
No known key found for this signature in database
GPG key ID: D2747312A6DB51AA
22 changed files with 383 additions and 363 deletions
Download patch file Download diff file Expand all files Collapse all files

63
docs/api/pty.md
View file

@ -10,7 +10,7 @@ permalink: /api/pty
**Inherits:** [Node] < [Object]
*Linux and macOS only.*
_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.
@ -18,36 +18,32 @@ 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
![PTY Diagram](../media/pty_diagram.png)
<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 | [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 **)**
@ -77,28 +73,27 @@ See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
- **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 |
| | |
| --------- | ------------------------ |
| _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.
[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 |
| | |
| --------- | --------------- |
| _Default_ | `80` |
| _Setter_ | set_cols(value) |
| _Getter_ | None |
The column size in characters.
@ -106,11 +101,11 @@ See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
- <a name="prop-rows" /> [int] **rows**
| | |
|-----------|--------------------------|
| *Default* | `24` |
| *Setter* | set_rows(value) |
| *Getter* | None |
| | |
| --------- | --------------- |
| _Default_ | `24` |
| _Setter_ | set_rows(value) |
| _Getter_ | None |
The row size in characters.
@ -119,10 +114,10 @@ See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
- <a name="prop-env" /> [Dictionary] **env**
| | |
|-----------|--------------------------------------------------------|
| *Default* | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
| *Setter* | None |
| *Getter* | None |
| --------- | ------------------------------------------------------ |
| _Default_ | `{ COLORTERM = "truecolor", TERM = "xterm-256color" }` |
| _Setter_ | None |
| _Getter_ | None |
Environment variables to be set for the child program.
@ -131,14 +126,13 @@ See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
- <a name="prop-use_os_env" /> [bool] **use_os_env**
| | |
|-----------|--------|
| *Default* | `true` |
| *Setter* | None |
| *Getter* | None |
| --------- | ------ |
| _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 **)**
@ -184,7 +178,6 @@ See issue [\#25](https://github.com/lihop/godot-xterm/issues/25).
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

76
docs/api/terminal.md
View file

@ -10,13 +10,13 @@ permalink: /api/terminal
**Inherits:** [Control] < [CanvasItem] < [Node] < [Object]
A Terminal emulator Control node.
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
## Overview
![Terminal Flow Diagram](../media/flow_diagram.svg)
<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/>
@ -40,22 +40,20 @@ In the other direction, data can be sent to the terminal. This corresponds to th
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) *(deprecated)* | `2` |
| [int] | [rows](#prop-rows) *(deprecated)* | `2` |
| [int] | [cols](#prop-cols) _(deprecated)_ | `2` |
| [int] | [rows](#prop-rows) _(deprecated)_ | `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) **()** |
@ -63,7 +61,6 @@ For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal
| [int] | [get_rows](#mthd-get_rows) **()** |
| void | [write](#mthd-write) **(** [String] \| [PoolByteArray] data **)** |
## Signals
- <a name="sgnl-bell" /> **bell** **()**
@ -90,46 +87,43 @@ For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal
- <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.
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.
- **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-cols" /> [int] **cols**
| | |
|-----------|------------|
| *Default* | `2` |
| *Setter* | None |
| *Getter* | get_cols() |
| --------- | ---------- |
| _Default_ | `2` |
| _Setter_ | None |
| _Getter_ | get_cols() |
*Deprecated*. This property is deprecated and will be removed in a future version.
_Deprecated_. This property is deprecated and will be removed in a future version.
Please use [get_cols](#mthd-get_cols) instead.
---
- <a name="prop-rows" /> [int] **rows** ***Deprecated***
- <a name="prop-rows" /> [int] **rows** **_Deprecated_**
| | |
|-----------|------------|
| *Default* | `2` |
| *Setter* | None |
| *Getter* | get_rows() |
*Deprecated*. This property is deprecated and will be removed in a future version.
| --------- | ---------- |
| _Default_ | `2` |
| _Setter_ | None |
| _Getter_ | get_rows() |
_Deprecated_. This property is deprecated and will be removed in a future version.
Please use the [get_rows](#mthd-get_rows) instead.
---
@ -137,10 +131,10 @@ For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal
- <a name="prop-bell_muted" /> [bool] **bell_muted**
| | |
|-----------|---------|
| *Default* | `false` |
| *Setter* | None |
| *Getter* | None |
| --------- | ------- |
| _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.
@ -149,10 +143,10 @@ For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal
- <a name="prop-bell_cooldown" /> [float] **bell_cooldown**
| | |
|-----------|-------|
| *Default* | `0.1` |
| *Setter* | None |
| *Getter* | None |
| --------- | ----- |
| _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`,
@ -164,17 +158,16 @@ For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal
- <a name="prop-update_mode" /> [UpdateMode] **update_mode**
| | |
|-----------|------------------------|
| *Default* | `AUTO` |
| *Setter* | set_update_mode(value) |
| *Getter* | None |
| --------- | ---------------------- |
| _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** **()**
@ -218,6 +211,7 @@ For example if the string `"\u001b[38;2;0;255;0;mA"` was written to the terminal
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())