001: /*******************************************************************************
002: * Copyright (c) 2000, 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: *******************************************************************************/package org.eclipse.ui.texteditor;
011:
012: import org.eclipse.jface.action.IAction;
013: import org.eclipse.jface.text.IRegion;
014: import org.eclipse.jface.viewers.ISelectionProvider;
015:
016: import org.eclipse.ui.IEditorPart;
017:
018: /**
019: * Interface to a text editor. This interface defines functional extensions to
020: * <code>IEditorPart</code> as well as the configuration capabilities of a
021: * text editor.
022: * <p>
023: * Text editors are configured with an <code>IDocumentProvider</code> which
024: * delivers a textual presentation (<code>IDocument</code>) of the editor's
025: * input. The editor works on the document and forwards all input element
026: * related calls, such as <code>save</code>, to the document provider. The
027: * provider also delivers the input's annotation model which is used by the
028: * editor's vertical ruler.
029: * </p>
030: * <p>
031: * Clients may implement this interface from scratch, but the recommended way is
032: * to subclass the abstract base class <code>AbstractTextEditor</code>.
033: * </p>
034: * <p>
035: * In order to provided backward compatibility for clients of
036: * <code>ITextEditor</code>, extension interfaces are used to provide a means
037: * of evolution. The following extension interfaces exist:
038: * <ul>
039: * <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension} since version 2.0
040: * introducing status fields, read-only state and ruler context menu
041: * listeners.</li>
042: * <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension2} since version 2.1
043: * introducing modifiable state for the editor input and validate state
044: * handling.</li>
045: * <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension3} since version 3.0
046: * adding input state and change information control.</li>
047: * <li>{@link org.eclipse.ui.texteditor.ITextEditorExtension4} since version 3.2
048: * adding annotation navigation and revision information display.</li>
049: * </ul>
050: * </p>
051: *
052: * @see org.eclipse.ui.texteditor.IDocumentProvider
053: * @see org.eclipse.jface.text.source.IAnnotationModel
054: * @see org.eclipse.ui.texteditor.ITextEditorExtension
055: * @see org.eclipse.ui.texteditor.ITextEditorExtension2
056: * @see org.eclipse.ui.texteditor.ITextEditorExtension3
057: */
058: public interface ITextEditor extends IEditorPart {
059:
060: /**
061: * Returns this text editor's document provider.
062: *
063: * @return the document provider or <code>null</code> if none, e.g. after closing the editor
064: */
065: IDocumentProvider getDocumentProvider();
066:
067: /**
068: * Closes this text editor after optionally saving changes.
069: *
070: * @param save <code>true</code> if unsaved changed should be saved, and
071: * <code>false</code> if unsaved changed should be discarded
072: */
073: void close(boolean save);
074:
075: /**
076: * Returns whether the text in this text editor can be changed by the user.
077: *
078: * @return <code>true</code> if it can be edited, and <code>false</code> if it is read-only
079: */
080: boolean isEditable();
081:
082: /**
083: * Abandons all modifications applied to this text editor's input element's
084: * textual presentation since the last save operation.
085: */
086: void doRevertToSaved();
087:
088: /**
089: * Installs the given action under the given action id.
090: *
091: * @param actionID the action id
092: * @param action the action, or <code>null</code> to clear it
093: * @see #getAction(String)
094: */
095: void setAction(String actionID, IAction action);
096:
097: /**
098: * Returns the action installed under the given action id.
099: *
100: * @param actionId the action id
101: * @return the action, or <code>null</code> if none
102: * @see #setAction(String, IAction)
103: */
104: IAction getAction(String actionId);
105:
106: /**
107: * Sets the given activation code for the specified action. If
108: * there is an activation code already registered, it is replaced.
109: * The activation code consists of the same information as
110: * a <code>KeyEvent</code>. If the activation code is triggered
111: * and the associated action is enabled, the action is performed
112: * and the triggering <code>KeyEvent</code> is considered consumed.
113: * If the action is disabled, the <code>KeyEvent</code> is passed
114: * on unmodified. Thus, action activation codes and action accelerators
115: * differ in their model of event consumption. The key code parameter
116: * can be <code>-1</code> to indicate a wild card. The state mask
117: * parameter can be SWT.DEFAULT to indicate a wild card.
118: *
119: * @param actionId the action id
120: * @param activationCharacter the activation code character
121: * @param activationKeyCode the activation code key code or <code>-1</code> for wild card
122: * @param activationStateMask the activation code state mask or <code>SWT.DEFAULT</code> for wild card
123: */
124: void setActionActivationCode(String actionId,
125: char activationCharacter, int activationKeyCode,
126: int activationStateMask);
127:
128: /**
129: * Removes any installed activation code for the specified action.
130: * If no activation code is installed, this method does not have
131: * any effect.
132: *
133: * @param actionId the action id
134: */
135: void removeActionActivationCode(String actionId);
136:
137: /**
138: * Returns whether this text editor is configured to show only the
139: * highlighted range of the text.
140: *
141: * @return <code>true</code> if only the highlighted range is shown, and
142: * <code>false</code> if this editor shows the entire text of the document
143: * @see #showHighlightRangeOnly(boolean)
144: */
145: boolean showsHighlightRangeOnly();
146:
147: /**
148: * Configures this text editor to show only the highlighted range of the
149: * text.
150: *
151: * @param showHighlightRangeOnly <code>true</code> if only the highlighted
152: * range is shown, and <code>false</code> if this editor shows the entire
153: * text of the document
154: * @see #showsHighlightRangeOnly()
155: */
156: void showHighlightRangeOnly(boolean showHighlightRangeOnly);
157:
158: /**
159: * Sets the highlighted range of this text editor to the specified region.
160: *
161: * @param offset the offset of the highlighted range
162: * @param length the length of the highlighted range
163: * @param moveCursor <code>true</code> if the cursor should be moved to
164: * the start of the highlighted range, and <code>false</code> to leave
165: * the cursor unaffected
166: * @see #getHighlightRange()
167: */
168: void setHighlightRange(int offset, int length, boolean moveCursor);
169:
170: /**
171: * Returns the highlighted range of this text editor.
172: *
173: * @return the highlighted range
174: * @see #setHighlightRange(int, int, boolean)
175: */
176: IRegion getHighlightRange();
177:
178: /**
179: * Resets the highlighted range of this text editor.
180: */
181: void resetHighlightRange();
182:
183: /**
184: * Returns this text editor's selection provider. Repeated calls to this
185: * method return the same selection provider.
186: *
187: * @return the selection provider
188: */
189: ISelectionProvider getSelectionProvider();
190:
191: /**
192: * Selects and reveals the specified range in this text editor.
193: *
194: * @param offset the offset of the selection
195: * @param length the length of the selection
196: */
197: void selectAndReveal(int offset, int length);
198: }
|