KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc fileNameOrExtension, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc filename);
267 }
268
Popular Tags