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 }