Test commit from within Eclipse

[nikiroo-utils.git] / README.md

Jexer - Java Text User Interface library
========================================

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.

Two 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 coordinates is
  supported.  For the demo application, this is the default backend on
  non-Windows platforms.

* 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.



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.



Acknowledgements
----------------

Jexer makes use of the Terminus TrueType font [made available
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:

```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 file demos/Demo1.java for 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
  ---------------

  - 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()).

  ECMA48 Backend
  --------------
  
  - Mouse support for BackendType.ECMA48/XTERM currently requires UTF-8 
    coordinates (1005 mode).  Terminals that support UTF-8 mouse coordinates
    include xterm, rxvt-unicode, gnome-terminal, and konsole.  Due to Java's
    InputStreamReader requirement of a valid UTF-8 stream, one must assume
    the terminal will always generate correct UTF-8 bytes.  Mode 1006 (SGR)
    will be supported in a future release.



Roadmap
-------

Many tasks remain before calling this version 1.0:

0.0.2: STABILIZE EXISTING

- TTerminalWindow
  - Expose shell commands as properties
- Swing:
  - Blinking cursor
  - Block cursor
- ECMA48Backend running on socket
- TFileOpen
- Decide on naming convention: getText, getValue, getLabel: one or all
  of them?
- Refactor:
  - TKeypress:
    - getCh() --> getChar()
    - getAlt/getCtrl/getShift --> isAltDown / isCtrlDown / isShiftDown
  - Other boolean getters --> isSomething
- Document any properties used
  - Expose use of 'stty'

0.0.3: FINISH PORTING

- TTreeView
  - Also add keyboard navigation
- TDirectoryList
  - Also add keyboard navigation

0.0.4: NEW STUFF

- Making TMenu keyboard accelerators active/inactive
- TStatusBar
- TEditor
- TWindow
  - "Smart placement" for new windows

0.0.5: BUG HUNT

- TSubMenu keyboard mnemonic not working
- ECMA48Terminal
  - Mode 1006 mouse coordinates

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().
- 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.")