#5 rgbColors fix
[fanfix.git] / README.md
... / ...
CommitLineData
1Jexer - Java Text User Interface library
2========================================
3
4This library implements a text-based windowing system reminiscient of
5Borland's [Turbo Vision](http://en.wikipedia.org/wiki/Turbo_Vision)
6system. (For those wishing to use the actual C++ Turbo Vision
7library, see [Sergio Sigala's C++ version based on the sources
8released by Borland,](http://tvision.sourceforge.net/) or consider
9Free Pascal's [Free Vision
10library.](http://wiki.freepascal.org/Free_Vision))
11
12Jexer currently supports three backends:
13
14* System.in/out to a command-line ECMA-48 / ANSI X3.64 type terminal
15 (tested on Linux + xterm). I/O is handled through terminal escape
16 sequences generated by the library itself: ncurses is not required
17 or linked to. xterm mouse tracking using UTF8 and SGR coordinates
18 are supported. For the demo application, this is the default
19 backend on non-Windows/non-Mac platforms.
20
21* The same command-line ECMA-48 / ANSI X3.64 type terminal as above,
22 but to any general InputStream/OutputStream or Reader/Writer. See
23 the file jexer.demos.Demo2 for an example of running the demo over a
24 TCP socket. jexer.demos.Demo3 demonstrates how one might use a
25 character encoding than the default UTF-8.
26
27* Java Swing UI. This backend can be selected by setting
28 jexer.Swing=true. The default window size for Swing is 80x25, which
29 is set in jexer.session.SwingSession. For the demo application,
30 this is the default backend on Windows and Mac platforms.
31
32Additional backends can be created by subclassing
33jexer.backend.Backend and passing it into the TApplication
34constructor.
35
36The Jexer homepage, which includes additional information and binary
37release downloads, is at: https://jexer.sourceforge.io . The Jexer
38source code is hosted at: https://github.com/klamonte/jexer .
39
40
41
42License
43-------
44
45This project is licensed under the MIT License. See the file LICENSE
46for the full license text.
47
48
49
50Acknowledgements
51----------------
52
53Jexer makes use of the Terminus TrueType font [made available
54here](http://files.ax86.net/terminus-ttf/) .
55
56
57
58Usage
59-----
60
61Simply subclass TApplication and then run it in a new thread:
62
63```Java
64import jexer.*;
65
66class MyApplication extends TApplication {
67
68 public MyApplication() throws Exception {
69 super(BackendType.SWING); // Could also use BackendType.XTERM
70
71 // Create standard menus for File and Window
72 addFileMenu();
73 addWindowMenu();
74
75 // Add a custom window, see below for its code.
76 addWindow(new MyWindow(this));
77 }
78
79 public static void main(String [] args) {
80 try {
81 MyApplication app = new MyApplication();
82 (new Thread(app)).start();
83 } catch (Throwable t) {
84 t.printStackTrace();
85 }
86 }
87}
88```
89
90Similarly, subclass TWindow and add some widgets:
91
92```Java
93class MyWindow extends TWindow {
94
95 public MyWindow(TApplication application) {
96 // See TWindow's API for several constructors. This one uses the
97 // application, title, width, and height. Note that the window width
98 // and height include the borders. The widgets inside the window
99 // will see (0, 0) as the top-left corner inside the borders,
100 // i.e. what the window would see as (1, 1).
101 super(application, "My Window", 30, 20);
102
103 // See TWidget's API for convenience methods to add various kinds of
104 // widgets. Note that ANY widget can be a container for other
105 // widgets: TRadioGroup for example has TRadioButtons as child
106 // widgets.
107
108 // We will add a basic label, text entry field, and button.
109 addLabel("This is a label", 5, 3);
110 addField(5, 5, 20, false, "enter text here");
111 // For the button, we will pop up a message box if the user presses
112 // it.
113 addButton("Press &Me!", 5, 8, new TAction() {
114 public void DO() {
115 MyWindow.this.messageBox("Box Title", "You pressed me, yay!");
116 }
117 } );
118 }
119}
120```
121
122Put these into a file, compile it with jexer.jar in the classpath, run
123it and you'll see an application like this:
124
125![The Example Code Above](/screenshots/readme_application.png?raw=true "The application in the text of README.md")
126
127See the files in jexer.demos for many more detailed examples showing
128all of the existing UI controls. The demo can be run in three
129different ways:
130
131 * 'java -jar jexer.jar' . This will use System.in/out with
132 xterm-like sequences on non-Windows platforms. On Windows it will
133 use a Swing JFrame.
134
135 * 'java -Djexer.Swing=true -jar jexer.jar' . This will always use
136 Swing on any platform.
137
138 * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a
139 number to run the TCP daemon on). This will use the telnet
140 protocol to establish an 8-bit clean channel and be aware of
141 screen size changes.
142
143
144
145More Screenshots
146----------------
147
148![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal")
149
150![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.")
151
152
153
154System Properties
155-----------------
156
157The following properties control features of Jexer:
158
159 jexer.Swing
160 -----------
161
162 Used only by jexer.demos.Demo1. If true, use the Swing interface
163 for the demo application. Default: true on Windows platforms
164 (os.name starts with "Windows"), false on non-Windows platforms.
165
166 jexer.Swing.cursorStyle
167 -----------------------
168
169 Used by jexer.io.SwingScreen. Selects the cursor style to draw.
170 Valid values are: underline, block, outline. Default: underline.
171
172 jexer.Swing.tripleBuffer
173 ------------------------
174
175 Used by jexer.io.SwingScreen. If false, use naive Swing thread
176 drawing. This may be faster on slower systems, but will also be
177 more likely to have screen tearing. Default: true.
178
179
180
181Known Issues / Arbitrary Decisions
182----------------------------------
183
184Some arbitrary design decisions had to be made when either the
185obviously expected behavior did not happen or when a specification was
186ambiguous. This section describes such issues.
187
188 - See jexer.tterminal.ECMA48 for more specifics of terminal
189 emulation limitations.
190
191 - TTerminalWindow uses cmd.exe on Windows. Output will not be seen
192 until enter is pressed, due to cmd.exe's use of line-oriented
193 input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and
194 SetConsoleMode()).
195
196 - TTerminalWindow launches 'script -fqe /dev/null' or 'script -q -F
197 /dev/null' on non-Windows platforms. This is a workaround for the
198 C library behavior of checking for a tty: script launches $SHELL
199 in a pseudo-tty. This works on Linux and Mac but might not on
200 other Posix-y platforms.
201
202 - Closing a TTerminalWindow without exiting the process inside it
203 may result in a zombie 'script' process.
204
205 - Java's InputStreamReader as used by the ECMA48 backend requires a
206 valid UTF-8 stream. The default X10 encoding for mouse
207 coordinates outside (160,94) can corrupt that stream, at best
208 putting garbage keyboard events in the input queue but at worst
209 causing the backend reader thread to throw an Exception and exit
210 and make the entire UI unusable. Mouse support therefore requires
211 a terminal that can deliver either UTF-8 coordinates (1005 mode)
212 or SGR coordinates (1006 mode). Most modern terminals can do
213 this.
214
215 - jexer.session.TTYSession calls 'stty size' once every second to
216 check the current window size, performing the same function as
217 ioctl(TIOCGWINSZ) but without requiring a native library.
218
219 - jexer.io.ECMA48Terminal calls 'stty' to perform the equivalent of
220 cfmakeraw() when using System.in/out. System.out is also
221 (blindly!) put in 'stty sane cooked' mode when exiting.
222
223
224
225Roadmap
226-------
227
228Many tasks remain before calling this version 1.0. See docs/TODO.md
229for the complete list of tasks.