IEditorRegistry


1   /*******************************************************************************
2    * Copyright (c) 2000, 2005 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;
12  
13  import org.eclipse.core.runtime.content.IContentType;
14  import org.eclipse.jface.resource.ImageDescriptor;
15  
16  /**
17   * Registry of editors known to the workbench.
18   * <p>
19   * An editor can be created in one of two ways:
20   * <ul>
21   *   <li>An editor can be defined by an extension to the workbench.</li>
22   *   <li>The user manually associates an editor with a given resource extension
23   *      type. This will override any default workbench or platform association.
24   *      </li>
25   * </ul>
26   * </p>
27   * <p>
28   * The registry does not keep track of editors that are "implicitly" determined.
29   * For example a bitmap (<code>.bmp</code>) file will typically not have a 
30   * registered editor. Instead, when no registered editor is found, the 
31   * underlying OS is consulted.
32   * </p>
33   * <p>
34   * This interface is not intended to be implemented by clients.
35   * </p>
36   * 
37   * @see org.eclipse.ui.IWorkbench#getEditorRegistry()
38   */
39  public interface IEditorRegistry {
40  
41      /**
42       * The property identifier for the contents of this registry.
43       */
44      public static final int PROP_CONTENTS = 0x01;
45  
46      /**
47       * The identifier for the system external editor descriptor. This descriptor 
48       * is always present in the registry on all platforms.
49       * This editor requires an input which implements
50       * {@link org.eclipse.ui.IPathEditorInput IPathEditorInput}.
51       * Use {@link #findEditor findEditor} to access the editor descriptor for
52       * this identifier.
53       * 
54       * @since 3.0
55       */
56      public static final String   SYSTEM_EXTERNAL_EDITOR_ID = "org.eclipse.ui.systemExternalEditor"; //$NON-NLS-1$
57  
58      /**
59       * The identifier for the system in-place editor descriptor. This descriptor 
60       * is only present in the registry on platforms that support in-place editing
61       * (for example Win32). This editor requires an input which implements
62       * {@link org.eclipse.ui.IInPlaceEditorInput IInPlaceEditorInput}. Use 
63       * {@link #findEditor findEditor} to access the editor descriptor for this
64       * identifier.
65       * 
66       * @since 3.0
67       */
68      public static final String   SYSTEM_INPLACE_EDITOR_ID = "org.eclipse.ui.systemInPlaceEditor"; //$NON-NLS-1$
69  
70      /**
71       * Adds a listener for changes to properties of this registry.
72       * Has no effect if an identical listener is already registered.
73       * <p>
74       * The properties ids are as follows:
75       * <ul>
76       *   <li><code>PROP_CONTENTS</code>: Triggered when the file editor mappings in
77       *       the editor registry change.</li>
78       * </ul>
79       * </p>
80       *
81       * @param listener a property listener
82       */
83      public void addPropertyListener(IPropertyListener listener);
84  
85      /**
86       * Finds and returns the descriptor of the editor with the given editor id.
87       *
88       * @param editorId the editor id
89       * @return the editor descriptor with the given id, or <code>null</code> if not
90       *   found
91       */
92      public IEditorDescriptor findEditor(String   editorId);
93  
94      /**
95       * Returns the default editor. The default editor always exist.
96       *
97       * @return the descriptor of the default editor
98       * @deprecated The system external editor is the default editor.
99       * Use <code>findEditor(IEditorRegistry.SYSTEM_EXTERNAL_EDITOR_ID)</code>
100      * instead.
101      */
102     public IEditorDescriptor getDefaultEditor();
103 
104     /**
105      * Returns the default editor for a given file name. This method assumes an
106      * unknown content type for the given file.
107      * <p>
108      * The default editor is determined by taking the file extension for the
109      * file and obtaining the default editor for that extension.
110      * </p>
111      * 
112      * @param fileName
113      *            the file name in the system
114      * @return the descriptor of the default editor, or <code>null</code> if
115      *         not found
116      */
117     public IEditorDescriptor getDefaultEditor(String   fileName);
118     
119     /**
120      * Returns the default editor for a given file name and with the given content type.  
121      * <p>
122      * The default editor is determined by taking the file extension for the
123      * file and obtaining the default editor for that extension.
124      * </p>
125      *
126      * @param fileName the file name in the system
127      * @param contentType the content type or <code>null</code> for the unknown content type
128      * @return the descriptor of the default editor, or <code>null</code> if not
129      *   found
130      * @since 3.1
131      */
132     public IEditorDescriptor getDefaultEditor(String   fileName, 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, IContentType contentType);
166 
167     /**
168      * Returns a list of mappings from file type to editor.  The resulting list
169      * is sorted in ascending order by file extension.
170      * <p>
171      * Each mapping defines an extension and the set of editors that are 
172      * available for that type. The set of editors includes those registered 
173      * via plug-ins and those explicitly associated with a type by the user 
174      * in the workbench preference pages.
175      * </p>
176      *
177      * @return a list of mappings sorted alphabetically by extension
178      */
179     public IFileEditorMapping[] getFileEditorMappings();
180 
181     /**
182      * Returns the image descriptor associated with a given file. This image is
183      * usually displayed next to the given file. This method assumes an unknown
184      * content type for the given file.
185      * <p>
186      * The image is determined by taking the file extension of the file and
187      * obtaining the image for the default editor associated with that
188      * extension. A default image is returned if no default editor is available.
189      * </p>
190      * 
191      * @param filename
192      *            the file name in the system
193      * @return the descriptor of the image to display next to the file
194      */
195     public ImageDescriptor getImageDescriptor(String   filename);
196     
197     /**
198      * Returns the image descriptor associated with a given file. This image is
199      * usually displayed next to the given file.
200      * <p>
201      * The image is determined by taking the file extension of the file and
202      * obtaining the image for the default editor associated with that
203      * extension. A default image is returned if no default editor is available.
204      * </p>
205      * 
206      * @param filename
207      *            the file name in the system
208      * @param contentType
209      *            the content type of the file or <code>null</code> for the
210      *            unknown content type
211      * @return the descriptor of the image to display next to the file
212      * @since 3.1
213      */
214     public ImageDescriptor getImageDescriptor(String   filename, IContentType contentType);
215 
216     /**
217      * Removes the given property listener from this registry.
218      * Has no affect if an identical listener is not registered.
219      *
220      * @param listener a property listener
221      */
222     public void removePropertyListener(IPropertyListener listener);
223 
224     /**
225      * Sets the default editor id for the files that match that
226      * specified file name or extension. The specified editor must be
227      * defined as an editor for that file name or extension.
228      *
229      * @param fileNameOrExtension the file name or extension pattern (e.g. "*.xml");
230      * @param editorId the editor id or <code>null</code> for no default
231      */
232     public void setDefaultEditor(String   fileNameOrExtension, String   editorId);
233 
234     /**
235      * Returns whether there is an in-place editor that could handle a file
236      * with the given name.
237      * 
238      * @param filename the file name
239      * @return <code>true</code> if an in-place editor is available, and
240      * <code>false</code> otherwise
241      * @since 3.0
242      */
243     public boolean isSystemInPlaceEditorAvailable(String   filename);
244 
245     /**
246      * Returns whether the system has an editor that could handle a file
247      * with the given name.
248      * 
249      * @param filename the file name
250      * @return <code>true</code> if an external editor available, and
251      * <code>false</code> otherwise
252      * @since 3.0
253      */
254     public boolean isSystemExternalEditorAvailable(String   filename);
255 
256     /**
257      * Returns the image descriptor associated with the system editor that
258      * would be used to edit this file externally.
259      *
260      * @param filename the file name
261      * @return the descriptor of the external editor image, or <code>null</code>
262      * if none
263      * @since 3.0
264      */
265     public ImageDescriptor getSystemExternalEditorImageDescriptor(
266             String   filename);
267 }
268
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags