Eclipse eRCP
Release 1.1

org.eclipse.ui.plugin
Class AbstractUIPlugin

java.lang.Object
  extended byPlugin
      extended byorg.eclipse.ui.plugin.AbstractUIPlugin

public abstract class AbstractUIPlugin
extends Plugin

Abstract base class for plug-ins that integrate with the Eclipse platform UI.

Subclasses obtain the following capabilities:

Preferences

Dialogs Images

For easy access to your plug-in object, use the singleton pattern. Declare a static variable in your plug-in class for the singleton. Store the first (and only) instance of the plug-in class in the singleton when it is created. Then access the singleton when needed through a static getDefault method.

See the description on Plugin.

See Also:
Serialized Form

Constructor Summary
AbstractUIPlugin()
          Creates an abstract UI plug-in runtime object.
AbstractUIPlugin(IPluginDescriptor descriptor)
          Deprecated. In Eclipse 3.0 this constructor has been replaced by AbstractUIPlugin(). Implementations of MyPlugin(IPluginDescriptor descriptor) should be changed to MyPlugin() and call super() instead of super(descriptor). The MyPlugin(IPluginDescriptor descriptor) constructor is called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in (or, as in this case, subclasses which might).
 
Method Summary
protected  ImageRegistry createImageRegistry()
          Returns a new image registry for this plugin-in.
 ImageRegistry getImageRegistry()
          Returns the image registry for this UI plug-in.
 IPreferenceStore getPreferenceStore()
          Returns the org.eclipse.jface.preference store for this UI plug-in.
 IWorkbench getWorkbench()
          Returns the Platform UI workbench.
static ImageDescriptor imageDescriptorFromPlugin(String pluginId, String imageFilePath)
          Creates and returns a new image descriptor for an image file located within the specified plug-in.
protected  void initializeDefaultPluginPreferences()
          Deprecated. this is only called if the runtime compatibility layer is present. See the deprecated comment in Plugin#initializeDefaultPluginPreferences.
protected  void initializeDefaultPreferences(IPreferenceStore store)
          Deprecated. this is only called if the runtime compatibility layer is present. See initializeDefaultPluginPreferences().
protected  void initializeImageRegistry(ImageRegistry reg)
          Initializes an image registry with images which are frequently used by the plugin.
protected  void loadPreferenceStore()
          Deprecated. As of Eclipse 2.0, a basic org.eclipse.jface.preference store exists for all plug-ins. This method now exists only for backwards compatibility. It is called as the plug-in's org.eclipse.jface.preference store is being initialized. The plug-ins preferences are loaded from the file regardless of what this method does.
protected  void savePreferenceStore()
          Deprecated. As of Eclipse 2.0, preferences exist for all plug-ins. The equivalent of this method is Plugin.savePluginPreferences. This method now calls savePluginPreferences, and exists only for backwards compatibility.
 void shutdown()
          Deprecated. In Eclipse 3.0, shutdown has been replaced by Plugin#stop(BundleContext context). Implementations of shutdown should be changed to extend stop(BundleContext context) and call super.stop(context) instead of super.shutdown(). Unlike super.shutdown(), super.stop(context) must be called as the very last thing rather than as the very first thing. The shutdown method is called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in; in contrast, the stop method is always called.
 void start(BundleContext context)
          The AbstractUIPlugin implementation of this Plugin method refreshes the plug-in actions.
 void startup()
          Deprecated. In Eclipse 3.0, startup has been replaced by Plugin#start(BundleContext context). Implementations of startup should be changed to extend start(BundleContext context) and call super.start(context) instead of super.startup(). Like super.startup(), super.stop(context) must be called as the very first thing. The startup method is called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in; in contrast, the start method is always called.
 void stop(BundleContext context)
          The AbstractUIPlugin implementation of this Plugin method saves this plug-in's org.eclipse.jface.preference and dialog stores and shuts down its image registry (if they are in use).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

AbstractUIPlugin

public AbstractUIPlugin(IPluginDescriptor descriptor)
Deprecated. In Eclipse 3.0 this constructor has been replaced by AbstractUIPlugin(). Implementations of MyPlugin(IPluginDescriptor descriptor) should be changed to MyPlugin() and call super() instead of super(descriptor). The MyPlugin(IPluginDescriptor descriptor) constructor is called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in (or, as in this case, subclasses which might).

Creates an abstract UI plug-in runtime object for the given plug-in descriptor.

Note that instances of plug-in runtime classes are automatically created by the platform in the course of plug-in activation.

Parameters:
descriptor - the plug-in descriptor
See Also:
Plugin#Plugin(org.eclipse.core.runtime.IPluginDescriptor descriptor)

AbstractUIPlugin

public AbstractUIPlugin()
Creates an abstract UI plug-in runtime object.

Plug-in runtime classes are BundleActivators and so must have an default constructor. This method is called by the runtime when the associated bundle is being activated.

For more details, see Plugin's default constructor.

Since:
3.0
See Also:
Plugin#Plugin()
Method Detail

createImageRegistry

protected ImageRegistry createImageRegistry()
Returns a new image registry for this plugin-in. The registry will be used to manage images which are frequently used by the plugin-in.

The default implementation of this method creates an empty registry. Subclasses may override this method if needed.

Returns:
ImageRegistry the resulting registry.
See Also:
getImageRegistry()

getImageRegistry

public ImageRegistry getImageRegistry()
Returns the image registry for this UI plug-in.

The image registry contains the images used by this plug-in that are very frequently used and so need to be globally shared within the plug-in. Since many OSs have a severe limit on the number of images that can be in memory at any given time, a plug-in should only keep a small number of images in their registry.

Subclasses should reimplement initializeImageRegistry if they have custom graphic images to load.

Subclasses may override this method but are not expected to.

Returns:
the image registry

getPreferenceStore

public IPreferenceStore getPreferenceStore()
Returns the org.eclipse.jface.preference store for this UI plug-in. This org.eclipse.jface.preference store is used to hold persistent settings for this plug-in in the context of a workbench. Some of these settings will be user controlled, whereas others may be internal setting that are never exposed to the user.

If an error occurs reading the org.eclipse.jface.preference store, an empty org.eclipse.jface.preference store is quietly created, initialized with defaults, and returned.

NOTE: As of Eclipse 3.1 this method is no longer referring to the core runtime compatibility layer and so plug-ins relying on Plugin#initializeDefaultPreferences will have to access the compatibility layer themselves.

Returns:
the org.eclipse.jface.preference store

getWorkbench

public IWorkbench getWorkbench()
Returns the Platform UI workbench.

This method exists as a convenience for plugin implementors. The workbench can also be accessed by invoking PlatformUI.getWorkbench().

Returns:
IWorkbench the workbench for this plug-in

initializeDefaultPreferences

protected void initializeDefaultPreferences(IPreferenceStore store)
Deprecated. this is only called if the runtime compatibility layer is present. See initializeDefaultPluginPreferences().

Initializes a org.eclipse.jface.preference store with default org.eclipse.jface.preference values for this plug-in.

This method is called after the org.eclipse.jface.preference store is initially loaded (default values are never stored in org.eclipse.jface.preference stores).

The default implementation of this method does nothing. Subclasses should reimplement this method if the plug-in has any preferences.

A subclass may reimplement this method to set default values for the org.eclipse.jface.preference store using JFace API. This is the older way of initializing default values. If this method is reimplemented, do not override initializeDefaultPluginPreferences().

Parameters:
store - the org.eclipse.jface.preference store to fill

initializeDefaultPluginPreferences

protected void initializeDefaultPluginPreferences()
Deprecated. this is only called if the runtime compatibility layer is present. See the deprecated comment in Plugin#initializeDefaultPluginPreferences.

The AbstractUIPlugin implementation of this Plugin method forwards to initializeDefaultPreferences(IPreferenceStore).

A subclass may reimplement this method to set default values for the core runtime org.eclipse.jface.preference store in the standard way. This is the recommended way to do this. The older initializeDefaultPreferences(IPreferenceStore) method serves a similar purpose. If this method is reimplemented, do not send super, and do not override initializeDefaultPreferences(IPreferenceStore).

Since:
2.0
See Also:
initializeDefaultPreferences(org.eclipse.jface.preference.IPreferenceStore)

initializeImageRegistry

protected void initializeImageRegistry(ImageRegistry reg)
Initializes an image registry with images which are frequently used by the plugin.

The image registry contains the images used by this plug-in that are very frequently used and so need to be globally shared within the plug-in. Since many OSs have a severe limit on the number of images that can be in memory at any given time, each plug-in should only keep a small number of images in its registry.

Implementors should create a JFace image descriptor for each frequently used image. The descriptors describe how to create/find the image should it be needed. The image described by the descriptor is not actually allocated until someone retrieves it.

Subclasses may override this method to fill the image registry.

Parameters:
reg - the registry to initalize
See Also:
getImageRegistry()

loadPreferenceStore

protected void loadPreferenceStore()
Deprecated. As of Eclipse 2.0, a basic org.eclipse.jface.preference store exists for all plug-ins. This method now exists only for backwards compatibility. It is called as the plug-in's org.eclipse.jface.preference store is being initialized. The plug-ins preferences are loaded from the file regardless of what this method does.

Loads the org.eclipse.jface.preference store for this plug-in. The default implementation looks for a standard named file in the plug-in's read/write state area. If no file is found or a problem occurs, a new empty org.eclipse.jface.preference store is silently created.

This framework method may be overridden, although this is typically unnecessary.


savePreferenceStore

protected void savePreferenceStore()
Deprecated. As of Eclipse 2.0, preferences exist for all plug-ins. The equivalent of this method is Plugin.savePluginPreferences. This method now calls savePluginPreferences, and exists only for backwards compatibility.

Saves this plug-in's org.eclipse.jface.preference store. Any problems which arise are silently ignored.

See Also:
Plugin#savePluginPreferences()

startup

public void startup()
             throws CoreException
Deprecated. In Eclipse 3.0, startup has been replaced by Plugin#start(BundleContext context). Implementations of startup should be changed to extend start(BundleContext context) and call super.start(context) instead of super.startup(). Like super.startup(), super.stop(context) must be called as the very first thing. The startup method is called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in; in contrast, the start method is always called.

The AbstractUIPlugin implementation of this Plugin method does nothing. Subclasses may extend this method, but must send super first.

WARNING: Plug-ins may not be started in the UI thread. The startup() method should not assume that its code runs in the UI thread, otherwise SWT thread exceptions may occur on startup.'

Throws:
CoreException

shutdown

public void shutdown()
              throws CoreException
Deprecated. In Eclipse 3.0, shutdown has been replaced by Plugin#stop(BundleContext context). Implementations of shutdown should be changed to extend stop(BundleContext context) and call super.stop(context) instead of super.shutdown(). Unlike super.shutdown(), super.stop(context) must be called as the very last thing rather than as the very first thing. The shutdown method is called only for plug-ins which explicitly require the org.eclipse.core.runtime.compatibility plug-in; in contrast, the stop method is always called.

The AbstractUIPlugin implementation of this Plugin method does nothing. Subclasses may extend this method, but must send super first.

Throws:
CoreException

start

public void start(BundleContext context)
           throws Exception
The AbstractUIPlugin implementation of this Plugin method refreshes the plug-in actions. Subclasses may extend this method, but must send super first. {@inheritDoc}

Throws:
Exception
Since:
3.0

stop

public void stop(BundleContext context)
          throws Exception
The AbstractUIPlugin implementation of this Plugin method saves this plug-in's org.eclipse.jface.preference and dialog stores and shuts down its image registry (if they are in use). Subclasses may extend this method, but must send super last. A try-finally statement should be used where necessary to ensure that super.shutdown() is always done. {@inheritDoc}

Throws:
Exception
Since:
3.0

imageDescriptorFromPlugin

public static ImageDescriptor imageDescriptorFromPlugin(String pluginId,
                                                        String imageFilePath)
Creates and returns a new image descriptor for an image file located within the specified plug-in.

This is a convenience method that simply locates the image file in within the plug-in (no image registries are involved). The path is relative to the root of the plug-in, and takes into account files coming from plug-in fragments. The path may include $arg$ elements. However, the path must not have a leading "." or path separator. Clients should use a path like "icons/mysample.gif" rather than "./icons/mysample.gif" or "/icons/mysample.gif".

Parameters:
pluginId - the id of the plug-in containing the image file; null is returned if the plug-in does not exist
imageFilePath - the relative path of the image file, relative to the root of the plug-in; the path must be legal
Returns:
an image descriptor, or null if no image could be found
Since:
3.0

Eclipse eRCP
Release 1.1