tty logo

TTY::Box Gitter

Gem Version Build Status Build status Maintainability Coverage Status Inline docs

Draw various frames and boxes in your terminal interface.

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

Box drawing

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

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 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.new(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 remoe 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      │
# │                            │
# │                            │
# │                            │
# └────────────────────────────┘
#

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.

Copyright

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