Eclipse Plug-in Developer Guide (Galileo) - MultiPageEditorPart (Eclipse Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.ui.part
Class MultiPageEditorPart


java.lang.Object
  

org.eclipse.core.commands.common.EventManager
      

org.eclipse.ui.part.WorkbenchPart
          

org.eclipse.ui.part.EditorPart
              
org.eclipse.ui.part.MultiPageEditorPart

All Implemented Interfaces:: IAdaptable, IExecutableExtension, IPageChangeProvider, IEditorPart, ISaveablePart, IWorkbenchPart, IWorkbenchPart2, IWorkbenchPart3, IWorkbenchPartOrientation

Direct Known Subclasses:: FormEditor

public abstract class MultiPageEditorPart
extends EditorPart
implements IPageChangeProvider
extends EditorPart
implements IPageChangeProvider

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 MultiPageEditorActionBarContributor. 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.

As of 3.5 multi-page editors will post PageChangedEvents at the end of pageChange(int). Subclasses may override getSelectedPage() to return a page appropriate to their multi-page editor. IPartListener2 listeners registered with the IPartService can implement IPageChangedListener to be notified about all page change events within the workbench page or workbench window.

See Also:: MultiPageEditorActionBarContributor, IPageChangeProvider, IPageChangedListener, IPartService

Field Summary

protected static int PAGE_CONTAINER_SITE
          Subclasses that override createPageContainer(Composite) can use this constant to get a site for the container that can be active while the current page is deactivated.

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

protected void activateSite ()
          This method can be used by implementors of createPageContainer(Composite) to activate the active inner editor services when their header loses focus.

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.

void addPage (int index, Control control)
          Creates and adds a new page containing the given control to this multi-page editor.

void addPage (int index, IEditorPart editor, IEditorInput input)
          Creates and adds a new page containing the given editor to this multi-page editor.

void addPageChangedListener ( IPageChangedListener listener)
          Add the page change listener to be notified when the page changes.

protected Composite createPageContainer ( Composite parent)
          Creates the parent control for the container returned by getContainer().

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.

protected void deactivateSite (boolean immediate, boolean containerSiteActive)
          This method can be used by implementors of createPageContainer(Composite) to deactivate the active inner editor services while their header has focus.

void dispose ()
          The MultiPageEditorPart implementation of this IWorkbenchPart method disposes all nested editors.

IEditorPart[] findEditors ( IEditorInput input)
          Find the editors contained in this multi-page editor whose editor input match the provided input.

protected IEditorPart getActiveEditor ()
          Returns the active nested editor if there is one.

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

Object getAdapter ( Class adapter)
          If there is an adapter registered against the subclass of MultiPageEditorPart return that.

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 IServiceLocator getPageSite (int pageIndex)
          Returns the service locator for the given page index.

protected String getPageText (int pageIndex)
          Returns the text label for the page with the given index.

Object getSelectedPage ()
          Returns the selected page for the current active page index, either the IEditorPart for editors or the Control for other pages.

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.

protected void initializePageSwitching ()
          Initialize the MultiPageEditorPart to use the page switching command.

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.

void removePageChangedListener ( IPageChangedListener listener)
          Remove the page change listener.

void setActiveEditor ( IEditorPart editorPart)
          Set the active page of this multi-page editor to the page that contains the given editor part.

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

checkSite, doSave, doSaveAs, getEditorInput, getEditorSite, getTitleToolTip, isSaveAsAllowed, isSaveOnCloseNeeded, setContentDescription, setInitializationData, setInput, setInputWithNotify, setPartName

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

addPartPropertyListener, addPropertyListener, firePartPropertyChanged, firePropertyChange, getConfigurationElement, getContentDescription, getDefaultImage, getOrientation, getPartName, getPartProperties, getPartProperty, getSite, getTitle, getTitleImage, removePartPropertyListener, removePropertyListener, setPartProperty, setSite, setTitle, setTitleImage, setTitleToolTip, showBusy

Methods inherited from class org.eclipse.core.commands.common. EventManager

addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject

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

Field Detail

PAGE_CONTAINER_SITE

protected static final int PAGE_CONTAINER_SITE

Subclasses that override createPageContainer(Composite) can use this constant to get a site for the container that can be active while the current page is deactivated.

Since:: 3.4
See Also:: activateSite(), deactivateSite(boolean, boolean), getPageSite(int), Constant Field Values

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, Control)

addPage

public void addPage(int index,
                    
Control control)

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

Parameters:: index - the index at which to add the page (0-based); control - the control, or null
See Also:: setControl(int, 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

addPage

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

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

Parameters:: index - the index at which to add the page (0-based); editor - the nested editor; input - the input for the nested editor
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 in which the editor should be created; must not be null.

initializePageSwitching

protected void initializePageSwitching()

Initialize the MultiPageEditorPart to use the page switching command. Clients can override this method with an empty body if they wish to opt-out.

Since:: 3.4

createPageContainer

protected 
Composite createPageContainer(
Composite parent)

Creates the parent control for the container returned by getContainer().

Subclasses may extend and must call super implementation first.

Parameters:: parent - the parent for all of the editors contents.
Returns:: the parent for this editor's container. Must not be null.
Since:: 3.2

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
Restriction:

getActivePage

public 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
Since:: 3.5
Restriction:

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)

getPageSite

protected final 
IServiceLocator getPageSite(int pageIndex)

Returns the service locator for the given page index. This method can be used to create service locators for pages that are just controls. The page index must be valid.

This will return the editor site service locator for an editor, and create one for a page that is just a control.

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)
Since:: 3.4

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 site for which this part is being created; must not be null.; input - The input on which this editor should be created; must not be null.
Throws:: PartInitException - If the initialization of the part fails -- currently never.

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 ISaveablePart
Specified by:: isDirty in class EditorPart

Returns:: true if any of the nested editors are dirty; false otherwise.

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

deactivateSite

protected final void deactivateSite(boolean immediate,
                                    boolean containerSiteActive)

This method can be used by implementors of createPageContainer(Composite) to deactivate the active inner editor services while their header has focus. A deactivateSite() must have a matching call to activateSite() when appropriate.

An new inner editor will have its site activated on a pageChange(int).

Note: This API is evolving in 3.4 and this might not be its final form.

Parameters:: immediate - immediately deactivate the legacy keybinding service; containerSiteActive - Leave the page container site active.
Since:: 3.4
See Also:: activateSite(), createPageContainer(Composite), getPageSite(int), PAGE_CONTAINER_SITE

activateSite

protected final void activateSite()

This method can be used by implementors of createPageContainer(Composite) to activate the active inner editor services when their header loses focus.

An new inner editor will have its site activated on a pageChange(int).

Note: This API is evolving in 3.4 and this might not be its final form.

Since:: 3.4
See Also:: deactivateSite(boolean,boolean), createPageContainer(Composite), getPageSite(int)

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(Control), addPage(IEditorPart, IEditorInput)

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

getAdapter

public 
Object getAdapter(
Class adapter)

If there is an adapter registered against the subclass of MultiPageEditorPart return that. Otherwise, delegate to the internal editor.

Specified by:: getAdapter in interface IAdaptable
Overrides:: getAdapter in class WorkbenchPart

Parameters:: adapter - the adapter class to look up
Returns:: a object castable to the given class, or null if this object does not have an adapter for the given class
See Also:: WorkbenchPart.getAdapter(java.lang.Class)

findEditors

public final 
IEditorPart[] findEditors(
IEditorInput input)

Find the editors contained in this multi-page editor whose editor input match the provided input.

Parameters:: input - the editor input
Returns:: the editors contained in this multi-page editor whose editor input match the provided input
Since:: 3.3

setActiveEditor

public final void setActiveEditor(
IEditorPart editorPart)

Set the active page of this multi-page editor to the page that contains the given editor part. This method has no effect of the given editor part is not contained in this multi-page editor.

Parameters:: editorPart - the editor part
Since:: 3.3

getSelectedPage

public 
Object getSelectedPage()

Returns the selected page for the current active page index, either the IEditorPart for editors or the Control for other pages.

Note: clients may override this method to return a page appropriate for their editors. Maybe be null.

Specified by:: getSelectedPage in interface IPageChangeProvider

Returns:: The IEditorPart or Control representing the current active page, or null if there are no active pages.
Since:: 3.5
See Also:: getActivePage()

addPageChangedListener

public void addPageChangedListener(
IPageChangedListener listener)

Add the page change listener to be notified when the page changes. The newly selected page will be the Object returned from getSelectedPage(). In the default case, this will be the active page Control, IEditorPart, or null.

This method has no effect if the listener has already been added.

Specified by:: addPageChangedListener in interface IPageChangeProvider

Parameters:: listener - a page changed listener
Since:: 3.5
Restriction:

removePageChangedListener

public void removePageChangedListener(
IPageChangedListener listener)

Remove the page change listener.

This method has no effect if the listener is not in the list.

Specified by:: removePageChangedListener in interface IPageChangeProvider

Parameters:: listener - a page changed listener
Since:: 3.5
Restriction:

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Platform
Release 3.5

PREV CLASS NEXT CLASS

NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

org.eclipse.ui.part Class MultiPageEditorPart

PAGE_CONTAINER_SITE

MultiPageEditorPart

addPage

addPage

addPage

addPage

createPages

createPartControl

initializePageSwitching

createPageContainer

createSite

dispose

getActiveEditor

getActivePage

getContainer

getControl

getEditor

getPageSite

getPageCount

getPageImage

getPageText

handlePropertyChange

init

isDirty

pageChange

deactivateSite

activateSite

removePage

setActivePage

setControl

setFocus

setPageImage

setPageText

getAdapter

findEditors

setActiveEditor

getSelectedPage

addPageChangedListener

removePageChangedListener

org.eclipse.ui.part
Class MultiPageEditorPart