001    /* UndoableEdit.java --
002       Copyright (C) 2002, 2006, Free Software Foundation, Inc.
003    
004    This file is part of GNU Classpath.
005    
006    GNU Classpath is free software; you can redistribute it and/or modify
007    it under the terms of the GNU General Public License as published by
008    the Free Software Foundation; either version 2, or (at your option)
009    any later version.
010    
011    GNU Classpath is distributed in the hope that it will be useful, but
012    WITHOUT ANY WARRANTY; without even the implied warranty of
013    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
014    General Public License for more details.
015    
016    You should have received a copy of the GNU General Public License
017    along with GNU Classpath; see the file COPYING.  If not, write to the
018    Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
019    02110-1301 USA.
020    
021    Linking this library statically or dynamically with other modules is
022    making a combined work based on this library.  Thus, the terms and
023    conditions of the GNU General Public License cover the whole
024    combination.
025    
026    As a special exception, the copyright holders of this library give you
027    permission to link this library with independent modules to produce an
028    executable, regardless of the license terms of these independent
029    modules, and to copy and distribute the resulting executable under
030    terms of your choice, provided that you also meet, for each linked
031    independent module, the terms and conditions of the license of that
032    module.  An independent module is a module which is not derived from
033    or based on this library.  If you modify this library, you may extend
034    this exception to your version of the library, but you are not
035    obligated to do so.  If you do not wish to do so, delete this
036    exception statement from your version. */
037    
038    package javax.swing.undo;
039    
040    /**
041     * An editing operation that supports undo/redoability.
042     *
043     * @author Andrew Selkirk
044     */
045    public interface UndoableEdit
046    {
047    
048      /**
049       * Incorporates another editing action into this one, thus forming a
050       * combined action.
051       *
052       * @param edit the editing action to be incorporated.
053       *
054       * @return <code>true</code> if the edit was combined successfully, and
055       *         <code>false</code> if it could not be combined.
056       */
057      boolean addEdit(UndoableEdit edit);
058    
059      /**
060       * Determines whether it would be possible to redo this editing
061       * action.
062       *
063       * @return <code>true</code> to indicate that this action can be
064       * redone, <code>false</code> otherwise.
065       *
066       * @see #redo()
067       * @see #canUndo()
068       */
069      boolean canRedo();
070    
071      /**
072       * Determines whether it would be possible to undo this editing
073       * action.
074       *
075       * @return <code>true</code> to indicate that this action can be
076       * undone, <code>false</code> otherwise.
077       *
078       * @see #undo()
079       * @see #canRedo()
080       */
081      boolean canUndo();
082    
083      /**
084       * Informs this edit action that it will no longer be used. Some
085       * actions might use this information to release resources, for
086       * example open files.  Called by {@link UndoManager} before this
087       * action is removed from the edit queue.
088       */
089      void die();
090    
091      /**
092       * Returns a human-readable, localized name that describes this
093       * editing action and can be displayed to the user.
094       *
095       * @return The presentation name.
096       */
097      String getPresentationName();
098    
099      /**
100       * Returns the redo presentation name.
101       *
102       * @return The redo presentation name.
103       */
104      String getRedoPresentationName();
105    
106      /**
107       * Returns the undo presentation name.
108       *
109       * @return The undo presentation name.
110       */
111      String getUndoPresentationName();
112    
113      /**
114       * Determines whether this editing action is significant enough for
115       * being seperately undoable by the user. A typical significant
116       * action would be the resizing of an object. However, changing the
117       * selection in a text document would usually not be considered
118       * significant.
119       *
120       * @return <code>true</code> to indicate that the action is
121       * significant enough for being separately undoable, or
122       * <code>false</code> otherwise.
123       */
124      boolean isSignificant();
125    
126      /**
127       * Redoes this editing action.
128       *
129       * @throws CannotRedoException if the edit cannot be undone.
130       *
131       * @see #canRedo()
132       * @see #undo()
133       */
134      void redo() throws CannotRedoException;
135    
136      /**
137       * Incorporates another editing action into this one, thus forming a
138       * combined action that replaces the argument action.
139       *
140       * @param edit the editing action to be replaced.
141       *
142       * @return <code>true</code> if the edit is successfully replaced, and
143       *         <code>false</code> otherwise.
144       */
145      boolean replaceEdit(UndoableEdit edit);
146    
147      /**
148       * Undoes this editing action.
149       *
150       * @throws CannotUndoException if the edit cannot be undone.
151       *
152       * @see #canUndo()
153       * @see #redo()
154       */
155      void undo() throws CannotUndoException;
156    
157    }