001: /*******************************************************************************
002: * Copyright (c) 2004, 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.internal;
011:
012: import org.eclipse.core.resources.IFile;
013: import org.eclipse.core.resources.IMarker;
014: import org.eclipse.ui.IEditorPart;
015: import org.eclipse.ui.PartInitException;
016:
017: /**
018: * Internal interface used in providing increased binary compatibility for
019: * pre-3.0 plug-ins. This declaration masks the empty interface of the same name
020: * declared in the Workbench proper. This interface declares IWorkbenchPage that
021: * existed in 2.1 but were removed in 3.0 because they referenced resource API.
022: * <p>
023: * Plug-ins should not refer to this type or its containing fragment from their
024: * class path. It is intended only to provide binary compatibility for pre-3.0
025: * plug-ins, and should not be referenced at development time.
026: * </p>
027: *
028: * @since 3.0
029: */
030: public interface ICompatibleWorkbenchPage {
031:
032: /**
033: * Opens an editor on the given file resource.
034: * <p>
035: * If this page already has an editor open on the target object that editor
036: * is activated; otherwise, a new editor is opened.
037: * <p>
038: * <p>
039: * An appropriate editor for the input is determined using a multistep
040: * process.
041: * </p>
042: * <ol>
043: * <li>The workbench editor registry is consulted to determine if an editor
044: * extension has been registered for the file type. If so, an instance of
045: * the editor extension is opened on the file. See
046: * <code>IEditorRegistry.getDefaultEditor(IFile)</code>.
047: * <li>Next, the native operating system will be consulted to determine if
048: * a native editor exists for the file type. If so, a new process is started
049: * and the native editor is opened on the file.
050: * <li>If all else fails the file will be opened in a default text editor.
051: * </li>
052: * </ol>
053: * </p>
054: *
055: * @param input
056: * the file to edit
057: * @return an open and active editor, or <code>null</code> if a system
058: * editor was opened
059: * @exception PartInitException
060: * if the editor could not be initialized
061: * @deprecated In 3.0 this resource-specific method moved from this
062: * interface to
063: * <code>org.eclipse.ui.ide.IDE.openEditor(IWorkbenchPage,IFile)</code>.
064: * This method should not be referenced at development time. See
065: * the class comment for more details.
066: */
067: public IEditorPart openEditor(IFile input) throws PartInitException;
068:
069: /**
070: * Opens an editor on the given file resource.
071: * <p>
072: * If this page already has an editor open on the target object that editor
073: * is brought to front; otherwise, a new editor is opened. If
074: * <code>activate == true</code> the editor will be activated.
075: * <p>
076: * <p>
077: * The editor type is determined by mapping <code>editorId</code> to an
078: * editor extension registered with the workbench. An editor id is passed
079: * rather than an editor object to prevent the accidental creation of more
080: * than one editor for the same input. It also guarantees a consistent
081: * lifecycle for editors, regardless of whether they are created by the user
082: * or restored from saved data.
083: * </p>
084: *
085: * @param input
086: * the file to edit
087: * @param editorId
088: * the id of the editor extension to use or null
089: * @param activate
090: * if <code>true</code> the editor will be activated
091: * @return an open and active editor
092: * @exception PartInitException
093: * if the editor could not be initialized
094: * @deprecated In 3.0 this resource-specific method moved from this
095: * interface to
096: * <code>org.eclipse.ui.ide.IDE.openEditor(IWorkbenchPage,IFile,String,boolean)</code>.
097: * This method should not be referenced at development time. See
098: * the class comment for more details.
099: */
100: public IEditorPart openEditor(IFile input, String editorId,
101: boolean activate) throws PartInitException;
102:
103: /**
104: * Opens an editor on the given file resource.
105: * <p>
106: * If this page already has an editor open on the target object that editor
107: * is activated; otherwise, a new editor is opened.
108: * <p>
109: * <p>
110: * The editor type is determined by mapping <code>editorId</code> to an
111: * editor extension registered with the workbench. An editor id is passed
112: * rather than an editor object to prevent the accidental creation of more
113: * than one editor for the same input. It also guarantees a consistent
114: * lifecycle for editors, regardless of whether they are created by the user
115: * or restored from saved data.
116: * </p>
117: *
118: * @param editorId
119: * the id of the editor extension to use
120: * @param input
121: * the file to edit
122: * @return an open and active editor
123: * @exception PartInitException
124: * if the editor could not be initialized
125: * @deprecated In 3.0 this resource-specific method moved from this
126: * interface to
127: * <code>org.eclipse.ui.ide.IDE.openEditor(IWorkbenchPage,IFile,String)</code>.
128: * This method should not be referenced at development time. See
129: * the class comment for more details.
130: */
131: public IEditorPart openEditor(IFile input, String editorId)
132: throws PartInitException;
133:
134: /**
135: * Opens an editor on the file resource of the given marker.
136: * <p>
137: * If this page already has an editor open on the target object that editor
138: * is activated; otherwise, a new editor is opened. The cursor and selection
139: * state of the editor is then updated from information recorded in the
140: * marker.
141: * <p>
142: * <p>
143: * If the marker contains an <code>EDITOR_ID_ATTR</code> attribute the
144: * attribute value will be used to determine the editor type to be opened.
145: * If not, the registered editor for the marker resource will be used.
146: * </p>
147: *
148: * @param marker
149: * the marker to open
150: * @return an open and active editor, or null if a system editor was opened
151: * @exception PartInitException
152: * if the editor could not be initialized
153: * @see IEditorPart#gotoMarker
154: * @deprecated In 3.0 this resource-specific method moved from this
155: * interface to
156: * <code>org.eclipse.ui.ide.IDE.openEditor(IWorkbenchPage,IMarker)</code>.
157: * This method should not be referenced at development time. See
158: * the class comment for more details.
159: */
160: public IEditorPart openEditor(IMarker marker)
161: throws PartInitException;
162:
163: /**
164: * Opens an editor on the file resource of the given marker.
165: * <p>
166: * If this page already has an editor open on the target object that editor
167: * is brought to front; otherwise, a new editor is opened. If
168: * <code>activate == true</code> the editor will be activated. The cursor
169: * and selection state of the editor are then updated from information
170: * recorded in the marker.
171: * <p>
172: * <p>
173: * If the marker contains an <code>EDITOR_ID_ATTR</code> attribute the
174: * attribute value will be used to determine the editor type to be opened.
175: * If not, the registered editor for the marker resource will be used.
176: * </p>
177: *
178: * @param marker
179: * the marker to open
180: * @param activate
181: * if <code>true</code> the editor will be activated
182: * @return an open editor, or null if a system editor was opened
183: * @exception PartInitException
184: * if the editor could not be initialized
185: * @see IEditorPart#gotoMarker
186: * @deprecated In 3.0 this resource-specific method moved from this
187: * interface to
188: * <code>org.eclipse.ui.ide.IDE.openEditor(IWorkbenchPage,IMarker,boolean)</code>.
189: * This method should not be referenced at development time. See
190: * the class comment for more details.
191: */
192: public IEditorPart openEditor(IMarker marker, boolean activate)
193: throws PartInitException;
194:
195: /**
196: * Opens an operating system editor on a given file. Once open, the
197: * workbench has no knowledge of the editor or the state of the file being
198: * edited. Users are expected to perform a "Local Refresh" from the
199: * workbench user interface.
200: *
201: * @param input
202: * the file to edit
203: * @exception PartInitException
204: * if the editor could not be opened.
205: * @deprecated In 3.0 this resource-specific method was removed. Use
206: * <code>openEditor(new FileEditorInput(file), IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID)</code>
207: * instead. This method should not be referenced at development
208: * time. See the class comment for more details.
209: */
210: public void openSystemEditor(IFile input) throws PartInitException;
211: }
|