telnet support 75%
[fanfix.git] / README.md
CommitLineData
7d4115a5
KL
1Jexer - Java Text User Interface library
2========================================
3
a4406f4e
KL
4WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU
5ENCOUNTER THEM.
30bd4abd
KL
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.
7d4115a5 13
55b4f29b 14Three backends are available:
1ac2ccb1 15
30bd4abd
KL
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
b5f2a6db
KL
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.
1ac2ccb1 22
55b4f29b
KL
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
a4406f4e
KL
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.
1ac2ccb1 32
a4406f4e 33The demo application showing the existing UI controls is available via
55b4f29b
KL
34'java -jar jexer.jar', 'java -Djexer.Swing=true -jar jexer.jar', or
35'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a number to
36run the TCP daemon on).
a4406f4e
KL
37
38Additional backends can be created by subclassing
39jexer.backend.Backend and passing it into the TApplication
40constructor.
1ac2ccb1
KL
41
42
7d4115a5
KL
43
44License
45-------
46
5e9795db
KL
47This project is licensed LGPL ("GNU Lesser General Public License",
48sometimes called the "Library GPL") version 3 or greater. You may
49freely use Jexer in both closed source (proprietary) and open source
50applications, however any changes you make to the Jexer code must be
51made available to your users.
52
53See the file LICENSE for the full license text, which includes both
54the GPL v3 and the LGPL supplemental terms.
7d4115a5
KL
55
56
30bd4abd
KL
57
58Acknowledgements
59----------------
60
61Jexer makes use of the Terminus TrueType font [made available
62here](http://files.ax86.net/terminus-ttf/) .
63
64
65
7d4115a5
KL
66Usage
67-----
68
30bd4abd 69Usage patterns are still being worked on, but in general the goal will
a4406f4e 70be to build applications as follows:
7d4115a5
KL
71
72```Java
73import jexer.*;
74
75public class MyApplication extends TApplication {
76
77 public MyApplication() {
a4406f4e 78 super(BackendType.SWING); // Could also use BackendType.XTERM
7d4115a5 79
fca67db0
KL
80 // Create standard menus for File and Window
81 addFileMenu();
82 addWindowMenu();
7d4115a5
KL
83 }
84
85 public static void main(String [] args) {
fca67db0 86 MyApplication app = new MyApplication();
a4406f4e 87 (new Thread(app)).start();
7d4115a5
KL
88 }
89}
90```
91
55b4f29b 92See the files in jexer.demos for more detailed examples.
30bd4abd
KL
93
94
7d4115a5 95
92554d64
KL
96Known Issues / Arbitrary Decisions
97----------------------------------
98
99Some arbitrary design decisions had to be made when either the
100obviously expected behavior did not happen or when a specification was
101ambiguous. This section describes such issues.
102
bb35d919 103 - TTerminalWindow will hang on input from the remote if the
69345248
KL
104 TApplication is exited before the TTerminalWindow's process has
105 closed on its own. This is due to a Java limitation/interaction
106 between blocking reads (which is necessary to get UTF8 translation
107 correct) and file streams.
92554d64 108
bd8d51fa
KL
109 - See jexer.tterminal.ECMA48 for more specifics of terminal
110 emulation limitations.
111
a4406f4e
KL
112 - TTerminalWindow uses cmd.exe on Windows. Output will not be seen
113 until enter is pressed, due to cmd.exe's use of line-oriented
114 input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and
115 SetConsoleMode()).
92554d64 116
b5f2a6db
KL
117 - TTerminalWindow launches 'script -fqe /dev/null' on non-Windows
118 platforms. This is a workaround for the C library behavior of
119 checking for a tty: script launches $SHELL in a pseudo-tty. This
120 works on Linux but might not on other Posix-y platforms.
121
e3dfbd23
KL
122 - Java's InputStreamReader as used by the ECMA48 backend requires a
123 valid UTF-8 stream. The default X10 encoding for mouse
124 coordinates outside (160,94) can corrupt that stream, at best
125 putting garbage keyboard events in the input queue but at worst
126 causing the backend reader thread to throw an Exception and exit
127 and make the entire UI unusable. Mouse support therefore requires
128 a terminal that can deliver either UTF-8 coordinates (1005 mode)
129 or SGR coordinates (1006 mode). Most modern terminals can do
130 this.
b5f2a6db
KL
131
132 - jexer.session.TTYSession calls 'stty size' once every second to
133 check the current window size, performing the same function as
134 ioctl(TIOCGWINSZ) but without requiring a native library.
135
136 - jexer.io.ECMA48Terminal calls 'stty' to perform the equivalent of
55b4f29b
KL
137 cfmakeraw() when using System.in/out. System.out is also
138 (blindly!) put in 'stty sane cooked' mode when exiting.
139
b5f2a6db
KL
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.
8caf0d51 159
36338168
KL
160
161
7d4115a5
KL
162Roadmap
163-------
164
30d336cc 165Many tasks remain before calling this version 1.0:
7d4115a5 166
a4406f4e 1670.0.3: FINISH PORTING
7d4115a5 168
a4406f4e
KL
169- TTreeView
170 - Also add keyboard navigation
171- TDirectoryList
172 - Also add keyboard navigation
b5f2a6db 173- TFileOpen
a4406f4e
KL
174
1750.0.4: NEW STUFF
7d4115a5 176
a4406f4e 177- Making TMenu keyboard accelerators active/inactive
cf9af8df 178- TStatusBar
cc99cba8 179- TEditor
a4406f4e
KL
180- TWindow
181 - "Smart placement" for new windows
cc99cba8 182
a4406f4e 1830.0.5: BUG HUNT
cc99cba8 184
a4406f4e 185- TSubMenu keyboard mnemonic not working
e3dfbd23 186- Swing performance. Even with double buffering it isn't great.
9edb442b 187
a4406f4e 1880.1.0: BETA RELEASE
9edb442b 189
a4406f4e
KL
190- TSpinner
191- TComboBox
192- TListBox
193- TCalendar
194- TColorPicker
7d4115a5
KL
195
196Wishlist features (2.0):
197
198- TTerminal
199 - Handle resize events (pass to child process)
7d4115a5
KL
200- Screen
201 - Allow complex characters in putCharXY() and detect them in putStrXY().
7d4115a5
KL
202- Drag and drop
203 - TEditor
204 - TField
205 - TText
206 - TTerminal
207 - TComboBox
92554d64
KL
208
209
210Screenshots
211-----------
212
bb35d919
KL
213![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal")
214
cf9af8df 215![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.")