Annotation


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  package org.openide.text;
20  
21  
22  /** Description of annotation. The class is extended by modules
23   * which creates annotations and defines annotation type and tooltip.
24   * The annotation can be attached to Annotatable object. Editors which
25   * displays Annotations listen on PropertyChangeListner for changes of
26   * annotation type or tooltip text. The tooltip text can be evaluated
27   * asynchronously. It means that editors after the getShortDescription call
28   * must listen on PropertyChangeListner while the tooltip is visible.
29   * If the tooltip text property is changed, the tooltip value must be updated.
30   * <p>
31   * See more - <a HREF="doc-files/api.html#auto-ann">description of the way to declare an Annotation</a>.
32   *
33   * @author David Konecny, Jaroslav Tulach
34   * @since 1.20
35   */
36  public abstract class Annotation extends Object   {
37      /** Property name of the tip text */
38      public static final String   PROP_SHORT_DESCRIPTION = "shortDescription"; // NOI18N
39  
40      /** Property name of the annotation type */
41      public static final String   PROP_ANNOTATION_TYPE = "annotationType"; // NOI18N
42  
43      /** Virtual property which does not have getter/setter. When change on this
44       * property is fired, listeners (= editors) must ensure that this annotation is not covered
45       * by some other annotation which is on the same line - annotation must be moved in front
46       * of others. See also moveToFront() method.
47       * @since 1.27 */
48      public static final String   PROP_MOVE_TO_FRONT = "moveToFront"; // NOI18N
49  
50      /** Support for property change listeners*/
51      private java.beans.PropertyChangeSupport   support;
52  
53      /** Holding the reference to Annotatable object to
54       * which is this Annotation attached*/
55      private Annotatable attached;
56  
57      /** Whether the annotation was added into document or not.
58       * Annotation is added to document only in case it is opened.
59       * WARNING: It is highly probable that this implementation
60       * will change and maybe will be completely removed
61       * in next version. It is used only during the attaching
62       * and detaching of annotations to document. If the code
63       * for loading/closing of document and add/remove of
64       * annotations would be synchronized, this variable would not be
65       * necessary. However, some refactoring on side of DocumentLine
66       * and CloneableEditorSupport will be necessary to achieve this.
67       */
68      private boolean inDocument = false;
69  
70      public Annotation() {
71          support = new java.beans.PropertyChangeSupport  (this);
72      }
73  
74      /** Returns name of the file which describes the annotation type.
75       * The file must be defined in module installation layer in the
76       * directory "Editors/AnnotationTypes"
77       * @return  name of the anotation type*/
78      public abstract String   getAnnotationType();
79  
80      /**
81       * Gets the tool tip text for this annotation.
82       * @return tool tip for this annotation, or null for no tool tip
83       */
84      public abstract String   getShortDescription();
85  
86      /** Attach annotation to Annotatable object.
87       * @param anno annotatable class to which this annotation will be attached */
88      public final void attach(Annotatable anno) {
89          if (attached != null) {
90              detach();
91          }
92  
93          attached = anno;
94  
95          attached.addAnnotation(this);
96          notifyAttached(attached);
97      }
98  
99      /** Notifies the annotation that it was attached
100      * to the annotatable.
101      * @param toAnno annotatable to which the annotation
102      *  was attached.
103      * @since 1.38
104      */
105     protected void notifyAttached(Annotatable toAnno) {
106     }
107 
108     /** Detach annotation.*/
109     public final void detach() {
110         if (attached != null) {
111             attached.removeAnnotation(this);
112 
113             Annotatable old = attached;
114             attached = null;
115             notifyDetached(old);
116         }
117     }
118 
119     /** Notifies the annotation that it was detached
120      * from the annotatable.
121      * @param fromAnno annotatable from which the annotation
122      *  was detached.
123      * @since 1.38
124      */
125     protected void notifyDetached(Annotatable fromAnno) {
126     }
127 
128     /** Gets annotatable object to which this annotation is attached.
129      * @return null if annotation is not attached or reference to annotatable object.
130      * @since 1.27 */
131     final public Annotatable getAttachedAnnotatable() {
132         return attached;
133     }
134 
135     /** Add listeners on changes of annotation properties
136      * @param l  change listener*/
137     final public void addPropertyChangeListener(java.beans.PropertyChangeListener   l) {
138         support.addPropertyChangeListener(l);
139     }
140 
141     /** Remove listeners on changes of annotation properties
142      * @param l  change listener*/
143     final public void removePropertyChangeListener(java.beans.PropertyChangeListener   l) {
144         support.removePropertyChangeListener(l);
145     }
146 
147     /** Fire property change to registered listeners. */
148     final protected void firePropertyChange(String   propertyName, Object   oldValue, Object   newValue) {
149         support.firePropertyChange(propertyName, oldValue, newValue);
150     }
151 
152     /** Helper method for moving annotation which is covered by other annotations
153      * on the same line in front of others. The method fires change on PROP_MOVE_TO_FRONT
154      * property on which editors must listen and do the fronting of the annotation. Whether the annotation
155      * is visible in editor or not is not guaranteed by this method - use Line.show instead.
156      * @since 1.27 */
157     final public void moveToFront() {
158         support.firePropertyChange(PROP_MOVE_TO_FRONT, null, null);
159     }
160 
161     /** Getter for the inDocument property
162      * @return is in document or not */
163     final boolean isInDocument() {
164         return inDocument;
165     }
166 
167     /** Setter for the inDocument property
168      * @param b is in document or not */
169     final void setInDocument(boolean b) {
170         inDocument = b;
171     }
172 }
173
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags