001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.text;
011:
012: /**
013: * Extension interface for {@link org.eclipse.jface.text.IDocument}. It adds the
014: * following concepts:
015: * <ul>
016: * <li>Rewrite sessions. A rewrite session is a sequence of replace operations
017: * that form a semantic unit.</li>
018: * <li>A modification stamp on the document</li>
019: * <li>The ability to set the initial line delimiter and to query the default
020: * line delimiter</li>
021: * </ul>
022: *
023: * @since 3.1
024: */
025: public interface IDocumentExtension4 {
026:
027: /**
028: * Tells the document that it is about to be rewritten. That is, a sequence
029: * of replace operations that form a semantic unit will be performed on this
030: * document. A specification of the nature of the operation sequence is
031: * given in form of the session type.
032: * <p>
033: * The document is considered being in rewrite mode as long as
034: * <code>stopRewriteSession</code> has not been called.
035: *
036: * @param sessionType the session type
037: * @return the started rewrite session
038: * @throws IllegalStateException in case there is already an active rewrite session
039: */
040: DocumentRewriteSession startRewriteSession(
041: DocumentRewriteSessionType sessionType)
042: throws IllegalStateException;
043:
044: /**
045: * Tells the document to stop the rewrite session. This method has only any
046: * effect if <code>startRewriteSession</code> has been called before.
047: * <p>
048: * This method does not have any effect if the given session is not the
049: * active rewrite session.
050: *
051: * @param session the session to stop
052: */
053: void stopRewriteSession(DocumentRewriteSession session);
054:
055: /**
056: * Returns the active rewrite session of this document or <code>null</code>.
057: *
058: * @return the active rewrite session or <code>null</code>
059: */
060: DocumentRewriteSession getActiveRewriteSession();
061:
062: /**
063: * Registers the document rewrite session listener with the document. After
064: * registration the <code>IDocumentRewriteSessionListener</code> is
065: * informed about each state change of rewrite sessions performed on this
066: * document.
067: * <p>
068: * If the listener is already registered nothing happens.
069: * <p>
070: * An <code>IRewriteSessionDocumentListener</code> may call back to this
071: * document when being inside a document notification.
072: *
073: * @param listener the listener to be registered
074: */
075: void addDocumentRewriteSessionListener(
076: IDocumentRewriteSessionListener listener);
077:
078: /**
079: * Removes the listener from the document's list of document rewrite session
080: * listeners. If the listener is not registered with the document nothing
081: * happens.
082: * <p>
083: * An <code>IDocumentRewriteSessionListener</code> may call back to this
084: * document when being inside a document notification.
085: *
086: * @param listener the listener to be removed
087: */
088: void removeDocumentRewriteSessionListener(
089: IDocumentRewriteSessionListener listener);
090:
091: /**
092: * Substitutes the given text for the specified document range.
093: * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>.
094: *
095: * @param offset the document offset
096: * @param length the length of the specified range
097: * @param text the substitution text
098: * @param modificationStamp of the document after replacing
099: * @exception BadLocationException if the offset is invalid in this document
100: *
101: * @see DocumentEvent
102: * @see IDocumentListener
103: */
104: void replace(int offset, int length, String text,
105: long modificationStamp) throws BadLocationException;
106:
107: /**
108: * Replaces the content of the document with the given text.
109: * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>.
110: * This method is a convenience method for <code>replace(0, getLength(), text)</code>.
111: *
112: * @param text the new content of the document
113: * @param modificationStamp of the document after setting the content
114: *
115: * @see DocumentEvent
116: * @see IDocumentListener
117: */
118: void set(String text, long modificationStamp);
119:
120: /**
121: * The unknown modification stamp.
122: */
123: long UNKNOWN_MODIFICATION_STAMP = -1;
124:
125: /**
126: * Returns the modification stamp of this document. The modification stamp
127: * is updated each time a modifying operation is called on this document. If
128: * two modification stamps of the same document are identical then the document
129: * content is too, however, same content does not imply same modification stamp.
130: * <p>
131: * The magnitude or sign of the numerical difference between two modification stamps
132: * is not significant.
133: * </p>
134: *
135: * @return the modification stamp of this document or <code>UNKNOWN_MODIFICATION_STAMP</code>
136: */
137: long getModificationStamp();
138:
139: /**
140: * Returns this document's default line delimiter.
141: * <p>
142: * This default line delimiter should be used by clients who
143: * want unique delimiters (e.g. 'CR's) in the document.</p>
144: *
145: * @return the default line delimiter or <code>null</code> if none
146: */
147: String getDefaultLineDelimiter();
148:
149: /**
150: * Sets this document's initial line delimiter i.e. the one
151: * which is returned by <code>getDefaultLineDelimiter</code>
152: * if the document does not yet contain any line delimiter.
153: *
154: * @param lineDelimiter the default line delimiter
155: */
156: void setInitialLineDelimiter(String lineDelimiter);
157: }
|