org.eclipse.ui
Interface IWorkbenchPart

All Superinterfaces:

IAdaptable

All Known Subinterfaces:

IDebugView, IEditorPart, IResourceNavigator, IReusableEditor, ISearchResultView, ITextEditor, IViewPart

All Known Implementing Classes:

AbstractDebugView, AbstractTextEditor, EditorPart, ResourceNavigator, ViewPart, WorkbenchPart

public interface IWorkbenchPart

extends IAdaptable

A workbench part is a visual component within a workbench page. There are two subtypes: view and editor, as defined by IViewPart and IEditorPart.

A view is typically used to navigate a hierarchy of information (like the workspace), open an editor, or display properties for the active editor. Modifications made in a view are saved immediately.

An editor is typically used to edit or browse a document or input object. The input is identified using an IEditorInput. Modifications made in an editor part follow an open-save-close lifecycle model.

This interface may be implemented directly. For convenience, a base implementation is defined in WorkbenchPart.

The lifecycle of a workbench part is as follows:

• When a part extension is created:
  • instantiate the part
  • create a part site
  • call part.init(site)
• When a part becomes visible in the workbench:
  • add part to presentation by calling part.createControl(parent) to create actual widgets
  • fire partOpened event to all listeners
• When a part is activated or gets focus:
  • call part.setFocus()
  • fire partActivated event to all listeners
• When a part is closed:
  • if save is needed, do save; if it fails or is canceled return
  • if part is active, deactivate part
  • fire partClosed event to all listeners
  • remove part from presentation; part controls are disposed as part of the SWT widget tree
  • call part.dispose()

After createPartControl has been called, the implementor may safely reference the controls created. When the part is closed these controls will be disposed as part of an SWT composite. This occurs before the IWorkbenchPart.dispose method is called. If there is a need to free SWT resources the part should define a dispose listener for its own control and free those resources from the dispose listener. If the part invokes any method on the disposed SWT controls after this point an SWTError will be thrown.

The last method called on IWorkbenchPart is dispose. This signals the end of the part lifecycle.

An important point to note about this lifecycle is that following a call to init, createControl may never be called. Thus in the dispose method, implementors must not assume controls were created.

Workbench parts implement the IAdaptable interface; extensions are managed by the platform's adapter manager.

See Also:

IViewPart, IEditorPart

Field Summary

static int

PROP_TITLE The property id for getTitle and getTitleImage.

Method Summary

void	addPropertyListener(IPropertyListener listener) Adds a listener for changes to properties of this workbench part.
void	createPartControl(Composite parent) Creates the SWT controls for this workbench part.
void	dispose() Disposes of this workbench part.
IWorkbenchPartSite	getSite() Returns the site for this workbench part.
String	getTitle() Returns the title of this workbench part.
Image	getTitleImage() Returns the title image of this workbench part.
String	getTitleToolTip() Returns the title tool tip text of this workbench part.
void	removePropertyListener(IPropertyListener listener) Removes the given property listener from this workbench part.
void	setFocus() Asks this part to take focus within the workbench.

Methods inherited from interface org.eclipse.core.runtime.IAdaptable

getAdapter

Field Detail

PROP_TITLE

public static final int PROP_TITLE

The property id for getTitle and getTitleImage.

See Also:

Constant Field Values

Method Detail

addPropertyListener

public void addPropertyListener(IPropertyListener listener)

Adds a listener for changes to properties of this workbench part. Has no effect if an identical listener is already registered.

The properties ids are as follows:

• IWorkbenchPart.PROP_TITLE
• IEditorPart.PROP_INPUT
• IEditorPart.PROP_DIRTY

Parameters:

listener - a property listener

createPartControl

public void createPartControl(Composite parent)

Creates the SWT controls for this workbench part.

Clients should not call this method (the workbench calls this method when it needs to, which may be never).

For implementors this is a multi-step process:

1. Create one or more controls within the parent.
2. Set the parent layout as needed.
3. Register any global actions with the IActionService.
4. Register any popup menus with the IActionService.
5. Register a selection provider with the ISelectionService (optional).

Parameters:

parent - the parent control

dispose

public void dispose()

Disposes of this workbench part.

This is the last method called on the IWorkbenchPart. At this point the part controls (if they were ever created) have been disposed as part of an SWT composite. There is no guarantee that createPartControl() has been called, so the part controls may never have been created.

Within this method a part may release any resources, fonts, images, etc. held by this part. It is also very important to deregister all listeners from the workbench.

Clients should not call this method (the workbench calls this method at appropriate times).

getSite

public IWorkbenchPartSite getSite()

Returns the site for this workbench part.

Returns:

the part site

getTitle

public String getTitle()

Returns the title of this workbench part. If this value changes the part must fire a property listener event with PROP_TITLE.

The title is used to populate the title bar of this part's visual container.

Returns:

the workbench part title

getTitleImage

public Image getTitleImage()

Returns the title image of this workbench part. If this value changes the part must fire a property listener event with PROP_TITLE.

The title image is usually used to populate the title bar of this part's visual container. Since this image is managed by the part itself, callers must not dispose the returned image.

Returns:

the title image

getTitleToolTip

public String getTitleToolTip()

Returns the title tool tip text of this workbench part. If this value changes the part must fire a property listener event with PROP_TITLE.

The tool tip text is used to populate the title bar of this part's visual container.

Returns:

the workbench part title tool tip

removePropertyListener

public void removePropertyListener(IPropertyListener listener)

Removes the given property listener from this workbench part. Has no affect if an identical listener is not registered.

Parameters:

listener - a property listener

setFocus

public void setFocus()

Asks this part to take focus within the workbench.

Clients should not call this method (the workbench calls this method at appropriate times).