Mercurial > projects > dwt2
comparison org.eclipse.jface.text/src/org/eclipse/jface/text/ITextViewer.d @ 12:bc29606a740c
Added dwt-addons in original directory structure of eclipse.org
author | Frank Benoit <benoit@tionex.de> |
---|---|
date | Sat, 14 Mar 2009 18:23:29 +0100 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
11:43904fec5dca | 12:bc29606a740c |
---|---|
1 /******************************************************************************* | |
2 * Copyright (c) 2000, 2008 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 org.eclipse.jface.text.ITextViewer; | |
14 | |
15 import org.eclipse.jface.text.ITextListener; // packageimport | |
16 import org.eclipse.jface.text.IUndoManager; // packageimport | |
17 import org.eclipse.jface.text.ITextHoverExtension2; // packageimport | |
18 import org.eclipse.jface.text.IViewportListener; // packageimport | |
19 import org.eclipse.jface.text.IRegion; // packageimport | |
20 import org.eclipse.jface.text.IFindReplaceTarget; // packageimport | |
21 import org.eclipse.jface.text.IAutoIndentStrategy; // packageimport | |
22 import org.eclipse.jface.text.ITextHover; // packageimport | |
23 import org.eclipse.jface.text.TextPresentation; // packageimport | |
24 import org.eclipse.jface.text.ITextDoubleClickStrategy; // packageimport | |
25 import org.eclipse.jface.text.ITextInputListener; // packageimport | |
26 import org.eclipse.jface.text.ITextOperationTarget; // packageimport | |
27 import org.eclipse.jface.text.IEventConsumer; // packageimport | |
28 import org.eclipse.jface.text.IDocument; // packageimport | |
29 | |
30 import java.lang.all; | |
31 import java.util.Set; | |
32 | |
33 import org.eclipse.swt.custom.StyledText; | |
34 import org.eclipse.swt.graphics.Color; | |
35 import org.eclipse.swt.graphics.Point; | |
36 import org.eclipse.jface.viewers.ISelectionProvider; | |
37 | |
38 | |
39 /** | |
40 * A text viewer connects a text widget with an | |
41 * {@link org.eclipse.jface.text.IDocument}. The document is used as the | |
42 * widget's text model. | |
43 * <p> | |
44 * It supports the following kinds of listeners: | |
45 * <ul> | |
46 * <li>view port listeners to inform about changes of the viewer's view port</li> | |
47 * <li>text listeners to inform about changes of the document and the | |
48 * subsequent viewer change</li> | |
49 * <li>text input listeners to inform about changes of the viewer's input | |
50 * document.</li> | |
51 * </ul> | |
52 * A text viewer supports a set of configuration options and plug-ins defining | |
53 * its behavior: | |
54 * <ul> | |
55 * <li>undo manager</li> | |
56 * <li>double click behavior</li> | |
57 * <li>auto indentation</li> | |
58 * <li>text hover</li> | |
59 * </ul> | |
60 * Installed plug-ins are not automatically activated. Plug-ins must be | |
61 * activated with the <code>activatePlugins</code> call. Most plug-ins can be | |
62 * defined per content type. Content types are derived from a partitioning of | |
63 * the text viewer's input document. In case of documents that support multiple | |
64 * partitionings, the implementer is responsible for determining the | |
65 * partitioning to use. | |
66 * <p> | |
67 * A text viewer also provides the concept of event consumption. Events handled | |
68 * by the viewer can be filtered and processed by a dynamic event consumer. With | |
69 * {@link org.eclipse.jface.text.ITextViewerExtension}, this mechanism has been | |
70 * replaced with the support for | |
71 * {@link org.eclipse.swt.custom.VerifyKeyListener}. | |
72 * <p> | |
73 * A text viewer provides several text editing functions, some of them are | |
74 * configurable, through a text operation target interface. It also supports a | |
75 * presentation mode in which it only shows a specified section of its document. | |
76 * By calling <code>setVisibleRegion</code> clients define which section is | |
77 * visible. Clients can get access to this section by calling | |
78 * <code>getVisibleRegion</code>. The viewer's presentation mode does not | |
79 * affect any client of the viewer other than text listeners. With | |
80 * {@link org.eclipse.jface.text.ITextViewerExtension5} the visible region | |
81 * support has been reworked. With that extension interface, text viewers are | |
82 * allowed to show fractions of their input document. I.e. a widget selection of | |
83 * two visually neighboring characters is no longer guaranteed to be two | |
84 * neighboring characters in the viewer's input document. Thus, viewers | |
85 * implementing {@link org.eclipse.jface.text.ITextViewerExtension5} are | |
86 * potentially forced to change the fractions of the input document that are | |
87 * shown when clients ask for the visible region. | |
88 * <p> | |
89 * | |
90 * In order to provide backward compatibility for clients of | |
91 * <code>ITextViewer</code>, extension interfaces are used as a means of | |
92 * evolution. The following extension interfaces exist: | |
93 * <ul> | |
94 * <li>{@link org.eclipse.jface.text.ITextViewerExtension} since version 2.0 | |
95 * replacing the event consumer mechanism and introducing the concept of rewrite | |
96 * targets and means to manage the viewer's redraw behavior</li> | |
97 * <li>{@link org.eclipse.jface.text.ITextViewerExtension2}since version 2.1 | |
98 * adding a way to invalidate a viewer's presentation and setters for hovers. | |
99 * </li> | |
100 * <li>{@link org.eclipse.jface.text.ITextViewerExtension3} since version 2.1 | |
101 * which itself was replaced by | |
102 * {@link org.eclipse.jface.text.ITextViewerExtension5} in version 3.0</li> | |
103 * <li>{@link org.eclipse.jface.text.ITextViewerExtension4} since version 3.0 | |
104 * introducing focus handling for widget token keepers and the concept of text | |
105 * presentation listeners.</li> | |
106 * <li>{@link org.eclipse.jface.text.ITextViewerExtension5} since version 3.0 | |
107 * extending the visible region concept with explicit handling and conversion | |
108 * of widget and model coordinates.</li> | |
109 * <li>{@link org.eclipse.jface.text.ITextViewerExtension6} since version 3.1 | |
110 * extending the text viewer with the ability to detect hyperlinks and access the undo manager.</li> | |
111 * <li>{@link org.eclipse.jface.text.ITextViewerExtension7} since version 3.3 | |
112 * extending the text viewer with the ability to install tabs to spaces conversion.</li> | |
113 * <li>{@link org.eclipse.jface.text.ITextViewerExtension8} since version 3.4 | |
114 * extending the text viewer with the ability to print and rich hover support.</li> | |
115 * </ul></p> | |
116 * <p> | |
117 * Clients may implement this interface and its extension interfaces or use the | |
118 * standard implementation {@link org.eclipse.jface.text.TextViewer}.</p> | |
119 * | |
120 * @see org.eclipse.jface.text.ITextViewerExtension | |
121 * @see org.eclipse.jface.text.ITextViewerExtension2 | |
122 * @see org.eclipse.jface.text.ITextViewerExtension3 | |
123 * @see org.eclipse.jface.text.ITextViewerExtension4 | |
124 * @see org.eclipse.jface.text.ITextViewerExtension5 | |
125 * @see org.eclipse.jface.text.ITextViewerExtension6 | |
126 * @see org.eclipse.jface.text.ITextViewerExtension7 | |
127 * @see org.eclipse.jface.text.ITextViewerExtension8 | |
128 * @see org.eclipse.jface.text.IDocument | |
129 * @see org.eclipse.jface.text.ITextInputListener | |
130 * @see org.eclipse.jface.text.IViewportListener | |
131 * @see org.eclipse.jface.text.ITextListener | |
132 * @see org.eclipse.jface.text.IEventConsumer | |
133 */ | |
134 public interface ITextViewer { | |
135 | |
136 | |
137 /* ---------- widget --------- */ | |
138 | |
139 /** | |
140 * Returns this viewer's SWT control, <code>null</code> if the control is disposed. | |
141 * <p> | |
142 * <em>Calling API directly on the widget can interfere with features provided | |
143 * by a text viewer. Clients who call API directly on the widget are responsible | |
144 * to resolve such conflicts on their side.</em> | |
145 * </p> | |
146 * | |
147 * @return the SWT control or <code>null</code> | |
148 */ | |
149 StyledText getTextWidget(); | |
150 | |
151 | |
152 /* --------- plug-ins --------- */ | |
153 | |
154 /** | |
155 * Sets this viewer's undo manager. | |
156 * | |
157 * @param undoManager the new undo manager. <code>null</code> is a valid argument. | |
158 */ | |
159 void setUndoManager(IUndoManager undoManager); | |
160 | |
161 /** | |
162 * Sets this viewer's text double click strategy for the given content type. | |
163 * | |
164 * @param strategy the new double click strategy. <code>null</code> is a valid argument. | |
165 * @param contentType the type for which the strategy is registered | |
166 */ | |
167 void setTextDoubleClickStrategy(ITextDoubleClickStrategy strategy, String contentType); | |
168 | |
169 /** | |
170 * Sets this viewer's auto indent strategy for the given content type. If | |
171 * the given strategy is <code>null</code> any installed strategy for the | |
172 * content type is removed. This method has been replaced by | |
173 * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and | |
174 * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)}. | |
175 * It is now equivalent to | |
176 * <pre> | |
177 * ITextViewerExtension2 extension= cast(ITextViewerExtension2) viewer; | |
178 * extension.removeAutoEditStrategy(oldStrategy, contentType); | |
179 * extension.prependAutoEditStrategy(strategy, contentType); | |
180 * </pre> | |
181 * | |
182 * @param strategy the new auto indent strategy. <code>null</code> is a | |
183 * valid argument. | |
184 * @param contentType the type for which the strategy is registered | |
185 * @deprecated since 3.1, use | |
186 * {@link ITextViewerExtension2#prependAutoEditStrategy(IAutoEditStrategy, String)} and | |
187 * {@link ITextViewerExtension2#removeAutoEditStrategy(IAutoEditStrategy, String)} instead | |
188 */ | |
189 void setAutoIndentStrategy(IAutoIndentStrategy strategy, String contentType); | |
190 | |
191 /** | |
192 * Sets this viewer's text hover for the given content type. | |
193 * <p> | |
194 * This method has been replaced by {@link ITextViewerExtension2#setTextHover(ITextHover, String, int)}. | |
195 * It is now equivalent to | |
196 * <pre> | |
197 * ITextViewerExtension2 extension= cast(ITextViewerExtension2) document; | |
198 * extension.setTextHover(textViewerHover, contentType, ITextViewerExtension2#DEFAULT_HOVER_STATE_MASK); | |
199 * </pre> | |
200 * | |
201 * | |
202 * @param textViewerHover the new hover. <code>null</code> is a valid | |
203 * argument. | |
204 * @param contentType the type for which the hover is registered | |
205 */ | |
206 void setTextHover(ITextHover textViewerHover, String contentType); | |
207 | |
208 /** | |
209 * Activates the installed plug-ins. If the plug-ins are already activated | |
210 * this call has no effect. | |
211 */ | |
212 void activatePlugins(); | |
213 | |
214 /** | |
215 * Resets the installed plug-ins. If plug-ins change their state or | |
216 * behavior over the course of time, this method causes them to be set | |
217 * back to their initial state and behavior. E.g., if an {@link IUndoManager} | |
218 * has been installed on this text viewer, the manager's list of remembered | |
219 * text editing operations is removed. | |
220 */ | |
221 void resetPlugins(); | |
222 | |
223 | |
224 | |
225 /* ---------- listeners ------------- */ | |
226 | |
227 /** | |
228 * Adds the given view port listener to this viewer. The listener | |
229 * is informed about all changes to the visible area of this viewer. | |
230 * If the listener is already registered with this viewer, this call | |
231 * has no effect. | |
232 * | |
233 * @param listener the listener to be added | |
234 */ | |
235 void addViewportListener(IViewportListener listener); | |
236 | |
237 /** | |
238 * Removes the given listener from this viewer's set of view port listeners. | |
239 * If the listener is not registered with this viewer, this call has | |
240 * no effect. | |
241 * | |
242 * @param listener the listener to be removed | |
243 */ | |
244 void removeViewportListener(IViewportListener listener); | |
245 | |
246 /** | |
247 * Adds a text listener to this viewer. If the listener is already registered | |
248 * with this viewer, this call has no effect. | |
249 * | |
250 * @param listener the listener to be added | |
251 */ | |
252 void addTextListener(ITextListener listener); | |
253 | |
254 /** | |
255 * Removes the given listener from this viewer's set of text listeners. | |
256 * If the listener is not registered with this viewer, this call has | |
257 * no effect. | |
258 * | |
259 * @param listener the listener to be removed | |
260 */ | |
261 void removeTextListener(ITextListener listener); | |
262 | |
263 /** | |
264 * Adds a text input listener to this viewer. If the listener is already registered | |
265 * with this viewer, this call has no effect. | |
266 * | |
267 * @param listener the listener to be added | |
268 */ | |
269 void addTextInputListener(ITextInputListener listener); | |
270 | |
271 /** | |
272 * Removes the given listener from this viewer's set of text input listeners. | |
273 * If the listener is not registered with this viewer, this call has | |
274 * no effect. | |
275 * | |
276 * @param listener the listener to be removed | |
277 */ | |
278 void removeTextInputListener(ITextInputListener listener); | |
279 | |
280 | |
281 | |
282 /* -------------- model manipulation ------------- */ | |
283 | |
284 /** | |
285 * Sets the given document as the text viewer's model and updates the | |
286 * presentation accordingly. An appropriate <code>TextEvent</code> is | |
287 * issued. This text event does not carry a related document event. | |
288 * | |
289 * @param document the viewer's new input document <code>null</code> if none | |
290 */ | |
291 void setDocument(IDocument document); | |
292 | |
293 /** | |
294 * Returns the text viewer's input document. | |
295 * | |
296 * @return the viewer's input document or <code>null</code> if none | |
297 */ | |
298 IDocument getDocument(); | |
299 | |
300 | |
301 /* -------------- event handling ----------------- */ | |
302 | |
303 /** | |
304 * Registers an event consumer with this viewer. This method has been | |
305 * replaces with the {@link org.eclipse.swt.custom.VerifyKeyListener} | |
306 * management methods in {@link ITextViewerExtension}. | |
307 * | |
308 * @param consumer the viewer's event consumer. <code>null</code> is a | |
309 * valid argument. | |
310 */ | |
311 void setEventConsumer(IEventConsumer consumer); | |
312 | |
313 /** | |
314 * Sets the editable state. | |
315 * | |
316 * @param editable the editable state | |
317 */ | |
318 void setEditable(bool editable); | |
319 | |
320 /** | |
321 * Returns whether the shown text can be manipulated. | |
322 * | |
323 * @return the viewer's editable state | |
324 */ | |
325 bool isEditable(); | |
326 | |
327 | |
328 /* ----------- visible region support ------------- */ | |
329 | |
330 /** | |
331 * Sets the given document as this viewer's model and | |
332 * exposes the specified region. An appropriate | |
333 * <code>TextEvent</code> is issued. The text event does not carry a | |
334 * related document event. This method is a convenience method for | |
335 * <code>setDocument(document);setVisibleRegion(offset, length)</code>. | |
336 * | |
337 * @param document the new input document or <code>null</code> if none | |
338 * @param modelRangeOffset the offset of the model range | |
339 * @param modelRangeLength the length of the model range | |
340 */ | |
341 void setDocument(IDocument document, int modelRangeOffset, int modelRangeLength); | |
342 | |
343 /** | |
344 * Defines and sets the region of this viewer's document which will be | |
345 * visible in the presentation. Every character inside the specified region | |
346 * is supposed to be visible in the viewer's widget after that call. | |
347 * | |
348 * @param offset the offset of the visible region | |
349 * @param length the length of the visible region | |
350 */ | |
351 void setVisibleRegion(int offset, int length); | |
352 | |
353 /** | |
354 * Resets the region of this viewer's document which is visible in the presentation. | |
355 * Afterwards, the whole input document is visible. | |
356 */ | |
357 void resetVisibleRegion(); | |
358 | |
359 /** | |
360 * Returns the current visible region of this viewer's document. The result | |
361 * may differ from the argument passed to <code>setVisibleRegion</code> if | |
362 * the document has been modified since then. The visible region is supposed | |
363 * to be a consecutive region in viewer's input document and every character | |
364 * inside that region is supposed to visible in the viewer's widget. | |
365 * <p> | |
366 * Viewers implementing {@link ITextViewerExtension5} may be forced to | |
367 * change the fractions of the input document that are shown, in order to | |
368 * fulfill this contract. | |
369 * | |
370 * @return this viewer's current visible region | |
371 */ | |
372 IRegion getVisibleRegion(); | |
373 | |
374 /** | |
375 * Returns whether a given range overlaps with the visible region of this | |
376 * viewer's document. | |
377 * <p> | |
378 * Viewers implementing {@link ITextViewerExtension5}may be forced to | |
379 * change the fractions of the input document that are shown in order to | |
380 * fulfill this request. This is because the overlap is supposed to be | |
381 * without gaps. | |
382 * | |
383 * @param offset the offset | |
384 * @param length the length | |
385 * @return <code>true</code> if the specified range overlaps with the | |
386 * visible region | |
387 */ | |
388 bool overlapsWithVisibleRegion(int offset, int length); | |
389 | |
390 | |
391 | |
392 /* ------------- presentation manipulation ----------- */ | |
393 | |
394 /** | |
395 * Applies the color information encoded in the given text presentation. | |
396 * <code>controlRedraw</code> tells this viewer whether it should take care of | |
397 * redraw management or not. If, e.g., this call is one in a sequence of multiple | |
398 * presentation calls, it is more appropriate to explicitly control redrawing at the | |
399 * beginning and the end of the sequence. | |
400 * | |
401 * @param presentation the presentation to be applied to this viewer | |
402 * @param controlRedraw indicates whether this viewer should manage redraws | |
403 */ | |
404 void changeTextPresentation(TextPresentation presentation, bool controlRedraw); | |
405 | |
406 /** | |
407 * Marks the currently applied text presentation as invalid. It is the | |
408 * viewer's responsibility to take any action it can to repair the text | |
409 * presentation. | |
410 * <p> | |
411 * See {@link ITextViewerExtension2#invalidateTextPresentation(int, int)} | |
412 * for a way to invalidate specific regions rather than the presentation as | |
413 * a whole. | |
414 * | |
415 * @since 2.0 | |
416 */ | |
417 void invalidateTextPresentation(); | |
418 | |
419 /** | |
420 * Applies the given color as text foreground color to this viewer's | |
421 * selection. | |
422 * | |
423 * @param color the color to be applied | |
424 */ | |
425 void setTextColor(Color color); | |
426 | |
427 /** | |
428 * Applies the given color as text foreground color to the specified section | |
429 * of this viewer. <code>controlRedraw</code> tells this viewer whether it | |
430 * should take care of redraw management or not. | |
431 * | |
432 * @param color the color to be applied | |
433 * @param offset the offset of the range to be changed | |
434 * @param length the length of the range to be changed | |
435 * @param controlRedraw indicates whether this viewer should manage redraws | |
436 */ | |
437 void setTextColor(Color color, int offset, int length, bool controlRedraw); | |
438 | |
439 | |
440 /* --------- target handling and configuration ------------ */ | |
441 | |
442 /** | |
443 * Returns the text operation target of this viewer. | |
444 * | |
445 * @return the text operation target of this viewer | |
446 */ | |
447 ITextOperationTarget getTextOperationTarget(); | |
448 | |
449 /** | |
450 * Returns the find/replace operation target of this viewer. | |
451 * | |
452 * @return the find/replace operation target of this viewer | |
453 */ | |
454 IFindReplaceTarget getFindReplaceTarget(); | |
455 | |
456 /** | |
457 * Sets the strings that are used as prefixes when lines of the given content type | |
458 * are prefixed using the prefix text operation. The prefixes are considered equivalent. | |
459 * Inserting a prefix always inserts the defaultPrefixes[0]. | |
460 * Removing a prefix removes all of the specified prefixes. | |
461 * | |
462 * @param defaultPrefixes the prefixes to be used | |
463 * @param contentType the content type for which the prefixes are specified | |
464 * @since 2.0 | |
465 */ | |
466 void setDefaultPrefixes(String[] defaultPrefixes, String contentType); | |
467 | |
468 /** | |
469 * Sets the strings that are used as prefixes when lines of the given content type | |
470 * are shifted using the shift text operation. The prefixes are considered equivalent. | |
471 * Thus "\t" and " " can both be used as prefix characters. | |
472 * Shift right always inserts the indentPrefixes[0]. | |
473 * Shift left removes all of the specified prefixes. | |
474 * | |
475 * @param indentPrefixes the prefixes to be used | |
476 * @param contentType the content type for which the prefixes are specified | |
477 */ | |
478 void setIndentPrefixes(String[] indentPrefixes, String contentType); | |
479 | |
480 | |
481 | |
482 /* --------- selection handling -------------- */ | |
483 | |
484 /** | |
485 * Sets the selection to the specified range. | |
486 * | |
487 * @param offset the offset of the selection range | |
488 * @param length the length of the selection range. A negative length places | |
489 * the caret at the visual start of the selection. | |
490 */ | |
491 void setSelectedRange(int offset, int length); | |
492 | |
493 /** | |
494 * Returns the range of the current selection in coordinates of this viewer's document. | |
495 * | |
496 * @return a <code>Point</code> with x as the offset and y as the length of the current selection | |
497 */ | |
498 Point getSelectedRange(); | |
499 | |
500 /** | |
501 * Returns a selection provider dedicated to this viewer. Subsequent | |
502 * calls to this method return always the same selection provider. | |
503 * | |
504 * @return this viewer's selection provider | |
505 */ | |
506 ISelectionProvider getSelectionProvider(); | |
507 | |
508 | |
509 /* ------------- appearance manipulation --------------- */ | |
510 | |
511 /** | |
512 * Ensures that the given range is visible. | |
513 * | |
514 * @param offset the offset of the range to be revealed | |
515 * @param length the length of the range to be revealed | |
516 */ | |
517 void revealRange(int offset, int length); | |
518 | |
519 /** | |
520 * Scrolls the widget so that the given index is the line | |
521 * with the smallest line number of all visible lines. | |
522 * | |
523 * @param index the line which should become the top most line | |
524 */ | |
525 void setTopIndex(int index); | |
526 | |
527 /** | |
528 * Returns the visible line with the smallest line number. | |
529 * | |
530 * @return the number of the top most visible line | |
531 */ | |
532 int getTopIndex(); | |
533 | |
534 /** | |
535 * Returns the document offset of the upper left corner of this viewer's view port. | |
536 * | |
537 * @return the upper left corner offset | |
538 */ | |
539 int getTopIndexStartOffset(); | |
540 | |
541 /** | |
542 * Returns the visible line with the highest line number. | |
543 * | |
544 * @return the number of the bottom most line | |
545 */ | |
546 int getBottomIndex(); | |
547 | |
548 /** | |
549 * Returns the document offset of the lower right | |
550 * corner of this viewer's view port. This is the visible character | |
551 * with the highest character position. If the content of this viewer | |
552 * is shorter, the position of the last character of the content is returned. | |
553 * | |
554 * @return the lower right corner offset | |
555 */ | |
556 int getBottomIndexEndOffset(); | |
557 | |
558 /** | |
559 * Returns the vertical offset of the first visible line. | |
560 * | |
561 * @return the vertical offset of the first visible line | |
562 */ | |
563 int getTopInset(); | |
564 } |