IContentAssistant


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.jface.text.ITextViewer;
14  
15  
16  /**
17   * An <code>IContentAssistant</code> provides support on interactive content completion.
18   * The content assistant is a {@link org.eclipse.jface.text.ITextViewer} add-on. Its
19   * purpose is to propose, display, and insert completions of the content
20   * of the text viewer's document at the viewer's cursor position. In addition
21   * to handle completions, a content assistant can also be requested to provide
22   * context information. Context information is shown in a tool tip like popup.
23   * As it is not always possible to determine the exact context at a given
24   * document offset, a content assistant displays the possible contexts and requests
25   * the user to choose the one whose information should be displayed.
26   * <p>
27   * A content assistant has a list of {@link org.eclipse.jface.text.contentassist.IContentAssistProcessor}
28   * objects each of which is registered for a  particular document content
29   * type. The content assistant uses the processors to react on the request
30   * of completing documents or presenting context information.
31   * </p>
32   * <p>
33   * In order to provide backward compatibility for clients of <code>IContentAssistant</code>, extension
34   * interfaces are used to provide a means of evolution. The following extension interfaces exist:
35   * <ul>
36   * <li>{@link org.eclipse.jface.text.contentassist.IContentAssistantExtension} since version 3.0 introducing
37   *      the following functions:
38   *          <ul>
39   *              <li>handle documents with multiple partitions</li>
40   *              <li>insertion of common completion prefixes</li>
41   *          </ul>
42   * </li>
43   * <li>{@link org.eclipse.jface.text.contentassist.IContentAssistantExtension2} since version 3.2 introducing
44   *      the following functions:
45   *          <ul>
46   *              <li>repeated invocation (cycling) mode</li>
47   *              <li>completion listeners</li>
48   *              <li>a local status line for the completion popup</li>
49   *              <li>control over the behavior when no proposals are available</li>
50   *          </ul>
51   * </li>
52   * <li>{@link org.eclipse.jface.text.contentassist.IContentAssistantExtension3} since version 3.2 introducing
53   *      the following function:
54   *          <ul>
55   *              <li>a key-sequence to listen for in repeated invocation mode</li>
56   *          </ul>
57   * </li>
58   * </ul>
59   * </p>
60   * <p>
61   * The interface can be implemented by clients. By default, clients use
62   * {@link org.eclipse.jface.text.contentassist.ContentAssistant} as the standard
63   * implementer of this interface.
64   * </p>
65   *
66   * @see org.eclipse.jface.text.ITextViewer
67   * @see org.eclipse.jface.text.contentassist.IContentAssistProcessor
68   */
69   public interface IContentAssistant {
70  
71      //------ proposal popup orientation styles ------------
72      /** The context info list will overlay the list of completion proposals. */
73      public final static int PROPOSAL_OVERLAY= 10;
74      /** The completion proposal list will be removed before the context info list will be shown. */
75      public final static int PROPOSAL_REMOVE=  11;
76      /** The context info list will be presented without hiding or overlapping the completion proposal list. */
77      public final static int PROPOSAL_STACKED= 12;
78  
79      //------ context info box orientation styles ----------
80      /** Context info will be shown above the location it has been requested for without hiding the location. */
81      public final static int CONTEXT_INFO_ABOVE= 20;
82      /** Context info will be shown below the location it has been requested for without hiding the location. */
83      public final static int CONTEXT_INFO_BELOW= 21;
84  
85  
86      /**
87       * Installs content assist support on the given text viewer.
88       *
89       * @param textViewer the text viewer on which content assist will work
90       */
91      void install(ITextViewer textViewer);
92  
93      /**
94       * Uninstalls content assist support from the text viewer it has
95       * previously be installed on.
96       */
97      void uninstall();
98  
99      /**
100      * Shows all possible completions of the content at the viewer's cursor position.
101      *
102      * @return an optional error message if no proposals can be computed
103      */
104     String   showPossibleCompletions();
105 
106     /**
107      * Shows context information for the content at the viewer's cursor position.
108      *
109      * @return an optional error message if no context information can be computed
110      */
111     String   showContextInformation();
112 
113     /**
114      * Returns the content assist processor to be used for the given content type.
115      *
116      * @param contentType the type of the content for which this
117      *        content assistant is to be requested
118      * @return an instance content assist processor or
119      *         <code>null</code> if none exists for the specified content type
120      */
121     IContentAssistProcessor getContentAssistProcessor(String   contentType);
122 }
123
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags