forked from amazingfate/loongoffice
331 lines
14 KiB
Plaintext
331 lines
14 KiB
Plaintext
/* -*- 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
|
|
an 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: */
|