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