Awesome

TTY::Box

Draw various frames and boxes in the terminal window.

TTY::Box provides box drawing component for TTY toolkit.

Installation

Add this line to your application's Gemfile:

gem "tty-box"

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-box

Contents

• 1. Usage
• 2. Interface
  • 2.1 frame
  • 2.2 position
  • 2.3 dimension
  • 2.4 title
  • 2.5 border
  • 2.6 styling
  • 2.7 formatting
  • 2.8 messages
    • 2.8.1 info
    • 2.8.2 warn
    • 2.8.3 success
    • 2.8.4 error

1. Usage

Using the frame method, you can draw a box in a terminal emulator:

box = TTY::Box.frame "Drawing a box in", "terminal emulator", padding: 3, align: :center

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:

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.frame(
  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.

You can disable or force output styling regardless of the terminal using the enable_color keyword. By default, the color support is automatically detected.

TTY::Box.frame({
  enable_color: true, # force to always color output
  style: {
    border: {
      fg: :bright_yellow,
      bg: :blue
    }
  }
})

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 ║
# ║                       ║
# ╚═══════════════════════╝

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-box. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the TTY::Box project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Copyright

Copyright (c) 2018 Piotr Murach. See LICENSE for further details.