01: /*******************************************************************************
02: * Copyright (c) 2000, 2006 IBM Corporation and others.
03: * All rights reserved. This program and the accompanying materials
04: * are made available under the terms of the Eclipse Public License v1.0
05: * which accompanies this distribution, and is available at
06: * http://www.eclipse.org/legal/epl-v10.html
07: *
08: * Contributors:
09: * IBM Corporation - initial API and implementation
10: *******************************************************************************/package org.eclipse.jface.text;
11:
12: /**
13: * Extension interface for {@link org.eclipse.jface.text.IDocument}.<p>
14: *
15: * It introduces the notion of sequentially rewriting a document. This is to tell a
16: * document that a sequence of non-overlapping replace operation is about to be
17: * performed. Implementers can use this knowledge for internal optimization.<p>
18: *
19: * Is also introduces the concept of post notification replaces. This is, a document
20: * listener who is informed about a document change can cause a derived document
21: * change. As the listener is not allowed to directly modify the document, it can
22: * register a replace operation that is performed directly after all document listeners
23: * have been notified.
24: *
25: * @since 2.0
26: */
27: public interface IDocumentExtension {
28:
29: /**
30: * Interface for a post notification replace operation.
31: */
32: public interface IReplace {
33:
34: /**
35: * Executes the replace operation on the given document.
36: *
37: * @param document the document to be changed
38: * @param owner the owner of this replace operation
39: */
40: void perform(IDocument document, IDocumentListener owner);
41: }
42:
43: /**
44: * Callback for document listeners to be used inside <code>documentChanged</code>
45: * to register a post notification replace operation on the document notifying them.
46: *
47: * @param owner the owner of the replace operation
48: * @param replace the replace operation to be executed
49: * @exception UnsupportedOperationException if <code>registerPostNotificationReplace</code>
50: * is not supported by this document
51: */
52: void registerPostNotificationReplace(IDocumentListener owner,
53: IReplace replace) throws UnsupportedOperationException;
54:
55: /**
56: * Stops the processing of registered post notification replace operations until
57: * <code>resumePostNotificationProcessing</code> is called.
58: */
59: void stopPostNotificationProcessing();
60:
61: /**
62: * Resumes the processing of post notification replace operations. If the queue of registered
63: * <code>IDocumentExtension.IReplace</code> objects is not empty, they are immediately processed if the
64: * document is not inside a replace operation. If the document is inside a replace operation,
65: * they are processed directly after the replace operation has finished.
66: */
67: void resumePostNotificationProcessing();
68:
69: /**
70: * Tells the document that it is about to be sequentially rewritten. That is a
71: * sequence of non-overlapping replace operations will be performed on it. The
72: * <code>normalize</code> flag indicates whether the rewrite is performed from
73: * the start of the document to its end or from an arbitrary start offset. <p>
74: *
75: * The document is considered being in sequential rewrite mode as long as
76: * <code>stopSequentialRewrite</code> has not been called.
77: *
78: * @param normalize <code>true</code> if performed from the start to the end of the document
79: * @deprecated since 3.1. Use {@link IDocumentExtension4#startRewriteSession(DocumentRewriteSessionType)} instead.
80: */
81: void startSequentialRewrite(boolean normalize);
82:
83: /**
84: * Tells the document that the sequential rewrite has been finished. This method
85: * has only any effect if <code>startSequentialRewrite</code> has been called before.
86: * @deprecated since 3.1. Use {@link IDocumentExtension4#stopRewriteSession(DocumentRewriteSession)} instead.
87: */
88: void stopSequentialRewrite();
89: }
|