|
129
|
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 dwtx.jface.text.source.IAnnotationModel;
|
|
|
14
|
|
|
15 import dwt.dwthelper.utils;
|
|
|
16
|
|
|
17 import java.util.Iterator;
|
|
|
18
|
|
|
19 import dwtx.jface.text.IDocument;
|
|
|
20 import dwtx.jface.text.Position;
|
|
|
21
|
|
|
22
|
|
|
23 /**
|
|
|
24 * This interface defines the model for managing annotations attached to a document.
|
|
|
25 * The model maintains a set of annotations for a given document and notifies registered annotation
|
|
|
26 * model listeners about annotation model changes. It also provides methods
|
|
|
27 * for querying the current position of an annotation managed
|
|
|
28 * by this model.
|
|
|
29 * <p>
|
|
|
30 * In order to provide backward compatibility for clients of <code>IAnnotationModel</code>, extension
|
|
|
31 * interfaces are used to provide a means of evolution. The following extension interfaces
|
|
|
32 * exist:
|
|
|
33 * <ul>
|
|
|
34 * <li> {@link dwtx.jface.text.source.IAnnotationModelExtension} since version 3.0 introducing the concept
|
|
|
35 * of model piggybacking annotation models, modification time stamps, and enhanced manipulation methods.
|
|
|
36 * </li>
|
|
|
37 * <li> {@link dwtx.jface.text.source.IAnnotationModelExtension2} since version 3.4 allows to retrieve
|
|
|
38 * annotations within a given region.
|
|
|
39 * </li>
|
|
|
40 * </ul>
|
|
|
41 * </p>
|
|
|
42 *
|
|
|
43 * Clients may implement this interface or use the default implementation provided
|
|
|
44 * by <code>AnnotationModel</code>.
|
|
|
45 *
|
|
|
46 * @see dwtx.jface.text.source.IAnnotationModelExtension
|
|
|
47 * @see dwtx.jface.text.source.IAnnotationModelExtension2
|
|
|
48 * @see dwtx.jface.text.source.Annotation
|
|
|
49 * @see dwtx.jface.text.source.IAnnotationModelListener
|
|
|
50 */
|
|
|
51 public interface IAnnotationModel {
|
|
|
52
|
|
|
53 /**
|
|
|
54 * Registers the annotation model listener with this annotation model.
|
|
|
55 * After registration listener is informed about each change of this model.
|
|
|
56 * If the listener is already registered nothing happens.
|
|
|
57 *
|
|
|
58 * @param listener the listener to be registered, may not be <code>null</code>
|
|
|
59 */
|
|
|
60 void addAnnotationModelListener(IAnnotationModelListener listener);
|
|
|
61
|
|
|
62 /**
|
|
|
63 * Removes the listener from the model's list of annotation model listeners.
|
|
|
64 * If the listener is not registered with the model nothing happens.
|
|
|
65 *
|
|
|
66 * @param listener the listener to be removed, may not be <code>null</code>
|
|
|
67 */
|
|
|
68 void removeAnnotationModelListener(IAnnotationModelListener listener);
|
|
|
69
|
|
|
70 /**
|
|
|
71 * Connects the annotation model to a document. The annotations managed
|
|
|
72 * by this model must subsequently update according to the changes applied
|
|
|
73 * to the document. Once an annotation model is connected to a document,
|
|
|
74 * all further <code>connect</code> calls must mention the document the
|
|
|
75 * model is already connected to. An annotation model primarily uses
|
|
|
76 * <code>connect</code> and <code>disconnect</code> for reference counting
|
|
|
77 * the document. Reference counting frees the clients from keeping tracker
|
|
|
78 * whether a model has already been connected to a document.
|
|
|
79 *
|
|
|
80 * @param document the document the model gets connected to,
|
|
|
81 * may not be <code>null</code>
|
|
|
82 *
|
|
|
83 * @see #disconnect(IDocument)
|
|
|
84 */
|
|
|
85 void connect(IDocument document);
|
|
|
86
|
|
|
87 /**
|
|
|
88 * Disconnects this model from a document. After that, document changes no longer matter.
|
|
|
89 * An annotation model may only be disconnected from a document to which it has been
|
|
|
90 * connected before. If the model reference counts the connections to a document,
|
|
|
91 * the connection to the document may only be terminated if the reference count does
|
|
|
92 * down to 0.
|
|
|
93 *
|
|
|
94 * @param document the document the model gets disconnected from,
|
|
|
95 * may not be <code>null</code>
|
|
|
96 *
|
|
|
97 * @see #connect(IDocument) for further specification details
|
|
|
98 */
|
|
|
99 void disconnect(IDocument document);
|
|
|
100
|
|
|
101 /**
|
|
|
102 * Adds a annotation to this annotation model. The annotation is associated with
|
|
|
103 * with the given position which describes the range covered by the annotation.
|
|
|
104 * All registered annotation model listeners are informed about the change.
|
|
|
105 * If the model is connected to a document, the position is automatically
|
|
|
106 * updated on document changes. If the annotation is already managed by
|
|
|
107 * this annotation model or is not a valid position in the connected document
|
|
|
108 * nothing happens.
|
|
|
109 * <p>
|
|
|
110 * <strong>Performance hint:</strong> Use {@link IAnnotationModelExtension#replaceAnnotations(Annotation[], java.util.Map)}
|
|
|
111 * if several annotations are added and/or removed.
|
|
|
112 * </p>
|
|
|
113 *
|
|
|
114 * @param annotation the annotation to add, may not be <code>null</code>
|
|
|
115 * @param position the position describing the range covered by this annotation,
|
|
|
116 * may not be <code>null</code>
|
|
|
117 */
|
|
|
118 void addAnnotation(Annotation annotation, Position position);
|
|
|
119
|
|
|
120 /**
|
|
|
121 * Removes the given annotation from the model. I.e. the annotation is no
|
|
|
122 * longer managed by this model. The position associated with the annotation
|
|
|
123 * is no longer updated on document changes. If the annotation is not
|
|
|
124 * managed by this model, nothing happens.
|
|
|
125 * <p>
|
|
|
126 * <strong>Performance hint:</strong> Use {@link IAnnotationModelExtension#replaceAnnotations(Annotation[], java.util.Map)}
|
|
|
127 * if several annotations are removed and/or added.
|
|
|
128 * </p>
|
|
|
129 *
|
|
|
130 * @param annotation the annotation to be removed from this model,
|
|
|
131 * may not be <code>null</code>
|
|
|
132 */
|
|
|
133 void removeAnnotation(Annotation annotation);
|
|
|
134
|
|
|
135 /**
|
|
|
136 * Returns all annotations managed by this model.
|
|
|
137 *
|
|
|
138 * @return all annotations managed by this model (element type: {@link Annotation})
|
|
|
139 */
|
|
|
140 Iterator getAnnotationIterator();
|
|
|
141
|
|
|
142 /**
|
|
|
143 * Returns the position associated with the given annotation.
|
|
|
144 *
|
|
|
145 * @param annotation the annotation whose position should be returned
|
|
|
146 * @return the position of the given annotation or <code>null</code> if no
|
|
|
147 * associated annotation exists
|
|
|
148 */
|
|
|
149 Position getPosition(Annotation annotation);
|
|
|
150 }
|
|
|
151
|
