Commit | Line | Data |
---|---|---|
7d4115a5 KL |
1 | Jexer - Java Text User Interface library |
2 | ======================================== | |
3 | ||
a4406f4e KL |
4 | WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU |
5 | ENCOUNTER THEM. | |
30bd4abd KL |
6 | |
7 | This library is intended to implement a text-based windowing system | |
8 | loosely reminiscient of Borland's [Turbo | |
9 | Vision](http://en.wikipedia.org/wiki/Turbo_Vision) library. For those | |
10 | wishing to use the actual C++ Turbo Vision library, see [Sergio | |
11 | Sigala's updated version](http://tvision.sourceforge.net/) that runs | |
12 | on many more platforms. | |
7d4115a5 | 13 | |
55b4f29b | 14 | Three backends are available: |
1ac2ccb1 | 15 | |
30bd4abd KL |
16 | * System.in/out to a command-line ECMA-48 / ANSI X3.64 type terminal |
17 | (tested on Linux + xterm). I/O is handled through terminal escape | |
18 | sequences generated by the library itself: ncurses is not required | |
b5f2a6db KL |
19 | or linked to. xterm mouse tracking using UTF8 and SGR coordinates |
20 | are supported. For the demo application, this is the default | |
21 | backend on non-Windows platforms. | |
1ac2ccb1 | 22 | |
55b4f29b KL |
23 | * The same command-line ECMA-48 / ANSI X3.64 type terminal as above, |
24 | but to any general InputStream/OutputStream. See the file | |
25 | jexer.demos.Demo2 for an example of running the demo over a TCP | |
26 | socket. | |
27 | ||
a4406f4e KL |
28 | * Java Swing UI. This backend can be selected by setting |
29 | jexer.Swing=true. The default window size for Swing is 132x40, | |
30 | which is set in jexer.session.SwingSession. For the demo | |
31 | application, this is the default backend on Windows platforms. | |
1ac2ccb1 | 32 | |
9b1afdde KL |
33 | The demo application showing the existing UI controls can be seen in |
34 | three ways: | |
35 | ||
36 | * 'java -jar jexer.jar' . This will use System.in/out on | |
37 | non-Windows, or Swing on Windows. | |
38 | ||
39 | * 'java -Djexer.Swing=true -jar jexer.jar' . This will always use | |
40 | Swing. | |
41 | ||
42 | * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a | |
43 | number to run the TCP daemon on). This will use the telnet | |
44 | protocol to establish an 8-bit clean channel and be aware of | |
45 | screen size changes. | |
a4406f4e KL |
46 | |
47 | Additional backends can be created by subclassing | |
48 | jexer.backend.Backend and passing it into the TApplication | |
49 | constructor. | |
1ac2ccb1 KL |
50 | |
51 | ||
7d4115a5 KL |
52 | |
53 | License | |
54 | ------- | |
55 | ||
5e9795db KL |
56 | This project is licensed LGPL ("GNU Lesser General Public License", |
57 | sometimes called the "Library GPL") version 3 or greater. You may | |
58 | freely use Jexer in both closed source (proprietary) and open source | |
59 | applications, however any changes you make to the Jexer code must be | |
60 | made available to your users. | |
61 | ||
62 | See the file LICENSE for the full license text, which includes both | |
63 | the GPL v3 and the LGPL supplemental terms. | |
7d4115a5 KL |
64 | |
65 | ||
30bd4abd KL |
66 | |
67 | Acknowledgements | |
68 | ---------------- | |
69 | ||
70 | Jexer makes use of the Terminus TrueType font [made available | |
71 | here](http://files.ax86.net/terminus-ttf/) . | |
72 | ||
73 | ||
74 | ||
7d4115a5 KL |
75 | Usage |
76 | ----- | |
77 | ||
30bd4abd | 78 | Usage patterns are still being worked on, but in general the goal will |
a4406f4e | 79 | be to build applications as follows: |
7d4115a5 KL |
80 | |
81 | ```Java | |
82 | import jexer.*; | |
83 | ||
84 | public class MyApplication extends TApplication { | |
85 | ||
86 | public MyApplication() { | |
a4406f4e | 87 | super(BackendType.SWING); // Could also use BackendType.XTERM |
7d4115a5 | 88 | |
fca67db0 KL |
89 | // Create standard menus for File and Window |
90 | addFileMenu(); | |
91 | addWindowMenu(); | |
7d4115a5 KL |
92 | } |
93 | ||
94 | public static void main(String [] args) { | |
fca67db0 | 95 | MyApplication app = new MyApplication(); |
a4406f4e | 96 | (new Thread(app)).start(); |
7d4115a5 KL |
97 | } |
98 | } | |
99 | ``` | |
100 | ||
55b4f29b | 101 | See the files in jexer.demos for more detailed examples. |
30bd4abd KL |
102 | |
103 | ||
7d4115a5 | 104 | |
92554d64 KL |
105 | Known Issues / Arbitrary Decisions |
106 | ---------------------------------- | |
107 | ||
108 | Some arbitrary design decisions had to be made when either the | |
109 | obviously expected behavior did not happen or when a specification was | |
110 | ambiguous. This section describes such issues. | |
111 | ||
bb35d919 | 112 | - TTerminalWindow will hang on input from the remote if the |
69345248 KL |
113 | TApplication is exited before the TTerminalWindow's process has |
114 | closed on its own. This is due to a Java limitation/interaction | |
115 | between blocking reads (which is necessary to get UTF8 translation | |
116 | correct) and file streams. | |
92554d64 | 117 | |
bd8d51fa KL |
118 | - See jexer.tterminal.ECMA48 for more specifics of terminal |
119 | emulation limitations. | |
120 | ||
a4406f4e KL |
121 | - TTerminalWindow uses cmd.exe on Windows. Output will not be seen |
122 | until enter is pressed, due to cmd.exe's use of line-oriented | |
123 | input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and | |
124 | SetConsoleMode()). | |
92554d64 | 125 | |
b5f2a6db KL |
126 | - TTerminalWindow launches 'script -fqe /dev/null' on non-Windows |
127 | platforms. This is a workaround for the C library behavior of | |
128 | checking for a tty: script launches $SHELL in a pseudo-tty. This | |
129 | works on Linux but might not on other Posix-y platforms. | |
130 | ||
e3dfbd23 KL |
131 | - Java's InputStreamReader as used by the ECMA48 backend requires a |
132 | valid UTF-8 stream. The default X10 encoding for mouse | |
133 | coordinates outside (160,94) can corrupt that stream, at best | |
134 | putting garbage keyboard events in the input queue but at worst | |
135 | causing the backend reader thread to throw an Exception and exit | |
136 | and make the entire UI unusable. Mouse support therefore requires | |
137 | a terminal that can deliver either UTF-8 coordinates (1005 mode) | |
138 | or SGR coordinates (1006 mode). Most modern terminals can do | |
139 | this. | |
b5f2a6db KL |
140 | |
141 | - jexer.session.TTYSession calls 'stty size' once every second to | |
142 | check the current window size, performing the same function as | |
143 | ioctl(TIOCGWINSZ) but without requiring a native library. | |
144 | ||
145 | - jexer.io.ECMA48Terminal calls 'stty' to perform the equivalent of | |
55b4f29b KL |
146 | cfmakeraw() when using System.in/out. System.out is also |
147 | (blindly!) put in 'stty sane cooked' mode when exiting. | |
148 | ||
b5f2a6db KL |
149 | |
150 | ||
151 | System Properties | |
152 | ----------------- | |
153 | ||
154 | The following properties control features of Jexer: | |
155 | ||
156 | jexer.Swing | |
157 | ----------- | |
158 | ||
159 | Used only by jexer.demos.Demo1. If true, use the Swing interface | |
160 | for the demo application. Default: true on Windows platforms | |
161 | (os.name starts with "Windows"), false on non-Windows platforms. | |
162 | ||
163 | jexer.Swing.cursorStyle | |
164 | ----------------------- | |
165 | ||
166 | Used by jexer.io.SwingScreen. Selects the cursor style to draw. | |
167 | Valid values are: underline, block, outline. Default: underline. | |
8caf0d51 | 168 | |
36338168 KL |
169 | |
170 | ||
7d4115a5 KL |
171 | Roadmap |
172 | ------- | |
173 | ||
30d336cc | 174 | Many tasks remain before calling this version 1.0: |
7d4115a5 | 175 | |
a4406f4e | 176 | 0.0.3: FINISH PORTING |
7d4115a5 | 177 | |
a4406f4e | 178 | 0.0.4: NEW STUFF |
7d4115a5 | 179 | |
a4406f4e | 180 | - Making TMenu keyboard accelerators active/inactive |
cf9af8df | 181 | - TStatusBar |
cc99cba8 | 182 | - TEditor |
a4406f4e KL |
183 | - TWindow |
184 | - "Smart placement" for new windows | |
cc99cba8 | 185 | |
a4406f4e | 186 | 0.0.5: BUG HUNT |
cc99cba8 | 187 | |
e3dfbd23 | 188 | - Swing performance. Even with double buffering it isn't great. |
9edb442b | 189 | |
a4406f4e | 190 | 0.1.0: BETA RELEASE |
9edb442b | 191 | |
a4406f4e KL |
192 | - TSpinner |
193 | - TComboBox | |
194 | - TListBox | |
195 | - TCalendar | |
196 | - TColorPicker | |
7d4115a5 KL |
197 | |
198 | Wishlist features (2.0): | |
199 | ||
200 | - TTerminal | |
201 | - Handle resize events (pass to child process) | |
7d4115a5 KL |
202 | - Screen |
203 | - Allow complex characters in putCharXY() and detect them in putStrXY(). | |
7d4115a5 KL |
204 | - Drag and drop |
205 | - TEditor | |
206 | - TField | |
207 | - TText | |
208 | - TTerminal | |
209 | - TComboBox | |
92554d64 KL |
210 | |
211 | ||
212 | Screenshots | |
213 | ----------- | |
214 | ||
bb35d919 KL |
215 | ![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal") |
216 | ||
cf9af8df | 217 | ![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.") |