net.sourceforge.phpeclipse/src/net/sourceforge/phpdt/internal/corext/textmanipulation/TextEdit.java

   1 /*
   2  * (c) Copyright IBM Corp. 2000, 2001.
   3  * All Rights Reserved.
   4  */
   5 package net.sourceforge.phpdt.internal.corext.textmanipulation;
   6
   7 import org.eclipse.core.runtime.CoreException;
   8
   9 /**
  10  * A text edit describes an elementary text manipulation operation. Text edits
  11  * are executed by adding them to a <code>TextBufferEditor</code> and then
  12  * calling <code>perform</code> on the <code>TextBufferEditor</code>.
  13  * <p>
  14  * After a <code>TextEdit</code> has been added to a <code>TextBufferEditor</code>
  15  * the method <code>connect</code> is sent to the text edit. A <code>TextEdit</code>
  16  * is allowed to do some adjustments of the text range it is going to manipulate while inside
  17  * the hook <code>connect</code>.
  18  *
  19  * @see TextBufferEditor
  20  */
  21 public abstract class TextEdit {
  22
  23         // index that determines the insertion order into a text buffer
  24         /* package */ int index;
  25         /* package */ boolean isSynthetic;
  26
  27         /**
  28          * Connects this text edit to the given <code>TextBufferEditor</code>. A text edit
  29          * must not keep a reference to the passed text buffer editor. It is guaranteed that
  30          * the buffer passed to <code>perform<code> is equal to the buffer managed by
  31          * the given text buffer editor. But they don't have to be identical.
  32          * <p>
  33          * Note that this method <b>should only be called</b> by a <code>
  34          * TextBufferEditor</code>.
  35          *<p>
  36          * This default implementation does nothing. Subclasses may override
  37          * if needed.
  38          *
  39          * @param editor the text buffer editor this text edit has been added to
  40          */
  41         public void connect(TextBufferEditor editor) throws CoreException {
  42                 // does nothing
  43         }
  44
  45         /**
  46          * Returns the <code>TextRange</code> that this text edit is going to
  47          * manipulate. If this method is called before the <code>TextEdit</code>
  48          * has been added to a <code>TextBufferEditor</code> it may return <code>
  49          * null</code> or <code>TextRange.UNDEFINED</code> to indicate this situation.
  50          *
  51          * @return the <code>TextRange</code>s this <code>TextEdit is going
  52          *      to manipulate
  53          */
  54         public abstract TextRange getTextRange();
  55
  56         /**
  57          * Performs the text edit. Note that this method <b>should only be called</b>
  58          * by a <code>TextBufferEditor</code>.
  59          *
  60          * @param buffer the actual buffer to manipulate
  61          * @return a text edit that can undo this text edit
  62          */
  63         public abstract TextEdit perform(TextBuffer buffer) throws CoreException;
  64
  65         /**
  66          * This method gets called after all <code>TextEdit</code>s added to a text buffer
  67          * editor are executed. Implementors of this method can do some clean-up or can
  68          * release allocated resources that are now longer needed.
  69          * <p>
  70          * This default implementation does nothing.
  71          */
  72         public void performed() {
  73                 // do nothing
  74         }
  75
  76         /**
  77      * Creates and returns a copy of this object. The copy method should
  78      * be implemented in a way so that the copy can be added to a different
  79      * <code>TextBufferEditor</code> without causing any harm to the object
  80      * from which the copy has been created.
  81      *
  82      * @return a copy of this object.
  83      */
  84         public abstract TextEdit copy() throws CoreException;
  85
  86         /**
  87          * Returns the element modified by this text edit. The method
  88          * may return <code>null</code> if the modification isn't related to a
  89          * element or if the content of the modified text buffer doesn't
  90          * follow any syntax.
  91          * <p>
  92          * This default implementation returns <code>null</code>
  93          *
  94          * @return the element modified by this text edit
  95          */
  96         public Object getModifiedElement() {
  97                 return null;
  98         }
  99 }
 100