IDocumentUndoManager


1   /*******************************************************************************
2    * Copyright (c) 2006 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.text.undo;
12  
13  import org.eclipse.core.commands.ExecutionException;
14  import org.eclipse.core.commands.operations.IUndoContext;
15  
16  /**
17   * Interface for a document undo manager. Tracks changes in a document and
18   * builds a history of text commands that describe the undoable changes to the
19   * document.
20   * <p>
21   * Clients must explicitly connect to the undo manager to express their interest
22   * in the undo history. Clients should disconnect from the undo manager when
23   * they are no longer interested in tracking the undo history. If there are no
24   * clients connected to the undo manager, it will not track the document's
25   * changes and will dispose of any history that was previously kept.</p>
26   * <p>
27   * Clients may also listen to the undo manager for notifications before and
28   * after undo or redo events are performed. Clients must connect to the undo
29   * manager in addition to registering listeners.</p>
30   * <p>
31   * Clients may implement this interface.
32   * </p>
33   * 
34   * @see DocumentUndoManagerRegistry
35   * @see IDocumentUndoListener
36   * @see org.eclipse.jface.text.IDocument
37   * @since 3.2
38   */
39  public interface IDocumentUndoManager {
40  
41      /**
42       * Adds the specified listener to the list of document undo listeners that
43       * are notified before and after changes are undone or redone in the
44       * document. This method has no effect if the instance being added is
45       * already in the list.
46       * <p>
47       * Notifications will not be received if there are no clients connected to
48       * the receiver. Registering a document undo listener does not implicitly
49       * connect the listener to the receiver.</p>
50       * <p>
51       * Document undo listeners must be prepared to receive notifications from a
52       * background thread. Any UI access occurring inside the implementation must
53       * be properly synchronized using the techniques specified by the client's
54       * widget library.</p>
55       * 
56       * @param listener the document undo listener to be added as a listener
57       */
58      void addDocumentUndoListener(IDocumentUndoListener listener);
59  
60      /**
61       * Removes the specified listener from the list of document undo listeners.
62       * <p>
63       * Removing a listener which is not registered has no effect
64       * </p>
65       * 
66       * @param listener the document undo listener to be removed
67       */
68      void removeDocumentUndoListener(IDocumentUndoListener listener);
69  
70      /**
71       * Returns the undo context registered for this document
72       * 
73       * @return the undo context registered for this document
74       */
75      IUndoContext getUndoContext();
76  
77      /**
78       * Closes the currently open text edit and open a new one.
79       */
80      void commit();
81  
82      /**
83       * Connects to the undo manager. Used to signify that a client is monitoring
84       * the history kept by the undo manager. This message has no effect if the
85       * client is already connected.
86       * 
87       * @param client the object connecting to the undo manager
88       */
89      void connect(Object   client);
90  
91      /**
92       * Disconnects from the undo manager. Used to signify that a client is no
93       * longer monitoring the history kept by the undo manager. If all clients
94       * have disconnected from the undo manager, the undo history will be
95       * deleted.
96       * 
97       * @param client the object disconnecting from the undo manager
98       */
99      void disconnect(Object   client);
100 
101     /**
102      * Signals the undo manager that all subsequent changes until
103      * <code>endCompoundChange</code> is called are to be undone in one piece.
104      */
105     void beginCompoundChange();
106 
107     /**
108      * Signals the undo manager that the sequence of changes which started with
109      * <code>beginCompoundChange</code> has been finished. All subsequent
110      * changes are considered to be individually undo-able.
111      */
112     void endCompoundChange();
113 
114     /**
115      * Sets the limit of the undo history to the specified value. The provided
116      * limit will supersede any previously set limit.
117      * 
118      * @param undoLimit the length of this undo manager's history
119      */
120     void setMaximalUndoLevel(int undoLimit);
121     
122     /**
123      * Resets the history of the undo manager. After that call,
124      * there aren't any undo-able or redo-able text changes.
125      */
126     void reset();
127 
128     /**
129      * Returns whether at least one text change can be rolled back.
130      *
131      * @return <code>true</code> if at least one text change can be rolled back
132      */
133     boolean undoable();
134 
135     /**
136      * Returns whether at least one text change can be repeated. A text change
137      * can be repeated only if it was executed and rolled back.
138      *
139      * @return <code>true</code> if at least on text change can be repeated
140      */
141     boolean redoable();
142 
143     /**
144      * Rolls back the most recently executed text change.
145      * 
146      * @throws ExecutionException if an exception occurred during undo
147      */
148     void undo() throws ExecutionException;
149 
150     /**
151      * Repeats the most recently rolled back text change.
152      * 
153      * @throws ExecutionException if an exception occurred during redo
154      */
155     void redo() throws ExecutionException;
156 
157     /**
158      * Transfers the undo history from the specified document undo manager to
159      * this undo manager.  This message should only be used when it is known 
160      * that the content of the document of the original undo manager when the
161      * last undo operation was recorded is the same as this undo manager's 
162      * current document content, since the undo history is based on document
163      * indexes.  It is the responsibility of the caller 
164      * to ensure that this call is used correctly.  
165      * 
166      * @param manager the document undo manger whose history is to be transferred to the receiver
167      */
168     public void transferUndoHistory(IDocumentUndoManager manager);
169 
170 }
171
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags