org.eclipse.ui
Interface IWorkbenchPage

All Superinterfaces:
org.eclipse.ui.internal.ICompatibleWorkbenchPage, IPartService, ISelectionService

public interface IWorkbenchPage
extends IPartService, ISelectionService, org.eclipse.ui.internal.ICompatibleWorkbenchPage

A workbench page consists of an arrangement of views and editors intended to be presented together to the user in a single workbench org.eclipse.jface.window.

A page can contain 0 or more views and 0 or more editors. These views and editors are contained wholly within the page and are not shared with other pages. The layout and visible action set for the page is defined by a perspective.

The number of views and editors within a page is restricted to simplify part management for the user. In particular:

This interface is not intended to be implemented by clients.

See Also:
IPerspectiveDescriptor, IEditorPart, IViewPart

Field Summary
static java.lang.String CHANGE_ACTION_SET_HIDE
          Change event id when an action set is hidden in a perspective.
static java.lang.String CHANGE_ACTION_SET_SHOW
          Change event id when an action set is shown in a perspective.
static java.lang.String CHANGE_EDITOR_AREA_HIDE
          Change event id when the editor area is hidden in a perspective.
static java.lang.String CHANGE_EDITOR_AREA_SHOW
          Change event id when the editor area is shown in a perspective.
static java.lang.String CHANGE_EDITOR_CLOSE
          Change event id when one or more editors are closed in a perspective.
static java.lang.String CHANGE_EDITOR_OPEN
          Change event id when one or more editors are opened in a perspective.
static java.lang.String CHANGE_FAST_VIEW_ADD
          Change event id when a fast view is added in a perspective.
static java.lang.String CHANGE_FAST_VIEW_REMOVE
          Change event id when a fast view is removed in a perspective.
static java.lang.String CHANGE_RESET
          Change event id when the perspective is reset to its original state.
static java.lang.String CHANGE_RESET_COMPLETE
          Change event id when the perspective has completed a reset to its original state.
static java.lang.String CHANGE_VIEW_HIDE
          Change event id when one or more views are hidden in a perspective.
static java.lang.String CHANGE_VIEW_SHOW
          Change event id when one or more views are shown in a perspective.
static java.lang.String CHANGE_WORKING_SET_REPLACE
          Change event id when the page working set was replaced
static java.lang.String EDITOR_ID_ATTR
          Deprecated. in 3.0 since the notion of markers this is not generally applicable. Use the IDE-specific constant IDE.EDITOR_ID_ATTR.
static int VIEW_ACTIVATE
          Show view mode that indicates the view should be made visible and activated.
static int VIEW_CREATE
          Show view mode that indicates the view should be made created but not necessarily be made visible.
static int VIEW_VISIBLE
          Show view mode that indicates the view should be made visible.
 
Method Summary
 void activate(IWorkbenchPart part)
          Activates the given part.
 void addPropertyChangeListener(IPropertyChangeListener listener)
          Deprecated. individual views should store a working set if needed and register a property change listener directly with the working set manager to receive notification when the view working set is removed.
 void bringToTop(IWorkbenchPart part)
          Moves the given part forward in the Z order of this page so as to make it visible, without changing which part has focus.
 boolean close()
          Closes this workbench page.
 void closeAllPerspectives(boolean saveEditors, boolean closePage)
          Closes all perspectives in this page.
 void closePerspective(IPerspectiveDescriptor desc, boolean saveEditors, boolean closePage)
          Closes the specified perspective in this page.
 IViewPart findView(java.lang.String viewId)
          Returns the view in this page with the specified id.
 IViewReference findViewReference(java.lang.String viewId)
          Returns the view reference with the specified id.
 IViewReference findViewReference(java.lang.String viewId, java.lang.String secondaryId)
          Returns the view reference with the specified id and secondary id.
 IExtensionTracker getExtensionTracker()
           Return the extension tracker for the workbench.
 IAdaptable getInput()
          Returns the input for this page.
 java.lang.String getLabel()
          Returns the page label.
 java.lang.String[] getNewWizardShortcuts()
          Returns the new wizard shortcuts associated with the current perspective.
 IPerspectiveDescriptor[] getOpenPerspectives()
          Returns the descriptors for the perspectives that are open in this page, in the order in which they were opened.
 IPerspectiveDescriptor getPerspective()
          Returns the current perspective descriptor for this page, or null if there is no current perspective.
 java.lang.String[] getPerspectiveShortcuts()
          Returns the perspective shortcuts associated with the current perspective.
 java.lang.String[] getShowViewShortcuts()
          Returns the show view shortcuts associated with the current perspective.
 IPerspectiveDescriptor[] getSortedPerspectives()
          Returns the descriptors for the perspectives that are open in this page, in the order in which they were activated (oldest first).
 IViewReference[] getViewReferences()
          Returns a list of the reference to views visible on this page.
 IViewPart[] getViews()
          Deprecated. use #getViewReferences() instead.
 IViewPart[] getViewStack(IViewPart part)
          Returns an array of IViewParts that are stacked with the given part.
 IWorkbenchWindow getWorkbenchWindow()
          Returns the workbench org.eclipse.jface.window of this page.
 void hideActionSet(java.lang.String actionSetID)
          Hides an action set in this page.
 void hideView(IViewPart view)
          Hides the given view.
 void hideView(IViewReference view)
          Hides the given view that belongs to the reference, if any.
 boolean isEditorAreaVisible()
          Returns whether the page's current perspective is showing the editor area.
 boolean isPartVisible(IWorkbenchPart part)
          Returns whether the specified part is visible.
 void removePropertyChangeListener(IPropertyChangeListener listener)
          Deprecated. individual views should store a working set if needed and register a property change listener directly with the working set manager to receive notification when the view working set is removed.
 void resetPerspective()
          Changes the visible views, their layout, and the visible action sets within the page to match the current perspective descriptor.
 boolean saveAllEditors(boolean confirm)
          Saves the contents of all dirty editors belonging to this workbench page.
 void savePerspective()
          Saves the visible views, their layout, and the visible action sets for this page to the current perspective descriptor.
 void savePerspectiveAs(IPerspectiveDescriptor perspective)
          Saves the visible views, their layout, and the visible action sets for this page to the given perspective descriptor.
 void setEditorAreaVisible(boolean showEditorArea)
          Show or hide the editor area for the page's active perspective.
 void setPerspective(IPerspectiveDescriptor perspective)
          Changes the visible views, their layout, and the visible action sets within the page to match the given perspective descriptor.
 void showActionSet(java.lang.String actionSetID)
          Shows an action set in this page.
 IViewPart showView(java.lang.String viewId)
          Shows the view identified by the given view id in this page and gives it focus.
 IViewPart showView(java.lang.String viewId, java.lang.String secondaryId, int mode)
          Shows a view in this page with the given id and secondary id.
 
Methods inherited from interface org.eclipse.ui.IPartService
addPartListener, addPartListener, getActivePart, getActivePartReference, removePartListener, removePartListener
 
Methods inherited from interface org.eclipse.ui.ISelectionService
addPostSelectionListener, addPostSelectionListener, addSelectionListener, addSelectionListener, getSelection, getSelection, removePostSelectionListener, removePostSelectionListener, removeSelectionListener, removeSelectionListener
 

Field Detail

EDITOR_ID_ATTR

static final java.lang.String EDITOR_ID_ATTR
Deprecated. in 3.0 since the notion of markers this is not generally applicable. Use the IDE-specific constant IDE.EDITOR_ID_ATTR.
An optional attribute within a workspace marker (IMarker) which identifies the preferred editor type to be opened when openEditor is called.

See Also:
#openEditor(IEditorInput, String), #openEditor(IEditorInput, String, boolean), Constant Field Values

CHANGE_RESET

static final java.lang.String CHANGE_RESET
Change event id when the perspective is reset to its original state.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_RESET_COMPLETE

static final java.lang.String CHANGE_RESET_COMPLETE
Change event id when the perspective has completed a reset to its original state.

Since:
3.0
See Also:
IPerspectiveListener, Constant Field Values

CHANGE_VIEW_SHOW

static final java.lang.String CHANGE_VIEW_SHOW
Change event id when one or more views are shown in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_VIEW_HIDE

static final java.lang.String CHANGE_VIEW_HIDE
Change event id when one or more views are hidden in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_EDITOR_OPEN

static final java.lang.String CHANGE_EDITOR_OPEN
Change event id when one or more editors are opened in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_EDITOR_CLOSE

static final java.lang.String CHANGE_EDITOR_CLOSE
Change event id when one or more editors are closed in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_EDITOR_AREA_SHOW

static final java.lang.String CHANGE_EDITOR_AREA_SHOW
Change event id when the editor area is shown in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_EDITOR_AREA_HIDE

static final java.lang.String CHANGE_EDITOR_AREA_HIDE
Change event id when the editor area is hidden in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_ACTION_SET_SHOW

static final java.lang.String CHANGE_ACTION_SET_SHOW
Change event id when an action set is shown in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_ACTION_SET_HIDE

static final java.lang.String CHANGE_ACTION_SET_HIDE
Change event id when an action set is hidden in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_FAST_VIEW_ADD

static final java.lang.String CHANGE_FAST_VIEW_ADD
Change event id when a fast view is added in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_FAST_VIEW_REMOVE

static final java.lang.String CHANGE_FAST_VIEW_REMOVE
Change event id when a fast view is removed in a perspective.

See Also:
IPerspectiveListener, Constant Field Values

CHANGE_WORKING_SET_REPLACE

static final java.lang.String CHANGE_WORKING_SET_REPLACE
Change event id when the page working set was replaced

See Also:
IPropertyChangeListener, Constant Field Values

VIEW_ACTIVATE

static final int VIEW_ACTIVATE
Show view mode that indicates the view should be made visible and activated. Use of this mode has the same effect as calling showView(String).

Since:
3.0
See Also:
Constant Field Values

VIEW_VISIBLE

static final int VIEW_VISIBLE
Show view mode that indicates the view should be made visible. If the view is opened in the container that contains the active view then this has the same effect as VIEW_CREATE.

Since:
3.0
See Also:
Constant Field Values

VIEW_CREATE

static final int VIEW_CREATE
Show view mode that indicates the view should be made created but not necessarily be made visible. It will only be made visible in the event that it is opened in its own container. In other words, only if it is not stacked with another view.

Since:
3.0
See Also:
Constant Field Values
Method Detail

activate

void activate(IWorkbenchPart part)
Activates the given part. The part will be brought to the front and given focus. The part must belong to this page.

Parameters:
part - the part to activate

addPropertyChangeListener

void addPropertyChangeListener(IPropertyChangeListener listener)
Deprecated. individual views should store a working set if needed and register a property change listener directly with the working set manager to receive notification when the view working set is removed.

Adds a property change listener.

Parameters:
listener - the property change listener to add
Since:
2.0

bringToTop

void bringToTop(IWorkbenchPart part)
Moves the given part forward in the Z order of this page so as to make it visible, without changing which part has focus. The part must belong to this page.

Parameters:
part - the part to bring forward

close

boolean close()
Closes this workbench page. If this page is the active one, this honor is passed along to one of the org.eclipse.jface.window's other pages if possible.

If the page has an open editor with unsaved content, the user will be given the opportunity to save it.

Returns:
true if the page was successfully closed, and false if it is still open

findView

IViewPart findView(java.lang.String viewId)
Returns the view in this page with the specified id. There is at most one view in the page with the specified id.

Parameters:
viewId - the id of the view extension to use
Returns:
the view, or null if none is found

findViewReference

IViewReference findViewReference(java.lang.String viewId)
Returns the view reference with the specified id.

Parameters:
viewId - the id of the view extension to use
Returns:
the view reference, or null if none is found
Since:
3.0

findViewReference

IViewReference findViewReference(java.lang.String viewId,
                                 java.lang.String secondaryId)
Returns the view reference with the specified id and secondary id.

Parameters:
viewId - the id of the view extension to use
secondaryId - the secondary id to use, or null for no secondary id
Returns:
the view reference, or null if none is found
Since:
3.0

getInput

IAdaptable getInput()
Returns the input for this page.

Returns:
the input for this page, or null if none

getLabel

java.lang.String getLabel()
Returns the page label. This will be a unique identifier within the containing workbench org.eclipse.jface.window.

Returns:
the page label

getPerspective

IPerspectiveDescriptor getPerspective()
Returns the current perspective descriptor for this page, or null if there is no current perspective.

Returns:
the current perspective descriptor or null
See Also:
setPerspective(org.eclipse.ui.IPerspectiveDescriptor), savePerspective()

getViewReferences

IViewReference[] getViewReferences()
Returns a list of the reference to views visible on this page.

Note that each page has its own views; views are never shared between pages.

Returns:
a list of references to visible views

getViews

IViewPart[] getViews()
Deprecated. use #getViewReferences() instead.

Returns a list of the views visible on this page.

Note that each page has its own views; views are never shared between pages.

Returns:
a list of visible views

getWorkbenchWindow

IWorkbenchWindow getWorkbenchWindow()
Returns the workbench org.eclipse.jface.window of this page.

Returns:
the workbench org.eclipse.jface.window

hideActionSet

void hideActionSet(java.lang.String actionSetID)
Hides an action set in this page.

In most cases where this method is used the caller is tightly coupled to a particular action set. They define it in the registry and may make it visible in certain scenarios by calling showActionSet. A static variable is often used to identify the action set id in caller code.

Parameters:
actionSetID - the action set to hide

hideView

void hideView(IViewPart view)
Hides the given view. The view must belong to this page.

Parameters:
view - the view to hide

hideView

void hideView(IViewReference view)
Hides the given view that belongs to the reference, if any.

Parameters:
view - the references whos view is to be hidden
Since:
3.0

isPartVisible

boolean isPartVisible(IWorkbenchPart part)
Returns whether the specified part is visible.

Parameters:
part - the part to test
Returns:
boolean true if part is visible

isEditorAreaVisible

boolean isEditorAreaVisible()
Returns whether the page's current perspective is showing the editor area.

Returns:
true when editor area visible, false otherwise

removePropertyChangeListener

void removePropertyChangeListener(IPropertyChangeListener listener)
Deprecated. individual views should store a working set if needed and register a property change listener directly with the working set manager to receive notification when the view working set is removed.

Removes the property change listener.

Parameters:
listener - the property change listener to remove
Since:
2.0

resetPerspective

void resetPerspective()
Changes the visible views, their layout, and the visible action sets within the page to match the current perspective descriptor. This is a rearrangement of components and not a replacement. The contents of the current perspective descriptor are unaffected.

For more information on perspective change see setPerspective().


saveAllEditors

boolean saveAllEditors(boolean confirm)
Saves the contents of all dirty editors belonging to this workbench page. If there are no dirty editors this method returns without effect.

If confirm is true the user is prompted to confirm the command.

Parameters:
confirm - true to ask the user before saving unsaved changes (recommended), and false to save unsaved changes without asking
Returns:
true if the command succeeded, and false if at least one editor with unsaved changes was not saved

savePerspective

void savePerspective()
Saves the visible views, their layout, and the visible action sets for this page to the current perspective descriptor. The contents of the current perspective descriptor are overwritten.


savePerspectiveAs

void savePerspectiveAs(IPerspectiveDescriptor perspective)
Saves the visible views, their layout, and the visible action sets for this page to the given perspective descriptor. The contents of the given perspective descriptor are overwritten and it is made the current one for this page.

Parameters:
perspective - the perspective descriptor to save to

setEditorAreaVisible

void setEditorAreaVisible(boolean showEditorArea)
Show or hide the editor area for the page's active perspective.

Parameters:
showEditorArea - true to show the editor area, false to hide the editor area

setPerspective

void setPerspective(IPerspectiveDescriptor perspective)
Changes the visible views, their layout, and the visible action sets within the page to match the given perspective descriptor. This is a rearrangement of components and not a replacement. The contents of the old perspective descriptor are unaffected.

When a perspective change occurs the old perspective is deactivated (hidden) and cached for future reference. Then the new perspective is activated (shown). The views within the page are shared by all existing perspectives to make it easy for the user to switch between one perspective and another quickly without loss of context.

During activation the action sets are modified. If an action set is specified in the new perspective which is not visible in the old one it will be created. If an old action set is not specified in the new perspective it will be disposed.

The visible views and their layout within the page also change. If a view is specified in the new perspective which is not visible in the old one a new instance of the view will be created. If an old view is not specified in the new perspective it will be hidden. This view may reappear if the user selects it from the View menu or if they switch to a perspective (which may be the old one) where the view is visible.

The open editors are not modified by this method.

Parameters:
perspective - the perspective descriptor

showActionSet

void showActionSet(java.lang.String actionSetID)
Shows an action set in this page.

In most cases where this method is used the caller is tightly coupled to a particular action set. They define it in the registry and may make it visible in certain scenarios by calling showActionSet. A static variable is often used to identify the action set id in caller code.

Parameters:
actionSetID - the action set to show

showView

IViewPart showView(java.lang.String viewId)
                   throws PartInitException
Shows the view identified by the given view id in this page and gives it focus. If there is a view identified by the given view id (and with no secondary id) already open in this page, it is given focus.

Parameters:
viewId - the id of the view extension to use
Returns:
the shown view
Throws:
PartInitException - if the view could not be initialized

showView

IViewPart showView(java.lang.String viewId,
                   java.lang.String secondaryId,
                   int mode)
                   throws PartInitException
Shows a view in this page with the given id and secondary id. The behaviour of this method varies based on the supplied mode. If VIEW_ACTIVATE is supplied, the view is focus. If VIEW_VISIBLE is supplied, then it is made visible but not given focus. Finally, if VIEW_CREATE is supplied the view is created and will only be made visible if it is not created in a folder that already contains visible views.

This allows multiple instances of a particular view to be created. They are disambiguated using the secondary id. If a secondary id is given, the view must allow multiple instances by having specified allowMultiple="true" in its extension.

Parameters:
viewId - the id of the view extension to use
secondaryId - the secondary id to use, or null for no secondary id
mode - the activation mode. Must be VIEW_ACTIVATE, VIEW_VISIBLE or VIEW_CREATE
Returns:
a view
Throws:
PartInitException - if the view could not be initialized
java.lang.IllegalArgumentException - if the supplied mode is not valid
Since:
3.0

getViewStack

IViewPart[] getViewStack(IViewPart part)
Returns an array of IViewParts that are stacked with the given part. EXPERIMENTAL

Parameters:
part - the part to test
Returns:
the parts that are stacked with this part, including the part in question. null is returned if the part does not belong to this page.
Since:
3.0

getNewWizardShortcuts

java.lang.String[] getNewWizardShortcuts()
Returns the new wizard shortcuts associated with the current perspective. Returns an empty array if there is no current perspective.

Returns:
an array of wizard identifiers
Since:
3.1
See Also:
IPageLayout.addNewWizardShortcut(String)

getPerspectiveShortcuts

java.lang.String[] getPerspectiveShortcuts()
Returns the perspective shortcuts associated with the current perspective. Returns an empty array if there is no current perspective.

Returns:
an array of perspective identifiers
Since:
3.1
See Also:
IPageLayout.addPerspectiveShortcut(String)

getShowViewShortcuts

java.lang.String[] getShowViewShortcuts()
Returns the show view shortcuts associated with the current perspective. Returns an empty array if there is no current perspective.

Returns:
an array of view identifiers
Since:
3.1
See Also:
IPageLayout.addShowViewShortcut(String)

getOpenPerspectives

IPerspectiveDescriptor[] getOpenPerspectives()
Returns the descriptors for the perspectives that are open in this page, in the order in which they were opened.

Returns:
the open perspective descriptors, in order of opening
Since:
3.1

getSortedPerspectives

IPerspectiveDescriptor[] getSortedPerspectives()
Returns the descriptors for the perspectives that are open in this page, in the order in which they were activated (oldest first).

Returns:
the open perspective descriptors, in order of activation
Since:
3.1

closePerspective

void closePerspective(IPerspectiveDescriptor desc,
                      boolean saveEditors,
                      boolean closePage)
Closes the specified perspective in this page. If the last perspective in this page is closed, then all editors are closed, prompting to save any unsaved changes if saveEditors is true, and the page itself is closed if closePage is true.

Parameters:
desc - the descriptor of the perspective to be closed
saveEditors - whether the page's editors should be saved if last perspective
closePage - whether the page itself should be closed if last perspective
Since:
3.1

closeAllPerspectives

void closeAllPerspectives(boolean saveEditors,
                          boolean closePage)
Closes all perspectives in this page. All editors are closed, prompting to save any unsaved changes if saveEditors is true. The page itself is closed if closePage is true.

Parameters:
saveEditors - whether the page's editors should be saved
closePage - whether the page itself should be closed
Since:
3.1

getExtensionTracker

IExtensionTracker getExtensionTracker()

Return the extension tracker for the workbench. This tracker may be used by plug-ins to ensure responsiveness to changes to the plug-in registry.

The tracker at this level of the workbench is typically used to track elements that only exist over the lifespan of a page. For example, ViewPart objects fall into this category.

This method is EXPERIMENTAL and may change prior to the 3.1 release.

Returns:
the extension tracker
Since:
3.1
See Also:
IWorkbench.getExtensionTracker(), IWorkbenchWindow.getExtensionTracker()