And then print:
print box
# =>
# ┌───────────────────────┐
# │ │
# │ │
# │ │
# │ Drawing a box in │
# │ terminal emulator │
# │ │
# │ │
# │ │
# └───────────────────────┘
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 │
# │ │
# │ │
# │ │
# │ │
# │ │
# │ │
# └────────────────────────────┘
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.
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)
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)┘
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
})
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 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 │
# │ │
# │ │
# │ │
# └────────────────────────────┘
#
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 ║
# ║ ║
# ╚═══════════════════════╝
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 ║
# ║ ║
# ╚═══════════════════════╝
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 ║
# ║ ║
# ╚═══════════════════════╝
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 ║
# ║ ║
# ╚═══════════════════════╝