Commit | Line | Data |
---|---|---|
7d4115a5 KL |
1 | Jexer - Java Text User Interface library |
2 | ======================================== | |
3 | ||
4b257bd8 KL |
4 | This library implements a text-based windowing system reminiscient of |
5 | Borland's [Turbo Vision](http://en.wikipedia.org/wiki/Turbo_Vision) | |
6 | system. (For those wishing to use the actual C++ Turbo Vision | |
7 | library, see [Sergio Sigala's C++ version based on the public domain | |
8 | sources released by Borland.](http://tvision.sourceforge.net/) ) | |
30bd4abd | 9 | |
4b257bd8 | 10 | Jexer currently supports three backends: |
1ac2ccb1 | 11 | |
30bd4abd KL |
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 | |
b5f2a6db KL |
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 platforms. | |
1ac2ccb1 | 18 | |
55b4f29b KL |
19 | * The same command-line ECMA-48 / ANSI X3.64 type terminal as above, |
20 | but to any general InputStream/OutputStream. See the file | |
21 | jexer.demos.Demo2 for an example of running the demo over a TCP | |
22 | socket. | |
23 | ||
a4406f4e KL |
24 | * Java Swing UI. This backend can be selected by setting |
25 | jexer.Swing=true. The default window size for Swing is 132x40, | |
26 | which is set in jexer.session.SwingSession. For the demo | |
27 | application, this is the default backend on Windows platforms. | |
1ac2ccb1 | 28 | |
a4406f4e KL |
29 | Additional backends can be created by subclassing |
30 | jexer.backend.Backend and passing it into the TApplication | |
31 | constructor. | |
1ac2ccb1 KL |
32 | |
33 | ||
7d4115a5 KL |
34 | |
35 | License | |
36 | ------- | |
37 | ||
5e9795db KL |
38 | This project is licensed LGPL ("GNU Lesser General Public License", |
39 | sometimes called the "Library GPL") version 3 or greater. You may | |
40 | freely use Jexer in both closed source (proprietary) and open source | |
41 | applications, however any changes you make to the Jexer code must be | |
42 | made available to your users. | |
43 | ||
44 | See the file LICENSE for the full license text, which includes both | |
45 | the GPL v3 and the LGPL supplemental terms. | |
7d4115a5 KL |
46 | |
47 | ||
30bd4abd KL |
48 | |
49 | Acknowledgements | |
50 | ---------------- | |
51 | ||
52 | Jexer makes use of the Terminus TrueType font [made available | |
53 | here](http://files.ax86.net/terminus-ttf/) . | |
54 | ||
55 | ||
56 | ||
7d4115a5 KL |
57 | Usage |
58 | ----- | |
59 | ||
4b257bd8 | 60 | Simply subclass TApplication and then run it in a new thread: |
7d4115a5 KL |
61 | |
62 | ```Java | |
63 | import jexer.*; | |
64 | ||
4b257bd8 | 65 | class MyApplication extends TApplication { |
7d4115a5 | 66 | |
4b257bd8 | 67 | public MyApplication() throws Exception { |
a4406f4e | 68 | super(BackendType.SWING); // Could also use BackendType.XTERM |
7d4115a5 | 69 | |
fca67db0 KL |
70 | // Create standard menus for File and Window |
71 | addFileMenu(); | |
72 | addWindowMenu(); | |
4b257bd8 KL |
73 | |
74 | // Add a custom window, see below for its code. | |
75 | addWindow(new MyWindow(this)); | |
7d4115a5 KL |
76 | } |
77 | ||
78 | public static void main(String [] args) { | |
4b257bd8 KL |
79 | try { |
80 | MyApplication app = new MyApplication(); | |
81 | (new Thread(app)).start(); | |
82 | } catch (Throwable t) { | |
83 | t.printStackTrace(); | |
84 | } | |
7d4115a5 KL |
85 | } |
86 | } | |
87 | ``` | |
88 | ||
4b257bd8 KL |
89 | Similarly, subclass TWindow and add some widgets: |
90 | ||
91 | ```Java | |
92 | class MyWindow extends TWindow { | |
93 | ||
94 | public MyWindow(TApplication application) { | |
95 | // See TWindow's API for several constructors. This one uses the | |
96 | // application, title, width, and height. Note that the window width | |
97 | // and height include the borders. The widgets inside the window | |
98 | // will see (0, 0) as the top-left corner inside the borders, | |
99 | // i.e. what the window would see as (1, 1). | |
100 | super(application, "My Window", 30, 20); | |
101 | ||
102 | // See TWidget's API for convenience methods to add various kinds of | |
103 | // widgets. Note that ANY widget can be a container for other | |
104 | // widgets: TRadioGroup for example has TRadioButtons as child | |
105 | // widgets. | |
106 | ||
107 | // We will add a basic label, text entry field, and button. | |
108 | addLabel("This is a label", 5, 3); | |
109 | addField(5, 5, 20, false, "enter text here"); | |
110 | // For the button, we will pop up a message box if the user presses | |
111 | // it. | |
112 | addButton("Press &Me!", 5, 8, new TAction() { | |
113 | public void DO() { | |
114 | MyWindow.this.messageBox("Box Title", "You pressed me, yay!"); | |
115 | } | |
116 | } ); | |
117 | } | |
118 | } | |
119 | ``` | |
120 | ||
121 | Put these into a file, compile it with jexer.jar in the classpath, run | |
122 | it and you'll see an application like this: | |
123 | ||
124 | ![The Example Code Above](/screenshots/readme_application.png?raw=true "The application in the text of README.md") | |
125 | ||
126 | See the files in jexer.demos for many more detailed examples showing | |
127 | all of the existing UI controls. The demo can be run in three | |
128 | different ways: | |
129 | ||
130 | * 'java -jar jexer.jar' . This will use System.in/out with | |
131 | xterm-like sequences on non-Windows platforms. On Windows it will | |
132 | use a Swing JFrame. | |
133 | ||
134 | * 'java -Djexer.Swing=true -jar jexer.jar' . This will always use | |
135 | Swing on any platform. | |
136 | ||
137 | * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a | |
138 | number to run the TCP daemon on). This will use the telnet | |
139 | protocol to establish an 8-bit clean channel and be aware of | |
140 | screen size changes. | |
141 | ||
142 | ||
143 | ||
144 | More Screenshots | |
145 | ---------------- | |
146 | ||
147 | ![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal") | |
148 | ||
149 | ![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.") | |
150 | ||
151 | ||
152 | ||
153 | System Properties | |
154 | ----------------- | |
155 | ||
156 | The following properties control features of Jexer: | |
157 | ||
158 | jexer.Swing | |
159 | ----------- | |
160 | ||
161 | Used only by jexer.demos.Demo1. If true, use the Swing interface | |
162 | for the demo application. Default: true on Windows platforms | |
163 | (os.name starts with "Windows"), false on non-Windows platforms. | |
164 | ||
165 | jexer.Swing.cursorStyle | |
166 | ----------------------- | |
167 | ||
168 | Used by jexer.io.SwingScreen. Selects the cursor style to draw. | |
169 | Valid values are: underline, block, outline. Default: underline. | |
30bd4abd KL |
170 | |
171 | ||
7d4115a5 | 172 | |
92554d64 KL |
173 | Known Issues / Arbitrary Decisions |
174 | ---------------------------------- | |
175 | ||
176 | Some arbitrary design decisions had to be made when either the | |
177 | obviously expected behavior did not happen or when a specification was | |
178 | ambiguous. This section describes such issues. | |
179 | ||
bb35d919 | 180 | - TTerminalWindow will hang on input from the remote if the |
69345248 KL |
181 | TApplication is exited before the TTerminalWindow's process has |
182 | closed on its own. This is due to a Java limitation/interaction | |
183 | between blocking reads (which is necessary to get UTF8 translation | |
184 | correct) and file streams. | |
92554d64 | 185 | |
bd8d51fa KL |
186 | - See jexer.tterminal.ECMA48 for more specifics of terminal |
187 | emulation limitations. | |
188 | ||
a4406f4e KL |
189 | - TTerminalWindow uses cmd.exe on Windows. Output will not be seen |
190 | until enter is pressed, due to cmd.exe's use of line-oriented | |
191 | input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and | |
192 | SetConsoleMode()). | |
92554d64 | 193 | |
b5f2a6db KL |
194 | - TTerminalWindow launches 'script -fqe /dev/null' on non-Windows |
195 | platforms. This is a workaround for the C library behavior of | |
196 | checking for a tty: script launches $SHELL in a pseudo-tty. This | |
197 | works on Linux but might not on other Posix-y platforms. | |
198 | ||
e3dfbd23 KL |
199 | - Java's InputStreamReader as used by the ECMA48 backend requires a |
200 | valid UTF-8 stream. The default X10 encoding for mouse | |
201 | coordinates outside (160,94) can corrupt that stream, at best | |
202 | putting garbage keyboard events in the input queue but at worst | |
203 | causing the backend reader thread to throw an Exception and exit | |
204 | and make the entire UI unusable. Mouse support therefore requires | |
205 | a terminal that can deliver either UTF-8 coordinates (1005 mode) | |
206 | or SGR coordinates (1006 mode). Most modern terminals can do | |
207 | this. | |
b5f2a6db KL |
208 | |
209 | - jexer.session.TTYSession calls 'stty size' once every second to | |
210 | check the current window size, performing the same function as | |
211 | ioctl(TIOCGWINSZ) but without requiring a native library. | |
212 | ||
213 | - jexer.io.ECMA48Terminal calls 'stty' to perform the equivalent of | |
55b4f29b KL |
214 | cfmakeraw() when using System.in/out. System.out is also |
215 | (blindly!) put in 'stty sane cooked' mode when exiting. | |
216 | ||
b5f2a6db KL |
217 | |
218 | ||
7d4115a5 KL |
219 | Roadmap |
220 | ------- | |
221 | ||
30d336cc | 222 | Many tasks remain before calling this version 1.0: |
7d4115a5 | 223 | |
4b257bd8 | 224 | 0.0.3 |
7d4115a5 | 225 | |
4b257bd8 KL |
226 | - TListBox |
227 | - TColorPicker | |
228 | ||
229 | 0.0.4 | |
7d4115a5 | 230 | |
cf9af8df | 231 | - TStatusBar |
cc99cba8 | 232 | - TEditor |
a4406f4e KL |
233 | - TWindow |
234 | - "Smart placement" for new windows | |
cc99cba8 | 235 | |
a4406f4e | 236 | 0.0.5: BUG HUNT |
cc99cba8 | 237 | |
e3dfbd23 | 238 | - Swing performance. Even with double buffering it isn't great. |
9edb442b | 239 | |
a4406f4e | 240 | 0.1.0: BETA RELEASE |
9edb442b | 241 | |
a4406f4e KL |
242 | - TSpinner |
243 | - TComboBox | |
a4406f4e | 244 | - TCalendar |
7d4115a5 KL |
245 | |
246 | Wishlist features (2.0): | |
247 | ||
248 | - TTerminal | |
249 | - Handle resize events (pass to child process) | |
7d4115a5 | 250 | - Screen |
4b257bd8 | 251 | - Allow complex characters in putCharXY() and detect them in putStringXY(). |
7d4115a5 KL |
252 | - Drag and drop |
253 | - TEditor | |
254 | - TField | |
255 | - TText | |
256 | - TTerminal | |
257 | - TComboBox |