Test commit from within Eclipse
[fanfix.git] / README.md
CommitLineData
7d4115a5
KL
1Jexer - Java Text User Interface library
2========================================
3
a4406f4e
KL
4WARNING: THIS IS ALPHA CODE! PLEASE CONSIDER FILING BUGS AS YOU
5ENCOUNTER THEM.
30bd4abd
KL
6
7This library is intended to implement a text-based windowing system
8loosely reminiscient of Borland's [Turbo
9Vision](http://en.wikipedia.org/wiki/Turbo_Vision) library. For those
10wishing to use the actual C++ Turbo Vision library, see [Sergio
11Sigala's updated version](http://tvision.sourceforge.net/) that runs
12on many more platforms.
7d4115a5 13
1ac2ccb1
KL
14Two 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
28The demo application showing the existing UI controls is available via
29'java -jar jexer.jar' or 'java -Djexer.Swing=true -jar jexer.jar' .
30
31Additional backends can be created by subclassing
32jexer.backend.Backend and passing it into the TApplication
33constructor.
1ac2ccb1
KL
34
35
7d4115a5
KL
36
37License
38-------
39
5e9795db
KL
40This project is licensed LGPL ("GNU Lesser General Public License",
41sometimes called the "Library GPL") version 3 or greater. You may
42freely use Jexer in both closed source (proprietary) and open source
43applications, however any changes you make to the Jexer code must be
44made available to your users.
45
46See the file LICENSE for the full license text, which includes both
47the GPL v3 and the LGPL supplemental terms.
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
30bd4abd 62Usage patterns are still being worked on, but in general the goal will
a4406f4e 63be to build applications as follows:
7d4115a5
KL
64
65```Java
66import jexer.*;
67
68public 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 85See the file demos/Demo1.java for detailed examples.
30bd4abd
KL
86
87
7d4115a5 88
92554d64
KL
89Known Issues / Arbitrary Decisions
90----------------------------------
91
92Some arbitrary design decisions had to be made when either the
93obviously expected behavior did not happen or when a specification was
94ambiguous. 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
8caf0d51
KL
113 ECMA48 Backend
114 --------------
115
116 - Mouse support for BackendType.ECMA48/XTERM currently requires UTF-8
117 coordinates (1005 mode). Terminals that support UTF-8 mouse coordinates
118 include xterm, rxvt-unicode, gnome-terminal, and konsole. Due to Java's
119 InputStreamReader requirement of a valid UTF-8 stream, one must assume
120 the terminal will always generate correct UTF-8 bytes. Mode 1006 (SGR)
121 will be supported in a future release.
122
36338168
KL
123
124
7d4115a5
KL
125Roadmap
126-------
127
30d336cc 128Many tasks remain before calling this version 1.0:
7d4115a5 129
a4406f4e 1300.0.2: STABILIZE EXISTING
7d4115a5 131
a4406f4e
KL
132- TTerminalWindow
133 - Expose shell commands as properties
134- Swing:
30bd4abd 135 - Blinking cursor
69345248 136 - Block cursor
1ac2ccb1 137- ECMA48Backend running on socket
b1b355b8 138- TFileOpen
30bd4abd
KL
139- Decide on naming convention: getText, getValue, getLabel: one or all
140 of them?
69345248
KL
141- Refactor:
142 - TKeypress:
143 - getCh() --> getChar()
144 - getAlt/getCtrl/getShift --> isAltDown / isCtrlDown / isShiftDown
145 - Other boolean getters --> isSomething
a4406f4e
KL
146- Document any properties used
147 - Expose use of 'stty'
148
1490.0.3: FINISH PORTING
7d4115a5 150
a4406f4e
KL
151- TTreeView
152 - Also add keyboard navigation
153- TDirectoryList
154 - Also add keyboard navigation
155
1560.0.4: NEW STUFF
7d4115a5 157
a4406f4e 158- Making TMenu keyboard accelerators active/inactive
cf9af8df 159- TStatusBar
cc99cba8 160- TEditor
a4406f4e
KL
161- TWindow
162 - "Smart placement" for new windows
cc99cba8 163
a4406f4e 1640.0.5: BUG HUNT
cc99cba8 165
a4406f4e 166- TSubMenu keyboard mnemonic not working
8caf0d51
KL
167- ECMA48Terminal
168 - Mode 1006 mouse coordinates
9edb442b 169
a4406f4e 1700.1.0: BETA RELEASE
9edb442b 171
a4406f4e
KL
172- TSpinner
173- TComboBox
174- TListBox
175- TCalendar
176- TColorPicker
7d4115a5
KL
177
178Wishlist features (2.0):
179
180- TTerminal
181 - Handle resize events (pass to child process)
7d4115a5
KL
182- Screen
183 - Allow complex characters in putCharXY() and detect them in putStrXY().
7d4115a5
KL
184- Drag and drop
185 - TEditor
186 - TField
187 - TText
188 - TTerminal
189 - TComboBox
92554d64
KL
190
191
192Screenshots
193-----------
194
bb35d919
KL
195![Several Windows Open Including A Terminal](/screenshots/screenshot1.png?raw=true "Several Windows Open Including A Terminal")
196
cf9af8df
KL
197![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.")
198