CompareUI


1   /*******************************************************************************
2    * Copyright (c) 2000, 2006 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.compare;
12  
13  import java.util.ResourceBundle  ;
14  
15  import org.eclipse.compare.internal.CompareUIPlugin;
16  import org.eclipse.compare.internal.DocumentManager;
17  import org.eclipse.compare.internal.ICompareUIConstants;
18  import org.eclipse.compare.structuremergeviewer.ICompareInput;
19  import org.eclipse.core.runtime.IAdaptable;
20  import org.eclipse.core.runtime.content.IContentType;
21  import org.eclipse.jface.resource.ImageDescriptor;
22  import org.eclipse.jface.text.IDocument;
23  import org.eclipse.jface.viewers.Viewer;
24  import org.eclipse.swt.graphics.Image;
25  import org.eclipse.swt.widgets.Composite;
26  import org.eclipse.ui.IReusableEditor;
27  import org.eclipse.ui.IWorkbenchPage;
28  import org.eclipse.ui.plugin.AbstractUIPlugin;
29  
30  
31  /**
32   * The class <code>CompareUI</code> defines the entry point to initiate a configurable
33   * compare operation on arbitrary resources. The result of the compare
34   * is opened into a compare editor where the details can be browsed and
35   * edited in dynamically selected structure and content viewers.
36   * <p>
37   * The Compare UI provides a registry for content and structure compare viewers,
38   * which is initialized from extensions contributed to extension points
39   * declared by this plug-in.
40   */
41  public final class CompareUI {
42      
43      /**
44       * Compare Plug-in ID (value <code>"org.eclipse.compare"</code>).
45       * @since 2.0
46       */
47      public static final String   PLUGIN_ID= "org.eclipse.compare"; //$NON-NLS-1$
48      
49      /**
50       * The id of the Compare Preference Page
51       * (value <code>"org.eclipse.compare.internal.ComparePreferencePage"</code>).
52       * 
53       * @since 3.1
54       */
55      public static final String   PREFERENCE_PAGE_ID= "org.eclipse.compare.internal.ComparePreferencePage"; //$NON-NLS-1$
56  
57      /**
58       * Image descriptor for the disabled icon of the 'Next' tool bar button.
59       * @since 2.0
60       */
61      public static final ImageDescriptor DESC_DTOOL_NEXT= CompareUIPlugin.getImageDescriptor(ICompareUIConstants.DTOOL_NEXT);
62      /**
63       * Image descriptor for the normal icon of the 'Next' tool bar button.
64       * @since 2.0
65       */
66      public static final ImageDescriptor DESC_CTOOL_NEXT= CompareUIPlugin.getImageDescriptor(ICompareUIConstants.CTOOL_NEXT);
67      /**
68       * Image descriptor for the roll-over icon of the 'Next' tool bar button.
69       * @since 2.0
70       */
71      public static final ImageDescriptor DESC_ETOOL_NEXT= CompareUIPlugin.getImageDescriptor(ICompareUIConstants.ETOOL_NEXT);
72      
73      /**
74       * Image descriptor for the disabled icon of the 'Previous' tool bar button.
75       * @since 2.0
76       */
77      public static final ImageDescriptor DESC_DTOOL_PREV= CompareUIPlugin.getImageDescriptor(ICompareUIConstants.DTOOL_PREV);
78      /**
79       * Image descriptor for the normal icon of the 'Previous' tool bar button.
80       * @since 2.0
81       */
82      public static final ImageDescriptor DESC_CTOOL_PREV= CompareUIPlugin.getImageDescriptor(ICompareUIConstants.CTOOL_PREV);
83      /**
84       * Image descriptor for the roll-over icon of the 'Previous' tool bar button.
85       * @since 2.0
86       */
87      public static final ImageDescriptor DESC_ETOOL_PREV= CompareUIPlugin.getImageDescriptor(ICompareUIConstants.ETOOL_PREV);
88  
89      /**
90       * Name of the title property of a compare viewer.
91       * If a property with this name is set
92       * on the top level SWT control of a viewer, it is used as a title in the pane's
93       * title bar.
94       */
95      public static final String   COMPARE_VIEWER_TITLE= "org.eclipse.compare.CompareUI.CompareViewerTitle"; //$NON-NLS-1$
96      
97      private CompareUI() {
98          // empty implementation
99      }
100     
101     public static AbstractUIPlugin getPlugin() {
102         return CompareUIPlugin.getDefault();
103     }
104     
105     /**
106      * Returns this plug-in's resource bundle.
107      *
108      * @return the plugin's resource bundle
109      */
110     public static ResourceBundle   getResourceBundle() {
111         return CompareUIPlugin.getDefault().getResourceBundle();
112     }
113     
114     /**
115      * Performs the comparison described by the given input and opens a
116      * compare editor on the result in the currently active workbench page.
117      *
118      * @param input the input on which to open the compare editor
119      */
120     public static void openCompareEditor(CompareEditorInput input) {
121         openCompareEditorOnPage(input, null);
122     }
123             
124     /**
125      * Performs the comparison described by the given input and opens a
126      * compare editor on the result in the given workbench page.
127      *
128      * @param input the input on which to open the compare editor
129      * @param page the workbench page in which to open the compare editor
130      * @since 2.1
131      */
132     public static void openCompareEditorOnPage(CompareEditorInput input, IWorkbenchPage page) {
133         CompareUIPlugin plugin= CompareUIPlugin.getDefault();
134         if (plugin != null)
135             plugin.openCompareEditor(input, page, null);
136     }
137     
138     /**
139      * Performs the comparison described by the given input and
140      * shows the result in the given editor.
141      *
142      * @param input the input on which to open the compare editor
143      * @param editor the compare editor to reuse or null to create a new one
144      * @since 3.0
145      */
146     public static void reuseCompareEditor(CompareEditorInput input, IReusableEditor editor) {
147         CompareUIPlugin plugin= CompareUIPlugin.getDefault();
148         if (plugin != null)
149             plugin.openCompareEditor(input, null, editor);
150     }
151             
152     /**
153      * Performs the comparison described by the given input and opens a
154      * modal compare dialog on the result.
155      *
156      * @param input the input on which to open the compare dialog
157      */
158     public static void openCompareDialog(CompareEditorInput input) {
159         CompareUIPlugin plugin= CompareUIPlugin.getDefault();
160         if (plugin != null)
161             plugin.openCompareDialog(input);
162     }
163             
164     /**
165      * Registers an image descriptor for the given type.
166      *
167      * @param type the type
168      * @param descriptor the image descriptor
169      */
170     public static void registerImageDescriptor(String   type, ImageDescriptor descriptor) {
171         CompareUIPlugin.registerImageDescriptor(type, descriptor);
172     }
173     
174     /**
175      * Returns a shared image for the given type, or a generic image if none
176      * has been registered for the given type.
177      * <p>
178      * Note: Images returned from this method will be automatically disposed
179      * of when this plug-in shuts down. Callers must not dispose of these
180      * images themselves.
181      * </p>
182      *
183      * @param type the type
184      * @return the image
185      */
186     public static Image getImage(String   type) {
187         return CompareUIPlugin.getImage(type);
188     }
189         
190     /**
191      * Registers the given image for being disposed when this plug-in is shutdown.
192      *
193      * @param image the image to register for disposal
194      */
195     public static void disposeOnShutdown(Image image) {
196         CompareUIPlugin.disposeOnShutdown(image);
197     }
198     
199     /**
200      * Returns a shared image for the given adaptable.
201      * This convenience method queries the given adaptable
202      * for its <code>IWorkbenchAdapter.getImageDescriptor</code>, which it
203      * uses to create an image if it does not already have one.
204      * <p>
205      * Note: Images returned from this method will be automatically disposed
206      * of when this plug-in shuts down. Callers must not dispose of these
207      * images themselves.
208      * </p>
209      *
210      * @param adaptable the adaptable for which to find an image
211      * @return an image
212      */
213     public static Image getImage(IAdaptable adaptable) {
214         return CompareUIPlugin.getImage(adaptable);
215     }
216         
217     
218     /**
219      * Creates a stream merger for the given content type.
220      * If no stream merger is registered for the given content type <code>null</code> is returned.
221      *
222      * @param type the type for which to find a stream merger
223      * @return a stream merger for the given type, or <code>null</code> if no
224      *   stream merger has been registered
225      */
226     public static IStreamMerger createStreamMerger(IContentType type) {
227         return CompareUIPlugin.getDefault().createStreamMerger(type);
228     }
229 
230     /**
231      * Creates a stream merger for the given file extension.
232      * If no stream merger is registered for the file extension <code>null</code> is returned.
233      *
234      * @param type the type for which to find a stream merger
235      * @return a stream merger for the given type, or <code>null</code> if no
236      *   stream merger has been registered
237      */
238     public static IStreamMerger createStreamMerger(String   type) {
239         return CompareUIPlugin.getDefault().createStreamMerger(type);
240     }
241 
242     /**
243      * Returns a structure compare viewer based on an old viewer and an input object.
244      * If the old viewer is suitable for showing the input, the old viewer
245      * is returned. Otherwise, the input's type is used to find a viewer descriptor in the registry
246      * which in turn is used to create a structure compare viewer under the given parent composite.
247      * If no viewer descriptor can be found <code>null</code> is returned.
248      *
249      * @param oldViewer a new viewer is only created if this old viewer cannot show the given input
250      * @param input the input object for which to find a structure viewer
251      * @param parent the SWT parent composite under which the new viewer is created
252      * @param configuration a configuration which is passed to a newly created viewer
253      * @return the compare viewer which is suitable for the given input object or <code>null</code>
254      */
255     public static Viewer findStructureViewer(Viewer oldViewer, ICompareInput input, Composite parent,
256                 CompareConfiguration configuration) {
257 
258         return CompareUIPlugin.getDefault().findStructureViewer(oldViewer, input, parent, configuration);
259     }
260     
261     /**
262      * Returns a content compare viewer based on an old viewer and an input object.
263      * If the old viewer is suitable for showing the input the old viewer
264      * is returned. Otherwise the input's type is used to find a viewer descriptor in the registry
265      * which in turn is used to create a content compare viewer under the given parent composite.
266      * If no viewer descriptor can be found <code>null</code> is returned.
267      *
268      * @param oldViewer a new viewer is only created if this old viewer cannot show the given input
269      * @param input the input object for which to find a content viewer
270      * @param parent the SWT parent composite under which the new viewer is created
271      * @param configuration a configuration which is passed to a newly created viewer
272      * @return the compare viewer which is suitable for the given input object or <code>null</code>
273      */
274     public static Viewer findContentViewer(Viewer oldViewer, ICompareInput input, Composite parent,
275             CompareConfiguration configuration) {
276         return CompareUIPlugin.getDefault().findContentViewer(oldViewer, input, parent, configuration);
277     }
278     
279     /**
280      * Returns a content compare viewer based on an old viewer and an input
281      * object. If the old viewer is suitable for showing the input the old
282      * viewer is returned. Otherwise the input's type is used to find a viewer
283      * descriptor in the registry which in turn is used to create a content
284      * compare viewer under the given parent composite. In order to determine
285      * the input's type, the input must either implement IStreamContentAccessor
286      * and ITypedElement or ICompareInput. If no viewer descriptor can be found
287      * <code>null</code> is returned.
288      *
289      * @param oldViewer a new viewer is only created if this old viewer cannot show the given input
290      * @param input the input object for which to find a content viewer. Must
291      * implement either <code>IStreamContentAccessor</code> and<code>
292      * ITypedElement</code> or <code>ICompareInput</code>.
293      * @param parent the SWT parent composite under which the new viewer is created
294      * @param configuration a configuration which is passed to a newly created viewer
295      * @return the compare viewer which is suitable for the given input object or <code>null</code>
296      */
297     public static Viewer findContentViewer(Viewer oldViewer, Object   input, Composite parent,
298             CompareConfiguration configuration) {
299         
300         return CompareUIPlugin.getDefault().findContentViewer(oldViewer, input, parent, configuration);
301     }
302 
303     /**
304      * Adds an alias for the given type.
305      * Subsequent calls to <code>findStructureViewer</code>
306      * treat alias as a synonym for type and return the same viewer.
307      * <p>
308      * Note: this method is for internal use only. Clients should not call this method. 
309      * @param type a type name for which a viewer has been registered
310      * @param alias a type name which should be treated as a synonym of type
311      * @since 2.0
312      */
313     public static void addStructureViewerAlias(String   type, String   alias) {
314         CompareUIPlugin.getDefault().addStructureViewerAlias(type, alias);
315     }
316     
317     /**
318      * Remove all aliases for the given type. This method does not affect
319      * the initial binding between type and viewer. If no aliases exist for the
320      * given type this method does nothing.
321      * <p>
322      * Note: this method is for internal use only. Clients should not call this method. 
323      * @param type the type name for which all synonyms are removed.
324      * @since 2.0
325      */
326     public static void removeAllStructureViewerAliases(String   type) {
327         CompareUIPlugin.getDefault().removeAllStructureViewerAliases(type);
328     }
329     
330     /**
331      * Retrieve a document for the given input or return <code>null</code> if
332      * no document has been registered for the input.
333      * @param input the object for which to retrieve a document
334      * @return a document or <code>null</code> if no document was registered for the input
335      * @since 3.1
336      */
337     public static IDocument getDocument(Object   input) {
338         return DocumentManager.get(input);
339     }
340 
341     /**
342      * Register a document for the given input.
343      * @param input the object for which to register a document
344      * @param document the document to register
345      * @since 3.1
346      */
347     public static void registerDocument(Object   input, IDocument document) {
348         DocumentManager.put(input, document);
349     }
350 
351     /**
352      * Unregister the given document.
353      * @param document the document to unregister
354      * @since 3.1
355      */
356     public static void unregisterDocument(IDocument document) {
357         DocumentManager.remove(document);
358     }
359     
360 }
361 
362
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags