Prev Up Next
Combining Undoinfo The Undo Mechanism Plugins

The Undo API

The module undo.py implements most functions and classes necessary for handling undo in Sketch.

The format for a single unit of undoinfo is as described above with a single extension: The first item in the tuple may be a string, in which case the second item is callable and the items [2:] are the arguments. The string is meant to provide a short description of the operation, such as `Create Rectangle', that may be displayed as a menu item like `Undo Create Rectangle'. Therefore, this string is only necessary at the top level undo info, which is currently always created by the document object.

The public interface to undo handling in Sketch consists of the following functions and objects which are exported by the package Sketch.

Constructors

In many cases, methods that change graphics objects or are otherwise expected to return undoinfo, simply create a tuple of the correct format.

Example: The SetRadius method of the regular polygon Plugin: 
def SetRadius(self, radius):
    undo = self.SetRadius, self.radius  # create undoinfo
    self.radius = radius    # set the instance variable
    self.compute_poly()     # update the polygon
    self._changed()	    # notify interested objects that self changed,
			    # and force update of bounding rects, etc.
    return undo             # finally, return undo info

For compound objects and methods that need to combine several pieces of undo info there are two special constructors:

CreateListUndo(infos)

Return undo info that combines the undo infos in infos. infos is expected to be a sequence of undo infos listed in the order in which the actions were performed. When the operation is undone they are executed in reverse order.

CreateListUndo tries to simplify infos. It builds a new list by iterating over the items of infos and inlining list undo info (as created by CreateListUndo) and by discarding empty undo info (represented by the NullUndo object, see below). If the resulting list is empty return NullUndo.

CreateMultiUndo(info1[, info2[, ...]])

Return undoinfo that undoes info1, info2, etc., in reverse order. This is implemented via CreateListUndo.

Sometimes it happens that nothing has to be undone:

NullUndo

NullUndo is an undo info tuple that does nothing. If a method needs to return undo info, but for some reason nothing needs to be undone, this object should be returned.

The functions that combine undo info treat it specially by removing it from the list of undo infos.

Combining Undoinfo The Undo Mechanism Plugins
Prev Up Next