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