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