blinking cursor and SGR 1006 mode
[fanfix.git] / README.md
... / ...
CommitLineData
1Jexer - Java Text User Interface library
2========================================
3
4WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU
5ENCOUNTER THEM.
6
7This library is intended to implement a text-based windowing system
8loosely reminiscient of Borland's [Turbo
9Vision](http://en.wikipedia.org/wiki/Turbo_Vision) library. For those
10wishing to use the actual C++ Turbo Vision library, see [Sergio
11Sigala's updated version](http://tvision.sourceforge.net/) that runs
12on many more platforms.
13
14Two 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
28The demo application showing the existing UI controls is available via
29'java -jar jexer.jar' or 'java -Djexer.Swing=true -jar jexer.jar' .
30
31Additional backends can be created by subclassing
32jexer.backend.Backend and passing it into the TApplication
33constructor.
34
35
36
37License
38-------
39
40This project is licensed LGPL ("GNU Lesser General Public License",
41sometimes called the "Library GPL") version 3 or greater. You may
42freely use Jexer in both closed source (proprietary) and open source
43applications, however any changes you make to the Jexer code must be
44made available to your users.
45
46See the file LICENSE for the full license text, which includes both
47the GPL v3 and the LGPL supplemental terms.
48
49
50
51Acknowledgements
52----------------
53
54Jexer makes use of the Terminus TrueType font [made available
55here](http://files.ax86.net/terminus-ttf/) .
56
57
58
59Usage
60-----
61
62Usage patterns are still being worked on, but in general the goal will
63be to build applications as follows:
64
65```Java
66import jexer.*;
67
68public 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
85See the file demos/Demo1.java for detailed examples.
86
87
88
89Known Issues / Arbitrary Decisions
90----------------------------------
91
92Some arbitrary design decisions had to be made when either the
93obviously expected behavior did not happen or when a specification was
94ambiguous. 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
142System Properties
143-----------------
144
145The 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
162Roadmap
163-------
164
165Many tasks remain before calling this version 1.0:
166
1670.0.2: STABILIZE EXISTING
168
169- ECMA48Backend running on socket
170
1710.0.3: FINISH PORTING
172
173- TTreeView
174 - Also add keyboard navigation
175- TDirectoryList
176 - Also add keyboard navigation
177- TFileOpen
178
1790.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
1870.0.5: BUG HUNT
188
189- TSubMenu keyboard mnemonic not working
190
1910.1.0: BETA RELEASE
192
193- TSpinner
194- TComboBox
195- TListBox
196- TCalendar
197- TColorPicker
198
199Wishlist 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
213Screenshots
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.")