001: /*******************************************************************************
002: * Copyright (c) 2000, 2005 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;
011:
012: import org.eclipse.core.runtime.content.IContentType;
013: import org.eclipse.jface.resource.ImageDescriptor;
014:
015: /**
016: * Registry of editors known to the workbench.
017: * <p>
018: * An editor can be created in one of two ways:
019: * <ul>
020: * <li>An editor can be defined by an extension to the workbench.</li>
021: * <li>The user manually associates an editor with a given resource extension
022: * type. This will override any default workbench or platform association.
023: * </li>
024: * </ul>
025: * </p>
026: * <p>
027: * The registry does not keep track of editors that are "implicitly" determined.
028: * For example a bitmap (<code>.bmp</code>) file will typically not have a
029: * registered editor. Instead, when no registered editor is found, the
030: * underlying OS is consulted.
031: * </p>
032: * <p>
033: * This interface is not intended to be implemented by clients.
034: * </p>
035: *
036: * @see org.eclipse.ui.IWorkbench#getEditorRegistry()
037: */
038: public interface IEditorRegistry {
039:
040: /**
041: * The property identifier for the contents of this registry.
042: */
043: public static final int PROP_CONTENTS = 0x01;
044:
045: /**
046: * The identifier for the system external editor descriptor. This descriptor
047: * is always present in the registry on all platforms.
048: * This editor requires an input which implements
049: * {@link org.eclipse.ui.IPathEditorInput IPathEditorInput}.
050: * Use {@link #findEditor findEditor} to access the editor descriptor for
051: * this identifier.
052: *
053: * @since 3.0
054: */
055: public static final String SYSTEM_EXTERNAL_EDITOR_ID = "org.eclipse.ui.systemExternalEditor"; //$NON-NLS-1$
056:
057: /**
058: * The identifier for the system in-place editor descriptor. This descriptor
059: * is only present in the registry on platforms that support in-place editing
060: * (for example Win32). This editor requires an input which implements
061: * {@link org.eclipse.ui.IInPlaceEditorInput IInPlaceEditorInput}. Use
062: * {@link #findEditor findEditor} to access the editor descriptor for this
063: * identifier.
064: *
065: * @since 3.0
066: */
067: public static final String SYSTEM_INPLACE_EDITOR_ID = "org.eclipse.ui.systemInPlaceEditor"; //$NON-NLS-1$
068:
069: /**
070: * Adds a listener for changes to properties of this registry.
071: * Has no effect if an identical listener is already registered.
072: * <p>
073: * The properties ids are as follows:
074: * <ul>
075: * <li><code>PROP_CONTENTS</code>: Triggered when the file editor mappings in
076: * the editor registry change.</li>
077: * </ul>
078: * </p>
079: *
080: * @param listener a property listener
081: */
082: public void addPropertyListener(IPropertyListener listener);
083:
084: /**
085: * Finds and returns the descriptor of the editor with the given editor id.
086: *
087: * @param editorId the editor id
088: * @return the editor descriptor with the given id, or <code>null</code> if not
089: * found
090: */
091: public IEditorDescriptor findEditor(String editorId);
092:
093: /**
094: * Returns the default editor. The default editor always exist.
095: *
096: * @return the descriptor of the default editor
097: * @deprecated The system external editor is the default editor.
098: * Use <code>findEditor(IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID)</code>
099: * instead.
100: */
101: public IEditorDescriptor getDefaultEditor();
102:
103: /**
104: * Returns the default editor for a given file name. This method assumes an
105: * unknown content type for the given file.
106: * <p>
107: * The default editor is determined by taking the file extension for the
108: * file and obtaining the default editor for that extension.
109: * </p>
110: *
111: * @param fileName
112: * the file name in the system
113: * @return the descriptor of the default editor, or <code>null</code> if
114: * not found
115: */
116: public IEditorDescriptor getDefaultEditor(String fileName);
117:
118: /**
119: * Returns the default editor for a given file name and with the given content type.
120: * <p>
121: * The default editor is determined by taking the file extension for the
122: * file and obtaining the default editor for that extension.
123: * </p>
124: *
125: * @param fileName the file name in the system
126: * @param contentType the content type or <code>null</code> for the unknown content type
127: * @return the descriptor of the default editor, or <code>null</code> if not
128: * found
129: * @since 3.1
130: */
131: public IEditorDescriptor getDefaultEditor(String fileName,
132: IContentType contentType);
133:
134: /**
135: * Returns the list of file editors registered to work against the file with
136: * the given file name. This method assumes an unknown content type for the
137: * given file.
138: * <p>
139: * Note: Use <code>getDefaultEditor(String)</code> if you only the need
140: * the default editor rather than all candidate editors.
141: * </p>
142: *
143: * @param fileName
144: * the file name in the system
145: * @return a list of editor descriptors
146: */
147: public IEditorDescriptor[] getEditors(String fileName);
148:
149: /**
150: * Returns the list of file editors registered to work against the file with
151: * the given file name and with the given content type.
152: * <p>
153: * Note: Use <code>getDefaultEditor(String)</code> if you only the need
154: * the default editor rather than all candidate editors.
155: * </p>
156: *
157: * @param fileName
158: * the file name in the system
159: * @param contentType
160: * the content type or <code>null</code> for the unknown
161: * content type
162: * @return a list of editor descriptors
163: * @since 3.1
164: */
165: public IEditorDescriptor[] getEditors(String fileName,
166: IContentType contentType);
167:
168: /**
169: * Returns a list of mappings from file type to editor. The resulting list
170: * is sorted in ascending order by file extension.
171: * <p>
172: * Each mapping defines an extension and the set of editors that are
173: * available for that type. The set of editors includes those registered
174: * via plug-ins and those explicitly associated with a type by the user
175: * in the workbench preference pages.
176: * </p>
177: *
178: * @return a list of mappings sorted alphabetically by extension
179: */
180: public IFileEditorMapping[] getFileEditorMappings();
181:
182: /**
183: * Returns the image descriptor associated with a given file. This image is
184: * usually displayed next to the given file. This method assumes an unknown
185: * content type for the given file.
186: * <p>
187: * The image is determined by taking the file extension of the file and
188: * obtaining the image for the default editor associated with that
189: * extension. A default image is returned if no default editor is available.
190: * </p>
191: *
192: * @param filename
193: * the file name in the system
194: * @return the descriptor of the image to display next to the file
195: */
196: public ImageDescriptor getImageDescriptor(String filename);
197:
198: /**
199: * Returns the image descriptor associated with a given file. This image is
200: * usually displayed next to the given file.
201: * <p>
202: * The image is determined by taking the file extension of the file and
203: * obtaining the image for the default editor associated with that
204: * extension. A default image is returned if no default editor is available.
205: * </p>
206: *
207: * @param filename
208: * the file name in the system
209: * @param contentType
210: * the content type of the file or <code>null</code> for the
211: * unknown content type
212: * @return the descriptor of the image to display next to the file
213: * @since 3.1
214: */
215: public ImageDescriptor getImageDescriptor(String filename,
216: IContentType contentType);
217:
218: /**
219: * Removes the given property listener from this registry.
220: * Has no affect if an identical listener is not registered.
221: *
222: * @param listener a property listener
223: */
224: public void removePropertyListener(IPropertyListener listener);
225:
226: /**
227: * Sets the default editor id for the files that match that
228: * specified file name or extension. The specified editor must be
229: * defined as an editor for that file name or extension.
230: *
231: * @param fileNameOrExtension the file name or extension pattern (e.g. "*.xml");
232: * @param editorId the editor id or <code>null</code> for no default
233: */
234: public void setDefaultEditor(String fileNameOrExtension,
235: String editorId);
236:
237: /**
238: * Returns whether there is an in-place editor that could handle a file
239: * with the given name.
240: *
241: * @param filename the file name
242: * @return <code>true</code> if an in-place editor is available, and
243: * <code>false</code> otherwise
244: * @since 3.0
245: */
246: public boolean isSystemInPlaceEditorAvailable(String filename);
247:
248: /**
249: * Returns whether the system has an editor that could handle a file
250: * with the given name.
251: *
252: * @param filename the file name
253: * @return <code>true</code> if an external editor available, and
254: * <code>false</code> otherwise
255: * @since 3.0
256: */
257: public boolean isSystemExternalEditorAvailable(String filename);
258:
259: /**
260: * Returns the image descriptor associated with the system editor that
261: * would be used to edit this file externally.
262: *
263: * @param filename the file name
264: * @return the descriptor of the external editor image, or <code>null</code>
265: * if none
266: * @since 3.0
267: */
268: public ImageDescriptor getSystemExternalEditorImageDescriptor(
269: String filename);
270: }
|