ITextEditor


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.ui.texteditor;
12  
13  
14  
15  import org.eclipse.jface.action.IAction;
16  import org.eclipse.jface.text.IRegion;
17  import org.eclipse.jface.viewers.ISelectionProvider;
18  
19  import org.eclipse.ui.IEditorPart;
20  
21  
22  /**
23   * Interface to a text editor. This interface defines functional extensions to
24   * <code>IEditorPart</code> as well as the configuration capabilities of a
25   * text editor.
26   * <p>
27   * Text editors are configured with an <code>IDocumentProvider</code> which
28   * delivers a textual presentation (<code>IDocument</code>) of the editor's
29   * input. The editor works on the document and forwards all input element
30   * related calls, such as <code>save</code>, to the document provider. The
31   * provider also delivers the input's annotation model which is used by the
32   * editor's vertical ruler.
33   * </p>
34   * <p>
35   * Clients may implement this interface from scratch, but the recommended way is
36   * to subclass the abstract base class <code>AbstractTextEditor</code>.
37   * </p>
38   * <p>
39   * In order to provided backward compatibility for clients of
40   * <code>ITextEditor</code>, extension interfaces are used to provide a means
41   * of evolution. The following extension interfaces exist:
42   * <ul>
43   * <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension} since version 2.0
44   *      introducing status fields, read-only state and ruler context menu
45   *      listeners.</li>
46   * <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension2} since version 2.1
47   *      introducing modifiable state for the editor input and validate state
48   *      handling.</li>
49   * <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension3} since version 3.0
50   *      adding input state and change information control.</li>
51   * <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension4} since version 3.2
52   *      adding annotation navigation and revision information display.</li>
53   * </ul>
54   * </p>
55   *
56   * @see org.eclipse.ui.texteditor.IDocumentProvider
57   * @see org.eclipse.jface.text.source.IAnnotationModel
58   * @see org.eclipse.ui.texteditor.ITextEditorExtension
59   * @see org.eclipse.ui.texteditor.ITextEditorExtension2
60   * @see org.eclipse.ui.texteditor.ITextEditorExtension3
61   */
62  public interface ITextEditor extends IEditorPart {
63  
64      /**
65       * Returns this text editor's document provider.
66       *
67       * @return the document provider or <code>null</code> if none, e.g. after closing the editor
68       */
69      IDocumentProvider getDocumentProvider();
70  
71      /**
72       * Closes this text editor after optionally saving changes.
73       *
74       * @param save <code>true</code> if unsaved changed should be saved, and
75       *   <code>false</code> if unsaved changed should be discarded
76       */
77      void close(boolean save);
78  
79      /**
80       * Returns whether the text in this text editor can be changed by the user.
81       *
82       * @return <code>true</code> if it can be edited, and <code>false</code> if it is read-only
83       */
84      boolean isEditable();
85  
86      /**
87       * Abandons all modifications applied to this text editor's input element's
88       * textual presentation since the last save operation.
89       */
90      void doRevertToSaved();
91  
92      /**
93       * Installs the given action under the given action id.
94       *
95       * @param actionID the action id
96       * @param action the action, or <code>null</code> to clear it
97       * @see #getAction(String)
98       */
99      void setAction(String   actionID, IAction action);
100 
101     /**
102      * Returns the action installed under the given action id.
103      *
104      * @param actionId the action id
105      * @return the action, or <code>null</code> if none
106      * @see #setAction(String, IAction)
107      */
108     IAction getAction(String   actionId);
109 
110     /**
111      * Sets the given activation code for the specified action. If
112      * there is an activation code already registered, it is replaced.
113      * The activation code consists of the same information as
114      * a <code>KeyEvent</code>. If the activation code is triggered
115      * and the associated action is enabled, the action is performed
116      * and the triggering <code>KeyEvent</code> is considered consumed.
117      * If the action is disabled, the <code>KeyEvent</code> is passed
118      * on unmodified. Thus, action activation codes and action accelerators
119      * differ in their model of event consumption. The key code parameter
120      * can be <code>-1</code> to indicate a wild card. The state mask
121      * parameter can be SWT.DEFAULT to indicate a wild card.
122      *
123      * @param actionId the action id
124      * @param activationCharacter the activation code character
125      * @param activationKeyCode the activation code key code or <code>-1</code> for wild card
126      * @param activationStateMask the activation code state mask or <code>SWT.DEFAULT</code> for wild card
127      */
128     void setActionActivationCode(String   actionId, char activationCharacter, int activationKeyCode, int activationStateMask);
129 
130     /**
131      * Removes any installed activation code for the specified action.
132      * If no activation code is installed, this method does not have
133      * any effect.
134      *
135      * @param actionId the action id
136      */
137     void removeActionActivationCode(String   actionId);
138 
139     /**
140      * Returns whether this text editor is configured to show only the
141      * highlighted range of the text.
142      *
143      * @return <code>true</code> if only the highlighted range is shown, and
144      *   <code>false</code> if this editor shows the entire text of the document
145      * @see #showHighlightRangeOnly(boolean)
146      */
147     boolean showsHighlightRangeOnly();
148 
149     /**
150      * Configures this text editor to show only the highlighted range of the
151      * text.
152      *
153      * @param showHighlightRangeOnly <code>true</code> if only the highlighted
154      *   range is shown, and <code>false</code> if this editor shows the entire
155      *   text of the document
156      * @see #showsHighlightRangeOnly()
157      */
158     void showHighlightRangeOnly(boolean showHighlightRangeOnly);
159 
160     /**
161      * Sets the highlighted range of this text editor to the specified region.
162      *
163      * @param offset the offset of the highlighted range
164      * @param length the length of the highlighted range
165      * @param moveCursor <code>true</code> if the cursor should be moved to
166      *   the start of the highlighted range, and <code>false</code> to leave
167      *   the cursor unaffected
168      * @see #getHighlightRange()
169      */
170     void setHighlightRange(int offset, int length, boolean moveCursor);
171 
172     /**
173      * Returns the highlighted range of this text editor.
174      *
175      * @return the highlighted range
176      * @see #setHighlightRange(int, int, boolean)
177      */
178     IRegion getHighlightRange();
179 
180     /**
181      * Resets the highlighted range of this text editor.
182      */
183     void resetHighlightRange();
184 
185     /**
186      * Returns this text editor's selection provider. Repeated calls to this
187      * method return the same selection provider.
188      *
189      * @return the selection provider
190      */
191     ISelectionProvider getSelectionProvider();
192 
193     /**
194      * Selects and reveals the specified range in this text editor.
195      *
196      * @param offset the offset of the selection
197      * @param length the length of the selection
198      */
199     void selectAndReveal(int offset, int length);
200 }
201
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags