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 | |
1ac2ccb1 KL |
14 | Two backends are available: |
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 | |
19 | or linked to. xterm mouse tracking using UTF8 coordinates is | |
a4406f4e KL |
20 | supported. For the demo application, this is the default backend on |
21 | non-Windows platforms. | |
1ac2ccb1 | 22 | |
a4406f4e KL |
23 | * Java Swing UI. This backend can be selected by setting |
24 | jexer.Swing=true. The default window size for Swing is 132x40, | |
25 | which is set in jexer.session.SwingSession. For the demo | |
26 | application, this is the default backend on Windows platforms. | |
1ac2ccb1 | 27 | |
a4406f4e KL |
28 | The demo application showing the existing UI controls is available via |
29 | 'java -jar jexer.jar' or 'java -Djexer.Swing=true -jar jexer.jar' . | |
30 | ||
31 | Additional backends can be created by subclassing | |
32 | jexer.backend.Backend and passing it into the TApplication | |
33 | constructor. | |
1ac2ccb1 KL |
34 | |
35 | ||
7d4115a5 KL |
36 | |
37 | License | |
38 | ------- | |
39 | ||
5e9795db KL |
40 | This project is licensed LGPL ("GNU Lesser General Public License", |
41 | sometimes called the "Library GPL") version 3 or greater. You may | |
42 | freely use Jexer in both closed source (proprietary) and open source | |
43 | applications, however any changes you make to the Jexer code must be | |
44 | made available to your users. | |
45 | ||
46 | See the file LICENSE for the full license text, which includes both | |
47 | the GPL v3 and the LGPL supplemental terms. | |
7d4115a5 KL |
48 | |
49 | ||
30bd4abd KL |
50 | |
51 | Acknowledgements | |
52 | ---------------- | |
53 | ||
54 | Jexer makes use of the Terminus TrueType font [made available | |
55 | here](http://files.ax86.net/terminus-ttf/) . | |
56 | ||
57 | ||
58 | ||
7d4115a5 KL |
59 | Usage |
60 | ----- | |
61 | ||
30bd4abd | 62 | Usage patterns are still being worked on, but in general the goal will |
a4406f4e | 63 | be to build applications as follows: |
7d4115a5 KL |
64 | |
65 | ```Java | |
66 | import jexer.*; | |
67 | ||
68 | public class MyApplication extends TApplication { | |
69 | ||
70 | public MyApplication() { | |
a4406f4e | 71 | super(BackendType.SWING); // Could also use BackendType.XTERM |
7d4115a5 | 72 | |
fca67db0 KL |
73 | // Create standard menus for File and Window |
74 | addFileMenu(); | |
75 | addWindowMenu(); | |
7d4115a5 KL |
76 | } |
77 | ||
78 | public static void main(String [] args) { | |
fca67db0 | 79 | MyApplication app = new MyApplication(); |
a4406f4e | 80 | (new Thread(app)).start(); |
7d4115a5 KL |
81 | } |
82 | } | |
83 | ``` | |
84 | ||
87a17f3c | 85 | See the file demos/Demo1.java for detailed examples. |
30bd4abd KL |
86 | |
87 | ||
7d4115a5 | 88 | |
92554d64 KL |
89 | Known Issues / Arbitrary Decisions |
90 | ---------------------------------- | |
91 | ||
92 | Some arbitrary design decisions had to be made when either the | |
93 | obviously expected behavior did not happen or when a specification was | |
94 | ambiguous. This section describes such issues. | |
95 | ||
bb35d919 KL |
96 | TTerminalWindow |
97 | --------------- | |
98 | ||
99 | - TTerminalWindow will hang on input from the remote if the | |
69345248 KL |
100 | TApplication is exited before the TTerminalWindow's process has |
101 | closed on its own. This is due to a Java limitation/interaction | |
102 | between blocking reads (which is necessary to get UTF8 translation | |
103 | correct) and file streams. | |
92554d64 | 104 | |
bd8d51fa KL |
105 | - See jexer.tterminal.ECMA48 for more specifics of terminal |
106 | emulation limitations. | |
107 | ||
a4406f4e KL |
108 | - TTerminalWindow uses cmd.exe on Windows. Output will not be seen |
109 | until enter is pressed, due to cmd.exe's use of line-oriented | |
110 | input (see the ENABLE_LINE_INPUT flag for GetConsoleMode() and | |
111 | SetConsoleMode()). | |
92554d64 | 112 | |
36338168 KL |
113 | |
114 | ||
7d4115a5 KL |
115 | Roadmap |
116 | ------- | |
117 | ||
30d336cc | 118 | Many tasks remain before calling this version 1.0: |
7d4115a5 | 119 | |
a4406f4e | 120 | 0.0.2: STABILIZE EXISTING |
7d4115a5 | 121 | |
a4406f4e KL |
122 | - TTerminalWindow |
123 | - Expose shell commands as properties | |
124 | - Swing: | |
30bd4abd | 125 | - Blinking cursor |
69345248 | 126 | - Block cursor |
1ac2ccb1 | 127 | - ECMA48Backend running on socket |
b1b355b8 | 128 | - TFileOpen |
30bd4abd KL |
129 | - Decide on naming convention: getText, getValue, getLabel: one or all |
130 | of them? | |
69345248 KL |
131 | - Refactor: |
132 | - TKeypress: | |
133 | - getCh() --> getChar() | |
134 | - getAlt/getCtrl/getShift --> isAltDown / isCtrlDown / isShiftDown | |
135 | - Other boolean getters --> isSomething | |
a4406f4e KL |
136 | - Document any properties used |
137 | - Expose use of 'stty' | |
138 | ||
139 | 0.0.3: FINISH PORTING | |
7d4115a5 | 140 | |
a4406f4e KL |
141 | - TTreeView |
142 | - Also add keyboard navigation | |
143 | - TDirectoryList | |
144 | - Also add keyboard navigation | |
145 | ||
146 | 0.0.4: NEW STUFF | |
7d4115a5 | 147 | |
a4406f4e | 148 | - Making TMenu keyboard accelerators active/inactive |
cf9af8df | 149 | - TStatusBar |
cc99cba8 | 150 | - TEditor |
a4406f4e KL |
151 | - TWindow |
152 | - "Smart placement" for new windows | |
cc99cba8 | 153 | |
a4406f4e | 154 | 0.0.5: BUG HUNT |
cc99cba8 | 155 | |
a4406f4e | 156 | - TSubMenu keyboard mnemonic not working |
9edb442b | 157 | |
a4406f4e | 158 | 0.1.0: BETA RELEASE |
9edb442b | 159 | |
a4406f4e KL |
160 | - TSpinner |
161 | - TComboBox | |
162 | - TListBox | |
163 | - TCalendar | |
164 | - TColorPicker | |
7d4115a5 KL |
165 | |
166 | Wishlist features (2.0): | |
167 | ||
168 | - TTerminal | |
169 | - Handle resize events (pass to child process) | |
7d4115a5 KL |
170 | - Screen |
171 | - Allow complex characters in putCharXY() and detect them in putStrXY(). | |
7d4115a5 KL |
172 | - Drag and drop |
173 | - TEditor | |
174 | - TField | |
175 | - TText | |
176 | - TTerminal | |
177 | - TComboBox | |
92554d64 KL |
178 | |
179 | ||
180 | Screenshots | |
181 | ----------- | |
182 | ||
bb35d919 KL |
183 | ![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal") |
184 | ||
cf9af8df KL |
185 | ![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.") |
186 |