Update documentation and LICENSE

Former-commit-id: c66e478484

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Leroy Hopson
+Copyright (c) 2020 Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/contributors)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,36 +1,100 @@
 <img align="left" width="64" height="64" src="icon.png">
 
-# Godot Xterm Native
+# GodotXterm 
 
 ![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)
 ![Godot Version](https://img.shields.io/badge/godot-3.2+-blue.svg)
 ![License](https://img.shields.io/badge/license-MIT-green.svg)
-
+[![Build Status](https://travis-ci.org/lihop/godot-xterm.svg?branch=master)](https://travis-ci.org/lihop/godot-xterm)
-Native implementation of Godot Xterm using GDNative with [libtsm](https://github.com/Aetf/libtsm).
 
 Terminal emulator for Godot using GDNative and [libtsm](https://github.com/Aetf/libtsm).
 
-**Note**: If you are looking for the purely gdscript version of this plugin it was too buggy and slow so is no longer being developed or maintained but can found [here](https://github.com/lihop/godot-xterm/tree/gdscript-unmaintained).
+**Note**: If you are looking for the purely gdscript version of this plugin which was based on Xterm.js, it turned out to be too buggy and slow so is no longer being developed or maintained but can still be found in the [gdscript-unmaintaned](https://github.com/lihop/godot-xterm/tree/gdscript-unmaintained) branch.
 
-## Demo
+![Screenshot of Main Menu Scene](./docs/screenshot.png)
 
-Click the thumbnail to watch a demo video on youtube:
+## Building
 
-[![Demo video thumbnail](https://img.youtube.com/vi/_Tt4eQEBybo/0.jpg)](https://www.youtube.com/watch?v=_Tt4eQEBybo)
+### All Operating Systems
+
+**Important**: The main dependencies of this project are included as git submodules.
+You can install them in this repo after cloning with:
+```
+git submodule update --init --recursive
+```
+In addition to these, you will need some other dependencies including:
+- a C++ compiler (e.g. gcc)
+- ar (part of GNU Binutils)
+- CMake
+- Python
+- SCons
+
+### Operating System Specific
+
+#### NixOS
+On NixOS you can simply run the [build.sh] script in the `addons/godot_xterm/native` directory:
+```
+cd addons/godot_xterm/native
+./build.sh
+```
+All dependencies will be pulled in by nix-shell and the build steps will run.
+
+#### Arch Linux and Ubuntu
+See the [Arch Linux Dockerfile](dockerfiles/archlinux) and [Ubuntu Dockerfile](dockerfiles/ubuntu) for a list of packages that need to be installed. Once installed, run the [build.sh] script from the `addons/godot_xterm/native` directory:
+```
+cd addons/godot_xterm/native
+bash ./build.sh
+```
+Make sure you use `bash` to run the script as the default interpreter is set to nix-shell. 
+
+#### Other
+Other operating systems will probably be similar to the above. When in doubt check the documentation in the submodule repos, the [build.sh] script, and the [SConstruct] file.
 
 ## Usage
 
-### Asciicast (.cast) file importer
+- ### [Terminal](addons/godot_xterm/nodes/terminal/README.md)
-[Asciinema](https://asciinema.org) recordings saved with the `.cast` extension will be automatically imported as animations. They can then be added to AnimationPlayer which is a child of the Terminal node. Playing the animation will play the terminal session recording in the parent Terminal.
+  The main node provided by this plugin.
 
-For an example, see the scene in [/examples/asciicast](/examples/asciicast).
+- ### [Pseudoterminal](addons/godot_xterm/nodes/pseudoterminal/README.md)
+  A node that can be used to connect the Terminal to a shell. Currently Linux only.
+
+  An example of how to use this node with a Terminal can be found in the [terminal scene](examples/terminal).
+
+- ### TPut
+  An incomplete helper class based on the [tput](https://invisible-island.net/ncurses/man/tput.1.html) utility.
+
+  Example: On the command line you can use `tput cup 5 5` to position the cursor at row 5 col 5.
+  In GDScript this utility can be used to similar effect by doing:
+  ```gdscript
+  tput.cup(5, 5)
+  ```
+  Other commands include `tput setaf` to set a foreground color, `tput setab` to set a background color, and many more.
+  But only a few of these have been implemented.
+
+  Its usage is demonstrated in the script for the [menu scene](examples/menu). 
+
+- ### Asciicast (.cast) file importer plugin
+  [Asciinema](https://asciinema.org) recordings saved with the `.cast` extension will be automatically imported as animations. They can then be added to AnimationPlayer which is a child of a Terminal node. Playing the animation will play the terminal session recording in the parent Terminal.
+
+  See the [asciicast scene](examples/asciicast) for an example.
+
+
+## Examples
+There are three example scenes included in this project which you can study to learn more.
+- menu.tscn
+- terminal.tscn
+- asciicast.tscn
 
 ## License
 
 If you contribute code to this project, you are implicitly allowing your code to be distributed under the MIT license.
 You are also implicitly verifying that all code is your original work, or unoriginal work which is published under a compatible license or waiver.
 
-Copyright (c) 2020 Leroy Hopson (MIT License)
+Copyright (c) 2020 [The GodotXterm authors](https://github.com/lihop/godot-xterm/graphs/contributors) (MIT License)<br>
 
 The fonts used in this project are published under a seperate license.
 See the various license files in the [subdirectories](addons/godot_xterm/themes/fonts/) for each font.
+
+
+[build.sh]: /addons/godot_xterm/native/build.sh
+[SConstruct]: /addons/godot_xterm/native/SConstruct

addons/godot_xterm/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 The GodotXterm authors (https://github.com/lihop/godot-xterm/contributors)
+Copyright (c) 2020 Leroy Hopson and [contributors](https://github.com/lihop/godot-xterm/contributors)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

addons/godot_xterm/nodes/pseudoterminal/README.md

@@ -0,0 +1,51 @@
+# Pseudoterminal
+
+**Inherits:** [Node] < [Object]
+
+
+Can be used with the [Terminal] node to get an actual shell. Currently only tested/working on Linux.
+
+## Methods
+
+| Returns | Signature                              |
+|---------|----------------------------------------|
+| void    | write **(** [PoolByteArray] data **)** |
+| void    | resize **(** [Vector2] size **)**      |
+
+## Signals
+
+- **data_sent** **(** [PoolByteArray] data **)**
+
+  Emitted when some data comes out of the pseudoterminal.
+  In a typical setup this signal would be connected to the [Terminal]'s `write()` method.
+
+---
+
+- **exited** **(** [int] status **)**
+
+  Emitted when the pseudoterminal's process (typically a shell like `bash` or `sh`) has exited. `status` is the exit code.
+
+  For example, if you are using the terminal with a `bash` shell, then issuing the  `exit` command would cause this signal to be emitted.
+  ```bash
+  > exit
+  exit
+
+  ```
+
+## Method Descriptions
+
+- void **write** **(** [PoolByteArray] data **)**
+
+  Writes data to the pseudoterminal. In a typical setup this would be connected to the [Terminal]'s `data_sent()` signal.
+
+- void **resize** **(** [Vector2] size **)**
+
+  Used to notify the pseudoterminal about window size changes. In a typical setup it would be connected to the [Terminal]'s `size_changed()` signal.
+
+
+[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html
+[int]: https://docs.godotengine.org/en/stable/classes/class_int.html
+[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html
+[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html
+[Terminal]: ../terminal/README.md
+[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html

addons/godot_xterm/nodes/terminal/README.md

@@ -9,7 +9,7 @@ Terminal emulator.
 
 <img align="right" src="./docs/important_properties.png"/>
 
-- If you are not seeing anything in the terminal check that a theme has been set. If there is no theme, everything will be drawn in black by default.
+- If you are not seeing anything in the terminal check that a theme has been set. If there is no theme, everything will be drawn in black by default. A default theme can be found in the [themes directory](../../themes). 
 - If the terminal isn't responding to keyboard or mouse input check that `focus_mode` is set to `All`, otherwise `_gui_input()` won't be called so no input will be processed.
 
 
@@ -19,15 +19,15 @@ Terminal emulator.
 
 ### (1) User Input
 
-The users enters some data into the terminal, typically by typing something on the keyboard or clicking (and possibly dragging) somewhere on the screen.
+The user enters some data into the terminal, typically by typing something on the keyboard or clicking (and possibly dragging) somewhere on the screen.
-This corresponds to the `_gui_input()` method which is implemented in [terminal.cpp](../native/src/terminal.cpp).
+This corresponds to the `_gui_input()` method which is implemented in [terminal.cpp](./terminal.cpp).
 
 ### (2) Terminal Output
 
 The user input from (1) is processed by the terminal and converted.
-For example, if the user were to press the down key, the terminal would
+For example, if the user were to press the downwards arrow key (↓), the terminal would interpret this
-and the `data_sent` signal would be emitted with the value `"\u001b[A"`.
+and the `data_sent()` signal would be emitted with the value `"\u001b[A"`.
-For a full list of escape sequences ["XTerm Control Sequences"](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html).
+For a full list of escape sequences see ["XTerm Control Sequences"](https://invisible-island.net/xterm/ctlseqs/ctlseqs.html).
 
 ### (3) Terminal Input
 
@@ -36,7 +36,7 @@ In the other direction, characters can be sent to the terminal. This corresponds
 ### (4) Draw
 
 The input from (3) is then intepreted by the terminal and drawn to the screen.
-For example if the string "\u001b[39;m" was written to the terminal, then it would draw some colorful output 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
 
@@ -47,6 +47,11 @@ For example if the string "\u001b[39;m" was written to the terminal, then it wou
 
 ## Methods
 
+| Returns | Signature                                       |
+|---------|-------------------------------------------------|
+| void    | write **(** [String]\|[PoolByteArray] data **)** |
+
+
 ## Theme Properties
 
 | Type    | Name                          | Default                      |
@@ -76,44 +81,63 @@ For example if the string "\u001b[39;m" was written to the terminal, then it wou
 
 ## Signals
 
-- **data_sent** **(** PoolByteArray data **)**
+- **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 or clicking somewhere.
-  It might also occur.
+  Input can be interpreted differently depending on modifier keys and the terminal's settings/state.
-  Depending on several terminal settings can be interpreted differently, depending on modifier keys and the terminals settings/state.
+
-  In a typical setup, this data would be forwarded to the linux operating system.
+  In a typical setup, this data would be forwarded to the pseudoterminal.
 
 ---
 
-- **key_pressed** **(** int row **)**
+- **key_pressed** **(** [String] data, [InputEventKey] event **)**
 
-  Emitted when a key is pressed.
+  Emitted when a key is pressed. `data` is the data that would be emitted by the terminal via the `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.
+
+---
+
+- **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.
 
 ## Property Descriptions
 
 - [int] **rows**
 
   |           |      |
-  |-----------|-----------------|
+  |-----------|------|
   | *Default* | 24   |
-  | *Setter*  | set_rows(value) |
+  | *Setter*  | None |
-  | *Getter*  | get_rows(value) |
+  | *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 one side to another.
+  When using a monospace font, this is typically the number of characters that can fit from the top to the bottom.
-  Therefore it is affected by the things thing.
+  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.
 
 ---
 
 - [int] **cols**
+
+  |           |      |
+  |-----------|------|
+  | *Default* | 80   |
+  | *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.
+
 
 ## Method Descriptions
 
-- void **write** **(** String|PoolByteArray data **)**
+- void **write** **(** [String]|[PoolByteArray] data **)**
 
-  Writes data to the terminal emulator. Accepts either a String or PoolByteArray.
+  Writes data to the terminal emulator. Accepts either a [String] or [PoolByteArray].
+  Typically it would be connected to the output of a pseudoterminal.
 
   Example:
   ```gdscript
@@ -122,10 +146,14 @@ The number of columns in the terminal's rect.
   $Terminal.write(PoolByteArray([0x1b, 0x9e])
   ```
 
-[Control]: https://docs.godotengine.org/en/stable/classes/class_control.html#class-control
+[CanvasItem]: https://docs.godotengine.org/en/stable/classes/class_canvasitem.html
-[CanvasItem]: https://docs.godotengine.org/en/stable/classes/class_canvasitem.html#class-canvasitem
+[Color]: https://docs.godotengine.org/en/stable/classes/class_color.html
-[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html#class-node
+[Control]: https://docs.godotengine.org/en/stable/classes/class_control.html
-[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html#class-object
+[Node]: https://docs.godotengine.org/en/stable/classes/class_node.html
-[Color]: https://docs.godotengine.org/en/stable/classes/class_color.html#class-color
+[Font]: https://docs.godotengine.org/en/stable/classes/class_font.html
-[Font]: https://docs.godotengine.org/en/stable/classes/class_font.html#class-font
+[InputEventKey]: https://docs.godotengine.org/en/stable/classes/class_inputeventkey.html
-[int]: https://docs.godotengine.org/en/stable/classes/class_int.html#class-int
+[int]: https://docs.godotengine.org/en/stable/classes/class_int.html
+[Object]: https://docs.godotengine.org/en/stable/classes/class_object.html
+[PoolByteArray]: https://docs.godotengine.org/en/stable/classes/class_poolbytearray.html
+[String]: https://docs.godotengine.org/en/stable/classes/class_string.html
+[Vector2]: https://docs.godotengine.org/en/stable/classes/class_vector2.html