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  ;
23  import java.awt.Font  ;
24  import java.awt.Graphics  ;
25  import java.awt.event.KeyEvent  ;
26  import javax.swing.text.JTextComponent  ;
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   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   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   g, Font   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   g, Font   defaultFont, Color   defaultColor,
85      Color   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   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   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   getInsertPrefix();
154 
155 }
156
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags