Typewriter<T>
CLASS
A component to create versatile typewriter animations with.
A typewriter animation is an type of text based animation in which
a piece of text is typed one letter at a time at a certain interval.
Has support for: multiple cursors, cursor selection, mouse movement,
and keyboard movement.
There are two main ways to create a typewriter animation:
1. By using the `typewriterFromSentences` function, it can create
single cursor animations from sentences (strings). It does do
by comparing and diffing the sentences and generating the
required keystrokes to go from one sentence to another.
2. You can use the typewriter composer, a web based tool to
generate the animations using your own keyboard.
It can be found at:
https://www.uiloos.dev/docs/typewriter/composer/
Since 1.2.0
Constructor
Creates an Typewriter based on the TypewriterConfig config.
You can also optionally provide an subscriber so you can get
informed of the changes happening to the Typewriter.
Since 1.2.0
Signature
Parameters
subscriber:
TypewriterSubscriber<T>
An optional subscriber which responds to changes in the Typewriter.
Throws
TypewriterBlinkAfterError
blinkAfter duration must be a positive number
TypewriterDelayError
delay duration must be a positive number
TypewriterRepeatError
repeat must be a positive number
TypewriterRepeatDelayError
repeatDelay must be a positive number or zero
TypewriterRepeatDelayError
repeatDelay must be a positive number or zero
TypewriterCursorOutOfBoundsError
cursor must be in bounds of text
TypewriterCursorNotAtSelectionEdgeError
when cursor has a selection the cursor must be on edges of the selection
TypewriterCursorSelectionOutOfBoundsError
the start and end of the selection must be in bounds of the text
TypewriterCursorSelectionInvalidRangeError
the start of a selection must on or after the end of a selection
TypewriterActionUnknownCursorError
actions must use cursors that exist
Properties
actions
The actions which the `Typewriter` is going to perform.
Basically the representation of the entire animation.
The actions happen in a linear fashion, meaning the first item
in the array is chronologically the first action, and the last
item in the array the last action.
Since 1.2.0
blinkAfter
number
The time it takes until a cursor starts blinking again after
the cursor was used.
A cursor does not blink when it is used until after a certain
time. So if you keep typing the cursor does not blink, until
you stop typing for some "predefined amount" of time.
The `blinkAfter` is what represents that 'predefined amount' of
time, you can also say this is a debounce time.
Note: when you set the `blinkAfter` to a number lower or equal to
the `delay` of a `TypewriterAction`, it will negate the debounce.
The effect is that all "CHANGED" events will have a "BLINKING"
event. This might not "visually" affect your animation, but
will make the `Typewriter` send extra events. If this happens it
is technically as "misconfiguration" on your part, but the
Typewriter will not throw any errors, since visually nothing
bad happens.
Defaults to after `250` milliseconds.
Since 1.2.0
hasBeenStoppedBefore
boolean
Whether or not the Typewriter has been stopped at one point
before during the current animation.
The `hasBeenStoppedBefore` is tied to the lifecycle of an
animation, and reflects if the current animation has been
stopped before or not.
Whenever a new animation starts the `hasBeenStoppedBefore`
resets to `false`. An animation starts whenever `play()` is
called, or through autoPlay, and lasts until there are no
more actions, or `stop()` is called.
Use case: say you are making an animation which has a stop button
to stop the animation. Say you also have another feature: a pause
whenever the user hovers over the typewriter animation. These two
features would cause a conflict:
Whenever the mouse over happens you call `play()`, which negates
the `stop()`, causing the typewriter to play again.
To fix this problem you should on the mouse over not call
`play()` whenever `hasBeenStoppedBefore` is `true`.
`hasBeenStoppedBefore` is tied to the animation cycle so a user
clicks on the stop button, and then on the play button, the
hover on pause will work again. The hover now works only because
`hasBeenStoppedBefore` is now false.
Since 1.2.0
history
Contains the history of the changes in the views array.
Tracks 8 types of changes:
1. INITIALIZED: fired when Typewriter is initialized
2. CHANGED: fired when a change in the text of the typewriter
occurred, when a cursor moves, or a when a cursors selection
changes.
3. PLAYING: fired when play is called.
4. PAUSED: fired when pause is called.
5. STOPPED: fire when stop is called.
6. FINISHED: fired when the animation was finished. When the
Typewriter is configured to repeat indefinitely the FINISHED
event will never fire.
7. BLINKING: fired when one of the cursors started blinking.
8. REPEATING: fired when the animation starts repeating.
Goes only as far back as configured in the `Config` property
`keepHistoryFor`, to prevent an infinitely growing history.
Note that by default no history is kept, as `keepHistoryFor`
is zero by default.
The last item in the `history` is the current active item. The
further to the left the further in the past you go.
This means that a history at index 0 is further in the past than
an item at index 1.
Since 1.2.0
isFinished
boolean
Whether or not the `Typewriter` has finished playing the entire
animation.
Note: when `repeat` is configured as `true` the animation will
never finish.
Note: when the `Typewriter` is initialized the `isFinished`
boolean will always be set to `false`, regardless of whether
or not there are any actions.
Since 1.2.0
lastPerformedAction
TypewriterAction
|
null
The last action that was performed by the Typewriter.
Note: `lastPerformedAction` is not affected by repeats.
Since 1.2.0
repeat
number
|
boolean
Whether or not this animation repeats and how often.
There are three ways to define `repeat`.
1. When `repeat` is `false` or `1` it will never repeat the
animation, the animation will run only once.
2. When `repeat` is `true` it will repeat the animation forever.
3. When `repeat` is a number it will repeat the animation
for given number of times. If the number is 0 or a negative
number is provided a error occurs.
Defaults to `false` meaning that the animation will run once.
Since 1.2.0
text
string
The current text of the `Typewriter` which it currently displays.
For example if the actions are type in 'a' 3 times then a
backspace. The `text` would be the following, after each of
the 4 actions:
1. 'a'
2. 'aa'
3. 'aaa'
4. 'aa'
Since 1.2.0
Methods
initialize
Initializes the Typewriter based on the config provided.
This effectively resets the Typewriter when called,
including the history.
Since 1.2.0
Signature
Parameters
Throws
TypewriterBlinkAfterError
blinkAfter duration must be a positive number
TypewriterDelayError
delay duration must be a positive number
TypewriterRepeatError
repeat must be a positive number
TypewriterRepeatDelayError
repeatDelay must be a positive number or zero
TypewriterRepeatDelayError
repeatDelay must be a positive number or zero
TypewriterCursorOutOfBoundsError
cursor must be in bounds of text
TypewriterCursorNotAtSelectionEdgeError
when cursor has a selection the cursor must be on edges of the selection
TypewriterCursorSelectionOutOfBoundsError
the start and end of the selection must be in bounds of the text
TypewriterCursorSelectionInvalidRangeError
the start of a selection must on or after the end of a selection
TypewriterActionUnknownCursorError
actions must use cursors that exist
pause
When the Typewriter is playing it will pause the animation, as
if the person using the typewriter stops typing, this means that
the cursors will start blinking again.
Calling `play()` again will continue the animation.
For example: when the `pause` of the current `TypewriterAction`
is 1 second and the `pause` is called after 0.8 seconds, it will
after `play` is called, take 0.2 seconds to go to the next
action.
Since 1.2.0
Signature
pause():
void
play
When the Typewriter is paused or stopped it will start the
animation from that point. If the animation was finished calling
`play()` will restart the animation.
When there are is no more animations the Typewriter will stop
automatically.
Is called automatically when the Typewriter is instantiated
and there are `actions` configured and `autoPlay` is `true`.
Note: the animation will only start when there are one or more
actions are defined.
Since 1.2.0
Signature
play():
void
stop
When the Typewriter is playing it will stop the animation.
Calling `play()` again will restart the animation.
Note: this will keep the text of the Typewriter as is, util
`play()` is called again then the text will reset.
Note: calling stop will also reset the number of repeats if
`repeat` was set to a number.
Since 1.2.0
Signature
stop():
void
subscribe
Subscribe to changes of the Typewriter. The function you provide
will get called whenever changes occur in the Typewriter.
Returns an unsubscribe function which when called will
unsubscribe from the Typewriter.
Since 1.2.0
Signature
Parameters
Returns
A function which when called will unsubscribe from the Typewriter.
unsubscribe
Unsubscribe the subscriber so it no longer receives changes / updates
of the state changes of the Typewriter.
Since 1.2.0
Signature
Parameters
unsubscribeAll
Unsubscribes all subscribers at once, all subscribers will no
longer receives changes / updates of the state changes of
the Typewriter.
Since 1.5.0
Signature
unsubscribeAll():
void
Creates an Typewriter based on the TypewriterConfig config.
You can also optionally provide an subscriber so you can get
informed of the changes happening to the Typewriter.
Since 1.2.0
Signature
Parameters
subscriber:
TypewriterSubscriber<T>
An optional subscriber which responds to changes in the Typewriter.
Throws
An optional subscriber which responds to changes in the Typewriter.
Throws
TypewriterBlinkAfterError blinkAfter duration must be a positive number
TypewriterDelayError delay duration must be a positive number
TypewriterRepeatError repeat must be a positive number
TypewriterRepeatDelayError repeatDelay must be a positive number or zero
TypewriterRepeatDelayError repeatDelay must be a positive number or zero
TypewriterCursorOutOfBoundsError cursor must be in bounds of text
TypewriterCursorNotAtSelectionEdgeError when cursor has a selection the cursor must be on edges of the selection
TypewriterCursorSelectionOutOfBoundsError the start and end of the selection must be in bounds of the text
TypewriterCursorSelectionInvalidRangeError the start of a selection must on or after the end of a selection
TypewriterActionUnknownCursorError actions must use cursors that exist
actions
The actions which the `Typewriter` is going to perform.
Basically the representation of the entire animation.
The actions happen in a linear fashion, meaning the first item
in the array is chronologically the first action, and the last
item in the array the last action.
Since 1.2.0
blinkAfter
number
The time it takes until a cursor starts blinking again after
the cursor was used.
A cursor does not blink when it is used until after a certain
time. So if you keep typing the cursor does not blink, until
you stop typing for some "predefined amount" of time.
The `blinkAfter` is what represents that 'predefined amount' of
time, you can also say this is a debounce time.
Note: when you set the `blinkAfter` to a number lower or equal to
the `delay` of a `TypewriterAction`, it will negate the debounce.
The effect is that all "CHANGED" events will have a "BLINKING"
event. This might not "visually" affect your animation, but
will make the `Typewriter` send extra events. If this happens it
is technically as "misconfiguration" on your part, but the
Typewriter will not throw any errors, since visually nothing
bad happens.
Defaults to after `250` milliseconds.
Since 1.2.0
hasBeenStoppedBefore
boolean
Whether or not the Typewriter has been stopped at one point
before during the current animation.
The `hasBeenStoppedBefore` is tied to the lifecycle of an
animation, and reflects if the current animation has been
stopped before or not.
Whenever a new animation starts the `hasBeenStoppedBefore`
resets to `false`. An animation starts whenever `play()` is
called, or through autoPlay, and lasts until there are no
more actions, or `stop()` is called.
Use case: say you are making an animation which has a stop button
to stop the animation. Say you also have another feature: a pause
whenever the user hovers over the typewriter animation. These two
features would cause a conflict:
Whenever the mouse over happens you call `play()`, which negates
the `stop()`, causing the typewriter to play again.
To fix this problem you should on the mouse over not call
`play()` whenever `hasBeenStoppedBefore` is `true`.
`hasBeenStoppedBefore` is tied to the animation cycle so a user
clicks on the stop button, and then on the play button, the
hover on pause will work again. The hover now works only because
`hasBeenStoppedBefore` is now false.
Since 1.2.0
history
Contains the history of the changes in the views array.
Tracks 8 types of changes:
1. INITIALIZED: fired when Typewriter is initialized
2. CHANGED: fired when a change in the text of the typewriter
occurred, when a cursor moves, or a when a cursors selection
changes.
3. PLAYING: fired when play is called.
4. PAUSED: fired when pause is called.
5. STOPPED: fire when stop is called.
6. FINISHED: fired when the animation was finished. When the
Typewriter is configured to repeat indefinitely the FINISHED
event will never fire.
7. BLINKING: fired when one of the cursors started blinking.
8. REPEATING: fired when the animation starts repeating.
Goes only as far back as configured in the `Config` property
`keepHistoryFor`, to prevent an infinitely growing history.
Note that by default no history is kept, as `keepHistoryFor`
is zero by default.
The last item in the `history` is the current active item. The
further to the left the further in the past you go.
This means that a history at index 0 is further in the past than
an item at index 1.
Since 1.2.0
isFinished
boolean
Whether or not the `Typewriter` has finished playing the entire
animation.
Note: when `repeat` is configured as `true` the animation will
never finish.
Note: when the `Typewriter` is initialized the `isFinished`
boolean will always be set to `false`, regardless of whether
or not there are any actions.
Since 1.2.0
lastPerformedAction
TypewriterAction | null
The last action that was performed by the Typewriter.
Note: `lastPerformedAction` is not affected by repeats.
Since 1.2.0
repeat
number | boolean
Whether or not this animation repeats and how often.
There are three ways to define `repeat`.
1. When `repeat` is `false` or `1` it will never repeat the
animation, the animation will run only once.
2. When `repeat` is `true` it will repeat the animation forever.
3. When `repeat` is a number it will repeat the animation
for given number of times. If the number is 0 or a negative
number is provided a error occurs.
Defaults to `false` meaning that the animation will run once.
Since 1.2.0
text
string
The current text of the `Typewriter` which it currently displays.
For example if the actions are type in 'a' 3 times then a
backspace. The `text` would be the following, after each of
the 4 actions:
1. 'a'
2. 'aa'
3. 'aaa'
4. 'aa'
Since 1.2.0
initialize
Initializes the Typewriter based on the config provided.
This effectively resets the Typewriter when called,
including the history.
Since 1.2.0
Signature
Parameters
Throws
Throws
TypewriterBlinkAfterError blinkAfter duration must be a positive number
TypewriterDelayError delay duration must be a positive number
TypewriterRepeatError repeat must be a positive number
TypewriterRepeatDelayError repeatDelay must be a positive number or zero
TypewriterRepeatDelayError repeatDelay must be a positive number or zero
TypewriterCursorOutOfBoundsError cursor must be in bounds of text
TypewriterCursorNotAtSelectionEdgeError when cursor has a selection the cursor must be on edges of the selection
TypewriterCursorSelectionOutOfBoundsError the start and end of the selection must be in bounds of the text
TypewriterCursorSelectionInvalidRangeError the start of a selection must on or after the end of a selection
TypewriterActionUnknownCursorError actions must use cursors that exist
pause
When the Typewriter is playing it will pause the animation, as
if the person using the typewriter stops typing, this means that
the cursors will start blinking again.
Calling `play()` again will continue the animation.
For example: when the `pause` of the current `TypewriterAction`
is 1 second and the `pause` is called after 0.8 seconds, it will
after `play` is called, take 0.2 seconds to go to the next
action.
Since 1.2.0
Signature
pause():
void
play
When the Typewriter is paused or stopped it will start the
animation from that point. If the animation was finished calling
`play()` will restart the animation.
When there are is no more animations the Typewriter will stop
automatically.
Is called automatically when the Typewriter is instantiated
and there are `actions` configured and `autoPlay` is `true`.
Note: the animation will only start when there are one or more
actions are defined.
Since 1.2.0
Signature
play():
void
stop
When the Typewriter is playing it will stop the animation.
Calling `play()` again will restart the animation.
Note: this will keep the text of the Typewriter as is, util
`play()` is called again then the text will reset.
Note: calling stop will also reset the number of repeats if
`repeat` was set to a number.
Since 1.2.0
Signature
stop():
void
subscribe
Subscribe to changes of the Typewriter. The function you provide
will get called whenever changes occur in the Typewriter.
Returns an unsubscribe function which when called will
unsubscribe from the Typewriter.
Since 1.2.0
Signature
Parameters
Returns
Returns
A function which when called will unsubscribe from the Typewriter.
unsubscribe
Unsubscribe the subscriber so it no longer receives changes / updates of the state changes of the Typewriter.
Since 1.2.0
Signature
Parameters
unsubscribeAll
Unsubscribes all subscribers at once, all subscribers will no longer receives changes / updates of the state changes of the Typewriter.
Since 1.5.0