[fanfix.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 and SGR coordinates
  are 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()).

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

  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'
  -------------

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


Roadmap
-------

Many tasks remain before calling this version 1.0:

0.0.2: STABILIZE EXISTING

- ECMA48Backend running on socket

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

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