offapi/com/sun/star/document/XUndoManager.idl

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 #ifndef __com_sun_star_document_XUndoManager_idl__
  21 #define __com_sun_star_document_XUndoManager_idl__
  22
  23 #include <com/sun/star/document/EmptyUndoStackException.idl>
  24 #include <com/sun/star/document/UndoContextNotClosedException.idl>
  25 #include <com/sun/star/document/UndoFailedException.idl>
  26 #include <com/sun/star/util/InvalidStateException.idl>
  27 #include <com/sun/star/util/XLockable.idl>
  28 #include <com/sun/star/container/XChild.idl>
  29 #include <com/sun/star/lang/IllegalArgumentException.idl>
  30 #include <com/sun/star/lang/WrappedTargetException.idl>
  31
  32
  33 module com { module sun { module star { module document {
  34
  35 interface XUndoAction;
  36 interface XUndoManagerListener;
  37
  38
  39 /** provides access to the undo/redo stacks of a document
  40     <p></p>
  41     <h3>Undo</h3>
  42     <p>Changes to a document usually result in recording of information how to undo those changes, if desired. A so-called
  43     undo action records the information how to undo a single change. Undo actions are maintained in a stack, so that
  44     the changes they represent can be undo in the reverse order they have originally been applied.</p>
  45
  46     <h3>Redo</h3>
  47     <p>Additionally, the Undo manager manages a Redo stack: Actions which are undone are moved from the Undo to the Redo
  48     stack, so it is possible to re-apply the changes to the document.</p>
  49
  50     <h3>Undo contexts</h3>
  51     <p>For collecting multiple changes in a single undo action, so-called Undo contexts are provided. When an Undo
  52     context is entered, all subsequently added Undo actions are not pushed onto the undo stack directly, but considered
  53     a sub action of the Undo context. Once the Undo context is left, a single undo action is pushed onto the undo stack,
  54     which comprises all those single Undo actions.<br/>
  55     Undo contexts can be arbitrarily nested.</p>
  56
  57     <h3>Hidden Undo actions</h3>
  58     <p>Hidden Undo actions are those which in no observable way contribute to the undo stack. That is,
  59     any method retrieving information about the stack will behave as if the undo action does not exist. Nonetheless,
  60     calling undo() respectively redo() will include those actions.<br/>
  61     Hidden Undo actions can be created by calling enterHiddenUndoContext(), following by
  62     leaveUndoContext().</p>
  63
  64     <a name="locking"></a>
  65     <h3>Locking</h3>
  66     <p>An Undo manager can be locked and unlocked, using the XLockable::lock() and
  67     XLockable::unlock() methods. When it is locked, then every attempt to add an undo action, or to
  68     enter or leave an Undo context, will be silently ignored.</p>
  69
  70     @since OOo 3.4
  71  */
  72 interface XUndoManager
  73 {
  74     /** allows <a href="#locking">locking</a> the undo manager.
  75     */
  76     interface ::com::sun::star::util::XLockable;
  77
  78     /** allows accessing the component, usually a document, which the undo manager works for.
  79
  80         <p>com::sun::star::container::XChild::setParent() is not supported, and will throw
  81         an com::sun::star::lang::NoSupportException.</p>
  82     */
  83     interface ::com::sun::star::container::XChild;
  84
  85     /** enters a new undo context.
  86
  87         <p>A new undo action will be added to the undo stack, with the title given as <code>iTitle</code>. As long
  88         as the context is not left, every undo action added to the stack will be treated as sub action. This means
  89         it will not be directly accessible at the Undo manager, not appear in any user interface, and cannot be
  90         separately undone or re-done.</p>
  91
  92         <p>Each call to <code>enterUndoContext</code> must be paired by a call to leaveUndoContext(),
  93         otherwise, the document's undo stack is left in an inconsistent state.</p>
  94
  95         <p>Undo contexts can be nested, i.e. it is legitimate to call <code>enterUndoContext</code> and
  96         enterHiddenUndoContext() multiple times without calling leaveUndoContext() inbetween.</p>
  97
  98         @see leaveUndoContext
  99     */
 100     void    enterUndoContext(
 101                 [in] string iTitle
 102             );
 103
 104     /** enters a new undo context, creating a hidden undo action.
 105
 106         <p>A hidden undo action does not, in any visible way, contribute to the undo stack. This means
 107         that
 108         <ul><li>Calling undo() when the top-element is a hidden undo action will transparently
 109                 undo this action, and also undo the new top element of the stack.</li>
 110             <li>Calling redo() when the top-element is a hidden action will transparently
 111                 redo this action, and also redo the new top element of the stack.</li>
 112             <li>In any user interface presenting the current Undo or Redo actions to the user, a hidden
 113                 action will not be listed.</p>
 114         </ul>
 115
 116         <p>A new undo action will be added to the undo stack. As long as the context is not left, every undo action
 117         added to the stack will be treated as sub action. This means it will not be directly accessible at the undo
 118         manager, not appear in any user interface, and cannot be separately undone or re-done.</p>
 119
 120         <p>Each call to <code>enterHiddenUndoContext</code> must be paired by a call to leaveUndoContext(),
 121         otherwise, the document's undo stack is left in an inconsistent state.</p>
 122
 123         <p>Undo contexts can be nested, i.e. it is legitimate to call enterUndoContext() and
 124         <code>enterHiddenUndoContext</code> multiple times without calling leaveUndoContext() inbetween.</p>
 125
 126         @throws EmptyUndoStackException
 127             if the undo stack is currently empty, in which case it is impossible to push a hidden undo action onto
 128             it.
 129
 130         @see enterUndoContext
 131         @see leaveUndoContext
 132     */
 133     void    enterHiddenUndoContext()
 134         raises( EmptyUndoStackException );
 135
 136     /** leaves the undo context previously opened via enterUndoContext() respectively
 137         enterHiddenUndoContext().
 138
 139         <p>If no undo action has been added since the context has been opened, the context is not only left,
 140         but silently removed, and does not contribute to the undo stack at all. In this case, possible
 141         listeners will be notified via XUndoManagerListener::cancelledContext().</p>
 142
 143         <p>Otherwise, the undo context will be closed, and added to the Undo stack; the redo stack will be cleared,
 144         and listeners will be notified via XUndoManagerListener::leftContext() resp.
 145         XUndoManagerListener::leftHiddenContext()</p>
 146
 147         @throws ::com::sun::star::util::InvalidStateException
 148             if no undo context is currently open.
 149
 150         @see enterUndoContext
 151         @see enterHiddenUndoContext
 152     */
 153     void    leaveUndoContext()
 154         raises( ::com::sun::star::util::InvalidStateException );
 155
 156     /** adds the given undo action to the undo stack.
 157
 158         <p>The redo stack is cleared when a new action is pushed onto the undo stack.</p>
 159
 160         <p>The Undo manager takes ownership of any actions pushed onto the undo stack. This means that if the
 161         action is finally removed from the Undo manager's control (e.g. by calling clear() resp.
 162         clearRedo()), it will be disposed, as long as it supports the com::sun::star::lang::XComponent
 163         interface.</p>
 164
 165         <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
 166         will immediately be disposed, if applicable.</p>
 167
 168         @throws ::com::sun::star::lang::IllegalArgumentException
 169             if the given undo action is `NULL`.
 170     */
 171     void    addUndoAction(
 172                 [in] XUndoAction iAction
 173             )
 174             raises( ::com::sun::star::lang::IllegalArgumentException );
 175
 176     /** reverts the most recent action on the document.
 177
 178         <p>Effectively, invoking this method will
 179         <ul><li>invoke XUndoAction::undo() on the top-most action of the undo stack</li>
 180             <li>move this undo action from the undo stack to the redo stack</li>
 181         </ul></p>
 182
 183         @throws EmptyUndoStackException
 184             if the undo stack is currently empty
 185
 186         @throws UndoContextNotClosedException
 187             if there currently is an open undo context
 188
 189         @throws UndoFailedException
 190             if the invocation of XUndoAction::undo() raised this exception. In this case, the undo stack
 191             of the undo manager will have been cleared.
 192
 193         @see redo
 194         @see enterUndoContext
 195     */
 196     void    undo()
 197             raises( ::com::sun::star::document::EmptyUndoStackException,
 198                     ::com::sun::star::document::UndoContextNotClosedException,
 199                     ::com::sun::star::document::UndoFailedException );
 200
 201     /** replays the action on the document which has most recently been undone
 202
 203         <p>Effectively, invoking this method will
 204         <ul><li>invoke XUndoAction::redo() on the top-most action of the redo stack</li>
 205             <li>move this action from the redo stack to the undo stack</li>
 206         </ul></p>
 207
 208         @throws EmptyUndoStackException
 209             when the Redo stack is currently empty
 210
 211         @throws UndoContextNotClosedException
 212             if there currently is an open undo context
 213
 214         @throws UndoFailedException
 215             if the invocation of XUndoAction::redo() raised this exception. In this case, the redo stack
 216             of the undo manager will have been cleared.
 217
 218         @see undo
 219     */
 220     void    redo()
 221             raises( ::com::sun::star::document::EmptyUndoStackException,
 222                     ::com::sun::star::document::UndoContextNotClosedException,
 223                     ::com::sun::star::document::UndoFailedException );
 224
 225     /** determines whether undo() can reasonably be expected to succeed.
 226
 227         @return
 228             `FALSE` if and only if the undo stack is currently empty, or there is an open and not-yet-closed
 229             undo context.
 230     */
 231     boolean isUndoPossible();
 232
 233     /** determines whether redo() can reasonably be expected to succeed.
 234
 235         @return
 236             `FALSE` if and only if the redo stack is currently empty, or there is an open and not-yet-closed
 237             undo context.
 238     */
 239     boolean isRedoPossible();
 240
 241     /** returns the title of the top-most action on the undo stack
 242
 243         @throws EmptyUndoStackException
 244             when the undo stack is currently empty
 245
 246         @see XUndoAction::Title
 247     */
 248     string  getCurrentUndoActionTitle()
 249             raises( ::com::sun::star::document::EmptyUndoStackException );
 250
 251     /** returns the title of the top-most action on the Redo stack
 252
 253         @throws EmptyUndoStackException
 254             when the Redo stack is currently empty
 255         @see XUndoAction::Title
 256     */
 257     string  getCurrentRedoActionTitle()
 258             raises( ::com::sun::star::document::EmptyUndoStackException );
 259
 260     /** returns the titles of all actions currently on the undo stack, from top to bottom
 261         @see XUndoAction::Title
 262     */
 263     sequence< string >
 264             getAllUndoActionTitles();
 265
 266     /** returns the titles of all actions currently on the Redo stack, from top to bottom
 267
 268         @see XUndoAction::Title
 269     */
 270     sequence< string >
 271             getAllRedoActionTitles();
 272
 273     /** clears the undo and the redo stack.
 274
 275         <p>All actions will be removed from both the Undo and the Redo stack. Actions which implement the
 276         com::sun::star::lang::XComponent interface will be disposed.</p>
 277
 278         @throws UndoContextNotClosedException
 279             if the method is invoked while an undo context is still open
 280     */
 281     void    clear()
 282             raises( ::com::sun::star::document::UndoContextNotClosedException );
 283
 284     /** clears the redo stack.
 285
 286         <p>All actions will be removed from the Redo stack. Actions which implement the com::sun::star::lang::XComponent
 287         interface will be disposed.</p>
 288
 289         @throws UndoContextNotClosedException
 290             if the method is invoked while an undo context is still open
 291     */
 292     void    clearRedo()
 293             raises( ::com::sun::star::document::UndoContextNotClosedException );
 294
 295     /** resets the Undo manager
 296
 297         <p>In particular, this method will
 298             <ul><li>remove all locks from the undo manager</li>
 299                 <li>close all open undo contexts</li>
 300                 <li>clear the undo stack</li>
 301                 <li>clear the redo stack</li>
 302             </ul></p>
 303
 304         <p>Note that possible listeners will not get notifications for the single parts of the reset, i.e. there
 305         will be no single XUndoManagerListener::allActionsCleared(),
 306         XUndoManagerListener::leftContext(), etc., notifications. Instead, listeners will be
 307         notified of the reset by calling their XUndoManagerListener::resetAll() method.</p>
 308     */
 309     void    reset();
 310
 311     /** adds a listener to be notified of changes in the Undo/Redo stacks.
 312     */
 313     void    addUndoManagerListener(
 314                 [in] XUndoManagerListener iListener
 315             );
 316
 317     /** removes a previously added listener
 318     */
 319     void    removeUndoManagerListener(
 320                 [in] XUndoManagerListener iListener
 321             );
 322 };
 323
 324
 325 }; }; }; };
 326
 327
 328 #endif
 329
 330 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */