Jexer - Java Text User Interface library
========================================
-This library is currently in design, but when finished it is intended
-to implement a text-based windowing system loosely reminiscient of
-Borland's [Turbo Vision](http://en.wikipedia.org/wiki/Turbo_Vision)
-library. For those wishing to use the actual C++ Turbo Vision
-library, see [Sergio Sigala's updated
-version](http://tvision.sourceforge.net/) that runs on many more
-platforms.
+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](http://en.wikipedia.org/wiki/Turbo_Vision) library. For those
+wishing to use the actual C++ Turbo Vision library, see [Sergio
+Sigala's updated version](http://tvision.sourceforge.net/) 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 can be seen in
+three ways:
+
+ * 'java -jar jexer.jar' . This will use System.in/out on
+ non-Windows, or Swing on Windows.
+
+ * 'java -Djexer.Swing=true -jar jexer.jar' . This will always use
+ Swing.
+
+ * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
+ number to run the TCP daemon on). This will use the telnet
+ protocol to establish an 8-bit clean channel and be aware of
+ screen size changes.
+
+Additional backends can be created by subclassing
+jexer.backend.Backend and passing it into the TApplication
+constructor.
+
License
-------
-This library is licensed LGPL ("GNU Lesser General Public License")
-version 3 or greater. See the file LICENSE for the full license text,
-which includes both the GPL v3 and the LGPL supplemental terms.
+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.
+
+
+
+Acknowledgements
+----------------
+
+Jexer makes use of the Terminus TrueType font [made available
+here](http://files.ax86.net/terminus-ttf/) .
+
Usage
-----
-The library is currently under initial development, usage patterns are
-still being worked on. Generally the goal will be to build
-applications somewhat as follows:
+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();
-
- // Create an editor window that has support for
- // copy/paste, search text, arrow keys, horizontal
- // and vertical scrollbar, etc.
- addEditor();
+ super(BackendType.SWING); // Could also use BackendType.XTERM
// Create standard menus for File and Window
addFileMenu();
public static void main(String [] args) {
MyApplication app = new MyApplication();
- app.run();
+ (new Thread(app)).start();
}
}
```
+See the files in jexer.demos for more detailed examples.
+
+
+
+Known Issues / Arbitrary Decisions
+----------------------------------
+
+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.
+
+
+
+System Properties
+-----------------
+
+The following properties control features of Jexer:
+
+ jexer.Swing
+ -----------
+
+ 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.
+
+ jexer.Swing.cursorStyle
+ -----------------------
+
+ Used by jexer.io.SwingScreen. Selects the cursor style to draw.
+ Valid values are: underline, block, outline. Default: underline.
+
+
Roadmap
-------
Many tasks remain before calling this version 1.0:
-0.0.1:
+0.0.3: FINISH PORTING
-- TDirectoryList
-- TField
-- TMessageBox
-- THScroller / TVScroller
-- TText
- TTreeView
+ - Also add keyboard navigation
+- TDirectoryList
+ - Also add keyboard navigation
+- TFileOpen
-0.0.2:
+0.0.4: NEW STUFF
+- Making TMenu keyboard accelerators active/inactive
+- TStatusBar
- TEditor
-- TFileOpen
-- TTerminal
+- TWindow
+ - "Smart placement" for new windows
-0.0.3:
+0.0.5: BUG HUNT
-- Bugs
- - TSubMenu keyboard mnemonic not working
- - kbDel assertion failure in TMenu (MID_CLEAR)
-- TEditor
- - Word wrap
- - Forward/backward word
- - Search
- - Replace
- - Cut/Copy/Paste
+- TSubMenu keyboard mnemonic not working
+- Swing performance. Even with double buffering it isn't great.
-0.0.4:
+0.1.0: BETA RELEASE
-- ECMATerminal
- - Mouse 1006 mode parsing
-- Bugs
- - TDirectoryList cannot be navigated only with keyboard
- - TTreeView cannot be navigated only with keyboard
- - RangeViolation after dragging scrollbar up/down
+- TSpinner
+- TComboBox
+- TListBox
+- TCalendar
+- TColorPicker
Wishlist features (2.0):
- TTerminal
- Handle resize events (pass to child process)
- - xterm mouse handling
-- TWindow
- - "Smart placement" for new windows
- Screen
- Allow complex characters in putCharXY() and detect them in putStrXY().
-- TComboBox
-- TListBox
-- TSpinner
-- TCalendar widget
-- TColorPicker widget
- Drag and drop
- TEditor
- TField
- TText
- TTerminal
- TComboBox
-- AWTBackend
+
+
+Screenshots
+-----------
+
+
+
+
git://git.nikiroo.be / nikiroo-utils.git / blobdiff