KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > editor > view > spi > FlyView


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
20 package org.netbeans.editor.view.spi;
21
22 import javax.swing.text.View JavaDoc;
23
24 /**
25  * Interface marking the flyweight views.
26  * <br>
27  * Flyweight views
28  * are immutable view instances that can be shared in arbitrary number of
29  * occurrences.
30  * <br>
31  * They are typically only leaf views usually built on top of flyweight
32  * elements.
33  *
34  * <p>
35  * A view can be rendered differently in various rendering contexts.
36  * Rendering contexts can affect measurements done by the view.
37  * Therefore there are methods that can replicate the view
38  * into a new instance in a particular context.
39  *
40  * <p>
41  * Flyweight views cannot hold a reference to parent
42  * and their <code>getParent()</code> returns null.
43  * <br>
44  * A call to <code>setParent()</code> would throw an exception.
45  * <br>
46  * Their <code>getElement()</code> returns <code>null</code>.
47  * <br>
48  * <code>getStartOffset()</code> always returns 0.
49  * <br>
50  * <code>getEndOffset()</code> returns length of the text
51  * that they represent.
52  * <br>
53  * <code>getContainer()</code> always returns null.
54  *
55  *
56  * @author Miloslav Metelka
57  * @version 1.00
58  */
59
60 public interface FlyView {
61
62     /**
63      * Create an instance of the view dependent on the context
64      * given by the parent view. If this view instance
65      * satisfies the conditions imposed by parent's context
66      * (e.g. this view's measurements match those with
67      * the given parent's container font rendering context)
68      * then this instance can be returned instead of creating a new one.
69      *
70      * <b>Note:</b> The parent view should only be used to perform
71      * the necessary initialization of the new instance (or verification
72      * that existing instance can be created) but it should never
73      * be held by the flyweight view permanently.
74      *
75      * @param parent instance of view that will act as parent for the view
76      * in the given context. The possibly created instance of the view
77      * can use the parent but it must not hold the reference to it permanently.
78      * @return a this view instance if measurements of this view satisfy
79      * the context of the parent or a new view instance otherwise.
80      */
81     public FlyView flyInstance(View JavaDoc parent);
82     
83     /**
84      * Create a regular instance that will act as a normal view.
85      * This can be used in certain contexts where a regular view
86      * would be needed typically for a short term use.
87      * <br>
88      * Caller ensures that the text represented by the given offset range
89      * matches the text returned by {@link #getText()}.
90      * <br>
91      * Caller is also responsible to remove this view in case the text
92      * in the particular area changes.
93      */
94     public View JavaDoc regularInstance(View JavaDoc parent, int startOffset, int endOffset);
95
96     /**
97      * Get the text represented by this view.
98      * @return non-null instance of a character sequence.
99      * In case the view does not represent any text an empty sequence
100      * must be returned.
101      */
102     public CharSequence JavaDoc getText();
103
104     
105     /**
106      * Interface that views capable of maintaining flyweight views
107      * as their children must implement.
108      */
109     public interface Parent {
110         
111         /**
112          * Get start offset of the child with the given index.
113          * <br>
114          * The child can be either flyweight or regular view.
115          *
116          * @param childViewIndex &gt;=0 index of the child.
117          * @return start offset of the requested child.
118          */
119         public int getStartOffset(int childViewIndex);
120         
121         /**
122          * Get end offset of the child with the given index.
123          * <br>
124          * The child can be either flyweight or regular view.
125          *
126          * @param childViewIndex &gt;=0 index of the child.
127          * @return start offset of the requested child.
128          */
129         public int getEndOffset(int childViewIndex);
130         
131     }
132 }
133
Popular Tags