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:

  • Field Details

  • Constructor Details

    • MultiPageEditorPart

      protected MultiPageEditorPart()
      Creates an empty multi-page editor with no pages and registers a PropertyChangeListener to listen for changes to the editor's preference..

  • Method Details

    • isUpdateRequired

      protected boolean isUpdateRequired(PropertyChangeEvent event)
      Determines whether an update is required based on a property change event.
      Parameters:
      event - the PropertyChangeEvent triggered by a change in the preference store
      Since:
      3.134

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

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

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

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

    • createContainer

      protected CTabFolder createContainer(Composite parent)
      Creates an empty container. Creates a CTabFolder with no style bits set, and hooks a selection listener which calls pageChange() whenever the selected tab changes.
      Parameters:
      parent - The composite in which the container tab folder should be created; must not be null.
      Returns:
      a new container
      Since:
      3.115

    • getTabStyle

      protected int getTabStyle()
      Determines the tab style based on user preferences.

      This method retrieves the user preference for aligning multi-page editor tabs on top or bottom, and returns the corresponding SWT style constant.

      Returns:
      SWT.TOP if the user prefers tabs to be aligned on top, SWT.BOTTOM if the user prefers tabs to be aligned on the bottom.
      Since:
      3.134

    • getAPIPreferenceStore

      protected IPreferenceStore getAPIPreferenceStore()
      Since:
      3.134

    • createItem

      protected CTabItem createItem(int index, Control control)
      Creates a tab item at the given index and places the given control in the new item. The item is a CTabItem with no style bits set.
      Parameters:
      index - the index at which to add the control
      control - is the control to be placed in an item
      Returns:
      a new item
      Since:
      3.115

    • createPages

      protected abstract void createPages()
      Creates the pages of this multi-page editor.

      Subclasses must implement this method.

    • createPartControl

      public 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

      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:

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

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

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

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

    • updateContainer

      protected void updateContainer()
      Updates the tab position of the container in the multi-page editor.

      This method retrieves the current container and sets the tab position based on the user preference.

      Since:
      3.134