001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.jface.text.source;
011:
012: import org.eclipse.jface.text.IDocument;
013: import org.eclipse.jface.text.IRegion;
014: import org.eclipse.jface.text.ITextOperationTarget;
015: import org.eclipse.jface.text.ITextViewer;
016:
017: /**
018: * In addition to the text viewer functionality a source viewer supports:
019: * <ul>
020: * <li>visual annotations based on an annotation model
021: * <li>visual range indication
022: * <li>management of text viewer add-ons
023: * <li>explicit configuration
024: * </ul>
025: * It is assumed that range indication and visual annotations are shown inside
026: * the same presentation area. There are no assumptions about whether this area
027: * is different from the viewer's text widget.
028: * <p>
029: * As the visibility of visual annotations can dynamically be changed, it is
030: * assumed that the annotation presentation area can dynamically be hidden if it
031: * is different from the text widget.
032: * <p>
033: * In order to provide backward compatibility for clients of
034: * <code>ISourceViewer</code>, extension interfaces are used as a means of
035: * evolution. The following extension interfaces exist:
036: * <ul>
037: * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension} since version 2.1
038: * introducing the concept of an annotation overview.</li>
039: * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension2} since version 3.0
040: * allowing source viewers to roll back a previously performed configuration and
041: * allows access to the viewer's visual annotation model.</li>
042: * <li>{@link org.eclipse.jface.text.source.ISourceViewerExtension3} since version 3.2
043: * introducing the concept of a quick assist assistant and providing access
044: * to the quick assist invocation context as well as the current annotation hover.</li>
045: * </ul></p>
046: * <p>
047: * Clients may implement this interface and its extension interfaces or use the
048: * default implementation provided by
049: * {@link org.eclipse.jface.text.source.SourceViewer}.</p>
050: *
051: * @see org.eclipse.jface.text.source.ISourceViewerExtension
052: * @see org.eclipse.jface.text.source.ISourceViewerExtension2
053: * @see org.eclipse.jface.text.source.ISourceViewerExtension3
054: */
055: public interface ISourceViewer extends ITextViewer {
056:
057: /**
058: * Text operation code for requesting content assist to show completion
059: * proposals for the current insert position.
060: */
061: int CONTENTASSIST_PROPOSALS = ITextOperationTarget.STRIP_PREFIX + 1;
062:
063: /**
064: * Text operation code for requesting content assist to show
065: * the content information for the current insert position.
066: */
067: int CONTENTASSIST_CONTEXT_INFORMATION = ITextOperationTarget.STRIP_PREFIX + 2;
068:
069: /**
070: * Text operation code for formatting the selected text or complete document
071: * of this viewer if the selection is empty.
072: */
073: int FORMAT = ITextOperationTarget.STRIP_PREFIX + 3;
074:
075: /**
076: * Text operation code for requesting information at the current insertion position.
077: * @since 2.0
078: */
079: int INFORMATION = ITextOperationTarget.STRIP_PREFIX + 4;
080:
081: /*
082: * XXX: Cannot continue numbering due to operation codes used in ProjectionViewer
083: */
084:
085: /**
086: * Text operation code for requesting quick assist. This will normally
087: * show quick assist and quick fix proposals for the current position.
088: * @since 3.2
089: */
090: int QUICK_ASSIST = ITextOperationTarget.STRIP_PREFIX + 10;
091:
092: /**
093: * Configures the source viewer using the given configuration. Prior to 3.0 this
094: * method can only be called once. Since 3.0 this method can be called again
095: * after a call to {@link ISourceViewerExtension2#unconfigure()}.
096: *
097: * @param configuration the source viewer configuration to be used
098: */
099: void configure(SourceViewerConfiguration configuration);
100:
101: /**
102: * Sets the annotation hover of this source viewer. The annotation hover
103: * provides the information to be displayed in a hover popup window
104: * if requested over the annotation presentation area. The annotation
105: * hover is assumed to be line oriented.
106: *
107: * @param annotationHover the hover to be used, <code>null</code> is a valid argument
108: */
109: void setAnnotationHover(IAnnotationHover annotationHover);
110:
111: /**
112: * Sets the given document as this viewer's text model and the
113: * given annotation model as the model for this viewer's visual
114: * annotations. The presentation is accordingly updated. An appropriate
115: * <code>TextEvent</code> is issued. This text event does not carry
116: * a related document event.
117: *
118: * @param document the viewer's new input document
119: * @param annotationModel the model for the viewer's visual annotations
120: *
121: * @see ITextViewer#setDocument(IDocument)
122: */
123: void setDocument(IDocument document,
124: IAnnotationModel annotationModel);
125:
126: /**
127: * Sets the given document as this viewer's text model and the
128: * given annotation model as the model for this viewer's visual
129: * annotations. The presentation is accordingly updated whereby
130: * only the specified region is exposed. An appropriate
131: * <code>TextEvent</code> is issued. The text event does not carry a
132: * related document event. This method is a convenience method for
133: * <code>setDocument(document, annotationModel);setVisibleRegion(offset, length)</code>.
134: *
135: * @param document the new input document
136: * @param annotationModel the model of the viewer's visual annotations
137: * @param modelRangeOffset the offset of the model range
138: * @param modelRangeLength the length of the model range
139: *
140: * @see ITextViewer#setDocument(IDocument, int, int)
141: */
142: void setDocument(IDocument document,
143: IAnnotationModel annotationModel, int modelRangeOffset,
144: int modelRangeLength);
145:
146: /**
147: * Returns this viewer's annotation model. Use
148: * {@link ISourceViewerExtension2#getVisualAnnotationModel()}in order to
149: * get access to the viewer's visual annotation model.
150: *
151: * @return this viewer's annotation model
152: */
153: IAnnotationModel getAnnotationModel();
154:
155: /**
156: * Sets the annotation used by this viewer as range indicator. The
157: * range covered by this annotation is referred to as range indication.
158: *
159: * @param rangeIndicator the annotation to be used as this viewer's range indicator
160: */
161: void setRangeIndicator(Annotation rangeIndicator);
162:
163: /**
164: * Sets the viewers's range indication to the specified range. Its is indicated
165: * whether the cursor should also be moved to the beginning of the specified range.
166: *
167: * @param offset the offset of the range
168: * @param length the length of the range
169: * @param moveCursor indicates whether the cursor should be moved to the given offset
170: */
171: void setRangeIndication(int offset, int length, boolean moveCursor);
172:
173: /**
174: * Returns the viewer's range indication.
175: *
176: * @return the viewer's range indication.
177: */
178: IRegion getRangeIndication();
179:
180: /**
181: * Removes the viewer's range indication. There is no visible range indication
182: * after this method completed.
183: */
184: void removeRangeIndication();
185:
186: /**
187: * Controls the visibility of annotations and in the case of separate
188: * presentation areas of text and annotations, the visibility of the
189: * annotation's presentation area.<p>
190: * By default, annotations and their presentation area are visible.
191: *
192: * @param show indicates the visibility of annotations
193: */
194: void showAnnotations(boolean show);
195: }
|