fix table
[nikiroo-utils.git] / README.md
CommitLineData
7d4115a5
KL
1Jexer - Java Text User Interface library
2========================================
3
3cb99336
KL
4This library implements a text-based windowing system loosely
5reminiscient of Borland's [Turbo
6Vision](http://en.wikipedia.org/wiki/Turbo_Vision) system. (For those
7wishing to use the actual C++ Turbo Vision library, see [Sergio
8Sigala's C++ version based on the sources released by
9Borland,](http://tvision.sourceforge.net/) or consider Free Pascal's
10[Free Vision library.](http://wiki.freepascal.org/Free_Vision))
30bd4abd 11
4b257bd8 12Jexer currently supports three backends:
1ac2ccb1 13
30bd4abd
KL
14* System.in/out to a command-line ECMA-48 / ANSI X3.64 type terminal
15 (tested on Linux + xterm). I/O is handled through terminal escape
16 sequences generated by the library itself: ncurses is not required
a69ed767 17 or linked to. xterm mouse tracking is supported using both UTF8 and
3cb99336
KL
18 SGR coordinates. Images are optionally rendered via sixel graphics
19 (see jexer.ECMA48.sixel). For the demo application, this is the
20 default backend on non-Windows/non-Mac platforms.
1ac2ccb1 21
55b4f29b 22* The same command-line ECMA-48 / ANSI X3.64 type terminal as above,
31b7033c
KL
23 but to any general InputStream/OutputStream or Reader/Writer. See
24 the file jexer.demos.Demo2 for an example of running the demo over a
3cb99336
KL
25 TCP (telnet) socket. jexer.demos.Demo3 demonstrates how one might
26 use a character encoding than the default UTF-8.
55b4f29b 27
c447c6e5
KL
28* Java Swing UI. The default window size for Swing is 80x25 and 20
29 point font; this can be changed in the TApplication(BackendType)
30 constructor. For the demo applications, this is the default backend
31 on Windows and Mac platforms. This backend can be explicitly
32 selected for the demo applications by setting jexer.Swing=true.
1ac2ccb1 33
a4406f4e
KL
34Additional backends can be created by subclassing
35jexer.backend.Backend and passing it into the TApplication
fe0770f9 36constructor. See Demo5 and Demo6 for examples of other backends.
1ac2ccb1 37
1c15371a
KL
38The Jexer homepage, which includes additional information and binary
39release downloads, is at: https://jexer.sourceforge.io . The Jexer
a69ed767 40source code is hosted at: https://gitlab.com/klamonte/jexer .
1c15371a 41
1ac2ccb1 42
7d4115a5
KL
43
44License
45-------
46
e16dda65
KL
47This project is licensed under the MIT License. See the file LICENSE
48for the full license text.
7d4115a5
KL
49
50
1596e11a
KL
51Maven
52-----
53
54Jexer is available on Maven Central:
55
56```xml
57<dependency>
58 <groupId>com.gitlab.klamonte</groupId>
59 <artifactId>jexer</artifactId>
60 <version>0.3.0</version>
61</dependency>
62```
63
64
30bd4abd
KL
65
66Acknowledgements
67----------------
68
69Jexer makes use of the Terminus TrueType font [made available
70here](http://files.ax86.net/terminus-ttf/) .
71
72
73
7d4115a5
KL
74Usage
75-----
76
4b257bd8 77Simply subclass TApplication and then run it in a new thread:
7d4115a5
KL
78
79```Java
80import jexer.*;
81
4b257bd8 82class MyApplication extends TApplication {
7d4115a5 83
4b257bd8 84 public MyApplication() throws Exception {
a4406f4e 85 super(BackendType.SWING); // Could also use BackendType.XTERM
7d4115a5 86
fca67db0
KL
87 // Create standard menus for File and Window
88 addFileMenu();
89 addWindowMenu();
4b257bd8 90
d36057df
KL
91 // Add a custom window, see below for its code. The TWindow
92 // constructor will add it to this application.
93 new MyWindow(this);
7d4115a5
KL
94 }
95
4ac6237d
KL
96 public static void main(String [] args) throws Exception {
97 MyApplication app = new MyApplication();
98 (new Thread(app)).start();
7d4115a5
KL
99 }
100}
101```
102
4b257bd8
KL
103Similarly, subclass TWindow and add some widgets:
104
105```Java
106class MyWindow extends TWindow {
107
108 public MyWindow(TApplication application) {
109 // See TWindow's API for several constructors. This one uses the
110 // application, title, width, and height. Note that the window width
111 // and height include the borders. The widgets inside the window
112 // will see (0, 0) as the top-left corner inside the borders,
113 // i.e. what the window would see as (1, 1).
114 super(application, "My Window", 30, 20);
115
116 // See TWidget's API for convenience methods to add various kinds of
117 // widgets. Note that ANY widget can be a container for other
118 // widgets: TRadioGroup for example has TRadioButtons as child
119 // widgets.
120
121 // We will add a basic label, text entry field, and button.
122 addLabel("This is a label", 5, 3);
123 addField(5, 5, 20, false, "enter text here");
124 // For the button, we will pop up a message box if the user presses
125 // it.
126 addButton("Press &Me!", 5, 8, new TAction() {
127 public void DO() {
128 MyWindow.this.messageBox("Box Title", "You pressed me, yay!");
129 }
130 } );
131 }
132}
133```
134
135Put these into a file, compile it with jexer.jar in the classpath, run
136it and you'll see an application like this:
137
138![The Example Code Above](/screenshots/readme_application.png?raw=true "The application in the text of README.md")
139
528874e2
KL
140
141
142More Examples
143-------------
144
145The examples/ folder currently contains:
146
147 * A [prototype tiling window
d4c334ef 148 manager](/examples/JexerTilingWindowManager.java) in less than 250
528874e2
KL
149 lines of code.
150
5434cb2b
KL
151 * A [prototype image thumbnail
152 viewer](/examples/JexerImageViewer.java) in less than 350 lines of
153 code.
154
528874e2
KL
155jexer.demos contains official demos showing all of the existing UI
156controls. The demos can be run as follows:
4b257bd8
KL
157
158 * 'java -jar jexer.jar' . This will use System.in/out with
92453213
KL
159 xterm-like sequences on non-Windows non-Mac platforms. On Windows
160 and Mac it will use a Swing JFrame.
4b257bd8
KL
161
162 * 'java -Djexer.Swing=true -jar jexer.jar' . This will always use
163 Swing on any platform.
164
165 * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
166 number to run the TCP daemon on). This will use the telnet
167 protocol to establish an 8-bit clean channel and be aware of
168 screen size changes.
169
92453213
KL
170 * 'java -cp jexer.jar jexer.demos.Demo3' . This will use
171 System.in/out with xterm-like sequences. One can see in the code
172 how to pass a different InputReader and OutputReader to
173 TApplication, permitting a different encoding than UTF-8.
174
175 * 'java -cp jexer.jar jexer.demos.Demo4' . This demonstrates hidden
176 windows and a custom TDesktop.
177
88a99379
KL
178 * 'java -cp jexer.jar jexer.demos.Demo5' . This demonstrates two
179 demo applications using different fonts in the same Swing frame.
180
15c86fc2
KL
181 * 'java -cp jexer.jar jexer.demos.Demo6' . This demonstrates two
182 applications performing I/O across three screens: an xterm screen
183 and Swing screen, monitored from a third Swing screen.
88a99379 184
4b257bd8
KL
185
186
187More Screenshots
188----------------
189
190![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal")
191
192![Yo Dawg...](/screenshots/yodawg.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.")
193
3cb99336
KL
194![Sixel Pictures Of Cliffs Of Moher And Buoy](/screenshots/sixel_images.png?raw=true "Sixel Pictures Of Cliffs Of Moher And Buoy")
195
196![Sixel Color Wheel](/screenshots/sixel_color_wheel.png?raw=true "Sixel Color Wheel")
197
4b257bd8 198
9c238a4b
KL
199Terminal Support
200----------------
201
202The table below lists terminals tested against Jexer's ECMA48/Xterm
203backend.
204
205| Terminal | Environment | Mouse Click | Mouse Cursor | Images |
206| -------------- | ------------------ | ----------- | ------------ | ------ |
207| xterm | X11 | yes | yes | yes |
4d184008 208| lcxterm(3) | CLI, Linux console | yes | yes | no |
9c238a4b
KL
209| rxvt-unicode | X11 | yes | yes | no |
210| alacritty(3) | X11 | yes | yes | no |
211| gnome-terminal | X11 | yes | yes | no |
212| xfce4-terminal | X11 | yes | yes | no |
f0e0da5b 213| mlterm | X11 | yes | yes | no(5) |
9c238a4b
KL
214| aminal(3) | X11 | yes | no | no |
215| konsole | X11 | yes | no | no |
216| yakuake | X11 | yes | no | no |
217| screen | CLI | no(1) | no | no(2) |
218| tmux | CLI | no(1) | no | no |
219| putty | X11, Windows | yes | no | no(2) |
220| Linux | Linux console | no | no | no(2) |
221| qodem(3) | CLI, Linux console | yes | yes(4) | no |
4d184008 222| qodem-x11(3) | X11 | yes | no | no |
9c238a4b 223
f0e0da5b
KL
2241 - Passes mouse to its host terminal, so will support mouse if the
225host terminal does.
9c238a4b
KL
226
2272 - Also fails to filter out sixel data, leaving garbage on screen.
228
2293 - Latest in repository.
230
2314 - Requires TERM=xterm-1003 before starting.
232
f0e0da5b
KL
2335 - Opening image crashes terminal.
234
9c238a4b 235
4b257bd8
KL
236
237System Properties
238-----------------
239
240The following properties control features of Jexer:
241
242 jexer.Swing
243 -----------
244
92453213
KL
245 Used only by jexer.demos.Demo1 and jexer.demos.Demo4. If true, use
246 the Swing interface for the demo application. Default: true on
247 Windows (os.name starts with "Windows") and Mac (os.name starts with
248 "Mac"), false on non-Windows and non-Mac platforms.
4b257bd8
KL
249
250 jexer.Swing.cursorStyle
251 -----------------------
252
d79f1f31
KL
253 Used by jexer.backend.SwingTerminal. Selects the cursor style to
254 draw. Valid values are: underline, block, outline. Default:
255 underline.
30bd4abd 256
e685a47d
KL
257 jexer.Swing.tripleBuffer
258 ------------------------
259
d79f1f31
KL
260 Used by jexer.backend.SwingTerminal. If true, use triple-buffering
261 which reduces screen tearing but may also be slower to draw on
262 slower systems. If false, use naive Swing thread drawing, which may
263 be faster on slower systems but also more likely to have screen
92453213 264 tearing. Default: true.
e685a47d 265
1d99a38f
KL
266 jexer.TTerminal.ptypipe
267 -----------------------
268
269 Used by jexer.TTerminalWindow. If true, spawn shell using the
270 'ptypipe' utility rather than 'script'. This permits terminals to
271 resize with the window. ptypipe is a separate C language utility,
a69ed767
KL
272 available at https://gitlab.com/klamonte/ptypipe. Default: false.
273
3cb99336
KL
274 jexer.TTerminal.closeOnExit
275 ---------------------------
276
277 Used by jexer.TTerminalWindow. If true, close the window when the
278 spawned shell exits. Default: false.
279
a69ed767
KL
280 jexer.ECMA48.rgbColor
281 ---------------------
282
283 Used by jexer.backend.ECMA48Terminal. If true, emit T.416-style RGB
284 colors for normal system colors. This is expensive in bandwidth,
285 and potentially terrible looking for non-xterms. Default: false.
1d99a38f 286
3cb99336
KL
287 jexer.ECMA48.sixel
288 ------------------
289
290 Used by jexer.backend.ECMA48Terminal. If true, emit image data
291 using sixel, otherwise show blank cells where images could be. This
292 is expensive in bandwidth, very expensive in CPU (especially for
293 large images), and will leave artifacts on the screen if the
294 terminal does not support sixel. Default: true.
295
30bd4abd 296
7d4115a5 297
92554d64
KL
298Known Issues / Arbitrary Decisions
299----------------------------------
300
301Some arbitrary design decisions had to be made when either the
302obviously expected behavior did not happen or when a specification was
303ambiguous. This section describes such issues.
304
bd8d51fa
KL
305 - See jexer.tterminal.ECMA48 for more specifics of terminal
306 emulation limitations.
307
a4406f4e
KL
308 - TTerminalWindow uses cmd.exe on Windows. Output will not be seen
309 until enter is pressed, due to cmd.exe's use of line-oriented
310 input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and
311 SetConsoleMode()).
92554d64 312
1d99a38f
KL
313 - TTerminalWindow by default launches 'script -fqe /dev/null' or
314 'script -q -F /dev/null' on non-Windows platforms. This is a
315 workaround for the C library behavior of checking for a tty:
316 script launches $SHELL in a pseudo-tty. This works on Linux and
317 Mac but might not on other Posix-y platforms.
b5f2a6db 318
5dfd1c11
KL
319 - Closing a TTerminalWindow without exiting the process inside it
320 may result in a zombie 'script' process.
321
3cb99336
KL
322 - When using the Swing backend, and not using 'ptypipe', closing a
323 TTerminalWindow without exiting the process inside it may result
324 in a SIGTERM to the JVM causing it to crash. The root cause is
325 currently unknown, but is potentially a bug in more recent
326 releases of the 'script' utility from the util-linux package.
327
1d99a38f
KL
328 - TTerminalWindow can only notify the child process of changes in
329 window size if using the 'ptypipe' utility, due to Java's lack of
330 support for forkpty() and similar. ptypipe is available at
a69ed767 331 https://gitlab.com/klamonte/ptypipe.
fe0770f9 332
e3dfbd23
KL
333 - Java's InputStreamReader as used by the ECMA48 backend requires a
334 valid UTF-8 stream. The default X10 encoding for mouse
335 coordinates outside (160,94) can corrupt that stream, at best
336 putting garbage keyboard events in the input queue but at worst
337 causing the backend reader thread to throw an Exception and exit
338 and make the entire UI unusable. Mouse support therefore requires
339 a terminal that can deliver either UTF-8 coordinates (1005 mode)
340 or SGR coordinates (1006 mode). Most modern terminals can do
341 this.
b5f2a6db
KL
342
343 - jexer.session.TTYSession calls 'stty size' once every second to
344 check the current window size, performing the same function as
345 ioctl(TIOCGWINSZ) but without requiring a native library.
346
d79f1f31
KL
347 - jexer.backend.ECMA48Terminal calls 'stty' to perform the
348 equivalent of cfmakeraw() when using System.in/out. System.out is
349 also (blindly!) put in 'stty sane cooked' mode when exiting.
55b4f29b 350
3cb99336
KL
351 - jexer.backend.ECMA48Terminal uses a single palette containing
352 MAX_COLOR_REGISTERS colors for all sixel images. These colors are
353 generated in the SixelPalette.makePalette() method with bits for
354 hue, saturation, and luminance, and the two extremes set to pure
355 black and pure white. This provides a reasonable general-purpose
356 palette light on CPU, but at a cost that individual images do not
357 look as good as the terminal is actually capable of.
b5f2a6db
KL
358
359
7d4115a5 360
3cb99336
KL
361See Also
362--------
363
364[Tranquil Java IDE](https://tjide.sourceforge.io) is a TUI-based
365integrated development environment for the Java language that was
366built using a very lightly modified GPL version of Jexer. TJ provided
367a real-world use case to shake out numerous bugs and limitations of
368Jexer.
c60550e5
KL
369
370
371
372Maintainers Wanted
373------------------
374
375Both Jexer and TJIDE are seeking additional maintainers. I am not in
376a position in life to take on significant off-hours programming work,
377and am willing to hand these projects over to one or more persons with
378time and interest.
379
380My personal code design philosophy for TJIDE/Jexer is outlined at
381https://gitlab.com/klamonte/tjide/blob/master/java/docs/code_design.txt
382. I realize that some of the features listed below may require
383deviations from this philosophy, but this is what I have built so far.
384
385Some of the areas that will likely require significant efforts are:
386
387 * Editor improvements. The editor is currently very minimalistic,
388 much closer to MS-DOS edit.com than a real programmer's editor.
389 Users will probably desire many more features: drag-and-drop, real
390 syntax or at least regexp highlighting (not just keywords), paren
391 matching, paragraph/comment reflow, and dozens more. The
392 underlying Document/Line/Word model is not going to be sufficient
81377654 393 to meet these features.
c60550e5
KL
394
395 * Better Windows and OSX support. It would be nice to ship a
396 jlink'ed JVM on these platforms with the JRE, JDK, and JPDA
397 modules all together. For Windows, it might be preferable to
398 consider doing any of the following: ship a third-party terminal,
399 use PowerShell, or use the newer ConPTY for TTerminalWindow.
400
81377654 401 * Bug fixes. The Jexer codebase is quite large despite my best
c60550e5
KL
402 efforts. Bugs are typically very small to fix, but can take some
403 time to find: a simple NPE or AssertionError can sometimes take
404 4-8 hours to squash. Fortunately, fixing issues in one place has
405 not often led to breakages elsewhere.
406
81377654 407 * New Jexer applications. So far as I know, Jexer is the only
c60550e5
KL
408 mouse-supporting full TUI windowing framework with sixel image
409 support in existence. I cannot predict what kinds of applications
410 could be built out of it, and how those needs will push back to
411 the framework.
412
413These are what I can clearly see right now. Obviously users are
414capable of finding many more.
415
81377654 416I intend to continue poking on Jexer and TJIDE, and will maintain a
c60550e5
KL
417branch to be "the fastest and simplest Java language IDE available",
418which will deliberately remain small.
419
81377654
KL
420I hope that other languages choose to transliterate Jexer to provide
421TUIs to their own platforms. I will be happy to help them understand
422the code to support those efforts.