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