org.eclipse.ui
Interface IWorkbenchPage

All Superinterfaces:

IPartService, ISelectionService

public interface IWorkbenchPage

extends IPartService, ISelectionService

A workbench page consists of an arrangement of views and editors intended to be presented together to the user in a single workbench 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:

• Only one instance of a particular view type may exist within a workbench page.
• Only one editor can exist for each editor input within a page.

This interface is not intended to be implemented by clients.

See Also:

IPerspectiveDescriptor, IEditorPart, IViewPart

Field Summary

static String	CHANGE_ACTION_SET_HIDE Change event id when the perspective action set is hidden.
static String	CHANGE_ACTION_SET_SHOW Change event id when a perspective action set is shown.
static String	CHANGE_EDITOR_AREA_HIDE Change event id when the perspective editor area is hidden.
static String	CHANGE_EDITOR_AREA_SHOW Change event id when the perspective editor area is shown.
static String	CHANGE_EDITOR_CLOSE Change event id when one or more perspective editors are closed.
static String	CHANGE_EDITOR_OPEN Change event id when one or more perspective editors are opened.
static String	CHANGE_FAST_VIEW_ADD Change event id when a perspective fast view added.
static String	CHANGE_FAST_VIEW_REMOVE Change event id when the perspective fast view removed.
static String	CHANGE_RESET Change event id when the perspective is reset to its original state.
static String	CHANGE_VIEW_HIDE Change event id when one or more perspective views are hidden.
static String	CHANGE_VIEW_SHOW Change event id when one or more perspective views are shown.
static String	CHANGE_WORKING_SET_REPLACE Change event id when the page working set was replaced
static String	EDITOR_ID_ATTR An optional attribute within a workspace marker (IMarker) which identifies the preferred editor type to be opened when openEditor is called.

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.
boolean	closeAllEditors(boolean save) Closes all of the editors belonging to this workbench page.
boolean	closeEditor(IEditorPart editor, boolean save) Closes the given editor.
IEditorPart	findEditor(IEditorInput input) Returns the editor with the specified input.
IViewPart	findView(String viewId) Returns the view in this page with the specified id.
IEditorPart	getActiveEditor() Returns the active editor open in this page.
IEditorPart[]	getDirtyEditors() Returns a list of dirty editors in this page.
IEditorReference[]	getEditorReferences() Returns a array of references to open editors in this page.
int	getEditorReuseThreshold() Deprecated.
IEditorPart[]	getEditors() Deprecated. use getEditorReferences() instead
IAdaptable	getInput() Returns the input for this page.
String	getLabel() Returns the page label.
IPerspectiveDescriptor	getPerspective() Returns the current perspective descriptor for this page.
IViewReference[]	getViewReferences() Returns a list of the reference to views visible on this page.
IViewPart[]	getViews() Deprecated. use getViewReferences() instead.
IWorkbenchWindow	getWorkbenchWindow() Returns the workbench window of this page.
IWorkingSet	getWorkingSet() Deprecated. individual views should store a working set if needed
void	hideActionSet(String actionSetID) Hides an action set in this page.
void	hideView(IViewPart view) Hides the given view.
boolean	isEditorAreaVisible() Returns whether the page's current perspective is showing the editor area.
boolean	isEditorPinned(IEditorPart editor) Returns true if the editor is pinned and should not be reused.
IEditorPart	openEditor(IEditorInput input, String editorId) Opens an editor on the given object.
IEditorPart	openEditor(IEditorInput input, String editorId, boolean activate) Opens an editor on the given object.
IEditorPart	openEditor(IFile input) Opens an editor on the given file resource.
IEditorPart	openEditor(IFile input, String editorID) Opens an editor on the given file resource.
IEditorPart	openEditor(IFile input, String editorID, boolean activate) Opens an editor on the given file resource.
IEditorPart	openEditor(IMarker marker) Opens an editor on the file resource of the given marker.
IEditorPart	openEditor(IMarker marker, boolean activate) Opens an editor on the file resource of the given marker.
void	openSystemEditor(IFile input) Opens an operating system editor on a given file.
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.
boolean	saveEditor(IEditorPart editor, boolean confirm) Saves the contents of the given editor if dirty.
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	setEditorReuseThreshold(int openEditors) Deprecated. use IPageLayout.setEditorReuseThreshold(int openEditors) instead.
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(String actionSetID) Shows an action set in this page.
IViewPart	showView(String viewId) Shows a view in this page and give it focus.

Methods inherited from interface org.eclipse.ui.IPartService

addPartListener, getActivePart, removePartListener

Methods inherited from interface org.eclipse.ui.ISelectionService

addPostSelectionListener, addPostSelectionListener, addSelectionListener, addSelectionListener, getSelection, getSelection, removePostSelectionListener, removePostSelectionListener, removeSelectionListener, removeSelectionListener

Field Detail

EDITOR_ID_ATTR

public static final String 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(org.eclipse.core.resources.IFile), Constant Field Values

CHANGE_RESET

public static final String CHANGE_RESET

Change event id when the perspective is reset to its original state.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_VIEW_SHOW

public static final String CHANGE_VIEW_SHOW

Change event id when one or more perspective views are shown.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_VIEW_HIDE

public static final String CHANGE_VIEW_HIDE

Change event id when one or more perspective views are hidden.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_EDITOR_OPEN

public static final String CHANGE_EDITOR_OPEN

Change event id when one or more perspective editors are opened.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_EDITOR_CLOSE

public static final String CHANGE_EDITOR_CLOSE

Change event id when one or more perspective editors are closed.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_EDITOR_AREA_SHOW

public static final String CHANGE_EDITOR_AREA_SHOW

Change event id when the perspective editor area is shown.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_EDITOR_AREA_HIDE

public static final String CHANGE_EDITOR_AREA_HIDE

Change event id when the perspective editor area is hidden.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_ACTION_SET_SHOW

public static final String CHANGE_ACTION_SET_SHOW

Change event id when a perspective action set is shown.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_ACTION_SET_HIDE

public static final String CHANGE_ACTION_SET_HIDE

Change event id when the perspective action set is hidden.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_FAST_VIEW_ADD

public static final String CHANGE_FAST_VIEW_ADD

Change event id when a perspective fast view added.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_FAST_VIEW_REMOVE

public static final String CHANGE_FAST_VIEW_REMOVE

Change event id when the perspective fast view removed.

See Also:

IPerspectiveListener, Constant Field Values

CHANGE_WORKING_SET_REPLACE

public static final String CHANGE_WORKING_SET_REPLACE

Change event id when the page working set was replaced

See Also:

IPropertyChangeListener, Constant Field Values

Method Detail

activate

public 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

public 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

public 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

public boolean close()

Closes this workbench page. If this page is the active one, this honor is passed along to one of the 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

closeAllEditors

public boolean closeAllEditors(boolean save)

Closes all of the editors belonging to this workbench page.

If the page has open editors with unsaved content and save is true, the user will be given the opportunity to save them.

Returns:

true if all editors were successfully closed, and false if at least one is still open

closeEditor

public boolean closeEditor(IEditorPart editor,
                           boolean save)

Closes the given editor. The editor must belong to this workbench page.

If the editor has unsaved content and save is true, the user will be given the opportunity to save it.

Parameters:

editor - the editor to close

save - true to save the editor contents if required (recommended), and false to discard any unsaved changes

Returns:

true if the editor was successfully closed, and false if the editor is still open

findView

public IViewPart findView(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

getActiveEditor

public IEditorPart getActiveEditor()

Returns the active editor open in this page.

This is the visible editor on the page, or, if there is more than one visible editor, this is the one most recently brought to top.

Returns:

the active editor, or null if no editor is active

findEditor

public IEditorPart findEditor(IEditorInput input)

Returns the editor with the specified input. Returns null if there is no opened editor with that input.

Returns:

an editor with input equals to input

getEditors

public IEditorPart[] getEditors()

Deprecated. use getEditorReferences() instead

Returns a list of the editors open in this page.

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

Returns:

a list of open editors

getEditorReferences

public IEditorReference[] getEditorReferences()

Returns a array of references to open editors in this page.

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

Returns:

a list of open editors

getDirtyEditors

public IEditorPart[] getDirtyEditors()

Returns a list of dirty editors in this page.

Returns:

a list of dirty editors

getInput

public IAdaptable getInput()

Returns the input for this page.

Returns:

the input for this page, or null if none

getLabel

public String getLabel()

Returns the page label. This will be a unique identifier within the containing workbench window.

Returns:

the page label

getPerspective

public IPerspectiveDescriptor getPerspective()

Returns the current perspective descriptor for this page.

Returns:

the current perspective descriptor

See Also:

setPerspective(org.eclipse.ui.IPerspectiveDescriptor), savePerspective()

getViewReferences

public 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

public 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

public IWorkbenchWindow getWorkbenchWindow()

Returns the workbench window of this page.

Returns:

the workbench window

getWorkingSet

public IWorkingSet getWorkingSet()

Deprecated. individual views should store a working set if needed

Returns the working set of this page.

Returns:

the working set of this page.

Since:

2.0

hideActionSet

public void hideActionSet(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.

hideView

public void hideView(IViewPart view)

Hides the given view. The view must belong to this page.

Parameters:

view - the view to hide

isEditorAreaVisible

public boolean isEditorAreaVisible()

Returns whether the page's current perspective is showing the editor area.

Returns:

true when editor area visible, false otherwise

openEditor

public IEditorPart openEditor(IFile input)
                       throws PartInitException

Opens an editor on the given file resource.

If this page already has an editor open on the target object that editor is activated; otherwise, a new editor is opened.

An appropriate editor for the input is determined using a multistep process.

1. The workbench editor registry is consulted to determine if an editor extension has been registered for the file type. If so, an instance of the editor extension is opened on the file. See IEditorRegistry.getDefaultEditor(IFile).
2. Next, the native operating system will be consulted to determine if a native editor exists for the file type. If so, a new process is started and the native editor is opened on the file.
3. If all else fails the file will be opened in a default text editor.

Parameters:

input - the file to edit

Returns:

an open and active editor, or null if a system editor was opened

Throws:

PartInitException - if the editor could not be initialized

openEditor

public IEditorPart openEditor(IFile input,
                              String editorID,
                              boolean activate)
                       throws PartInitException

Opens an editor on the given file resource.

If this page already has an editor open on the target object that editor is brought to front; otherwise, a new editor is opened. If activate == true the editor will be activated.

The editor type is determined by mapping editorId to an editor extension registered with the workbench. An editor id is passed rather than an editor object to prevent the accidental creation of more than one editor for the same input. It also guarantees a consistent lifecycle for editors, regardless of whether they are created by the user or restored from saved data.

Parameters:

input - the file to edit

activate - if true the editor will be activated

Returns:

an open and active editor

Throws:

PartInitException - if the editor could not be initialized

openEditor

public IEditorPart openEditor(IFile input,
                              String editorID)
                       throws PartInitException

Opens an editor on the given file resource.

If this page already has an editor open on the target object that editor is activated; otherwise, a new editor is opened.

The editor type is determined by mapping editorId to an editor extension registered with the workbench. An editor id is passed rather than an editor object to prevent the accidental creation of more than one editor for the same input. It also guarantees a consistent lifecycle for editors, regardless of whether they are created by the user or restored from saved data.

Parameters:

input - the file to edit

Returns:

an open and active editor

Throws:

PartInitException - if the editor could not be initialized

openEditor

public IEditorPart openEditor(IMarker marker)
                       throws PartInitException

Opens an editor on the file resource of the given marker.

If this page already has an editor open on the target object that editor is activated; otherwise, a new editor is opened. The cursor and selection state of the editor is then updated from information recorded in the marker.

If the marker contains an EDITOR_ID_ATTR attribute the attribute value will be used to determine the editor type to be opened. If not, the registered editor for the marker resource will be used.

Parameters:

marker - the marker to open

Returns:

an open and active editor, or null if a system editor was opened

Throws:

PartInitException - if the editor could not be initialized

See Also:

IEditorPart.gotoMarker(org.eclipse.core.resources.IMarker)

openEditor

public IEditorPart openEditor(IMarker marker,
                              boolean activate)
                       throws PartInitException

Opens an editor on the file resource of the given marker.

If this page already has an editor open on the target object that editor is brought to front; otherwise, a new editor is opened. If activate == true the editor will be activated. The cursor and selection state of the editor are then updated from information recorded in the marker.

If the marker contains an EDITOR_ID_ATTR attribute the attribute value will be used to determine the editor type to be opened. If not, the registered editor for the marker resource will be used.

Parameters:

marker - the marker to open

activate - if true the editor will be activated

Returns:

an open editor, or null if a system editor was opened

Throws:

PartInitException - if the editor could not be initialized

See Also:

IEditorPart.gotoMarker(org.eclipse.core.resources.IMarker)

openEditor

public IEditorPart openEditor(IEditorInput input,
                              String editorId)
                       throws PartInitException

Opens an editor on the given object.

If this page already has an editor open on the target object that editor is activated; otherwise, a new editor is opened.

The editor type is determined by mapping editorId to an editor extension registered with the workbench. An editor id is passed rather than an editor object to prevent the accidental creation of more than one editor for the same input. It also guarantees a consistent lifecycle for editors, regardless of whether they are created by the user or restored from saved data.

Parameters:

input - the editor input

editorId - the id of the editor extension to use

Returns:

an open and active editor

Throws:

PartInitException - if the editor could not be initialized

openEditor

public IEditorPart openEditor(IEditorInput input,
                              String editorId,
                              boolean activate)
                       throws PartInitException

Opens an editor on the given object.

If this page already has an editor open on the target object that editor is brought to the front; otherwise, a new editor is opened. If activate == true the editor will be activated.

The editor type is determined by mapping editorId to an editor extension registered with the workbench. An editor id is passed rather than an editor object to prevent the accidental creation of more than one editor for the same input. It also guarantees a consistent lifecycle for editors, regardless of whether they are created by the user or restored from saved data.

Parameters:

input - the editor input

editorId - the id of the editor extension to use

activate - if true the editor will be activated

Returns:

an open editor

Throws:

PartInitException - if the editor could not be initialized

openSystemEditor

public void openSystemEditor(IFile input)
                      throws PartInitException

Opens an operating system editor on a given file. Once open, the workbench has no knowledge of the editor or the state of the file being edited. Users are expected to perform a "Local Refresh" from the workbench user interface.

Parameters:

input - the file to edit

Throws:

PartInitException - if the editor could not be opened.

removePropertyChangeListener

public 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

public 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 seesetPerspective().

saveAllEditors

public 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

saveEditor

public boolean saveEditor(IEditorPart editor,
                          boolean confirm)

Saves the contents of the given editor if dirty. If not, this method returns without effect.

If confirm is true the user is prompted to confirm the command. Otherwise, the save happens without prompt.

The editor must belong to this workbench page.

Parameters:

editor - the editor to close

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 the editor was not saved

savePerspective

public 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

public 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

public 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

public 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

public void showActionSet(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.

showView

public IViewPart showView(String viewId)
                   throws PartInitException

Shows a view in this page and give it focus. If the view is already visible, it is given focus.

The view type is determined by mapping viewId to a view extension registered with the workbench. A view id is passed rather than a view object to prevent the accidental creation of more than one view of a particular type. It also guarantees a consistent lifecycle for views, regardless of whether they are created by the user or restored from saved data.

Parameters:

viewId - the id of the view extension to use

Returns:

a view

Throws:

PartInitException - if the view could not be initialized

isEditorPinned

public boolean isEditorPinned(IEditorPart editor)

Returns true if the editor is pinned and should not be reused.

Returns:

boolean

getEditorReuseThreshold

public int getEditorReuseThreshold()

Deprecated.

Returns the number of open editors before reusing editors.

Returns:

a int Note: For EXPERIMENTAL use only. IT MAY CHANGE IN NEAR FUTURE.

setEditorReuseThreshold

public void setEditorReuseThreshold(int openEditors)

Deprecated. use IPageLayout.setEditorReuseThreshold(int openEditors) instead.

Set the number of open editors before reusing editors. If < 0 the user preference settings will be used. Note: For EXPERIMENTAL use only. IT MAY CHANGE IN NEAR FUTURE.