git://git.nikiroo.be / nikiroo-utils.git / blob
WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU ENCOUNTER THEM.
This library is intended to implement a text-based windowing system loosely reminiscient of Borland’s Turbo Vision library. For those wishing to use the actual C++ Turbo Vision library, see Sergio Sigala’s updated version that runs on many more platforms.
Three backends are available:
System.in/out to a command-line ECMA-48 / ANSI X3.64 type terminal (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 using UTF8 and SGR coordinates are supported. For the demo application, this is the default backend on non-Windows platforms.
The same command-line ECMA-48 / ANSI X3.64 type terminal as above, but to any general InputStream/OutputStream. See the file jexer.demos.Demo2 for an example of running the demo over a TCP socket.
Java Swing UI. This backend can be selected by setting jexer.Swing=true. The default window size for Swing is 132x40, which is set in jexer.session.SwingSession. For the demo application, this is the default backend on Windows platforms.
The demo application showing the existing UI controls is available via ‘java -jar jexer.jar’, ‘java -Djexer.Swing=true -jar jexer.jar’, or ‘java -cp jexer.jar jexer.demos.Demo2 PORT’ (where PORT is a number to run the TCP daemon on).
Additional backends can be created by subclassing jexer.backend.Backend and passing it into the TApplication constructor.
This project is licensed LGPL (“GNU Lesser General Public License”, sometimes called the “Library GPL”) version 3 or greater. You may freely use Jexer in both closed source (proprietary) and open source applications, however any changes you make to the Jexer code must be made available to your users.
See the file LICENSE for the full license text, which includes both the GPL v3 and the LGPL supplemental terms.
Jexer makes use of the Terminus TrueType font made available here .
Usage patterns are still being worked on, but in general the goal will be to build applications as follows:
```Java import jexer.*;
public class MyApplication extends TApplication {
public MyApplication() {
super(BackendType.SWING); // Could also use BackendType.XTERM
// Create standard menus for File and Window
addFileMenu();
addWindowMenu();
}
public static void main(String [] args) {
MyApplication app = new MyApplication();
(new Thread(app)).start();
}
} ```
See the files in jexer.demos for more detailed examples.
Some arbitrary design decisions had to be made when either the obviously expected behavior did not happen or when a specification was ambiguous. This section describes such issues.
TTerminalWindow will hang on input from the remote if the TApplication is exited before the TTerminalWindow’s process has closed on its own. This is due to a Java limitation/interaction between blocking reads (which is necessary to get UTF8 translation correct) and file streams.
See jexer.tterminal.ECMA48 for more specifics of terminal emulation limitations.
TTerminalWindow uses cmd.exe on Windows. Output will not be seen until enter is pressed, due to cmd.exe’s use of line-oriented input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and SetConsoleMode()).
TTerminalWindow launches ‘script -fqe /dev/null’ on non-Windows platforms. This is a workaround for the C library behavior of checking for a tty: script launches $SHELL in a pseudo-tty. This works on Linux but might not on other Posix-y platforms.
Java’s InputStreamReader as used by the ECMA48 backend requires a valid UTF-8 stream. The default X10 encoding for mouse coordinates outside (160,94) can corrupt that stream, at best putting garbage keyboard events in the input queue but at worst causing the backend reader thread to throw an Exception and exit and make the entire UI unusable. Mouse support therefore requires a terminal that can deliver either UTF-8 coordinates (1005 mode) or SGR coordinates (1006 mode). Most modern terminals can do this.
jexer.session.TTYSession calls ‘stty size’ once every second to check the current window size, performing the same function as ioctl(TIOCGWINSZ) but without requiring a native library.
jexer.io.ECMA48Terminal calls ‘stty’ to perform the equivalent of cfmakeraw() when using System.in/out. System.out is also (blindly!) put in ‘stty sane cooked’ mode when exiting.
The following properties control features of Jexer:
Used only by jexer.demos.Demo1. If true, use the Swing interface for the demo application. Default: true on Windows platforms (os.name starts with “Windows”), false on non-Windows platforms.
Used by jexer.io.SwingScreen. Selects the cursor style to draw. Valid values are: underline, block, outline. Default: underline.
Many tasks remain before calling this version 1.0:
0.0.3: FINISH PORTING
0.0.4: NEW STUFF
0.0.5: BUG HUNT
0.1.0: BETA RELEASE
Wishlist features (2.0):
