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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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:

  1. The Scene will register with the Effect when it as added using register_scene().

  2. The Scene will call Effect.reset() for all Effects when it starts.

  3. The Scene will determine the number of frames required (either through explicit configuration or querying stop_frame for every Effect).

  4. 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.

  5. 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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

abstract reset()

Function to reset the effect when replaying the scene.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

abstract property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: Effect

Matrix-like falling green letters.

Parameters:

screen – The Screen being used for the Scene.

Also see the common keyword arguments in Effect.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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 updates.

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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: Effect

Settling snow effect.

Parameters:

screen – The Screen being used for the Scene.

Also see the common keyword arguments in Effect.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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, speed=2, **kwargs)

Bases: 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.

  • speed – The refresh rate in frames between updates.

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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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: 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.

add_note()

Exception.add_note(note) – add a note to the exception

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 data is found.

Parameters:

fields – The list of the fields that are invalid.

add_note()

Exception.add_note(note) – add a note to the exception

property 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.

add_note()

Exception.add_note(note) – add a note to the exception

property 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.

add_note()

Exception.add_note(note) – add a note to the exception

property 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.

add_note()

Exception.add_note(note) – add a note to the 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: Parser

Parser to handle ANSI terminal escape codes.

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

RESTORE_CURSOR = 10

Restore the cursor position. No parameters.

SAVE_CURSOR = 9

Save the cursor position. No parameters.

SHOW_CURSOR = 7

Set cursor visibility. Param is boolean setting True=visible

append(text)

Append more text to the current text being processed.

Parameters:

text – raw text to process.

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: Parser

Parser to handle Asciimatics rendering escape strings.

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

RESTORE_CURSOR = 10

Restore the cursor position. No parameters.

SAVE_CURSOR = 9

Save the cursor position. No parameters.

SHOW_CURSOR = 7

Set cursor visibility. Param is boolean setting True=visible

append(text)

Append more text to the current text being processed.

Parameters:

text – raw text to process.

parse()

Generator to return coloured text from raw text.

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: Parser

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

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

RESTORE_CURSOR = 10

Restore the cursor position. No parameters.

SAVE_CURSOR = 9

Save the cursor position. No parameters.

SHOW_CURSOR = 7

Set cursor visibility. Param is boolean setting True=visible

append(text)

Append more text to the current text being processed.

Parameters:

text – raw text to process.

parse()

Generator to return coloured text from raw text.

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

RESTORE_CURSOR = 10

Restore the cursor position. No parameters.

SAVE_CURSOR = 9

Save the cursor position. No parameters.

SHOW_CURSOR = 7

Set cursor visibility. Param is boolean setting True=visible

append(text)

Append more text to the current text being processed.

Parameters:

text – raw text to process.

abstract 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: 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: ParticleEffect

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

See ParticleEffect for details of the parameters.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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: 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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

abstract reset()

Reset the particle effect back to its initial state. This must be implemented by the child classes.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: ParticleEffect

Rain storm effect.

See ParticleEffect for details of the parameters.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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: 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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: 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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, diameter=None, **kwargs)

Bases: ParticleEffect

Shoot the screen out like a massive gunshot.

See ParticleEffect for details of the parameters.

In addition, it is possible to set the diameter of this effect using the extra keyword parameter.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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, diameter, life_time)

Bases: 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.

  • diameter – The diameter 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: 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: 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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: _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.

abstract 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: _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.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.

property clear
Returns:

Whether the Scene should clear at the start.

property duration
Returns:

The length of the scene in frames.

property effects
Returns:

The list of Effects in this Scene.

exit()

Handle any tidy up required on the exit of the Scene.

property 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: _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.

property 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.

property 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).

property 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.

property start_line
Returns:

The start line of the top of the canvas.

property 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: _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.

abstract 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.

property current_scene
Returns:

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

property 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.

abstract 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.

abstract 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).

property 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.

abstract 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.

property start_line
Returns:

The start line of the top of the canvas.

property unicode_aware
Returns:

Whether unicode input/output is supported or not.

abstract 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.

class asciimatics.screen.TemporaryCanvas(height, width)

Bases: _AbstractCanvas

A TemporaryCanvas is an object that can only be used to draw to a buffer.

This class is desigend purely for use by dynamic renderers and so ignores some features of a full Canvas - most notably the screen related fhnction (e.g. the screen buffer and related properties).

Parameters:
  • height – The height of the screen buffer to be used.

  • width – The width of the screen buffer to be used.

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.

property 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.

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).

property 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()

Refresh this object - this will draw to the underlying display interface.

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.

property start_line
Returns:

The start line of the top of the canvas.

property unicode_aware
Returns:

Whether unicode input/output is supported or not.

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: Sprite

Sample arrow sprite - points where it is going.

See Sprite for details.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: 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.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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: Sprite

Sam Paul sprite - an simple sample animated character.

See Sprite for details.

property delete_count

The number of frames before this Effect should be deleted.

property 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.

property 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.

property scene

The Scene that owns this Effect.

property screen

The Screen that will render this Effect.

property 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.

property colour_map

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

property 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.

property last_colour

Last colour triplet used for this text.

property 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.

class asciimatics.utilities.BoxTool(unicode_aware, style=1)

Bases: object

Tool for building boxes out of characters.

Supports a variety of line styles from asciimatics.constants:

  • ASCII_LINE – ASCII safe characters (0)

  • SINGLE_LINE – Unicode based single lined box (1)

  • DOUBLE_LINE – Unicode based double lined box (2)

Individual characters of a box can be accessed directly through attributes. Most attribute names are based on the Extended-ASCII characters used for the UNICODE version of the shape. The names describe the directions the piece point in (not the part of the box). For example, “up_left” is a corner piece that has a part that points up and a part that points left – the character usually used for the bottom right hand corner of a box.

Attribute values are:

  • up_left – corner piece facing up and left

  • up_right – corner piece facing up and right

  • down_left – corner piece facing down and left

  • down_right – corner piece facing down and right

  • h – horizontal line

  • v – vertical line

  • v_inside – vertical line used inside the grid

  • v_left – vertical line with mid joiner facing to the left

  • v_right – vertical line with mid joiner facing to the right

  • h_up – horizontal line with a mid joiner facing up

  • h_down – horizontal line with a mid joiner facing down

  • cross – intersection between vertical and horizontal

Parameters:
  • unicode_aware – boolean indicating if the terminal is Unicode aware. If False, will force the use of the ASCII style

  • style – line style specifier. Supports ASCII_LINE, SINGLE_LINE, and DOUBLE_LINE. Defaults to SINGLE_LINE.

box(width, height)

Returns a string containing a box with the given width and height.

box_bottom(width)

Returns a string containing the bottom border of a box

Parameters:

width – width of box, including corners

box_line(width)

Returns a string with a vertical bar on each end, padded with spaces in between for the given width.

Parameters:

width – width of box including sides

box_top(width)

Returns a string containing the top border of a box

Parameters:

width – width of box, including corners

property style

The line drawing style used to draw boxes. Possible styles are set in asciimatics.constants.

Parameters:

style – One of ASCII_LINE, SINGLE_LINE, or DOUBLE_LINE

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.