001: /*
002: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
003: *
004: * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
005: *
006: * The contents of this file are subject to the terms of either the GNU
007: * General Public License Version 2 only ("GPL") or the Common
008: * Development and Distribution License("CDDL") (collectively, the
009: * "License"). You may not use this file except in compliance with the
010: * License. You can obtain a copy of the License at
011: * http://www.netbeans.org/cddl-gplv2.html
012: * or nbbuild/licenses/CDDL-GPL-2-CP. See the License for the
013: * specific language governing permissions and limitations under the
014: * License. When distributing the software, include this License Header
015: * Notice in each file and include the License file at
016: * nbbuild/licenses/CDDL-GPL-2-CP. Sun designates this
017: * particular file as subject to the "Classpath" exception as provided
018: * by Sun in the GPL Version 2 section of the License file that
019: * accompanied this code. If applicable, add the following below the
020: * License Header, with the fields enclosed by brackets [] replaced by
021: * your own identifying information:
022: * "Portions Copyrighted [year] [name of copyright owner]"
023: *
024: * Contributor(s):
025: *
026: * The Original Software is NetBeans. The Initial Developer of the Original
027: * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
028: * Microsystems, Inc. All Rights Reserved.
029: *
030: * If you wish your version of this file to be governed by only the CDDL
031: * or only the GPL Version 2, indicate your decision by adding
032: * "[Contributor] elects to include this software in this distribution
033: * under the [CDDL or GPL Version 2] license." If you do not indicate a
034: * single choice of license, a recipient has the option to distribute
035: * your version of this file under either the CDDL, the GPL Version 2 or
036: * to extend the choice of license to its licensees as provided above.
037: * However, if you add GPL Version 2 code and therefore, elected the GPL
038: * Version 2 license, then the option applies only if the new code is
039: * made subject to such option by the copyright holder.
040: */
041:
042: package org.netbeans.spi.editor.completion;
043:
044: import java.awt.Color;
045: import java.awt.Font;
046: import java.awt.Graphics;
047: import java.awt.event.KeyEvent;
048: import javax.swing.text.JTextComponent;
049:
050: /**
051: * The interface representing a single item of the result list that can be displayed
052: * in the completion popup.
053: *
054: * @author Miloslav Metelka, Dusan Balek
055: * @version 1.01
056: */
057:
058: public interface CompletionItem {
059:
060: /**
061: * Gets invoked when user presses <code>VK_ENTER</code> key
062: * or when she double-clicks on this item with the mouse cursor.
063: * <br/>
064: * This method gets invoked from AWT thread.
065: *
066: * @param component non-null text component for which the completion was invoked.
067: */
068: void defaultAction(JTextComponent component);
069:
070: /**
071: * Process the key pressed when this completion item was selected
072: * in the completion popup window.
073: * <br/>
074: * This method gets invoked from AWT thread.
075: *
076: * @param evt non-null key event of the pressed key. It should be consumed
077: * in case the item is sensitive to the given key. The source of this
078: * event is the text component to which the corresponding action should
079: * be performed.
080: */
081: void processKeyEvent(KeyEvent evt);
082:
083: /**
084: * Get the preferred visual width of this item.
085: * <br>
086: * The visual height of the item is fixed to 16 points.
087: *
088: * @param g graphics that can be used for determining the preferred width
089: * e.g. getting of the font metrics.
090: * @param defaultFont default font used for rendering.
091: */
092: int getPreferredWidth(Graphics g, Font defaultFont);
093:
094: /**
095: * Render this item into the given graphics.
096: *
097: * @param g graphics to render the item into.
098: * @param defaultFont default font used for rendering.
099: * @param defaultColor default color used for rendering.
100: * @param backgroundColor color used for background.
101: * @param width width of the area to render into.
102: * @param height height of the are to render into.
103: * @param selected whether this item is visually selected in the list
104: * into which the items are being rendered.
105: */
106: void render(Graphics g, Font defaultFont, Color defaultColor,
107: Color backgroundColor, int width, int height,
108: boolean selected);
109:
110: /**
111: * Returns a task used to obtain a documentation associated with the item if there
112: * is any.
113: */
114: CompletionTask createDocumentationTask();
115:
116: /**
117: * Returns a task used to obtain a tooltip hint associated with the item if there
118: * is any.
119: */
120: CompletionTask createToolTipTask();
121:
122: /**
123: * When enabled for the item the instant substitution should process the item
124: * in the same way like when the item is displayed and Enter key gets pressed
125: * by the user.
126: * <br>
127: * Instant substitution is invoked when there would be just a single item
128: * displayed in the completion popup window.
129: * <br>
130: * The implementation can invoke the {@link #defaultAction(JTextComponent)}
131: * if necessary.
132: * <br/>
133: * This method gets invoked from AWT thread.
134: *
135: * @param component non-null text component for which the completion was invoked.
136: * @return <code>true</code> if the instant substitution was successfully done.
137: * <code>false</code> means that the instant substitution should not be done
138: * for this item and the completion item should normally be displayed.
139: */
140: boolean instantSubstitution(JTextComponent component);
141:
142: /**
143: * Returns the item's priority. A lower value means a lower index of the item
144: * in the completion result list.
145: */
146: int getSortPriority();
147:
148: /**
149: * Returns a text used to sort items alphabetically.
150: */
151: CharSequence getSortText();
152:
153: /**
154: * Returns a text used for finding of a longest common prefix
155: * after the <i>TAB</i> gets pressed or when the completion is opened explicitly.
156: * <br>
157: * The completion infrastructure will evaluate the insert prefixes
158: * of all the items present in the visible result and finds the longest
159: * common prefix.
160: *
161: * <p>
162: * Generally the returned text does not need to contain all the information
163: * that gets inserted when the item is selected.
164: * <br>
165: * For example in java completion the field name should be returned for fields
166: * or a method name for methods (but not parameters)
167: * or a non-FQN name for classes.
168: *
169: * @return non-null character sequence containing the insert prefix.
170: * <br>
171: * Returning an empty string will effectively disable the TAB completion
172: * as the longest common prefix will be empty.
173: *
174: * @since 1.4
175: */
176: CharSequence getInsertPrefix();
177:
178: }
|