summaryrefslogtreecommitdiffstats
path: root/offapi/com/sun/star/document/XUndoManager.idl
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--offapi/com/sun/star/document/XUndoManager.idl330
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: */