TTY::Box

Draw various frames and boxes in your terminal interface.

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

1. Usage
2. Interface

1. Usage

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

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

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

2. Interface

2.1 frame

You can draw a box in the top left corner of your terminal window by using the frame method and providing at the very minimum the height and the width:

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

which when printed will prodcue the following output in your terminal:

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

Then you can use tty-cursor to directly manipulate content to be displayed inside the 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

which 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 be positioned in the top left corner of the terminal emulator. Use :top and :left keyword arguments to change this:

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

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)

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 two types of border :light and :thick. By default the :light border is used. This can be changed using the :border keyword:

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

and printing the box out to console will produce:

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

You can also selectively switch off border sides by passing options hash. 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      │
# │                            │
# │                            │
# │                            │
# └────────────────────────────┘
#

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 Contributor Covenant 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.

theusernameisavailable / tty-box