org.eclipse.ui.part
Class MultiPageEditorPart

java.lang.Object
  |
  +--org.eclipse.ui.part.WorkbenchPart
        |
        +--org.eclipse.ui.part.EditorPart
              |
              +--org.eclipse.ui.part.MultiPageEditorPart

All Implemented Interfaces:

IAdaptable, IEditorPart, IExecutableExtension, IWorkbenchPart

public abstract class MultiPageEditorPart

extends EditorPart

A multi-page editor is an editor with multiple pages, each of which may contain an editor or an arbitrary SWT control.

Subclasses must implement the following methods:

• createPages - to create the required pages by calling one of the addPage methods
• IEditorPart.doSave - to save contents of editor
• IEditorPart.doSaveAs - to save contents of editor
• IEditorPart.isSaveAsAllowed - to enable Save As
• IEditorPart.gotoMarker - to scroll to a marker

Multi-page editors have a single action bar contributor, which manages contributions for all the pages. The contributor must be a subclass of AbstractMultiPageEditorActionBarContributor. Note that since any nested editors are created directly in code by callers of addPage(IEditorPart,IEditorInput), nested editors do not have their own contributors.

See Also:

AbstractMultiPageEditorActionBarContributor

Field Summary

Fields inherited from interface org.eclipse.ui.IEditorPart

PROP_DIRTY, PROP_INPUT

Fields inherited from interface org.eclipse.ui.IWorkbenchPart

PROP_TITLE

Constructor Summary

protected

MultiPageEditorPart() Creates an empty multi-page editor with no pages.

Method Summary

int	addPage(Control control) Creates and adds a new page containing the given control to this multi-page editor.
int	addPage(IEditorPart editor, IEditorInput input) Creates and adds a new page containing the given editor to this multi-page editor.
protected abstract void	createPages() Creates the pages of this multi-page editor.
void	createPartControl(Composite parent) The MultiPageEditor implementation of this IWorkbenchPart method creates the control for the multi-page editor by calling createContainer, then createPages.
protected IEditorSite	createSite(IEditorPart editor) Creates the site for the given nested editor.
void	dispose() The MultiPageEditorPart implementation of this IWorkbenchPart method disposes all nested editors.
protected IEditorPart	getActiveEditor() Returns the active nested editor if there is one.
protected int	getActivePage() Returns the index of the currently active page, or -1 if there is no active page.
protected Composite	getContainer() Returns the composite control containing this multi-page editor's pages.
protected Control	getControl(int pageIndex) Returns the control for the given page index, or null if no control has been set for the page.
protected IEditorPart	getEditor(int pageIndex) Returns the editor for the given page index.
protected int	getPageCount() Returns the number of pages in this multi-page editor.
protected Image	getPageImage(int pageIndex) Returns the image for the page with the given index, or null if no image has been set for the page.
protected String	getPageText(int pageIndex) Returns the text label for the page with the given index.
protected void	handlePropertyChange(int propertyId) Handles a property change notification from a nested editor.
void	init(IEditorSite site, IEditorInput input) The MultiPageEditorPart implementation of this IEditorPart method sets its site to the given site, its input to the given input, and the site's selection provider to a MultiPageSelectionProvider.
boolean	isDirty() The MultiPageEditorPart implementation of this IEditorPart method returns whether the contents of any of this multi-page editor's nested editors have changed since the last save.
protected void	pageChange(int newPageIndex) Notifies this multi-page editor that the page with the given id has been activated.
void	removePage(int pageIndex) Removes the page with the given index from this multi-page editor.
protected void	setActivePage(int pageIndex) Sets the currently active page.
protected void	setControl(int pageIndex, Control control) Sets the control for the given page index.
void	setFocus() The MultiPageEditor implementation of this IWorkbenchPart method sets focus on the active nested editor, if there is one.
protected void	setPageImage(int pageIndex, Image image) Sets the image for the page with the given index, or null to clear the image for the page.
protected void	setPageText(int pageIndex, String text) Sets the text label for the page with the given index.

Methods inherited from class org.eclipse.ui.part.EditorPart

doSave, doSaveAs, getEditorInput, getEditorSite, getTitleToolTip, gotoMarker, isSaveAsAllowed, isSaveOnCloseNeeded, setInput

Methods inherited from class org.eclipse.ui.part.WorkbenchPart

addPropertyListener, firePropertyChange, getAdapter, getConfigurationElement, getDefaultImage, getSite, getTitle, getTitleImage, removePropertyListener, setInitializationData, setSite, setTitle, setTitleImage, setTitleToolTip

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.eclipse.ui.IWorkbenchPart

addPropertyListener, getSite, getTitle, getTitleImage, removePropertyListener

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

getAdapter

Constructor Detail

MultiPageEditorPart

protected MultiPageEditorPart()

Creates an empty multi-page editor with no pages.

Method Detail

addPage

public int addPage(Control control)

Creates and adds a new page containing the given control to this multi-page editor. The control may be null, allowing it to be created and set later using setControl.

Parameters:

control - the control, or null

Returns:

the index of the new page

See Also:

setControl(int, org.eclipse.swt.widgets.Control)

addPage

public int addPage(IEditorPart editor,
                   IEditorInput input)
            throws PartInitException

Creates and adds a new page containing the given editor to this multi-page editor. This also hooks a property change listener on the nested editor.

Parameters:

editor - the nested editor

input - the input for the nested editor

Returns:

the index of the new page

Throws:

PartInitException - if a new page could not be created

See Also:

the handler for property change events from the nested editor

createPages

protected abstract void createPages()

Creates the pages of this multi-page editor.

Subclasses must implement this method.

createPartControl

public final void createPartControl(Composite parent)

The MultiPageEditor implementation of this IWorkbenchPart method creates the control for the multi-page editor by calling createContainer, then createPages. Subclasses should implement createPages rather than overriding this method.

Specified by:

createPartControl in interface IWorkbenchPart

Specified by:

createPartControl in class WorkbenchPart

Parameters:

parent - the parent control

createSite

protected IEditorSite createSite(IEditorPart editor)

Creates the site for the given nested editor. The MultiPageEditorPart implementation of this method creates an instance of MultiPageEditorSite. Subclasses may reimplement to create more specialized sites.

Parameters:

editor - the nested editor

Returns:

the editor site

dispose

public void dispose()

The MultiPageEditorPart implementation of this IWorkbenchPart method disposes all nested editors. Subclasses may extend.

Specified by:

dispose in interface IWorkbenchPart

Overrides:

dispose in class WorkbenchPart

getActiveEditor

protected IEditorPart getActiveEditor()

Returns the active nested editor if there is one.

Subclasses should not override this method

Returns:

the active nested editor, or null if none

getActivePage

protected int getActivePage()

Returns the index of the currently active page, or -1 if there is no active page.

Subclasses should not override this method

Returns:

the index of the active page, or -1 if there is no active page

getContainer

protected Composite getContainer()

Returns the composite control containing this multi-page editor's pages. This should be used as the parent when creating controls for the individual pages. That is, when calling addPage(Control), the passed control should be a child of this container.

Warning: Clients should not assume that the container is any particular subclass of Composite. The actual class used may change in order to improve the look and feel of multi-page editors. Any code making assumptions on the particular subclass would thus be broken.

Subclasses should not override this method

Returns:

the composite, or null if createPartControl has not been called yet

getControl

protected Control getControl(int pageIndex)

Returns the control for the given page index, or null if no control has been set for the page. The page index must be valid.

Subclasses should not override this method

Parameters:

pageIndex - the index of the page

Returns:

the control for the specified page, or null if none has been set

getEditor

protected IEditorPart getEditor(int pageIndex)

Returns the editor for the given page index. The page index must be valid.

Parameters:

pageIndex - the index of the page

Returns:

the editor for the specified page, or null if the specified page was not created with addPage(IEditorPart,IEditorInput)

getPageCount

protected int getPageCount()

Returns the number of pages in this multi-page editor.

Returns:

the number of pages

getPageImage

protected Image getPageImage(int pageIndex)

Returns the image for the page with the given index, or null if no image has been set for the page. The page index must be valid.

Parameters:

pageIndex - the index of the page

Returns:

the image, or null if none

getPageText

protected String getPageText(int pageIndex)

Returns the text label for the page with the given index. Returns the empty string if no text label has been set for the page. The page index must be valid.

Parameters:

pageIndex - the index of the page

Returns:

the text label for the page

handlePropertyChange

protected void handlePropertyChange(int propertyId)

Handles a property change notification from a nested editor. The default implementation simply forwards the change to listeners on this multi-page editor by calling firePropertyChange with the same property id. For example, if the dirty state of a nested editor changes (property id IEditorPart.PROP_DIRTY), this method handles it by firing a property change event for IEditorPart.PROP_DIRTY to property listeners on this multi-page editor.

Subclasses may extend or reimplement this method.

Parameters:

propertyId - the id of the property that changed

init

public void init(IEditorSite site,
                 IEditorInput input)
          throws PartInitException

The MultiPageEditorPart implementation of this IEditorPart method sets its site to the given site, its input to the given input, and the site's selection provider to a MultiPageSelectionProvider. Subclasses may extend this method.

Specified by:

init in interface IEditorPart

Specified by:

init in class EditorPart

Parameters:

site - the editor site

input - the editor input

Throws:

PartInitException - if this editor was not initialized successfully

isDirty

public boolean isDirty()

The MultiPageEditorPart implementation of this IEditorPart method returns whether the contents of any of this multi-page editor's nested editors have changed since the last save. Pages created with addPage(Control) are ignored.

Subclasses may extend or reimplement this method.

Specified by:

isDirty in interface IEditorPart

Specified by:

isDirty in class EditorPart

Returns:

true if the contents have been modified and need saving, and false if they have not changed since the last save

pageChange

protected void pageChange(int newPageIndex)

Notifies this multi-page editor that the page with the given id has been activated. This method is called when the user selects a different tab.

The MultiPageEditorPart implementation of this method sets focus to the new page, and notifies the action bar contributor (if there is one). This checks whether the action bar contributor is an instance of MultiPageEditorActionBarContributor, and, if so, calls setActivePage with the active nested editor. This also fires a selection change event if required.

Subclasses may extend this method.

Parameters:

newPageIndex - the index of the activated page

removePage

public void removePage(int pageIndex)

Removes the page with the given index from this multi-page editor. The controls for the page are disposed of; if the page has an editor, it is disposed of too. The page index must be valid.

Parameters:

pageIndex - the index of the page

See Also:

addPage(org.eclipse.swt.widgets.Control)

setActivePage

protected void setActivePage(int pageIndex)

Sets the currently active page.

Parameters:

pageIndex - the index of the page to be activated; the index must be valid

setControl

protected void setControl(int pageIndex,
                          Control control)

Sets the control for the given page index. The page index must be valid.

Parameters:

pageIndex - the index of the page

control - the control for the specified page, or null to clear the control

setFocus

public void setFocus()

The MultiPageEditor implementation of this IWorkbenchPart method sets focus on the active nested editor, if there is one.

Subclasses may extend or reimplement.

Specified by:

setFocus in interface IWorkbenchPart

Specified by:

setFocus in class WorkbenchPart

setPageImage

protected void setPageImage(int pageIndex,
                            Image image)

Sets the image for the page with the given index, or null to clear the image for the page. The page index must be valid.

Parameters:

pageIndex - the index of the page

image - the image, or null

setPageText

protected void setPageText(int pageIndex,
                           String text)

Sets the text label for the page with the given index. The page index must be valid. The text label must not be null.

Parameters:

pageIndex - the index of the page

text - the text label