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

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 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 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.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
  - "Smart placement" for new windows

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().
- 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.")
Commit	Line	Data
	1	Jexer - Java Text User Interface library
	2	========================================
	3
	4	WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU
	5	ENCOUNTER THEM.
	6
	7	This library is intended to implement a text-based windowing system
	8	loosely reminiscient of Borland's [Turbo
	9	Vision](http://en.wikipedia.org/wiki/Turbo_Vision) library. For those
	10	wishing to use the actual C++ Turbo Vision library, see [Sergio
	11	Sigala's updated version](http://tvision.sourceforge.net/) that runs
	12	on many more platforms.
	13
	14	Three backends are available:
	15
	16	* System.in/out to a command-line ECMA-48 / ANSI X3.64 type terminal
	17	(tested on Linux + xterm). I/O is handled through terminal escape
	18	sequences generated by the library itself: ncurses is not required
	19	or linked to. xterm mouse tracking using UTF8 and SGR coordinates
	20	are supported. For the demo application, this is the default
	21	backend on non-Windows platforms.
	22
	23	* The same command-line ECMA-48 / ANSI X3.64 type terminal as above,
	24	but to any general InputStream/OutputStream. See the file
	25	jexer.demos.Demo2 for an example of running the demo over a TCP
	26	socket.
	27
	28	* Java Swing UI. This backend can be selected by setting
	29	jexer.Swing=true. The default window size for Swing is 132x40,
	30	which is set in jexer.session.SwingSession. For the demo
	31	application, this is the default backend on Windows platforms.
	32
	33	The demo application showing the existing UI controls can be seen in
	34	three ways:
	35
	36	* 'java -jar jexer.jar' . This will use System.in/out on
	37	non-Windows, or Swing on Windows.
	38
	39	* 'java -Djexer.Swing=true -jar jexer.jar' . This will always use
	40	Swing.
	41
	42	* 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
	43	number to run the TCP daemon on). This will use the telnet
	44	protocol to establish an 8-bit clean channel and be aware of
	45	screen size changes.
	46
	47	Additional backends can be created by subclassing
	48	jexer.backend.Backend and passing it into the TApplication
	49	constructor.
	50
	51
	52
	53	License
	54	-------
	55
	56	This project is licensed LGPL ("GNU Lesser General Public License",
	57	sometimes called the "Library GPL") version 3 or greater. You may
	58	freely use Jexer in both closed source (proprietary) and open source
	59	applications, however any changes you make to the Jexer code must be
	60	made available to your users.
	61
	62	See the file LICENSE for the full license text, which includes both
	63	the GPL v3 and the LGPL supplemental terms.
	64
	65
	66
	67	Acknowledgements
	68	----------------
	69
	70	Jexer makes use of the Terminus TrueType font [made available
	71	here](http://files.ax86.net/terminus-ttf/) .
	72
	73
	74
	75	Usage
	76	-----
	77
	78	Usage patterns are still being worked on, but in general the goal will
	79	be to build applications as follows:
	80
	81	```Java
	82	import jexer.*;
	83
	84	public class MyApplication extends TApplication {
	85
	86	public MyApplication() {
	87	super(BackendType.SWING); // Could also use BackendType.XTERM
	88
	89	// Create standard menus for File and Window
	90	addFileMenu();
	91	addWindowMenu();
	92	}
	93
	94	public static void main(String [] args) {
	95	MyApplication app = new MyApplication();
	96	(new Thread(app)).start();
	97	}
	98	}
	99	```
	100
	101	See the files in jexer.demos for more detailed examples.
	102
	103
	104
	105	Known Issues / Arbitrary Decisions
	106	----------------------------------
	107
	108	Some arbitrary design decisions had to be made when either the
	109	obviously expected behavior did not happen or when a specification was
	110	ambiguous. This section describes such issues.
	111
	112	- TTerminalWindow will hang on input from the remote if the
	113	TApplication is exited before the TTerminalWindow's process has
	114	closed on its own. This is due to a Java limitation/interaction
	115	between blocking reads (which is necessary to get UTF8 translation
	116	correct) and file streams.
	117
	118	- See jexer.tterminal.ECMA48 for more specifics of terminal
	119	emulation limitations.
	120
	121	- TTerminalWindow uses cmd.exe on Windows. Output will not be seen
	122	until enter is pressed, due to cmd.exe's use of line-oriented
	123	input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and
	124	SetConsoleMode()).
	125
	126	- TTerminalWindow launches 'script -fqe /dev/null' on non-Windows
	127	platforms. This is a workaround for the C library behavior of
	128	checking for a tty: script launches $SHELL in a pseudo-tty. This
	129	works on Linux but might not on other Posix-y platforms.
	130
	131	- Java's InputStreamReader as used by the ECMA48 backend requires a
	132	valid UTF-8 stream. The default X10 encoding for mouse
	133	coordinates outside (160,94) can corrupt that stream, at best
	134	putting garbage keyboard events in the input queue but at worst
	135	causing the backend reader thread to throw an Exception and exit
	136	and make the entire UI unusable. Mouse support therefore requires
	137	a terminal that can deliver either UTF-8 coordinates (1005 mode)
	138	or SGR coordinates (1006 mode). Most modern terminals can do
	139	this.
	140
	141	- jexer.session.TTYSession calls 'stty size' once every second to
	142	check the current window size, performing the same function as
	143	ioctl(TIOCGWINSZ) but without requiring a native library.
	144
	145	- jexer.io.ECMA48Terminal calls 'stty' to perform the equivalent of
	146	cfmakeraw() when using System.in/out. System.out is also
	147	(blindly!) put in 'stty sane cooked' mode when exiting.
	148
	149
	150
	151	System Properties
	152	-----------------
	153
	154	The following properties control features of Jexer:
	155
	156	jexer.Swing
	157	-----------
	158
	159	Used only by jexer.demos.Demo1. If true, use the Swing interface
	160	for the demo application. Default: true on Windows platforms
	161	(os.name starts with "Windows"), false on non-Windows platforms.
	162
	163	jexer.Swing.cursorStyle
	164	-----------------------
	165
	166	Used by jexer.io.SwingScreen. Selects the cursor style to draw.
	167	Valid values are: underline, block, outline. Default: underline.
	168
	169
	170
	171	Roadmap
	172	-------
	173
	174	Many tasks remain before calling this version 1.0:
	175
	176	0.0.3: FINISH PORTING
	177
	178	- TTreeView
	179	- Also add keyboard navigation
	180	- TDirectoryList
	181	- Also add keyboard navigation
	182	- TFileOpen
	183
	184	0.0.4: NEW STUFF
	185
	186	- Making TMenu keyboard accelerators active/inactive
	187	- TStatusBar
	188	- TEditor
	189	- TWindow
	190	- "Smart placement" for new windows
	191
	192	0.0.5: BUG HUNT
	193
	194	- TSubMenu keyboard mnemonic not working
	195	- Swing performance. Even with double buffering it isn't great.
	196
	197	0.1.0: BETA RELEASE
	198
	199	- TSpinner
	200	- TComboBox
	201	- TListBox
	202	- TCalendar
	203	- TColorPicker
	204
	205	Wishlist features (2.0):
	206
	207	- TTerminal
	208	- Handle resize events (pass to child process)
	209	- Screen
	210	- Allow complex characters in putCharXY() and detect them in putStrXY().
	211	- Drag and drop
	212	- TEditor
	213	- TField
	214	- TText
	215	- TTerminal
	216	- TComboBox
	217
	218
	219	Screenshots
	220	-----------
	221
	222	![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal")
	223
	224	![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.")