| 1 | Jexer - Java Text User Interface library |
| 2 | ======================================== |
| 3 | |
| 4 | This library implements a text-based windowing system loosely |
| 5 | reminiscent of Borland's [Turbo |
| 6 | Vision](http://en.wikipedia.org/wiki/Turbo_Vision) system. It looks |
| 7 | like this: |
| 8 | |
| 9 | ![Terminal, Image, Table](/screenshots/new_demo1.png?raw=true "Terminal, Image, Table") |
| 10 | |
| 11 | Jexer works on both Xterm-like terminals and Swing, and supports |
| 12 | images in both Xterm and Swing. On Swing, images are true color: |
| 13 | |
| 14 | ![Swing Snake Image](/screenshots/snake_swing.png?raw=true "Swing Snake Image") |
| 15 | |
| 16 | On Xterm, images are dithered to a common palette: |
| 17 | |
| 18 | ![Xterm Snake Image](/screenshots/snake_xterm.png?raw=true "Xterm Snake Image") |
| 19 | |
| 20 | |
| 21 | |
| 22 | License |
| 23 | ------- |
| 24 | |
| 25 | Jexer is available to all under the MIT License. See the file LICENSE |
| 26 | for the full license text. |
| 27 | |
| 28 | |
| 29 | |
| 30 | Obtaining Jexer |
| 31 | --------------- |
| 32 | |
| 33 | Jexer is available on Maven Central: |
| 34 | |
| 35 | ```xml |
| 36 | <dependency> |
| 37 | <groupId>com.gitlab.klamonte</groupId> |
| 38 | <artifactId>jexer</artifactId> |
| 39 | <version>0.3.2</version> |
| 40 | </dependency> |
| 41 | ``` |
| 42 | |
| 43 | Binary releases are available on SourceForge: |
| 44 | https://sourceforge.net/projects/jexer/files/jexer/ |
| 45 | |
| 46 | The Jexer source code is hosted at: https://gitlab.com/klamonte/jexer |
| 47 | |
| 48 | |
| 49 | |
| 50 | 1.0.0 Release |
| 51 | ------------- |
| 52 | |
| 53 | |
| 54 | Jexer's original list of features for its 1.0.0 release are undergoing |
| 55 | final testing. Issues and merge requests are disabled until that |
| 56 | release is out. |
| 57 | |
| 58 | |
| 59 | |
| 60 | Documentation |
| 61 | ------------- |
| 62 | |
| 63 | * [Java API Docs](https://jexer.sourceforge.io/apidocs/api/index.html) |
| 64 | |
| 65 | * [Wiki](https://gitlab.com/klamonte/jexer/wikis/home) |
| 66 | |
| 67 | * [Jexer web page](https://jexer.sourceforge.io/) |
| 68 | |
| 69 | * [Development Standards](https://gitlab.com/klamonte/jexer/wikis/dev-standards) |
| 70 | |
| 71 | |
| 72 | |
| 73 | Programming Examples |
| 74 | -------------------- |
| 75 | |
| 76 | The examples/ folder currently contains: |
| 77 | |
| 78 | * A [prototype tiling window |
| 79 | manager](/examples/JexerTilingWindowManager.java) in less than 250 |
| 80 | lines of code. |
| 81 | |
| 82 | * A much slicker [prototype tiling window |
| 83 | manager](/examples/JexerTilingWindowManager2.java) in less than 200 |
| 84 | lines of code. |
| 85 | |
| 86 | * A [prototype image thumbnail |
| 87 | viewer](/examples/JexerImageViewer.java) in less than 350 lines of |
| 88 | code. |
| 89 | |
| 90 | jexer.demos contains official demos showing all of the existing UI |
| 91 | controls. The demos can be run as follows: |
| 92 | |
| 93 | * 'java -jar jexer.jar' . This will use System.in/out with |
| 94 | Xterm-like sequences on non-Windows non-Mac platforms. On Windows |
| 95 | and Mac it will use a Swing JFrame. |
| 96 | |
| 97 | * 'java -Djexer.Swing=true -jar jexer.jar' . This will always use |
| 98 | Swing on any platform. |
| 99 | |
| 100 | * 'java -cp jexer.jar jexer.demos.Demo2 PORT' (where PORT is a |
| 101 | number to run the TCP daemon on). This will use the Xterm backend |
| 102 | on a telnet server that will update with screen size changes. |
| 103 | |
| 104 | * 'java -cp jexer.jar jexer.demos.Demo3' . This will use |
| 105 | System.in/out with Xterm-like sequences. One can see in the code |
| 106 | how to pass a different InputReader and OutputReader to |
| 107 | TApplication, permitting a different encoding than UTF-8. |
| 108 | |
| 109 | * 'java -cp jexer.jar jexer.demos.Demo4' . This demonstrates hidden |
| 110 | windows and a custom TDesktop. |
| 111 | |
| 112 | * 'java -cp jexer.jar jexer.demos.Demo5' . This demonstrates two |
| 113 | demo applications using different fonts in the same Swing frame. |
| 114 | |
| 115 | * 'java -cp jexer.jar jexer.demos.Demo6' . This demonstrates two |
| 116 | applications performing I/O across three screens: an Xterm screen |
| 117 | and Swing screen, monitored from a third Swing screen. |
| 118 | |
| 119 | * 'java -cp jexer.jar jexer.demos.Demo7' . This demonstrates the |
| 120 | BoxLayoutManager, achieving a similar result as the |
| 121 | javax.swing.BoxLayout apidocs example. |
| 122 | |
| 123 | |
| 124 | |
| 125 | More Screenshots |
| 126 | ---------------- |
| 127 | |
| 128 | Jexer can be run inside its own terminal window, with support for all |
| 129 | of its features including images and mouse, and more terminals: |
| 130 | |
| 131 | ![Yo Dawg...](/screenshots/jexer_sixel_in_sixel.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.") |
| 132 | |
| 133 | Sixel output uses a single palette which works OK for a variety of |
| 134 | real-world images: |
| 135 | |
| 136 | ![Sixel Pictures Of Cliffs Of Moher And Buoy](/screenshots/sixel_images.png?raw=true "Sixel Pictures Of Cliffs Of Moher And Buoy") |
| 137 | |
| 138 | The color wheel with that palette is shown below: |
| 139 | |
| 140 | ![Sixel Color Wheel](/screenshots/sixel_color_wheel.png?raw=true "Sixel Color Wheel") |
| 141 | |
| 142 | |
| 143 | |
| 144 | Terminal Support |
| 145 | ---------------- |
| 146 | |
| 147 | The table below lists terminals tested against Jexer's Xterm backend: |
| 148 | |
| 149 | | Terminal | Environment | Mouse Click | Mouse Cursor | Images | |
| 150 | | -------------- | ------------------ | ----------- | ------------ | ------ | |
| 151 | | xterm | X11 | yes | yes | yes | |
| 152 | | jexer | CLI, X11, Windows | yes | yes | yes | |
| 153 | | mlterm | X11 | yes | yes | yes | |
| 154 | | RLogin | Windows | yes | yes | yes | |
| 155 | | alacritty(3) | X11 | yes | yes | no | |
| 156 | | gnome-terminal | X11 | yes | yes | no | |
| 157 | | iTerm2 | Mac | yes | yes | no(5) | |
| 158 | | kitty(3) | X11 | yes | yes | no | |
| 159 | | lcxterm(3) | CLI, Linux console | yes | yes | no | |
| 160 | | mintty | Windows | yes | yes | no(5) | |
| 161 | | rxvt-unicode | X11 | yes | yes | no(2) | |
| 162 | | xfce4-terminal | X11 | yes | yes | no | |
| 163 | | aminal(3) | X11 | yes | no | no | |
| 164 | | konsole | X11 | yes | no | no | |
| 165 | | yakuake | X11 | yes | no | no | |
| 166 | | Windows Terminal(6) | Windows | no | no | no(2) | |
| 167 | | screen | CLI | yes(1) | yes(1) | no(2) | |
| 168 | | tmux | CLI | yes(1) | yes(1) | no | |
| 169 | | putty | X11, Windows | yes | no | no(2) | |
| 170 | | Linux | Linux console | no | no | no(2) | |
| 171 | | qodem(3) | CLI, Linux console | yes | yes(4) | no | |
| 172 | | qodem-x11(3) | X11 | yes | no | no | |
| 173 | | yaft | Linux console (FB) | no | no | yes | |
| 174 | |
| 175 | 1 - Requires mouse support from host terminal. |
| 176 | |
| 177 | 2 - Also fails to filter out sixel data, leaving garbage on screen. |
| 178 | |
| 179 | 3 - Latest in repository. |
| 180 | |
| 181 | 4 - Requires TERM=xterm-1003 before starting. |
| 182 | |
| 183 | 5 - Sixel images can crash terminal. |
| 184 | |
| 185 | 6 - Version 0.7.3291.0, on Windows 10.0.18362.30. Tested against |
| 186 | WSL-1 Debian instance. |
| 187 | |
| 188 | |
| 189 | |
| 190 | See Also |
| 191 | -------- |
| 192 | |
| 193 | * [Tranquil Java IDE](https://tjide.sourceforge.io) is a TUI-based |
| 194 | integrated development environment for the Java language that was |
| 195 | built using a very lightly modified GPL version of Jexer. TJ |
| 196 | provided a real-world use case to shake out numerous bugs and |
| 197 | limitations of Jexer. |
| 198 | |
| 199 | * [LCXterm](https://lcxterm.sourceforge.io) is a curses-based terminal |
| 200 | emulator that allows one to use Jexer with full support on the raw |
| 201 | Linux console. |
| 202 | |
| 203 | * [ptypipe](https://gitlab.com/klamonte/ptypipe) is a small C utility |
| 204 | that permits a Jexer TTerminalWindow to resize the running shell |
| 205 | when its window is resized. |
| 206 | |
| 207 | |
| 208 | |
| 209 | Acknowledgements |
| 210 | ---------------- |
| 211 | |
| 212 | Jexer makes use of the Terminus TrueType font [made available |
| 213 | here](http://files.ax86.net/terminus-ttf/) . |