<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Undo Framework — AppTools v3.1.0 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '3.1.0',
COLLAPSE_MODINDEX: false,
FILE_SUFFIX: '.html'
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="contents" title="Global table of contents" href="../contents.html" />
<link rel="index" title="Global index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="top" title="AppTools v3.1.0 documentation" href="../index.html" />
<link rel="prev" title="Automatic script recording" href="../scripting/introduction.html" />
</head>
<body>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="../scripting/introduction.html" title="Automatic script recording"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">AppTools v3.1.0 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="undo-framework">
<h1>Undo Framework<a class="headerlink" href="#undo-framework" title="Permalink to this headline">¶</a></h1>
<p>The Undo Framework is a component of the Enthought Tool Suite that provides
developers with an API that implements the standard pattern for do/undo/redo
commands.</p>
<p>The framework is completely configurable. Alternate implementations of all
major components can be provided if necessary.</p>
<div class="section" id="framework-concepts">
<h2>Framework Concepts<a class="headerlink" href="#framework-concepts" title="Permalink to this headline">¶</a></h2>
<p>The following are the concepts supported by the framework.</p>
<ul>
<li><p class="first">Command</p>
<p>A command is an application defined operation that can be done (i.e.
executed), undone (i.e. reverted) and redone (i.e. repeated).</p>
<p>A command operates on some data and maintains sufficient state to allow it to
revert or repeat a change to the data.</p>
<p>Commands may be merged so that potentially long sequences of similar
commands (e.g. to add a character to some text) can be collapsed into a
single command (e.g. to add a word to some text).</p>
</li>
<li><p class="first">Macro</p>
<p>A macro is a sequence of commands that is treated as a single command when
being undone or redone.</p>
</li>
<li><p class="first">Command Stack</p>
<p>A command is done by pushing it onto a command stack. The last command can
be undone and redone by calling appropriate command stack methods. It is
also possible to move the stack’s position to any point and the command stack
will ensure that commands are undone or redone as required.</p>
<p>A command stack maintains a <em>clean</em> state which is updated as commands are
done and undone. It may be explicitly set, for example when the data being
manipulated by the commands is saved to disk.</p>
<p>Canned PyFace actions are provided as wrappers around command stack methods
to implement common menu items.</p>
</li>
<li><p class="first">Undo Manager</p>
<p>An undo manager is responsible for one or more command stacks and maintains
a reference to the currently active stack. It provides convenience undo and
redo methods that operate on the currently active stack.</p>
<p>An undo manager ensures that each command execution is allocated a unique
sequence number, irrespective of which command stack it is pushed to. Using
this it is possible to synchronise multiple command stacks and restore them
to a particular point in time.</p>
<p>An undo manager will generate an event whenever the clean state of the active
stack changes. This can be used to maintain some sort of GUI status
indicator to tell the user that their data has been modified since it was
last saved.</p>
</li>
</ul>
<p>Typically an application will have one undo manager and one undo stack for
each data type that can be edited. However this is not a requirement: how the
command stack’s in particular are organised and linked (with the user
manager’s sequence number) can need careful thought so as not to confuse the
user - particularly in a plugin based application that may have many editors.</p>
<p>To support this typical usage the PyFace <tt class="docutils literal"><span class="pre">Workbench</span></tt> class has an
<tt class="docutils literal"><span class="pre">undo_manager</span></tt> trait and the PyFace <tt class="docutils literal"><span class="pre">Editor</span></tt> class has a <tt class="docutils literal"><span class="pre">command_stack</span></tt>
trait. Both are lazy loaded so can be completely ignored if they are not used.</p>
</div>
<div class="section" id="api-overview">
<h2>API Overview<a class="headerlink" href="#api-overview" title="Permalink to this headline">¶</a></h2>
<p>This section gives a brief overview of the various classes implemented in the
framework. The complete <a class="reference external" href="api/index.html">API</a> documentation is available as endo generated
HTML.</p>
<p>The <a class="reference external" href="https://svn.enthought.com/enthought/browser/AppTools/trunk/examples/undo/">example</a> application demonstrates all the major features of the framework.</p>
<div class="section" id="undomanager">
<h3>UndoManager<a class="headerlink" href="#undomanager" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">UndoManager</span></tt> class is the default implementation of the <tt class="docutils literal"><span class="pre">IUndoManager</span></tt>
interface.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">active_stack</span></tt></dt>
<dd>This trait is a reference to the currently active command stack and may be
None. Typically it is set when some sort of editor becomes active.</dd>
<dt><tt class="docutils literal"><span class="pre">active_stack_clean</span></tt></dt>
<dd>This boolean trait reflects the clean state of the currently active
command stack. It is intended to support a “document modified” indicator
in the GUI. It is maintained by the undo manager.</dd>
<dt><tt class="docutils literal"><span class="pre">stack_updated</span></tt></dt>
<dd>This event is fired when the index of a command stack is changed. A
reference to the stack is passed as an argument to the event and may not
be the currently active stack.</dd>
<dt><tt class="docutils literal"><span class="pre">undo_name</span></tt></dt>
<dd>This Unicode trait is the name of the command that can be undone, and will
be empty if there is no such command. It is maintained by the undo
manager.</dd>
<dt><tt class="docutils literal"><span class="pre">redo_name</span></tt></dt>
<dd>This Unicode trait is the name of the command that can be redone, and will
be empty if there is no such command. It is maintained by the undo
manager.</dd>
<dt><tt class="docutils literal"><span class="pre">sequence_nr</span></tt></dt>
<dd>This integer trait is the sequence number of the next command to be
executed. It is incremented immediately before a command’s <tt class="docutils literal"><span class="pre">do()</span></tt>
method is called. A particular sequence number identifies the state of
all command stacks handled by the undo manager and allows those stacks to
be set to the point they were at at a particular point in time. In other
words, the sequence number allows otherwise independent command stacks to
be synchronised.</dd>
<dt><tt class="docutils literal"><span class="pre">undo()</span></tt></dt>
<dd>This method calls the <tt class="docutils literal"><span class="pre">undo()</span></tt> method of the last command on the active
command stack.</dd>
<dt><tt class="docutils literal"><span class="pre">redo()</span></tt></dt>
<dd>This method calls the <tt class="docutils literal"><span class="pre">redo()</span></tt> method of the last undone command on the
active command stack.</dd>
</dl>
</div>
<div class="section" id="commandstack">
<h3>CommandStack<a class="headerlink" href="#commandstack" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">CommandStack</span></tt> class is the default implementation of the
<tt class="docutils literal"><span class="pre">ICommandStack</span></tt> interface.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">clean</span></tt></dt>
<dd>This boolean traits reflects the clean state of the command stack. Its
value changes as commands are executed, undone and redone. It may also be
explicitly set to mark the current stack position as being clean (when
data is saved to disk for example).</dd>
<dt><tt class="docutils literal"><span class="pre">undo_name</span></tt></dt>
<dd>This Unicode trait is the name of the command that can be undone, and will
be empty if there is no such command. It is maintained by the command
stack.</dd>
<dt><tt class="docutils literal"><span class="pre">redo_name</span></tt></dt>
<dd>This Unicode trait is the name of the command that can be redone, and will
be empty if there is no such command. It is maintained by the command
stack.</dd>
<dt><tt class="docutils literal"><span class="pre">undo_manager</span></tt></dt>
<dd>This trait is a reference to the undo manager that manages the command
stack.</dd>
<dt><tt class="docutils literal"><span class="pre">push(command)</span></tt></dt>
<dd>This method executes the given command by calling its <tt class="docutils literal"><span class="pre">do()</span></tt> method.
Any value returned by <tt class="docutils literal"><span class="pre">do()</span></tt> is returned by <tt class="docutils literal"><span class="pre">push()</span></tt>. If the command
couldn’t be merged with the previous one then it is saved on the command
stack.</dd>
<dt><tt class="docutils literal"><span class="pre">undo(sequence_nr=0)</span></tt></dt>
<dd>This method undoes the last command. If a sequence number is given then
all commands are undone up to an including the sequence number.</dd>
<dt><tt class="docutils literal"><span class="pre">redo(sequence_nr=0)</span></tt></dt>
<dd>This method redoes the last command and returns any result. If a sequence
number is given then all commands are redone up to an including the
sequence number and any result of the last of these is returned.</dd>
<dt><tt class="docutils literal"><span class="pre">clear()</span></tt></dt>
<dd>This method clears the command stack, without undoing or redoing any
commands, and leaves the stack in a clean state. It is typically used
when all changes to the data have been abandoned.</dd>
<dt><tt class="docutils literal"><span class="pre">begin_macro(name)</span></tt></dt>
<dd>This method begins a macro by creating an empty command with the given
name. The commands passed to all subsequent calls to <tt class="docutils literal"><span class="pre">push()</span></tt> will be
contained in the macro until the next call to <tt class="docutils literal"><span class="pre">end_macro()</span></tt>. Macros may
be nested. The command stack is disabled (ie. nothing can be undone or
redone) while a macro is being created (ie. while there is an outstanding
<tt class="docutils literal"><span class="pre">end_macro()</span></tt> call).</dd>
<dt><tt class="docutils literal"><span class="pre">end_macro()</span></tt></dt>
<dd>This method ends the current macro.</dd>
</dl>
</div>
<div class="section" id="icommand">
<h3>ICommand<a class="headerlink" href="#icommand" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">ICommand</span></tt> interface defines the interface that must be implemented by
any undoable/redoable command.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">data</span></tt></dt>
<dd>This optional trait is a reference to the data object that the command
operates on. It is not used by the framework itself.</dd>
<dt><tt class="docutils literal"><span class="pre">name</span></tt></dt>
<dd>This Unicode trait is the name of the command as it will appear in any GUI
element (e.g. in the text of an undo and redo menu entry). It may include
<tt class="docutils literal"><span class="pre">&</span></tt> to indicate a keyboard shortcut which will be automatically removed
whenever it is inappropriate.</dd>
<dt><tt class="docutils literal"><span class="pre">__init__(*args)</span></tt></dt>
<dd>If the command takes arguments then the command must ensure that deep
copies should be made if appropriate.</dd>
<dt><tt class="docutils literal"><span class="pre">do()</span></tt></dt>
<dd>This method is called by a command stack to execute the command and to
return any result. The command must save any state necessary for the
<tt class="docutils literal"><span class="pre">undo()</span></tt> and <tt class="docutils literal"><span class="pre">redo()</span></tt> methods to work. It is guaranteed that this
will only ever be called once and that it will be called before any call
to <tt class="docutils literal"><span class="pre">undo()</span></tt> or <tt class="docutils literal"><span class="pre">redo()</span></tt>.</dd>
<dt><tt class="docutils literal"><span class="pre">undo()</span></tt></dt>
<dd>This method is called by a command stack to undo the command.</dd>
<dt><tt class="docutils literal"><span class="pre">redo()</span></tt></dt>
<dd>This method is called by a command stack to redo the command and to return
any result.</dd>
<dt><tt class="docutils literal"><span class="pre">merge(other)</span></tt></dt>
<dd>This method is called by the command stack to try and merge the <tt class="docutils literal"><span class="pre">other</span></tt>
command with this one. True should be returned if the commands were
merged. If the commands are merged then <tt class="docutils literal"><span class="pre">other</span></tt> will not be placed on
the command stack. A subsequent undo or redo of this modified command
must have the same effect as the two original commands.</dd>
</dl>
</div>
<div class="section" id="abstractcommand">
<h3>AbstractCommand<a class="headerlink" href="#abstractcommand" title="Permalink to this headline">¶</a></h3>
<p><tt class="docutils literal"><span class="pre">AbstractCommand</span></tt> is an abstract base class that implements the <tt class="docutils literal"><span class="pre">ICommand</span></tt>
interface. It provides a default implementation of the <tt class="docutils literal"><span class="pre">merge()</span></tt> method.</p>
</div>
<div class="section" id="commandaction">
<h3>CommandAction<a class="headerlink" href="#commandaction" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">CommandAction</span></tt> class is a sub-class of the PyFace <tt class="docutils literal"><span class="pre">Action</span></tt> class that
is used to wrap commands.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">command</span></tt></dt>
<dd>This callable trait must be set to a factory that will return an object
that implements <tt class="docutils literal"><span class="pre">ICommand</span></tt>. It will be called when the action is invoked
and the object created pushed onto the command stack.</dd>
<dt><tt class="docutils literal"><span class="pre">command_stack</span></tt></dt>
<dd>This instance trait must be set to the command stack that commands invoked
by the action are pushed to.</dd>
<dt><tt class="docutils literal"><span class="pre">data</span></tt></dt>
<dd>This optional trait is a reference to the data object that will be passed
to the <tt class="docutils literal"><span class="pre">command</span></tt> factory when it is called.</dd>
</dl>
</div>
<div class="section" id="undoaction">
<h3>UndoAction<a class="headerlink" href="#undoaction" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">UndoAction</span></tt> class is a canned PyFace action that undoes the last
command of the active command stack.</p>
</div>
<div class="section" id="redoaction">
<h3>RedoAction<a class="headerlink" href="#redoaction" title="Permalink to this headline">¶</a></h3>
<p>The <tt class="docutils literal"><span class="pre">RedoAction</span></tt> class is a canned PyFace action that redoes the last
command undone of the active command stack.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3>Table Of Contents</h3>
<ul>
<li><a class="reference external" href="">Undo Framework</a><ul>
<li><a class="reference external" href="#framework-concepts">Framework Concepts</a></li>
<li><a class="reference external" href="#api-overview">API Overview</a><ul>
<li><a class="reference external" href="#undomanager">UndoManager</a></li>
<li><a class="reference external" href="#commandstack">CommandStack</a></li>
<li><a class="reference external" href="#icommand">ICommand</a></li>
<li><a class="reference external" href="#abstractcommand">AbstractCommand</a></li>
<li><a class="reference external" href="#commandaction">CommandAction</a></li>
<li><a class="reference external" href="#undoaction">UndoAction</a></li>
<li><a class="reference external" href="#redoaction">RedoAction</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="../scripting/introduction.html" title="previous chapter">Automatic script recording</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/undo/Introduction.txt">Show Source</a></li>
</ul>
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" /> <input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../modindex.html" title="Global Module Index"
accesskey="M">modules</a> |</li>
<li class="right" >
<a href="../scripting/introduction.html" title="Automatic script recording"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">AppTools v3.1.0 documentation</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2008, Enthought.
Last updated on Dec 03, 2008.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
</body>
</html>
