asciimatics package¶
Subpackages¶
- asciimatics.renderers package
- Submodules
- asciimatics.renderers.base module
- asciimatics.renderers.box module
- asciimatics.renderers.charts module
- asciimatics.renderers.figlettext module
- asciimatics.renderers.fire module
- asciimatics.renderers.images module
- asciimatics.renderers.kaleidoscope module
- asciimatics.renderers.plasma module
- asciimatics.renderers.players module
- asciimatics.renderers.rainbow module
- asciimatics.renderers.rotatedduplicate module
- asciimatics.renderers.scales module
- asciimatics.renderers.speechbubble module
- Module contents
- asciimatics.widgets package
- Submodules
- asciimatics.widgets.baselistbox module
- asciimatics.widgets.button module
Button
Button.FILL_COLUMN
Button.FILL_FRAME
Button.blur()
Button.custom_colour
Button.disabled
Button.focus()
Button.frame
Button.frame_update_count
Button.get_location()
Button.is_mouse_over()
Button.is_tab_stop
Button.is_valid
Button.is_visible
Button.label
Button.name
Button.process_event()
Button.register_frame()
Button.required_height()
Button.reset()
Button.set_layout()
Button.text
Button.update()
Button.value
Button.width
- asciimatics.widgets.checkbox module
CheckBox
CheckBox.FILL_COLUMN
CheckBox.FILL_FRAME
CheckBox.blur()
CheckBox.custom_colour
CheckBox.disabled
CheckBox.focus()
CheckBox.frame
CheckBox.frame_update_count
CheckBox.get_location()
CheckBox.is_mouse_over()
CheckBox.is_tab_stop
CheckBox.is_valid
CheckBox.is_visible
CheckBox.label
CheckBox.name
CheckBox.process_event()
CheckBox.register_frame()
CheckBox.required_height()
CheckBox.reset()
CheckBox.set_layout()
CheckBox.update()
CheckBox.value
CheckBox.width
- asciimatics.widgets.datepicker module
DatePicker
DatePicker.FILL_COLUMN
DatePicker.FILL_FRAME
DatePicker.blur()
DatePicker.custom_colour
DatePicker.disabled
DatePicker.focus()
DatePicker.frame
DatePicker.frame_update_count
DatePicker.get_location()
DatePicker.is_mouse_over()
DatePicker.is_tab_stop
DatePicker.is_valid
DatePicker.is_visible
DatePicker.label
DatePicker.name
DatePicker.process_event()
DatePicker.register_frame()
DatePicker.required_height()
DatePicker.reset()
DatePicker.set_layout()
DatePicker.update()
DatePicker.value
DatePicker.width
- asciimatics.widgets.divider module
Divider
Divider.FILL_COLUMN
Divider.FILL_FRAME
Divider.blur()
Divider.custom_colour
Divider.disabled
Divider.focus()
Divider.frame
Divider.frame_update_count
Divider.get_location()
Divider.is_mouse_over()
Divider.is_tab_stop
Divider.is_valid
Divider.is_visible
Divider.label
Divider.name
Divider.process_event()
Divider.register_frame()
Divider.required_height()
Divider.reset()
Divider.set_layout()
Divider.update()
Divider.value
Divider.width
- asciimatics.widgets.dropdownlist module
DropdownList
DropdownList.FILL_COLUMN
DropdownList.FILL_FRAME
DropdownList.blur()
DropdownList.custom_colour
DropdownList.disabled
DropdownList.fit
DropdownList.focus()
DropdownList.frame
DropdownList.frame_update_count
DropdownList.get_location()
DropdownList.is_mouse_over()
DropdownList.is_tab_stop
DropdownList.is_valid
DropdownList.is_visible
DropdownList.label
DropdownList.name
DropdownList.options
DropdownList.process_event()
DropdownList.register_frame()
DropdownList.required_height()
DropdownList.reset()
DropdownList.set_layout()
DropdownList.update()
DropdownList.value
DropdownList.width
- asciimatics.widgets.filebrowser module
FileBrowser
FileBrowser.FILL_COLUMN
FileBrowser.FILL_FRAME
FileBrowser.blur()
FileBrowser.custom_colour
FileBrowser.disabled
FileBrowser.focus()
FileBrowser.frame
FileBrowser.frame_update_count
FileBrowser.get_location()
FileBrowser.is_mouse_over()
FileBrowser.is_tab_stop
FileBrowser.is_valid
FileBrowser.is_visible
FileBrowser.label
FileBrowser.name
FileBrowser.options
FileBrowser.process_event()
FileBrowser.register_frame()
FileBrowser.required_height()
FileBrowser.reset()
FileBrowser.set_layout()
FileBrowser.start_line
FileBrowser.update()
FileBrowser.value
FileBrowser.width
- asciimatics.widgets.frame module
Frame
Frame.add_effect()
Frame.add_layout()
Frame.blur()
Frame.border_box
Frame.canvas
Frame.clone()
Frame.data
Frame.delete_count
Frame.find_widget()
Frame.fix()
Frame.focussed_widget
Frame.frame_update_count
Frame.get_scroll_pos()
Frame.move_to()
Frame.palette
Frame.process_event()
Frame.rebase_event()
Frame.reduce_cpu
Frame.register_scene()
Frame.reset()
Frame.safe_to_default_unhandled_input
Frame.save()
Frame.scene
Frame.screen
Frame.set_scroll_pos()
Frame.set_theme()
Frame.stop_frame
Frame.switch_focus()
Frame.title
Frame.update()
- asciimatics.widgets.label module
Label
Label.FILL_COLUMN
Label.FILL_FRAME
Label.blur()
Label.custom_colour
Label.disabled
Label.focus()
Label.frame
Label.frame_update_count
Label.get_location()
Label.is_mouse_over()
Label.is_tab_stop
Label.is_valid
Label.is_visible
Label.label
Label.name
Label.process_event()
Label.register_frame()
Label.required_height()
Label.reset()
Label.set_layout()
Label.text
Label.update()
Label.value
Label.width
- asciimatics.widgets.layout module
Layout
Layout.add_widget()
Layout.blur()
Layout.clear_widgets()
Layout.disable()
Layout.enable()
Layout.fill_frame
Layout.find_widget()
Layout.fix()
Layout.focus()
Layout.frame_update_count
Layout.get_current_widget()
Layout.get_nearest_widget()
Layout.process_event()
Layout.register_frame()
Layout.reset()
Layout.save()
Layout.update()
Layout.update_widgets()
- asciimatics.widgets.listbox module
ListBox
ListBox.FILL_COLUMN
ListBox.FILL_FRAME
ListBox.blur()
ListBox.custom_colour
ListBox.disabled
ListBox.focus()
ListBox.frame
ListBox.frame_update_count
ListBox.get_location()
ListBox.is_mouse_over()
ListBox.is_tab_stop
ListBox.is_valid
ListBox.is_visible
ListBox.label
ListBox.name
ListBox.options
ListBox.process_event()
ListBox.register_frame()
ListBox.required_height()
ListBox.reset()
ListBox.set_layout()
ListBox.start_line
ListBox.update()
ListBox.value
ListBox.width
- asciimatics.widgets.multicolumnlistbox module
MultiColumnListBox
MultiColumnListBox.FILL_COLUMN
MultiColumnListBox.FILL_FRAME
MultiColumnListBox.blur()
MultiColumnListBox.custom_colour
MultiColumnListBox.disabled
MultiColumnListBox.focus()
MultiColumnListBox.frame
MultiColumnListBox.frame_update_count
MultiColumnListBox.get_location()
MultiColumnListBox.is_mouse_over()
MultiColumnListBox.is_tab_stop
MultiColumnListBox.is_valid
MultiColumnListBox.is_visible
MultiColumnListBox.label
MultiColumnListBox.name
MultiColumnListBox.options
MultiColumnListBox.process_event()
MultiColumnListBox.register_frame()
MultiColumnListBox.required_height()
MultiColumnListBox.reset()
MultiColumnListBox.set_layout()
MultiColumnListBox.start_line
MultiColumnListBox.update()
MultiColumnListBox.value
MultiColumnListBox.width
- asciimatics.widgets.popupdialog module
PopUpDialog
PopUpDialog.add_effect()
PopUpDialog.add_layout()
PopUpDialog.blur()
PopUpDialog.border_box
PopUpDialog.canvas
PopUpDialog.clone()
PopUpDialog.data
PopUpDialog.delete_count
PopUpDialog.find_widget()
PopUpDialog.fix()
PopUpDialog.focussed_widget
PopUpDialog.frame_update_count
PopUpDialog.get_scroll_pos()
PopUpDialog.move_to()
PopUpDialog.palette
PopUpDialog.process_event()
PopUpDialog.rebase_event()
PopUpDialog.reduce_cpu
PopUpDialog.register_scene()
PopUpDialog.reset()
PopUpDialog.safe_to_default_unhandled_input
PopUpDialog.save()
PopUpDialog.scene
PopUpDialog.screen
PopUpDialog.set_scroll_pos()
PopUpDialog.set_theme()
PopUpDialog.stop_frame
PopUpDialog.switch_focus()
PopUpDialog.title
PopUpDialog.update()
- asciimatics.widgets.popupmenu module
PopupMenu
PopupMenu.add_effect()
PopupMenu.add_layout()
PopupMenu.blur()
PopupMenu.border_box
PopupMenu.canvas
PopupMenu.clone()
PopupMenu.data
PopupMenu.delete_count
PopupMenu.find_widget()
PopupMenu.fix()
PopupMenu.focussed_widget
PopupMenu.frame_update_count
PopupMenu.get_scroll_pos()
PopupMenu.move_to()
PopupMenu.palette
PopupMenu.process_event()
PopupMenu.rebase_event()
PopupMenu.reduce_cpu
PopupMenu.register_scene()
PopupMenu.reset()
PopupMenu.safe_to_default_unhandled_input
PopupMenu.save()
PopupMenu.scene
PopupMenu.screen
PopupMenu.set_scroll_pos()
PopupMenu.set_theme()
PopupMenu.stop_frame
PopupMenu.switch_focus()
PopupMenu.title
PopupMenu.update()
- asciimatics.widgets.radiobuttons module
RadioButtons
RadioButtons.FILL_COLUMN
RadioButtons.FILL_FRAME
RadioButtons.blur()
RadioButtons.custom_colour
RadioButtons.disabled
RadioButtons.focus()
RadioButtons.frame
RadioButtons.frame_update_count
RadioButtons.get_location()
RadioButtons.is_mouse_over()
RadioButtons.is_tab_stop
RadioButtons.is_valid
RadioButtons.is_visible
RadioButtons.label
RadioButtons.name
RadioButtons.process_event()
RadioButtons.register_frame()
RadioButtons.required_height()
RadioButtons.reset()
RadioButtons.set_layout()
RadioButtons.update()
RadioButtons.value
RadioButtons.width
- asciimatics.widgets.scrollbar module
- asciimatics.widgets.temppopup module
- asciimatics.widgets.text module
Text
Text.FILL_COLUMN
Text.FILL_FRAME
Text.blur()
Text.custom_colour
Text.disabled
Text.focus()
Text.frame
Text.frame_update_count
Text.get_location()
Text.is_mouse_over()
Text.is_tab_stop
Text.is_valid
Text.is_visible
Text.label
Text.name
Text.process_event()
Text.readonly
Text.register_frame()
Text.required_height()
Text.reset()
Text.set_layout()
Text.update()
Text.value
Text.width
- asciimatics.widgets.textbox module
TextBox
TextBox.FILL_COLUMN
TextBox.FILL_FRAME
TextBox.auto_scroll
TextBox.blur()
TextBox.custom_colour
TextBox.disabled
TextBox.focus()
TextBox.frame
TextBox.frame_update_count
TextBox.get_location()
TextBox.hide_cursor
TextBox.is_mouse_over()
TextBox.is_tab_stop
TextBox.is_valid
TextBox.is_visible
TextBox.label
TextBox.name
TextBox.process_event()
TextBox.readonly
TextBox.register_frame()
TextBox.required_height()
TextBox.reset()
TextBox.set_layout()
TextBox.update()
TextBox.value
TextBox.width
- asciimatics.widgets.timepicker module
TimePicker
TimePicker.FILL_COLUMN
TimePicker.FILL_FRAME
TimePicker.blur()
TimePicker.custom_colour
TimePicker.disabled
TimePicker.focus()
TimePicker.frame
TimePicker.frame_update_count
TimePicker.get_location()
TimePicker.is_mouse_over()
TimePicker.is_tab_stop
TimePicker.is_valid
TimePicker.is_visible
TimePicker.label
TimePicker.name
TimePicker.process_event()
TimePicker.register_frame()
TimePicker.required_height()
TimePicker.reset()
TimePicker.set_layout()
TimePicker.update()
TimePicker.value
TimePicker.width
- asciimatics.widgets.utilities module
- asciimatics.widgets.verticaldivider module
VerticalDivider
VerticalDivider.FILL_COLUMN
VerticalDivider.FILL_FRAME
VerticalDivider.blur()
VerticalDivider.custom_colour
VerticalDivider.disabled
VerticalDivider.focus()
VerticalDivider.frame
VerticalDivider.frame_update_count
VerticalDivider.get_location()
VerticalDivider.is_mouse_over()
VerticalDivider.is_tab_stop
VerticalDivider.is_valid
VerticalDivider.is_visible
VerticalDivider.label
VerticalDivider.name
VerticalDivider.process_event()
VerticalDivider.register_frame()
VerticalDivider.required_height()
VerticalDivider.reset()
VerticalDivider.set_layout()
VerticalDivider.update()
VerticalDivider.value
VerticalDivider.width
- asciimatics.widgets.widget module
Widget
Widget.FILL_COLUMN
Widget.FILL_FRAME
Widget.blur()
Widget.custom_colour
Widget.disabled
Widget.focus()
Widget.frame
Widget.frame_update_count
Widget.get_location()
Widget.is_mouse_over()
Widget.is_tab_stop
Widget.is_valid
Widget.is_visible
Widget.label
Widget.name
Widget.process_event()
Widget.register_frame()
Widget.required_height()
Widget.reset()
Widget.set_layout()
Widget.update()
Widget.value
Widget.width
- Module contents
Submodules¶
asciimatics.constants module¶
This module is just a collection of simple helper functions.
- asciimatics.constants.COLOUR_REGEX = '^\\$\\{((\\d+),(\\d+),(\\d+)|(\\d+),(\\d+)|(\\d+))\\}(.*)'¶
Regex for asciimatics ${c,a,b} embedded colour attributes.
asciimatics.effects module¶
This module defines Effects which can be used for animations. For more details see http://asciimatics.readthedocs.io/en/latest/animation.html
- class asciimatics.effects.Background(screen, bg=0, **kwargs)¶
Bases:
Effect
Effect to be used as a Desktop background. This sets the background to the specified colour.
- Parameters:
screen – The Screen being used for the Scene.
bg – Optional colour for the background.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.BannerText(screen, renderer, y, colour, bg=0, **kwargs)¶
Bases:
Effect
Special effect to scroll some text (from a Renderer) horizontally like a banner.
- Parameters:
screen – The Screen being used for the Scene.
renderer – The renderer to be scrolled
y – The line (y coordinate) for the start of the text.
colour – The default foreground colour to use for the text.
bg – The default background colour to use for the text.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Clock(screen, x, y, r, bg=0, **kwargs)¶
Bases:
Effect
An ASCII ticking clock (telling the correct local time).
- Parameters:
screen – The Screen being used for the Scene.
x – X coordinate for the centre of the clock.
y – Y coordinate for the centre of the clock.
r – Radius of the clock.
bg – Background colour for the clock.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Cog(screen, x, y, radius, direction=1, colour=7, **kwargs)¶
Bases:
Effect
A rotating cog.
- Parameters:
screen – The Screen being used for the Scene.
x – X coordinate of the centre of the cog.
y – Y coordinate of the centre of the cog.
radius – The radius of the cog.
direction – The direction of rotation. Positive numbers are anti-clockwise, negative numbers clockwise.
colour – The colour of the cog.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Cycle(screen, renderer, y, **kwargs)¶
Bases:
Effect
Special effect to cycle the colours on some specified text from a Renderer. The text is automatically centred to the width of the Screen. This effect is not compatible with multi-colour rendered text.
- Parameters:
screen – The Screen being used for the Scene.
renderer – The Renderer which is to be cycled.
y – The line (y coordinate) for the start of the text.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Effect(screen, start_frame=0, stop_frame=0, delete_count=None)¶
Bases:
object
Abstract class to handle a special effect on the screen. An Effect can cover anything from a static image at the start of the Scene through to dynamic animations that need to be redrawn for every frame.
The basic interaction with a
Scene
is as follows: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.
- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- abstract reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- abstract property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Julia(screen, c=None, **kwargs)¶
Bases:
Effect
Julia Set generator. See http://en.wikipedia.org/wiki/Julia_set for more information on this fractal.
- Parameters:
screen – The Screen being used for the Scene.
c – The starting value of ‘c’ for the Julia Set.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Matrix(screen, **kwargs)¶
Bases:
Effect
Matrix-like falling green letters.
- Parameters:
screen – The Screen being used for the Scene.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Mirage(screen, renderer, y, colour, **kwargs)¶
Bases:
Effect
Special effect to make bits of the specified text appear over time. This text is automatically centred on the screen.
- Parameters:
screen – The Screen being used for the Scene.
renderer – The renderer to be displayed.
y – The line (y coordinate) for the start of the text.
colour – The colour attribute to use for the text.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Print(screen, renderer, y, x=None, colour=7, attr=0, bg=0, clear=False, transparent=True, speed=4, **kwargs)¶
Bases:
Effect
Special effect that simply prints the specified text (from a Renderer) at the required location.
- Parameters:
screen – The Screen being used for the Scene.
renderer – The renderer to be printed.
x – The column (x coordinate) for the start of the text. If not specified, defaults to centring the text on screen.
y – The line (y coordinate) for the start of the text.
colour – The foreground colour to use for the text.
attr – The colour attribute to use for the text.
bg – The background colour to use for the text.
clear – Whether to clear the text before stopping.
transparent – Whether to print spaces (and so be able to overlay other Effects). If False, this will redraw all characters and so replace any Effect underneath it.
speed – The refresh rate in frames between updates.
Note that a speed of 1 will force the Screen to redraw the Effect every frame update, while a value of 0 will redraw on demand - i.e. will redraw every time that an update is required by another Effect.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.RandomNoise(screen, signal=None, jitter=6, **kwargs)¶
Bases:
Effect
White noise effect - like an old analogue TV set that isn’t quite tuned right. If desired, a signal image (from a renderer) can be specified that will appear from the noise.
- Parameters:
screen – The Screen being used for the Scene.
signal – The renderer to use as the ‘signal’ in the white noise.
jitter – The amount that the signal will jump when there is noise.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Scroll(screen, rate, **kwargs)¶
Bases:
Effect
Special effect to scroll the screen up at a required rate. Since the Screen has a limited size and will not wrap, ensure that it is large enough to Scroll for the desired time.
- Parameters:
screen – The Screen being used for the Scene.
rate – How many frames to wait between scrolling the screen.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Snow(screen, **kwargs)¶
Bases:
Effect
Settling snow effect.
- Parameters:
screen – The Screen being used for the Scene.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Sprite(screen, renderer_dict, path, colour=7, clear=True, speed=2, **kwargs)¶
Bases:
Effect
An animated character capable of following a path around the screen.
- Parameters:
screen – The Screen being used for the Scene.
renderer_dict – A dictionary of Renderers to use for displaying the Sprite.
path – The Path for the Sprite to follow.
colour – The colour to use to render the Sprite.
clear – Whether to clear out old images or leave a trail.
speed – The refresh rate in frames between updates.
Note that a speed of 1 will force the Screen to redraw the Effect every frame update, while a value of 0 will redraw on demand - i.e. will redraw every time that an update is required by another Effect.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- last_position()¶
Returns the last position of this Sprite as a tuple (x, y, width, height).
- overlaps(other, use_new_pos=False)¶
Check whether this Sprite overlaps another.
- Parameters:
other – The other Sprite to check for an overlap.
use_new_pos – Whether to use latest position (due to recent update). Defaults to False.
- Returns:
True if the two Sprites overlap.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Stars(screen, count, pattern='..+.. ...x... ...*... ', **kwargs)¶
Bases:
Effect
Add random stars to the screen and make them twinkle.
- Parameters:
screen – The Screen being used for the Scene.
count – The number of starts to create.
pattern – The string pattern for the stars to loop through
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.effects.Wipe(screen, bg=0, **kwargs)¶
Bases:
Effect
Wipe the screen down from top to bottom.
- Parameters:
screen – The Screen being used for the Scene.
bg – Optional background colour to use for the wipe.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- asciimatics.effects.random() x in the interval [0, 1). ¶
asciimatics.event module¶
This module defines basic input events. For more details, see http://asciimatics.readthedocs.io/en/latest/.html
- class asciimatics.event.Event¶
Bases:
object
A class to hold information about an input event.
The exact contents varies from event to event. See specific classes for more information.
- class asciimatics.event.KeyboardEvent(key_code)¶
Bases:
Event
An event that represents a key press.
Its key field is the key_code. This is the ordinal representation of the key (taking into account keyboard state - e.g. caps lock) if possible, or an extended key code (the KEY_xxx constants in the
Screen
class) where not.- Parameters:
key_code – the ordinal value of the key that was pressed.
- class asciimatics.event.MouseEvent(x, y, buttons)¶
Bases:
Event
An event that represents a mouse move or click.
Allowed values for the buttons are any bitwise combination of LEFT_CLICK, RIGHT_CLICK and DOUBLE_CLICK.
- Parameters:
x – The X coordinate of the mouse event.
y – The Y coordinate of the mouse event.
buttons – A bitwise flag for any mouse buttons that were pressed (if any).
asciimatics.exceptions module¶
This module defines the exceptions used by asciimatics.
- exception asciimatics.exceptions.Highlander¶
Bases:
Exception
There can be only one Layout or Widget with certain options set (designed to fill the rest of the screen). If you hit this exception you have a bug in your application.
If you don’t get the name, take a look at this link.
- add_note()¶
Exception.add_note(note) – add a note to the exception
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception asciimatics.exceptions.InvalidFields(fields)¶
Bases:
Exception
When saving data from a Frame, you can ask the Frame to validate the data before saving. This is the exception that gets thrwn if any invalid data is found.
- Parameters:
fields – The list of the fields that are invalid.
- add_note()¶
Exception.add_note(note) – add a note to the exception
- property fields¶
The list of fields that are invalid.
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception asciimatics.exceptions.NextScene(name=None)¶
Bases:
Exception
Any component can raise this exception to tell Asciimatics to move to the next Scene being played. Only effective inside Screen.play().
- Parameters:
name – Next Scene to invoke. Defaults to next in the list.
- add_note()¶
Exception.add_note(note) – add a note to the exception
- property name¶
The name of the next Scene to invoke.
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception asciimatics.exceptions.ResizeScreenError(message, scene=None)¶
Bases:
Exception
Asciimatics raises this Exception if the terminal is resized while playing a Scene (and the Screen has been told not to ignore a resizing event).
- Parameters:
message – Error message for this exception.
scene – Scene that was active at time of resize.
- add_note()¶
Exception.add_note(note) – add a note to the exception
- property scene¶
The Scene that was running when the Screen resized.
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
- exception asciimatics.exceptions.StopApplication(message)¶
Bases:
Exception
Any component can raise this exception to tell Asciimatics to stop running. If playing a Scene (i.e. inside Screen.play()) the Screen will return to the calling function. When used at any other time, the exception will need to be caught by the application using Asciimatics.
- Parameters:
message – Error message for this exception.
- add_note()¶
Exception.add_note(note) – add a note to the exception
- with_traceback()¶
Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
asciimatics.parsers module¶
This module provides parsers to create ColouredText objects from embedded control strings.
- class asciimatics.parsers.AnsiTerminalParser¶
Bases:
Parser
Parser to handle ANSI terminal escape codes.
Initialize the parser.
- CHANGE_COLOURS = 1¶
Command to change active colour tuple. Parameters are the 3-tuple of (fg, attr, bg)
- CLEAR_SCREEN = 8¶
Clear the screen. No parameters.
- DELETE_CHARS = 5¶
Command to delete next N characters from this line.
- DELETE_LINE = 4¶
Command to delete part of the current line. Params are 0, 1 and 2 for end, start, all.
- DISPLAY_TEXT = 0¶
Command to display some text. Parameter is the text to display
- MOVE_ABSOLUTE = 2¶
Command to move cursor to abs position. Parameters are (x, y) where each are absolute positions.
- MOVE_RELATIVE = 3¶
Command to move cursor to relative position. Parameters are (x, y) where each are relative positions.
- NEXT_TAB = 6¶
Next tab stop
- RESTORE_CURSOR = 10¶
Restore the cursor position. No parameters.
- SAVE_CURSOR = 9¶
Save the cursor position. No parameters.
- SHOW_CURSOR = 7¶
Set cursor visibility. Param is boolean setting True=visible
- append(text)¶
Append more text to the current text being processed.
- Parameters:
text – raw text to process.
- parse()¶
Generator to return coloured text from raw text.
Generally returns a stream of text/color tuple/offset tuples. If there is a colour update with no visible text, the first element of the tuple may be None.
- Returns:
a 3-tuple of (start offset in raw text, command to execute, parameters)
- reset(text, colours)¶
Reset the parser to analyze the supplied raw text.
- Parameters:
text – raw text to process.
colours – colour tuple to initialise the colour map.
- class asciimatics.parsers.AsciimaticsParser¶
Bases:
Parser
Parser to handle Asciimatics rendering escape strings.
Initialize the parser.
- CHANGE_COLOURS = 1¶
Command to change active colour tuple. Parameters are the 3-tuple of (fg, attr, bg)
- CLEAR_SCREEN = 8¶
Clear the screen. No parameters.
- DELETE_CHARS = 5¶
Command to delete next N characters from this line.
- DELETE_LINE = 4¶
Command to delete part of the current line. Params are 0, 1 and 2 for end, start, all.
- DISPLAY_TEXT = 0¶
Command to display some text. Parameter is the text to display
- MOVE_ABSOLUTE = 2¶
Command to move cursor to abs position. Parameters are (x, y) where each are absolute positions.
- MOVE_RELATIVE = 3¶
Command to move cursor to relative position. Parameters are (x, y) where each are relative positions.
- NEXT_TAB = 6¶
Next tab stop
- RESTORE_CURSOR = 10¶
Restore the cursor position. No parameters.
- SAVE_CURSOR = 9¶
Save the cursor position. No parameters.
- SHOW_CURSOR = 7¶
Set cursor visibility. Param is boolean setting True=visible
- append(text)¶
Append more text to the current text being processed.
- Parameters:
text – raw text to process.
- parse()¶
Generator to return coloured text from raw text.
- Returns:
a 3-tuple of (start offset in raw text, command to execute, parameters)
- reset(text, colours)¶
Reset the parser to analyze the supplied raw text.
- Parameters:
text – raw text to process.
colours – colour tuple to initialise the colour map.
- class asciimatics.parsers.ControlCodeParser¶
Bases:
Parser
Parser to replace all control codes with a readable version - e.g. “^M” for carriage return.
Initialize the parser.
- CHANGE_COLOURS = 1¶
Command to change active colour tuple. Parameters are the 3-tuple of (fg, attr, bg)
- CLEAR_SCREEN = 8¶
Clear the screen. No parameters.
- DELETE_CHARS = 5¶
Command to delete next N characters from this line.
- DELETE_LINE = 4¶
Command to delete part of the current line. Params are 0, 1 and 2 for end, start, all.
- DISPLAY_TEXT = 0¶
Command to display some text. Parameter is the text to display
- MOVE_ABSOLUTE = 2¶
Command to move cursor to abs position. Parameters are (x, y) where each are absolute positions.
- MOVE_RELATIVE = 3¶
Command to move cursor to relative position. Parameters are (x, y) where each are relative positions.
- NEXT_TAB = 6¶
Next tab stop
- RESTORE_CURSOR = 10¶
Restore the cursor position. No parameters.
- SAVE_CURSOR = 9¶
Save the cursor position. No parameters.
- SHOW_CURSOR = 7¶
Set cursor visibility. Param is boolean setting True=visible
- append(text)¶
Append more text to the current text being processed.
- Parameters:
text – raw text to process.
- parse()¶
Generator to return coloured text from raw text.
- Returns:
a 3-tuple of (start offset in raw text, command to execute, parameters)
- reset(text, colours)¶
Reset the parser to analyze the supplied raw text.
- Parameters:
text – raw text to process.
colours – colour tuple to initialise the colour map.
- class asciimatics.parsers.Parser¶
Bases:
object
Abstract class to represent text parsers that extract colour control codes from raw text and convert them to displayable text and associated colour maps.
Initialize the parser.
- CHANGE_COLOURS = 1¶
Command to change active colour tuple. Parameters are the 3-tuple of (fg, attr, bg)
- CLEAR_SCREEN = 8¶
Clear the screen. No parameters.
- DELETE_CHARS = 5¶
Command to delete next N characters from this line.
- DELETE_LINE = 4¶
Command to delete part of the current line. Params are 0, 1 and 2 for end, start, all.
- DISPLAY_TEXT = 0¶
Command to display some text. Parameter is the text to display
- MOVE_ABSOLUTE = 2¶
Command to move cursor to abs position. Parameters are (x, y) where each are absolute positions.
- MOVE_RELATIVE = 3¶
Command to move cursor to relative position. Parameters are (x, y) where each are relative positions.
- NEXT_TAB = 6¶
Next tab stop
- RESTORE_CURSOR = 10¶
Restore the cursor position. No parameters.
- SAVE_CURSOR = 9¶
Save the cursor position. No parameters.
- SHOW_CURSOR = 7¶
Set cursor visibility. Param is boolean setting True=visible
- append(text)¶
Append more text to the current text being processed.
- Parameters:
text – raw text to process.
- abstract parse()¶
Generator to return coloured text from raw text.
Generally returns a stream of text/color tuple/offset tuples. If there is a colour update with no visible text, the first element of the tuple may be None.
- Returns:
a 3-tuple of (start offset in raw text, command to execute, parameters)
- reset(text, colours)¶
Reset the parser to analyze the supplied raw text.
- Parameters:
text – raw text to process.
colours – colour tuple to initialise the colour map.
asciimatics.particles module¶
This module implements a particle system for complex animcation effects. For more details, see http://asciimatics.readthedocs.io/en/latest/animation.html
- class asciimatics.particles.DropEmitter(screen, life_time)¶
Bases:
ParticleEmitter
Replicate the whole screen with Particles and then drop them a cell at a time.
- Parameters:
screen – The Screen being used for this particle system.
life_time – The life time of this particle system.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.DropScreen(screen, life_time, **kwargs)¶
Bases:
ParticleEffect
Drop all the text on the screen as if it was subject to gravity.
See
ParticleEffect
for details of the parameters.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.Explosion(screen, x, y, life_time, **kwargs)¶
Bases:
ParticleEffect
An explosion effect.
- Parameters:
screen – The Screen being used for the Scene.
x – The column (x coordinate) for the origin of the effect.
y – The line (y coordinate) for the origin of the effect.
life_time – The life time of the effect.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.ExplosionFlames(screen, x, y, life_time)¶
Bases:
ParticleEmitter
An explosion of flame and smoke.
- Parameters:
screen – The Screen being used for this particle system.
x – The column (x coordinate) for the origin of this explosion.
y – The line (y coordinate) for the origin of this explosion.
life_time – The life time of this explosion.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.PalmExplosion(screen, x, y, life_time, on_each=None)¶
Bases:
ParticleEmitter
A classic firework explosion into a palm shape.
- Parameters:
screen – The Screen being used for this particle system.
x – The column (x coordinate) for the origin of this explosion.
y – The line (y coordinate) for the origin of this explosion.
life_time – The life time of this explosion.
on_each – The function to call to spawn a trail.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.PalmFirework(screen, x, y, life_time, **kwargs)¶
Bases:
ParticleEffect
Classic palm shaped firework.
- Parameters:
screen – The Screen being used for the Scene.
x – The column (x coordinate) for the origin of the effect.
y – The line (y coordinate) for the origin of the effect.
life_time – The life time of the effect.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.Particle(chars, x, y, dx, dy, colours, life_time, move, next_colour=None, next_char=None, parm=None, on_create=None, on_each=None, on_destroy=None)¶
Bases:
object
A single particle in a Particle Effect.
- Parameters:
chars – String of characters to use for the particle.
x – The initial horizontal position of the particle.
y – The initial vertical position of the particle.
dx – The initial horizontal velocity of the particle.
dy – The initial vertical velocity of the particle.
colours – A list of colour tuples to use for the particle.
life_time – The life time of the particle.
move – A function which returns the next location of the particle.
next_colour – An optional function to return the next colour for the particle. Defaults to a linear progression of chars.
next_char – An optional function to return the next character for the particle. Defaults to a linear progression of colours.
parm – An optional parameter for use within any of the
on_create – An optional function to spawn new particles when this particle first is created.
on_each – An optional function to spawn new particles for every frame of this particle (other than creation/destruction).
on_destroy – An optional function to spawn new particles when this particle is destroyed.
- last()¶
The last attributes returned for this particle - typically used for clearing out the particle on the next frame. See
next()
for details of the returned results.
- next()¶
The set of attributes for this particle for the next frame to be rendered.
- Returns:
A tuple of (character, x, y, fg, attribute, bg)
- class asciimatics.particles.ParticleEffect(screen, x, y, life_time, **kwargs)¶
Bases:
Effect
An Effect that uses a
ParticleEmitter
to create the animation.To define a new ParticleEffect, you must implement the reset() method to construct a chain of ParticleEmitter objects and append them to the internal _active_systems list.
- Parameters:
screen – The Screen being used for the Scene.
x – The column (x coordinate) for the origin of the effect.
y – The line (y coordinate) for the origin of the effect.
life_time – The life time of the effect.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- abstract reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.ParticleEmitter(screen, x, y, count, new_particle, spawn, life_time, blend=False)¶
Bases:
object
An emitter for a particle system to create a set of
_Particle
objects for aParticleEffect
. After initialization, the emitter will be called once per frame to be displayed on the Screen.- Parameters:
screen – The screen to which the particle system will be rendered.
x – The x location of origin of the particle system.
y – The y location of origin of the particle system.
count – The count of new particles to spawn on each frame.
new_particle – The function to call to spawn a new particle.
spawn – The number of frames for which to spawn particles.
life_time – The life time of the whole particle system.
blend – Whether to blend particles or not. A blended system picks the colour based on the number of overlapping particles, while an unblended one picks the colour based on a the state of Each Particle individually as they are drawn. Defaults to False.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.Rain(screen, life_time, **kwargs)¶
Bases:
ParticleEffect
Rain storm effect.
See
ParticleEffect
for details of the parameters.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.RainSource(screen, life_time, on_each)¶
Bases:
ParticleEmitter
Source of the raindrops for a rain storm effect. This emits rain drops from a single line at the top of the screen (starting sufficiently off- screen to ensure that it can cover all the screen due to horizontal motion).
- Parameters:
screen – The Screen being used for this particle system.
life_time – The life time of this particle system.
on_each – Function to call on each iteration of the particle.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.RingExplosion(screen, x, y, life_time)¶
Bases:
ParticleEmitter
A classic firework explosion in a simple ring.
- Parameters:
screen – The Screen being used for this particle system.
x – The column (x coordinate) for the origin of this explosion.
y – The line (y coordinate) for the origin of this explosion.
life_time – The life time of this explosion.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.RingFirework(screen, x, y, life_time, **kwargs)¶
Bases:
ParticleEffect
Classic rocket with ring explosion.
- Parameters:
screen – The Screen being used for the Scene.
x – The column (x coordinate) for the origin of the effect.
y – The line (y coordinate) for the origin of the effect.
life_time – The life time of the effect.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.Rocket(screen, x, y, life_time, on_destroy=None)¶
Bases:
ParticleEmitter
A rocket being launched from the ground.
- Parameters:
screen – The Screen being used for this particle system.
x – The column (x coordinate) for the origin of the rocket.
y – The line (y coordinate) for the origin of the rocket.
life_time – The life time of the rocket.
on_destroy – The function to call when the rocket explodes.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.SerpentExplosion(screen, x, y, life_time)¶
Bases:
ParticleEmitter
A firework explosion where each trail changes direction.
- Parameters:
screen – The Screen being used for this particle system.
x – The column (x coordinate) for the origin of this explosion.
y – The line (y coordinate) for the origin of this explosion.
life_time – The life time of this explosion.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.SerpentFirework(screen, x, y, life_time, **kwargs)¶
Bases:
ParticleEffect
A firework where each trail changes direction.
- Parameters:
screen – The Screen being used for the Scene.
x – The column (x coordinate) for the origin of the effect.
y – The line (y coordinate) for the origin of the effect.
life_time – The life time of the effect.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.ShootScreen(screen, x, y, life_time, diameter=None, **kwargs)¶
Bases:
ParticleEffect
Shoot the screen out like a massive gunshot.
See
ParticleEffect
for details of the parameters.In addition, it is possible to set the diameter of this effect using the extra keyword parameter.
- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.ShotEmitter(screen, x, y, diameter, life_time)¶
Bases:
ParticleEmitter
Replicate the whole screen with Particles and then explode the screen from a given location.
- Parameters:
screen – The Screen being used for this particle system.
x – The x position of the origin of the explosion.
y – The y position of the origin of the explosion.
diameter – The diameter of the explosion.
life_time – The life time of this particle system.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.Splash(screen, x, y)¶
Bases:
ParticleEmitter
Splash effect for falling rain.
- Parameters:
screen – The Screen being used for this particle system.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.StarExplosion(screen, x, y, life_time, points, on_each)¶
Bases:
ParticleEmitter
A classic firework explosion to a Peony shape with trails.
- Parameters:
screen – The Screen being used for this particle system.
x – The column (x coordinate) for the origin of this explosion.
y – The line (y coordinate) for the origin of this explosion.
life_time – The life time of this explosion.
points – Number of points the explosion should have.
on_each – The function to call to spawn a trail.
- update()¶
The function to draw a new frame for the particle system.
- class asciimatics.particles.StarFirework(screen, x, y, life_time, **kwargs)¶
Bases:
ParticleEffect
Classic rocket with star explosion.
- Parameters:
screen – The Screen being used for the Scene.
x – The column (x coordinate) for the origin of the effect.
y – The line (y coordinate) for the origin of the effect.
life_time – The life time of the effect.
Also see the common keyword arguments in
Effect
.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Reset the particle effect back to its initial state. This must be implemented by the child classes.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.particles.StarTrail(screen, x, y, life_time, colour)¶
Bases:
ParticleEmitter
A trail for a
StarExplosion
.- Parameters:
screen – The Screen being used for this particle system.
x – The column (x coordinate) for the origin of this trail.
y – The line (y coordinate) for the origin of this trail.
life_time – The life time of this trail.
colour – The colour of this trail.
- update()¶
The function to draw a new frame for the particle system.
asciimatics.paths module¶
This module provides Paths to create animation effects with Sprites. For more details see http://asciimatics.readthedocs.io/en/latest/animation.html
- class asciimatics.paths.DynamicPath(screen, x, y)¶
Bases:
_AbstractPath
Class to create a dynamic path that reacts to events
The Screen will reset() the Path before iterating through each position using next_pos() and checking whether it has reached the end using is_finished().
To implement a DynamicPath, override the
process_event()
method to react to any user input.- is_finished()¶
- Returns:
Whether this path has got to the end.
- next_pos()¶
- Returns:
The next position tuple (x, y) for the Sprite on this path.
- abstract process_event(event)¶
Process any mouse event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- reset()¶
Reset the Path for use next time.
- class asciimatics.paths.Path¶
Bases:
_AbstractPath
Class to record and play back the motion of a Sprite.
The Screen will reset() the Path before iterating through each position using next_pos() and checking whether it has reached the end using is_finished().
To define a Path, use the methods to jump to a location, wait or move between points.
- is_finished()¶
- Returns:
Whether this path has got to the end.
- jump_to(x, y)¶
Jump straight to the newly specified location - i.e. teleport there and don’t create a path to get there.
- Parameters:
x – X coord for the end position.
y – Y coord for the end position.
- move_round_to(points, steps)¶
Follow a path pre-defined by a set of at least 4 points. This Path will interpolate the points into a curve and follow that curve.
- Parameters:
points – The list of points that defines the path.
steps – The number of steps to take to follow the path.
- move_straight_to(x, y, steps)¶
Move straight to the newly specified location - i.e. create a straight line Path from the current location to the specified point.
- Parameters:
x – X coord for the end position.
y – Y coord for the end position.
steps – How many steps to take for the move.
- next_pos()¶
- Returns:
The next position tuple (x, y) for the Sprite on this path.
- reset()¶
Reset the Path for use next time.
- wait(delay)¶
Wait at the current location for the specified number of iterations.
- Parameters:
delay – The time to wait (in animation frames).
asciimatics.scene module¶
This module defines Scene objects for animation purposes. For more details, see http://asciimatics.readthedocs.io/en/latest/animation.html
- class asciimatics.scene.Scene(effects, duration=0, clear=True, name=None)¶
Bases:
object
Class to store the details of a single scene to be displayed. This is made up of a set of
Effect
objects. See the documentation for Effect to understand the interaction between the two classes and http://asciimatics.readthedocs.io/en/latest/animation.html for how to use them together.- Parameters:
effects – The list of effects to apply to this scene.
duration – The number of frames in this Scene. A value of 0 means that the Scene should query the Effects to find the duration. A value of -1 means don’t stop.
clear – Whether to clear the Screen at the start of the Scene.
name – Optional name to identify the scene.
- add_effect(effect, reset=True)¶
Add an effect to the Scene.
This method can be called at any time - even when playing the Scene. The default logic assumes that the Effect needs to be reset before being displayed. This can be overridden using the reset parameter.
- Parameters:
effect – The Effect to be added.
reset – Whether to reset the Effect that has just been added.
- property clear¶
- Returns:
Whether the Scene should clear at the start.
- property duration¶
- Returns:
The length of the scene in frames.
- property effects¶
- Returns:
The list of Effects in this Scene.
- exit()¶
Handle any tidy up required on the exit of the Scene.
- property name¶
- Returns:
The name of this Scene. May be None.
- process_event(event)¶
Process a new input event.
This method will pass the event on to any Effects in reverse Z order so that the top-most Effect has priority.
- Parameters:
event – The Event that has been triggered.
- Returns:
None if the Scene processed the event, else the original event.
- remove_effect(effect)¶
Remove an effect from the scene.
- Parameters:
effect – The effect to remove.
- reset(old_scene=None, screen=None)¶
Reset the scene ready for playing.
- Parameters:
old_scene – The previous version of this Scene that was running before the application reset - e.g. due to a screen resize.
screen – New screen to use if old_scene is not None.
asciimatics.screen module¶
This module defines common screen output function. For more details, see http://asciimatics.readthedocs.io/en/latest/io.html
- class asciimatics.screen.Canvas(screen, height, width, x=None, y=None)¶
Bases:
_AbstractCanvas
A Canvas is an object that can be used to draw to the screen. It maintains its own buffer that will be flushed to the screen when refresh() is called.
- Parameters:
screen – The underlying Screen that will be drawn to on refresh.
height – The height of the screen buffer to be used.
width – The width of the screen buffer to be used.
x – The x position for the top left corner of the Canvas.
y – The y position for the top left corner of the Canvas.
If either of the x or y positions is not set, the Canvas will default to centring within the current Screen for that location.
- block_transfer(buffer, x, y)¶
Copy a buffer to the screen double buffer at a specified location.
- Parameters:
buffer – The double buffer to copy
x – The X origin for where to place it in the Screen
y – The Y origin for where to place it in the Screen
- centre(text, y, colour=7, attr=0, colour_map=None)¶
Centre the text on the specified line (y) using the optional colour and attributes.
- Parameters:
text – The (single line) text to be printed.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
colour_map – Colour/attribute list for multi-colour text.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.
- clear_buffer(fg, attr, bg, x=0, y=0, w=None, h=None)¶
Clear a box in the current double-buffer used by this object.
This is the recommended way to clear parts, or all, ofthe Screen without causing flicker as it will only become visible at the next refresh. Defaults to the whole buffer if no box is specified.
- Parameters:
fg – The foreground colour to use for the new buffer.
attr – The attribute value to use for the new buffer.
bg – The background colour to use for the new buffer.
x – Optional X coordinate for top left of box.
y – Optional Y coordinate for top left of box.
w – Optional width of the box.
h – Optional height of the box.
- property dimensions¶
- Returns:
The full dimensions of the canvas as a (height, width) tuple.
- draw(x, y, char=None, colour=7, bg=0, thin=False)¶
Draw a line from drawing cursor to the specified position.
This uses a modified Bressenham algorithm, interpolating twice as many points to render down to anti-aliased characters when no character is specified, or uses standard algorithm plotting with the specified character.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
char – Optional character to use to draw the line.
colour – Optional colour for plotting the line.
bg – Optional background colour for plotting the line.
thin – Optional width of anti-aliased line.
- fill_polygon(polygons, colour=7, bg=0)¶
Draw a filled polygon.
This function uses the scan line algorithm to create the polygon. See https://www.cs.uic.edu/~jbell/CourseNotes/ComputerGraphics/PolygonFilling.html for details.
- Parameters:
polygons – A list of polygons (which are each a list of (x,y) coordinates for the points of the polygon) - i.e. nested list of 2-tuples.
colour – The foreground colour to use for the polygon
bg – The background colour to use for the polygon
- get_from(x, y)¶
Get the character at the specified location.
- Parameters:
x – The column (x coord) of the character.
y – The row (y coord) of the character.
- Returns:
A 4-tuple of (ascii code, foreground, attributes, background) for the character at the location.
- highlight(x, y, w, h, fg=None, bg=None, blend=100)¶
Highlight a specified section of the screen.
- Parameters:
x – The column (x coord) for the start of the highlight.
y – The line (y coord) for the start of the highlight.
w – The width of the highlight (in characters).
h – The height of the highlight (in characters).
fg – The foreground colour of the highlight.
bg – The background colour of the highlight.
blend – How much (as a percentage) to take of the new colour when blending.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. If fg or bg are None that means don’t change the foreground/background as appropriate.
- is_visible(x, y)¶
Return whether the specified location is on the visible screen.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
- move(x, y)¶
Move the drawing cursor to the specified position.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
- property origin¶
The location of top left corner of the canvas on the Screen.
- Returns:
A tuple (x, y) of the location
- paint(text, x, y, colour=7, attr=0, bg=0, transparent=False, colour_map=None)¶
Paint multi-colour text at the defined location.
- Parameters:
text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The default colour of the text to be displayed.
attr – The default cell attribute of the text to be displayed.
bg – The default background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
colour_map – Colour/attribute list for multi-colour text.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. colour_map is a list of tuples (foreground, attribute, background) that must be the same length as the passed in text (or None if no mapping is required).
- property palette¶
- Returns:
A palette compatible with the PIL.
- print_at(text, x, y, colour=7, attr=0, bg=0, transparent=False)¶
Print the text at the specified location using the specified colour and attributes.
- Parameters:
text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
bg – The background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.
- refresh()¶
Flush the canvas content to the underlying screen.
- reset()¶
Reset the internal buffers for the abstract canvas.
- scroll(lines=1)¶
Scroll the abstract canvas up one line.
- Parameters:
lines – The number of lines to scroll. Defaults to down by one.
- scroll_to(line)¶
Scroll the abstract canvas to make a specific line.
- Parameters:
line – The line to scroll to.
- property start_line¶
- Returns:
The start line of the top of the canvas.
- property unicode_aware¶
- Returns:
Whether unicode input/output is supported or not.
- class asciimatics.screen.ManagedScreen(func=<function ManagedScreen.<lambda>>)¶
Bases:
object
Decorator and class to create a managed Screen. It can be used in two ways. If used as a method decorator it will create and open a new Screen, pass the screen to the method as a keyword argument, and close the screen when the method has completed. If used with the with statement the class will create and open a new Screen, return the screen for using in the block, and close the screen when the statement ends. Note that any arguments are in this class so that you can use it as a decorator or using the with statment. No arguments are required to use.
- Parameters:
func – The function to call once the Screen has been created.
- class asciimatics.screen.Screen(height, width, buffer_height, unicode_aware)¶
Bases:
_AbstractCanvas
Class to track basic state of the screen. This constructs the necessary resources to allow us to do the ASCII animations.
This is an abstract class that will build the correct concrete class for you when you call
wrapper()
. If needed, you can use theopen()
andclose()
methods for finer grained control of the construction and tidy up.Note that you need to define the required height for your screen buffer. This is important if you plan on using any Effects that will scroll the screen vertically (e.g. Scroll). It must be big enough to handle the full scrolling of your selected Effect.
Don’t call this constructor directly.
- block_transfer(buffer, x, y)¶
Copy a buffer to the screen double buffer at a specified location.
- Parameters:
buffer – The double buffer to copy
x – The X origin for where to place it in the Screen
y – The Y origin for where to place it in the Screen
- centre(text, y, colour=7, attr=0, colour_map=None)¶
Centre the text on the specified line (y) using the optional colour and attributes.
- Parameters:
text – The (single line) text to be printed.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
colour_map – Colour/attribute list for multi-colour text.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.
- clear()¶
Clear the Screen of all content.
Note that this will instantly clear the Screen and reset all buffers to the default state, without waiting for you to call
refresh()
. It is designed for use once at the start of your application to reset all buffers and the screen to a known state.If you want to clear parts, or all, of the Screen inside your application without any flicker, use
clear_buffer()
instead.
- clear_buffer(fg, attr, bg, x=0, y=0, w=None, h=None)¶
Clear a box in the current double-buffer used by this object.
This is the recommended way to clear parts, or all, ofthe Screen without causing flicker as it will only become visible at the next refresh. Defaults to the whole buffer if no box is specified.
- Parameters:
fg – The foreground colour to use for the new buffer.
attr – The attribute value to use for the new buffer.
bg – The background colour to use for the new buffer.
x – Optional X coordinate for top left of box.
y – Optional Y coordinate for top left of box.
w – Optional width of the box.
h – Optional height of the box.
- abstract close(restore=True)¶
Close down this Screen and tidy up the environment as required.
- Parameters:
restore – whether to restore the environment or not.
- static ctrl(char)¶
Calculate the control code for a given key. For example, this converts “a” to 1 (which is the code for ctrl-a).
- Parameters:
char – The key to convert to a control code.
- Returns:
The control code as an integer or None if unknown.
- property current_scene¶
- Returns:
The scene currently being rendered. To be used in conjunction with
draw_next_frame()
.
- property dimensions¶
- Returns:
The full dimensions of the canvas as a (height, width) tuple.
- draw(x, y, char=None, colour=7, bg=0, thin=False)¶
Draw a line from drawing cursor to the specified position.
This uses a modified Bressenham algorithm, interpolating twice as many points to render down to anti-aliased characters when no character is specified, or uses standard algorithm plotting with the specified character.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
char – Optional character to use to draw the line.
colour – Optional colour for plotting the line.
bg – Optional background colour for plotting the line.
thin – Optional width of anti-aliased line.
- draw_next_frame(repeat=True)¶
Draw the next frame in the currently configured Scenes. You must call
set_scenes()
before using this for the first time.- Parameters:
repeat – Whether to repeat the Scenes once it has reached the end. Defaults to True.
- Raises:
StopApplication – if the application should be terminated.
- fill_polygon(polygons, colour=7, bg=0)¶
Draw a filled polygon.
This function uses the scan line algorithm to create the polygon. See https://www.cs.uic.edu/~jbell/CourseNotes/ComputerGraphics/PolygonFilling.html for details.
- Parameters:
polygons – A list of polygons (which are each a list of (x,y) coordinates for the points of the polygon) - i.e. nested list of 2-tuples.
colour – The foreground colour to use for the polygon
bg – The background colour to use for the polygon
- force_update(full_refresh=False)¶
Force the Screen to redraw the current Scene on the next call to draw_next_frame, overriding the frame_update_count value for all the Effects.
- Parameters:
full_refresh – if True force the whole screen to redraw.
- abstract get_event()¶
Check for any events (e.g. key-press or mouse movement) without waiting.
- Returns:
A
Event
object if anything was detected, otherwise it returns None.
- get_from(x, y)¶
Get the character at the specified location.
- Parameters:
x – The column (x coord) of the character.
y – The row (y coord) of the character.
- Returns:
A 4-tuple of (ascii code, foreground, attributes, background) for the character at the location.
- get_key()¶
Check for a key without waiting. This method is deprecated. Use
get_event()
instead.
- getch(x, y)¶
Get the character at a specified location. This method is deprecated. Use
get_from()
instead.- Parameters:
x – The x coordinate.
y – The y coordinate.
- abstract has_resized()¶
Check whether the screen has been re-sized.
- Returns:
True when the screen has been re-sized since the last check.
- highlight(x, y, w, h, fg=None, bg=None, blend=100)¶
Highlight a specified section of the screen.
- Parameters:
x – The column (x coord) for the start of the highlight.
y – The line (y coord) for the start of the highlight.
w – The width of the highlight (in characters).
h – The height of the highlight (in characters).
fg – The foreground colour of the highlight.
bg – The background colour of the highlight.
blend – How much (as a percentage) to take of the new colour when blending.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. If fg or bg are None that means don’t change the foreground/background as appropriate.
- is_visible(x, y)¶
Return whether the specified location is on the visible screen.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
- move(x, y)¶
Move the drawing cursor to the specified position.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
- classmethod open(height=None, catch_interrupt=False, unicode_aware=None)¶
Construct a new Screen for any platform. This will just create the correct Screen object for your environment. See
wrapper()
for a function to create and tidy up once you’ve finished with the Screen.- Parameters:
height – The buffer height for this window (for testing only).
catch_interrupt – Whether to catch and prevent keyboard interrupts. Defaults to False to maintain backwards compatibility.
unicode_aware – Whether the application can use unicode or not. If None, try to detect from the environment if UTF-8 is enabled.
- paint(text, x, y, colour=7, attr=0, bg=0, transparent=False, colour_map=None)¶
Paint multi-colour text at the defined location.
- Parameters:
text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The default colour of the text to be displayed.
attr – The default cell attribute of the text to be displayed.
bg – The default background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
colour_map – Colour/attribute list for multi-colour text.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. colour_map is a list of tuples (foreground, attribute, background) that must be the same length as the passed in text (or None if no mapping is required).
- property palette¶
- Returns:
A palette compatible with the PIL.
- play(scenes, stop_on_resize=False, unhandled_input=None, start_scene=None, repeat=True, allow_int=False)¶
Play a set of scenes.
This is effectively a helper function to wrap
set_scenes()
anddraw_next_frame()
to simplify animation for most applications.- Parameters:
scenes – a list of
Scene
objects to play.stop_on_resize – Whether to stop when the screen is resized. Default is to carry on regardless - which will typically result in an error. This is largely done for back-compatibility.
unhandled_input – Function to call for any input not handled by the Scenes/Effects being played. Defaults to a function that closes the application on “Q” or “X” being pressed.
start_scene – The old Scene to start from. This must have name that matches the name of one of the Scenes passed in.
repeat – Whether to repeat the Scenes once it has reached the end. Defaults to True.
allow_int – Allow input to interrupt frame rate delay.
- Raises:
ResizeScreenError – if the screen is resized (and allowed by stop_on_resize).
The unhandled input function just takes one parameter - the input event that was not handled.
- print_at(text, x, y, colour=7, attr=0, bg=0, transparent=False)¶
Print the text at the specified location using the specified colour and attributes.
- Parameters:
text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
bg – The background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.
- putch(text, x, y, colour=7, attr=0, bg=0, transparent=False)¶
Print text at the specified location. This method is deprecated. Use
print_at()
instead.- Parameters:
text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
bg – The background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
- refresh()¶
Refresh the screen.
- reset()¶
Reset the internal buffers for the abstract canvas.
- scroll(lines=1)¶
Scroll the abstract canvas up one line.
- Parameters:
lines – The number of lines to scroll. Defaults to down by one.
- scroll_to(line)¶
Scroll the abstract canvas to make a specific line.
- Parameters:
line – The line to scroll to.
- set_scenes(scenes, unhandled_input=None, start_scene=None)¶
Remember a set of scenes to be played. This must be called before using
draw_next_frame()
.- Parameters:
scenes – a list of
Scene
objects to play.unhandled_input – Function to call for any input not handled by the Scenes/Effects being played. Defaults to a function that closes the application on “Q” or “X” being pressed.
start_scene – The old Scene to start from. This must have name that matches the name of one of the Scenes passed in.
- Raises:
ResizeScreenError – if the screen is resized (and allowed by stop_on_resize).
The unhandled input function just takes one parameter - the input event that was not handled.
- abstract set_title(title)¶
Set the title for this terminal/console session. This will typically change the text displayed in the window title bar.
- Parameters:
title – The title to be set.
- property start_line¶
- Returns:
The start line of the top of the canvas.
- property unicode_aware¶
- Returns:
Whether unicode input/output is supported or not.
- abstract wait_for_input(timeout)¶
Wait until there is some input or the timeout is hit.
- Parameters:
timeout – Time to wait for input in seconds (floating point).
- classmethod wrapper(func, height=None, catch_interrupt=False, arguments=None, unicode_aware=None)¶
Construct a new Screen for any platform. This will initialize the Screen, call the specified function and then tidy up the system as required when the function exits.
- Parameters:
func – The function to call once the Screen has been created.
height – The buffer height for this Screen (only for test purposes).
catch_interrupt – Whether to catch and prevent keyboard interrupts. Defaults to False to maintain backwards compatibility.
arguments – Optional arguments list to pass to func (after the Screen object).
unicode_aware – Whether the application can use unicode or not. If None, try to detect from the environment if UTF-8 is enabled.
- class asciimatics.screen.TemporaryCanvas(height, width)¶
Bases:
_AbstractCanvas
A TemporaryCanvas is an object that can only be used to draw to a buffer.
This class is desigend purely for use by dynamic renderers and so ignores some features of a full Canvas - most notably the screen related fhnction (e.g. the screen buffer and related properties).
- Parameters:
height – The height of the screen buffer to be used.
width – The width of the screen buffer to be used.
- block_transfer(buffer, x, y)¶
Copy a buffer to the screen double buffer at a specified location.
- Parameters:
buffer – The double buffer to copy
x – The X origin for where to place it in the Screen
y – The Y origin for where to place it in the Screen
- centre(text, y, colour=7, attr=0, colour_map=None)¶
Centre the text on the specified line (y) using the optional colour and attributes.
- Parameters:
text – The (single line) text to be printed.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
colour_map – Colour/attribute list for multi-colour text.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.
- clear_buffer(fg, attr, bg, x=0, y=0, w=None, h=None)¶
Clear a box in the current double-buffer used by this object.
This is the recommended way to clear parts, or all, ofthe Screen without causing flicker as it will only become visible at the next refresh. Defaults to the whole buffer if no box is specified.
- Parameters:
fg – The foreground colour to use for the new buffer.
attr – The attribute value to use for the new buffer.
bg – The background colour to use for the new buffer.
x – Optional X coordinate for top left of box.
y – Optional Y coordinate for top left of box.
w – Optional width of the box.
h – Optional height of the box.
- property dimensions¶
- Returns:
The full dimensions of the canvas as a (height, width) tuple.
- draw(x, y, char=None, colour=7, bg=0, thin=False)¶
Draw a line from drawing cursor to the specified position.
This uses a modified Bressenham algorithm, interpolating twice as many points to render down to anti-aliased characters when no character is specified, or uses standard algorithm plotting with the specified character.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
char – Optional character to use to draw the line.
colour – Optional colour for plotting the line.
bg – Optional background colour for plotting the line.
thin – Optional width of anti-aliased line.
- fill_polygon(polygons, colour=7, bg=0)¶
Draw a filled polygon.
This function uses the scan line algorithm to create the polygon. See https://www.cs.uic.edu/~jbell/CourseNotes/ComputerGraphics/PolygonFilling.html for details.
- Parameters:
polygons – A list of polygons (which are each a list of (x,y) coordinates for the points of the polygon) - i.e. nested list of 2-tuples.
colour – The foreground colour to use for the polygon
bg – The background colour to use for the polygon
- get_from(x, y)¶
Get the character at the specified location.
- Parameters:
x – The column (x coord) of the character.
y – The row (y coord) of the character.
- Returns:
A 4-tuple of (ascii code, foreground, attributes, background) for the character at the location.
- highlight(x, y, w, h, fg=None, bg=None, blend=100)¶
Highlight a specified section of the screen.
- Parameters:
x – The column (x coord) for the start of the highlight.
y – The line (y coord) for the start of the highlight.
w – The width of the highlight (in characters).
h – The height of the highlight (in characters).
fg – The foreground colour of the highlight.
bg – The background colour of the highlight.
blend – How much (as a percentage) to take of the new colour when blending.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. If fg or bg are None that means don’t change the foreground/background as appropriate.
- is_visible(x, y)¶
Return whether the specified location is on the visible screen.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
- move(x, y)¶
Move the drawing cursor to the specified position.
- Parameters:
x – The column (x coord) for the location to check.
y – The line (y coord) for the location to check.
- paint(text, x, y, colour=7, attr=0, bg=0, transparent=False, colour_map=None)¶
Paint multi-colour text at the defined location.
- Parameters:
text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The default colour of the text to be displayed.
attr – The default cell attribute of the text to be displayed.
bg – The default background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
colour_map – Colour/attribute list for multi-colour text.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class. colour_map is a list of tuples (foreground, attribute, background) that must be the same length as the passed in text (or None if no mapping is required).
- property palette¶
- Returns:
A palette compatible with the PIL.
- print_at(text, x, y, colour=7, attr=0, bg=0, transparent=False)¶
Print the text at the specified location using the specified colour and attributes.
- Parameters:
text – The (single line) text to be printed.
x – The column (x coord) for the start of the text.
y – The line (y coord) for the start of the text.
colour – The colour of the text to be displayed.
attr – The cell attribute of the text to be displayed.
bg – The background colour of the text to be displayed.
transparent – Whether to print spaces or not, thus giving a transparent effect.
The colours and attributes are the COLOUR_xxx and A_yyy constants defined in the Screen class.
- refresh()¶
Refresh this object - this will draw to the underlying display interface.
- reset()¶
Reset the internal buffers for the abstract canvas.
- scroll(lines=1)¶
Scroll the abstract canvas up one line.
- Parameters:
lines – The number of lines to scroll. Defaults to down by one.
- scroll_to(line)¶
Scroll the abstract canvas to make a specific line.
- Parameters:
line – The line to scroll to.
- property start_line¶
- Returns:
The start line of the top of the canvas.
- property unicode_aware¶
- Returns:
Whether unicode input/output is supported or not.
asciimatics.sprites module¶
This module provides Sprites to create animation effects with Paths. For more details see http://asciimatics.readthedocs.io/en/latest/animation.html
- class asciimatics.sprites.Arrow(screen, path, colour=7, start_frame=0, stop_frame=0)¶
Bases:
Sprite
Sample arrow sprite - points where it is going.
See
Sprite
for details.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- last_position()¶
Returns the last position of this Sprite as a tuple (x, y, width, height).
- overlaps(other, use_new_pos=False)¶
Check whether this Sprite overlaps another.
- Parameters:
other – The other Sprite to check for an overlap.
use_new_pos – Whether to use latest position (due to recent update). Defaults to False.
- Returns:
True if the two Sprites overlap.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.sprites.Plot(screen, path, colour=7, start_frame=0, stop_frame=0)¶
Bases:
Sprite
Sample Sprite that simply plots an “X” for each step in the path. Useful for plotting a path to the screen.
See
Sprite
for details.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- last_position()¶
Returns the last position of this Sprite as a tuple (x, y, width, height).
- overlaps(other, use_new_pos=False)¶
Check whether this Sprite overlaps another.
- Parameters:
other – The other Sprite to check for an overlap.
use_new_pos – Whether to use latest position (due to recent update). Defaults to False.
- Returns:
True if the two Sprites overlap.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
- class asciimatics.sprites.Sam(screen, path, start_frame=0, stop_frame=0)¶
Bases:
Sprite
Sam Paul sprite - an simple sample animated character.
See
Sprite
for details.- property delete_count¶
The number of frames before this Effect should be deleted.
- property frame_update_count¶
The number of frames before this Effect should be updated.
Increasing this number potentially reduces the CPU load of a Scene (if no other Effect needs to be scheduled sooner), but can affect perceived responsiveness of the Scene if it is too long. Handle with care!
A value of 0 means refreshes are not required beyond a response to an input event. It defaults to 1 for all Effects.
- last_position()¶
Returns the last position of this Sprite as a tuple (x, y, width, height).
- overlaps(other, use_new_pos=False)¶
Check whether this Sprite overlaps another.
- Parameters:
other – The other Sprite to check for an overlap.
use_new_pos – Whether to use latest position (due to recent update). Defaults to False.
- Returns:
True if the two Sprites overlap.
- process_event(event)¶
Process any input event.
- Parameters:
event – The event that was triggered.
- Returns:
None if the Effect processed the event, else the original event.
- register_scene(scene)¶
Register the Scene that owns this Effect.
- Parameters:
scene – The Scene to be registered
- reset()¶
Function to reset the effect when replaying the scene.
- property safe_to_default_unhandled_input¶
Whether it is safe to use the default handler for any unhandled input from this Effect.
A value of False means that asciimatics should not use the default handler. This is typically the case for Frames.
- property scene¶
The Scene that owns this Effect.
- property screen¶
The Screen that will render this Effect.
- property stop_frame¶
Last frame for this effect. A value of zero means no specific end.
- update(frame_no)¶
Process the animation effect for the specified frame number.
- Parameters:
frame_no – The index of the frame being generated.
asciimatics.strings module¶
This module provides classes to handle embedded control strings for widgets.
- class asciimatics.strings.ColouredText(raw_text, parser, colour=None, colour_map=None, offsets=None, text=None)¶
Bases:
object
Unicode string-like object to store text and colour maps, using a parser to convert the raw text passed in into visible text and an associated colour map. This only handles simple colour change commands and will ignore more complex commands).
- Parameters:
raw_text – The raw unicode string to be processed
parser – The parser to process the text
colour – Optional starting colour tuple to use for this text.
colour_map – Optional ready parsed colour map for this text.
offsets – Optional ready parsed offsets for this text.
text – Optional ready parsed text for this text.
The colour_map, offsets and text options are to optimize creation of substrings from an existing ColouredText object and should not be used in general.
- property colour_map¶
Colour map for the processed text (for use with paint method).
- property first_colour¶
First colour triplet used for this text.
- join(others)¶
Join the list of ColouredObjects using this ColouredObject.
- Parameters:
others – the list of other objects to join.
- property last_colour¶
Last colour triplet used for this text.
- property raw_text¶
Raw (unprocessed) text for this object.
- startswith(text)¶
Check whether parsed (i.e. displayed) text starts woth specified string.
asciimatics.utilities module¶
This module is just a collection of simple helper functions.
- class asciimatics.utilities.BoxTool(unicode_aware, style=1)¶
Bases:
object
Tool for building boxes out of characters.
Supports a variety of line styles from asciimatics.constants:
ASCII_LINE
– ASCII safe characters (0)SINGLE_LINE
– Unicode based single lined box (1)DOUBLE_LINE
– Unicode based double lined box (2)
Individual characters of a box can be accessed directly through attributes. Most attribute names are based on the Extended-ASCII characters used for the UNICODE version of the shape. The names describe the directions the piece point in (not the part of the box). For example, “up_left” is a corner piece that has a part that points up and a part that points left – the character usually used for the bottom right hand corner of a box.
Attribute values are:
up_left
– corner piece facing up and leftup_right
– corner piece facing up and rightdown_left
– corner piece facing down and leftdown_right
– corner piece facing down and righth
– horizontal linev
– vertical linev_inside
– vertical line used inside the gridv_left
– vertical line with mid joiner facing to the leftv_right
– vertical line with mid joiner facing to the righth_up
– horizontal line with a mid joiner facing uph_down
– horizontal line with a mid joiner facing downcross
– intersection between vertical and horizontal
- Parameters:
unicode_aware – boolean indicating if the terminal is Unicode aware. If False, will force the use of the ASCII style
style – line style specifier. Supports
ASCII_LINE
,SINGLE_LINE
, andDOUBLE_LINE
. Defaults toSINGLE_LINE
.
- box(width, height)¶
Returns a string containing a box with the given width and height.
- box_bottom(width)¶
Returns a string containing the bottom border of a box
- Parameters:
width – width of box, including corners
- box_line(width)¶
Returns a string with a vertical bar on each end, padded with spaces in between for the given width.
- Parameters:
width – width of box including sides
- box_top(width)¶
Returns a string containing the top border of a box
- Parameters:
width – width of box, including corners
- property style¶
The line drawing style used to draw boxes. Possible styles are set in
asciimatics.constants
.- Parameters:
style – One of
ASCII_LINE
,SINGLE_LINE
, orDOUBLE_LINE
- asciimatics.utilities.readable_mem(mem)¶
- Parameters:
mem – An integer number of bytes to convert to human-readable form.
- Returns:
A human-readable string representation of the number.
- asciimatics.utilities.readable_timestamp(stamp)¶
- Parameters:
stamp – A floating point number representing the POSIX file timestamp.
- Returns:
A short human-readable string representation of the timestamp.
asciimatics.version module¶
Module contents¶
Asciimatics is a package to help people create full-screen text UIs (from interactive forms to ASCII animations) on any platform. It is licensed under the Apache Software Foundation License 2.0.