History

class pygamelib.base.History

Bases: object

New in version 1.4.0.

History is a general history management object. It works by managing a time structure with past, current and future actions. Undoing and redoing is simply the action of moving along this timeline.

This object is data agnostic, it can be used with any type of objects. Internally, it uses a concept of “actions”. An “action” consist of any python object that can be stored in an array.

Undoing or redoing over the limit of the past and future actions is not doing anything.

When add() is called, it clears the future actions.

This object provides a singleton interface through the instance(). It can be created as a normal instantiated object or as a global manager depending on your needs.

Example:

global_history = History.instance()
global_history.add('Hel')
global_history.add('Hello')
global_history.add('Hello Wo')
global_history.add('Hello World')
print(global_history.current)  # print "Hello World"
global_history.undo()
print(global_history.current)  # print "Hello Wo"
global_history.undo()
print(global_history.current)  # print "Hello"
global_history.redo()
global_history.redo()
global_history.redo() # This one does nothing as we called undo only twice.
print(global_history.current)  # print "Hello World"
# Now an example of reset through add()
global_history.undo()
global_history.undo()
print(global_history.current)  # print "Hello"
global_history.add("Hello there!")
print(global_history.current)  # print "Hello there!"
global_history.redo() # does nothing as the future was reset by add()

__init__() → None: The constructor takes no parameters. In the future, it could take some, like the maximum size of the history for example.

Methods

`__init__`()	The constructor takes no parameters.
`add`(action)	Add an action (i.e: object) to the history.
`instance`(args, *kwargs)	Returns/creates the instance of the History object
`redo`()	Step forward into the actions' timeline.
`reset`()	Reset the history to its initial state.
`undo`()	Step backward into the actions' timeline.

Attributes

current

current is a read-only property to access the current action of the history.

add(action: object) → None

Add an action (i.e: object) to the history.

This action becomes the current one.

Adding an action reset the future actions (i.e: you cannot redo what was undone before adding the action).

Parameters:: action (object) – The action to add to the history.

Example:

global_history = History.instance()
global_history.add('Hel')
global_history.add('Hello')
print(global_history.current)  # print "Hello"

property current: object

current is a read-only property to access the current action of the history.

To add an action and set it as current, use the add() method.

classmethod instance(*args, **kwargs)

Returns/creates the instance of the History object

Creates an History object on first call an then returns the same instance on further calls

Returns:: Instance of the History object
Return type:: History

redo() → None

Step forward into the actions’ timeline.

This method takes the current action and puts it in the past queue. It then pop the last action of the future queue and set it as current.

If there’s no more future actions, it does nothing.

Example:

global_history = History.instance()
global_history.add('Hel')
global_history.add('Hello')
print(global_history.current)  # print "Hello"
global_history.undo()
print(global_history.current)  # print "Hel"
global_history.redo()
print(global_history.current)  # print "Hello"

reset() → None: Reset the history to its initial state. It clears all the past and future actions. It also set the current action to None.

undo() → None

Step backward into the actions’ timeline.

This method takes the current action and puts it in the future queue. It then pop the last action of the past queue and set it as current.

If there’s no more past actions, it does nothing.

Example:

global_history = History.instance()
global_history.add('Hel')
global_history.add('Hello')
print(global_history.current)  # print "Hello"
global_history.undo()
print(global_history.current)  # print "Hel"