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