< prev index next >

src/java.desktop/share/classes/javax/swing/undo/UndoableEdit.java

Print this page

        

*** 26,69 **** package javax.swing.undo; import javax.swing.event.*; /** ! * An <code>UndoableEdit</code> represents an edit. The edit may * be undone, or if already undone the edit may be redone. * <p> ! * <code>UndoableEdit</code> is designed to be used with the ! * <code>UndoManager</code>. As <code>UndoableEdit</code>s are generated ! * by an <code>UndoableEditListener</code> they are typically added to ! * the <code>UndoManager</code>. When an <code>UndoableEdit</code> ! * is added to an <code>UndoManager</code> the following occurs (assuming ! * <code>end</code> has not been called on the <code>UndoManager</code>): * <ol> ! * <li>If the <code>UndoManager</code> contains edits it will call ! * <code>addEdit</code> on the current edit passing in the new edit ! * as the argument. If <code>addEdit</code> returns true the * new edit is assumed to have been incorporated into the current edit and * the new edit will not be added to the list of current edits. ! * Edits can use <code>addEdit</code> as a way for smaller edits to * be incorporated into a larger edit and treated as a single edit. ! * <li>If <code>addEdit</code> returns false <code>replaceEdit</code> * is called on the new edit with the current edit passed in as the ! * argument. This is the inverse of <code>addEdit</code> — ! * if the new edit returns true from <code>replaceEdit</code>, the new * edit replaces the current edit. * </ol> ! * The <code>UndoManager</code> makes use of ! * <code>isSignificant</code> to determine how many edits should be ! * undone or redone. The <code>UndoManager</code> will undo or redo ! * all insignificant edits (<code>isSignificant</code> returns false) * between the current edit and the last or ! * next significant edit. <code>addEdit</code> and ! * <code>replaceEdit</code> can be used to treat multiple edits as ! * a single edit, returning false from <code>isSignificant</code> * allows for treating can be used to * have many smaller edits undone or redone at once. Similar functionality ! * can also be done using the <code>addEdit</code> method. * * @author Ray Ryan */ public interface UndoableEdit { /** --- 26,69 ---- package javax.swing.undo; import javax.swing.event.*; /** ! * An {@code UndoableEdit} represents an edit. The edit may * be undone, or if already undone the edit may be redone. * <p> ! * {@code UndoableEdit} is designed to be used with the ! * {@code UndoManager}. As {@code UndoableEdit}s are generated ! * by an {@code UndoableEditListener} they are typically added to ! * the {@code UndoManager}. When an {@code UndoableEdit} ! * is added to an {@code UndoManager} the following occurs (assuming ! * {@code end} has not been called on the {@code UndoManager}): * <ol> ! * <li>If the {@code UndoManager} contains edits it will call ! * {@code addEdit} on the current edit passing in the new edit ! * as the argument. If {@code addEdit} returns true the * new edit is assumed to have been incorporated into the current edit and * the new edit will not be added to the list of current edits. ! * Edits can use {@code addEdit} as a way for smaller edits to * be incorporated into a larger edit and treated as a single edit. ! * <li>If {@code addEdit} returns false {@code replaceEdit} * is called on the new edit with the current edit passed in as the ! * argument. This is the inverse of {@code addEdit} — ! * if the new edit returns true from {@code replaceEdit}, the new * edit replaces the current edit. * </ol> ! * The {@code UndoManager} makes use of ! * {@code isSignificant} to determine how many edits should be ! * undone or redone. The {@code UndoManager} will undo or redo ! * all insignificant edits ({@code isSignificant} returns false) * between the current edit and the last or ! * next significant edit. {@code addEdit} and ! * {@code replaceEdit} can be used to treat multiple edits as ! * a single edit, returning false from {@code isSignificant} * allows for treating can be used to * have many smaller edits undone or redone at once. Similar functionality ! * can also be done using the {@code addEdit} method. * * @author Ray Ryan */ public interface UndoableEdit { /**
*** 94,174 **** */ public boolean canRedo(); /** * Informs the edit that it should no longer be used. Once an ! * <code>UndoableEdit</code> has been marked as dead it can no longer * be undone or redone. * <p> * This is a useful hook for cleaning up state no longer * needed once undoing or redoing is impossible--for example, * deleting file resources used by objects that can no longer be ! * undeleted. <code>UndoManager</code> calls this before it dequeues edits. * <p> * Note that this is a one-way operation. There is no "un-die" * method. * * @see CompoundEdit#die */ public void die(); /** ! * Adds an <code>UndoableEdit</code> to this <code>UndoableEdit</code>. * This method can be used to coalesce smaller edits into a larger * compound edit. For example, text editors typically allow * undo operations to apply to words or sentences. The text * editor may choose to generate edits on each key event, but allow * those edits to be coalesced into a more user-friendly unit, such as ! * a word. In this case, the <code>UndoableEdit</code> would ! * override <code>addEdit</code> to return true when the edits may * be coalesced. * <p> ! * A return value of true indicates <code>anEdit</code> was incorporated ! * into this edit. A return value of false indicates <code>anEdit</code> * may not be incorporated into this edit. * <p>Typically the receiver is already in the queue of a ! * <code>UndoManager</code> (or other <code>UndoableEditListener</code>), ! * and is being given a chance to incorporate <code>anEdit</code> * rather than letting it be added to the queue in turn.</p> * ! * <p>If true is returned, from now on <code>anEdit</code> must return ! * false from <code>canUndo</code> and <code>canRedo</code>, ! * and must throw the appropriate exception on <code>undo</code> or ! * <code>redo</code>.</p> * * @param anEdit the edit to be added ! * @return true if <code>anEdit</code> may be incorporated into this * edit */ public boolean addEdit(UndoableEdit anEdit); /** ! * Returns true if this <code>UndoableEdit</code> should replace ! * <code>anEdit</code>. This method is used by <code>CompoundEdit</code> ! * and the <code>UndoManager</code>; it is called if ! * <code>anEdit</code> could not be added to the current edit ! * (<code>addEdit</code> returns false). * <p> * This method provides a way for an edit to replace an existing edit. * <p>This message is the opposite of addEdit--anEdit has typically ! * already been queued in an <code>UndoManager</code> (or other * UndoableEditListener), and the receiver is being given a chance * to take its place.</p> * * <p>If true is returned, from now on anEdit must return false from * canUndo() and canRedo(), and must throw the appropriate * exception on undo() or redo().</p> * * @param anEdit the edit that replaces the current edit ! * @return true if this edit should replace <code>anEdit</code> */ public boolean replaceEdit(UndoableEdit anEdit); /** * Returns true if this edit is considered significant. A significant * edit is typically an edit that should be presented to the user, perhaps ! * on a menu item or tooltip. The <code>UndoManager</code> will undo, * or redo, all insignificant edits to the next significant edit. * * @return true if this edit is significant */ public boolean isSignificant(); --- 94,174 ---- */ public boolean canRedo(); /** * Informs the edit that it should no longer be used. Once an ! * {@code UndoableEdit} has been marked as dead it can no longer * be undone or redone. * <p> * This is a useful hook for cleaning up state no longer * needed once undoing or redoing is impossible--for example, * deleting file resources used by objects that can no longer be ! * undeleted. {@code UndoManager} calls this before it dequeues edits. * <p> * Note that this is a one-way operation. There is no "un-die" * method. * * @see CompoundEdit#die */ public void die(); /** ! * Adds an {@code UndoableEdit} to this {@code UndoableEdit}. * This method can be used to coalesce smaller edits into a larger * compound edit. For example, text editors typically allow * undo operations to apply to words or sentences. The text * editor may choose to generate edits on each key event, but allow * those edits to be coalesced into a more user-friendly unit, such as ! * a word. In this case, the {@code UndoableEdit} would ! * override {@code addEdit} to return true when the edits may * be coalesced. * <p> ! * A return value of true indicates {@code anEdit} was incorporated ! * into this edit. A return value of false indicates {@code anEdit} * may not be incorporated into this edit. * <p>Typically the receiver is already in the queue of a ! * {@code UndoManager} (or other {@code UndoableEditListener}), ! * and is being given a chance to incorporate {@code anEdit} * rather than letting it be added to the queue in turn.</p> * ! * <p>If true is returned, from now on {@code anEdit} must return ! * false from {@code canUndo} and {@code canRedo}, ! * and must throw the appropriate exception on {@code undo} or ! * {@code redo}.</p> * * @param anEdit the edit to be added ! * @return true if {@code anEdit} may be incorporated into this * edit */ public boolean addEdit(UndoableEdit anEdit); /** ! * Returns true if this {@code UndoableEdit} should replace ! * {@code anEdit}. This method is used by {@code CompoundEdit} ! * and the {@code UndoManager}; it is called if ! * {@code anEdit} could not be added to the current edit ! * ({@code addEdit} returns false). * <p> * This method provides a way for an edit to replace an existing edit. * <p>This message is the opposite of addEdit--anEdit has typically ! * already been queued in an {@code UndoManager} (or other * UndoableEditListener), and the receiver is being given a chance * to take its place.</p> * * <p>If true is returned, from now on anEdit must return false from * canUndo() and canRedo(), and must throw the appropriate * exception on undo() or redo().</p> * * @param anEdit the edit that replaces the current edit ! * @return true if this edit should replace {@code anEdit} */ public boolean replaceEdit(UndoableEdit anEdit); /** * Returns true if this edit is considered significant. A significant * edit is typically an edit that should be presented to the user, perhaps ! * on a menu item or tooltip. The {@code UndoManager} will undo, * or redo, all insignificant edits to the next significant edit. * * @return true if this edit is significant */ public boolean isSignificant();
*** 182,201 **** public String getPresentationName(); /** * Returns a localized, human-readable description of the undoable form of * this edit, suitable for use as an Undo menu item, for example. ! * This is typically derived from <code>getPresentationName</code>. * * @return a description of the undoable form of this edit */ public String getUndoPresentationName(); /** * Returns a localized, human-readable description of the redoable form of * this edit, suitable for use as a Redo menu item, for example. This is ! * typically derived from <code>getPresentationName</code>. * * @return a description of the redoable form of this edit */ public String getRedoPresentationName(); } --- 182,201 ---- public String getPresentationName(); /** * Returns a localized, human-readable description of the undoable form of * this edit, suitable for use as an Undo menu item, for example. ! * This is typically derived from {@code getPresentationName}. * * @return a description of the undoable form of this edit */ public String getUndoPresentationName(); /** * Returns a localized, human-readable description of the redoable form of * this edit, suitable for use as a Redo menu item, for example. This is ! * typically derived from {@code getPresentationName}. * * @return a description of the redoable form of this edit */ public String getRedoPresentationName(); }
< prev index next >