| Frames | No Frames |
1: /* UndoManager.java -- 2: Copyright (C) 2002, 2004, 2005, 2006, Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: 39: package javax.swing.undo; 40: 41: import javax.swing.UIManager; 42: import javax.swing.event.UndoableEditEvent; 43: import javax.swing.event.UndoableEditListener; 44: 45: 46: /** 47: * A manager for providing an application’s undo/redo 48: * functionality. 49: * 50: * <p>Tyipcally, an application will create only one single instance 51: * of UndoManager. When the user performs an undoable action, for 52: * instance changing the color of an object from green to blue, the 53: * application registers an {@link UndoableEdit} object with the 54: * <code>UndoManager</code>. To implement the “undo” and 55: * “redo” menu commands, the application invokes the 56: * UndoManager’s {@link #undo} and {@link #redo} methods. The 57: * human-readable text of these menu commands is provided by {@link 58: * #getUndoPresentationName} and {@link #getRedoPresentationName}, 59: * respectively. To determine whether the menu item should be 60: * selectable or greyed out, use {@link #canUndo} and {@link 61: * #canRedo}. 62: * 63: * <p>The UndoManager will only keep a specified number of editing 64: * actions, the <em>limit</em>. The value of this parameter can be 65: * retrieved by calling {@link #getLimit} and set with {@link 66: * #setLimit}. If more UndoableEdits are added to the UndoManager, 67: * the oldest actions will be discarded. 68: * 69: * <p>Some applications do not provide separate menu commands for 70: * “undo” and “redo.” Instead, they 71: * have just a single command whose text switches between the two. 72: * Such applications would use an UndoManager with a <code>limit</code> 73: * of 1. The text of this combined menu item is available via 74: * {@link #getUndoOrRedoPresentationName}, and it is implemented 75: * by calling {@link #undoOrRedo}. 76: * 77: * <p><b>Thread Safety:</b> In constrast to the other classes of the 78: * <code>javax.swing.undo</code> package, the public methods of an 79: * <code>UndoManager</code> are safe to call from concurrent threads. 80: * The caller does not need to perform external synchronization, and 81: * {@link javax.swing.event.UndoableEditEvent} sources do not need to 82: * broadcast their events from inside the Swing worker thread. 83: * 84: * @author Sascha Brawer (brawer@dandelis.ch) 85: */ 86: public class UndoManager 87: extends CompoundEdit 88: implements UndoableEditListener 89: { 90: /** 91: * The unique ID for serializing instances of this class. Determined 92: * using the <code>serialver</code> tool of Sun JDK 1.4.1_01 on 93: * GNU/Linux. 94: */ 95: static final long serialVersionUID = -2077529998244066750L; 96: 97: 98: /** 99: * An index into the inherited {@link #edits} Vector that indicates 100: * at which position newly added editing actions would get inserted. 101: * 102: * <p>Normally, the value of <code>indexOfNextAdd</code> equals 103: * the number of UndoableEdits stored by this UndoManager, i.e. 104: * <code>edits.size()</code>. For each call to {@link #undo}, 105: * <code>indexOfNextAdd</code> is decremented by one. For each 106: * call to {@link #redo}, it is incremented again. 107: */ 108: int indexOfNextAdd; 109: 110: 111: /** 112: * The maximum number of UndoableEdits stored by this UndoManager. 113: */ 114: int limit; 115: 116: 117: /** 118: * Constructs an UndoManager. 119: * 120: * <p>The <code>limit</code> of the freshly constructed UndoManager 121: * is 100. 122: */ 123: public UndoManager() 124: { 125: limit = 100; 126: } 127: 128: 129: /** 130: * Returns a string representation for this UndoManager. This may be 131: * useful for debugging purposes. For the text of menu items, please 132: * refer to {@link #getUndoPresentationName}, {@link 133: * #getRedoPresentationName}, and {@link 134: * #getUndoOrRedoPresentationName}. 135: */ 136: public String toString() 137: { 138: return super.toString() 139: + " limit: " + limit 140: + " indexOfNextAdd: " + indexOfNextAdd; 141: } 142: 143: 144: /** 145: * Puts this UndoManager into a state where it acts as a normal 146: * {@link CompoundEdit}. It is unlikely that an application would 147: * want to do this. 148: */ 149: public synchronized void end() 150: { 151: super.end(); 152: trimEdits(indexOfNextAdd, edits.size() - 1); 153: } 154: 155: 156: /** 157: * Returns how many edits this UndoManager can maximally hold. 158: * 159: * @see #setLimit 160: */ 161: public synchronized int getLimit() 162: { 163: return limit; 164: } 165: 166: 167: /** 168: * Changes the maximal number of edits that this UndoManager can 169: * process. If there are currently more edits than the new limit 170: * allows, they will receive a {@link UndoableEdit#die() die} 171: * message in reverse order of addition. 172: * 173: * @param limit the new limit. 174: * 175: * @throws IllegalStateException if {@link #end()} has already been 176: * called on this UndoManager. 177: */ 178: public synchronized void setLimit(int limit) 179: { 180: if (!isInProgress()) 181: throw new IllegalStateException(); 182: 183: this.limit = limit; 184: trimForLimit(); 185: } 186: 187: 188: /** 189: * Discards all editing actions that are currently registered with 190: * this UndoManager. Each {@link UndoableEdit} will receive a {@link 191: * UndoableEdit#die() die message}. 192: */ 193: public synchronized void discardAllEdits() 194: { 195: int size; 196: 197: size = edits.size(); 198: for (int i = size - 1; i >= 0; i--) 199: edits.get(i).die(); 200: indexOfNextAdd = 0; 201: edits.clear(); 202: } 203: 204: 205: /** 206: * Called by various internal methods in order to enforce 207: * the <code>limit</code> value. 208: */ 209: protected void trimForLimit() 210: { 211: int high, s; 212: 213: s = edits.size(); 214: 215: /* The Sun J2SE1.4.1_01 implementation can be observed to do 216: * nothing (instead of throwing an exception) with a negative or 217: * zero limit. It may be debatable whether this is the best 218: * behavior, but we replicate it for sake of compatibility. 219: */ 220: if (limit <= 0 || s <= limit) 221: return; 222: 223: high = Math.min(indexOfNextAdd + limit/2 - 1, s - 1); 224: trimEdits(high + 1, s - 1); 225: trimEdits(0, high - limit); 226: } 227: 228: 229: /** 230: * Discards a range of edits. All edits in the range <code>[from 231: * .. to]</code> will receive a {@linkplain UndoableEdit#die() die 232: * message} before being removed from the edits array. If 233: * <code>from</code> is greater than <code>to</code>, nothing 234: * happens. 235: * 236: * @param from the lower bound of the range of edits to be 237: * discarded. 238: * 239: * @param to the upper bound of the range of edits to be discarded. 240: */ 241: protected void trimEdits(int from, int to) 242: { 243: if (from > to) 244: return; 245: 246: for (int i = to; i >= from; i--) 247: edits.get(i).die(); 248: 249: // Remove the range [from .. to] from edits. If from == to, which 250: // is likely to be a very common case, we can do better than 251: // creating a sub-list and clearing it. 252: if (to == from) 253: edits.remove(from); 254: else 255: edits.subList(from, to + 1).clear(); 256: 257: if (indexOfNextAdd > to) 258: indexOfNextAdd = indexOfNextAdd - to + from - 1; 259: else if (indexOfNextAdd >= from) 260: indexOfNextAdd = from; 261: } 262: 263: 264: /** 265: * Determines which significant edit would be undone if {@link 266: * #undo()} was called. 267: * 268: * @return the significant edit that would be undone, or 269: * <code>null</code> if no significant edit would be affected by 270: * calling {@link #undo()}. 271: */ 272: protected UndoableEdit editToBeUndone() 273: { 274: UndoableEdit result; 275: 276: for (int i = indexOfNextAdd - 1; i >= 0; i--) 277: { 278: result = edits.get(i); 279: if (result.isSignificant()) 280: return result; 281: } 282: 283: return null; 284: } 285: 286: 287: /** 288: * Determines which significant edit would be redone if {@link 289: * #redo()} was called. 290: * 291: * @return the significant edit that would be redone, or 292: * <code>null</code> if no significant edit would be affected by 293: * calling {@link #redo()}. 294: */ 295: protected UndoableEdit editToBeRedone() 296: { 297: UndoableEdit result; 298: 299: for (int i = indexOfNextAdd; i < edits.size(); i++) 300: { 301: result = edits.get(i); 302: if (result.isSignificant()) 303: return result; 304: } 305: 306: return null; 307: } 308: 309: 310: /** 311: * Undoes all editing actions in reverse order of addition, 312: * up to the specified action, 313: * 314: * @param edit the last editing action to be undone. 315: */ 316: protected void undoTo(UndoableEdit edit) 317: throws CannotUndoException 318: { 319: UndoableEdit cur; 320: 321: if (!edits.contains(edit)) 322: throw new CannotUndoException(); 323: 324: while (true) 325: { 326: indexOfNextAdd -= 1; 327: cur = edits.get(indexOfNextAdd); 328: cur.undo(); 329: if (cur == edit) 330: return; 331: } 332: } 333: 334: 335: /** 336: * Redoes all editing actions in the same order as they were 337: * added to this UndoManager, up to the specified action. 338: * 339: * @param edit the last editing action to be redone. 340: */ 341: protected void redoTo(UndoableEdit edit) 342: throws CannotRedoException 343: { 344: UndoableEdit cur; 345: 346: if (!edits.contains(edit)) 347: throw new CannotRedoException(); 348: 349: while (true) 350: { 351: cur = edits.get(indexOfNextAdd); 352: indexOfNextAdd += 1; 353: cur.redo(); 354: if (cur == edit) 355: return; 356: } 357: } 358: 359: 360: /** 361: * Undoes or redoes the last action. If the last action has already 362: * been undone, it will be re-done, and vice versa. 363: * 364: * <p>This is useful for applications that do not present a separate 365: * undo and redo facility, but just have a single menu item for 366: * undoing and redoing the very last action. Such applications will 367: * use an <code>UndoManager</code> whose <code>limit</code> is 1. 368: */ 369: public synchronized void undoOrRedo() 370: throws CannotRedoException, CannotUndoException 371: { 372: if (indexOfNextAdd == edits.size()) 373: undo(); 374: else 375: redo(); 376: } 377: 378: 379: /** 380: * Determines whether it would be possible to either undo or redo 381: * this editing action. 382: * 383: * <p>This is useful for applications that do not present a separate 384: * undo and redo facility, but just have a single menu item for 385: * undoing and redoing the very last action. Such applications will 386: * use an <code>UndoManager</code> whose <code>limit</code> is 1. 387: * 388: * @return <code>true</code> to indicate that this action can be 389: * undone or redone; <code>false</code> if neither is possible at 390: * the current time. 391: */ 392: public synchronized boolean canUndoOrRedo() 393: { 394: return indexOfNextAdd == edits.size() ? canUndo() : canRedo(); 395: } 396: 397: 398: /** 399: * Undoes one significant edit action. If insignificant actions have 400: * been posted after the last signficant action, the insignificant 401: * ones will be undone first. 402: * 403: * <p>However, if {@link #end()} has been called on this 404: * UndoManager, it will behave like a normal {@link 405: * CompoundEdit}. In this case, all actions will be undone in 406: * reverse order of addition. Typical applications will never call 407: * {@link #end()} on their <code>UndoManager</code>. 408: * 409: * @throws CannotUndoException if no action can be undone. 410: * 411: * @see #canUndo() 412: * @see #redo() 413: * @see #undoOrRedo() 414: */ 415: public synchronized void undo() 416: throws CannotUndoException 417: { 418: if (!isInProgress()) 419: { 420: super.undo(); 421: return; 422: } 423: 424: UndoableEdit edit = editToBeUndone(); 425: if (edit == null) 426: throw new CannotUndoException(); 427: 428: undoTo(edit); 429: } 430: 431: 432: /** 433: * Determines whether it would be possible to undo this editing 434: * action. 435: * 436: * @return <code>true</code> to indicate that this action can be 437: * undone; <code>false</code> otherwise. 438: * 439: * @see #undo() 440: * @see #canRedo() 441: * @see #canUndoOrRedo() 442: */ 443: public synchronized boolean canUndo() 444: { 445: UndoableEdit edit; 446: 447: if (!isInProgress()) 448: return super.canUndo(); 449: 450: edit = editToBeUndone(); 451: return edit != null && edit.canUndo(); 452: } 453: 454: 455: 456: /** 457: * Redoes one significant edit action. If insignificant actions have 458: * been posted in between, the insignificant ones will be redone 459: * first. 460: * 461: * <p>However, if {@link #end()} has been called on this 462: * UndoManager, it will behave like a normal {@link 463: * CompoundEdit}. In this case, <em>all</em> actions will be redone 464: * in order of addition. Typical applications will never call {@link 465: * #end()} on their <code>UndoManager</code>. 466: * 467: * @throws CannotRedoException if no action can be redone. 468: * 469: * @see #canRedo() 470: * @see #redo() 471: * @see #undoOrRedo() 472: */ 473: public synchronized void redo() 474: throws CannotRedoException 475: { 476: if (!isInProgress()) 477: { 478: super.redo(); 479: return; 480: } 481: 482: UndoableEdit edit = editToBeRedone(); 483: if (edit == null) 484: throw new CannotRedoException(); 485: 486: redoTo(edit); 487: } 488: 489: 490: /** 491: * Determines whether it would be possible to redo this editing 492: * action. 493: * 494: * @return <code>true</code> to indicate that this action can be 495: * redone; <code>false</code> otherwise. 496: * 497: * @see #redo() 498: * @see #canUndo() 499: * @see #canUndoOrRedo() 500: */ 501: public synchronized boolean canRedo() 502: { 503: UndoableEdit edit; 504: 505: if (!isInProgress()) 506: return super.canRedo(); 507: 508: edit = editToBeRedone(); 509: return edit != null && edit.canRedo(); 510: } 511: 512: 513: /** 514: * Registers an undoable editing action with this UndoManager. If 515: * the capacity <code>limit</code> is reached, the oldest action 516: * will be discarded (and receives a {@linkplain UndoableEdit#die() 517: * die message}. Equally, any actions that were undone (but not re-done) 518: * will be discarded, too. 519: * 520: * @param edit the editing action that is added to this UndoManager. 521: * 522: * @return <code>true</code> if <code>edit</code> could be 523: * incorporated; <code>false</code> if <code>edit</code> has not 524: * been incorporated because {@link #end()} has already been called 525: * on this <code>UndoManager</code>. 526: */ 527: public synchronized boolean addEdit(UndoableEdit edit) 528: { 529: boolean result; 530: 531: // Discard any edits starting at indexOfNextAdd. 532: trimEdits(indexOfNextAdd, edits.size() - 1); 533: 534: result = super.addEdit(edit); 535: indexOfNextAdd = edits.size(); 536: trimForLimit(); 537: return result; 538: } 539: 540: 541: /** 542: * Calculates a localized text for presenting the undo or redo 543: * action to the user, for example in the form of a menu command. 544: * 545: * <p>This is useful for applications that do not present a separate 546: * undo and redo facility, but just have a single menu item for 547: * undoing and redoing the very last action. Such applications will 548: * use an <code>UndoManager</code> whose <code>limit</code> is 1. 549: * 550: * @return the redo presentation name if the last action has already 551: * been undone, or the undo presentation name otherwise. 552: * 553: * @see #getUndoPresentationName() 554: * @see #getRedoPresentationName() 555: */ 556: public synchronized String getUndoOrRedoPresentationName() 557: { 558: if (indexOfNextAdd == edits.size()) 559: return getUndoPresentationName(); 560: else 561: return getRedoPresentationName(); 562: } 563: 564: 565: /** 566: * Calculates a localized text for presenting the undo action 567: * to the user, for example in the form of a menu command. 568: */ 569: public synchronized String getUndoPresentationName() 570: { 571: UndoableEdit edit; 572: 573: if (!isInProgress()) 574: return super.getUndoPresentationName(); 575: 576: edit = editToBeUndone(); 577: if (edit == null) 578: return UIManager.getString("AbstractUndoableEdit.undoText"); 579: else 580: return edit.getUndoPresentationName(); 581: } 582: 583: 584: /** 585: * Calculates a localized text for presenting the redo action 586: * to the user, for example in the form of a menu command. 587: */ 588: public synchronized String getRedoPresentationName() 589: { 590: UndoableEdit edit; 591: 592: if (!isInProgress()) 593: return super.getRedoPresentationName(); 594: 595: edit = editToBeRedone(); 596: if (edit == null) 597: return UIManager.getString("AbstractUndoableEdit.redoText"); 598: else 599: return edit.getRedoPresentationName(); 600: } 601: 602: 603: /** 604: * Registers the edit action of an {@link UndoableEditEvent} 605: * with this UndoManager. 606: * 607: * <p><b>Thread Safety:</b> This method may safely be invoked from 608: * concurrent threads. The caller does not need to perform external 609: * synchronization. This means that {@link 610: * javax.swing.event.UndoableEditEvent} sources do not need to broadcast 611: * their events from inside the Swing worker thread. 612: * 613: * @param event the event whose <code>edit</code> will be 614: * passed to {@link #addEdit}. 615: * 616: * @see UndoableEditEvent#getEdit() 617: * @see #addEdit 618: */ 619: public void undoableEditHappened(UndoableEditEvent event) 620: { 621: // Note that this method does not need to be synchronized, 622: // because addEdit will obtain and release the mutex. 623: addEdit(event.getEdit()); 624: } 625: }