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
26package javax.swing.undo;
27
28import 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> &#8212;
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 */
68public 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}
202