KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > jface > text > contentassist > ICompletionProposal


1 /*******************************************************************************
2  * Copyright (c) 2000, 2006 IBM Corporation and others.
3  * All rights reserved. This program and the accompanying materials
4  * are made available under the terms of the Eclipse Public License v1.0
5  * which accompanies this distribution, and is available at
6  * http://www.eclipse.org/legal/epl-v10.html
7  *
8  * Contributors:
9  * IBM Corporation - initial API and implementation
10  *******************************************************************************/

11 package org.eclipse.jface.text.contentassist;
12
13 import org.eclipse.swt.graphics.Image;
14 import org.eclipse.swt.graphics.Point;
15
16 import org.eclipse.jface.text.IDocument;
17
18
19 /**
20  * The interface of completion proposals generated by content assist processors.
21  * A completion proposal contains information used to present the proposed completion
22  * to the user, to insert the completion should the user select it, and to present
23  * context information for the chosen completion once it has been inserted.
24  * <p>
25  * In order to provide backward compatibility for clients of <code>ICompletionProposal</code>, extension
26  * interfaces are used to provide a means of evolution. The following extension interfaces exist:
27  * <ul>
28  * <li>{@link org.eclipse.jface.text.contentassist.ICompletionProposalExtension} since version 2.0 introducing
29  * the following functions:
30  * <ul>
31  * <li>handling of trigger characters other than ENTER</li>
32  * <li>completion proposal validation for a given offset</li>
33  * <li>context information can be freely positioned</li>
34  * </ul>
35  * </li>
36  * <li>{@link org.eclipse.jface.text.contentassist.ICompletionProposalExtension2} since version 2.1 introducing
37  * the following functions:
38  * <ul>
39  * <li>handling of trigger characters with modifiers</li>
40  * <li>visual indication for selection of a proposal</li>
41  * </ul>
42  * </li>
43  * <li>{@link org.eclipse.jface.text.contentassist.ICompletionProposalExtension3} since version 3.0 introducing
44  * the following functions:
45  * <ul>
46  * <li>provision of a custom information control creator</li>
47  * <li>provide a custom completion text and offset for prefix completion</li>
48  * </ul>
49  * </li>
50  * <li>{@link org.eclipse.jface.text.contentassist.ICompletionProposalExtension4} since version 3.1 introducing
51  * the following functions:
52  * <ul>
53  * <li>specify whether a proposal is automatically insertable</li>
54  * </ul>
55  * </li>
56  * <li>{@link org.eclipse.jface.text.contentassist.ICompletionProposalExtension5} since version 3.2 introducing
57  * the following function:
58  * <ul>
59  * <li>Allow background computation of the additional info.</li>
60  * </ul>
61  * </li>
62  * </ul>
63  * </p>
64  * <p>
65  * This interface can be implemented by clients. By default, clients use
66  * {@link org.eclipse.jface.text.contentassist.CompletionProposal} as the
67  * standard implementer of this interface.
68  * </p>
69  *
70  * @see IContentAssistProcessor
71  */

72 public interface ICompletionProposal {
73
74     /**
75      * Inserts the proposed completion into the given document.
76      *
77      * @param document the document into which to insert the proposed completion
78      */

79     void apply(IDocument document);
80
81     /**
82      * Returns the new selection after the proposal has been applied to
83      * the given document in absolute document coordinates. If it returns
84      * <code>null</code>, no new selection is set.
85      *
86      * A document change can trigger other document changes, which have
87      * to be taken into account when calculating the new selection. Typically,
88      * this would be done by installing a document listener or by using a
89      * document position during {@link #apply(IDocument)}.
90      *
91      * @param document the document into which the proposed completion has been inserted
92      * @return the new selection in absolute document coordinates
93      */

94     Point getSelection(IDocument document);
95
96     /**
97      * Returns optional additional information about the proposal. The additional information will
98      * be presented to assist the user in deciding if the selected proposal is the desired choice.
99      * <p>
100      * If {@link ICompletionProposalExtension5} is implemented, this method should not be called any
101      * longer. This method may be deprecated in a future release.
102      * </p>
103      *
104      * @return the additional information or <code>null</code>
105      */

106     String JavaDoc getAdditionalProposalInfo();
107
108     /**
109      * Returns the string to be displayed in the list of completion proposals.
110      *
111      * @return the string to be displayed
112      */

113     String JavaDoc getDisplayString();
114
115     /**
116      * Returns the image to be displayed in the list of completion proposals.
117      * The image would typically be shown to the left of the display string.
118      *
119      * @return the image to be shown or <code>null</code> if no image is desired
120      */

121     Image getImage();
122
123     /**
124      * Returns optional context information associated with this proposal.
125      * The context information will automatically be shown if the proposal
126      * has been applied.
127      *
128      * @return the context information for this proposal or <code>null</code>
129      */

130     IContextInformation getContextInformation();
131 }
132
Popular Tags