Class TypewriterEffect

Reveals text one character at a time, the way a terminal prints in an old film.

Inheritance
object
TextEffectBase
TypewriterEffect
Implements
Inherited Members
Namespace: Scylla.TextMode
Assembly: ScyllaTextMode.dll
Syntax
public sealed class TypewriterEffect : TextEffectBase, ITextEffect, IDisposable
Remarks

Speed is set in characters per second, and the duration follows from the length of the text. Setting Duration directly instead makes the text take exactly that long regardless of how long it is, which is what a sequence with fixed timing wants.

Layout is computed once when the effect starts and then held, so characters never shift position as more of them appear. Line breaks in the text move to the next row, and text that runs past the right edge of the region continues on the row below. Text that runs past the bottom of the region is dropped.

The insertion cursor is drawn with the existing Blink attribute, so it blinks in the shader at the view's configured text blink rate and costs nothing per frame.

Properties

AttributeMap

Gets or sets extra attributes per character of Text, for text that is not styled uniformly. Null, the default, applies Attributes to everything.

Declaration
public CellAttributes[] AttributeMap { get; set; }
Property Value
Type Description
CellAttributes[]
Remarks

Each entry corresponds to the character at the same index in Text, line breaks included, and is combined with Attributes rather than replacing it, so the uniform attributes stay the baseline and the map adds to it. A map shorter than the text leaves the characters past its end unstyled, which is what makes it reasonable to supply a map covering only a heading.

The array is used by reference and read as characters are revealed, so changing its contents mid-reveal restyles whatever has not been written yet.

Attributes

Gets or sets the cell attributes applied to revealed text.

Declaration
public CellAttributes Attributes { get; set; }
Property Value
Type Description
CellAttributes

Background

Gets or sets the background color of revealed text.

Declaration
public Color32 Background { get; set; }
Property Value
Type Description
Color32

CharactersPerSecond

Gets or sets the typing speed in characters per second. Setting this recomputes the duration from the length of the text when the effect starts.

Declaration
public float CharactersPerSecond { get; set; }
Property Value
Type Description
float

CursorCodepoint

Gets or sets the codepoint drawn one cell ahead of the last revealed character while typing. Zero draws no cursor. A solid block reads best.

Declaration
public uint CursorCodepoint { get; set; }
Property Value
Type Description
uint

Foreground

Gets or sets the foreground color of revealed text.

Declaration
public Color32 Foreground { get; set; }
Property Value
Type Description
Color32

KeepCursorOnCompletion

Gets or sets whether a blinking cursor is left sitting after the last character once the text is complete.

Declaration
public bool KeepCursorOnCompletion { get; set; }
Property Value
Type Description
bool
Remarks

The cursor is solid while text is being typed and only blinks once there is nothing left to type, which is how a terminal behaves and keeps the cursor from vanishing mid-line. The resting cursor is drawn by the view's cursor renderer, so its shape, color and blink rate all come from the Cursor settings in the TextMode configuration.

The cursor left behind is an ordinary cell carrying the cursor attribute, so it costs nothing to keep on screen and survives the effect being disposed. Whatever clears or redraws that area next removes it.

PublishCharacterEvents

Gets or sets whether the effect publishes a TypewriterCharacterRevealedEvent for each character it reveals.

Declaration
public bool PublishCharacterEvents { get; set; }
Property Value
Type Description
bool
Remarks

This is off by default. A line of a hundred characters would otherwise put a hundred dispatches through the event bus, which is only worth paying for when something is actually listening, typically to play a keystroke sound.

RevealedCount

Gets the number of characters revealed so far.

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

Text

Gets or sets the text to reveal. Setting this while the effect runs has no effect until it is started again.

Declaration
public string Text { get; set; }
Property Value
Type Description
string

VisibleCount

Gets the number of visible characters the text laid out to, which excludes line breaks and anything that fell outside the region.

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

Methods

OnEffectFinish(bool)

Called when the effect finishes, whether it completed, was skipped or was stopped.

Declaration
protected override void OnEffectFinish(bool completed)
Parameters
Type Name Description
bool completed

True when the effect reached its final state.
Overrides
Remarks

The default implementation does nothing. Override it to restore state an effect borrowed, which is what a corrupting effect needs so the grid is not left damaged.

OnEffectRelease()

Called when the effect is disposed. Return anything rented from the context here.

Declaration
protected override void OnEffectRelease()
Overrides

OnEffectStart()

Called when the effect starts, after the region is resolved and before any tick. Capture whatever the effect needs from the grid here.

Declaration
protected override void OnEffectStart()
Overrides

OnEffectTick(float, float)

Called once per tick to draw the effect at the given progress.

Declaration
protected override void OnEffectTick(float progress, float easedProgress)
Parameters
Type Name Description
float progress

Linear progress from 0 to 1.
float easedProgress

Progress with the easing curve applied.
Overrides

SetAttributeMap(CellAttributes[])

Sets extra attributes per character, for text that is not styled uniformly.

Declaration
public TypewriterEffect SetAttributeMap(CellAttributes[] attributeMap)
Parameters
Type Name Description
CellAttributes[] attributeMap

Attributes per character of the text, or null for uniform styling.
Returns
Type Description
TypewriterEffect

This effect, for chaining.
Remarks

See AttributeMap for how the map lines up with the text and combines with the uniform attributes.

SetAttributes(CellAttributes)

Sets the cell attributes revealed text is drawn with.

Declaration
public TypewriterEffect SetAttributes(CellAttributes attributes)
Parameters
Type Name Description
CellAttributes attributes

Attributes to apply.
Returns
Type Description
TypewriterEffect

This effect, for chaining.

SetCharactersPerSecond(float)

Sets the typing speed in characters per second.

Declaration
public TypewriterEffect SetCharactersPerSecond(float charactersPerSecond)
Parameters
Type Name Description
float charactersPerSecond

Characters revealed each second.
Returns
Type Description
TypewriterEffect

This effect, for chaining.

SetColors(Color32, Color32)

Sets the colors revealed text is drawn in.

Declaration
public TypewriterEffect SetColors(Color32 foreground, Color32 background)
Parameters
Type Name Description
Color32 foreground

Foreground color.
Color32 background

Background color.
Returns
Type Description
TypewriterEffect

This effect, for chaining.

SetCursor(char)

Draws a cursor one cell ahead of the last revealed character while typing.

Declaration
public TypewriterEffect SetCursor(char cursor)
Parameters
Type Name Description
char cursor

The character to use as the cursor.
Returns
Type Description
TypewriterEffect

This effect, for chaining.

SetKeepCursorOnCompletion(bool)

Leaves a blinking cursor after the last character once the text is complete.

Declaration
public TypewriterEffect SetKeepCursorOnCompletion(bool keep)
Parameters
Type Name Description
bool keep

True to leave a cursor behind.
Returns
Type Description
TypewriterEffect

This effect, for chaining.

SetPublishCharacterEvents(bool)

Turns per-character event publishing on or off.

Declaration
public TypewriterEffect SetPublishCharacterEvents(bool publish)
Parameters
Type Name Description
bool publish

True to publish an event for each revealed character.
Returns
Type Description
TypewriterEffect

This effect, for chaining.

SetText(string)

Sets the text to reveal.

Declaration
public TypewriterEffect SetText(string text)
Parameters
Type Name Description
string text

The text to type out.
Returns
Type Description
TypewriterEffect

This effect, for chaining.

Implements

Extension Methods