Adding upstream version 4:7.4.7.upstream/4%7.4.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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: */