Mercurial > projects > dwt-addons

comparison dwtx/jface/text/IDocumentExtension4.d @ 129:eb30df5ca28b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added JFace Text sources
author Frank Benoit <benoit@tionex.de>
date Sat, 23 Aug 2008 19:10:48 +0200
parents
children c4fb132a086c
comparison
equal deleted inserted replaced
128:8df1d4193877 129:eb30df5ca28b
1 /*******************************************************************************
2 * Copyright (c) 2000, 2005 IBM Corporation and others.
3 * All rights reserved. This program and the accompanying materials
4 * are made available under the terms of the Eclipse Public License v1.0
5 * which accompanies this distribution, and is available at
6 * http://www.eclipse.org/legal/epl-v10.html
7 *
8 * Contributors:
9 * IBM Corporation - initial API and implementation
10 * Port to the D programming language:
11 * Frank Benoit <benoit@tionex.de>
12 *******************************************************************************/
13 module dwtx.jface.text.IDocumentExtension4;
14
15 import dwt.dwthelper.utils;
16
17 /**
18 * Extension interface for {@link dwtx.jface.text.IDocument}. It adds the
19 * following concepts:
20 * <ul>
21 * <li>Rewrite sessions. A rewrite session is a sequence of replace operations
22 * that form a semantic unit.</li>
23 * <li>A modification stamp on the document</li>
24 * <li>The ability to set the initial line delimiter and to query the default
25 * line delimiter</li>
26 * </ul>
27 *
28 * @since 3.1
29 */
30 public interface IDocumentExtension4 {
31
32 /**
33 * Tells the document that it is about to be rewritten. That is, a sequence
34 * of replace operations that form a semantic unit will be performed on this
35 * document. A specification of the nature of the operation sequence is
36 * given in form of the session type.
37 * <p>
38 * The document is considered being in rewrite mode as long as
39 * <code>stopRewriteSession</code> has not been called.
40 *
41 * @param sessionType the session type
42 * @return the started rewrite session
43 * @throws IllegalStateException in case there is already an active rewrite session
44 */
45 DocumentRewriteSession startRewriteSession(DocumentRewriteSessionType sessionType) throws IllegalStateException;
46
47 /**
48 * Tells the document to stop the rewrite session. This method has only any
49 * effect if <code>startRewriteSession</code> has been called before.
50 * <p>
51 * This method does not have any effect if the given session is not the
52 * active rewrite session.
53 *
54 * @param session the session to stop
55 */
56 void stopRewriteSession(DocumentRewriteSession session);
57
58 /**
59 * Returns the active rewrite session of this document or <code>null</code>.
60 *
61 * @return the active rewrite session or <code>null</code>
62 */
63 DocumentRewriteSession getActiveRewriteSession();
64
65 /**
66 * Registers the document rewrite session listener with the document. After
67 * registration the <code>IDocumentRewriteSessionListener</code> is
68 * informed about each state change of rewrite sessions performed on this
69 * document.
70 * <p>
71 * If the listener is already registered nothing happens.
72 * <p>
73 * An <code>IRewriteSessionDocumentListener</code> may call back to this
74 * document when being inside a document notification.
75 *
76 * @param listener the listener to be registered
77 */
78 void addDocumentRewriteSessionListener(IDocumentRewriteSessionListener listener);
79
80 /**
81 * Removes the listener from the document's list of document rewrite session
82 * listeners. If the listener is not registered with the document nothing
83 * happens.
84 * <p>
85 * An <code>IDocumentRewriteSessionListener</code> may call back to this
86 * document when being inside a document notification.
87 *
88 * @param listener the listener to be removed
89 */
90 void removeDocumentRewriteSessionListener(IDocumentRewriteSessionListener listener);
91
92 /**
93 * Substitutes the given text for the specified document range.
94 * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>.
95 *
96 * @param offset the document offset
97 * @param length the length of the specified range
98 * @param text the substitution text
99 * @param modificationStamp of the document after replacing
100 * @exception BadLocationException if the offset is invalid in this document
101 *
102 * @see DocumentEvent
103 * @see IDocumentListener
104 */
105 void replace(int offset, int length, String text, 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 }