Draw Gist.md

And then print:

print box
# =>
# ┌───────────────────────┐
# │                       │
# │                       │
# │                       │
# │   Drawing a box in    │
# │   terminal emulator   │
# │                       │
# │                       │
# │                       │
# └───────────────────────┘

2. Interface

2.1 frame

You can draw a box in your terminal window by using the frame method and passing a content to display. By default the box will be drawn around the content.

print TTY::Box.frame "Hello world!"
# =>
# ┌────────────┐
# │Hello world!│
# └────────────┘

You can also provide multi line content as separate arguments.

print TTY::Box.frame "Hello", "world!"
# =>
# ┌──────┐
# │Hello │
# │world!│
# └──────┘

Alternatively, provide a multi line content using newline chars in a single argument:

print TTY::Box.frame "Hello\nworld!"
# =>
# ┌──────┐
# │Hello │
# │world!│
# └──────┘

Finally, you can use a block to specify content:

print TTY::Box.frame { "Hello world!" }
# =>
# ┌────────────┐
# │Hello world!│
# └────────────┘

You can also enforce a given box size without any content and use tty-cursor to position content whatever you like.

box = TTY::Box.frame(width: 30, height: 10)

When printed will produce the following output in your terminal:

print box
# =>
# ┌────────────────────────────┐
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# └────────────────────────────┘

Alternatively, you can also pass a block to provide a content for the box:

box = TTY::Box.frame(width: 30, height: 10) do
  "Drawin a box in terminal emulator"
end

When printed will produce the following output in your terminal:

print box
# =>
# ┌────────────────────────────┐
# │Drawing a box in terminal   │
# │emulator                    │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# └────────────────────────────┘

2.2 position

By default, a box will not be positioned. To position your box absolutely within a terminal window use :top and :left keyword arguments:

TTY::Box.frame(top: 5, left: 10)

This will place box 10 columns to the right and 5 lines down counting from the top left corner.

If you wish to center your box within the terminal window then consider using tty-screen for gathering terminal screen size information.

2.3 dimension

At the very minimum a box requires to be given size by using two keyword arguments :width and :height:

TTY::Box.frame(width: 30, height: 10)

If you wish to create a box that depends on the terminal window size then consider using tty-screen for gathering terminal screen size information.

For example to print a box that spans the whole terminal window do:

TTY::Box.frame(width: TTY::Screen.width, height: TTY::Screen.height)

2.4 title

You can specify titles using the :title keyword and a hash value that contains one of the :top_left, :top_center, :top_right, :bottom_left, :bottom_center, :bottom_right keys and actual title as value. For example, to add titles to top left and bottom right of the frame do:

box = TTY::Box.frame(width: 30, height: 10, title: {top_left: 'TITLE', bottom_right: 'v1.0'})

which when printed in console will render the following:

print box
# =>
# ┌TITLE───────────────────────┐
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# └──────────────────────(v1.0)┘

2.5 border

There are three types of border :ascii, :light, :thick. By default the :light border is used. This can be changed using the :border keyword:

box = TTY::Box.frame(width: 30, height: 10, border: :thick)

and printing the box out to console will produce:

print box
# =>
# ╔════════════════════════════╗
# ║                            ║
# ║                            ║
# ║                            ║
# ║                            ║
# ║                            ║
# ║                            ║
# ║                            ║
# ║                            ║
# ╚════════════════════════════╝

You can also selectively specify and turn off border parts by passing a hash with a :border key. The border parts are:

                 :top
    :top_left ┌────────┐ :top_right
              │        │
        :left │        │ :right
              │        │
 :bottom_left └────────┘ :bottom_right
               :bottom

The following are available border parts values:

Border values	ASCII	Unicode Light	Unicode Thick
:line	-	─	═
:pipe	|	\│	\║
:cross	+	┼	╬
:divider_up	+	┴	╩
:divider_down	+	┬	╦
:divider_left	+	┤	╣
:divider_right	+	├	╠
:corner_top_left	+	┌	╔
:corner_top_right	+	┐	╗
:corner_bottom_left	+	└	╚
:corner_bottom_right	+	┘	╝

For example, to change all box corners to be a :cross do:

box = TTY::Box.frame(
  width: 10, height: 4,
  border: {
    top_left: :cross,
    top_right: :cross,
    bottom_left: :cross,
    bottom_right: :cross
  }
)

print box
# =>
# ┼────────┼
# │        │
# │        │
# ┼────────┼

If you want to remove a given border element as a value use false. For example to remove bottom border do:

TTY::Box.new(
  width: 30, height: 10,
  border: {
    type: :thick,
    bottom: false
  })

2.6 styling

By default drawing a box doesn't apply any styling. You can change this using the :style keyword with foreground :fg and background :bg keys for both the main content and the border:

style: {
  fg: :bright_yellow,
  bg: :blue,
  border: {
    fg: :bright_yellow,
    bg: :blue
  }
}

The above style configuration will produce the result similar to the top demo, a MS-DOS look & feel window.

2.7 formatting

You can use :align keyword to format content either to be :left, :center or :right aligned:

box = TTY::Box.frame(width: 30, height: 10, align: :center) do
  "Drawing a box in terminal emulator"
end

The above will create the following output in your terminal:

print box
# =>
# ┌────────────────────────────┐
# │ Drawing a box in terminal  │
# │          emulator          │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# │                            │
# └────────────────────────────┘

You can also use :padding keyword to further format the content using the following values:

[1,3,1,3]  # => pad content left & right with 3 spaces and add 1 line above & below
[1,3]      # => pad content left & right with 3 spaces and add 1 line above & below
1          # => shorthand for [1,1,1,1]

For example, if you wish to pad content all around do:

box = TTY::Box.frame(width: 30, height: 10, align: :center, padding: 3) do
  "Drawing a box in terminal emulator"
end

Here's an example output:

print box
# =>
# ┌────────────────────────────┐
# │                            │
# │                            │
# │                            │
# │     Drawing a box in       │
# │     terminal emulator      │
# │                            │
# │                            │
# │                            │
# └────────────────────────────┘
#

2.8 messages

2.8.1 info

To draw an information type box around your content use info:

box = TTY::Box.info("Deploying application")

And then print:

print box
# =>
# ╔ ℹ INFO ═══════════════╗
# ║                       ║
# ║ Deploying application ║
# ║                       ║
# ╚═══════════════════════╝

2.8.2 warn

To draw a warning type box around your content use warn:

box = TTY::Box.warn("Deploying application")

And then print:

print box
# =>
# ╔ ⚠ WARNING ════════════╗
# ║                       ║
# ║ Deploying application ║
# ║                       ║
# ╚═══════════════════════╝

2.8.3 success

To draw a success type box around your content use success:

box = TTY::Box.success("Deploying application")

And then print:

print box
# =>
# ╔ ✔ OK ═════════════════╗
# ║                       ║
# ║ Deploying application ║
# ║                       ║
# ╚═══════════════════════╝

2.8.4 error

To draw an error type box around your content use error:

box = TTY::Box.error("Deploying application")

And then print:

print box
# =>
# ╔ ⨯ ERROR ══════════════╗
# ║                       ║
# ║ Deploying application ║
# ║                       ║
# ╚═══════════════════════╝