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