Mercurial > projects > dwt-addons
annotate dwtx/jface/text/IDocument.d @ 200:eb3414669eb0 default tip
fix for dmd 1.041 and tango 0.99.8
| author | Frank Benoit <benoit@tionex.de> |
|---|---|
| date | Sat, 28 Mar 2009 03:09:57 +0100 |
| parents | 7926b636c282 |
| children |
| rev | line source |
|---|---|
| 129 | 1 /******************************************************************************* |
| 2 * Copyright (c) 2000, 2007 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 | |
| 131 | 14 |
| 151 | 15 module dwtx.jface.text.IDocument; |
| 16 | |
| 131 | 17 import dwtx.jface.text.IDocumentPartitioningListener; // packageimport |
| 18 import dwtx.jface.text.IDocumentPartitioner; // packageimport | |
| 19 import dwtx.jface.text.IRegion; // packageimport | |
| 20 import dwtx.jface.text.IDocumentListener; // packageimport | |
| 21 import dwtx.jface.text.Position; // packageimport | |
| 22 import dwtx.jface.text.IPositionUpdater; // packageimport | |
| 23 import dwtx.jface.text.ITypedRegion; // packageimport | |
| 24 | |
| 129 | 25 import dwt.dwthelper.utils; |
| 26 | |
| 27 | |
| 28 /** | |
| 29 * An <code>IDocument</code> represents text providing support for | |
| 30 * <ul> | |
| 31 * <li> text manipulation | |
| 32 * <li> positions | |
| 33 * <li> partitions | |
| 34 * <li> line information | |
| 35 * <li> document change listeners | |
| 36 * <li> document partition change listeners | |
| 37 * </ul> | |
| 38 * | |
| 39 * A document allows to set its content and to manipulate it. For manipulation | |
| 40 * a document provides the <code>replace</code> method which substitutes a given | |
| 41 * string for a specified text range in the document. On each document change, all | |
| 42 * registered document listeners are informed exactly once. | |
| 43 * <p> | |
| 44 * Positions are stickers to the document's text that are updated when the | |
| 45 * document is changed. Positions are updated by {@link dwtx.jface.text.IPositionUpdater}s. Position | |
| 46 * updaters are managed as a list. The list defines the sequence in which position | |
| 47 * updaters are invoked. This way, position updaters may rely on each other. | |
| 48 * Positions are grouped into categories. A category is a ordered list of positions. | |
| 49 * the document defines the order of position in a category based on the position's offset | |
| 50 * based on the implementation of the method <code>computeIndexInCategory</code>. | |
| 51 * Each document must support a default position category whose name is specified by this | |
| 52 * interface.</p> | |
| 53 * <p> | |
| 54 * A document can be considered consisting of a sequence of not overlapping partitions. | |
| 55 * A partition is defined by its offset, its length, and its type. Partitions are | |
| 56 * updated on every document manipulation and ensured to be up-to-date when the document | |
| 57 * listeners are informed. A document uses an <code>IDocumentPartitioner</code> to | |
| 58 * manage its partitions. A document may be unpartitioned which happens when there is no | |
| 59 * partitioner. In this case, the document is considered as one single partition of a | |
| 60 * default type. The default type is specified by this interface. If a document change | |
| 61 * changes the document's partitioning all registered partitioning listeners are | |
| 62 * informed exactly once. The extension interface {@link dwtx.jface.text.IDocumentExtension3} | |
| 63 * introduced in version 3.0 extends the concept of partitions and allows a document to | |
| 64 * not only manage one but multiple partitioning. Each partitioning has an id which must | |
| 65 * be used to refer to a particular partitioning.</p> | |
| 66 * <p> | |
| 67 * An <code>IDocument</code> provides methods to map line numbers and character | |
| 68 * positions onto each other based on the document's line delimiters. When moving text | |
| 69 * between documents using different line delimiters, the text must be converted to | |
| 70 * use the target document's line delimiters.</p> | |
| 71 * <p> | |
| 72 * An <code>IDocument</code> does not care about mixed line delimiters. Clients who | |
| 73 * want to ensure a single line delimiter in their document should use the line | |
| 74 * delimiter returned by {@link dwtx.jface.text.TextUtilities#getDefaultLineDelimiter(IDocument)}.</p> | |
| 75 * <p> | |
| 76 * <code>IDocument</code> throws <code>BadLocationException</code> if the parameters of | |
| 77 * queries or manipulation requests are not inside the bounds of the document. The purpose | |
| 78 * of this style of exception handling is | |
| 79 * <ul> | |
| 80 * <li> prepare document for multi-thread access | |
| 81 * <li> allow clients to implement backtracking recovery methods | |
| 82 * <li> prevent clients from up-front contract checking when dealing with documents. | |
| 83 * </ul></p> | |
| 84 * <p> | |
| 85 * A document support for searching has deprecated since version 3.0. The recommended way | |
| 86 * for searching is to use a {@link dwtx.jface.text.FindReplaceDocumentAdapter}.</p> | |
| 87 * <p> | |
| 88 * In order to provide backward compatibility for clients of <code>IDocument</code>, extension | |
| 89 * interfaces are used to provide a means of evolution. The following extension interfaces | |
| 90 * exist: | |
| 91 * <ul> | |
| 92 * <li> {@link dwtx.jface.text.IDocumentExtension} since version 2.0 introducing the concept | |
| 93 * of post notification replaces in order to allow document listeners to manipulate the document | |
| 94 * while receiving a document change notification </li> | |
| 95 * <li> {@link dwtx.jface.text.IDocumentExtension2} since version 2.1 introducing configuration | |
| 96 * methods for post notification replaces and document change notification. </li> | |
| 97 * <li> {@link dwtx.jface.text.IDocumentExtension3} since version 3.0 replacing the original | |
| 98 * partitioning concept by allowing multiple partitionings at the same time and introducing zero- | |
| 99 * length partitions in conjunction with the distinction between open and closed partitions. </li> | |
| 100 * <li> {@link dwtx.jface.text.IDocumentExtension4} since version 3.1 introducing the | |
| 101 * concept of rewrite sessions. A rewrite session is a sequence of document replace operations | |
| 102 * that form a semantic unit. It also introduces a modification stamp and the ability to | |
| 103 * set the initial line delimiter and to query the default line delimiter.</li> | |
| 104 * </ul></p> | |
| 105 * <p> | |
| 106 * Clients may implement this interface and its extension interfaces or use the default | |
| 107 * implementation provided by <code>AbstractDocument</code> and <code>Document</code>.</p> | |
| 159 | 108 * |
| 129 | 109 * @see dwtx.jface.text.IDocumentExtension |
| 110 * @see dwtx.jface.text.IDocumentExtension2 | |
| 111 * @see dwtx.jface.text.IDocumentExtension3 | |
| 112 * @see dwtx.jface.text.IDocumentExtension4 | |
| 113 * @see dwtx.jface.text.Position | |
| 114 * @see dwtx.jface.text.IPositionUpdater | |
| 115 * @see dwtx.jface.text.IDocumentPartitioner | |
| 116 * @see dwtx.jface.text.ILineTracker | |
| 117 * @see dwtx.jface.text.IDocumentListener | |
| 118 * @see dwtx.jface.text.IDocumentPartitioningListener | |
| 119 */ | |
| 120 public interface IDocument { | |
| 121 | |
| 122 | |
| 123 /** | |
| 124 * The identifier of the default position category. | |
| 125 */ | |
| 126 final static String DEFAULT_CATEGORY= "__dflt_position_category"; //$NON-NLS-1$ | |
| 127 | |
| 128 /** | |
| 129 * The identifier of the default partition content type. | |
| 130 */ | |
| 131 final static String DEFAULT_CONTENT_TYPE= "__dftl_partition_content_type"; //$NON-NLS-1$ | |
| 132 | |
| 133 | |
| 134 | |
| 135 | |
| 136 /* --------------- text access and manipulation --------------------------- */ | |
| 137 | |
| 138 /** | |
| 139 * Returns the character at the given document offset in this document. | |
| 140 * | |
| 141 * @param offset a document offset | |
| 142 * @return the character at the offset | |
| 143 * @exception BadLocationException if the offset is invalid in this document | |
| 144 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
145 char getChar(int offset) ; |
| 129 | 146 |
| 147 /** | |
| 148 * Returns the number of characters in this document. | |
| 149 * | |
| 150 * @return the number of characters in this document | |
| 151 */ | |
| 152 int getLength(); | |
| 153 | |
| 154 /** | |
| 155 * Returns this document's complete text. | |
| 156 * | |
| 157 * @return the document's complete text | |
| 158 */ | |
| 159 String get(); | |
| 160 | |
| 161 /** | |
| 162 * Returns this document's text for the specified range. | |
| 163 * | |
| 164 * @param offset the document offset | |
| 165 * @param length the length of the specified range | |
| 166 * @return the document's text for the specified range | |
| 167 * @exception BadLocationException if the range is invalid in this document | |
| 168 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
169 String get(int offset, int length) ; |
| 129 | 170 |
| 171 /** | |
| 172 * Replaces the content of the document with the given text. | |
| 173 * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>. | |
| 174 * This method is a convenience method for <code>replace(0, getLength(), text)</code>. | |
| 175 * | |
| 176 * @param text the new content of the document | |
| 177 * | |
| 178 * @see DocumentEvent | |
| 179 * @see IDocumentListener | |
| 180 */ | |
| 181 void set(String text); | |
| 182 | |
| 183 /** | |
| 184 * Substitutes the given text for the specified document range. | |
| 185 * Sends a <code>DocumentEvent</code> to all registered <code>IDocumentListener</code>. | |
| 186 * | |
| 187 * @param offset the document offset | |
| 188 * @param length the length of the specified range | |
| 189 * @param text the substitution text | |
| 190 * @exception BadLocationException if the offset is invalid in this document | |
| 191 * | |
| 192 * @see DocumentEvent | |
| 193 * @see IDocumentListener | |
| 194 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
195 void replace(int offset, int length, String text) ; |
| 129 | 196 |
| 197 /** | |
| 198 * Registers the document listener with the document. After registration | |
| 199 * the IDocumentListener is informed about each change of this document. | |
| 200 * If the listener is already registered nothing happens.<p> | |
| 201 * An <code>IDocumentListener</code> may call back to this method | |
| 202 * when being inside a document notification. | |
| 203 * | |
| 204 * @param listener the listener to be registered | |
| 205 */ | |
| 206 void addDocumentListener(IDocumentListener listener); | |
| 207 | |
| 208 /** | |
| 209 * Removes the listener from the document's list of document listeners. | |
| 210 * If the listener is not registered with the document nothing happens.<p> | |
| 211 * An <code>IDocumentListener</code> may call back to this method | |
| 212 * when being inside a document notification. | |
| 213 * | |
| 214 * @param listener the listener to be removed | |
| 215 */ | |
| 216 void removeDocumentListener(IDocumentListener listener); | |
| 217 | |
| 218 /** | |
| 219 * Adds the given document listener as one which is notified before | |
| 220 * those document listeners added with <code>addDocumentListener</code> | |
| 221 * are notified. If the given listener is also registered using | |
| 222 * <code>addDocumentListener</code> it will be notified twice. | |
| 223 * If the listener is already registered nothing happens.<p> | |
| 224 * | |
| 225 * This method is not for public use. | |
| 226 * | |
| 227 * @param documentAdapter the listener to be added as pre-notified document listener | |
| 228 * | |
| 229 * @see #removePrenotifiedDocumentListener(IDocumentListener) | |
| 230 */ | |
| 231 void addPrenotifiedDocumentListener(IDocumentListener documentAdapter); | |
| 232 | |
| 233 /** | |
| 234 * Removes the given document listener from the document's list of | |
| 235 * pre-notified document listeners. If the listener is not registered | |
| 236 * with the document nothing happens. <p> | |
| 237 * | |
| 238 * This method is not for public use. | |
| 239 * | |
| 240 * @param documentAdapter the listener to be removed | |
| 241 * | |
| 242 * @see #addPrenotifiedDocumentListener(IDocumentListener) | |
| 243 */ | |
| 244 void removePrenotifiedDocumentListener(IDocumentListener documentAdapter); | |
| 245 | |
| 246 | |
| 247 | |
| 248 /* -------------------------- positions ----------------------------------- */ | |
| 249 | |
| 250 /** | |
| 251 * Adds a new position category to the document. If the position category | |
| 252 * already exists nothing happens. | |
| 253 * | |
| 254 * @param category the category to be added | |
| 255 */ | |
| 256 void addPositionCategory(String category); | |
| 257 | |
| 258 /** | |
| 259 * Deletes the position category from the document. All positions | |
| 260 * in this category are thus deleted as well. | |
| 261 * | |
| 262 * @param category the category to be removed | |
| 263 * @exception BadPositionCategoryException if category is undefined in this document | |
| 264 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
265 void removePositionCategory(String category) ; |
| 129 | 266 |
| 267 /** | |
| 268 * Returns all position categories of this document. This | |
| 269 * includes the default position category. | |
| 270 * | |
| 271 * @return the document's position categories | |
| 272 */ | |
| 273 String[] getPositionCategories(); | |
| 274 | |
| 275 /** | |
| 276 * Checks the presence of the specified position category. | |
| 277 * | |
| 278 * @param category the category to check | |
| 279 * @return <code>true</code> if category is defined | |
| 280 */ | |
| 281 bool containsPositionCategory(String category); | |
| 282 | |
| 283 /** | |
| 284 * Adds the position to the document's default position category. | |
| 285 * This is a convenience method for <code>addPosition(DEFAULT_CATEGORY, position)</code>. | |
| 286 * | |
| 287 * @param position the position to be added | |
| 288 * @exception BadLocationException if position describes an invalid range in this document | |
| 289 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
290 void addPosition(Position position) ; |
| 129 | 291 |
| 292 /** | |
| 293 * Removes the given position from the document's default position category. | |
| 294 * This is a convenience method for <code>removePosition(DEFAULT_CATEGORY, position)</code>. | |
| 295 * | |
| 296 * @param position the position to be removed | |
| 297 */ | |
| 298 void removePosition(Position position); | |
| 299 | |
| 300 /** | |
| 301 * Adds the position to the specified position category of the document. | |
| 302 * Positions may be added multiple times. The order of the category is | |
| 303 * maintained. | |
| 304 * <p> | |
| 305 * <strong>Note:</strong> The position is only updated on each change | |
| 306 * applied to the document if a {@link IPositionUpdater} has been | |
| 307 * registered that handles the given category. | |
| 308 * </p> | |
| 309 * | |
| 310 * @param category the category to which to add | |
| 311 * @param position the position to be added | |
| 312 * @throws BadLocationException if position describes an invalid range in this document | |
| 313 * @throws BadPositionCategoryException if the category is undefined in this document | |
| 314 */ | |
| 141 | 315 void addPosition(String category, Position position); |
| 129 | 316 |
| 317 /** | |
| 318 * Removes the given position from the specified position category. | |
| 319 * If the position is not part of the specified category nothing happens. | |
| 320 * If the position has been added multiple times, only the first occurrence is deleted. | |
| 321 * | |
| 322 * @param category the category from which to delete | |
| 323 * @param position the position to be deleted | |
| 324 * @exception BadPositionCategoryException if category is undefined in this document | |
| 325 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
326 void removePosition(String category, Position position) ; |
| 129 | 327 |
| 328 /** | |
| 329 * Returns all positions of the given position category. | |
| 330 * The positions are ordered according to the category's order. | |
| 331 * Manipulating this list does not affect the document, but manipulating the | |
| 332 * position does affect the document. | |
| 333 * | |
| 334 * @param category the category | |
| 335 * @return the list of all positions | |
| 336 * @exception BadPositionCategoryException if category is undefined in this document | |
| 337 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
338 Position[] getPositions(String category) ; |
| 129 | 339 |
| 340 /** | |
| 341 * Determines whether a position described by the parameters is managed by this document. | |
| 342 * | |
| 343 * @param category the category to check | |
| 344 * @param offset the offset of the position to find | |
| 345 * @param length the length of the position to find | |
| 346 * @return <code>true</code> if position is found | |
| 347 */ | |
| 348 bool containsPosition(String category, int offset, int length); | |
| 349 | |
| 350 /** | |
| 351 * Computes the index at which a <code>Position</code> with the | |
| 352 * specified offset would be inserted into the given category. As the | |
| 353 * ordering inside a category only depends on the offset, the index must be | |
| 354 * chosen to be the first of all positions with the same offset. | |
| 355 * | |
| 356 * @param category the category in which would be added | |
| 357 * @param offset the position offset to be considered | |
| 358 * @return the index into the category | |
| 359 * @exception BadLocationException if offset is invalid in this document | |
| 360 * @exception BadPositionCategoryException if category is undefined in this document | |
| 361 */ | |
| 141 | 362 int computeIndexInCategory(String category, int offset); |
| 129 | 363 |
| 364 /** | |
| 365 * Appends a new position updater to the document's list of position updaters. | |
| 366 * Position updaters may be added multiple times.<p> | |
| 367 * An <code>IPositionUpdater</code> may call back to this method | |
| 368 * when being inside a document notification. | |
| 369 * | |
| 370 * @param updater the updater to be added | |
| 371 */ | |
| 372 void addPositionUpdater(IPositionUpdater updater); | |
| 373 | |
| 374 /** | |
| 375 * Removes the position updater from the document's list of position updaters. | |
| 376 * If the position updater has multiple occurrences only the first occurrence is | |
| 377 * removed. If the position updater is not registered with this document, nothing | |
| 378 * happens.<p> | |
| 379 * An <code>IPositionUpdater</code> may call back to this method | |
| 380 * when being inside a document notification. | |
| 381 * | |
| 382 * @param updater the updater to be removed | |
| 383 */ | |
| 384 void removePositionUpdater(IPositionUpdater updater); | |
| 385 | |
| 386 /** | |
| 387 * Inserts the position updater at the specified index in the document's | |
| 388 * list of position updaters. Positions updaters may be inserted multiple times.<p> | |
| 389 * An <code>IPositionUpdater</code> may call back to this method | |
| 390 * when being inside a document notification. | |
| 391 * | |
| 392 * @param updater the updater to be inserted | |
| 393 * @param index the index in the document's updater list | |
| 394 */ | |
| 395 void insertPositionUpdater(IPositionUpdater updater, int index); | |
| 396 | |
| 397 /** | |
| 398 * Returns the list of position updaters attached to the document. | |
| 399 * | |
| 400 * @return the list of position updaters | |
| 401 */ | |
| 402 IPositionUpdater[] getPositionUpdaters(); | |
| 403 | |
| 404 | |
| 405 | |
| 406 | |
| 407 /* -------------------------- partitions ---------------------------------- */ | |
| 408 | |
| 409 /** | |
| 410 * Returns the set of legal content types of document partitions. | |
| 411 * This set can be empty. The set can contain more content types than | |
| 412 * contained by the result of <code>getPartitioning(0, getLength())</code>. | |
| 413 * <p> | |
| 414 * Use {@link IDocumentExtension3#getLegalContentTypes(String)} when the document | |
| 415 * supports multiple partitionings. In that case this method is equivalent to: | |
| 416 * <pre> | |
| 134 | 417 * IDocumentExtension3 extension= cast(IDocumentExtension3) document; |
| 129 | 418 * return extension.getLegalContentTypes(IDocumentExtension3.DEFAULT_PARTITIONING); |
| 419 * </pre> | |
| 420 * | |
| 421 * @return the set of legal content types | |
| 422 */ | |
| 423 String[] getLegalContentTypes(); | |
| 424 | |
| 425 /** | |
| 426 * Returns the type of the document partition containing the given offset. | |
| 427 * This is a convenience method for <code>getPartition(offset).getType()</code>. | |
| 428 * <p> | |
| 429 * Use {@link IDocumentExtension3#getContentType(String, int, bool)} when | |
| 430 * the document supports multiple partitionings. In that case this method is | |
| 431 * equivalent to: | |
| 432 * <pre> | |
| 134 | 433 * IDocumentExtension3 extension= cast(IDocumentExtension3) document; |
| 129 | 434 * return extension.getContentType(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false); |
| 435 * </pre> | |
| 436 * | |
| 437 * @param offset the document offset | |
| 438 * @return the partition type | |
| 439 * @exception BadLocationException if offset is invalid in this document | |
| 440 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
441 String getContentType(int offset) ; |
| 129 | 442 |
| 443 /** | |
| 444 * Returns the document partition in which the position is located. | |
| 445 * <p> | |
| 446 * Use {@link IDocumentExtension3#getPartition(String, int, bool)} when | |
| 447 * the document supports multiple partitionings. In that case this method is | |
| 448 * equivalent: | |
| 449 * <pre> | |
| 134 | 450 * IDocumentExtension3 extension= cast(IDocumentExtension3) document; |
| 129 | 451 * return extension.getPartition(IDocumentExtension3.DEFAULT_PARTITIONING, offset, false); |
| 452 * </pre> | |
| 453 * | |
| 454 * @param offset the document offset | |
| 455 * @return a specification of the partition | |
| 456 * @exception BadLocationException if offset is invalid in this document | |
| 457 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
458 ITypedRegion getPartition(int offset) ; |
| 129 | 459 |
| 460 /** | |
| 461 * Computes the partitioning of the given document range using the | |
| 462 * document's partitioner. | |
| 463 * <p> | |
| 464 * Use {@link IDocumentExtension3#computePartitioning(String, int, int, bool)} when | |
| 465 * the document supports multiple partitionings. In that case this method is | |
| 466 * equivalent: | |
| 467 * <pre> | |
| 134 | 468 * IDocumentExtension3 extension= cast(IDocumentExtension3) document; |
| 129 | 469 * return extension.computePartitioning(IDocumentExtension3.DEFAULT_PARTITIONING, offset, length, false); |
| 470 * </pre> | |
| 471 * | |
| 472 * @param offset the document offset at which the range starts | |
| 473 * @param length the length of the document range | |
| 474 * @return a specification of the range's partitioning | |
| 475 * @exception BadLocationException if the range is invalid in this document | |
| 476 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
477 ITypedRegion[] computePartitioning(int offset, int length) ; |
| 129 | 478 |
| 479 /** | |
| 480 * Registers the document partitioning listener with the document. After registration | |
| 481 * the document partitioning listener is informed about each partition change | |
| 482 * cause by a document manipulation or by changing the document's partitioner. | |
| 483 * If a document partitioning listener is also | |
| 484 * a document listener, the following notification sequence is guaranteed if a | |
| 485 * document manipulation changes the document partitioning: | |
| 486 * <ul> | |
| 487 * <li>listener.documentAboutToBeChanged(DocumentEvent); | |
| 488 * <li>listener.documentPartitioningChanged(); | |
| 489 * <li>listener.documentChanged(DocumentEvent); | |
| 490 * </ul> | |
| 491 * If the listener is already registered nothing happens.<p> | |
| 492 * An <code>IDocumentPartitioningListener</code> may call back to this method | |
| 493 * when being inside a document notification. | |
| 494 * | |
| 495 * @param listener the listener to be added | |
| 496 */ | |
| 497 void addDocumentPartitioningListener(IDocumentPartitioningListener listener); | |
| 498 | |
| 499 /** | |
| 500 * Removes the listener from this document's list of document partitioning | |
| 501 * listeners. If the listener is not registered with the document nothing | |
| 502 * happens.<p> | |
| 503 * An <code>IDocumentPartitioningListener</code> may call back to this method | |
| 504 * when being inside a document notification. | |
| 505 * | |
| 506 * @param listener the listener to be removed | |
| 507 */ | |
| 508 void removeDocumentPartitioningListener(IDocumentPartitioningListener listener); | |
| 509 | |
| 510 /** | |
| 511 * Sets this document's partitioner. The caller of this method is responsible for | |
| 512 * disconnecting the document's old partitioner from the document and to | |
| 513 * connect the new partitioner to the document. Informs all document partitioning | |
| 514 * listeners about this change. | |
| 515 * <p> | |
| 516 * Use {@link IDocumentExtension3#setDocumentPartitioner(String, IDocumentPartitioner)} when | |
| 517 * the document supports multiple partitionings. In that case this method is equivalent to: | |
| 518 * <pre> | |
| 134 | 519 * IDocumentExtension3 extension= cast(IDocumentExtension3) document; |
| 129 | 520 * extension.setDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING, partitioner); |
| 521 * </pre> | |
| 522 * | |
| 523 * @param partitioner the document's new partitioner | |
| 524 * | |
| 525 * @see IDocumentPartitioningListener | |
| 526 */ | |
| 527 void setDocumentPartitioner(IDocumentPartitioner partitioner); | |
| 528 | |
| 529 /** | |
| 530 * Returns this document's partitioner. | |
| 531 * <p> | |
| 532 * Use {@link IDocumentExtension3#getDocumentPartitioner(String)} when | |
| 533 * the document supports multiple partitionings. In that case this method is | |
| 534 * equivalent to: | |
| 535 * <pre> | |
| 134 | 536 * IDocumentExtension3 extension= cast(IDocumentExtension3) document; |
| 129 | 537 * return extension.getDocumentPartitioner(IDocumentExtension3.DEFAULT_PARTITIONING); |
| 538 * </pre> | |
| 539 * | |
| 540 * @return this document's partitioner | |
| 541 */ | |
| 542 IDocumentPartitioner getDocumentPartitioner(); | |
| 543 | |
| 544 | |
| 545 | |
| 546 /* ---------------------- line information -------------------------------- */ | |
| 547 | |
| 548 /** | |
| 549 * Returns the length of the given line including the line's delimiter. | |
| 550 * | |
| 551 * @param line the line of interest | |
| 552 * @return the length of the line | |
| 553 * @exception BadLocationException if the line number is invalid in this document | |
| 554 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
555 int getLineLength(int line) ; |
| 129 | 556 |
| 557 /** | |
| 558 * Returns the number of the line at which the character of the specified position is located. | |
| 559 * The first line has the line number 0. A new line starts directly after a line | |
| 560 * delimiter. <code>(offset is document length)</code> is a valid argument although there is no | |
| 561 * corresponding character. | |
| 562 * | |
| 563 * @param offset the document offset | |
| 564 * @return the number of the line | |
| 565 * @exception BadLocationException if the offset is invalid in this document | |
| 566 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
567 int getLineOfOffset(int offset) ; |
| 129 | 568 |
| 569 /** | |
| 570 * Determines the offset of the first character of the given line. | |
| 571 * | |
| 572 * @param line the line of interest | |
| 573 * @return the document offset | |
| 574 * @exception BadLocationException if the line number is invalid in this document | |
| 575 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
576 int getLineOffset(int line) ; |
| 129 | 577 |
| 578 /** | |
| 579 * Returns a description of the specified line. The line is described by its | |
| 580 * offset and its length excluding the line's delimiter. | |
| 581 * | |
| 582 * @param line the line of interest | |
| 583 * @return a line description | |
| 584 * @exception BadLocationException if the line number is invalid in this document | |
| 585 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
586 IRegion getLineInformation(int line) ; |
| 129 | 587 |
| 588 /** | |
| 589 * Returns a description of the line at the given offset. | |
| 590 * The description contains the offset and the length of the line | |
| 591 * excluding the line's delimiter. | |
| 592 * | |
| 593 * @param offset the offset whose line should be described | |
| 594 * @return a region describing the line | |
| 595 * @exception BadLocationException if offset is invalid in this document | |
| 596 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
597 IRegion getLineInformationOfOffset(int offset) ; |
| 129 | 598 |
| 599 /** | |
| 600 * Returns the number of lines in this document | |
| 601 * | |
| 602 * @return the number of lines in this document | |
| 603 */ | |
| 604 int getNumberOfLines(); | |
| 605 | |
| 606 /** | |
| 607 * Returns the number of lines which are occupied by a given text range. | |
| 608 * | |
| 609 * @param offset the offset of the specified text range | |
| 610 * @param length the length of the specified text range | |
| 611 * @return the number of lines occupied by the specified range | |
| 612 * @exception BadLocationException if specified range is invalid in this tracker | |
| 613 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
614 int getNumberOfLines(int offset, int length) ; |
| 129 | 615 |
| 616 /** | |
| 617 * Computes the number of lines in the given text. For a given | |
| 618 * implementer of this interface this method returns the same | |
| 619 * result as <code>set(text); getNumberOfLines()</code>. | |
| 620 * | |
| 621 * @param text the text whose number of lines should be computed | |
| 622 * @return the number of lines in the given text | |
| 623 */ | |
| 624 int computeNumberOfLines(String text); | |
| 625 | |
| 626 | |
| 627 /* ------------------ line delimiter conversion --------------------------- */ | |
| 628 | |
| 629 /** | |
| 630 * Returns the document's legal line delimiters. | |
| 631 * | |
| 632 * @return the document's legal line delimiters | |
| 633 */ | |
| 634 String[] getLegalLineDelimiters(); | |
| 635 | |
| 636 /** | |
| 637 * Returns the line delimiter of that line or <code>null</code> if the | |
| 638 * line is not closed with a line delimiter. | |
| 639 * | |
| 640 * @param line the line of interest | |
| 641 * @return the line's delimiter or <code>null</code> if line does not have a delimiter | |
| 642 * @exception BadLocationException if the line number is invalid in this document | |
| 643 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
644 String getLineDelimiter(int line) ; |
| 129 | 645 |
| 646 | |
| 647 /* ---------------------------- search ------------------------------------ */ | |
| 648 | |
| 649 /** | |
| 650 * Returns the offset of a given search string in the document based on a set of search criteria. | |
| 651 * | |
| 652 * @param startOffset document offset at which search starts | |
| 653 * @param findString the string to find | |
| 654 * @param forwardSearch the search direction | |
| 655 * @param caseSensitive indicates whether lower and upper case should be distinguished | |
| 656 * @param wholeWord indicates whether the findString should be limited by white spaces as | |
| 657 * defined by Character.isWhiteSpace | |
| 658 * @return the offset of the first occurrence of findString based on the parameters or -1 if no match is found | |
| 659 * @exception BadLocationException if startOffset is an invalid document offset | |
| 660 * @deprecated as of 3.0 search is provided by {@link FindReplaceDocumentAdapter} | |
| 661 */ | |
|
139
93a6ec48fd28
Regexp throws removal in interfaces
Frank Benoit <benoit@tionex.de>
parents:
134
diff
changeset
|
662 int search(int startOffset, String findString, bool forwardSearch, bool caseSensitive, bool wholeWord) ; |
| 129 | 663 } |