asciimatics package¶

Subpackages¶

Submodules¶

asciimatics.constants module¶

This module is just a collection of simple helper functions.

asciimatics.constants.COLOUR_REGEX = '^\\$\\{((\\d+),(\\d+),(\\d+)|(\\d+),(\\d+)|(\\d+))\\}(.*)'¶: Regex for asciimatics ${c,a,b} embedded colour attributes.

asciimatics.constants.MAPPING_ATTRIBUTES = {'1': 1, '2': 2, '3': 3, '4': 4}¶: Attribute conversion table for the ${c,a} form of attributes for paint.

asciimatics.effects module¶

This module defines Effects which can be used for animations. For more details see http://asciimatics.readthedocs.io/en/latest/animation.html

class asciimatics.effects.Background(screen, bg=0, **kwargs)¶

Bases: asciimatics.effects.Effect

Effect to be used as a Desktop background. This sets the background to the specified colour.

Parameters:	screen – The Screen being used for the Scene. bg – Optional colour for the background.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.BannerText(screen, renderer, y, colour, bg=0, **kwargs)¶

Bases: asciimatics.effects.Effect

Special effect to scroll some text (from a Renderer) horizontally like a banner.

Parameters:	screen – The Screen being used for the Scene. renderer – The renderer to be scrolled y – The line (y coordinate) for the start of the text. colour – The default foreground colour to use for the text. bg – The default background colour to use for the text.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Clock(screen, x, y, r, bg=0, **kwargs)¶

Bases: asciimatics.effects.Effect

An ASCII ticking clock (telling the correct local time).

Parameters:	screen – The Screen being used for the Scene. x – X coordinate for the centre of the clock. y – Y coordinate for the centre of the clock. r – Radius of the clock. bg – Background colour for the clock.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Cog(screen, x, y, radius, direction=1, colour=7, **kwargs)¶

Bases: asciimatics.effects.Effect

A rotating cog.

Parameters:	screen – The Screen being used for the Scene. x – X coordinate of the centre of the cog. y – Y coordinate of the centre of the cog. radius – The radius of the cog. direction – The direction of rotation. Positive numbers are anti-clockwise, negative numbers clockwise. colour – The colour of the cog.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Cycle(screen, renderer, y, **kwargs)¶

Bases: asciimatics.effects.Effect

Special effect to cycle the colours on some specified text from a Renderer. The text is automatically centred to the width of the Screen. This effect is not compatible with multi-colour rendered text.

Parameters:	screen – The Screen being used for the Scene. renderer – The Renderer which is to be cycled. y – The line (y coordinate) for the start of the text.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Effect(screen, start_frame=0, stop_frame=0, delete_count=None)¶

Bases: object

Abstract class to handle a special effect on the screen. An Effect can cover anything from a static image at the start of the Scene through to dynamic animations that need to be redrawn for every frame.

The basic interaction with a Scene is as follows:

The Scene will register with the Effect when it as added using register_scene().
The Scene will call Effect.reset() for all Effects when it starts.
The Scene will determine the number of frames required (either through explicit configuration or querying stop_frame for every Effect).
It will then run the scene, calling Effect.update() for each effect that is in the scene. The base Effect will then call the abstract method _update() if the effect should be visible.
If any keys are pressed or the mouse moved/clicked, the scene will call Effect.process_event() for each event, allowing the effect to act on it if needed.

New Effects, therefore need to implement the abstract methods on this class to satisfy the contract with Scene. Since most effects don’t require user interaction, the default process_event() implementation will ignore the event (and so effects don’t need to implement this method unless needed).

Parameters:	screen – The Screen that will render this Effect. start_frame – Start index for the effect. stop_frame – Stop index for the effect. delete_count – Number of frames before this effect is deleted.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Julia(screen, c=None, **kwargs)¶

Bases: asciimatics.effects.Effect

Julia Set generator. See http://en.wikipedia.org/wiki/Julia_set for more information on this fractal.

Parameters:	screen – The Screen being used for the Scene. c – The starting value of ‘c’ for the Julia Set.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Matrix(screen, **kwargs)¶

Bases: asciimatics.effects.Effect

Matrix-like falling green letters.

Parameters:	screen – The Screen being used for the Scene.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Mirage(screen, renderer, y, colour, **kwargs)¶

Bases: asciimatics.effects.Effect

Special effect to make bits of the specified text appear over time. This text is automatically centred on the screen.

Parameters:	screen – The Screen being used for the Scene. renderer – The renderer to be displayed. y – The line (y coordinate) for the start of the text. colour – The colour attribute to use for the text.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Print(screen, renderer, y, x=None, colour=7, attr=0, bg=0, clear=False, transparent=True, speed=4, **kwargs)¶

Bases: asciimatics.effects.Effect

Special effect that simply prints the specified text (from a Renderer) at the required location.

Parameters:

screen – The Screen being used for the Scene.
renderer – The renderer to be printed.
x – The column (x coordinate) for the start of the text. If not specified, defaults to centring the text on screen.
y – The line (y coordinate) for the start of the text.
colour – The foreground colour to use for the text.
attr – The colour attribute to use for the text.
bg – The background colour to use for the text.
clear – Whether to clear the text before stopping.
transparent – Whether to print spaces (and so be able to overlay other Effects). If False, this will redraw all characters and so replace any Effect underneath it.
speed – The refresh rate in frames between refreshes.

Note that a speed of 1 will force the Screen to redraw the Effect every frame update, while a value of 0 will redraw on demand - i.e. will redraw every time that an update is required by another Effect.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.RandomNoise(screen, signal=None, jitter=6, **kwargs)¶

Bases: asciimatics.effects.Effect

White noise effect - like an old analogue TV set that isn’t quite tuned right. If desired, a signal image (from a renderer) can be specified that will appear from the noise.

Parameters:	screen – The Screen being used for the Scene. signal – The renderer to use as the ‘signal’ in the white noise. jitter – The amount that the signal will jump when there is noise.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Scroll(screen, rate, **kwargs)¶

Bases: asciimatics.effects.Effect

Special effect to scroll the screen up at a required rate. Since the Screen has a limited size and will not wrap, ensure that it is large enough to Scroll for the desired time.

Parameters:	screen – The Screen being used for the Scene. rate – How many frames to wait between scrolling the screen.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Snow(screen, **kwargs)¶

Bases: asciimatics.effects.Effect

Settling snow effect.

Parameters:	screen – The Screen being used for the Scene.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Sprite(screen, renderer_dict, path, colour=7, clear=True, **kwargs)¶

Bases: asciimatics.effects.Effect

An animated character capable of following a path around the screen.

Parameters:	screen – The Screen being used for the Scene. renderer_dict – A dictionary of Renderers to use for displaying the Sprite. path – The Path for the Sprite to follow. colour – The colour to use to render the Sprite. clear – Whether to clear out old images or leave a trail.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

last_position()¶: Returns the last position of this Sprite as a tuple (x, y, width, height).

overlaps(other, use_new_pos=False)¶

Check whether this Sprite overlaps another.

Parameters:	other – The other Sprite to check for an overlap. use_new_pos – Whether to use latest position (due to recent update). Defaults to False.
Returns:	True if the two Sprites overlap.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Stars(screen, count, pattern='..+.. ...x... ...*... ', **kwargs)¶

Bases: asciimatics.effects.Effect

Add random stars to the screen and make them twinkle.

Parameters:	screen – The Screen being used for the Scene. count – The number of starts to create. pattern – The string pattern for the stars to loop through

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.effects.Wipe(screen, bg=0, **kwargs)¶

Bases: asciimatics.effects.Effect

Wipe the screen down from top to bottom.

Parameters:	screen – The Screen being used for the Scene. bg – Optional background colour to use for the wipe.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

asciimatics.effects.random() → x in the interval [0, 1).¶

asciimatics.event module¶

This module defines basic input events. For more details, see http://asciimatics.readthedocs.io/en/latest/.html

class asciimatics.event.Event¶

Bases: object

A class to hold information about an input event.

The exact contents varies from event to event. See specific classes for more information.

class asciimatics.event.KeyboardEvent(key_code)¶

Bases: asciimatics.event.Event

An event that represents a key press.

Its key field is the key_code. This is the ordinal representation of the key (taking into account keyboard state - e.g. caps lock) if possible, or an extended key code (the KEY_xxx constants in the Screen class) where not.

Parameters:	key_code – the ordinal value of the key that was pressed.

class asciimatics.event.MouseEvent(x, y, buttons)¶

Bases: asciimatics.event.Event

An event that represents a mouse move or click.

Allowed values for the buttons are any bitwise combination of LEFT_CLICK, RIGHT_CLICK and DOUBLE_CLICK.

Parameters:	x – The X coordinate of the mouse event. y – The Y coordinate of the mouse event. buttons – A bitwise flag for any mouse buttons that were pressed (if any).

asciimatics.exceptions module¶

This module defines the exceptions used by asciimatics.

exception asciimatics.exceptions.Highlander¶

Bases: Exception

There can be only one Layout or Widget with certain options set (designed to fill the rest of the screen). If you hit this exception you have a bug in your application.

If you don’t get the name, take a look at this link.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception asciimatics.exceptions.InvalidFields(fields)¶

Bases: Exception

When saving data from a Frame, you can ask the Frame to validate the data before saving. This is the exception that gets thrwn if any invalid datd is found.

Parameters:	fields – The list of the fields that are invalid.

fields¶: The list of fields that are invalid.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception asciimatics.exceptions.NextScene(name=None)¶

Bases: Exception

Any component can raise this exception to tell Asciimatics to move to the next Scene being played. Only effective inside Screen.play().

Parameters:	name – Next Scene to invoke. Defaults to next in the list.

name¶: The name of the next Scene to invoke.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception asciimatics.exceptions.ResizeScreenError(message, scene=None)¶

Bases: Exception

Asciimatics raises this Exception if the terminal is resized while playing a Scene (and the Screen has been told not to ignore a resizing event).

Parameters:	message – Error message for this exception. scene – Scene that was active at time of resize.

scene¶: The Scene that was running when the Screen resized.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception asciimatics.exceptions.StopApplication(message)¶

Bases: Exception

Any component can raise this exception to tell Asciimatics to stop running. If playing a Scene (i.e. inside Screen.play()) the Screen will return to the calling function. When used at any other time, the exception will need to be caught by the application using Asciimatics.

Parameters:	message – Error message for this exception.

with_traceback()¶: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

asciimatics.parsers module¶

This module provides parsers to create ColouredText objects from embedded control strings.

class asciimatics.parsers.AnsiTerminalParser¶

Bases: asciimatics.parsers.Parser

Parser to handle ANSI terminal escape codes.

Initialize the parser.

parse()¶

Generator to return coloured text from raw text.

Generally returns a stream of text/color tuple/offset tuples. If there is a colour update with no visible text, the first element of the tuple may be None.

Returns:	a 3-tuple of (start offset in raw text, command to execute, parameters)

reset(text, colours)¶

Reset the parser to analyze the supplied raw text.

Parameters:	text – raw text to process. colours – colour tuple to initialise the colour map.

class asciimatics.parsers.AsciimaticsParser¶

Bases: asciimatics.parsers.Parser

Parser to handle Asciimatics rendering escape strings.

Initialize the parser.

parse()¶

Generator to return coloured text from raw text.

Generally returns a stream of text/color tuple/offset tuples. If there is a colour update with no visible text, the first element of the tuple may be None.

Returns:	a 3-tuple of (start offset in raw text, command to execute, parameters)

reset(text, colours)¶

Reset the parser to analyze the supplied raw text.

Parameters:	text – raw text to process. colours – colour tuple to initialise the colour map.

class asciimatics.parsers.ControlCodeParser¶

Bases: asciimatics.parsers.Parser

Parser to replace all control codes with a readable version - e.g. “^M” for r.

Initialize the parser.

parse()¶

Generator to return coloured text from raw text.

Generally returns a stream of text/color tuple/offset tuples. If there is a colour update with no visible text, the first element of the tuple may be None.

Returns:	a 3-tuple of (start offset in raw text, command to execute, parameters)

reset(text, colours=None)¶

Reset the parser to analyze the supplied raw text.

Parameters:	text – raw text to process. colours – colour tuple to initialise the colour map.

class asciimatics.parsers.Parser¶

Bases: object

Abstract class to represent text parsers that extract colour control codes from raw text and convert them to displayable text and associated colour maps.

Initialize the parser.

CHANGE_COLOURS = 1¶: Command to change active colour tuple. Parameters are the 3-tuple of (fg, attr, bg)

CLEAR_SCREEN = 8¶: Clear the screen. No parameters.

DELETE_CHARS = 5¶: Command to delete next N characters from this line.

DELETE_LINE = 4¶: Command to delete part of the current line. Params are 0, 1 and 2 for end, start, all.

DISPLAY_TEXT = 0¶: Command to display some text. Parameter is the text to display

MOVE_ABSOLUTE = 2¶: Command to move cursor to abs position. Parameters are (x, y) where each are absolute positions.

MOVE_RELATIVE = 3¶: Command to move cursor to relative position. Parameters are (x, y) where each are relative positions.

NEXT_TAB = 6¶: Next tab stop

SHOW_CURSOR = 7¶: Set cursor visibility. Param is boolean setting True=visible

parse()¶

Generator to return coloured text from raw text.

Generally returns a stream of text/color tuple/offset tuples. If there is a colour update with no visible text, the first element of the tuple may be None.

Returns:	a 3-tuple of (start offset in raw text, command to execute, parameters)

reset(text, colours)¶

Reset the parser to analyze the supplied raw text.

Parameters:	text – raw text to process. colours – colour tuple to initialise the colour map.

asciimatics.particles module¶

This module implements a particle system for complex animcation effects. For more details, see http://asciimatics.readthedocs.io/en/latest/animation.html

class asciimatics.particles.DropEmitter(screen, life_time)¶

Bases: asciimatics.particles.ParticleEmitter

Replicate the whole screen with Particles and then drop them a cell at a time.

Parameters:	screen – The Screen being used for this particle system. life_time – The life time of this particle system.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.DropScreen(screen, life_time, **kwargs)¶

Bases: asciimatics.particles.ParticleEffect

Drop all the text on the screen as if it was subject to gravity.

See ParticleEffect for details of the parameters.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.Explosion(screen, x, y, life_time, **kwargs)¶

Bases: asciimatics.particles.ParticleEffect

An explosion effect.

Parameters:	screen – The Screen being used for the Scene. x – The column (x coordinate) for the origin of the effect. y – The line (y coordinate) for the origin of the effect. life_time – The life time of the effect.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.ExplosionFlames(screen, x, y, life_time)¶

Bases: asciimatics.particles.ParticleEmitter

An explosion of flame and smoke.

Parameters:	screen – The Screen being used for this particle system. x – The column (x coordinate) for the origin of this explosion. y – The line (y coordinate) for the origin of this explosion. life_time – The life time of this explosion.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.PalmExplosion(screen, x, y, life_time, on_each=None)¶

Bases: asciimatics.particles.ParticleEmitter

A classic firework explosion into a palm shape.

Parameters:	screen – The Screen being used for this particle system. x – The column (x coordinate) for the origin of this explosion. y – The line (y coordinate) for the origin of this explosion. life_time – The life time of this explosion. on_each – The function to call to spawn a trail.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.PalmFirework(screen, x, y, life_time, **kwargs)¶

Bases: asciimatics.particles.ParticleEffect

Classic palm shaped firework.

Parameters:	screen – The Screen being used for the Scene. x – The column (x coordinate) for the origin of the effect. y – The line (y coordinate) for the origin of the effect. life_time – The life time of the effect.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.Particle(chars, x, y, dx, dy, colours, life_time, move, next_colour=None, next_char=None, parm=None, on_create=None, on_each=None, on_destroy=None)¶

Bases: object

A single particle in a Particle Effect.

Parameters:

chars – String of characters to use for the particle.
x – The initial horizontal position of the particle.
y – The initial vertical position of the particle.
dx – The initial horizontal velocity of the particle.
dy – The initial vertical velocity of the particle.
colours – A list of colour tuples to use for the particle.
life_time – The life time of the particle.
move – A function which returns the next location of the particle.
next_colour – An optional function to return the next colour for the particle. Defaults to a linear progression of chars.
next_char – An optional function to return the next character for the particle. Defaults to a linear progression of colours.
parm – An optional parameter for use within any of the
on_create – An optional function to spawn new particles when this particle first is created.
on_each – An optional function to spawn new particles for every frame of this particle (other than creation/destruction).
on_destroy – An optional function to spawn new particles when this particle is destroyed.

last()¶: The last attributes returned for this particle - typically used for clearing out the particle on the next frame. See next() for details of the returned results.

next()¶

The set of attributes for this particle for the next frame to be rendered.

Returns:	A tuple of (character, x, y, fg, attribute, bg)

class asciimatics.particles.ParticleEffect(screen, x, y, life_time, **kwargs)¶

Bases: asciimatics.effects.Effect

An Effect that uses a ParticleEmitter to create the animation.

To define a new ParticleEffect, you must implement the reset() method to construct a chain of ParticleEmitter objects and append them to the internal _active_systems list.

Parameters:	screen – The Screen being used for the Scene. x – The column (x coordinate) for the origin of the effect. y – The line (y coordinate) for the origin of the effect. life_time – The life time of the effect.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.ParticleEmitter(screen, x, y, count, new_particle, spawn, life_time, blend=False)¶

Bases: object

An emitter for a particle system to create a set of _Particle objects for a ParticleEffect. After initialization, the emitter will be called once per frame to be displayed on the Screen.

Parameters:

screen – The screen to which the particle system will be rendered.
x – The x location of origin of the particle system.
y – The y location of origin of the particle system.
count – The count of new particles to spawn on each frame.
new_particle – The function to call to spawn a new particle.
spawn – The number of frames for which to spawn particles.
life_time – The life time of the whole particle system.
blend – Whether to blend particles or not. A blended system picks the colour based on the number of overlapping particles, while an unblended one picks the colour based on a the state of Each Particle individually as they are drawn. Defaults to False.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.Rain(screen, life_time, **kwargs)¶

Bases: asciimatics.particles.ParticleEffect

Rain storm effect.

See ParticleEffect for details of the parameters.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.RainSource(screen, life_time, on_each)¶

Bases: asciimatics.particles.ParticleEmitter

Source of the raindrops for a rain storm effect. This emits rain drops from a single line at the top of the screen (starting sufficiently off- screen to ensure that it can cover all the screen due to horizontal motion).

Parameters:	screen – The Screen being used for this particle system. life_time – The life time of this particle system. on_each – Function to call on each iteration of the particle.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.RingExplosion(screen, x, y, life_time)¶

Bases: asciimatics.particles.ParticleEmitter

A classic firework explosion in a simple ring.

Parameters:	screen – The Screen being used for this particle system. x – The column (x coordinate) for the origin of this explosion. y – The line (y coordinate) for the origin of this explosion. life_time – The life time of this explosion.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.RingFirework(screen, x, y, life_time, **kwargs)¶

Bases: asciimatics.particles.ParticleEffect

Classic rocket with ring explosion.

Parameters:	screen – The Screen being used for the Scene. x – The column (x coordinate) for the origin of the effect. y – The line (y coordinate) for the origin of the effect. life_time – The life time of the effect.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.Rocket(screen, x, y, life_time, on_destroy=None)¶

Bases: asciimatics.particles.ParticleEmitter

A rocket being launched from the ground.

Parameters:	screen – The Screen being used for this particle system. x – The column (x coordinate) for the origin of the rocket. y – The line (y coordinate) for the origin of the rocket. life_time – The life time of the rocket. on_destroy – The function to call when the rocket explodes.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.SerpentExplosion(screen, x, y, life_time)¶

Bases: asciimatics.particles.ParticleEmitter

A firework explosion where each trail changes direction.

Parameters:	screen – The Screen being used for this particle system. x – The column (x coordinate) for the origin of this explosion. y – The line (y coordinate) for the origin of this explosion. life_time – The life time of this explosion.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.SerpentFirework(screen, x, y, life_time, **kwargs)¶

Bases: asciimatics.particles.ParticleEffect

A firework where each trail changes direction.

Parameters:	screen – The Screen being used for the Scene. x – The column (x coordinate) for the origin of the effect. y – The line (y coordinate) for the origin of the effect. life_time – The life time of the effect.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.ShootScreen(screen, x, y, life_time, **kwargs)¶

Bases: asciimatics.particles.ParticleEffect

Shoot the screen out like a massive gunshot.

Parameters:	screen – The Screen being used for the Scene. x – The column (x coordinate) for the origin of the effect. y – The line (y coordinate) for the origin of the effect. life_time – The life time of the effect.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.ShotEmitter(screen, x, y, life_time)¶

Bases: asciimatics.particles.ParticleEmitter

Replicate the whole screen with Particles and then explode the screen from a given location.

Parameters:	screen – The Screen being used for this particle system. x – The x position of the origin of the explosion. y – The y position of the origin of the explosion. life_time – The life time of this particle system.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.Splash(screen, x, y)¶

Bases: asciimatics.particles.ParticleEmitter

Splash effect for falling rain.

Parameters:	screen – The Screen being used for this particle system.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.StarExplosion(screen, x, y, life_time, points, on_each)¶

Bases: asciimatics.particles.ParticleEmitter

A classic firework explosion to a Peony shape with trails.

Parameters:	screen – The Screen being used for this particle system. x – The column (x coordinate) for the origin of this explosion. y – The line (y coordinate) for the origin of this explosion. life_time – The life time of this explosion. points – Number of points the explosion should have. on_each – The function to call to spawn a trail.

update()¶: The function to draw a new frame for the particle system.

class asciimatics.particles.StarFirework(screen, x, y, life_time, **kwargs)¶

Bases: asciimatics.particles.ParticleEffect

Classic rocket with star explosion.

Parameters:	screen – The Screen being used for the Scene. x – The column (x coordinate) for the origin of the effect. y – The line (y coordinate) for the origin of the effect. life_time – The life time of the effect.

Also see the common keyword arguments in Effect.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Reset the particle effect back to its initial state. This must be implemented by the child classes.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.particles.StarTrail(screen, x, y, life_time, colour)¶

Bases: asciimatics.particles.ParticleEmitter

A trail for a StarExplosion.

Parameters:	screen – The Screen being used for this particle system. x – The column (x coordinate) for the origin of this trail. y – The line (y coordinate) for the origin of this trail. life_time – The life time of this trail. colour – The colour of this trail.

update()¶: The function to draw a new frame for the particle system.

asciimatics.paths module¶

This module provides Paths to create animation effects with Sprites. For more details see http://asciimatics.readthedocs.io/en/latest/animation.html

class asciimatics.paths.DynamicPath(screen, x, y)¶

Bases: asciimatics.paths._AbstractPath

Class to create a dynamic path that reacts to events

The Screen will reset() the Path before iterating through each position using next_pos() and checking whether it has reached the end using is_finished().

To implement a DynamicPath, override the process_event() method to react to any user input.

is_finished()¶

Returns:	Whether this path has got to the end.

next_pos()¶

Returns:	The next position tuple (x, y) for the Sprite on this path.

process_event(event)¶

Process any mouse event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

reset()¶: Reset the Path for use next time.

class asciimatics.paths.Path¶

Bases: asciimatics.paths._AbstractPath

Class to record and play back the motion of a Sprite.

The Screen will reset() the Path before iterating through each position using next_pos() and checking whether it has reached the end using is_finished().

To define a Path, use the methods to jump to a location, wait or move between points.

is_finished()¶

Returns:	Whether this path has got to the end.

jump_to(x, y)¶

Jump straight to the newly specified location - i.e. teleport there and don’t create a path to get there.

Parameters:	x – X coord for the end position. y – Y coord for the end position.

move_round_to(points, steps)¶

Follow a path pre-defined by a set of at least 4 points. This Path will interpolate the points into a curve and follow that curve.

Parameters:	points – The list of points that defines the path. steps – The number of steps to take to follow the path.

move_straight_to(x, y, steps)¶

Move straight to the newly specified location - i.e. create a straight line Path from the current location to the specified point.

Parameters:	x – X coord for the end position. y – Y coord for the end position. steps – How many steps to take for the move.

next_pos()¶

Returns:	The next position tuple (x, y) for the Sprite on this path.

reset()¶: Reset the Path for use next time.

wait(delay)¶

Wait at the current location for the specified number of iterations.

Parameters:	delay – The time to wait (in animation frames).

asciimatics.renderers module¶

This module provides Renderers to create complex animation effects. For more details see http://asciimatics.readthedocs.io/en/latest/rendering.html

asciimatics.renderers.ATTRIBUTES = {'1': 1, '2': 2, '3': 3, '4': 4}¶: Attribute conversion table for the ${c,a} form of attributes for paint.

class asciimatics.renderers.BarChart(height, width, functions, char='#', colour=2, bg=0, gradient=None, scale=None, axes=2, intervals=None, labels=False, border=True, keys=None)¶

Bases: asciimatics.renderers.DynamicRenderer

Renderer to create a bar chart using the specified functions as inputs for each entry. Can be used to chart distributions or for more graphical effect - e.g. to imitate a sound equalizer or a progress indicator.

Parameters:

height – The max height of the rendered image.
width – The max width of the rendered image.
functions – List of functions to chart.
char – Character to use for the bar.
colour – Default colour to use for the bars. This can be a single value or list of values (to cycle around for each bar).
bg – Default background colour to use for the bars. This can be a single value or list of values (to cycle around for each bar).
gradient – Colour gradient for use on all bars. This is a list of tuple pairs specifying a threshold and a colour, or triplets to include a background colour too.
scale – Maximum value for the bars. This is used to scale the function values to the maximum space available. Any value over this will be truncated when drawn. Defaults to the number of available characters in the chart.
axes – Which axes to draw.
intervals – Units for interval markers on the main axis. Defaults to none.
labels – Whether to label the main axis.
border – Whether to draw a border around the chart.
keys – Optional keys for each bar.

BOTH = 3¶: Constant to indicate both axes should be rendered.

NONE = 0¶: Constant to indicate no axes should be rendered.

X_AXIS = 1¶: Constant to indicate just the x axis should be rendered.

Y_AXIS = 2¶: Constant to indicate just the y axis should be rendered.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Box(width, height, uni=False)¶

Bases: asciimatics.renderers.StaticRenderer

Renders a simple box using ASCII characters. This does not render in extended box drawing characters as that requires non-ASCII characters in Windows and direct access to curses in Linux.

Parameters:	width – The desired width of the box. height – The desired height of the box. uni – Whether to use unicode box characters or not.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.ColourImageFile(screen, filename, height=30, bg=0, fill_background=False, uni=False, dither=False)¶

Bases: asciimatics.renderers.StaticRenderer

Renderer to convert an image file (as supported by the Python Imaging Library) into an block image of available colours.

Warning

This is only compatible with 256-colour terminals. Results in other terminals with reduced colour capabilities are severely restricted. Since Windows only has 8 base colours, it is recommended that you avoid this renderer on that platform.

Parameters:

screen – The screen to use when displaying the image.
filename – The name of the file to render.
height – The height of the text rendered image.
bg – The default background colour for this image.
fill_background – Whether to set background colours too.
uni – Whether to use unicode box characters or not.
dither – Whether to dither the rendered image or not.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.DynamicRenderer(height, width)¶

Bases: asciimatics.renderers.Renderer

A DynamicRenderer is a Renderer that creates each image as requested. It has a defined maximum size on construction.

Parameters:	height – The max height of the rendered image. width – The max width of the rendered image.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.FigletText(text, font='standard', width=200)¶

Bases: asciimatics.renderers.StaticRenderer

This class renders the supplied text using the specified Figlet font. See http://www.figlet.org/ for details of available fonts.

Parameters:	text – The text string to convert with Figlet. font – The Figlet font to use (optional). width – The maximum width for this text in characters.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Fire(height, width, emitter, intensity, spot, colours, bg=False)¶

Bases: asciimatics.renderers.DynamicRenderer

Renderer to create a fire effect based on a specified emitter that defines the heat source.

The implementation here uses the same techniques described in http://freespace.virgin.net/hugo.elias/models/m_fire.htm, although a slightly different implementation.

Parameters:

height – Height of the box to contain the flames.
width – Width of the box to contain the flames.
emitter – Heat source for the flames. Any non-whitespace character is treated as part of the heat source.
intensity – The strength of the flames. The bigger the number, the hotter the fire. 0 <= intensity <= 1.0.
spot – Heat of each spot source. Must be an integer > 0.
colours – Number of colours the screen supports.
bg – (Optional) Whether to render background colours only.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.ImageFile(filename, height=30, colours=8)¶

Bases: asciimatics.renderers.StaticRenderer

Renderer to convert an image file (as supported by the Python Imaging Library) into an ascii grey scale text image.

Parameters:	filename – The name of the file to render. height – The height of the text rendered image. colours – The number of colours the terminal supports.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Kaleidoscope(height, width, cell, symmetry)¶

Bases: asciimatics.renderers.DynamicRenderer

Renderer to create a 2-mirror kaleidoscope effect.

This is a chained renderer (i.e. it acts upon the output of another Renderer which is passed to it on construction). The other Renderer is used as the cell that is rotated over time to create the animation.

You can specify the desired rotational symmetry of the kaleidoscope (which determines the angle between the mirrors). If you chose values of less than 2, you are effectively removing one or both mirrors, thus either getting the original cell or a simple mirrored image of the cell.

Since this renderer rotates the background cell, it needs operate on square pixels, which means each character in the cell is drawn as 2 next to each other on the screen. In other words the cell needs to be half the width of the desired output (when measured in text characters).

Parameters:	height – Height of the box to contain the kaleidoscope. width – Width of the box to contain the kaleidoscope. cell – A Renderer to use as the backing cell for the kaleidoscope. symmetry – The desired rotational symmetry. Must be a non-negative integer.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Plasma(height, width, colours)¶

Bases: asciimatics.renderers.DynamicRenderer

Renderer to create a “plasma” effect using sinusoidal functions.

The implementation here uses the same techniques described in http://lodev.org/cgtutor/plasma.html

Parameters:	height – Height of the box to contain the plasma. width – Width of the box to contain the plasma. colours – Number of colours the screen supports.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Rainbow(screen, renderer)¶

Bases: asciimatics.renderers.StaticRenderer

Chained renderer to add rainbow colours to output of another renderer. The embedded rendered must not use multi-colour mode (i.e. ${c,a} mark-ups) as these will be converted to explicit text by this renderer.

Parameters:	screen – The screen object for this renderer. renderer – The renderer to wrap.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.Renderer¶

Bases: object

A Renderer is simply a class that will return one or more text renderings for display by an Effect.

In the simple case, this can be a single string that contains some unchanging content - e.g. a simple text message.

It can also represent a sequence of strings that can be played one after the other to make a simple animation sequence - e.g. a rotating globe.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.RotatedDuplicate(width, height, renderer)¶

Bases: asciimatics.renderers.StaticRenderer

Chained renderer to add a rotated version of the original renderer underneath and centre the whole thing within within the specified dimensions.

Parameters:	width – The maximum width of the rendered text. height – The maximum height of the rendered text. renderer – The renderer to wrap.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.SpeechBubble(text, tail=None, uni=False)¶

Bases: asciimatics.renderers.StaticRenderer

Renders supplied text into a speech bubble.

Parameters:	text – The text to be put into a speech bubble. tail – Where to put the bubble callout tail, specifying “L” or “R” for left or right tails. Can be None for no tail.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

class asciimatics.renderers.StaticRenderer(images=None, animation=None)¶

Bases: asciimatics.renderers.Renderer

A StaticRenderer is a Renderer that can create all possible images in advance. After construction the images will not change, but can by cycled for animation purposes.

This class will also convert text like ${c,a,b} into colour c, attribute a and background b for any subsequent text in the line, thus allowing multi-coloured text. The attribute and background are optional.

Parameters:	images – An optional set of ascii images to be rendered. animation – A function to pick the image (from images) to be rendered for any given frame.

images¶

Returns:	An iterator of all the images in the Renderer.

max_height¶

Returns:	The max height of the rendered text (across all images if an animated renderer).

max_width¶

Returns:	The max width of the rendered text (across all images if an animated renderer).

rendered_text¶

Returns:	The next image and colour map in the sequence as a tuple.

asciimatics.renderers.random() → x in the interval [0, 1).¶

asciimatics.scene module¶

This module defines Scene objects for animation purposes. For more details, see http://asciimatics.readthedocs.io/en/latest/animation.html

class asciimatics.scene.Scene(effects, duration=0, clear=True, name=None)¶

Bases: object

Class to store the details of a single scene to be displayed. This is made up of a set of Effect objects. See the documentation for Effect to understand the interaction between the two classes and http://asciimatics.readthedocs.io/en/latest/animation.html for how to use them together.

Parameters:	effects – The list of effects to apply to this scene. duration – The number of frames in this Scene. A value of 0 means that the Scene should query the Effects to find the duration. A value of -1 means don’t stop. clear – Whether to clear the Screen at the start of the Scene. name – Optional name to identify the scene.

add_effect(effect, reset=True)¶

Add an effect to the Scene.

This method can be called at any time - even when playing the Scene. The default logic assumes that the Effect needs to be reset before being displayed. This can be overridden using the reset parameter.

Parameters:	effect – The Effect to be added. reset – Whether to reset the Effect that has just been added.

clear¶

Returns:	Whether the Scene should clear at the start.

duration¶

Returns:	The length of the scene in frames.

effects¶

Returns:	The list of Effects in this Scene.

exit()¶: Handle any tidy up required on the exit of the Scene.

name¶

Returns:	The name of this Scene. May be None.

process_event(event)¶

Process a new input event.

This method will pass the event on to any Effects in reverse Z order so that the top-most Effect has priority.

Parameters:	event – The Event that has been triggered.
Returns:	None if the Scene processed the event, else the original event.

remove_effect(effect)¶

Remove an effect from the scene.

Parameters:	effect – The effect to remove.

reset(old_scene=None, screen=None)¶

Reset the scene ready for playing.

Parameters:	old_scene – The previous version of this Scene that was running before the application reset - e.g. due to a screen resize. screen – New screen to use if old_scene is not None.

asciimatics.screen module¶

This module defines common screen output function. For more details, see http://asciimatics.readthedocs.io/en/latest/io.html

class asciimatics.screen.Canvas(screen, height, width, x=None, y=None)¶

Bases: asciimatics.screen._AbstractCanvas

A Canvas is an object that can be used to draw to the screen. It maintains its own buffer that will be flushed to the screen when refresh() is called.

Parameters:	screen – The underlying Screen that will be drawn to on refresh. height – The height of the screen buffer to be used. width – The width of the screen buffer to be used. x – The x position for the top left corner of the Canvas. y – The y position for the top left corner of the Canvas.

If either of the x or y positions is not set, the Canvas will default to centring within the current Screen for that location.

block_transfer(buffer, x, y)¶

Copy a buffer to the screen double buffer at a specified location.

Parameters:	buffer – The double buffer to copy x – The X origin for where to place it in the Screen y – The Y origin for where to place it in the Screen

centre(text, y, colour=7, attr=0, colour_map=None)¶

Centre the text on the specified line (y) using the optional colour and attributes.

Parameters:	text – The (single line) text to be printed. y – The line (y coord) for the start of the text. colour – The colour of the text to be displayed. attr – The cell attribute of the text to be displayed. colour_map – Colour/attribute list for multi-colour text.

The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.

clear_buffer(fg, attr, bg, x=0, y=0, w=None, h=None)¶

Clear a box in the current double-buffer used by this object.

This is the recommended way to clear parts, or all, ofthe Screen without causing flicker as it will only become visible at the next refresh. Defaults to the whole buffer if no box is specified.

Parameters:	fg – The foreground colour to use for the new buffer. attr – The attribute value to use for the new buffer. bg – The background colour to use for the new buffer. x – Optional X coordinate for top left of box. y – Optional Y coordinate for top left of box. w – Optional width of the box. h – Optional height of the box.

dimensions¶

Returns:	The full dimensions of the canvas as a (height, width) tuple.

draw(x, y, char=None, colour=7, bg=0, thin=False)¶

Draw a line from drawing cursor to the specified position.

This uses a modified Bressenham algorithm, interpolating twice as many points to render down to anti-aliased characters when no character is specified, or uses standard algorithm plotting with the specified character.

Parameters:	x – The column (x coord) for the location to check. y – The line (y coord) for the location to check. char – Optional character to use to draw the line. colour – Optional colour for plotting the line. bg – Optional background colour for plotting the line. thin – Optional width of anti-aliased line.

fill_polygon(polygons, colour=7, bg=0)¶

Draw a filled polygon.

This function uses the scan line algorithm to create the polygon. See https://www.cs.uic.edu/~jbell/CourseNotes/ComputerGraphics/PolygonFilling.html for details.

Parameters:	polygons – A list of polygons (which are each a list of (x,y) coordinates for the points of the polygon) - i.e. nested list of 2-tuples. colour – The foreground colour to use for the polygon bg – The background colour to use for the polygon

get_from(x, y)¶

Get the character at the specified location.

Parameters:	x – The column (x coord) of the character. y – The row (y coord) of the character.
Returns:	A 4-tuple of (ascii code, foreground, attributes, background) for the character at the location.

highlight(x, y, w, h, fg=None, bg=None, blend=100)¶

Highlight a specified section of the screen.

Parameters:	x – The column (x coord) for the start of the highlight. y – The line (y coord) for the start of the highlight. w – The width of the highlight (in characters). h – The height of the highlight (in characters). fg – The foreground colour of the highlight. bg – The background colour of the highlight. blend – How much (as a percentage) to take of the new colour when blending.

The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. If fg or bg are None that means don’t change the foreground/background as appropriate.

is_visible(x, y)¶

Return whether the specified location is on the visible screen.

Parameters:	x – The column (x coord) for the location to check. y – The line (y coord) for the location to check.

move(x, y)¶

Move the drawing cursor to the specified position.

Parameters:	x – The column (x coord) for the location to check. y – The line (y coord) for the location to check.

origin¶

The location of top left corner of the canvas on the Screen.

Returns:	A tuple (x, y) of the location

paint(text, x, y, colour=7, attr=0, bg=0, transparent=False, colour_map=None)¶

Paint multi-colour text at the defined location.

Parameters:

text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The default colour of the text to be displayed.
attr – The default cell attribute of the text to be displayed.
bg – The default background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
colour_map – Colour/attribute list for multi-colour text.

The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. colour_map is a list of tuples (foreground, attribute, background) that must be the same length as the passed in text (or None if no mapping is required).

palette¶

Returns:	A palette compatible with the PIL.

print_at(text, x, y, colour=7, attr=0, bg=0, transparent=False)¶

Print the text at the specified location using the specified colour and attributes.

Parameters:

text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
bg – The background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.

The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.

refresh()¶: Flush the canvas content to the underlying screen.

reset()¶: Reset the internal buffers for the abstract canvas.

scroll(lines=1)¶

Scroll the abstract canvas up one line.

Parameters:	lines – The number of lines to scroll. Defaults to down by one.

scroll_to(line)¶

Scroll the abstract canvas to make a specific line.

Parameters:	line – The line to scroll to.

start_line¶

Returns:	The start line of the top of the canvas.

unicode_aware¶

Returns:	Whether unicode input/output is supported or not.

class asciimatics.screen.ManagedScreen(func=<function ManagedScreen.<lambda>>)¶

Bases: object

Decorator and class to create a managed Screen. It can be used in two ways. If used as a method decorator it will create and open a new Screen, pass the screen to the method as a keyword argument, and close the screen when the method has completed. If used with the with statement the class will create and open a new Screen, return the screen for using in the block, and close the screen when the statement ends. Note that any arguments are in this class so that you can use it as a decorator or using the with statment. No arguments are required to use.

Parameters:	func – The function to call once the Screen has been created.

class asciimatics.screen.Screen(height, width, buffer_height, unicode_aware)¶

Bases: asciimatics.screen._AbstractCanvas

Class to track basic state of the screen. This constructs the necessary resources to allow us to do the ASCII animations.

This is an abstract class that will build the correct concrete class for you when you call wrapper(). If needed, you can use the open() and close() methods for finer grained control of the construction and tidy up.

Note that you need to define the required height for your screen buffer. This is important if you plan on using any Effects that will scroll the screen vertically (e.g. Scroll). It must be big enough to handle the full scrolling of your selected Effect.

Don’t call this constructor directly.

block_transfer(buffer, x, y)¶

Copy a buffer to the screen double buffer at a specified location.

Parameters:	buffer – The double buffer to copy x – The X origin for where to place it in the Screen y – The Y origin for where to place it in the Screen

centre(text, y, colour=7, attr=0, colour_map=None)¶

Centre the text on the specified line (y) using the optional colour and attributes.

Parameters:	text – The (single line) text to be printed. y – The line (y coord) for the start of the text. colour – The colour of the text to be displayed. attr – The cell attribute of the text to be displayed. colour_map – Colour/attribute list for multi-colour text.

The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.

clear()¶

Clear the Screen of all content.

Note that this will instantly clear the Screen and reset all buffers to the default state, without waiting for you to call refresh(). It is designed for use once at the start of your application to reset all buffers and the screen to a known state.

If you want to clear parts, or all, of the Screen inside your application without any flicker, use clear_buffer() instead.

clear_buffer(fg, attr, bg, x=0, y=0, w=None, h=None)¶

Clear a box in the current double-buffer used by this object.

This is the recommended way to clear parts, or all, ofthe Screen without causing flicker as it will only become visible at the next refresh. Defaults to the whole buffer if no box is specified.

Parameters:	fg – The foreground colour to use for the new buffer. attr – The attribute value to use for the new buffer. bg – The background colour to use for the new buffer. x – Optional X coordinate for top left of box. y – Optional Y coordinate for top left of box. w – Optional width of the box. h – Optional height of the box.

close(restore=True)¶

Close down this Screen and tidy up the environment as required.

Parameters:	restore – whether to restore the environment or not.

static ctrl(char)¶

Calculate the control code for a given key. For example, this converts “a” to 1 (which is the code for ctrl-a).

Parameters:	char – The key to convert to a control code.
Returns:	The control code as an integer or None if unknown.

current_scene¶

Returns:	The scene currently being rendered. To be used in conjunction with `draw_next_frame()`.

dimensions¶

Returns:	The full dimensions of the canvas as a (height, width) tuple.

draw(x, y, char=None, colour=7, bg=0, thin=False)¶

Draw a line from drawing cursor to the specified position.

This uses a modified Bressenham algorithm, interpolating twice as many points to render down to anti-aliased characters when no character is specified, or uses standard algorithm plotting with the specified character.

Parameters:	x – The column (x coord) for the location to check. y – The line (y coord) for the location to check. char – Optional character to use to draw the line. colour – Optional colour for plotting the line. bg – Optional background colour for plotting the line. thin – Optional width of anti-aliased line.

draw_next_frame(repeat=True)¶

Draw the next frame in the currently configured Scenes. You must call set_scenes() before using this for the first time.

Parameters:	repeat – Whether to repeat the Scenes once it has reached the end. Defaults to True.
Raises:	StopApplication – if the application should be terminated.

fill_polygon(polygons, colour=7, bg=0)¶

Draw a filled polygon.

This function uses the scan line algorithm to create the polygon. See https://www.cs.uic.edu/~jbell/CourseNotes/ComputerGraphics/PolygonFilling.html for details.

Parameters:	polygons – A list of polygons (which are each a list of (x,y) coordinates for the points of the polygon) - i.e. nested list of 2-tuples. colour – The foreground colour to use for the polygon bg – The background colour to use for the polygon

force_update(full_refresh=False)¶

Force the Screen to redraw the current Scene on the next call to draw_next_frame, overriding the frame_update_count value for all the Effects.

Parameters:	full_refresh – if True force the whole screen to redraw.

get_event()¶

Check for any events (e.g. key-press or mouse movement) without waiting.

Returns:	A `Event` object if anything was detected, otherwise it returns None.

get_from(x, y)¶

Get the character at the specified location.

Parameters:	x – The column (x coord) of the character. y – The row (y coord) of the character.
Returns:	A 4-tuple of (ascii code, foreground, attributes, background) for the character at the location.

get_key()¶: Check for a key without waiting. This method is deprecated. Use get_event() instead.

getch(x, y)¶

Get the character at a specified location. This method is deprecated. Use get_from() instead.

Parameters:	x – The x coordinate. y – The y coordinate.

has_resized()¶

Check whether the screen has been re-sized.

Returns:	True when the screen has been re-sized since the last check.

highlight(x, y, w, h, fg=None, bg=None, blend=100)¶

Highlight a specified section of the screen.

Parameters:	x – The column (x coord) for the start of the highlight. y – The line (y coord) for the start of the highlight. w – The width of the highlight (in characters). h – The height of the highlight (in characters). fg – The foreground colour of the highlight. bg – The background colour of the highlight. blend – How much (as a percentage) to take of the new colour when blending.

The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. If fg or bg are None that means don’t change the foreground/background as appropriate.

is_visible(x, y)¶

Return whether the specified location is on the visible screen.

Parameters:	x – The column (x coord) for the location to check. y – The line (y coord) for the location to check.

move(x, y)¶

Move the drawing cursor to the specified position.

Parameters:	x – The column (x coord) for the location to check. y – The line (y coord) for the location to check.

classmethod open(height=None, catch_interrupt=False, unicode_aware=None)¶

Construct a new Screen for any platform. This will just create the correct Screen object for your environment. See wrapper() for a function to create and tidy up once you’ve finished with the Screen.

Parameters:	height – The buffer height for this window (for testing only). catch_interrupt – Whether to catch and prevent keyboard interrupts. Defaults to False to maintain backwards compatibility. unicode_aware – Whether the application can use unicode or not. If None, try to detect from the environment if UTF-8 is enabled.

paint(text, x, y, colour=7, attr=0, bg=0, transparent=False, colour_map=None)¶

Paint multi-colour text at the defined location.

Parameters:

text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The default colour of the text to be displayed.
attr – The default cell attribute of the text to be displayed.
bg – The default background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
colour_map – Colour/attribute list for multi-colour text.

The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. colour_map is a list of tuples (foreground, attribute, background) that must be the same length as the passed in text (or None if no mapping is required).

palette¶

Returns:	A palette compatible with the PIL.

play(scenes, stop_on_resize=False, unhandled_input=None, start_scene=None, repeat=True, allow_int=False)¶

Play a set of scenes.

This is effectively a helper function to wrap set_scenes() and draw_next_frame() to simplify animation for most applications.

Parameters:

scenes – a list of Scene objects to play.
stop_on_resize – Whether to stop when the screen is resized. Default is to carry on regardless - which will typically result in an error. This is largely done for back-compatibility.
unhandled_input – Function to call for any input not handled by the Scenes/Effects being played. Defaults to a function that closes the application on “Q” or “X” being pressed.
start_scene – The old Scene to start from. This must have name that matches the name of one of the Scenes passed in.
repeat – Whether to repeat the Scenes once it has reached the end. Defaults to True.
allow_int – Allow input to interrupt frame rate delay.

Raises:

ResizeScreenError – if the screen is resized (and allowed by stop_on_resize).

The unhandled input function just takes one parameter - the input event that was not handled.

print_at(text, x, y, colour=7, attr=0, bg=0, transparent=False)¶

Print the text at the specified location using the specified colour and attributes.

Parameters:

text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
bg – The background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.

The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.

putch(text, x, y, colour=7, attr=0, bg=0, transparent=False)¶

Print text at the specified location. This method is deprecated. Use print_at() instead.

Parameters:

text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
bg – The background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.

refresh()¶: Refresh the screen.

reset()¶: Reset the internal buffers for the abstract canvas.

scroll(lines=1)¶

Scroll the abstract canvas up one line.

Parameters:	lines – The number of lines to scroll. Defaults to down by one.

scroll_to(line)¶

Scroll the abstract canvas to make a specific line.

Parameters:	line – The line to scroll to.

set_scenes(scenes, unhandled_input=None, start_scene=None)¶

Remember a set of scenes to be played. This must be called before using draw_next_frame().

Parameters:	scenes – a list of `Scene` objects to play. unhandled_input – Function to call for any input not handled by the Scenes/Effects being played. Defaults to a function that closes the application on “Q” or “X” being pressed. start_scene – The old Scene to start from. This must have name that matches the name of one of the Scenes passed in.
Raises:	ResizeScreenError – if the screen is resized (and allowed by stop_on_resize).

The unhandled input function just takes one parameter - the input event that was not handled.

set_title(title)¶

Set the title for this terminal/console session. This will typically change the text displayed in the window title bar.

Parameters:	title – The title to be set.

start_line¶

Returns:	The start line of the top of the canvas.

unicode_aware¶

Returns:	Whether unicode input/output is supported or not.

wait_for_input(timeout)¶

Wait until there is some input or the timeout is hit.

Parameters:	timeout – Time to wait for input in seconds (floating point).

classmethod wrapper(func, height=None, catch_interrupt=False, arguments=None, unicode_aware=None)¶

Construct a new Screen for any platform. This will initialize the Screen, call the specified function and then tidy up the system as required when the function exits.

Parameters:

func – The function to call once the Screen has been created.
height – The buffer height for this Screen (only for test purposes).
catch_interrupt – Whether to catch and prevent keyboard interrupts. Defaults to False to maintain backwards compatibility.
arguments – Optional arguments list to pass to func (after the Screen object).
unicode_aware – Whether the application can use unicode or not. If None, try to detect from the environment if UTF-8 is enabled.

asciimatics.sprites module¶

This module provides Sprites to create animation effects with Paths. For more details see http://asciimatics.readthedocs.io/en/latest/animation.html

class asciimatics.sprites.Arrow(screen, path, colour=7, start_frame=0, stop_frame=0)¶

Bases: asciimatics.effects.Sprite

Sample arrow sprite - points where it is going.

See Sprite for details.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

last_position()¶: Returns the last position of this Sprite as a tuple (x, y, width, height).

overlaps(other, use_new_pos=False)¶

Check whether this Sprite overlaps another.

Parameters:	other – The other Sprite to check for an overlap. use_new_pos – Whether to use latest position (due to recent update). Defaults to False.
Returns:	True if the two Sprites overlap.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.sprites.Plot(screen, path, colour=7, start_frame=0, stop_frame=0)¶

Bases: asciimatics.effects.Sprite

Sample Sprite that simply plots an “X” for each step in the path. Useful for plotting a path to the screen.

See Sprite for details.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

last_position()¶: Returns the last position of this Sprite as a tuple (x, y, width, height).

overlaps(other, use_new_pos=False)¶

Check whether this Sprite overlaps another.

Parameters:	other – The other Sprite to check for an overlap. use_new_pos – Whether to use latest position (due to recent update). Defaults to False.
Returns:	True if the two Sprites overlap.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

class asciimatics.sprites.Sam(screen, path, start_frame=0, stop_frame=0)¶

Bases: asciimatics.effects.Sprite

Sam Paul sprite - an simple sample animated character.

See Sprite for details.

delete_count¶: The number of frames before this Effect should be deleted.

frame_update_count¶

The number of frames before this Effect should be updated.

Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!

A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.

last_position()¶: Returns the last position of this Sprite as a tuple (x, y, width, height).

overlaps(other, use_new_pos=False)¶

Check whether this Sprite overlaps another.

Parameters:	other – The other Sprite to check for an overlap. use_new_pos – Whether to use latest position (due to recent update). Defaults to False.
Returns:	True if the two Sprites overlap.

process_event(event)¶

Process any input event.

Parameters:	event – The event that was triggered.
Returns:	None if the Effect processed the event, else the original event.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

reset()¶: Function to reset the effect when replaying the scene.

safe_to_default_unhandled_input¶

Whether it is safe to use the default handler for any unhandled input from this Effect.

A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

stop_frame¶: Last frame for this effect. A value of zero means no specific end.

update(frame_no)¶

Process the animation effect for the specified frame number.

Parameters:	frame_no – The index of the frame being generated.

asciimatics.strings module¶

This module provides classes to handle embedded control strings for widgets.

class asciimatics.strings.ColouredText(raw_text, parser, colour=None, colour_map=None, offsets=None, text=None)¶

Bases: object

Unicode string-like object to store text and colour maps, using a parser to convert the raw text passed in into visible text and an associated colour map. This only handles simple colour change commands and will ignore more complex commands).

Parameters:	raw_text – The raw unicode string to be processed parser – The parser to process the text colour – Optional starting colour tuple to use for this text. colour_map – Optional ready parsed colour map for this text. offsets – Optional ready parsed offsets for this text. text – Optional ready parsed text for this text.

The colour_map, offsets and text options are to optimize creation of substrings from an existing ColouredText object and should not be used in general.

colour_map¶: Colour map for the processed text (for use with paint method).

first_colour¶: First colour triplet used for this text.

join(others)¶

Join the list of ColouredObjects using this ColouredObject.

Parameters:	others – the list of other objects to join.

last_colour¶: Last colour triplet used for this text.

raw_text¶: Raw (unprocessed) text for this object.

startswith(text)¶: Check whether parsed (i.e. displayed) text starts woth specified string.

asciimatics.utilities module¶

This module is just a collection of simple helper functions.

asciimatics.utilities.readable_mem(mem)¶

Parameters:	mem – An integer number of bytes to convert to human-readable form.
Returns:	A human-readable string representation of the number.

asciimatics.utilities.readable_timestamp(stamp)¶

Parameters:	stamp – A floating point number representing the POSIX file timestamp.
Returns:	A short human-readable string representation of the timestamp.

asciimatics.version module¶

Module contents¶

Asciimatics is a package to help people create full-screen text UIs (from interactive forms to ASCII animations) on any platform. It is licensed under the Apache Software Foundation License 2.0.

asciimatics package¶

Subpackages¶

Submodules¶

asciimatics.constants module¶

asciimatics.effects module¶

asciimatics.event module¶

asciimatics.exceptions module¶

asciimatics.parsers module¶

asciimatics.particles module¶

asciimatics.paths module¶

asciimatics.renderers module¶

asciimatics.scene module¶

asciimatics.screen module¶

asciimatics.sprites module¶

asciimatics.strings module¶

asciimatics.utilities module¶

asciimatics.version module¶

Module contents¶

Table of Contents

Previous topic

This Page