Commit | Line | Data |
---|---|---|
7d4115a5 KL |
1 | Jexer - Java Text User Interface library |
2 | ======================================== | |
3 | ||
3cb99336 KL |
4 | This library implements a text-based windowing system loosely |
5 | reminiscient of Borland's [Turbo | |
6 | Vision](http://en.wikipedia.org/wiki/Turbo_Vision) system. (For those | |
7 | wishing to use the actual C++ Turbo Vision library, see [Sergio | |
8 | Sigala's C++ version based on the sources released by | |
9 | Borland,](http://tvision.sourceforge.net/) or consider Free Pascal's | |
10 | [Free Vision library.](http://wiki.freepascal.org/Free_Vision)) | |
30bd4abd | 11 | |
4b257bd8 | 12 | Jexer 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 |
34 | Additional backends can be created by subclassing |
35 | jexer.backend.Backend and passing it into the TApplication | |
fe0770f9 | 36 | constructor. See Demo5 and Demo6 for examples of other backends. |
1ac2ccb1 | 37 | |
1c15371a KL |
38 | The Jexer homepage, which includes additional information and binary |
39 | release downloads, is at: https://jexer.sourceforge.io . The Jexer | |
a69ed767 | 40 | source code is hosted at: https://gitlab.com/klamonte/jexer . |
1c15371a | 41 | |
1ac2ccb1 | 42 | |
7d4115a5 KL |
43 | |
44 | License | |
45 | ------- | |
46 | ||
e16dda65 KL |
47 | This project is licensed under the MIT License. See the file LICENSE |
48 | for the full license text. | |
7d4115a5 KL |
49 | |
50 | ||
1596e11a KL |
51 | Maven |
52 | ----- | |
53 | ||
54 | Jexer 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 | |
66 | Acknowledgements | |
67 | ---------------- | |
68 | ||
69 | Jexer makes use of the Terminus TrueType font [made available | |
70 | here](http://files.ax86.net/terminus-ttf/) . | |
71 | ||
72 | ||
73 | ||
7d4115a5 KL |
74 | Usage |
75 | ----- | |
76 | ||
4b257bd8 | 77 | Simply subclass TApplication and then run it in a new thread: |
7d4115a5 KL |
78 | |
79 | ```Java | |
80 | import jexer.*; | |
81 | ||
4b257bd8 | 82 | class 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 |
103 | Similarly, subclass TWindow and add some widgets: |
104 | ||
105 | ```Java | |
106 | class 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 | ||
135 | Put these into a file, compile it with jexer.jar in the classpath, run | |
136 | it 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 | ||
142 | More Examples | |
143 | ------------- | |
144 | ||
145 | The 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 |
155 | jexer.demos contains official demos showing all of the existing UI |
156 | controls. 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 | ||
187 | More 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 |
199 | Terminal Support |
200 | ---------------- | |
201 | ||
202 | The table below lists terminals tested against Jexer's ECMA48/Xterm | |
203 | backend. | |
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 |
224 | 1 - Passes mouse to its host terminal, so will support mouse if the |
225 | host terminal does. | |
9c238a4b KL |
226 | |
227 | 2 - Also fails to filter out sixel data, leaving garbage on screen. | |
228 | ||
229 | 3 - Latest in repository. | |
230 | ||
231 | 4 - Requires TERM=xterm-1003 before starting. | |
232 | ||
f0e0da5b KL |
233 | 5 - Opening image crashes terminal. |
234 | ||
9c238a4b | 235 | |
4b257bd8 KL |
236 | |
237 | System Properties | |
238 | ----------------- | |
239 | ||
240 | The 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 |
298 | Known Issues / Arbitrary Decisions |
299 | ---------------------------------- | |
300 | ||
301 | Some arbitrary design decisions had to be made when either the | |
302 | obviously expected behavior did not happen or when a specification was | |
303 | ambiguous. 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 |
361 | See Also |
362 | -------- | |
363 | ||
364 | [Tranquil Java IDE](https://tjide.sourceforge.io) is a TUI-based | |
365 | integrated development environment for the Java language that was | |
366 | built using a very lightly modified GPL version of Jexer. TJ provided | |
367 | a real-world use case to shake out numerous bugs and limitations of | |
368 | Jexer. | |
c60550e5 KL |
369 | |
370 | ||
371 | ||
372 | Maintainers Wanted | |
373 | ------------------ | |
374 | ||
375 | Both Jexer and TJIDE are seeking additional maintainers. I am not in | |
376 | a position in life to take on significant off-hours programming work, | |
377 | and am willing to hand these projects over to one or more persons with | |
378 | time and interest. | |
379 | ||
380 | My personal code design philosophy for TJIDE/Jexer is outlined at | |
381 | https://gitlab.com/klamonte/tjide/blob/master/java/docs/code_design.txt | |
382 | . I realize that some of the features listed below may require | |
383 | deviations from this philosophy, but this is what I have built so far. | |
384 | ||
385 | Some 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 | ||
413 | These are what I can clearly see right now. Obviously users are | |
414 | capable of finding many more. | |
415 | ||
81377654 | 416 | I intend to continue poking on Jexer and TJIDE, and will maintain a |
c60550e5 KL |
417 | branch to be "the fastest and simplest Java language IDE available", |
418 | which will deliberately remain small. | |
419 | ||
81377654 KL |
420 | I hope that other languages choose to transliterate Jexer to provide |
421 | TUIs to their own platforms. I will be happy to help them understand | |
422 | the code to support those efforts. |