The JScreen is a text-mode screen that accurately resembles a DOS screen because of the font's appearance, and the cursor's behaviour (in some technical circles, this word "caret" is used to refer to the cursor; we prefer to use the traditional terms "cursor" and "cursor position"), while also introducing some new features that update text mode to current times.


Class Summary
JScreen The JScreen class creates a text mode screen that fits within any JFC/Swing GUI like a typical JComponent.
JScreenCharacter The JScreenCharacter class encapsulates each character that is displayed on the JScreen object's screen, and keeps track of all its attributes (the character's on-screen position is not included in the list of attributes as this is tracked directly by the JScreen object).
JScreenFont The JScreenFont class reads a fixed-size font file that contains a list of pixel co-ordinates that are used to draw each ASCII character.  The font data is returned as a multi-dimensional array of integers that JScreen uses to draw pixel-perfect ASCII characters.
JScreenTransaction The JScreenTransaction class is used to implement transactions that allow for uninterrupted screen output by grouping a series of commands together.

Package Description

The JScreen is a text-mode screen that accurately resembles a DOS screen because of the font's appearance, and the cursor's behaviour (in some technical circles, this word "caret" is used to refer to the cursor; we prefer to use the traditional terms "cursor" and "cursor position"), while also introducing some new features that update text mode to current times.


When people see a text mode screen, such as the one that JScreen presents, they often assume that they're using at a DOS application.  This is due to the fact a text mode interface was used by the vast majority of DOS applications.

It's important to note that "text mode" is not equivilant to "DOS" and that there are many non-DOS applications that utilize text mode (such as the FAR Manager at, which we assume was inspired by the Norton Commander, an advanced and famously popular file management system for DOS that was an essential tool for many computer users).


Extended ASCII is supported.  Unicode, UTF-8, etc., is not, so if you need to support other languages that aren't possible with the standard Extended ASCII character set, then JScreen probably isn't appropriate (if there is sufficient demand and support for it, and free fonts are available for inclusion, we would like to consider updating this class {or creating a new one} accordingly).

For ASCII art, ASCII games, text-mode interfaces, etc., JScreen is ideally suited.  JScreen supports blinking and underlining attributes, multiple types of transparency, and custom RGB (and RGBA) colours; full details are available in the "Features" section below...

Text output is designed to be handled in the most efficient manner.  One additional thread waits continuously, and processes all queued command sets that alter attributes, write to the screen, etc., as they become ready for processing.  Also, the use of primitive data types eliminates the memory and processor overhead incurred by wrappers of those types, which is particularly important for the loops used to do basic things like drawing characters pixel-by-pixel and manipulating groups of screen memory.


Some of the main reasons that text-mode applications disappeared, which were primarily architectural challenges imposed by DOS (Disk Operating System), included a variety of limitations:

The most notable aspect was the popularization of the GUI (Graphical User Interface), but not so much for reasons of practicality (because support for it required more powerful hardware) or because it looked attractive (in fact it tended to look very ugly and unfriendly with all the single-colour pixel patterns and shades of grey, and the small assortment of icons that were built with {at the time} limited numbers of colours, that all resided on top of bland colour schemes that were set up by default on the majority of the GUI-centric Operating Systems {after colours were introduced in the later versions}), but because it was well marketed to software developers and users in a way that emphasized that it was where the future of computing was headed.

This over-emphasis by marketers turned out to be a great success for the GUI, and although it, for the most-part, ended text-mode development, most of the ASCII art and ANSI art enthusiasts weren't discouraged and all the hardware manufacturers continue to support it to this day not only because there is so much software that still needs it (such as the BIOS interface), but also because it's so simple to implement.  Text mode is extremely useful, and even Apple is finding that they can no longer continue to resist it (they were the only vendor I'm aware of who manufactured computer hardware that had absolutely no text mode support {it started in graphics mode first, immediately after the power was switched on, displaying Apple's famous MacOS logo, icons, etc., prior to booting the Operating System}, until within the first decade after the turn of the century; c. year 2000).

Evolution - 1st generation text mode

The first generation of text mode was very simple, and was compatible with line printers (a.k.a., basic dot matrix printers), and later evolved to what I refer to as second-generation text mode.

Functional control characters that could move the cursor's position (the most common provided tabulation, home position, and line feed support), clearing the screen, implementing the BackSpace key's function, were essential aspects of the basic text-mode interface.

Some vendors ventured forth with a few additions that eventually became common-place on most platforms as well, most notably Unix, but those basic few mentioned in the previous paragraph were the only ones that were supported with actual consistency.

Evolution - 2nd generation text mode

The second generation introduced underlining, high-intensity (bold), and blinking effects, which were popular on monochrome (no colour) displays and various types of mainframe terminals.  Some manufacturers made some significant enhancements to the feature-set, most notably IBM who somehow added a 26th row to the bottom of the screen and displayed a small variety of some really nice looking non-standard characters to indicate the status for various actions/activities (note that JScreen has built-in support for more than 256 characters so that stuff like this can be simulated easily).

The second generation also introduced 16 colours, with a background colour that could be set independently of the character colour.  This, combined with the Extended ASCII characters, turned out to be a wonderful feature for a ASCII art editors who wanted to use colours.  With this colour came those who then wanted to take ASCII art into the 8-bit realm, and thus ANSI art was born due to the ubiquitous deployment of ANSI among users of BBSs (Bulletin Board Systems, which were the mainstream electronic communications medium before it was mostly replaced by the internet).

Unix environments also contributed a lot to text mode, and were especially notable for the flexible screen sizing capabilities, some of which was made available to DOS users later on.  Certain video card manufacturers, such as ATi, also pioneered support for some exotic text mode screen sizes that included hundreds of rows and columns (albeit with very small fonts) that also yielded better performance than using graphics mode to accomplish the same screen output (the newer high-performance video cards that were produced less than a decade later completely overcame this graphics mode performance challenge).

Evolution - 3nd generation text mode

Thanks to Java, the aforementioned limits are also not a hinderance, so the potential future of feature-rich text-mode applications and games looks promising.  With JScreen, we take text-mode screen technology to a new level with features like per-character transparency (Unix is known for providing a uniform transparency level only) which greatly simplifies the creation of "viewports" that reveal portions of background graphics (this could be used in text-mode platform game development).  In a future version we plan to expand our support for more than 256 characters by providing an easy way to draw custom characters on-the-fly.

The features introduced by JScreen (documented below) bring text mode into its 3rd generation.  Aside from per-character transparency and support for characters beyond the 8-bit realm, there is also multi-processor/thread and database-like transaction support.


Our hope, with these new features, is that a blizzard of new text-mode games that utilize JScreen will increasily become available.  We would love to get a letter or an eMail about any text-mode games that use JScreen so that we can a link to it from some of our web sites.  In particular, we'd love to promote such educational games and applications.

We would also like to see interest from hardware manufacturers wanting to support our implementation of text-mode with the new features we've added, natively with their video cards.  Whether they implement it with an embedded JVM (this is likely the best and easiest approach because it will require far less programming), or directly in hardware (we can certainly help with testing).

Text mode font
The font is based on the original font used on the original VGA and SuperVGA video adapters on XT, PC, and PS/2 computers.  It is a fixed-size font that is commonly referred to as the CP437 (Code Page 437) font where every character has the same width and height in pixels, and also includes the original standard Extended ASCII characters.

We need to use this specialized font to simulate text mode because Java doesn't support using any of the text modes (that all video hardware natively supports) when specifying a custom graphics mode, and store it internally in the form of arrays of points to be drawn on the screen (this results in a small savings in memory, and uses fewer CPU cycles to draw).

The standard Extended ASCII (or "8-bit ASCII") character values range from 0 through 255.  These "Extended" characters (values above 127) are essential to good user-friendly text-mode interface designs because they include, in particular, mathematical symbols and line-drawing characters (plus some language-specific letters with accents, umluts, etc.) that aid in presenting information to the user in a manner that's easier to understand.

Flashing cursor
The cursor flashes in the same manner as text mode, and helps to re-create the look-and-feel of actual text mode.  It can be disabled at will, and its shape can be changed.

Two specific commands for disabling and enabling the cursor are also provided.  Since the implementation of this feature was different on early text-mode computers, many of which didn't have this feautre at all (so the work-around was to change the size of the cursor to make it invisible, but this was also problematic because the rules for setting the cursor size were inconsistent due to competing vendors interpreting these numbers differently).

Per-character foreground/text colours
The foreground/text colours may be specified for every character (the most recent colour setting is used when not specified).

Additionally, colours may be specified by providing RGB (or RGBA) colour values.  This is feature, which is not supported by standard text mode, is unique to JScreen.

Per-character background colours
The background colours may be specified for every character (the most recent colour setting is used when not specified).

Normally there are only 8 possible background colours unless a special flag is set to extend this to 16 (this flag was primarily intended to disable blinking text).  JScreen supports all 16 background colours without the need to set a special flag.

Additionally, colours may be specified by providing RGB (or RGBA) colour values.  This is feature, which is not supported by standard text mode, is unique to JScreen.

Transparency attribute
For each character, the background can be set to be completely transparent.  Whatever was drawn immediately behind each transparent charater will be visible and appear to be behind the foreground text character.  This is particularly useful for:

For more detailed control over transparency, which is provided with advanced alpha-blending techniques, JScreen supports the use of custom RGBA colours to be used as backround and/or foreground colours.  This makes it possible to appear partially blended with the background.

The flashing cursor always takes on the colour of the foreground character behind it, including any alpha-blending settings provided by an RGBA colour.

This feature, which is not supported by standard text mode, is unique to JScreen.

Blinking attribute
Any foreground/text character can be set to blink.

In text mode, all characters that blink do so at precisely the same moments, and at a rate that isn't bothersome.  Great efforts were made to ensure that JScreen simulates this effect well, and the speed of the blinking was chosen very carefully.

Underlining attribute
Any character may be displayed with an underline.

This feature was available on monochrome displays because certain colours indicated when text should appear underlined (this approach was a good one because colours were differentiated in a useful way; this is also the reason some DOS applications prompted the user if they were using a colour display {a different colour scheme would be used on non-colour displays to prevent underlining from being displayed inappropriately}).

Although underlining was only really available on monocrhome displays, JScreen supports this feature without compromising colour selection options.

Strike-through attribute
Any character may be displayed with a strike-through line, which is drawn horizontally across the middle of text.

This feature, which is not supported by standard text mode, is unique to JScreen.

Swing (JFC) integration
This class extends Swing's JComponent object, which means that it can be seamlessly integrated into any Swing container such as a JFrame, and be positioned accordingly.

The transparency features for backgrounds make it easy to display ASCII text within your applications, without interfering with the style and background behind it.  One example of such an application is a hexadecimal file editor that shows all the binary characters on one side of the screen using a JScreen object that doesn't need to obscure any characters with a period.

Multiple threads may print output to the JScreen and alter its attributes, cursor positions, etc., without corruption, crashing, or deadlocks occurring.  Randolf Richardson, the developer, has done extensive work with threads, threadgroups, processes, locks, semaphores, etc., and has a very good understanding of problems that can arise when multi-threading is used incorrectly.

A low-overhead thread-safe queing system is used to ensure that every aspect of screen I/O is processed in the correct order, and without conflict or unneccesary complexity.  This simplifies the implementation of a feature-rich command-set, which leads to greater flexibility for multi-threaded application development.

Interactions with the JScreen can be grouped into sets of transactions to prevent many series of small alterations and data output collisions (which may result in unexpected combinations of text and colour, incorrect cursor movements, etc.).

Transactions are a very useful feature which have a proven track record due to heavy use in enterprise-class SQL servers such as PostgreSQL and Oracle.  The JScreen transactions start with the begin() method call, and are ended with either the commit() or rollback() method calls, just like they are in transactional SQL.

Any number of transactions are permitted within any transaction, but do note that nothing will appear on the screen until the root (first/initial) transaction in the hierarchy is finally committed.

A transaction is written to the screen when commit() is called, and not when the transaction was started, unless the point in time when the transaction was started is still in the queue (then the transaction will appear to have been inserted at that point instead).  The commitNow() method will always add the transaction to the end of the queue regardless of whether its starting point is still in the queue.