X-Git-Url: http://git.nikiroo.be/?a=blobdiff_plain;f=README.md;h=f902ad84790762e15d2cf5bad0953c00a338ecc1;hb=e16dda65585466c8987bd1efd718431450a96605;hp=1e1bb544bbaa83f05eda45babc25eef10c57b1dc;hpb=b5f2a6dbf2f2b925007a85f68665103ec3514f84;p=nikiroo-utils.git diff --git a/README.md b/README.md index 1e1bb54..f902ad8 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,13 @@ Jexer - Java Text User Interface library ======================================== -WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU -ENCOUNTER THEM. +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 public domain +sources released by Borland.](http://tvision.sourceforge.net/) ) -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. - -Two backends are available: +Jexer currently supports three backends: * 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 @@ -20,14 +16,16 @@ Two backends are available: 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' or 'java -Djexer.Swing=true -jar jexer.jar' . - Additional backends can be created by subclassing jexer.backend.Backend and passing it into the TApplication constructor. @@ -37,14 +35,8 @@ constructor. License ------- -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. +This project is licensed under the MIT License. See the file LICENSE +for the full license text. @@ -59,30 +51,116 @@ here](http://files.ax86.net/terminus-ttf/) . Usage ----- -Usage patterns are still being worked on, but in general the goal will -be to build applications as follows: +Simply subclass TApplication and then run it in a new thread: ```Java import jexer.*; -public class MyApplication extends TApplication { +class MyApplication extends TApplication { - public MyApplication() { + public MyApplication() throws Exception { super(BackendType.SWING); // Could also use BackendType.XTERM // Create standard menus for File and Window addFileMenu(); addWindowMenu(); + + // Add a custom window, see below for its code. + addWindow(new MyWindow(this)); } public static void main(String [] args) { - MyApplication app = new MyApplication(); - (new Thread(app)).start(); + try { + MyApplication app = new MyApplication(); + (new Thread(app)).start(); + } catch (Throwable t) { + t.printStackTrace(); + } } } ``` -See the file demos/Demo1.java for detailed examples. +Similarly, subclass TWindow and add some widgets: + +```Java +class MyWindow extends TWindow { + + public MyWindow(TApplication application) { + // See TWindow's API for several constructors. This one uses the + // application, title, width, and height. Note that the window width + // and height include the borders. The widgets inside the window + // will see (0, 0) as the top-left corner inside the borders, + // i.e. what the window would see as (1, 1). + super(application, "My Window", 30, 20); + + // See TWidget's API for convenience methods to add various kinds of + // widgets. Note that ANY widget can be a container for other + // widgets: TRadioGroup for example has TRadioButtons as child + // widgets. + + // We will add a basic label, text entry field, and button. + addLabel("This is a label", 5, 3); + addField(5, 5, 20, false, "enter text here"); + // For the button, we will pop up a message box if the user presses + // it. + addButton("Press &Me!", 5, 8, new TAction() { + public void DO() { + MyWindow.this.messageBox("Box Title", "You pressed me, yay!"); + } + } ); + } +} +``` + +Put these into a file, compile it with jexer.jar in the classpath, run +it and you'll see an application like this: + +![The Example Code Above](/screenshots/readme_application.png?raw=true "The application in the text of README.md") + +See the files in jexer.demos for many more detailed examples showing +all of the existing UI controls. The demo can be run in three +different ways: + + * 'java -jar jexer.jar' . This will use System.in/out with + xterm-like sequences on non-Windows platforms. On Windows it will + use a Swing JFrame. + + * 'java -Djexer.Swing=true -jar jexer.jar' . This will always use + Swing on any platform. + + * '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. + + + +More Screenshots +---------------- + +![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal") + +![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.") + + + +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. @@ -93,9 +171,6 @@ 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 - --------------- - - 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 @@ -115,47 +190,23 @@ ambiguous. This section describes such issues. checking for a tty: script launches $SHELL in a pseudo-tty. This works on Linux but might not on other Posix-y platforms. - ECMA48 Backend - -------------- - - - Java's InputStreamReader 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. - - Use of 'stty' - ------------- + - 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(). The terminal is (blindly!) put back 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. + cfmakeraw() when using System.in/out. System.out is also + (blindly!) put in 'stty sane cooked' mode when exiting. @@ -164,21 +215,8 @@ Roadmap Many tasks remain before calling this version 1.0: -0.0.2: STABILIZE EXISTING - -- ECMA48Backend running on socket +0.0.4 -0.0.3: FINISH PORTING - -- TTreeView - - Also add keyboard navigation -- TDirectoryList - - Also add keyboard navigation -- TFileOpen - -0.0.4: NEW STUFF - -- Making TMenu keyboard accelerators active/inactive - TStatusBar - TEditor - TWindow @@ -186,33 +224,23 @@ Many tasks remain before calling this version 1.0: 0.0.5: BUG HUNT -- TSubMenu keyboard mnemonic not working +- Swing performance. Even with double buffering it isn't great. 0.1.0: BETA RELEASE - TSpinner - TComboBox -- TListBox - TCalendar -- TColorPicker Wishlist features (2.0): - TTerminal - Handle resize events (pass to child process) - Screen - - Allow complex characters in putCharXY() and detect them in putStrXY(). + - Allow complex characters in putCharXY() and detect them in putStringXY(). - Drag and drop - TEditor - TField - TText - TTerminal - TComboBox - - -Screenshots ------------ - -![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal") - -![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.")