|
| |
|
| org.eclipse.ui.plugin.AbstractUIPlugin
All known Subclasses: org.eclipse.ui.internal.texteditor.TextEditorPlugin, org.eclipse.ui.internal.WorkbenchPlugin,
| AbstractUIPlugin | | abstract public class AbstractUIPlugin extends Plugin (Code) | | Abstract base class for plug-ins that integrate with the Eclipse platform UI.
Subclasses obtain the following capabilities:
Preferences
- The platform core runtime contains general support for plug-in
preferences (
org.eclipse.core.runtime.Preferences).
This class provides appropriate conversion to the older JFace preference
API (org.eclipse.jface.preference.IPreferenceStore).
- The method
getPreferenceStore returns the JFace preference
store (cf. Plugin.getPluginPreferences which returns
a core runtime preferences object.
- Subclasses may reimplement
initializeDefaultPreferences
to set up any default values for preferences using JFace API. In this
case, initializeDefaultPluginPreferences should not be
overridden.
- Subclasses may reimplement
initializeDefaultPluginPreferences to set up any default
values for preferences using core runtime API. In this
case, initializeDefaultPreferences should not be
overridden.
- Preferences are also saved automatically on plug-in shutdown.
However, saving preferences immediately after changing them is
strongly recommended, since that ensures that preference settings
are not lost even in the event of a platform crash.
Dialogs
- The dialog store is read the first time
getDialogSettings
is called.
- The dialog store allows the plug-in to "record" important choices made
by the user in a wizard or dialog, so that the next time the
wizard/dialog is used the widgets can be defaulted to better values. A
wizard could also use it to record the last 5 values a user entered into
an editable combo - to show "recent values".
- The dialog store is found in the file whose name is given by the
constant
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.
- Plug-in code can call
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.
- Dialog settings are also saved automatically on plug-in shutdown.
Images
- A typical UI plug-in will have some images that are used very frequently
and so need to be cached and shared. The plug-in's image registry
provides a central place for a plug-in to store its common images.
Images managed by the registry are created lazily as needed, and will be
automatically disposed of when the plug-in shuts down. Note that the
number of registry images should be kept to a minimum since many OSs
have severe limits on the number of images that can be in memory at once.
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 | |
| public | AbstractUIPlugin(IPluginDescriptor descriptor)
Creates an abstract UI plug-in runtime object for the given plug-in
descriptor. | | public | AbstractUIPlugin()
Creates an abstract UI plug-in runtime object.
Plug-in runtime classes are BundleActivators and so must
have an default constructor. |
| Method Summary | |
| protected ImageRegistry | createImageRegistry()
Returns a new image registry for this plugin-in. | | public IDialogSettings | getDialogSettings()
Returns the dialog settings for this UI plug-in.
The dialog settings is used to hold persistent state data for the various
wizards and dialogs of this plug-in in the context of a workbench. | | public ImageRegistry | getImageRegistry()
Returns the image registry for this UI plug-in. | | public IPreferenceStore | getPreferenceStore()
Returns the preference store for this UI plug-in.
This preference store is used to hold persistent settings for this plug-in in
the context of a workbench. | | public IWorkbench | getWorkbench()
Returns the Platform UI workbench. | | 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). | | protected void | 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 preference store in the standard way. | | protected void | initializeDefaultPreferences(IPreferenceStore store)
Initializes a preference store with default preference values
for this plug-in.
This method is called after the preference store is initially loaded
(default values are never stored in 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
preference store using JFace API. | | 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. | | protected void | loadDialogSettings()
Loads the dialog settings for this plug-in.
The default implementation first looks for a standard named file in the
plug-in's read/write state area; if no such file exists, the plug-in's
install directory is checked to see if one was installed with some default
settings; if no file is found in either place, a new empty dialog settings
is created. | | protected void | loadPreferenceStore()
Loads the preference store for this plug-in.
The default implementation looks for a standard named file in the
plug-in's read/write state area. | | protected void | refreshPluginActions()
Refreshes the actions for the plugin. | | protected void | saveDialogSettings()
Saves this plug-in's dialog settings. | | protected void | savePreferenceStore()
Saves this plug-in's preference store. | | public void | shutdown()
The AbstractUIPlugin implementation of this Plugin
method does nothing. | | public void | start(BundleContext context)
The AbstractUIPlugin implementation of this Plugin
method refreshes the plug-in actions. | | public void | startup()
The AbstractUIPlugin implementation of this Plugin
method does nothing. | | public void | stop(BundleContext context)
The AbstractUIPlugin implementation of this Plugin
method saves this plug-in's preference and dialog stores and shuts down
its image registry (if they are in use). |
| AbstractUIPlugin | | public AbstractUIPlugin(IPluginDescriptor descriptor)(Code) | | 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.AbstractUIPlugin() |
| AbstractUIPlugin | | public AbstractUIPlugin()(Code) | | 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.
See Also: Plugin.Plugin
since:
3.0 |
| createImageRegistry | | protected ImageRegistry createImageRegistry()(Code) | | 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.
ImageRegistry the resulting registry.
See Also: AbstractUIPlugin.getImageRegistry |
| getDialogSettings | | public IDialogSettings getDialogSettings()(Code) | | Returns the dialog settings for this UI plug-in.
The dialog settings is used to hold persistent state data for the various
wizards and dialogs of this plug-in in the context of a workbench.
If an error occurs reading the dialog store, an empty one is quietly created
and returned.
Subclasses may override this method but are not expected to.
the dialog settings |
| getImageRegistry | | public ImageRegistry getImageRegistry()(Code) | | 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.
the image registry |
| getPreferenceStore | | public IPreferenceStore getPreferenceStore()(Code) | | Returns the preference store for this UI plug-in.
This 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 preference store, an empty 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.
the preference store |
| getWorkbench | | public IWorkbench getWorkbench()(Code) | | Returns the Platform UI workbench.
This method exists as a convenience for plugin implementors. The
workbench can also be accessed by invoking PlatformUI.getWorkbench().
IWorkbench the workbench for this plug-in |
| imageDescriptorFromPlugin | | public static ImageDescriptor imageDescriptorFromPlugin(String pluginId, String imageFilePath)(Code) | | 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
Parameters:
imageFilePath - the relative path of the image file, relative to theroot of the plug-in; the path must be legal an image descriptor, or null if no imagecould be found
since:
3.0 |
| initializeDefaultPluginPreferences | | protected void initializeDefaultPluginPreferences()(Code) | | 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 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).
Plugin.initializeDefaultPluginPreferences
See Also: AbstractUIPlugin.initializeDefaultPreferences
since:
2.0 |
| initializeDefaultPreferences | | protected void initializeDefaultPreferences(IPreferenceStore store)(Code) | | Initializes a preference store with default preference values
for this plug-in.
This method is called after the preference store is initially loaded
(default values are never stored in 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
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 preference store to fillAbstractUIPlugin.initializeDefaultPluginPreferences |
| initializeImageRegistry | | protected void initializeImageRegistry(ImageRegistry reg)(Code) | | 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: AbstractUIPlugin.getImageRegistry |
| loadDialogSettings | | protected void loadDialogSettings()(Code) | | Loads the dialog settings for this plug-in.
The default implementation first looks for a standard named file in the
plug-in's read/write state area; if no such file exists, the plug-in's
install directory is checked to see if one was installed with some default
settings; if no file is found in either place, a new empty dialog settings
is created. If a problem occurs, an empty settings is silently used.
This framework method may be overridden, although this is typically
unnecessary.
|
| loadPreferenceStore | | protected void loadPreferenceStore()(Code) | | Loads the 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 preference store is silently created.
This framework method may be overridden, although this is typically
unnecessary.
|
| refreshPluginActions | | protected void refreshPluginActions()(Code) | | Refreshes the actions for the plugin.
This method is called from startup.
This framework method may be overridden, although this is typically
unnecessary.
|
| saveDialogSettings | | protected void saveDialogSettings()(Code) | | Saves this plug-in's dialog settings.
Any problems which arise are silently ignored.
|
| savePreferenceStore | | protected void savePreferenceStore()(Code) | | Saves this plug-in's preference store.
Any problems which arise are silently ignored.
See Also: Plugin.savePluginPreferences |
| shutdown | | public void shutdown() throws CoreException(Code) | | The AbstractUIPlugin implementation of this Plugin
method does nothing. Subclasses may extend this method, but must send
super first.
Plugin.stop(BundleContext context) |
| start | | public void start(BundleContext context) throws Exception(Code) | | The AbstractUIPlugin implementation of this Plugin
method refreshes the plug-in actions. Subclasses may extend this method,
but must send super first.
since:
3.0 |
| startup | | public void startup() throws CoreException(Code) | | 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.'
Plugin.start(BundleContext context) |
| stop | | public void stop(BundleContext context) throws Exception(Code) | | The AbstractUIPlugin implementation of this Plugin
method saves this plug-in's 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.
since:
3.0 |
|
|
|