asciimatics package¶

Submodules¶

asciimatics.constants module¶

This module is just a collection of simple helper functions.

asciimatics.effects module¶

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

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

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

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

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

A rotating cog.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

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: future.types.newobject.newobject

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

The basic interaction with a Scene is as follows:

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

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

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

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

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

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

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

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

Matrix-like falling green letters.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

Parameters:

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

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

Also see the common keyword arguments in Effect.

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

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

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

Settling snow effect.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

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

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

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

overlaps(other, use_new_pos=False)¶

Check whether this Sprite overlaps another.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

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=u'..+.. ...x... ...*... ', **kwargs)¶

Bases: asciimatics.effects.Effect

Add random stars to the screen and make them twinkle.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Effect

Wipe the screen down from top to bottom.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

asciimatics.event module¶

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

class asciimatics.event.Event¶

Bases: object

A class to hold information about an input event.

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

class asciimatics.event.KeyboardEvent(key_code)¶

Bases: asciimatics.event.Event

An event that represents a key press.

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

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

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

Bases: asciimatics.event.Event

An event that represents a mouse move or click.

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

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

asciimatics.exceptions module¶

This module defines the exceptions used by asciimatics.

exception asciimatics.exceptions.Highlander¶

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

exception asciimatics.exceptions.InvalidFields(fields)¶

Bases: exceptions.Exception

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

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

fields¶: The list of fields that are invalid.

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

Bases: exceptions.Exception

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

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

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

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

Bases: exceptions.Exception

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

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

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

exception asciimatics.exceptions.StopApplication(message)¶

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

asciimatics.parsers module¶

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

class asciimatics.parsers.AnsiTerminalParser¶

Bases: asciimatics.parsers.Parser

Parser to handle ANSI terminal escape codes.

Initialize the parser.

parse()¶

Generator to return coloured text from raw text.

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

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

reset(text, colours)¶

Reset the parser to analyze the supplied raw text.

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

class asciimatics.parsers.AsciimaticsParser¶

Bases: asciimatics.parsers.Parser

Parser to handle Asciimatics rendering escape strings.

Initialize the parser.

parse()¶

Generator to return coloured text from raw text.

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

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

reset(text, colours)¶

Reset the parser to analyze the supplied raw text.

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

class asciimatics.parsers.ControlCodeParser¶

Bases: asciimatics.parsers.Parser

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

Initialize the parser.

parse()¶

Generator to return coloured text from raw text.

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

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

reset(text, colours=None)¶

Reset the parser to analyze the supplied raw text.

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

class asciimatics.parsers.Parser¶

Bases: object

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

Initialize the parser.

parse()¶

Generator to return coloured text from raw text.

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

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

reset(text, colours)¶

Reset the parser to analyze the supplied raw text.

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

asciimatics.particles module¶

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

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

Bases: asciimatics.particles.ParticleEmitter

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

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

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

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

Bases: asciimatics.particles.ParticleEffect

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

See ParticleEffect for details of the parameters.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.particles.ParticleEffect

An explosion effect.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.particles.ParticleEmitter

An explosion of flame and smoke.

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

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

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

Bases: asciimatics.particles.ParticleEmitter

A classic firework explosion into a palm shape.

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

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

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

Bases: asciimatics.particles.ParticleEffect

Classic palm shaped firework.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

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: future.types.newobject.newobject

A single particle in a Particle Effect.

Parameters:

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

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

next()¶

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

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

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

Bases: asciimatics.effects.Effect

An Effect that uses a ParticleEmitter to create the animation.

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

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

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

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

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: future.types.newobject.newobject

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

Parameters:

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

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

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

Bases: asciimatics.particles.ParticleEffect

Rain storm effect.

See ParticleEffect for details of the parameters.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.particles.ParticleEmitter

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

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

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

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

Bases: asciimatics.particles.ParticleEmitter

A classic firework explosion in a simple ring.

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

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

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

Bases: asciimatics.particles.ParticleEffect

Classic rocket with ring explosion.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.particles.ParticleEmitter

A rocket being launched from the ground.

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

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

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

Bases: asciimatics.particles.ParticleEmitter

A firework explosion where each trail changes direction.

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

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

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

Bases: asciimatics.particles.ParticleEffect

A firework where each trail changes direction.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.particles.ParticleEffect

Shoot the screen out like a massive gunshot.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.particles.ParticleEmitter

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

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

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

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

Bases: asciimatics.particles.ParticleEmitter

Splash effect for falling rain.

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

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

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

Bases: asciimatics.particles.ParticleEmitter

A classic firework explosion to a Peony shape with trails.

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

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

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

Bases: asciimatics.particles.ParticleEffect

Classic rocket with star explosion.

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

Also see the common keyword arguments in Effect.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

process_event(event)¶

Process any input event.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.particles.ParticleEmitter

A trail for a StarExplosion.

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

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

asciimatics.paths module¶

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

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

Bases: asciimatics.paths._AbstractPath

Class to create a dynamic path that reacts to events

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

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

is_finished()¶

Returns:	Whether this path has got to the end.

next_pos()¶

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

process_event(event)¶

Process any mouse event.

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

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

class asciimatics.paths.Path¶

Bases: asciimatics.paths._AbstractPath

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

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

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

is_finished()¶

Returns:	Whether this path has got to the end.

jump_to(x, y)¶

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

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

move_round_to(points, steps)¶

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

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

move_straight_to(x, y, steps)¶

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

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

next_pos()¶

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

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

wait(delay)¶

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

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

asciimatics.renderers module¶

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

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

Bases: asciimatics.renderers.DynamicRenderer

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

Parameters:

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

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

Bases: asciimatics.renderers.StaticRenderer

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

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

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

Bases: asciimatics.renderers.StaticRenderer

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

Warning

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

Parameters:

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

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

Bases: asciimatics.renderers.Renderer

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

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

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

Bases: asciimatics.renderers.StaticRenderer

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

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

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

Bases: asciimatics.renderers.DynamicRenderer

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

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

Parameters:

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

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

Bases: asciimatics.renderers.StaticRenderer

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

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

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

Bases: asciimatics.renderers.DynamicRenderer

Renderer to create a 2-mirror kaleidoscope effect.

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

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

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

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

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

Bases: asciimatics.renderers.DynamicRenderer

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

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

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

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

Bases: asciimatics.renderers.StaticRenderer

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

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

class asciimatics.renderers.Renderer¶

Bases: future.types.newobject.newobject

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

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

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

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

Bases: asciimatics.renderers.StaticRenderer

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

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

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

Bases: asciimatics.renderers.StaticRenderer

Renders supplied text into a speech bubble.

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

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

Bases: asciimatics.renderers.Renderer

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

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

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

images¶

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

max_height¶

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

max_width¶

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

rendered_text¶

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

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

asciimatics.scene module¶

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

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

Bases: future.types.newobject.newobject

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

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

add_effect(effect, reset=True)¶

Add an effect to the Scene.

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

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

clear¶

Returns:	Whether the Scene should clear at the start.

duration¶

Returns:	The length of the scene in frames.

effects¶

Returns:	The list of Effects in this Scene.

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

name¶

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

process_event(event)¶

Process a new input event.

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

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

remove_effect(effect)¶

Remove an effect from the scene.

Parameters:	effect – The effect to remove.

reset(old_scene=None, screen=None)¶

Reset the scene ready for playing.

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

asciimatics.screen module¶

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

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

Bases: asciimatics.screen._AbstractCanvas

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

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

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

block_transfer(buffer, x, y)¶

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

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

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

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

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

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

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

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

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

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

dimensions¶

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

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

Draw a line from drawing cursor to the specified position.

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

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

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

Draw a filled polygon.

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

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

get_from(x, y)¶

Get the character at the specified location.

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

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

Highlight a specified section of the screen.

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

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

is_visible(x, y)¶

Return whether the specified location is on the visible screen.

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

move(x, y)¶

Move the drawing cursor to the specified position.

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

origin¶

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

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

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

Paint multi-colour text at the defined location.

Parameters:

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

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

palette¶

Returns:	A palette compatible with the PIL.

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

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

Parameters:

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

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

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

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

scroll(lines=1)¶

Scroll the abstract canvas up one line.

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

scroll_to(line)¶

Scroll the abstract canvas to make a specific line.

Parameters:	line – The line to scroll to.

start_line¶

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

unicode_aware¶

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

asciimatics.screen.ManagedScreen¶: 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.

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

Bases: asciimatics.screen._AbstractCanvas

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

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

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

Don’t call this constructor directly.

block_transfer(buffer, x, y)¶

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

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

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

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

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

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

clear()¶

Clear the Screen of all content.

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

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

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

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

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

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

close(restore=True)¶

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

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

static ctrl(char)¶

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

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

current_scene¶

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

dimensions¶

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

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

Draw a line from drawing cursor to the specified position.

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

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

draw_next_frame(repeat=True)¶

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

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

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

Draw a filled polygon.

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

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

force_update()¶: 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.

get_event()¶

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

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

get_from(x, y)¶

Get the character at the specified location.

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

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

getch(x, y)¶

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

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

has_resized()¶

Check whether the screen has been re-sized.

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

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

Highlight a specified section of the screen.

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

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

is_visible(x, y)¶

Return whether the specified location is on the visible screen.

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

move(x, y)¶

Move the drawing cursor to the specified position.

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

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

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

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

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

Paint multi-colour text at the defined location.

Parameters:

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

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

palette¶

Returns:	A palette compatible with the PIL.

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

Play a set of scenes.

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

Parameters:

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

Raises:

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

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

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

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

Parameters:

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

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

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

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

Parameters:

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

refresh()¶: Refresh the screen.

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

scroll(lines=1)¶

Scroll the abstract canvas up one line.

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

scroll_to(line)¶

Scroll the abstract canvas to make a specific line.

Parameters:	line – The line to scroll to.

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

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

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

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

set_title(title)¶

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

Parameters:	title – The title to be set.

start_line¶

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

unicode_aware¶

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

wait_for_input(timeout)¶

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

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

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

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

Parameters:

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

asciimatics.sprites module¶

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

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

Bases: asciimatics.effects.Sprite

Sample arrow sprite - points where it is going.

See Sprite for details.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

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

overlaps(other, use_new_pos=False)¶

Check whether this Sprite overlaps another.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Sprite

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

See Sprite for details.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

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

overlaps(other, use_new_pos=False)¶

Check whether this Sprite overlaps another.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

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

Bases: asciimatics.effects.Sprite

Sam Paul sprite - an simple sample animated character.

See Sprite for details.

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

frame_update_count¶

The number of frames before this Effect should be updated.

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

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

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

overlaps(other, use_new_pos=False)¶

Check whether this Sprite overlaps another.

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

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

safe_to_default_unhandled_input¶

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

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

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

asciimatics.utilities module¶

This module is just a collection of simple helper functions.

asciimatics.utilities.readable_mem(mem)¶

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

asciimatics.utilities.readable_timestamp(stamp)¶

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

asciimatics.version module¶

asciimatics.widgets module¶

This module allows you to create interactive text user interfaces. For more details see http://asciimatics.readthedocs.io/en/latest/widgets.html

class asciimatics.widgets.Button(text, on_click, label=None, add_box=True, **kwargs)¶

Bases: asciimatics.widgets.Widget

A Button widget to be displayed in a Frame.

It is typically used to represent a desired action for te user to invoke (e.g. a submit button on a form).

Parameters:	text – The text for the button. on_click – The function to invoke when the button is clicked. label – An optional label for the widget.

Also see the common keyword arguments in Widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.CheckBox(text, label=None, name=None, on_change=None, **kwargs)¶

Bases: asciimatics.widgets.Widget

A CheckBox widget is used to ask for Boolean (i.e. yes/no) input.

It consists of an optional label (typically used for the first in a group of CheckBoxes), the box and a field name.

Parameters:	text – The text to explain this specific field to the user. label – An optional label for the widget. name – The internal name for the widget. on_change – Optional function to call when text changes.

Also see the common keyword arguments in Widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.DatePicker(label=None, name=None, year_range=None, on_change=None, **kwargs)¶

Bases: asciimatics.widgets.Widget

A DatePicker widget allows you to pick a date from a compact, temporary, pop-up Frame.

Parameters:	label – An optional label for the widget. name – The name for the widget. on_change – Optional function to call when the selected time changes.

Also see the common keyword arguments in Widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.Divider(draw_line=True, height=1, line_char=None)¶

Bases: asciimatics.widgets.Widget

A divider to break up a group of widgets.

Parameters:	draw_line – Whether to draw a line in the centre of the gap. height – The required vertical gap. line_char – Optional character to use for drawing the line.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.DropdownList(options, label=None, name=None, on_change=None, **kwargs)¶

Bases: asciimatics.widgets.Widget

This widget allows you to pick an item from a temporary pop-up list.

Parameters:	options – The options for each row in the widget. label – An optional label for the widget. name – The name for the widget. on_change – Optional function to call when the selected time changes.

The options are a list of tuples, where the first value is the string to be displayed to the user and the second is an interval value to identify the entry to the program. For example:

options=[(“First option”, 1), (“Second option”, 2)]

Also see the common keyword arguments in Widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

options¶: The set of allowed options for the drop-down list.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.FileBrowser(height, root, name=None, on_select=None, on_change=None, file_filter=None)¶

Bases: asciimatics.widgets.MultiColumnListBox

A FileBrowser is a widget for finding a file on the local disk.

Parameters:

height – The desired height for this widget.
root – The starting root directory to display in the widget.
name – The name of this widget.
on_select – Optional function that gets called when user selects a file (by pressing enter or double-clicking).
on_change – Optional function that gets called on any movement of the selection.
file_filter – Optional RegEx string that can be passed in to filter the files to be displayed.

Most people will want to use a filter to finx files with a particular extension. In this case, you must use a regex that matches to the end of the line - e.g. use “.*.txt$” to find files ending with “.txt”. This ensures that you don’t accidentally pick up files containing the filter.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

options¶

The list of options available for user selection

This is a list of tuples ([<col 1 string>, …, <col n string>], <internal value>).

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

start_line¶: The line that will be drawn at the top of the visible section of this list.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.Frame(screen, height, width, data=None, on_load=None, has_border=True, hover_focus=False, name=None, title=None, x=None, y=None, has_shadow=False, reduce_cpu=False, is_modal=False, can_scroll=True)¶

Bases: asciimatics.effects.Effect

A Frame is a special Effect for controlling and displaying Widgets.

It is similar to a window as used in native GUI applications. Widgets are text UI elements that can be used to create an interactive application within your Frame.

Parameters:

screen – The Screen that owns this Frame.
width – The desired width of the Frame.
height – The desired height of the Frame.
data – optional data dict to initialize any widgets in the frame.
on_load – optional function to call whenever the Frame reloads.
has_border – Whether the frame has a border box (and scroll bar). Defaults to True.
hover_focus – Whether hovering a mouse over a widget (i.e. mouse move events) should change the input focus. Defaults to false.
name – Optional name to identify this Frame. This is used to reset data as needed from on old copy after the screen resizes.
title – Optional title to display if has_border is True.
x – Optional x position for the top left corner of the Frame.
y – Optional y position for the top left corner of the Frame.
has_shadow – Optional flag to indicate if this Frame should have a shadow when drawn.
reduce_cpu – Whether to minimize CPU usage (for use on low spec systems).
is_modal – Whether this Frame is “modal” - i.e. will stop all other Effects from receiving input events.
can_scroll – Whether a scrollbar should be available on the border, or not. (Only valid if has_border=True).

add_effect(effect)¶

Add an Effect to the Frame.

Parameters:	effect – The Effect to be added.

add_layout(layout)¶

Add a Layout to the Frame.

Parameters:	layout – The Layout to be added.

canvas¶: The Canvas that backs this Frame.

clone(_, scene)¶

Create a clone of this Frame into a new Screen.

Parameters:	_ – ignored. scene – The new Scene object to clone into.

data¶: Data dictionary containing values from the contained widgets.

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

find_widget(name)¶

Look for a widget with a specified name.

Parameters:	name – The name to search for.
Returns:	The widget that matches or None if one couldn’t be found.

fix()¶

Fix the layouts and calculate the locations of all the widgets.

This function should be called once all Layouts have been added to the Frame and all widgets added to the Layouts.

focussed_widget¶: The widget that currently has the focus within this Frame.

frame_update_count¶: The number of frames before this Effect should be updated.

move_to(x, y, h)¶

Make the specified location visible. This is typically used by a widget to scroll the canvas such that it is visible.

Parameters:	x – The x location to make visible. y – The y location to make visible. h – The height of the location to make visible.

rebase_event(event)¶

Rebase the coordinates of the passed event to frame-relative coordinates.

Parameters:	event – The event to be rebased.
Returns:	A new event object appropriately re-based.

reduce_cpu¶: Whether this Frame should try to optimize refreshes to reduce CPU.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

save(validate=False)¶

Save the current values in all the widgets back to the persistent data storage.

Parameters:	validate – Whether to validate the data before saving.

Calling this while setting the data field (e.g. in a widget callback) will have no effect.

When validating data, it can throw an Exception for any

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

set_theme(theme)¶

Pick a palette from the list of supported THEMES.

Parameters:	theme – The name of the theme to set.

switch_focus(layout, column, widget)¶

Switch focus to the specified widget.

Parameters:	layout – The layout that owns the widget. column – The column the widget is in. widget – The index of the widget to take the focus.

title¶: Title for this Frame.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

class asciimatics.widgets.Label(label, height=1, align=u'<')¶

Bases: asciimatics.widgets.Widget

A text label.

Parameters:	label – The text to be displayed for the Label. height – Optional height for the label. Defaults to 1 line. align – Optional alignment for the Label. Defaults to left aligned. Options are “<” = left, “>” = right and “^” = centre

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

text¶: The current text for this Label.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.Layout(columns, fill_frame=False)¶

Bases: future.types.newobject.newobject

Widget layout handler.

All Widgets must be contained within a Layout within a Frame.The Layout class is responsible for deciding the exact size and location of the widgets. The logic uses similar ideas as used in modern web frameworks and is as follows.

The Frame owns one or more Layouts. The Layouts stack one above each other when displayed - i.e. the first Layout in the Frame is above the second, etc.
Each Layout defines the horizontal constraints by defining columns as a percentage of the full canvas width.
The Widgets are assigned a column within the Layout that owns them.
The Layout then decides the exact size and location to make the Widget best fit the canvas as constrained by the above.

Parameters:	columns – A list of numbers specifying the width of each column in this layout. fill_frame – Whether this Layout should attempt to fill the rest of the Frame. Defaults to False.

The Layout will automatically normalize the units used for the columns, e.g. converting [2, 6, 2] to [20%, 60%, 20%] of the available canvas.

add_widget(widget, column=0)¶

Add a widget to this Layout.

If you are adding this Widget to the Layout dynamically after starting to play the Scene, don’t forget to ensure that the value is explicitly set before the next update.

Parameters:	widget – The widget to be added. column – The column within the widget for this widget. Defaults to zero.

blur()¶: Call this to take the input focus from this Layout.

clear_widgets()¶

Clear all widgets from this Layout.

This method allows users of the Layout to dynamically recreate a new Layout. After calling this method, you can add new widgetsback into the Layout and then need to call fix to force the Frame to recalculate the resulting new overall layout.

disable(columns=None)¶

Disable all widgets in the specified columns of this Layout.

Parameters:	columns – The list of columns to disable. Defaults to all columns.

enable(columns=None)¶

Enable all widgets in the specified columns of this Layout.

Parameters:	columns – The list of columns to enable. Defaults to all columns.

fill_frame¶: Whether this Layout is variable height or not.

find_widget(name)¶

Look for a widget with a specified name.

Parameters:	name – The name to search for.
Returns:	The widget that matches or None if one couldn’t be found.

fix(start_x, start_y, max_width, max_height)¶

Fix the location and size of all the Widgets in this Layout.

Parameters:	start_x – The start column for the Layout. start_y – The start line for the Layout. max_width – Max width to allow this layout. max_height – Max height to allow this layout.
Returns:	The next line to be used for any further Layouts.

focus(force_first=False, force_last=False, force_column=None, force_widget=None)¶

Call this to give this Layout the input focus.

Parameters:	force_first – Optional parameter to force focus to first widget. force_last – Optional parameter to force focus to last widget. force_column – Optional parameter to mandate the new column index. force_widget – Optional parameter to mandate the new widget index.

The force_column and force_widget parameters must both be set together or they will otherwise be ignored.

Raises:	IndexError – if a force option specifies a bad column or widget, or if the whole Layout is readonly.

frame_update_count¶: The number of frames before this Layout should be updated.

get_current_widget()¶: Return the current widget with the focus, or None if there isn’t one.

get_nearest_widget(target_widget, direction)¶

Find the nearest enabled widget to the specified target widget, bearing in mind the direction of travel.

Direction of travel is defined to be the movement from current Layout to next. This is important for the case where we wrap back to the beginning or end of the Layouts - and so should still only look for the widgets nearest the top/bottom (depending on direction of travel).

This function may return None if there is no match (e.g. all widgets are disabled).

Parameters:	target_widget – the target widget to match. direction – The direction of travel across Layouts.

process_event(event, hover_focus)¶

Process any input event.

Parameters:	event – The event that was triggered. hover_focus – Whether to trigger focus change on mouse moves.
Returns:	None if the Effect processed the event, else the original event.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

reset()¶: Reset this Layout and the Widgets it contains.

save(validate)¶

Save the current values in all the widgets back to the persistent data storage.

Parameters:	validate – whether to validate the saved data or not.
Raises:	InvalidFields if any invalid data is found.

update(frame_no)¶

Redraw the widgets inside this Layout.

Parameters:	frame_no – The current frame to be drawn.

update_widgets(new_frame=None)¶

Reset the values for any Widgets in this Layout based on the current Frame data store.

Parameters:	new_frame – optional old Frame - used when cloning scenes.

class asciimatics.widgets.ListBox(height, options, centre=False, label=None, name=None, add_scroll_bar=False, parser=None, on_change=None, on_select=None, validator=None)¶

Bases: asciimatics.widgets._BaseListBox

A ListBox is a widget that displays a list from which the user can select one option.

Parameters:

height – The required number of input lines for this ListBox.
options – The options for each row in the widget.
centre – Whether to centre the selected line in the list.
label – An optional label for the widget.
name – The name for the ListBox.
parser – Optional parser to colour text.
on_change – Optional function to call when selection changes.
on_select – Optional function to call when the user actually selects an entry from
validator – Optional function to validate selection for this widget.

The options are a list of tuples, where the first value is the string to be displayed to the user and the second is an interval value to identify the entry to the program. For example:

options=[(“First option”, 1), (“Second option”, 2)]

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

options¶

The list of options available for user selection

This is a list of tuples (<human readable string>, <internal value>).

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

start_line¶: The line that will be drawn at the top of the visible section of this list.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.MultiColumnListBox(height, columns, options, titles=None, label=None, name=None, add_scroll_bar=False, parser=None, on_change=None, on_select=None, space_delimiter=u' ')¶

Bases: asciimatics.widgets._BaseListBox

A MultiColumnListBox is a widget for displaying tabular data.

It displays a list of related data in columns, from which the user can select a line.

Parameters:

height – The required number of input lines for this ListBox.
columns – A list of widths and alignments for each column.
options – The options for each row in the widget.
titles – Optional list of titles for each column. Must match the length of columns.
label – An optional label for the widget.
name – The name for the ListBox.
add_scroll_bar – Whether to add optional scrollbar for large lists.
parser – Optional parser to colour text.
on_change – Optional function to call when selection changes.
on_select – Optional function to call when the user actually selects an entry from
space_delimiter – Optional parameter to define the delimiter between columns. The default value is blank space.

The columns parameter is a list of integers or strings. If it is an integer, this is the absolute width of the column in characters. If it is a string, it must be of the format “[<align>]<width>[%]” where:

<align> is the alignment string (“<” = left, “>” = right, “^” = centre)
<width> is the width in characters
% is an optional qualifier that says the number is a percentage of the width of the widget.

Column widths need to encompass any space required between columns, so for example, if your column is 5 characters, allow 6 for an extra space at the end. It is not possible to do this when you have a right-justified column next to a left-justified column, so this widget will automatically space them for you.

An integer value of 0 is interpreted to be use whatever space is left available after the rest of the columns have been calculated. There must be only one of these columns.

The number of columns is for this widget is determined from the number of entries in the columns parameter. The options list is then a list of tuples of the form ([val1, val2, … , valn], index). For example, this data provides 2 rows for a 3 column widget:

options=[([“One”, “row”, “here”], 1), ([“Second”, “row”, “here”], 2)]

The options list may be None and then can be set later using the options property on this widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

options¶

The list of options available for user selection

This is a list of tuples ([<col 1 string>, …, <col n string>], <internal value>).

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

start_line¶: The line that will be drawn at the top of the visible section of this list.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.PopUpDialog(screen, text, buttons, on_close=None, has_shadow=False, theme=u'warning')¶

Bases: asciimatics.widgets.Frame

A fixed implementation Frame that provides a standard message box dialog.

Parameters:

screen – The Screen that owns this dialog.
text – The message text to display.
buttons – A list of button names to display. This may be an empty list.
on_close – Optional function to invoke on exit.
has_shadow – optional flag to specify if dialog should have a shadow when drawn.
theme – optional colour theme for this pop-up. Defaults to the warning colours.

The on_close method (if specified) will be called with one integer parameter that corresponds to the index of the button passed in the array of available buttons.

Note that on_close must be a static method to work across screen resizing. Either it is static (and so the dialog will be cloned) or it is not (and the dialog will disappear when the screen is resized).

add_effect(effect)¶

Add an Effect to the Frame.

Parameters:	effect – The Effect to be added.

add_layout(layout)¶

Add a Layout to the Frame.

Parameters:	layout – The Layout to be added.

canvas¶: The Canvas that backs this Frame.

clone(screen, scene)¶

Create a clone of this Dialog into a new Screen.

Parameters:	screen – The new Screen object to clone into. scene – The new Scene object to clone into.

data¶: Data dictionary containing values from the contained widgets.

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

find_widget(name)¶

Look for a widget with a specified name.

Parameters:	name – The name to search for.
Returns:	The widget that matches or None if one couldn’t be found.

fix()¶

Fix the layouts and calculate the locations of all the widgets.

This function should be called once all Layouts have been added to the Frame and all widgets added to the Layouts.

focussed_widget¶: The widget that currently has the focus within this Frame.

frame_update_count¶: The number of frames before this Effect should be updated.

move_to(x, y, h)¶

Make the specified location visible. This is typically used by a widget to scroll the canvas such that it is visible.

Parameters:	x – The x location to make visible. y – The y location to make visible. h – The height of the location to make visible.

rebase_event(event)¶

Rebase the coordinates of the passed event to frame-relative coordinates.

Parameters:	event – The event to be rebased.
Returns:	A new event object appropriately re-based.

reduce_cpu¶: Whether this Frame should try to optimize refreshes to reduce CPU.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

save(validate=False)¶

Save the current values in all the widgets back to the persistent data storage.

Parameters:	validate – Whether to validate the data before saving.

Calling this while setting the data field (e.g. in a widget callback) will have no effect.

When validating data, it can throw an Exception for any

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

set_theme(theme)¶

Pick a palette from the list of supported THEMES.

Parameters:	theme – The name of the theme to set.

switch_focus(layout, column, widget)¶

Switch focus to the specified widget.

Parameters:	layout – The layout that owns the widget. column – The column the widget is in. widget – The index of the widget to take the focus.

title¶: Title for this Frame.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

class asciimatics.widgets.PopupMenu(screen, menu_items, x, y)¶

Bases: asciimatics.widgets.Frame

A widget for displaying a menu.

Parameters:	screen – The Screen being used for this pop-up. menu_items – a list of items to be displayed in the menu. x – The X coordinate for the desired pop-up. y – The Y coordinate for the desired pop-up.

The menu_items parameter is a list of 2-tuples, which define the text to be displayed in the menu and the function to call when that menu item is clicked. For example:

menu_items = [(“Open”, file_open), (“Save”, file_save), (“Close”, file_close)]

add_effect(effect)¶

Add an Effect to the Frame.

Parameters:	effect – The Effect to be added.

add_layout(layout)¶

Add a Layout to the Frame.

Parameters:	layout – The Layout to be added.

canvas¶: The Canvas that backs this Frame.

clone(_, scene)¶

Create a clone of this Frame into a new Screen.

Parameters:	_ – ignored. scene – The new Scene object to clone into.

data¶: Data dictionary containing values from the contained widgets.

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

find_widget(name)¶

Look for a widget with a specified name.

Parameters:	name – The name to search for.
Returns:	The widget that matches or None if one couldn’t be found.

fix()¶

Fix the layouts and calculate the locations of all the widgets.

This function should be called once all Layouts have been added to the Frame and all widgets added to the Layouts.

focussed_widget¶: The widget that currently has the focus within this Frame.

frame_update_count¶: The number of frames before this Effect should be updated.

move_to(x, y, h)¶

Make the specified location visible. This is typically used by a widget to scroll the canvas such that it is visible.

Parameters:	x – The x location to make visible. y – The y location to make visible. h – The height of the location to make visible.

rebase_event(event)¶

Rebase the coordinates of the passed event to frame-relative coordinates.

Parameters:	event – The event to be rebased.
Returns:	A new event object appropriately re-based.

reduce_cpu¶: Whether this Frame should try to optimize refreshes to reduce CPU.

register_scene(scene)¶

Register the Scene that owns this Effect.

Parameters:	scene – The Scene to be registered

save(validate=False)¶

Save the current values in all the widgets back to the persistent data storage.

Parameters:	validate – Whether to validate the data before saving.

Calling this while setting the data field (e.g. in a widget callback) will have no effect.

When validating data, it can throw an Exception for any

scene¶: The Scene that owns this Effect.

screen¶: The Screen that will render this Effect.

set_theme(theme)¶

Pick a palette from the list of supported THEMES.

Parameters:	theme – The name of the theme to set.

switch_focus(layout, column, widget)¶

Switch focus to the specified widget.

Parameters:	layout – The layout that owns the widget. column – The column the widget is in. widget – The index of the widget to take the focus.

title¶: Title for this Frame.

update(frame_no)¶

Process the animation effect for the specified frame number.

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

class asciimatics.widgets.RadioButtons(options, label=None, name=None, on_change=None, **kwargs)¶

Bases: asciimatics.widgets.Widget

A RadioButtons widget is used to ask for one of a list of values to be selected by the user.

It consists of an optional label and then a list of selection bullets with field names.

Parameters:	options – A list of (text, value) tuples for each radio button. label – An optional label for the widget. name – The internal name for the widget. on_change – Optional function to call when text changes.

Also see the common keyword arguments in Widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.Text(label=None, name=None, on_change=None, validator=None, hide_char=None, max_length=None, readonly=False, **kwargs)¶

Bases: asciimatics.widgets.Widget

A Text widget is a single line input field.

It consists of an optional label and an entry box.

Parameters:

label – An optional label for the widget.
name – The name for the widget.
on_change – Optional function to call when text changes.
validator – Optional definition of valid data for this widget. This can be a function (which takes the current value and returns True for valid content) or a regex string (which must match the entire allowed value).
hide_char – Character to use instead of what the user types - e.g. to hide passwords.
max_length – Optional maximum length of the field. If set, the widget will limit data entry to this length.
readonly – Whether the widget prevents user input to change values. Default is False.

Also see the common keyword arguments in Widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

readonly¶: Whether this widget is readonly or not.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.TextBox(height, label=None, name=None, as_string=False, line_wrap=False, parser=None, on_change=None, readonly=False, **kwargs)¶

Bases: asciimatics.widgets.Widget

A TextBox is a widget for multi-line text editing.

It consists of a framed box with option label.

Parameters:

height – The required number of input lines for this TextBox.
label – An optional label for the widget.
name – The name for the TextBox.
as_string – Use string with newline separator instead of a list for the value of this widget.
line_wrap – Whether to wrap at the end of the line.
parser – Optional parser to colour text.
on_change – Optional function to call when text changes.
readonly – Whether the widget prevents user input to change values. Default is False.

Also see the common keyword arguments in Widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

readonly¶: Whether this widget is readonly or not.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.TimePicker(label=None, name=None, seconds=False, on_change=None, **kwargs)¶

Bases: asciimatics.widgets.Widget

A TimePicker widget allows you to pick a time from a compact, temporary, pop-up Frame.

Parameters:	label – An optional label for the widget. name – The name for the widget. seconds – Whether to include selection of seconds or not. on_change – Optional function to call when the selected time changes.

Also see the common keyword arguments in Widget.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.VerticalDivider(height=-135792467)¶

Bases: asciimatics.widgets.Widget

A vertical divider for separating columns.

This widget should be put into a column of its own in the Layout.

Parameters:	height – The required height for this divider.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

register_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

class asciimatics.widgets.Widget(name, tab_stop=True, disabled=False, on_focus=None, on_blur=None)¶

Bases: future.types.newobject.newobject

A Widget is a re-usable component that can be used to create a simple GUI.

Parameters:	name – The name of this Widget. tab_stop – Whether this widget should take focus or not when tabbing around the Frame. disabled – Whether this Widget should be disabled or not. on_focus – Optional callback whenever this widget gets the focus. on_blur – Optional callback whenever this widget loses the focus.

blur()¶: Call this to take the input focus from this Widget.

custom_colour¶

A custom colour to use instead of the normal calculated one when drawing this widget.

This must be a key name from the palette dictionary.

disabled¶: Whether this widget is disabled or not.

focus()¶: Call this to give this Widget the input focus.

frame¶: The Frame that contains this Widget.

frame_update_count¶: The number of frames before this Widget should be updated.

get_location()¶

Return the absolute location of this widget on the Screen, taking into account the current state of the Frame that is displaying it and any label offsets of the Widget.

Returns:	A tuple of the form (<X coordinate>, <Y coordinate>).

is_mouse_over(event, include_label=True, width_modifier=0)¶

Check if the specified mouse event is over this widget.

Parameters:	event – The MouseEvent to check. include_label – Include space reserved for the label when checking. width_modifier – Adjustement to width (e.g. for scroll bars).
Returns:	True if the mouse is over the active parts of the widget.

is_tab_stop¶: Whether this widget is a valid tab stop for keyboard navigation.

is_valid¶: Whether this widget has passed its data validation or not.

is_visible¶: Whether this widget is visible on the Canvas or not.

label¶: The label for this widget. Can be None.

name¶: The name for this widget (for reference in the persistent data). Can be None.

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_frame(frame)¶

Register the Frame that owns this Widget.

Parameters:	frame – The owning Frame.

required_height(offset, width)¶

Calculate the minimum required height for this widget.

Parameters:	offset – The allowed width for any labels. width – The total width of the widget, including labels.

reset()¶: The reset method is called whenever the widget needs to go back to its default (initially created) state.

set_layout(x, y, offset, w, h)¶

Set the size and position of the Widget.

This should not be called directly. It is used by the Layout class to arrange all widgets within the Frame.

Parameters:	x – The x position of the widget. y – The y position of the widget. offset – The allowed label size for the widget. w – The width of the widget. h – The height of the widget.

update(frame_no)¶

The update method is called whenever this widget needs to redraw itself.

Parameters:	frame_no – The frame number for this screen update.

width¶

The width of this Widget (excluding any labels).

Only valid after the Frame has been fixed in place.

Module contents¶

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

asciimatics package¶

Submodules¶

asciimatics.constants module¶

asciimatics.effects module¶

asciimatics.event module¶

asciimatics.exceptions module¶

asciimatics.parsers module¶

asciimatics.particles module¶

asciimatics.paths module¶

asciimatics.renderers module¶

asciimatics.scene module¶

asciimatics.screen module¶

asciimatics.sprites module¶

asciimatics.utilities module¶

asciimatics.version module¶

asciimatics.widgets module¶

Module contents¶

Table of Contents

Previous topic

This Page