Jexer - Java Text User Interface library
========================================
-This library implements a text-based windowing system reminiscient of
-Borland's [Turbo Vision](http://en.wikipedia.org/wiki/Turbo_Vision)
-system. (For those wishing to use the actual C++ Turbo Vision
-library, see [Sergio Sigala's C++ version based on the sources
-released by Borland,](http://tvision.sourceforge.net/) or consider
-Free Pascal's [Free Vision
-library.](http://wiki.freepascal.org/Free_Vision))
+This library implements a text-based windowing system loosely
+reminiscient of Borland's [Turbo
+Vision](http://en.wikipedia.org/wiki/Turbo_Vision) system. (For those
+wishing to use the actual C++ Turbo Vision library, see [Sergio
+Sigala's C++ version based on the sources released by
+Borland,](http://tvision.sourceforge.net/) or consider Free Pascal's
+[Free Vision library.](http://wiki.freepascal.org/Free_Vision))
Jexer currently supports three backends:
(tested on Linux + xterm). I/O is handled through terminal escape
sequences generated by the library itself: ncurses is not required
or linked to. xterm mouse tracking is supported using both UTF8 and
- SGR coordinates. For the demo application, this is the default
- backend on non-Windows/non-Mac platforms.
+ SGR coordinates. Images are optionally rendered via sixel graphics
+ (see jexer.ECMA48.sixel). For the demo application, this is the
+ default backend on non-Windows/non-Mac platforms.
* The same command-line ECMA-48 / ANSI X3.64 type terminal as above,
but to any general InputStream/OutputStream or Reader/Writer. See
the file jexer.demos.Demo2 for an example of running the demo over a
- TCP socket. jexer.demos.Demo3 demonstrates how one might use a
- character encoding than the default UTF-8.
+ TCP (telnet) socket. jexer.demos.Demo3 demonstrates how one might
+ use a character encoding than the default UTF-8.
* Java Swing UI. The default window size for Swing is 80x25 and 20
point font; this can be changed in the TApplication(BackendType)
for the full license text.
+Maven
+-----
+
+Jexer is available on Maven Central:
+
+```xml
+<dependency>
+ <groupId>com.gitlab.klamonte</groupId>
+ <artifactId>jexer</artifactId>
+ <version>0.3.0</version>
+</dependency>
+```
+
+
Acknowledgements
----------------
new MyWindow(this);
}
- public static void main(String [] args) {
- try {
- MyApplication app = new MyApplication();
- (new Thread(app)).start();
- } catch (Throwable t) {
- t.printStackTrace();
- }
+ public static void main(String [] args) throws Exception {
+ MyApplication app = new MyApplication();
+ (new Thread(app)).start();
}
}
```
-See the files in jexer.demos for many more detailed examples showing
-all of the existing UI controls. The available demos can be run as
-follows:
+
+
+More Examples
+-------------
+
+The examples/ folder currently contains:
+
+ * A [prototype tiling window
+ manager](/examples/JavaTilingWindowManager.java) in less than 250
+ 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
* '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 one
- application performing I/O to two screens: an xterm screen and a
- Swing screen.
+ * '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.
+
+
+
+
System Properties
resize with the window. ptypipe is a separate C language utility,
available at https://gitlab.com/klamonte/ptypipe. Default: false.
+ jexer.TTerminal.closeOnExit
+ ---------------------------
+
+ Used by jexer.TTerminalWindow. If true, close the window when the
+ spawned shell exits. Default: false.
+
jexer.ECMA48.rgbColor
---------------------
colors for normal system colors. This is expensive in bandwidth,
and potentially terrible looking for non-xterms. Default: false.
+ jexer.ECMA48.sixel
+ ------------------
+
+ Used by jexer.backend.ECMA48Terminal. If true, emit image data
+ using sixel, otherwise show blank cells where images could be. This
+ is expensive in bandwidth, very expensive in CPU (especially for
+ large images), and will leave artifacts on the screen if the
+ terminal does not support sixel. Default: true.
+
Known Issues / Arbitrary Decisions
- Closing a TTerminalWindow without exiting the process inside it
may result in a zombie 'script' process.
+ - When using the Swing backend, and not using 'ptypipe', closing a
+ TTerminalWindow without exiting the process inside it may result
+ in a SIGTERM to the JVM causing it to crash. The root cause is
+ currently unknown, but is potentially a bug in more recent
+ releases of the 'script' utility from the util-linux package.
+
- TTerminalWindow can only notify the child process of changes in
window size if using the 'ptypipe' utility, due to Java's lack of
support for forkpty() and similar. ptypipe is available at
equivalent of cfmakeraw() when using System.in/out. System.out is
also (blindly!) put in 'stty sane cooked' mode when exiting.
+ - jexer.backend.ECMA48Terminal uses a single palette containing
+ MAX_COLOR_REGISTERS colors for all sixel images. These colors are
+ generated in the SixelPalette.makePalette() method with bits for
+ hue, saturation, and luminance, and the two extremes set to pure
+ black and pure white. This provides a reasonable general-purpose
+ palette light on CPU, but at a cost that individual images do not
+ look as good as the terminal is actually capable of.
-Roadmap
--------
-Many tasks remain before calling this version 1.0. See docs/TODO.md
-for the complete list of tasks.
+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.
+
+
+
+Maintainers Wanted
+------------------
+
+Both Jexer and TJIDE are seeking additional maintainers. I am not in
+a position in life to take on significant off-hours programming work,
+and am willing to hand these projects over to one or more persons with
+time and interest.
+
+My personal code design philosophy for TJIDE/Jexer is outlined at
+https://gitlab.com/klamonte/tjide/blob/master/java/docs/code_design.txt
+. I realize that some of the features listed below may require
+deviations from this philosophy, but this is what I have built so far.
+
+Some of the areas that will likely require significant efforts are:
+
+ * Editor improvements. The editor is currently very minimalistic,
+ much closer to MS-DOS edit.com than a real programmer's editor.
+ Users will probably desire many more features: drag-and-drop, real
+ syntax or at least regexp highlighting (not just keywords), paren
+ matching, paragraph/comment reflow, and dozens more. The
+ underlying Document/Line/Word model is not going to be sufficient
+ to meet these features.
+
+ * Better Windows and OSX support. It would be nice to ship a
+ jlink'ed JVM on these platforms with the JRE, JDK, and JPDA
+ modules all together. For Windows, it might be preferable to
+ consider doing any of the following: ship a third-party terminal,
+ use PowerShell, or use the newer ConPTY for TTerminalWindow.
+
+ * Bug fixes. The Jexer codebase is quite large despite my best
+ efforts. Bugs are typically very small to fix, but can take some
+ time to find: a simple NPE or AssertionError can sometimes take
+ 4-8 hours to squash. Fortunately, fixing issues in one place has
+ not often led to breakages elsewhere.
+
+ * New Jexer applications. So far as I know, Jexer is the only
+ mouse-supporting full TUI windowing framework with sixel image
+ support in existence. I cannot predict what kinds of applications
+ could be built out of it, and how those needs will push back to
+ the framework.
+
+These are what I can clearly see right now. Obviously users are
+capable of finding many more.
+
+I intend to continue poking on Jexer and TJIDE, and will maintain a
+branch to be "the fastest and simplest Java language IDE available",
+which will deliberately remain small.
+
+I hope that other languages choose to transliterate Jexer to provide
+TUIs to their own platforms. I will be happy to help them understand
+the code to support those efforts.
git://git.nikiroo.be / fanfix.git / blobdiff