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.util.Collection;
045: import javax.swing.JToolTip;
046: import org.netbeans.modules.editor.completion.CompletionResultSetImpl;
047: import org.netbeans.modules.editor.completion.CompletionSpiPackageAccessor;
048:
049: /**
050: * Listener interface for passing the query results.
051: * @see CompletionProvider#createTask
052: *
053: * @author Miloslav Metelka, Dusan Balek
054: * @version 1.01
055: */
056:
057: public final class CompletionResultSet {
058:
059: static {
060: CompletionSpiPackageAccessor.register(new SpiAccessor());
061: }
062:
063: /**
064: * Sort type returned from {@link #getSortType()}
065: * that prefers priority of the item ({@link CompletionItem#getSortPriority()})
066: * over the text of the item ({@link CompletionItem#getSortText()}).
067: */
068: public static final int PRIORITY_SORT_TYPE = 0;
069:
070: /**
071: * Sort type returned from {@link #getSortType()}
072: * that prefers text of the item ({@link CompletionItem#getSortText()}).
073: * over the priority of the item ({@link CompletionItem#getSortPriority()})
074: */
075: public static final int TEXT_SORT_TYPE = 1;
076:
077: private CompletionResultSetImpl impl;
078:
079: CompletionResultSet(CompletionResultSetImpl impl) {
080: this .impl = impl;
081: impl.setResultSet(this );
082: }
083:
084: /**
085: * Set title that will be assigned to the completion popup window.
086: * <br>
087: * It's only relevant to set the title when providing completion items
088: * for {@link CompletionProvider#COMPLETION_QUERY_TYPE}.
089: * <br>
090: * If there will be multiple completion providers setting this property
091: * for the given mime-type then only the first one
092: * (according to the xml-layer registration order)
093: * will be taken into account.
094: */
095: @Deprecated
096: public void setTitle(String title) {
097: impl.setTitle(title);
098: }
099:
100: /**
101: * Set the document offset to which the returned completion items
102: * or documentation or tooltip should be anchored.
103: * <br>
104: * If there will be multiple completion providers setting this property
105: * for the given mime-type then only the first one
106: * (according to the xml-layer registration order)
107: * will be taken into account.
108: */
109: public void setAnchorOffset(int anchorOffset) {
110: impl.setAnchorOffset(anchorOffset);
111: }
112:
113: /**
114: * Add the completion item to this result set.
115: * <br>
116: * This method can be called multiple times until
117: * all the items have been added to ths result set.
118: * <br>
119: * After the adding is completed @link #finish()} must be called to confirm
120: * that the result set will no longer be modified.
121: *
122: * @param item non-null completion item.
123: * @return true if adding of the items can continue
124: * or false if there is already too many items
125: * to be practical to display in the listbox so subsequent
126: * adding should preferably be discontinued.
127: */
128: public boolean addItem(CompletionItem item) {
129: return impl.addItem(item);
130: }
131:
132: /**
133: * Add the collection of the completion items to this result set.
134: * <br>
135: * This method can be called multiple times until
136: * all the items have been added to ths result set.
137: * <br>
138: * After the adding is completed @link #finish()} must be called to confirm
139: * that the result set will no longer be modified.
140: *
141: * @param items collection of items to be added.
142: * @return true if adding of the items can continue
143: * or false if there is already too many items
144: * to be practical to display in the listbox so subsequent
145: * adding should preferably be discontinued.
146: */
147: public boolean addAllItems(
148: Collection<? extends CompletionItem> items) {
149: return impl.addAllItems(items);
150: }
151:
152: /**
153: * Indicate that adding of the items to this result set
154: * will likely need a long time so the resulting number of items
155: * and their visual size should be estimated so that
156: * the completion infrastructure can estimate the size
157: * of the popup window and display the items added subsequently
158: * without changing its bound extensively.
159: * <br>
160: * Without calling of this method the completion infrastructure
161: * will wait until {@link #finish()} gets called on this result set
162: * before displaying any of the items added to this result set.
163: *
164: * <p>
165: * By calling of this method the task also confirms
166: * that the items added by {@link #addItem(CompletionItem)} subsequently
167: * are already in the order corresponding to the {@link #getSortType()}.
168: *
169: * @param estimatedItemCount estimated number of the items that will
170: * be added to this result set by {@link #addItem(CompletionItem)}.
171: * If the estimate is significantly lower than the reality then
172: * the vertical scrollbar granularity may be decreased or the vertical
173: * scrollbar can be removed completely once the result set is finished.
174: * If the estimate is significantly higher than the reality then
175: * the vertical scrollbar granularity may be increased
176: * once the result set is finished.
177: * @param estimatedItemWidth estimated maximum visual width of a completion item.
178: */
179: public void estimateItems(int estimatedItemCount,
180: int estimatedItemWidth) {
181: impl.estimateItems(estimatedItemCount, estimatedItemWidth);
182: }
183:
184: /**
185: * Indicate that additional items could be added to this result set. However,
186: * adding of these items will likely need a long time to complete so it is
187: * preferred to add them only on the special code completion invocation
188: * denoted by {@link CompletionProvider#COMPLETION_ALL_QUERY_TYPE}.
189: * <br>
190: * Calling this method is relevant only for tasks
191: * created by {@link CompletionProvider#createTask(int, javax.swing.text.JTextComponent)}
192: * with {@link CompletionProvider#COMPLETION_QUERY_TYPE}.
193: */
194: public void setHasAdditionalItems(boolean value) {
195: impl.setHasAdditionalItems(value);
196: }
197:
198: /**
199: * Set the text to be displayed in a completion popup whenever a {@link CompletionProvider}
200: * indicates that additional items could be added to this result set by passing
201: * <code>true</code> to {@link CompletionResultSet#setHasAdditionalItems(boolean)}.
202: *
203: * @param text the text that will be directly prepend to the "Press 'Ctrl-Space' Again for All Items"
204: * message in the completion popup. The text should end with a separator (e.g. space, semicolon and space, etc.)
205: * that will separate it from the rest of the displayed message. <code>null</code> can be passed
206: * to revert any previous setting of the text.
207: *
208: * @since 1.11
209: */
210: public void setHasAdditionalItemsText(String text) {
211: impl.setHasAdditionalItemsText(text);
212: }
213:
214: /**
215: * Set the documentation to this result set.
216: * <br>
217: * Calling this method is only relevant for tasks
218: * created by {@link CompletionProvider#createTask(int, javax.swing.text.JTextComponent)}
219: * with {@link CompletionProvider#DOCUMENTATION_QUERY_TYPE}
220: * or for {@link CompletionItem#createDocumentationTask()}.
221: */
222: public void setDocumentation(CompletionDocumentation documentation) {
223: impl.setDocumentation(documentation);
224: }
225:
226: /**
227: * Set the tooltip to this result set.
228: * <br>
229: * Calling this method is only relevant for tasks
230: * created by {@link CompletionProvider#createTask(int, javax.swing.text.JTextComponent)}
231: * with {@link CompletionProvider#TOOLTIP_QUERY_TYPE}
232: * or for {@link CompletionItem#createToolTipTask()}.
233: */
234: public void setToolTip(JToolTip toolTip) {
235: impl.setToolTip(toolTip);
236: }
237:
238: /**
239: * Mark that this result set is finished and there will be no more
240: * modifications done to it.
241: */
242: public void finish() {
243: impl.finish();
244: }
245:
246: /**
247: * Check whether this result set is finished.
248: *
249: * @return true if the result set is already finished by previous call
250: * to {@link #finish()}.
251: */
252: public boolean isFinished() {
253: return impl.isFinished();
254: }
255:
256: /**
257: * Get the sort type currently used by the code completion.
258: * <br>
259: * It's one of the {@link #PRIORITY_SORT_TYPE} or {@link #TEXT_SORT_TYPE}.
260: */
261: public int getSortType() {
262: return impl.getSortType();
263: }
264:
265: /**
266: * Set the explicit value displayed in a label when the completion results
267: * do not get computed during a certain timeout (e.g. 250ms).
268: * <br>
269: * If not set explicitly the completion infrastructure will use
270: * the default text.
271: *
272: * @param waitText description of what the query copmutation
273: * is currently (doing or waiting for).
274: * <br>
275: * After previous explicit setting <code>null</code> can be passed
276: * to restore using of the default text.
277: *
278: * @since 1.5
279: */
280: public void setWaitText(String waitText) {
281: impl.setWaitText(waitText);
282: }
283:
284: private static final class SpiAccessor extends
285: CompletionSpiPackageAccessor {
286:
287: public CompletionResultSet createCompletionResultSet(
288: CompletionResultSetImpl impl) {
289: return new CompletionResultSet(impl);
290: }
291:
292: }
293: }
|