View Javadoc
1   /*
2    * Copyright (c) 1997, 2005, Oracle and/or its affiliates. All rights reserved.
3    * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4    *
5    * This code is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU General Public License version 2 only, as
7    * published by the Free Software Foundation.  Oracle designates this
8    * particular file as subject to the "Classpath" exception as provided
9    * by Oracle in the LICENSE file that accompanied this code.
10   *
11   * This code is distributed in the hope that it will be useful, but WITHOUT
12   * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13   * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
14   * version 2 for more details (a copy is included in the LICENSE file that
15   * accompanied this code).
16   *
17   * You should have received a copy of the GNU General Public License version
18   * 2 along with this work; if not, write to the Free Software Foundation,
19   * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20   *
21   * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22   * or visit www.oracle.com if you need additional information or have any
23   * questions.
24   */
25  
26  package javax.swing.undo;
27  
28  import javax.swing.event.*;
29  
30  /**
31   * An <code>UndoableEdit</code> represents an edit.  The edit may
32   * be undone, or if already undone the edit may be redone.
33   * <p>
34   * <code>UndoableEdit</code> is designed to be used with the
35   * <code>UndoManager</code>.  As <code>UndoableEdit</code>s are generated
36   * by an <code>UndoableEditListener</code> they are typically added to
37   * the <code>UndoManager</code>.  When an <code>UndoableEdit</code>
38   * is added to an <code>UndoManager</code> the following occurs (assuming
39   * <code>end</code> has not been called on the <code>UndoManager</code>):
40   * <ol>
41   * <li>If the <code>UndoManager</code> contains edits it will call
42   *     <code>addEdit</code> on the current edit passing in the new edit
43   *     as the argument.  If <code>addEdit</code> returns true the
44   *     new edit is assumed to have been incorporated into the current edit and
45   *     the new edit will not be added to the list of current edits.
46   *     Edits can use <code>addEdit</code> as a way for smaller edits to
47   *     be incorporated into a larger edit and treated as a single edit.
48   * <li>If <code>addEdit</code> returns false <code>replaceEdit</code>
49   *     is called on the new edit with the current edit passed in as the
50   *     argument. This is the inverse of <code>addEdit</code> &#151;
51   *     if the new edit returns true from <code>replaceEdit</code>, the new
52   *     edit replaces the current edit.
53   * </ol>
54   * The <code>UndoManager</code> makes use of
55   * <code>isSignificant</code> to determine how many edits should be
56   * undone or redone.  The <code>UndoManager</code> will undo or redo
57   * all insignificant edits (<code>isSignificant</code> returns false)
58   * between the current edit and the last or
59   * next significant edit.   <code>addEdit</code> and
60   * <code>replaceEdit</code> can be used to treat multiple edits as
61   * a single edit, returning false from <code>isSignificant</code>
62   * allows for treating can be used to
63   * have many smaller edits undone or redone at once.  Similar functionality
64   * can also be done using the <code>addEdit</code> method.
65   *
66   * @author Ray Ryan
67   */
68  public interface UndoableEdit {
69      /**
70       * Undo the edit.
71       *
72       * @throws CannotUndoException if this edit can not be undone
73       */
74      public void undo() throws CannotUndoException;
75  
76      /**
77       * Returns true if this edit may be undone.
78       *
79       * @return true if this edit may be undone
80       */
81      public boolean canUndo();
82  
83      /**
84       * Re-applies the edit.
85       *
86       * @throws CannotRedoException if this edit can not be redone
87       */
88      public void redo() throws CannotRedoException;
89  
90      /**
91       * Returns true if this edit may be redone.
92       *
93       * @return true if this edit may be redone
94       */
95      public boolean canRedo();
96  
97      /**
98       * Informs the edit that it should no longer be used. Once an
99       * <code>UndoableEdit</code> has been marked as dead it can no longer
100      * be undone or redone.
101      * <p>
102      * This is a useful hook for cleaning up state no longer
103      * needed once undoing or redoing is impossible--for example,
104      * deleting file resources used by objects that can no longer be
105      * undeleted. <code>UndoManager</code> calls this before it dequeues edits.
106      * <p>
107      * Note that this is a one-way operation. There is no "un-die"
108      * method.
109      *
110      * @see CompoundEdit#die
111      */
112     public void die();
113 
114     /**
115      * Adds an <code>UndoableEdit</code> to this <code>UndoableEdit</code>.
116      * This method can be used to coalesce smaller edits into a larger
117      * compound edit.  For example, text editors typically allow
118      * undo operations to apply to words or sentences.  The text
119      * editor may choose to generate edits on each key event, but allow
120      * those edits to be coalesced into a more user-friendly unit, such as
121      * a word. In this case, the <code>UndoableEdit</code> would
122      * override <code>addEdit</code> to return true when the edits may
123      * be coalesced.
124      * <p>
125      * A return value of true indicates <code>anEdit</code> was incorporated
126      * into this edit.  A return value of false indicates <code>anEdit</code>
127      * may not be incorporated into this edit.
128      * <p>Typically the receiver is already in the queue of a
129      * <code>UndoManager</code> (or other <code>UndoableEditListener</code>),
130      * and is being given a chance to incorporate <code>anEdit</code>
131      * rather than letting it be added to the queue in turn.</p>
132      *
133      * <p>If true is returned, from now on <code>anEdit</code> must return
134      * false from <code>canUndo</code> and <code>canRedo</code>,
135      * and must throw the appropriate exception on <code>undo</code> or
136      * <code>redo</code>.</p>
137      *
138      * @param anEdit the edit to be added
139      * @return true if <code>anEdit</code> may be incorporated into this
140      *              edit
141      */
142     public boolean addEdit(UndoableEdit anEdit);
143 
144     /**
145      * Returns true if this <code>UndoableEdit</code> should replace
146      * <code>anEdit</code>. This method is used by <code>CompoundEdit</code>
147      * and the <code>UndoManager</code>; it is called if
148      * <code>anEdit</code> could not be added to the current edit
149      * (<code>addEdit</code> returns false).
150      * <p>
151      * This method provides a way for an edit to replace an existing edit.
152      * <p>This message is the opposite of addEdit--anEdit has typically
153      * already been queued in an <code>UndoManager</code> (or other
154      * UndoableEditListener), and the receiver is being given a chance
155      * to take its place.</p>
156      *
157      * <p>If true is returned, from now on anEdit must return false from
158      * canUndo() and canRedo(), and must throw the appropriate
159      * exception on undo() or redo().</p>
160      *
161      * @param anEdit the edit that replaces the current edit
162      * @return true if this edit should replace <code>anEdit</code>
163      */
164     public boolean replaceEdit(UndoableEdit anEdit);
165 
166     /**
167      * Returns true if this edit is considered significant.  A significant
168      * edit is typically an edit that should be presented to the user, perhaps
169      * on a menu item or tooltip.  The <code>UndoManager</code> will undo,
170      * or redo, all insignificant edits to the next significant edit.
171      *
172      * @return true if this edit is significant
173      */
174     public boolean isSignificant();
175 
176     /**
177      * Returns a localized, human-readable description of this edit, suitable
178      * for use in a change log, for example.
179      *
180      * @return description of this edit
181      */
182     public String getPresentationName();
183 
184     /**
185      * Returns a localized, human-readable description of the undoable form of
186      * this edit, suitable for use as an Undo menu item, for example.
187      * This is typically derived from <code>getPresentationName</code>.
188      *
189      * @return a description of the undoable form of this edit
190      */
191     public String getUndoPresentationName();
192 
193     /**
194      * Returns a localized, human-readable description of the redoable form of
195      * this edit, suitable for use as a Redo menu item, for example. This is
196      * typically derived from <code>getPresentationName</code>.
197      *
198      * @return a description of the redoable form of this edit
199      */
200     public String getRedoPresentationName();
201 }