KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > netbeans > spi > editor > completion > CompletionItem


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.spi.editor.completion;
21
22 import java.awt.Color JavaDoc;
23 import java.awt.Font JavaDoc;
24 import java.awt.Graphics JavaDoc;
25 import java.awt.event.KeyEvent JavaDoc;
26 import javax.swing.text.JTextComponent JavaDoc;
27
28 /**
29  * The interface representing a single item of the result list that can be displayed
30  * in the completion popup.
31  *
32  * @author Miloslav Metelka, Dusan Balek
33  * @version 1.01
34  */

35
36 public interface CompletionItem {
37
38     /**
39      * Gets invoked when user presses <code>VK_ENTER</code> key
40      * or when she double-clicks on this item with the mouse cursor.
41      * <br/>
42      * This method gets invoked from AWT thread.
43      *
44      * @param component non-null text component for which the completion was invoked.
45      */

46     void defaultAction(JTextComponent JavaDoc component);
47
48     /**
49      * Process the key pressed when this completion item was selected
50      * in the completion popup window.
51      * <br/>
52      * This method gets invoked from AWT thread.
53      *
54      * @param evt non-null key event of the pressed key. It should be consumed
55      * in case the item is sensitive to the given key. The source of this
56      * event is the text component to which the corresponding action should
57      * be performed.
58      */

59     void processKeyEvent(KeyEvent JavaDoc evt);
60     
61     /**
62      * Get the preferred visual width of this item.
63      * <br>
64      * The visual height of the item is fixed to 16 points.
65      *
66      * @param g graphics that can be used for determining the preferred width
67      * e.g. getting of the font metrics.
68      * @param defaultFont default font used for rendering.
69      */

70     int getPreferredWidth(Graphics JavaDoc g, Font JavaDoc defaultFont);
71
72     /**
73      * Render this item into the given graphics.
74      *
75      * @param g graphics to render the item into.
76      * @param defaultFont default font used for rendering.
77      * @param defaultColor default color used for rendering.
78      * @param backgroundColor color used for background.
79      * @param width width of the area to render into.
80      * @param height height of the are to render into.
81      * @param selected whether this item is visually selected in the list
82      * into which the items are being rendered.
83      */

84     void render(Graphics JavaDoc g, Font JavaDoc defaultFont, Color JavaDoc defaultColor,
85     Color JavaDoc backgroundColor, int width, int height, boolean selected);
86
87     /**
88      * Returns a task used to obtain a documentation associated with the item if there
89      * is any.
90      */

91     CompletionTask createDocumentationTask();
92
93     /**
94      * Returns a task used to obtain a tooltip hint associated with the item if there
95      * is any.
96      */

97     CompletionTask createToolTipTask();
98     
99     /**
100      * When enabled for the item the instant substitution should process the item
101      * in the same way like when the item is displayed and Enter key gets pressed
102      * by the user.
103      * <br>
104      * Instant substitution is invoked when there would be just a single item
105      * displayed in the completion popup window.
106      * <br>
107      * The implementation can invoke the {@link #defaultAction(JTextComponent)}
108      * if necessary.
109      * <br/>
110      * This method gets invoked from AWT thread.
111      *
112      * @param component non-null text component for which the completion was invoked.
113      * @return <code>true</code> if the instant substitution was successfully done.
114      * <code>false</code> means that the instant substitution should not be done
115      * for this item and the completion item should normally be displayed.
116      */

117     boolean instantSubstitution(JTextComponent JavaDoc component);
118     
119     /**
120      * Returns the item's priority. A lower value means a lower index of the item
121      * in the completion result list.
122      */

123     int getSortPriority();
124
125     /**
126      * Returns a text used to sort items alphabetically.
127      */

128     CharSequence JavaDoc getSortText();
129
130     /**
131      * Returns a text used for finding of a longest common prefix
132      * after the <i>TAB</i> gets pressed or when the completion is opened explicitly.
133      * <br>
134      * The completion infrastructure will evaluate the insert prefixes
135      * of all the items present in the visible result and finds the longest
136      * common prefix.
137      *
138      * <p>
139      * Generally the returned text does not need to contain all the information
140      * that gets inserted when the item is selected.
141      * <br>
142      * For example in java completion the field name should be returned for fields
143      * or a method name for methods (but not parameters)
144      * or a non-FQN name for classes.
145      *
146      * @return non-null character sequence containing the insert prefix.
147      * <br>
148      * Returning an empty string will effectively disable the TAB completion
149      * as the longest common prefix will be empty.
150      *
151      * @since 1.4
152      */

153     CharSequence JavaDoc getInsertPrefix();
154
155 }
156
Popular Tags