Gutenberg

Class Box<T>

Represents an immutable two-dimensional rectangular box of text. The box can be rendered by an IDocumentRenderer<T> or laid out as part of a Document<T>.

Inheritance
Declaration
public abstract class Box<T> : Object
Type Parameters
Name Description

T

The type of annotations in the box
Remarks

Boxes can be composed spatially to create bigger boxes: they can be placed LeftOf(Box<T>, Alignment), RightOf(Box<T>, Alignment), Above(Box<T>, Alignment), and Below(Box<T>, Alignment) one another.

You can also put boxes InFrontOf(Box<T>, Alignment) and Behind(Box<T>, Alignment) one another. Text contained in a box that's placed in front of another box will obscure text contained in in the background box. Additionally, boxes may contain Transparent(Int32, Int32) areas, through which background text will be visible.

The box may contain annotations - values of type T - which can be interpreted by the IDocumentRenderer<T>.

This class is intended to be imported under an alias, since typically the type of annotations won't change within your code: using Box = Gutenberg.Box<MyAnnotation>;

Properties

Empty

An empty box, with zero Width and Height.

Declaration
public static Box<T> Empty { get; }
Property Value
Type Description

Box<T>

Height

The width of the Box<T> in lines.

Declaration
public int Height { get; }
Property Value
Type Description

Int32

Width

The width of the Box<T> in characters.

Declaration
public int Width { get; }
Property Value
Type Description

Int32

Methods

Above(Box<T>, Alignment)

Creates a new Box<T> consisting of this box with bottom placed below it.

If either of the boxes is narrower than the other, it will be padded with a Transparent(Int32, Int32) box until the Width matches, according to the chosen alignment.

See the docs for Alignment for detailed examples of how the alignment affects the layout of the box.

Declaration
public Box<T> Above(Box<T> bottom, Alignment alignment)
Parameters
Type Name Description

Box<T>

bottom

The Box<T> to place below this one

Alignment

alignment

How to align the boxes if one is narrower than the other.
Returns
Type Description

Box<T>

A Box<T> consisting of this box with bottom placed below it.
Examples
var box = Box.FromString("abc")
    .Above("def")
    .WithBorder();
Console.Write(box.ToString());
// Output:
// ┌───┐
// │abc│
// │def│
// └───┘
See Also
Below(Box<T>, Alignment)

Annotated(T)

Apply an annotation to the current Box<T>. The annotation will be passed to the IDocumentRenderer<T>.

Declaration
public Box<T> Annotated(T value)
Parameters
Type Name Description

T

value

The annotation
Returns
Type Description

Box<T>

A copy of the current Box<T> with an annotation applied.

Behind(Box<T>, Alignment)

Returns a new Box<T> consisting of foreground overlaid onto this one.

Text contained within foreground will obscure any corresponding text in this box. If foreground has Transparent(Int32, Int32) areas, the content of this box will be visible through the transparent areas.

If either box is shorter or narrower than the other, it will be padded with a Transparent(Int32, Int32) box until the sizes match, according to the chosen alignment.

See the docs for Alignment for detailed examples of how the alignment affects the layout of the box.

Declaration
public Box<T> Behind(Box<T> foreground, Alignment alignment)
Parameters
Type Name Description

Box<T>

foreground

The Box<T> overlay onto this one

Alignment

alignment

How to align the boxes if one is smaller than the other.
Returns
Type Description

Box<T>

A Box<T> consisting of the content of foreground overlaid onto this box.
Examples
// a box with a transparent window in the centre
var mask = Box.Transparent(1, 1)
    .LeftOf("*").RightOf("*")
    .Above("***").Below("***");
var box = Box.FromString("abcde\nfghij\nklmno")
    .Behind(mask, Alignment.CenterStart)
    .WithBorder();
Console.Write(box.ToString());
// Output:
// ┌─────┐
// │a***e│
// │f*h*j│
// │k***o│
// └─────┘
See Also
InFrontOf(Box<T>, Alignment)

Below(Box<T>, Alignment)

Creates a new Box<T> consisting of this box with top placed above it.

If either of the boxes is narrower than the other, it will be padded with a Transparent(Int32, Int32) box until the Width matches, according to the chosen alignment.

See the docs for Alignment for detailed examples of how the alignment affects the layout of the box.

Declaration
public Box<T> Below(Box<T> top, Alignment alignment)
Parameters
Type Name Description

Box<T>

top

The Box<T> to place above this one

Alignment

alignment

How to align the boxes if one is narrower than the other.
Returns
Type Description

Box<T>

A Box<T> consisting of this box with top placed above it.
Examples
var box = Box.FromString("abc")
    .Below("def")
    .WithBorder();
Console.Write(box.ToString());
// Output:
// ┌───┐
// │def│
// │abc│
// └───┘
See Also
Above(Box<T>, Alignment)

FromString(String)

Creates a Box<T> containing the specified text.

Declaration
public static Box<T> FromString(string text)
Parameters
Type Name Description

String

text

The text to place into a Box<T>
Returns
Type Description

Box<T>

A Box<T> containing the specified text.
Remarks

If the text contains line breaks, the resulting box's height will be equal to the number of lines in the text, and its width will be equal to the length of the longest line. Each line will be left-aligned.

InFrontOf(Box<T>, Alignment)

Creates a new Box<T> consisting of this box overlaid onto background.

Text contained within this box will obscure any corresponding text in the background. If this box has Transparent(Int32, Int32) areas, the background will be visible through the transparent areas.

If either box is shorter or narrower than the other, it will be padded with a Transparent(Int32, Int32) box until the sizes match, according to the chosen alignment.

See the docs for Alignment for detailed examples of how the alignment affects the layout of the box.

Declaration
public Box<T> InFrontOf(Box<T> background, Alignment alignment)
Parameters
Type Name Description

Box<T>

background

The Box<T> to place behind this one

Alignment

alignment

How to align the boxes if one is smaller than the other.
Returns
Type Description

Box<T>

A Box<T> consisting of this box overlaid onto background.
Examples
// a box with a transparent window in the centre
var mask = Box.Transparent(1, 1)
    .LeftOf("*").RightOf("*")
    .Above("***").Below("***");
var box = mask
    .InFrontOf("abcde\nfghij\nklmno", Alignment.CenterStart)
    .WithBorder();
Console.Write(box.ToString());
// Output:
// ┌─────┐
// │a***e│
// │f*h*j│
// │k***o│
// └─────┘
See Also
Behind(Box<T>, Alignment)

LeftOf(Box<T>, Alignment)

Creates a new Box<T> consisting of this box with right placed to its right.

If either of the boxes is shorter than the other, it will be padded with a Transparent(Int32, Int32) box until the Height matches, according to the chosen alignment.

See the docs for Alignment for detailed examples of how the alignment affects the layout of the box.

Declaration
public Box<T> LeftOf(Box<T> right, Alignment alignment)
Parameters
Type Name Description

Box<T>

right

The Box<T> to place to the right of this one

Alignment

alignment

How to align the boxes if one is shorter than the other.
Returns
Type Description

Box<T>

A Box<T> consisting of this box with right placed to the right of it.
Examples
var box = Box.FromString(string.Join('\n', "abc".AsEnumerable()))
    .LeftOf(string.Join('\n', "def".AsEnumerable()))
    .WithBorder();
Console.Write(box.ToString());
// Output:
// ┌──┐
// │ad│
// │be│
// │cf│
// └──┘
See Also
RightOf(Box<T>, Alignment)

MapAnnotations<U>(Func<T, U>)

Apply a function to all the annotations in the current document.

Declaration
public Box<U> MapAnnotations<U>(Func<T, U> selector)
Parameters
Type Name Description

Func<T, U>

selector

The function to apply to the annotations.
Returns
Type Description

Box<U>

A document with all of the annotations replaced with the return value of selector
Type Parameters
Name Description

U

MapAnnotations<U>(Func<T, IEnumerable<U>>)

Apply a function to all the annotations in the current document. If the function returns multiple annotations, the annotations are added in a left-to-right fashion.

Declaration
public Box<U> MapAnnotations<U>(Func<T, IEnumerable<U>> selector)
Parameters
Type Name Description

Func<T, IEnumerable<U>>

selector

The function to apply to the annotations.
Returns
Type Description

Box<U>

A document with all of the annotations replaced with the return values of selector
Type Parameters
Name Description

U

Render(IDocumentRenderer<T>, CancellationToken)

Write the contents of this Box<T> into the renderer.

Declaration
public ValueTask Render(IDocumentRenderer<T> renderer, CancellationToken cancellationToken = null)
Parameters
Type Name Description

IDocumentRenderer<T>

renderer

The renderer

CancellationToken

cancellationToken

A CancellationToken
Returns
Type Description

ValueTask

A ValueTask which completes when the box has been written to the renderer.

RightOf(Box<T>, Alignment)

Creates a new Box<T> consisting of this box with left placed to its left.

If either of the boxes is shorter than the other, it will be padded with a Transparent(Int32, Int32) box until the Height matches, according to the chosen alignment.

See the docs for Alignment for detailed examples of how the alignment affects the layout of the box.

Declaration
public Box<T> RightOf(Box<T> left, Alignment alignment)
Parameters
Type Name Description

Box<T>

left

The Box<T> to place to the left of this one

Alignment

alignment

How to align the boxes if one is shorter than the other.
Returns
Type Description

Box<T>

A Box<T> consisting of this box with left placed to the left of it.
Examples
var box = Box.FromString(string.Join('\n', "abc".AsEnumerable()))
    .RightOf(string.Join('\n', "def".AsEnumerable()))
    .WithBorder();
Console.Write(box.ToString());
// Output:
// ┌──┐
// │da│
// │eb│
// │fc│
// └──┘
See Also
RightOf(Box<T>, Alignment)

Select<U>(Func<T, U>)

Apply a function to all the annotations in the current document.

Declaration
public Box<U> Select<U>(Func<T, U> selector)
Parameters
Type Name Description

Func<T, U>

selector

The function to apply to the annotations.
Returns
Type Description

Box<U>

A document with all of the annotations replaced with the return value of selector
Type Parameters
Name Description

U

ToString()

Render this Box<T> as a string

Declaration
public override string ToString()
Returns
Type Description

String

Transparent(Int32, Int32)

Creates a transparent Box<T> with the specified dimensions. If the box is placed InFrontOf(Box<T>, Alignment) another box, the other box will be visible through the transparent box.

Declaration
public static Box<T> Transparent(int width, int height)
Parameters
Type Name Description

Int32

width

The width of the box

Int32

height

The height of the box
Returns
Type Description

Box<T>

A transparent Box<T>

WithBorder()

Creates a Box<T> consisting of the current box with a border drawn around it.

Declaration
public Box<T> WithBorder()
Returns
Type Description

Box<T>

A Box<T> consisting of the current box with a border drawn around it.
Examples
var box = Box.FromString("abc\ndef\nghi")
    .WithBorder();
Console.Write(box);
// Output:
// ┌───┐
// │abc│
// │def│
// │ghi│
// └───┘

Write(TextWriter, CancellationToken)

Write the Box<T> into a TextWriter.

Declaration
public ValueTask Write(TextWriter writer, CancellationToken cancellationToken = null)
Parameters
Type Name Description

TextWriter

writer

The TextWriter

CancellationToken

cancellationToken

A CancellationToken
Returns
Type Description

ValueTask

A ValueTask which will complete when the Box<T> has been written to the writer.

Operators

Implicit(String to Box<T>)

Implicitly convert a string to a Box<T>

Declaration
public static implicit operator Box<T>(string str)
Parameters
Type Name Description

String

str
Returns
Type Description

Box<T>
Remarks

This implicit conversion is equivalent to FromString(String).

In This Article