String Box

StringBox is very simple terminal-based display. Can be used to place arbitrary strings in arbitrary locations in a terminal window. StringBox will not redraw the screen. Instead, it will produce a string that, when printed, will fill the screen, causing the screen's previous contents to scroll off of the screen. StringBox also is not designed to respond to events; however, you may create an Observer that aggregates a StringBox, producing a similar result.

The default StringBox is 23×80 which, when printed with System.out.println(), will fill a standard 24×80 window except for the last line and will place the cursor at the start of the last line for user input. You may consider creating a 24x80 StringBox with the two-argument constructor and print it with System.out.print(), which will fill a standard 24x80 window entirely and place the cursor at the end of the last line for user input.

A StringBox is populated with repeated calls to placeString(). The 5-argument placeString() method allows you to specify the top/bottom alignment and left/right justification. Since we expect that anchoring a string with its upper-left corner to be the common case, the 3-argument placeString() method defaults to that behavior. Each of the placeString() methods returns its StringBox object, which allows multiple placeString() calls to be chained. After you have constructed the screen to be displayed, a call to toString() will produce a string suitable for printing.

You may pass multi-line strings to the placeString*() methods, and the result would be the equivalent of making several placeString*() calls with one-line strings with the same left/right alignment column and adjacent rows.

Tab characters are converted to four spaces, which may be problematic if you rely on tabs in the middle of strings to perform alignment. We recommend that you either use separate calls to placeString*() to achieve this alignment, or use other methods that operate on Strings to provide alignment.

Examples

For conciseness, these examples assume a 12×25 StringBox object called stringBox. Note that the row/column numbering and the horizontal/vertical dividers are for illustration only and are not part of the generated string.

Basic Usage

We can place a single line on the screen:

stringBox.placeString("foo",2,10);

produces

              111111111122222
    0123456789012345678901234
    _________________________
 0 |
 1 |
 2 |          foo
 3 |
 4 |
 5 |
 6 |
 7 |
 8 |
 9 |
10 |
11 |

Multi-line

Multiple-line strings can be placed either as a single multi-line string or as multiple single-line strings:

stringBox.placeString("foo\nbar baz",2,10);

is equivalent to

stringBox.placeString("foo",2,10).placeString("bar baz",3,10);

as they both produce

              111111111122222
    0123456789012345678901234
    _________________________
 0 |
 1 |
 2 |          foo
 3 |          bar baz
 4 |
 5 |
 6 |
 7 |
 8 |
 9 |
10 |
11 |

Right-Justification

Inserted strings can be right-justified instead of left-justified:

stringBox.placeString("foo\nbar baz",Vertical.TOP,2,Horizontal.RIGHT,10);

produces

              111111111122222
    0123456789012345678901234
    _________________________
 0 |
 1 |
 2 |        foo
 3 |    bar baz
 4 |
 5 |
 6 |
 7 |
 8 |
 9 |
10 |
11 |

Bottom-Aligned

You can specify the bottom row for an inserted string instead of its top row:

stringBox.placeString("foo\nbar baz",Vertical.BOTTOM,2,Horizontal.LEFT,10);

produces

              111111111122222
    0123456789012345678901234
    _________________________
 0 |
 1 |          foo
 2 |          bar baz
 3 |
 4 |
 5 |
 6 |
 7 |
 8 |
 9 |
10 |
11 |

Emojis

Many emojis occupy more than one horizontal space; however, this is not a problem for StringBox because those emojis are also actually multiple characters:

stringBox.placeString("foo\n_😄_",Vertical.TOP,2,Horizontal.LEFT,10);

which is equivalent to

stringBox.placeStringAlignTopLeft("foo\n_\uD83D\uDE04_",Vertical.TOP,2,Horizontal.LEFT,10);

or, using the com.vdurmont.emoji-java library:

stringBox.placeStringAlignTopLeft(EmojiParser.parseToUnicode("foo\n_:smile:_"),Vertical.TOP,2,Horizontal.RIGHT,10);

produces

              111111111122222
    0123456789012345678901234
    _________________________
 0 |
 1 |
 2 |          foo
 3 |          _😄_
 4 |
 5 |
 6 |
 7 |
 8 |
 9 |
10 |
11 |

That these emojis will occupy multiple spaces will only be an issue if you rely on them occupying but one space.

Text Outside the Borders

Any text that extends beyond the right-most column or the bottom-most row, or occupies a negative row or a negative column, will be silently truncated:

stringBox.placeString("foo\nbar baz",-1,-1);

              111111111122222
    0123456789012345678901234
    _________________________
 0 |ar baz
 1 |
 2 |
 3 |
 4 |
 5 |
 6 |
 7 |
 8 |
 9 |
10 |
11 |

Interaction Among Inserted Strings

If two inserted strings overlap, the string inserted last will overwrite a portion of the string written first:

stringBox.placeString("foo\nbar", Vertical.TOP, 2, Horizontal.LEFT, 10)
         .placeString("larry\ncurly\nmoe", Vertical.BOTTOM, 5, Horizontal.LEFT, 6)
         .placeString("quux\nxyzzy", Vertical.TOP, 3, Horizontal.RIGHT, 20)
         .placeString("one\ntwo\nthree", Vertical.BOTTOM, 10, Horizontal.RIGHT, 15);

              111111111122222
    0123456789012345678901234
    _________________________
 0 |
 1 |
 2 |          foo
 3 |      larryar    quux
 4 |      curly     xyzzy
 5 |      moe
 6 |
 7 |
 8 |             one
 9 |             two
10 |           three
11 |

Javadoc Excerpt

public class StringBox

A very simple terminal-based display. Can be used to place arbitrary strings in arbitrary locations in a terminal window. StringBox will not redraw the screen. Instead, it will produce a string that, when printed, will fill the screen, causing the screen's previous contents to scroll off of the screen.

A typical usage is:

StringBox stringBox = new StringBox();
String screen = stringBox
        .placeString(...)
            ⋮
        .placeString(...)
        .toString();
System.out.println(screen);

Note that StringBox is not robust to hidden characters, such as VT100 escape sequences.

public enum Horizontal

Horizontal alignment directives

public enum Vertical

Vertical alignment directives

public StringBox()

Produces a StringBox suitably-sized for a standard 24×80 terminal. The StringBox will be 23×80; if the string is printed with System.out.println() then it will leave the cursor on the 24th line, where the user can enter their input without scrolling the top of the string off the screen.

Alternatively, you might create a StringBox using StringBox(24,80). If the string is printed with System.out.print() then it will leave the cursor at the end of the 24th line without scrolling the top of the string off of the screen. This particular style would be useful if you place the prompt on the 24th line.

• See also: StringBox(int, int)

public StringBox(int boxHeight, int boxWidth)

Produces an arbitrarily-sized StringBox. The StringBox should be no wider than your terminal and should be at least one line shorter than your terminal. If the string is printed with System.out.println() then it will leave the cursor on the last line, where the user can enter their input without scrolling the top of the string off the screen.

Alternatively, you might create a StringBox whose height is the height of your terminal. If the string is printed with System.out.print() then it will leave the cursor at the end of the last line without scrolling the top of the string off of the screen. This particular style would be useful if you place the prompt on the last line.

• Parameters:
  • boxHeight — the number of rows in this StringBox
  • boxWidth — the number of columns in this StringBox

public StringBox placeString(String string, int topRow, int leftColumn)

Places a string in the StringBox with its upper-left corner in the specified location. If the string contains multiple lines, each line after the first will be placed in the row subsequent to the previous line, and the lines will be left-justified. Any portions of the string that would be placed outside the StringBox's defined boundaries will be silently truncated.

Equivalent to placeString(string, Vertical.TOP, topRow, Horizontal.LEFT, leftColumn).

• Parameters:
  • string — the string to be placed in the StringBox
  • topRow — the row on which the first line of the string should be placed
  • leftColumn — the column in which the first character of each row should be placed
• Returns: the current StringBox object, suitable for chained calls
• See also: placeString(String, Vertical, int, Horizontal, int)

public StringBox placeString(String string, Vertical verticalAlignment, int verticalPosition, Horizontal horizontalAlignment, int horizontalPosition)

Places a string in the StringBox. If verticalAlignment is TOP then the string's first line will be in the verticalPosition'th row, and each subsequent line will be in each subsequent row. If verticalAlignment is BOTTOM then the string's last line will be in the verticalPosition'th row, and each preceding line will be in each preceding row. If horizontalAlignment is LEFT then each line will be left-justified to the horizontalPosition'th column. If horizontalAlignment is RIGHT then each line will be right-justified to the horizontalPosition'th column.

• Parameters:
  • string — the string to be placed in the StringBox
  • verticalAlignment — vertical alignment directive (top/bottom)
  • verticalPosition — the row on which the string should be top/bottom aligned
  • horizontalAlignment — horizontal alignment directive (left/right)
  • horizontalPosition — the column on which the string should be top/bottom aligned
• Returns: the current StringBox object, suitable for chained calls

@Override public String toString()

Generates the string that the client code produced by calling {@link #placeString(String, int, int)} and its related methods. Any unused lines between the last line of text and the bottom of the StringBox will be filled with newLines so that when the string is printed, the previous string will fully scroll off of the screen.

Equivalent to toString(true).

• Returns: the string built by calls to {@link #placeString(String, int, int)} and its related methods
• See also: toString(boolean)

public String toString(boolean padToHeight)

Generates the string that the client code produced by calling {@link #placeString(String, int, int)} and its related methods. If this method's argument is true, then any unused lines between the last line of text and the bottom of the StringBox will be filled with newLines so that when the string is printed, the previous string will fully scroll off of the screen. If the argument is false, then the returned string will stop after the last line of text.

• Parameters: padToHeight — indicates whether newlines should be placed after the last line of text
• Returns: the string built by calls to {@link #placeString(String, int, int)} and its related methods

String Box © 2020 Christopher Bohn, bohn@unl.edu