|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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:
This interface is not intended to be implemented by clients.
IPerspectiveDescriptor
,
IEditorPart
,
IViewPart
Field Summary | |
---|---|
static String |
CHANGE_ACTION_SET_HIDE
Change event id when an action set is hidden in a perspective. |
static String |
CHANGE_ACTION_SET_SHOW
Change event id when an action set is shown in a perspective. |
static String |
CHANGE_EDITOR_AREA_HIDE
Change event id when the editor area is hidden in a perspective. |
static String |
CHANGE_EDITOR_AREA_SHOW
Change event id when the editor area is shown in a perspective. |
static String |
CHANGE_EDITOR_CLOSE
Change event id when one or more editors are closed in a perspective. |
static String |
CHANGE_EDITOR_OPEN
Change event id when one or more editors are opened in a perspective. |
static String |
CHANGE_FAST_VIEW_ADD
Change event id when a fast view is added in a perspective. |
static String |
CHANGE_FAST_VIEW_REMOVE
Change event id when a fast view is removed in a perspective. |
static String |
CHANGE_RESET
Change event id when the perspective is reset to its original state. |
static String |
CHANGE_RESET_COMPLETE
Change event id when the perspective has completed a reset to its original state. |
static String |
CHANGE_VIEW_HIDE
Change event id when one or more views are hidden in a perspective. |
static String |
CHANGE_VIEW_SHOW
Change event id when one or more views are shown in a perspective. |
static String |
CHANGE_WORKING_SET_REPLACE
Change event id when the page working set was replaced |
static 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. |
boolean |
closeAllEditors(boolean save)
Closes all of the editors belonging to this workbench page. |
void |
closeAllPerspectives(boolean saveEditors,
boolean closePage)
Closes all perspectives in this page. |
boolean |
closeEditor(IEditorPart editor,
boolean save)
Closes the given editor. |
boolean |
closeEditors(IEditorReference[] editorRefs,
boolean save)
Closes the given Array of editor references. |
void |
closePerspective(IPerspectiveDescriptor desc,
boolean saveEditors,
boolean closePage)
Closes the specified perspective in this page. |
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. |
IViewReference |
findViewReference(String viewId)
Returns the view reference with the specified id. |
IViewReference |
findViewReference(String viewId,
String secondaryId)
Returns the view reference with the specified id and secondary 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 |
IExtensionTracker |
getExtensionTracker()
Return the extension tracker for the workbench. |
IAdaptable |
getInput()
Returns the input for this page. |
String |
getLabel()
Returns the page label. |
INavigationHistory |
getNavigationHistory()
Returns the navigation history which manages a list of entries keeping the history of places (positions, selection and editors) the user visited making it easier to the user to move back and forward without losing context. |
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. |
String[] |
getPerspectiveShortcuts()
Returns the perspective shortcuts associated with the current perspective. |
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 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. |
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 |
isEditorPinned(IEditorPart editor)
Returns true if the editor is pinned and should not be
reused. |
boolean |
isPartVisible(IWorkbenchPart part)
Returns whether the specified part is visible. |
IEditorPart |
openEditor(IEditorInput input,
String editorId)
Opens an editor on the given input. |
IEditorPart |
openEditor(IEditorInput input,
String editorId,
boolean activate)
Opens an editor on the given input. |
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. |
void |
reuseEditor(IReusableEditor editor,
IEditorInput input)
Reuses the specified editor by setting its new input. |
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 the view identified by the given view id in this page and gives it focus. |
IViewPart |
showView(String viewId,
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 |
public static final String EDITOR_ID_ATTR
IDE.EDITOR_ID_ATTR
.
IMarker
)
which identifies the preferred editor type to be opened when openEditor
is called.
openEditor(IEditorInput, String)
,
openEditor(IEditorInput, String, boolean)
,
Constant Field Valuespublic static final String CHANGE_RESET
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_RESET_COMPLETE
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_VIEW_SHOW
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_VIEW_HIDE
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_EDITOR_OPEN
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_EDITOR_CLOSE
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_EDITOR_AREA_SHOW
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_EDITOR_AREA_HIDE
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_ACTION_SET_SHOW
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_ACTION_SET_HIDE
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_FAST_VIEW_ADD
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_FAST_VIEW_REMOVE
IPerspectiveListener
,
Constant Field Valuespublic static final String CHANGE_WORKING_SET_REPLACE
IPropertyChangeListener
,
Constant Field Valuespublic static final int VIEW_ACTIVATE
showView(String)
.
public static final int VIEW_VISIBLE
VIEW_CREATE
.
public static final int VIEW_CREATE
Method Detail |
public void activate(IWorkbenchPart part)
part
- the part to activatepublic void addPropertyChangeListener(IPropertyChangeListener listener)
listener
- the property change listener to addpublic void bringToTop(IWorkbenchPart part)
part
- the part to bring forwardpublic boolean close()
If the page has an open editor with unsaved content, the user will be given the opportunity to save it.
true
if the page was successfully closed, and
false
if it is still openpublic boolean closeAllEditors(boolean save)
If the page has open editors with unsaved content and save
is true
, the user will be given the opportunity to save
them.
save
-
true
if all editors were successfully closed, and
false
if at least one is still openpublic boolean closeEditors(IEditorReference[] editorRefs, boolean save)
Array
of editor references. The editors must
belong to this workbench page.
If any of the editors have unsaved content and save
is true
,
the user will be given the opportunity to save them.
editorRefs
- the editors to closesave
- true
to save the editor contents if required
(recommended), and false
to discard any
unsaved changes
true
if the editors were successfully closed, and
false
if the editors are still openpublic boolean closeEditor(IEditorPart editor, boolean save)
If the editor has unsaved content and save
is true
,
the user will be given the opportunity to save it.
editor
- the editor to closesave
- true
to save the editor contents if required
(recommended), and false
to discard any
unsaved changes
true
if the editor was successfully closed, and
false
if the editor is still openpublic IViewPart findView(String viewId)
viewId
- the id of the view extension to use
null
if none is foundpublic IViewReference findViewReference(String viewId)
viewId
- the id of the view extension to use
null
if none is foundpublic IViewReference findViewReference(String viewId, String secondaryId)
viewId
- the id of the view extension to usesecondaryId
- the secondary id to use, or null
for no secondary id
null
if none is foundpublic IEditorPart getActiveEditor()
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.
null
if no editor is activepublic IEditorPart findEditor(IEditorInput input)
input
- the editor input
input
public IEditorPart[] getEditors()
Note that each page has its own editors; editors are never shared between pages.
public IEditorReference[] getEditorReferences()
Note that each page has its own editors; editors are never shared between pages.
public IEditorPart[] getDirtyEditors()
public IAdaptable getInput()
null
if nonepublic String getLabel()
public IPerspectiveDescriptor getPerspective()
null
if there is no current perspective.
null
setPerspective(org.eclipse.ui.IPerspectiveDescriptor)
,
savePerspective()
public IViewReference[] getViewReferences()
Note that each page has its own views; views are never shared between pages.
public IViewPart[] getViews()
Note that each page has its own views; views are never shared between pages.
public IWorkbenchWindow getWorkbenchWindow()
public IWorkingSet getWorkingSet()
public void hideActionSet(String actionSetID)
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.
actionSetID
- the action set to hidepublic void hideView(IViewPart view)
view
- the view to hidepublic void hideView(IViewReference view)
view
- the references whos view is to be hiddenpublic boolean isPartVisible(IWorkbenchPart part)
part
- the part to test
true
if part is visiblepublic boolean isEditorAreaVisible()
true
when editor area visible, false
otherwisepublic void reuseEditor(IReusableEditor editor, IEditorInput input)
editor
- the editor to be reusedinput
- the new input for the reusable editorpublic IEditorPart openEditor(IEditorInput input, String editorId) throws PartInitException
If this page already has an editor open on the target input that editor is activated; otherwise, a new editor is opened. Two editor inputs, input1 and input2, are considered the same if
input1.equals(input2) == true.
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.
input
- the editor inputeditorId
- the id of the editor extension to use
null
if an external
editor was opened
PartInitException
- if the editor could not be created or initializedpublic IEditorPart openEditor(IEditorInput input, String editorId, boolean activate) throws PartInitException
If this page already has an editor open on the target input that editor
is brought to the front; otherwise, a new editor is opened. Two editor
inputs are considered the same if they equal. See Object.equals(Object)
and
IEditorInput
. 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.
input
- the editor inputeditorId
- the id of the editor extension to useactivate
- if true
the editor will be activated
null
if an external editor was opened
PartInitException
- if the editor could not be created or initializedpublic void removePropertyChangeListener(IPropertyChangeListener listener)
listener
- the property change listener to removepublic void resetPerspective()
For more information on perspective change see setPerspective()
.
public boolean saveAllEditors(boolean confirm)
If confirm
is true
the user is prompted to
confirm the command.
confirm
- true
to ask the user before saving unsaved
changes (recommended), and false
to save
unsaved changes without asking
true
if the command succeeded, and false
if at least one editor with unsaved changes was not savedpublic boolean saveEditor(IEditorPart editor, boolean confirm)
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.
editor
- the editor to closeconfirm
- true
to ask the user before saving unsaved
changes (recommended), and false
to save
unsaved changes without asking
true
if the command succeeded, and false
if the editor was not savedpublic void savePerspective()
public void savePerspectiveAs(IPerspectiveDescriptor perspective)
perspective
- the perspective descriptor to save topublic void setEditorAreaVisible(boolean showEditorArea)
showEditorArea
- true
to show the editor area, false
to hide the editor areapublic void setPerspective(IPerspectiveDescriptor perspective)
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.
perspective
- the perspective descriptorpublic void showActionSet(String actionSetID)
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.
actionSetID
- the action set to showpublic IViewPart showView(String viewId) throws PartInitException
viewId
- the id of the view extension to use
PartInitException
- if the view could not be initializedpublic IViewPart showView(String viewId, String secondaryId, int mode) throws PartInitException
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.
viewId
- the id of the view extension to usesecondaryId
- the secondary id to use, or null
for no secondary idmode
- the activation mode. Must be VIEW_ACTIVATE
,
VIEW_VISIBLE
or VIEW_CREATE
PartInitException
- if the view could not be initialized
IllegalArgumentException
- if the supplied mode is not validpublic boolean isEditorPinned(IEditorPart editor)
true
if the editor is pinned and should not be
reused.
editor
- the editor to test
public int getEditorReuseThreshold()
public void setEditorReuseThreshold(int openEditors)
openEditors
- the thresholdpublic INavigationHistory getNavigationHistory()
public IViewPart[] getViewStack(IViewPart part)
part
- the part to test
null
is returned if the part does not belong to this page.public String[] getNewWizardShortcuts()
IPageLayout.addNewWizardShortcut(String)
public String[] getPerspectiveShortcuts()
IPageLayout.addPerspectiveShortcut(String)
public String[] getShowViewShortcuts()
IPageLayout.addShowViewShortcut(String)
public IPerspectiveDescriptor[] getOpenPerspectives()
public IPerspectiveDescriptor[] getSortedPerspectives()
public void closePerspective(IPerspectiveDescriptor desc, boolean saveEditors, boolean closePage)
saveEditors
is true
,
and the page itself is closed if closePage
is true
.
desc
- the descriptor of the perspective to be closedsaveEditors
- whether the page's editors should be saved if last perspectiveclosePage
- whether the page itself should be closed if last perspectivepublic void closeAllPerspectives(boolean saveEditors, boolean closePage)
saveEditors
is true
.
The page itself is closed if closePage
is true
.
saveEditors
- whether the page's editors should be savedclosePage
- whether the page itself should be closedpublic 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.
IWorkbench.getExtensionTracker()
,
IWorkbenchWindow.getExtensionTracker()
|
Eclipse Platform Release 3.1 |
|||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Guidelines for using Eclipse APIs.
Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.