Package 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

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

Fields
`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

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

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`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.
`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.
`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` `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.
`<T> T` `getAdapter​(Class<T> 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 <T> T getAdapter​(Class<T> 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`
Type Parameters:
  `T` - the class type
Parameters:
  `adapter` - the adapter class to look up
Returns:
  a object of 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: