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
Inherited Members
Declaration
public abstract class Box<T>
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(int, int) 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>
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(int, int) 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>;.

Height

The width of the Box<T> in lines.

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

int
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(int, int) 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>;.

Width

The width of the Box<T> in characters.

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

int
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(int, int) 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>;.

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(int, int) 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 = Alignment.Start)
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.
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(int, int) 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>;.

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.
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(int, int) 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>;.

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(int, int) 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(int, int) 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 = Alignment.Start)
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.
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(int, int) 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>;.

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(int, int) 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 = Alignment.Start)
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.
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(int, int) 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>;.

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(int, int) 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(int, int) 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 = Alignment.Start)
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.
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(int, int) 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>;.

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(int, int) 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 = Alignment.Start)
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.
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(int, int) 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>;.

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, 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

The type of annotations in the resulting 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(int, int) 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>;.

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

The type of annotations in the resulting 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(int, int) 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>;.

Render(IDocumentRenderer<T>, CancellationToken)

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

Declaration
public ValueTask Render(IDocumentRenderer<T> renderer, CancellationToken cancellationToken = default)
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.
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(int, int) 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>;.

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(int, int) 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 = Alignment.Start)
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.
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(int, int) 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>;.

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

The type of annotations in the resulting 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(int, int) 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>;.

ToString()

Render this Box<T> as a string.

Declaration
public override string ToString()
Returns
Type Description

string

A string representation of the box.
Overrides
object.ToString()
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(int, int) 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>;.

Transparent(int, int)

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

int

width

The width of the box.

int

height

The height of the box.
Returns
Type Description

Box<T>

A transparent Box<T>.
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(int, int) 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>;.

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.
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(int, int) 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>;.

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 = default)
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.
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(int, int) 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>;.

Operators

implicit operator Box<T>(string)

Implicitly convert a string to a Box<T>.

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

string

str

The string.
Returns
Type Description

Box<T>
Remarks

This implicit conversion is equivalent to FromString(string).

In This Article