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 */
76published interface XUndoManager
77{
78    /** allows <a href="#locking">locking</a> the undo manager.
79    */
80    interface ::com::sun::star::util::XLockable;
81
82    /** allows accessing the component, usually a document, which the undo manager works for.
83
84        <p><member scope="com::sun::star::container">XChild::setParent</member> is not supported, and will throw
85        an <type scope="com::sun::star::lang">NoSupportException</type>.</p>
86    */
87    interface ::com::sun::star::container::XChild;
88
89    /** enters a new undo context.
90
91        <p>A new undo action will be added to the undo stack, with the title given as <code>i_title</code>. As long
92        as the context is not left, every undo action added to the stack will be treated as sub action. This means
93        it will not be directly accessible at the Undo manager, not appear in any user interface, and cannot be
94        separately undone or re-done.</p>
95
96        <p>Each call to <code>enterUndoContext</code> must be paired by a call to <member>leaveUndoContext</member>,
97        otherwise, the document's undo stack is left in an inconsistent state.</p>
98
99        <p>Undo contexts can be nested, i.e. it is legitimate to call <code>enterUndoContext</code> and
100        <member>enterHiddenUndoContext</member> multiple times without calling <member>leaveUndoContext</member> inbetween.</p>
101
102        @see leaveUndoContext
103    */
104    void    enterUndoContext(
105                [in] string i_title
106            );
107
108    /** enters a new undo context, creating a hidden undo action.
109
110        <p>A hidden undo action does not, in any visible way, contribute to the undo stack. This means
111        that
112        <ul><li>Calling <member>undo</member> when the top-element is a hidden undo action will transparently
113                undo this action, and also undo the new top element of the stack.</li>
114            <li>Calling <member>redo</member> when the top-element is a hidden action will transparently
115                redo this action, and also redo the new top element of the stack.</li>
116            <li>In any user interface presenting the current Undo or Redo actions to the user, a hidden
117                action will not be listed.</p>
118        </ul>
119
120        <p>A new undo action will be added to the undo stack. As long as the context is not left, every undo action
121        added to the stack will be treated as sub action. This means it will not be directly accessible at the undo
122        manager, not appear in any user interface, and cannot be separately undone or re-done.</p>
123
124        <p>Each call to <code>enterHiddenUndoContext</code> must be paired by a call to <member>leaveUndoContext</member>,
125        otherwise, the document's undo stack is left in an inconsistent state.</p>
126
127        <p>Undo contexts can be nested, i.e. it is legitimate to call <member>enterUndoContext</member> and
128        <code>enterHiddenUndoContext</code> multiple times without calling <member>leaveUndoContext</member> inbetween.</p>
129
130        @throws EmptyUndoStackException
131            if the undo stack is currently empty, in which case it is impossible to push a hidden undo action onto
132            it.
133
134        @see enterUndoContext
135        @see leaveUndoContext
136    */
137    void    enterHiddenUndoContext()
138        raises( EmptyUndoStackException );
139
140    /** leaves the undo context previously opened via <member>enterUndoContext</member> respectively
141        <member>enterHiddenUndoContext</member>.
142
143        <p>If no undo action has been added since the context has been opened, the context is not only left,
144        but silently removed, and does not contribute to the undo stack at all. In this case, possible
145        listeners will be notified via <member>XUndoManagerListener::cancelledContext</member>.</p>
146
147        <p>Otherwise, the undo context will be closed, and added to the Undo stack; the redo stack will be cleared,
148        and listeners will be notified via <member>XUndoManagerListener::leftContext</member> resp.
149        <member>XUndoManagerListener::leftHiddenContext</member></p>
150
151        @throws ::com::sun::star::util::InvalidStateException
152            if no undo context is currently open.
153
154        @see enterUndoContext
155        @see enterHiddenUndoContext
156    */
157    void    leaveUndoContext()
158        raises( ::com::sun::star::util::InvalidStateException );
159
160    /** adds the given undo action to the undo stack.
161
162        <p>The redo stack is cleared when a new action is pushed onto the undo stack.</p>
163
164        <p>The Undo manager takes ownership of any actions pushed onto the undo stack. This means that if the
165        action is finally removed from the Undo manager's control (e.g. by calling <member>clear</member> resp.
166        <member>clearRedo</member>), it will be disposed, as long as it supports the <member scope="com::sun::star::lang">XComponent</member>
167        interface.</p>
168
169        <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
170        will immediately be disposed, if applicable.</p>
171
172        @throws ::com::sun::star::lang::IllegalArgumentException
173            if the given undo action is <NULL/>.
174    */
175    void    addUndoAction(
176                [in] XUndoAction i_action
177            )
178            raises( ::com::sun::star::lang::IllegalArgumentException );
179
180    /** reverts the most recent action on the document.
181
182        <p>Effectively, invoking this method will
183        <ul><li>invoke <member>XUndoAction::undo</member> on the top-most action of the undo stack</li>
184            <li>move this undo action from the undo stack to the redo stack</li>
185        </ul></p>
186
187        @throws EmptyUndoStackException
188            if the undo stack is currently empty
189
190        @throws UndoContextNotClosedException
191            if there currently is an open undo context
192
193        @throws UndoFailedException
194            if the invocation of <member>XUndoAction::undo</member> raised this exception. In this case, the undo stack
195            of the undo manager will have been cleared.
196
197        @see redo
198        @see enterUndoContext
199    */
200    void    undo()
201            raises( ::com::sun::star::document::EmptyUndoStackException,
202                    ::com::sun::star::document::UndoContextNotClosedException,
203                    ::com::sun::star::document::UndoFailedException );
204
205    /** replays the action on the document which has most recently been undone
206
207        <p>Effectively, invoking this method will
208        <ul><li>invoke <member>XUndoAction::redo</member> on the top-most action of the redo stack</li>
209            <li>move this action from the redo stack to the undo stack</li>
210        </ul></p>
211
212        @throws EmptyUndoStackException
213            when the Redo stack is currently empty
214
215        @throws UndoContextNotClosedException
216            if there currently is an open undo context
217
218        @throws UndoFailedException
219            if the invocation of <member>XUndoAction::redo</member> raised this exception. In this case, the redo stack
220            of the undo manager will have been cleared.
221
222        @see undo
223    */
224    void    redo()
225            raises( ::com::sun::star::document::EmptyUndoStackException,
226                    ::com::sun::star::document::UndoContextNotClosedException,
227                    ::com::sun::star::document::UndoFailedException );
228
229    /** determines whether <member>undo</member> can reasonably be expected to succeed.
230
231        @return
232            <FALSE/> if and only if the undo stack is currently empty, or there is an open and not-yet-closed
233            undo context.
234    */
235    boolean isUndoPossible();
236
237    /** determines whether <member>redo</member> can reasonably be expected to succeed.
238
239        @return
240            <FALSE/> if and only if the redo stack is currently empty, or there is an open and not-yet-closed
241            undo context.
242    */
243    boolean isRedoPossible();
244
245    /** returns the title of the top-most action on the undo stack
246
247        @throws EmptyUndoStackException
248            when the undo stack is currently empty
249
250        @see XUndoAction::Title
251    */
252    string  getCurrentUndoActionTitle()
253            raises( ::com::sun::star::document::EmptyUndoStackException );
254
255    /** returns the title of the top-most action on the Redo stack
256
257        @throws EmptyUndoStackException
258            when the Redo stack is currently empty
259        @see XUndoAction::Title
260    */
261    string  getCurrentRedoActionTitle()
262            raises( ::com::sun::star::document::EmptyUndoStackException );
263
264    /** returns the titles of all actions currently on the undo stack, from top to bottom
265        @see XUndoAction::Title
266    */
267    sequence< string >
268            getAllUndoActionTitles();
269
270    /** returns the titles of all actions currently on the Redo stack, from top to bottom
271
272        @see XUndoAction::Title
273    */
274    sequence< string >
275            getAllRedoActionTitles();
276
277    /** clears the undo and the redo stack.
278
279        <p>All actions will be removed from both the Undo and the Redo stack. Actions which implement the
280        <type scope="com::sun::star::lang">XComponent</type> interface will be disposed.</p>
281
282        @throws UndoContextNotClosedException
283            if the method is invoked while an undo context is still open
284    */
285    void    clear()
286            raises( ::com::sun::star::document::UndoContextNotClosedException );
287
288    /** clears the redo stack.
289
290        <p>All actions will be removed from the Redo stack. Actions which implement the <type scope="com::sun::star::lang">XComponent</type>
291        interface will be disposed.</p>
292
293        @throws UndoContextNotClosedException
294            if the method is invoked while an undo context is still open
295    */
296    void    clearRedo()
297            raises( ::com::sun::star::document::UndoContextNotClosedException );
298
299    /** resets the Undo manager
300
301        <p>In particular, this method will
302            <ul><li>remove all locks from the undo manager</li>
303                <li>close all open undo contexts</li>
304                <li>clear the undo stack</li>
305                <li>clear the redo stack</li>
306            </ul></p>
307
308        <p>Note that possible listeners will not get notifications for the single parts of the reset, i.e. there
309        will be no single <member>XUndoManagerListener::allActionsCleared</member>,
310        <member>XUndoManagerListener::leftContext</member>, etc., notifications. Instead, listeners will be
311        notified of the reset by calling their <member>XUndoManagerListener::resetAll</member> method.</p>
312    */
313    void    reset();
314
315    /** adds a listener to be notified of changes in the Undo/Redo stacks.
316    */
317    void    addUndoManagerListener(
318                [in] XUndoManagerListener i_listener
319            );
320
321    /** removes a previously added listener
322    */
323    void    removeUndoManagerListener(
324                [in] XUndoManagerListener i_listener
325            );
326};
327
328//==================================================================================================================
329
330}; }; }; };
331
332//==================================================================================================================
333
334#endif
335