Package org.eclipse.ui.part

Class 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

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

      • 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

      • 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(), createPageContainer(Composite), getPageSite(int), PAGE_CONTAINER_SITE

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