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