|
129
|
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.IDocumentPartitioner;
|
|
|
14
|
|
|
15 import dwt.dwthelper.utils;
|
|
|
16
|
|
|
17
|
|
|
18
|
|
|
19 /**
|
|
|
20 * A document partitioner divides a document into a set
|
|
|
21 * of disjoint text partitions. Each partition has a content type, an
|
|
|
22 * offset, and a length. The document partitioner is connected to one document
|
|
|
23 * and informed about all changes of this document before any of the
|
|
|
24 * document's document listeners. A document partitioner can thus
|
|
|
25 * incrementally update on the receipt of a document change event.<p>
|
|
|
26 *
|
|
|
27 * In order to provided backward compatibility for clients of <code>IDocumentPartitioner</code>, extension
|
|
|
28 * interfaces are used to provide a means of evolution. The following extension interfaces
|
|
|
29 * exist:
|
|
|
30 * <ul>
|
|
|
31 * <li> {@link dwtx.jface.text.IDocumentPartitionerExtension} since version 2.0 replacing
|
|
|
32 * the <code>documentChanged</code> method with a new one returning the minimal document region
|
|
|
33 * comprising all partition changes.</li>
|
|
|
34 * <li> {@link dwtx.jface.text.IDocumentPartitionerExtension2} since version 3.0
|
|
|
35 * introducing zero-length partitions in conjunction with the distinction between
|
|
|
36 * open and closed partitions. Also provides inside in the implementation of the partitioner
|
|
|
37 * by exposing the position category used for managing the partitioning information.</li>
|
|
|
38 * <li> {@link dwtx.jface.text.IDocumentPartitionerExtension3} since version 3.1 introducing
|
|
|
39 * rewrite session. It also replaces the existing {@link #connect(IDocument)} method with
|
|
|
40 * a new one: {@link dwtx.jface.text.IDocumentPartitionerExtension3#connect(IDocument, bool)}.
|
|
|
41 * </ul>
|
|
|
42 * <p>
|
|
|
43 * Clients may implement this interface and its extension interfaces or use the standard
|
|
|
44 * implementation <code>DefaultPartitioner</code>.
|
|
|
45 * </p>
|
|
|
46 *
|
|
|
47 * @see dwtx.jface.text.IDocumentPartitionerExtension
|
|
|
48 * @see dwtx.jface.text.IDocumentPartitionerExtension2
|
|
|
49 * @see dwtx.jface.text.IDocument
|
|
|
50 */
|
|
|
51 public interface IDocumentPartitioner {
|
|
|
52
|
|
|
53 /**
|
|
|
54 * Connects the partitioner to a document.
|
|
|
55 * Connect indicates the begin of the usage of the receiver
|
|
|
56 * as partitioner of the given document. Thus, resources the partitioner
|
|
|
57 * needs to be operational for this document should be allocated.<p>
|
|
|
58 *
|
|
|
59 * The caller of this method must ensure that this partitioner is
|
|
|
60 * also set as the document's document partitioner.<p>
|
|
|
61 *
|
|
|
62 * This method has been replaced with {@link IDocumentPartitionerExtension3#connect(IDocument, bool)}.
|
|
|
63 * Implementers should default a call <code>connect(document)</code> to
|
|
|
64 * <code>connect(document, false)</code> in order to sustain the same semantics.
|
|
|
65 *
|
|
|
66 * @param document the document to be connected to
|
|
|
67 */
|
|
|
68 void connect(IDocument document);
|
|
|
69
|
|
|
70 /**
|
|
|
71 * Disconnects the partitioner from the document it is connected to.
|
|
|
72 * Disconnect indicates the end of the usage of the receiver as
|
|
|
73 * partitioner of the connected document. Thus, resources the partitioner
|
|
|
74 * needed to be operation for its connected document should be deallocated.<p>
|
|
|
75 * The caller of this method should also must ensure that this partitioner is
|
|
|
76 * no longer the document's partitioner.
|
|
|
77 */
|
|
|
78 void disconnect();
|
|
|
79
|
|
|
80 /**
|
|
|
81 * Informs about a forthcoming document change. Will be called by the
|
|
|
82 * connected document and is not intended to be used by clients
|
|
|
83 * other than the connected document.
|
|
|
84 *
|
|
|
85 * @param event the event describing the forthcoming change
|
|
|
86 */
|
|
|
87 void documentAboutToBeChanged(DocumentEvent event);
|
|
|
88
|
|
|
89 /**
|
|
|
90 * The document has been changed. The partitioner updates
|
|
|
91 * the document's partitioning and returns whether the structure of the
|
|
|
92 * document partitioning has been changed, i.e. whether partitions
|
|
|
93 * have been added or removed. Will be called by the connected document and
|
|
|
94 * is not intended to be used by clients other than the connected document.<p>
|
|
|
95 *
|
|
|
96 * This method has been replaced by {@link IDocumentPartitionerExtension#documentChanged2(DocumentEvent)}.
|
|
|
97 *
|
|
|
98 * @param event the event describing the document change
|
|
|
99 * @return <code>true</code> if partitioning changed
|
|
|
100 */
|
|
|
101 bool documentChanged(DocumentEvent event);
|
|
|
102
|
|
|
103 /**
|
|
|
104 * Returns the set of all legal content types of this partitioner.
|
|
|
105 * I.e. any result delivered by this partitioner may not contain a content type
|
|
|
106 * which would not be included in this method's result.
|
|
|
107 *
|
|
|
108 * @return the set of legal content types
|
|
|
109 */
|
|
|
110 String[] getLegalContentTypes();
|
|
|
111
|
|
|
112 /**
|
|
|
113 * Returns the content type of the partition containing the
|
|
|
114 * given offset in the connected document. There must be a
|
|
|
115 * document connected to this partitioner.<p>
|
|
|
116 *
|
|
|
117 * Use {@link IDocumentPartitionerExtension2#getContentType(int, bool)} when
|
|
|
118 * zero-length partitions are supported. In that case this method is
|
|
|
119 * equivalent:
|
|
|
120 * <pre>
|
|
|
121 * IDocumentPartitionerExtension2 extension= (IDocumentPartitionerExtension2) partitioner;
|
|
|
122 * return extension.getContentType(offset, false);
|
|
|
123 * </pre>
|
|
|
124 *
|
|
|
125 * @param offset the offset in the connected document
|
|
|
126 * @return the content type of the offset's partition
|
|
|
127 */
|
|
|
128 String getContentType(int offset);
|
|
|
129
|
|
|
130 /**
|
|
|
131 * Returns the partitioning of the given range of the connected
|
|
|
132 * document. There must be a document connected to this partitioner.<p>
|
|
|
133 *
|
|
|
134 * Use {@link IDocumentPartitionerExtension2#computePartitioning(int, int, bool)} when
|
|
|
135 * zero-length partitions are supported. In that case this method is
|
|
|
136 * equivalent:
|
|
|
137 * <pre>
|
|
|
138 * IDocumentPartitionerExtension2 extension= (IDocumentPartitionerExtension2) partitioner;
|
|
|
139 * return extension.computePartitioning(offset, length, false);
|
|
|
140 * </pre>
|
|
|
141 *
|
|
|
142 * @param offset the offset of the range of interest
|
|
|
143 * @param length the length of the range of interest
|
|
|
144 * @return the partitioning of the range
|
|
|
145 */
|
|
|
146 ITypedRegion[] computePartitioning(int offset, int length);
|
|
|
147
|
|
|
148 /**
|
|
|
149 * Returns the partition containing the given offset of
|
|
|
150 * the connected document. There must be a document connected to this
|
|
|
151 * partitioner.<p>
|
|
|
152 *
|
|
|
153 * Use {@link IDocumentPartitionerExtension2#getPartition(int, bool)} when
|
|
|
154 * zero-length partitions are supported. In that case this method is
|
|
|
155 * equivalent:
|
|
|
156 * <pre>
|
|
|
157 * IDocumentPartitionerExtension2 extension= (IDocumentPartitionerExtension2) partitioner;
|
|
|
158 * return extension.getPartition(offset, false);
|
|
|
159 * </pre>
|
|
|
160 *
|
|
|
161 * @param offset the offset for which to determine the partition
|
|
|
162 * @return the partition containing the offset
|
|
|
163 */
|
|
|
164 ITypedRegion getPartition(int offset);
|
|
|
165 }
|
