diff options
Diffstat (limited to 'offapi/com/sun/star/document/XUndoManager.idl')
| -rw-r--r-- | offapi/com/sun/star/document/XUndoManager.idl | 337 |
1 files changed, 0 insertions, 337 deletions
diff --git a/offapi/com/sun/star/document/XUndoManager.idl b/offapi/com/sun/star/document/XUndoManager.idl deleted file mode 100644 index 74aa4de0c..000000000 --- a/offapi/com/sun/star/document/XUndoManager.idl +++ /dev/null @@ -1,337 +0,0 @@ -/************************************************************************* - * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. - * - * Copyright 2000, 2010 Oracle and/or its affiliates. - * - * OpenOffice.org - a multi-platform office productivity suite - * - * This file is part of OpenOffice.org. - * - * OpenOffice.org is free software: you can redistribute it and/or modify - * it under the terms of the GNU Lesser General Public License version 3 - * only, as published by the Free Software Foundation. - * - * OpenOffice.org is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU Lesser General Public License version 3 for more details - * (a copy is included in the LICENSE file that accompanied this code). - * - * You should have received a copy of the GNU Lesser General Public License - * version 3 along with OpenOffice.org. If not, see - * <http://www.openoffice.org/license.html> - * for a copy of the LGPLv3 License. - * - ************************************************************************/ - -#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 { - -published interface XUndoAction; -published interface XUndoManagerListener; - -//================================================================================================================== - -/** provides access to the undo/redo stacks of a document - - <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 <member>undo</member> respectively <member>redo</member> will include those actions.<br/> - Hidden Undo actions can be created by calling <member>enterHiddenUndoContext</member>, following by - <member>leaveUndoContext</member>.</p> - - <a name="locking"></a> - <h3>Locking</h3> - <p>An Undo manager can be locked and unlocked, using the <member>XLockable::lock</member> and - <member>XLockable::unlock</member> 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> - */ -published 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><member scope="com::sun::star::container">XChild::setParent</member> is not supported, and will throw - an <type scope="com::sun::star::lang">NoSupportException</type>.</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>i_title</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 <member>leaveUndoContext</member>, - 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 - <member>enterHiddenUndoContext</member> multiple times without calling <member>leaveUndoContext</member> inbetween.</p> - - @see leaveUndoContext - */ - void enterUndoContext( - [in] string i_title - ); - - /** 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 <member>undo</member> 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 <member>redo</member> 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 <member>leaveUndoContext</member>, - 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 <member>enterUndoContext</member> and - <code>enterHiddenUndoContext</code> multiple times without calling <member>leaveUndoContext</member> 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 <member>enterUndoContext</member> respectively - <member>enterHiddenUndoContext</member>. - - <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 <member>XUndoManagerListener::cancelledContext</member>.</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 <member>XUndoManagerListener::leftContext</member> resp. - <member>XUndoManagerListener::leftHiddenContext</member></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 <member>clear</member> resp. - <member>clearRedo</member>), it will be disposed, as long as it supports the <member scope="com::sun::star::lang">XComponent</member> - 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 i_action - ) - raises( ::com::sun::star::lang::IllegalArgumentException ); - - /** reverts the most recent action on the document. - - <p>Effectively, invoking this method will - <ul><li>invoke <member>XUndoAction::undo</member> 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 <member>XUndoAction::undo</member> 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 <member>XUndoAction::redo</member> 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 <member>XUndoAction::redo</member> 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 <member>undo</member> 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 <member>redo</member> 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 - <type scope="com::sun::star::lang">XComponent</type> 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 <type scope="com::sun::star::lang">XComponent</type> - 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 <member>XUndoManagerListener::allActionsCleared</member>, - <member>XUndoManagerListener::leftContext</member>, etc., notifications. Instead, listeners will be - notified of the reset by calling their <member>XUndoManagerListener::resetAll</member> method.</p> - */ - void reset(); - - /** adds a listener to be notified of changes in the Undo/Redo stacks. - */ - void addUndoManagerListener( - [in] XUndoManagerListener i_listener - ); - - /** removes a previously added listener - */ - void removeUndoManagerListener( - [in] XUndoManagerListener i_listener - ); -}; - -//================================================================================================================== - -}; }; }; }; - -//================================================================================================================== - -#endif |