diff options
Diffstat (limited to 'offapi/com/sun/star/document/XUndoManager.idl')
| -rw-r--r-- | offapi/com/sun/star/document/XUndoManager.idl | 330 |
1 files changed, 330 insertions, 0 deletions
diff --git a/offapi/com/sun/star/document/XUndoManager.idl b/offapi/com/sun/star/document/XUndoManager.idl new file mode 100644 index 000000000..9eb3d1d5c --- /dev/null +++ b/offapi/com/sun/star/document/XUndoManager.idl @@ -0,0 +1,330 @@ +/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */ +/* + * This file is part of the LibreOffice project. + * + * This Source Code Form is subject to the terms of the Mozilla Public + * License, v. 2.0. If a copy of the MPL was not distributed with this + * file, You can obtain one at http://mozilla.org/MPL/2.0/. + * + * This file incorporates work covered by the following license notice: + * + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed + * with this work for additional information regarding copyright + * ownership. The ASF licenses this file to you under the Apache + * License, Version 2.0 (the "License"); you may not use this file + * except in compliance with the License. You may obtain a copy of + * the License at http://www.apache.org/licenses/LICENSE-2.0 . + */ + +#ifndef __com_sun_star_document_XUndoManager_idl__ +#define __com_sun_star_document_XUndoManager_idl__ + +#include <com/sun/star/document/EmptyUndoStackException.idl> +#include <com/sun/star/document/UndoContextNotClosedException.idl> +#include <com/sun/star/document/UndoFailedException.idl> +#include <com/sun/star/util/InvalidStateException.idl> +#include <com/sun/star/util/XLockable.idl> +#include <com/sun/star/container/XChild.idl> +#include <com/sun/star/lang/IllegalArgumentException.idl> +#include <com/sun/star/lang/WrappedTargetException.idl> + + +module com { module sun { module star { module document { + +interface XUndoAction; +interface XUndoManagerListener; + + +/** provides access to the undo/redo stacks of a document + <p></p> + <h3>Undo</h3> + <p>Changes to a document usually result in recording of information how to undo those changes, if desired. A so-called + undo action records the information how to undo a single change. Undo actions are maintained in a stack, so that + the changes they represent can be undo in the reverse order they have originally been applied.</p> + + <h3>Redo</h3> + <p>Additionally, the Undo manager manages a Redo stack: Actions which are undone are moved from the Undo to the Redo + stack, so it is possible to re-apply the changes to the document.</p> + + <h3>Undo contexts</h3> + <p>For collecting multiple changes in a single undo action, so-called Undo contexts are provided. When an Undo + context is entered, all subsequently added Undo actions are not pushed onto the undo stack directly, but considered + a sub action of the Undo context. Once the Undo context is left, a single undo action is pushed onto the undo stack, + which comprises all those single Undo actions.<br/> + Undo contexts can be arbitrarily nested.</p> + + <h3>Hidden Undo actions</h3> + <p>Hidden Undo actions are those which in no observable way contribute to the undo stack. That is, + any method retrieving information about the stack will behave as if the undo action does not exist. Nonetheless, + calling undo() respectively redo() will include those actions.<br/> + Hidden Undo actions can be created by calling enterHiddenUndoContext(), following by + leaveUndoContext().</p> + + <a name="locking"></a> + <h3>Locking</h3> + <p>An Undo manager can be locked and unlocked, using the XLockable::lock() and + XLockable::unlock() methods. When it is locked, then every attempt to add an undo action, or to + enter or leave an Undo context, will be silently ignored.</p> + + @since OOo 3.4 + */ +interface XUndoManager +{ + /** allows <a href="#locking">locking</a> the undo manager. + */ + interface ::com::sun::star::util::XLockable; + + /** allows accessing the component, usually a document, which the undo manager works for. + + <p>com::sun::star::container::XChild::setParent() is not supported, and will throw + a com::sun::star::lang::NoSupportException.</p> + */ + interface ::com::sun::star::container::XChild; + + /** enters a new undo context. + + <p>A new undo action will be added to the undo stack, with the title given as <code>iTitle</code>. As long + as the context is not left, every undo action added to the stack will be treated as sub action. This means + it will not be directly accessible at the Undo manager, not appear in any user interface, and cannot be + separately undone or re-done.</p> + + <p>Each call to <code>enterUndoContext</code> must be paired by a call to leaveUndoContext(), + otherwise, the document's undo stack is left in an inconsistent state.</p> + + <p>Undo contexts can be nested, i.e. it is legitimate to call <code>enterUndoContext</code> and + enterHiddenUndoContext() multiple times without calling leaveUndoContext() inbetween.</p> + + @see leaveUndoContext + */ + void enterUndoContext( + [in] string iTitle + ); + + /** enters a new undo context, creating a hidden undo action. + + <p>A hidden undo action does not, in any visible way, contribute to the undo stack. This means + that + <ul><li>Calling undo() when the top-element is a hidden undo action will transparently + undo this action, and also undo the new top element of the stack.</li> + <li>Calling redo() when the top-element is a hidden action will transparently + redo this action, and also redo the new top element of the stack.</li> + <li>In any user interface presenting the current Undo or Redo actions to the user, a hidden + action will not be listed.</p> + </ul> + + <p>A new undo action will be added to the undo stack. As long as the context is not left, every undo action + added to the stack will be treated as sub action. This means it will not be directly accessible at the undo + manager, not appear in any user interface, and cannot be separately undone or re-done.</p> + + <p>Each call to <code>enterHiddenUndoContext</code> must be paired by a call to leaveUndoContext(), + otherwise, the document's undo stack is left in an inconsistent state.</p> + + <p>Undo contexts can be nested, i.e. it is legitimate to call enterUndoContext() and + <code>enterHiddenUndoContext</code> multiple times without calling leaveUndoContext() inbetween.</p> + + @throws EmptyUndoStackException + if the undo stack is currently empty, in which case it is impossible to push a hidden undo action onto + it. + + @see enterUndoContext + @see leaveUndoContext + */ + void enterHiddenUndoContext() + raises( EmptyUndoStackException ); + + /** leaves the undo context previously opened via enterUndoContext() respectively + enterHiddenUndoContext(). + + <p>If no undo action has been added since the context has been opened, the context is not only left, + but silently removed, and does not contribute to the undo stack at all. In this case, possible + listeners will be notified via XUndoManagerListener::cancelledContext().</p> + + <p>Otherwise, the undo context will be closed, and added to the Undo stack; the redo stack will be cleared, + and listeners will be notified via XUndoManagerListener::leftContext() resp. + XUndoManagerListener::leftHiddenContext()</p> + + @throws ::com::sun::star::util::InvalidStateException + if no undo context is currently open. + + @see enterUndoContext + @see enterHiddenUndoContext + */ + void leaveUndoContext() + raises( ::com::sun::star::util::InvalidStateException ); + + /** adds the given undo action to the undo stack. + + <p>The redo stack is cleared when a new action is pushed onto the undo stack.</p> + + <p>The Undo manager takes ownership of any actions pushed onto the undo stack. This means that if the + action is finally removed from the Undo manager's control (e.g. by calling clear() resp. + clearRedo()), it will be disposed, as long as it supports the com::sun::star::lang::XComponent + interface.</p> + + <p>If the Undo manager is <a href="#locking">locked</a> at the moment the method is called, the call will be ignored, and the undo action + will immediately be disposed, if applicable.</p> + + @throws ::com::sun::star::lang::IllegalArgumentException + if the given undo action is `NULL`. + */ + void addUndoAction( + [in] XUndoAction iAction + ) + raises( ::com::sun::star::lang::IllegalArgumentException ); + + /** reverts the most recent action on the document. + + <p>Effectively, invoking this method will + <ul><li>invoke XUndoAction::undo() on the top-most action of the undo stack</li> + <li>move this undo action from the undo stack to the redo stack</li> + </ul></p> + + @throws EmptyUndoStackException + if the undo stack is currently empty + + @throws UndoContextNotClosedException + if there currently is an open undo context + + @throws UndoFailedException + if the invocation of XUndoAction::undo() raised this exception. In this case, the undo stack + of the undo manager will have been cleared. + + @see redo + @see enterUndoContext + */ + void undo() + raises( ::com::sun::star::document::EmptyUndoStackException, + ::com::sun::star::document::UndoContextNotClosedException, + ::com::sun::star::document::UndoFailedException ); + + /** replays the action on the document which has most recently been undone + + <p>Effectively, invoking this method will + <ul><li>invoke XUndoAction::redo() on the top-most action of the redo stack</li> + <li>move this action from the redo stack to the undo stack</li> + </ul></p> + + @throws EmptyUndoStackException + when the Redo stack is currently empty + + @throws UndoContextNotClosedException + if there currently is an open undo context + + @throws UndoFailedException + if the invocation of XUndoAction::redo() raised this exception. In this case, the redo stack + of the undo manager will have been cleared. + + @see undo + */ + void redo() + raises( ::com::sun::star::document::EmptyUndoStackException, + ::com::sun::star::document::UndoContextNotClosedException, + ::com::sun::star::document::UndoFailedException ); + + /** determines whether undo() can reasonably be expected to succeed. + + @return + `FALSE` if and only if the undo stack is currently empty, or there is an open and not-yet-closed + undo context. + */ + boolean isUndoPossible(); + + /** determines whether redo() can reasonably be expected to succeed. + + @return + `FALSE` if and only if the redo stack is currently empty, or there is an open and not-yet-closed + undo context. + */ + boolean isRedoPossible(); + + /** returns the title of the top-most action on the undo stack + + @throws EmptyUndoStackException + when the undo stack is currently empty + + @see XUndoAction::Title + */ + string getCurrentUndoActionTitle() + raises( ::com::sun::star::document::EmptyUndoStackException ); + + /** returns the title of the top-most action on the Redo stack + + @throws EmptyUndoStackException + when the Redo stack is currently empty + @see XUndoAction::Title + */ + string getCurrentRedoActionTitle() + raises( ::com::sun::star::document::EmptyUndoStackException ); + + /** returns the titles of all actions currently on the undo stack, from top to bottom + @see XUndoAction::Title + */ + sequence< string > + getAllUndoActionTitles(); + + /** returns the titles of all actions currently on the Redo stack, from top to bottom + + @see XUndoAction::Title + */ + sequence< string > + getAllRedoActionTitles(); + + /** clears the undo and the redo stack. + + <p>All actions will be removed from both the Undo and the Redo stack. Actions which implement the + com::sun::star::lang::XComponent interface will be disposed.</p> + + @throws UndoContextNotClosedException + if the method is invoked while an undo context is still open + */ + void clear() + raises( ::com::sun::star::document::UndoContextNotClosedException ); + + /** clears the redo stack. + + <p>All actions will be removed from the Redo stack. Actions which implement the com::sun::star::lang::XComponent + interface will be disposed.</p> + + @throws UndoContextNotClosedException + if the method is invoked while an undo context is still open + */ + void clearRedo() + raises( ::com::sun::star::document::UndoContextNotClosedException ); + + /** resets the Undo manager + + <p>In particular, this method will + <ul><li>remove all locks from the undo manager</li> + <li>close all open undo contexts</li> + <li>clear the undo stack</li> + <li>clear the redo stack</li> + </ul></p> + + <p>Note that possible listeners will not get notifications for the single parts of the reset, i.e. there + will be no single XUndoManagerListener::allActionsCleared(), + XUndoManagerListener::leftContext(), etc., notifications. Instead, listeners will be + notified of the reset by calling their XUndoManagerListener::resetAll() method.</p> + */ + void reset(); + + /** adds a listener to be notified of changes in the Undo/Redo stacks. + */ + void addUndoManagerListener( + [in] XUndoManagerListener iListener + ); + + /** removes a previously added listener + */ + void removeUndoManagerListener( + [in] XUndoManagerListener iListener + ); +}; + + +}; }; }; }; + + +#endif + +/* vim:set shiftwidth=4 softtabstop=4 expandtab: */ |