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