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