[nikiroo-utils.git] / README.md

Jexer - Java Text User Interface library
========================================

This library implements a text-based windowing system loosely
reminiscent of Borland's [Turbo
Vision](http://en.wikipedia.org/wiki/Turbo_Vision) system.  It looks
like this:

![Terminal, Image, Table](/screenshots/new_demo1.png?raw=true "Terminal, Image, Table")

Jexer works on both Xterm-like terminals and Swing, and supports
images in both Xterm and Swing.  On Swing, images are true color:

![Swing Snake Image](/screenshots/snake_swing.png?raw=true "Swing Snake Image")

On Xterm, images are dithered to a common palette:

![Xterm Snake Image](/screenshots/snake_xterm.png?raw=true "Xterm Snake Image")


License
-------

Jexer is available to all under the MIT License.  See the file LICENSE
for the full license text.


Obtaining Jexer
---------------

Jexer is available on Maven Central:

```xml
<dependency>
  <groupId>com.gitlab.klamonte</groupId>
  <artifactId>jexer</artifactId>
  <version>0.3.1</version>
</dependency>
```

Binary releases are available on SourceForge:
https://sourceforge.net/projects/jexer/files/jexer/

The Jexer source code is hosted at: https://gitlab.com/klamonte/jexer


Documentation
-------------

* [Java API Docs](https://jexer.sourceforge.io/apidocs/api/index.html)

* [Wiki](https://gitlab.com/klamonte/jexer/wikis/home)


Programming Examples
--------------------

The examples/ folder currently contains:

  * A [prototype tiling window
    manager](/examples/JexerTilingWindowManager.java) in less than 250
    lines of code.

  * A [prototype image thumbnail
    viewer](/examples/JexerImageViewer.java) in less than 350 lines of
    code.

jexer.demos contains official demos showing all of the existing UI
controls.  The demos can be run as follows:

  * 'java -jar jexer.jar' .  This will use System.in/out with
    Xterm-like sequences on non-Windows non-Mac platforms.  On Windows
    and Mac it will use a Swing JFrame.

  * 'java -Djexer.Swing=true -jar jexer.jar' .  This will always use
    Swing on any platform.

  * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
    number to run the TCP daemon on).  This will use the Xterm backend
    on a telnet server that will update with screen size changes.

  * 'java -cp jexer.jar jexer.demos.Demo3' .  This will use
    System.in/out with Xterm-like sequences.  One can see in the code
    how to pass a different InputReader and OutputReader to
    TApplication, permitting a different encoding than UTF-8.

  * 'java -cp jexer.jar jexer.demos.Demo4' .  This demonstrates hidden
    windows and a custom TDesktop.

  * 'java -cp jexer.jar jexer.demos.Demo5' .  This demonstrates two
    demo applications using different fonts in the same Swing frame.

  * 'java -cp jexer.jar jexer.demos.Demo6' .  This demonstrates two
    applications performing I/O across three screens: an Xterm screen
    and Swing screen, monitored from a third Swing screen.

  * 'java -cp jexer.jar jexer.demos.Demo7' .  This demonstrates the
    BoxLayoutManager, achieving a similar result as the
    javax.swing.BoxLayout apidocs example.


More Screenshots
----------------

![Yo Dawg...](/screenshots/jexer_sixel_in_sixel.png?raw=true "Yo Dawg, I heard you like text windowing systems, so I ran a text windowing system inside your text windowing system so you can have a terminal in your terminal.")

![Sixel Pictures Of Cliffs Of Moher And Buoy](/screenshots/sixel_images.png?raw=true "Sixel Pictures Of Cliffs Of Moher And Buoy")

![Sixel Color Wheel](/screenshots/sixel_color_wheel.png?raw=true "Sixel Color Wheel")


Terminal Support
----------------

The table below lists terminals tested against Jexer's Xterm backend:

| Terminal       | Environment        | Mouse Click | Mouse Cursor | Images |
| -------------- | ------------------ | ----------- | ------------ | ------ |
| xterm          | X11                | yes         | yes          | yes    |
| jexer(3)       | CLI, X11, Windows  | yes         | yes          | yes    |
| mlterm         | X11                | yes         | yes          | yes    |
| lcxterm(3)     | CLI, Linux console | yes         | yes          | no     |
| rxvt-unicode   | X11                | yes         | yes          | no(2)  |
| alacritty(3)   | X11                | yes         | yes          | no     |
| gnome-terminal | X11                | yes         | yes          | no     |
| xfce4-terminal | X11                | yes         | yes          | no     |
| aminal(3)      | X11                | yes         | no           | no     |
| konsole        | X11                | yes         | no           | no     |
| yakuake        | X11                | yes         | no           | no     |
| screen         | CLI                | yes(1)      | yes(1)       | no(2)  |
| tmux           | CLI                | yes(1)      | yes(1)       | no     |
| putty          | X11, Windows       | yes         | no           | no(2)  |
| Linux          | Linux console      | no          | no           | no(2)  |
| qodem(3)       | CLI, Linux console | yes         | yes(4)       | no     |
| qodem-x11(3)   | X11                | yes         | no           | no     |
| yaft           | Linux console (FB) | no          | no           | yes    |

1 - Requires mouse support from host terminal.

2 - Also fails to filter out sixel data, leaving garbage on screen.

3 - Latest in repository.

4 - Requires TERM=xterm-1003 before starting.


See Also
--------

* [Tranquil Java IDE](https://tjide.sourceforge.io) is a TUI-based
  integrated development environment for the Java language that was
  built using a very lightly modified GPL version of Jexer.  TJ
  provided a real-world use case to shake out numerous bugs and
  limitations of Jexer.

* [LCXterm](https://lcxterm.sourceforge.io) is a curses-based terminal
  emulator that allows one to use Jexer with full support on the raw
  Linux console.

* [ptypipe](https://gitlab.com/klamonte/ptypipe) is a small C utility
  that permits a Jexer TTerminalWindow to resize the running shell
  when its window is resized.


Acknowledgements
----------------

Jexer makes use of the Terminus TrueType font [made available
here](http://files.ax86.net/terminus-ttf/) .
Commit	Line	Data
	1	Jexer - Java Text User Interface library
	2	========================================
	3
	4	This library implements a text-based windowing system loosely
	5	reminiscent of Borland's [Turbo
	6	Vision](http://en.wikipedia.org/wiki/Turbo_Vision) system. It looks
	7	like this:
	8
	9	![Terminal, Image, Table](/screenshots/new_demo1.png?raw=true "Terminal, Image, Table")
	10
	11	Jexer works on both Xterm-like terminals and Swing, and supports
	12	images in both Xterm and Swing. On Swing, images are true color:
	13
	14	![Swing Snake Image](/screenshots/snake_swing.png?raw=true "Swing Snake Image")
	15
	16	On Xterm, images are dithered to a common palette:
	17
	18	![Xterm Snake Image](/screenshots/snake_xterm.png?raw=true "Xterm Snake Image")
	19
	20
	21
	22	License
	23	-------
	24
	25	Jexer is available to all under the MIT License. See the file LICENSE
	26	for the full license text.
	27
	28
	29
	30	Obtaining Jexer
	31	---------------
	32
	33	Jexer is available on Maven Central:
	34
	35	```xml
	36	<dependency>
	37	<groupId>com.gitlab.klamonte</groupId>
	38	<artifactId>jexer</artifactId>
	39	<version>0.3.1</version>
	40	</dependency>
	41	```
	42
	43	Binary releases are available on SourceForge:
	44	https://sourceforge.net/projects/jexer/files/jexer/
	45
	46	The Jexer source code is hosted at: https://gitlab.com/klamonte/jexer
	47
	48
	49
	50	Documentation
	51	-------------
	52
	53	* [Java API Docs](https://jexer.sourceforge.io/apidocs/api/index.html)
	54
	55	* [Wiki](https://gitlab.com/klamonte/jexer/wikis/home)
	56
	57
	58
	59	Programming Examples
	60	--------------------
	61
	62	The examples/ folder currently contains:
	63
	64	* A [prototype tiling window
	65	manager](/examples/JexerTilingWindowManager.java) in less than 250
	66	lines of code.
	67
	68	* A [prototype image thumbnail
	69	viewer](/examples/JexerImageViewer.java) in less than 350 lines of
	70	code.
	71
	72	jexer.demos contains official demos showing all of the existing UI
	73	controls. The demos can be run as follows:
	74
	75	* 'java -jar jexer.jar' . This will use System.in/out with
	76	Xterm-like sequences on non-Windows non-Mac platforms. On Windows
	77	and Mac it will use a Swing JFrame.
	78
	79	* 'java -Djexer.Swing=true -jar jexer.jar' . This will always use
	80	Swing on any platform.
	81
	82	* 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
	83	number to run the TCP daemon on). This will use the Xterm backend
	84	on a telnet server that will update with screen size changes.
	85
	86	* 'java -cp jexer.jar jexer.demos.Demo3' . This will use
	87	System.in/out with Xterm-like sequences. One can see in the code
	88	how to pass a different InputReader and OutputReader to
	89	TApplication, permitting a different encoding than UTF-8.
	90
	91	* 'java -cp jexer.jar jexer.demos.Demo4' . This demonstrates hidden
	92	windows and a custom TDesktop.
	93
	94	* 'java -cp jexer.jar jexer.demos.Demo5' . This demonstrates two
	95	demo applications using different fonts in the same Swing frame.
	96
	97	* 'java -cp jexer.jar jexer.demos.Demo6' . This demonstrates two
	98	applications performing I/O across three screens: an Xterm screen
	99	and Swing screen, monitored from a third Swing screen.
	100
	101	* 'java -cp jexer.jar jexer.demos.Demo7' . This demonstrates the
	102	BoxLayoutManager, achieving a similar result as the
	103	javax.swing.BoxLayout apidocs example.
	104
	105
	106
	107	More Screenshots
	108	----------------
	109
	110	![Yo Dawg...](/screenshots/jexer_sixel_in_sixel.png?raw=true "Yo Dawg, I heard you like text windowing systems, so I ran a text windowing system inside your text windowing system so you can have a terminal in your terminal.")
	111
	112	![Sixel Pictures Of Cliffs Of Moher And Buoy](/screenshots/sixel_images.png?raw=true "Sixel Pictures Of Cliffs Of Moher And Buoy")
	113
	114	![Sixel Color Wheel](/screenshots/sixel_color_wheel.png?raw=true "Sixel Color Wheel")
	115
	116
	117
	118	Terminal Support
	119	----------------
	120
	121	The table below lists terminals tested against Jexer's Xterm backend:
	122
	123	\| Terminal \| Environment \| Mouse Click \| Mouse Cursor \| Images \|
	124	\| -------------- \| ------------------ \| ----------- \| ------------ \| ------ \|
	125	\| xterm \| X11 \| yes \| yes \| yes \|
	126	\| jexer(3) \| CLI, X11, Windows \| yes \| yes \| yes \|
	127	\| mlterm \| X11 \| yes \| yes \| yes \|
	128	\| lcxterm(3) \| CLI, Linux console \| yes \| yes \| no \|
	129	\| rxvt-unicode \| X11 \| yes \| yes \| no(2) \|
	130	\| alacritty(3) \| X11 \| yes \| yes \| no \|
	131	\| gnome-terminal \| X11 \| yes \| yes \| no \|
	132	\| xfce4-terminal \| X11 \| yes \| yes \| no \|
	133	\| aminal(3) \| X11 \| yes \| no \| no \|
	134	\| konsole \| X11 \| yes \| no \| no \|
	135	\| yakuake \| X11 \| yes \| no \| no \|
	136	\| screen \| CLI \| yes(1) \| yes(1) \| no(2) \|
	137	\| tmux \| CLI \| yes(1) \| yes(1) \| no \|
	138	\| putty \| X11, Windows \| yes \| no \| no(2) \|
	139	\| Linux \| Linux console \| no \| no \| no(2) \|
	140	\| qodem(3) \| CLI, Linux console \| yes \| yes(4) \| no \|
	141	\| qodem-x11(3) \| X11 \| yes \| no \| no \|
	142	\| yaft \| Linux console (FB) \| no \| no \| yes \|
	143
	144	1 - Requires mouse support from host terminal.
	145
	146	2 - Also fails to filter out sixel data, leaving garbage on screen.
	147
	148	3 - Latest in repository.
	149
	150	4 - Requires TERM=xterm-1003 before starting.
	151
	152
	153
	154	See Also
	155	--------
	156
	157	* [Tranquil Java IDE](https://tjide.sourceforge.io) is a TUI-based
	158	integrated development environment for the Java language that was
	159	built using a very lightly modified GPL version of Jexer. TJ
	160	provided a real-world use case to shake out numerous bugs and
	161	limitations of Jexer.
	162
	163	* [LCXterm](https://lcxterm.sourceforge.io) is a curses-based terminal
	164	emulator that allows one to use Jexer with full support on the raw
	165	Linux console.
	166
	167	* [ptypipe](https://gitlab.com/klamonte/ptypipe) is a small C utility
	168	that permits a Jexer TTerminalWindow to resize the running shell
	169	when its window is resized.
	170
	171
	172
	173	Acknowledgements
	174	----------------
	175
	176	Jexer makes use of the Terminus TrueType font [made available
	177	here](http://files.ax86.net/terminus-ttf/) .