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
40published interface XUndoAction;
41published interface 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 */
78published interface 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