|
Eclipse eRCP Release 1.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.ObjectPlugin
org.eclipse.ui.plugin.AbstractUIPlugin
Abstract base class for plug-ins that integrate with the Eclipse platform UI.
Subclasses obtain the following capabilities:
Preferences
org.eclipse.core.runtime.Preferences
).
This class provides appropriate conversion to the older JFace org.eclipse.jface.preference
API (org.eclipse.jface.preference.IPreferenceStore
).getPreferenceStore
returns the JFace org.eclipse.jface.preference
store (cf. Plugin.getPluginPreferences
which returns
a core runtime preferences object.initializeDefaultPreferences
to set up any default values for preferences using JFace API. In this
case, initializeDefaultPluginPreferences
should not be
overridden.initializeDefaultPluginPreferences
to set up any default
values for preferences using core runtime API. In this
case, initializeDefaultPreferences
should not be
overridden.getDialogSettings
is called.FN_DIALOG_STORE
. A dialog store file is first
looked for in the plug-in's read/write state area; if not found there,
the plug-in's install directory is checked.
This allows a plug-in to ship with a read-only copy of a dialog store
file containing initial values for certain settings.saveDialogSettings
to cause settings to
be saved in the plug-in's read/write state area. A plug-in may opt to do
this each time a wizard or dialog is closed to ensure the latest
information is always safe on disk.
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
.
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 |
public AbstractUIPlugin(IPluginDescriptor descriptor)
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).
Note that instances of plug-in runtime classes are automatically created by the platform in the course of plug-in activation.
descriptor
- the plug-in descriptorPlugin#Plugin(org.eclipse.core.runtime.IPluginDescriptor descriptor)
public AbstractUIPlugin()
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.
Plugin#Plugin()
Method Detail |
protected ImageRegistry createImageRegistry()
The default implementation of this method creates an empty registry. Subclasses may override this method if needed.
getImageRegistry()
public ImageRegistry getImageRegistry()
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.
public IPreferenceStore getPreferenceStore()
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.
public IWorkbench getWorkbench()
This method exists as a convenience for plugin implementors. The
workbench can also be accessed by invoking PlatformUI.getWorkbench()
.
protected void initializeDefaultPreferences(IPreferenceStore store)
initializeDefaultPluginPreferences()
.
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()
.
store
- the org.eclipse.jface.preference store to fillprotected void initializeDefaultPluginPreferences()
Plugin#initializeDefaultPluginPreferences
.
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)
.
initializeDefaultPreferences(org.eclipse.jface.preference.IPreferenceStore)
protected void initializeImageRegistry(ImageRegistry reg)
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.
reg
- the registry to initalizegetImageRegistry()
protected void loadPreferenceStore()
This framework method may be overridden, although this is typically unnecessary.
protected void savePreferenceStore()
Plugin.savePluginPreferences
.
This method now calls savePluginPreferences
, and exists only for
backwards compatibility.
Plugin#savePluginPreferences()
public void startup() throws CoreException
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.
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.'
CoreException
public void shutdown() throws CoreException
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.
AbstractUIPlugin
implementation of this Plugin
method does nothing. Subclasses may extend this method, but must send
super first.
CoreException
public void start(BundleContext context) throws Exception
AbstractUIPlugin
implementation of this Plugin
method refreshes the plug-in actions. Subclasses may extend this method,
but must send super first.
{@inheritDoc}
Exception
public void stop(BundleContext context) throws Exception
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}
Exception
public static ImageDescriptor imageDescriptorFromPlugin(String pluginId, String imageFilePath)
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".
pluginId
- the id of the plug-in containing the image file;
null
is returned if the plug-in does not existimageFilePath
- the relative path of the image file, relative to the
root of the plug-in; the path must be legal
null
if no image
could be found
|
Eclipse eRCP Release 1.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |