Skip to main content
summaryrefslogtreecommitdiffstats
blob: d8f4c2373b4e44cb590fe3ef76bc214d8a2f80f2 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
/*******************************************************************************
 * Copyright (c) 2000, 2010 IBM Corporation and others.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * which accompanies this distribution, and is available at
 * http://www.eclipse.org/legal/epl-v10.html
 *
 * Contributors:
 *     IBM Corporation - initial API and implementation
 *******************************************************************************/
package org.eclipse.jface.text.source;

import org.eclipse.jface.text.IDocument;
import org.eclipse.jface.text.IRegion;
import org.eclipse.jface.text.ITextOperationTarget;
import org.eclipse.jface.text.ITextViewer;


/**
 * In addition to the text viewer functionality a source viewer supports:
 * <ul>
 * <li>visual annotations based on an annotation model
 * <li>visual range indication
 * <li>management of text viewer add-ons
 * <li>explicit configuration
 * </ul>
 * It is assumed that range indication and visual annotations are shown inside
 * the same presentation area. There are no assumptions about whether this area
 * is different from the viewer's text widget.
 * <p>
 * As the visibility of visual annotations can dynamically be changed, it is
 * assumed that the annotation presentation area can dynamically be hidden if it
 * is different from the text widget.
 * <p>
 * In order to provide backward compatibility for clients of
 * <code>ISourceViewer</code>, extension interfaces are used as a means of
 * evolution. The following extension interfaces exist:
 * <ul>
 * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension} since version 2.1
 * introducing the concept of an annotation overview.</li>
 * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension2} since version 3.0
 * allowing source viewers to roll back a previously performed configuration and
 * allows access to the viewer's visual annotation model.</li>
 * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension3} since version 3.2
 * introducing the concept of a quick assist assistant and providing access
 * to the quick assist invocation context as well as the current annotation hover.</li>
 * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension4} since version 3.4
 * introducing API to access a minimal set of content assistant APIs.</li>
 * </ul></p>
 * <p>
 * Clients may implement this interface and its extension interfaces or use the
 * default implementation provided by
 * {@link org.eclipse.jface.text.source.SourceViewer}.</p>
 *
 * @see org.eclipse.jface.text.source.ISourceViewerExtension
 * @see org.eclipse.jface.text.source.ISourceViewerExtension2
 * @see org.eclipse.jface.text.source.ISourceViewerExtension3
 * @see org.eclipse.jface.text.source.ISourceViewerExtension4
 */
public interface ISourceViewer extends ITextViewer {

	/**
	 * Text operation code for requesting content assist to show completion
	 * proposals for the current insert position.
	 */
	int CONTENTASSIST_PROPOSALS= ITextOperationTarget.STRIP_PREFIX + 1;

	/**
	 * Text operation code for requesting content assist to show
	 * the content information for the current insert position.
	 */
	int CONTENTASSIST_CONTEXT_INFORMATION=	ITextOperationTarget.STRIP_PREFIX + 2;

	/**
	 * Text operation code for formatting the selected text or complete document
	 * of this viewer if the selection is empty.
	 */
	int FORMAT= ITextOperationTarget.STRIP_PREFIX + 3;

	/**
	 * Text operation code for requesting information at the current insertion position.
	 * @since 2.0
	 */
	int INFORMATION= ITextOperationTarget.STRIP_PREFIX + 4;

	/*
	 * XXX: Cannot continue numbering due to operation codes used in ProjectionViewer
	 */

	/**
	 * Text operation code for requesting quick assist. This will normally
	 * show quick assist and quick fix proposals for the current position.
	 * @since 3.2
	 */
	int QUICK_ASSIST= ITextOperationTarget.STRIP_PREFIX + 10;

	/*
	 * XXX: Next free number is HyperlinkManager.OPEN_HYPERLINK + 1
	 */


	/**
	 * Configures the source viewer using the given configuration. Prior to 3.0 this
	 * method can only be called once. Since 3.0 this method can be called again
	 * after a call to {@link ISourceViewerExtension2#unconfigure()}.
	 *
	 * @param configuration the source viewer configuration to be used
	 */
	void configure(SourceViewerConfiguration configuration);

	/**
	 * Sets the annotation hover of this source viewer. The annotation hover
	 * provides the information to be displayed in a hover popup window
	 * if requested over the annotation presentation area. The annotation
	 * hover is assumed to be line oriented.
	 *
	 * @param annotationHover the hover to be used, <code>null</code> is a valid argument
	 */
	void setAnnotationHover(IAnnotationHover annotationHover);

	/**
	 * Sets the given document as this viewer's text model and the
	 * given annotation model as the model for this viewer's visual
	 * annotations. The presentation is accordingly updated. An appropriate
	 * <code>TextEvent</code> is issued. This text event does not carry
	 * a related document event.
	 *
	 * @param document the viewer's new input document
	 * @param annotationModel the model for the viewer's visual annotations
	 *
	 * @see ITextViewer#setDocument(IDocument)
	 */
	void setDocument(IDocument document, IAnnotationModel annotationModel);

	/**
	 * Sets the given document as this viewer's text model and the
	 * given annotation model as the model for this viewer's visual
	 * annotations. The presentation is accordingly updated whereby
	 * only the specified region is exposed. An appropriate
	 * <code>TextEvent</code> is issued. The text event does not carry a
	 * related document event. This method is a convenience method for
	 * <code>setDocument(document, annotationModel);setVisibleRegion(offset, length)</code>.
	 *
	 * @param document the new input document
	 * @param annotationModel the model of the viewer's visual annotations
	 * @param modelRangeOffset the offset of the model range
	 * @param modelRangeLength the length of the model range
	 *
	 * @see ITextViewer#setDocument(IDocument, int, int)
	 */
	void setDocument(IDocument document, IAnnotationModel annotationModel, int modelRangeOffset, int modelRangeLength);

	/**
	 * Returns this viewer's annotation model. Use
	 * {@link ISourceViewerExtension2#getVisualAnnotationModel()}in order to
	 * get access to the viewer's visual annotation model.
	 *
	 * @return this viewer's annotation model, or <code>null</code> if none could be determined
	 */
	IAnnotationModel getAnnotationModel();

	/**
	 * Sets the annotation used by this viewer as range indicator. The
	 * range covered by this annotation is referred to as range indication.
	 *
	 * @param rangeIndicator the annotation to be used as this viewer's range indicator
	 */
	void setRangeIndicator(Annotation rangeIndicator);

	/**
	 * Sets the viewers's range indication to the specified range. It is indicated whether the
	 * cursor should also be moved to the beginning of the specified range.
	 *
	 * @param offset the offset of the range
	 * @param length the length of the range
	 * @param moveCursor indicates whether the cursor should be moved to the given offset
	 */
	void setRangeIndication(int offset, int length, boolean moveCursor);

	/**
	 * Returns the viewer's range indication.
	 *
	 * @return the viewer's range indication.
	 */
	IRegion getRangeIndication();

	/**
	 * Removes the viewer's range indication. There is no visible range indication
	 * after this method completed.
	 */
	void removeRangeIndication();

	/**
	 * Controls the visibility of annotations and in the case of separate
	 * presentation areas of text and annotations, the visibility of the
	 * annotation's presentation area.<p>
	 * By default, annotations and their presentation area are visible.
	 *
	 * @param show indicates the visibility of annotations
	 */
	void showAnnotations(boolean show);
}

Back to the top