Mercurial > projects > dwt-addons

comparison dwtx/jface/text/source/IAnnotationModel.d @ 129:eb30df5ca28b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added JFace Text sources
author Frank Benoit <benoit@tionex.de>
date Sat, 23 Aug 2008 19:10:48 +0200
parents
children c4fb132a086c
comparison
equal deleted inserted replaced
128:8df1d4193877 129:eb30df5ca28b
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