Interface IPageLayout
This interface is not intended to be implemented by clients.
When a perspective is opened, it creates a new page layout with a single
editor area. This layout is then passed to the perspective factory
(implementation of
IPerspectiveFactory.createInitialLayout(IPageLayout)
)
where additional views and other content can be added, using the existing
editor area as the initial point of reference.
In some cases, multiple instances of a particular view may need to be added
to the same layout. These are disambiguated using a secondary id. In layout
methods taking a view id, the id can have the compound form:
primaryId [':' secondaryId]. If a secondary id is given, the
view must allow multiple instances by having specified
allowMultiple="true"
in its extension. View placeholders may
also have a secondary id.
Wildcards are permitted in placeholder ids (but not regular view ids). '*' matches any substring, '?' matches any single character. Wildcards can be specified for the primary id, the secondary id, or both. For example, the placeholder "someView:*" will match any occurrence of the view that has primary id "someView" and that also has some non-null secondary id. Note that this placeholder will not match the view if it has no secondary id, since the compound id in this case is simply "someView".
Example of populating a layout with standard workbench views:
IPageLayout layout = ... // Get the editor area. String editorArea = layout.getEditorArea(); // Top left: Project Explorer view and Bookmarks view placeholder IFolderLayout topLeft = layout.createFolder("topLeft", IPageLayout.LEFT, 0.25f, editorArea); topLeft.addView(IPageLayout.ID_PROJECT_EXPLORER); topLeft.addPlaceholder(IPageLayout.ID_BOOKMARKS); // Bottom left: Outline view and Property Sheet view IFolderLayout bottomLeft = layout.createFolder("bottomLeft", IPageLayout.BOTTOM, 0.50f, "topLeft"); bottomLeft.addView(IPageLayout.ID_OUTLINE); bottomLeft.addView(IPageLayout.ID_PROP_SHEET); // Bottom right: Task List view layout.addView(IPageLayout.ID_TASK_LIST, IPageLayout.BOTTOM, 0.66f, editorArea);
- Restriction:
- This interface is not intended to be implemented by clients.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final int
Relationship constant indicating a part should be placed below its relative.static final float
Deprecated, for removal: This API element is subject to removal in a future version.discontinued support for fast viewsstatic final float
The default view ratio width for regular (non-fast) views.static final String
The view id for the workbench's Bookmark Navigator standard component.static final String
The part id for the workbench's editor area.static final String
The view id for the workbench's Minimap standard component.static final String
Id of the navigate action set.static final String
The view id for the workbench's Content Outline standard component.static final String
The view id for the workbench's Problems View standard component.static final String
The view id for the workbench's Progress View standard component.static final String
The view id for the Project Explorer.static final String
The view id for the workbench's Property Sheet standard component.static final String
The view id for the workbench's Task List standard component.static final float
A variable used to represent invalid ratios.static final int
Relationship constant indicating a part should be placed to the left of its relative.static final float
A variable used to represent a ratio which has not been specified.static final float
Maximum acceptable ratio value when adding a viewstatic final float
Minimum acceptable ratio value when adding a viewstatic final int
Relationship constant indicating a part should be placed to the right of its relative.static final int
Relationship constant indicating a part should be placed above its relative. -
Method Summary
Modifier and TypeMethodDescriptionvoid
addActionSet
(String actionSetId) Adds an action set with the given id to this page layout.void
addEditorOnboardingCommandId
(String commandId) Adds a command id for the empty editor area.void
addFastView
(String viewId) Deprecated, for removal: This API element is subject to removal in a future version.discontinued support for fast viewsvoid
addFastView
(String viewId, float ratio) Deprecated, for removal: This API element is subject to removal in a future version.discontinued support for fast viewsvoid
Adds a new wizard shortcut to the page layout.void
Adds a perspective shortcut to the page layout.void
addPlaceholder
(String viewId, int relationship, float ratio, String refId) Adds a view placeholder to this page layout.void
addShowInPart
(String id) Adds an item to the Show In prompter.void
Adds a show view shortcut to the page layout.void
addStandaloneView
(String viewId, boolean showTitle, int relationship, float ratio, String refId) Adds a standalone view with the given compound id to this page layout.void
addStandaloneViewPlaceholder
(String viewId, int relationship, float ratio, String refId, boolean showTitle) Adds a standalone view placeholder to this page layout.void
Adds a view with the given compound id to this page layout.createFolder
(String folderId, int relationship, float ratio, String refId) Creates and adds a new folder with the given id to this page layout.createPlaceholderFolder
(String folderId, int relationship, float ratio, String refId) Creates and adds a placeholder for a new folder with the given id to this page layout.Returns the perspective descriptor for the perspective being layed out.Returns the special identifier for the editor area in this page layout.int
Deprecated, for removal: This API element is subject to removal in a future version.this always returns -1 as of Eclipse 2.1Returns the folder layout for the view or placeholder with the given compound id in this page layout.getViewLayout
(String id) Returns the layout for the view or placeholder with the given compound id in this page layout.boolean
Returns whether the page's layout will show the editor area.boolean
isFixed()
Returnstrue
if this layout is fixed,false
if not.void
setEditorAreaVisible
(boolean showEditorArea) Show or hide the editor area for the page's layout.void
setEditorOnboardingImageUri
(String imageUri) Sets the onboarding image uri.void
Sets the onboarding text.void
setEditorReuseThreshold
(int openEditors) Deprecated, for removal: This API element is subject to removal in a future version.this method has no effect, as of Eclipse 2.1void
setFixed
(boolean isFixed) Sets whether this layout is fixed.
-
Field Details
-
ID_EDITOR_AREA
The part id for the workbench's editor area. This may only be used as a reference part for view addition.- See Also:
-
ID_PROJECT_EXPLORER
The view id for the Project Explorer.- Since:
- 3.5
- See Also:
-
ID_PROP_SHEET
The view id for the workbench's Property Sheet standard component.- See Also:
-
ID_OUTLINE
The view id for the workbench's Content Outline standard component.- See Also:
-
ID_BOOKMARKS
The view id for the workbench's Bookmark Navigator standard component.- See Also:
-
ID_PROBLEM_VIEW
The view id for the workbench's Problems View standard component.- Since:
- 3.0
- See Also:
-
ID_PROGRESS_VIEW
The view id for the workbench's Progress View standard component.- Since:
- 3.2
- See Also:
-
ID_TASK_LIST
The view id for the workbench's Task List standard component.- See Also:
-
ID_MINIMAP_VIEW
The view id for the workbench's Minimap standard component.- Since:
- 3.117
- See Also:
-
ID_NAVIGATE_ACTION_SET
Id of the navigate action set. (value"org.eclipse.ui.NavigateActionSet"
)- Since:
- 2.1
- See Also:
-
LEFT
static final int LEFTRelationship constant indicating a part should be placed to the left of its relative.- See Also:
-
RIGHT
static final int RIGHTRelationship constant indicating a part should be placed to the right of its relative.- See Also:
-
TOP
static final int TOPRelationship constant indicating a part should be placed above its relative.- See Also:
-
BOTTOM
static final int BOTTOMRelationship constant indicating a part should be placed below its relative.- See Also:
-
RATIO_MIN
static final float RATIO_MINMinimum acceptable ratio value when adding a view- Since:
- 2.0
- See Also:
-
RATIO_MAX
static final float RATIO_MAXMaximum acceptable ratio value when adding a view- Since:
- 2.0
- See Also:
-
DEFAULT_FASTVIEW_RATIO
Deprecated, for removal: This API element is subject to removal in a future version.discontinued support for fast viewsThe default fast view ratio width.- Since:
- 2.0
- See Also:
-
DEFAULT_VIEW_RATIO
static final float DEFAULT_VIEW_RATIOThe default view ratio width for regular (non-fast) views.- Since:
- 2.0
- See Also:
-
INVALID_RATIO
static final float INVALID_RATIOA variable used to represent invalid ratios.- Since:
- 2.0
- See Also:
-
NULL_RATIO
static final float NULL_RATIOA variable used to represent a ratio which has not been specified.- Since:
- 2.0
- See Also:
-
-
Method Details
-
addActionSet
Adds an action set with the given id to this page layout. The id must name an action set contributed to the workbench's extension point (named"org.eclipse.ui.actionSet"
).- Parameters:
actionSetId
- the action set id
-
addFastView
Deprecated, for removal: This API element is subject to removal in a future version.discontinued support for fast viewsAdds the view with the given compound id to the page layout as a fast view. See theIPageLayout
type documentation for more details about compound ids. The primary id must name a view contributed to the workbench's view extension point (named"org.eclipse.ui.views"
).- Parameters:
viewId
- the compound id of the view to be added- Since:
- 2.0
-
addFastView
Deprecated, for removal: This API element is subject to removal in a future version.discontinued support for fast viewsAdds the view with the given compound id to the page layout as a fast view with the given width ratio. See theIPageLayout
type documentation for more details about compound ids. The primary id must name a view contributed to the workbench's view extension point (named"org.eclipse.ui.views"
).- Parameters:
viewId
- the compound id of the view to be addedratio
- the percentage of the workbench the fast view will cover- Since:
- 2.0
-
addNewWizardShortcut
Adds a new wizard shortcut to the page layout. These are typically shown in the UI to allow rapid navigation to appropriate new wizards. For example, in the Eclipse IDE, these appear as items under the File > New menu. The id must name a new wizard extension contributed to the workbench's new wizards extension point (named"org.eclipse.ui.newWizards"
).- Parameters:
id
- the wizard id
-
addPerspectiveShortcut
Adds a perspective shortcut to the page layout. These are typically shown in the UI to allow rapid navigation to appropriate new wizards. For example, in the Eclipse IDE, these appear as items under the Window > Open Perspective menu. The id must name a perspective extension contributed to the workbench's perspectives extension point (named"org.eclipse.ui.perspectives"
).- Parameters:
id
- the perspective id
-
addPlaceholder
Adds a view placeholder to this page layout. A view placeholder is used to define the position of a view before the view appears. Initially, it is invisible; however, if the user ever opens a view whose compound id matches the placeholder, the view will appear at the same location as the placeholder. See theIPageLayout
type documentation for more details about compound ids. If the placeholder contains wildcards, it remains in the layout, otherwise it is replaced by the view. If the primary id of the placeholder has no wildcards, it must refer to a view contributed to the workbench's view extension point (named"org.eclipse.ui.views"
).- Parameters:
viewId
- the compound view id (wildcards allowed)relationship
- the position relative to the reference part; one ofTOP
,BOTTOM
,LEFT
, orRIGHT
ratio
- a ratio specifying how to divide the space currently occupied by the reference part, in the range0.05f
to0.95f
. Values outside this range will be clipped to facilitate direct manipulation. For a vertical split, the part on top gets the specified ratio of the current space and the part on bottom gets the rest. Likewise, for a horizontal split, the part at left gets the specified ratio of the current space and the part at right gets the rest.refId
- the id of the reference part; either a view id, a folder id, or the special editor area id returned bygetEditorArea
-
addShowInPart
Adds an item to the Show In prompter. The id must name a view contributed to the workbench's view extension point (named"org.eclipse.ui.views"
).- Parameters:
id
- the view id- Since:
- 2.1
-
addShowViewShortcut
Adds a show view shortcut to the page layout. These are typically shown in the UI to allow rapid navigation to appropriate views. For example, in the Eclipse IDE, these appear as items under the Window > Show View menu. The id must name a view contributed to the workbench's views extension point (named"org.eclipse.ui.views"
).- Parameters:
id
- the view id
-
addView
Adds a view with the given compound id to this page layout. See theIPageLayout
type documentation for more details about compound ids. The primary id must name a view contributed to the workbench's view extension point (named"org.eclipse.ui.views"
).- Parameters:
viewId
- the compound view idrelationship
- the position relative to the reference part; one ofTOP
,BOTTOM
,LEFT
, orRIGHT
ratio
- a ratio specifying how to divide the space currently occupied by the reference part, in the range0.05f
to0.95f
. Values outside this range will be clipped to facilitate direct manipulation. For a vertical split, the part on top gets the specified ratio of the current space and the part on bottom gets the rest. Likewise, for a horizontal split, the part at left gets the specified ratio of the current space and the part at right gets the rest.refId
- the id of the reference part; either a view id, a folder id, or the special editor area id returned bygetEditorArea
-
createFolder
Creates and adds a new folder with the given id to this page layout. The position and relative size of the folder is expressed relative to a reference part.- Parameters:
folderId
- the id for the new folder. This must be unique within the layout to avoid collision with other parts.relationship
- the position relative to the reference part; one ofTOP
,BOTTOM
,LEFT
, orRIGHT
ratio
- a ratio specifying how to divide the space currently occupied by the reference part, in the range0.05f
to0.95f
. Values outside this range will be clipped to facilitate direct manipulation. For a vertical split, the part on top gets the specified ratio of the current space and the part on bottom gets the rest. Likewise, for a horizontal split, the part at left gets the specified ratio of the current space and the part at right gets the rest.refId
- the id of the reference part; either a view id, a folder id, or the special editor area id returned bygetEditorArea
- Returns:
- the new folder
-
createPlaceholderFolder
IPlaceholderFolderLayout createPlaceholderFolder(String folderId, int relationship, float ratio, String refId) Creates and adds a placeholder for a new folder with the given id to this page layout. The position and relative size of the folder is expressed relative to a reference part.- Parameters:
folderId
- the id for the new folder. This must be unique within the layout to avoid collision with other parts.relationship
- the position relative to the reference part; one ofTOP
,BOTTOM
,LEFT
, orRIGHT
ratio
- a ratio specifying how to divide the space currently occupied by the reference part, in the range0.05f
to0.95f
. Values outside this range will be clipped to facilitate direct manipulation. For a vertical split, the part on top gets the specified ratio of the current space and the part on bottom gets the rest. Likewise, for a horizontal split, the part at left gets the specified ratio of the current space and the part at right gets the rest.refId
- the id of the reference part; either a view id, a folder id, or the special editor area id returned bygetEditorArea
- Returns:
- a placeholder for the new folder
- Since:
- 2.0
-
getEditorArea
String getEditorArea()Returns the special identifier for the editor area in this page layout. The identifier for the editor area is also stored inID_EDITOR_AREA
.The editor area is automatically added to each layout before anything else. It should be used as the point of reference when adding views to a layout.
- Returns:
- the special id of the editor area
-
isEditorAreaVisible
boolean isEditorAreaVisible()Returns whether the page's layout will show the editor area.- Returns:
true
when editor area visible,false
otherwise
-
setEditorAreaVisible
void setEditorAreaVisible(boolean showEditorArea) Show or hide the editor area for the page's layout.- Parameters:
showEditorArea
-true
to show the editor area,false
to hide the editor area
-
getEditorReuseThreshold
Deprecated, for removal: This API element is subject to removal in a future version.this always returns -1 as of Eclipse 2.1Returns the number of open editors before reusing editors or -1 if the preference settings should be used instead.- Returns:
- the number of open editors before reusing editors or -1 if the preference settings should be used instead.
-
setEditorReuseThreshold
Deprecated, for removal: This API element is subject to removal in a future version.this method has no effect, as of Eclipse 2.1Sets the number of open editors before reusing editors. If < 0 the user preference settings will be used.- Parameters:
openEditors
- the number of open editors
-
setFixed
void setFixed(boolean isFixed) Sets whether this layout is fixed. In a fixed layout, layout parts cannot be moved or zoomed, and the initial set of views cannot be closed.- Parameters:
isFixed
-true
if this layout is fixed,false
if not- Since:
- 3.0
-
isFixed
boolean isFixed()Returnstrue
if this layout is fixed,false
if not. In a fixed layout, layout parts cannot be moved or zoomed, and the initial set of views cannot be closed. The default isfalse
.- Returns:
true
if this layout is fixed,false
if not.- Since:
- 3.0
-
getViewLayout
Returns the layout for the view or placeholder with the given compound id in this page layout. See theIPageLayout
type documentation for more details about compound ids. Returnsnull
if the specified view or placeholder is unknown to the layout.- Parameters:
id
- the compound view id or placeholder- Returns:
- the view layout, or
null
- Since:
- 3.0
-
addStandaloneView
void addStandaloneView(String viewId, boolean showTitle, int relationship, float ratio, String refId) Adds a standalone view with the given compound id to this page layout. See theIPageLayout
type documentation for more details about compound ids. A standalone view cannot be docked together with other views. A standalone view's title can optionally be hidden. If hidden, then any controls typically shown with the title (such as the close button) are also hidden. Any contributions or other content from the view itself are always shown (e.g. toolbar or view menu contributions, content description).The id must name a view contributed to the workbench's view extension point (named
"org.eclipse.ui.views"
).- Parameters:
viewId
- the compound view idshowTitle
-true
to show the title and related controls,false
to hide themrelationship
- the position relative to the reference part; one ofTOP
,BOTTOM
,LEFT
, orRIGHT
ratio
- a ratio specifying how to divide the space currently occupied by the reference part, in the range0.05f
to0.95f
. Values outside this range will be clipped to facilitate direct manipulation. For a vertical split, the part on top gets the specified ratio of the current space and the part on bottom gets the rest. Likewise, for a horizontal split, the part at left gets the specified ratio of the current space and the part at right gets the rest.refId
- the id of the reference part; either a view id, a folder id, or the special editor area id returned bygetEditorArea
- Since:
- 3.0
-
addStandaloneViewPlaceholder
void addStandaloneViewPlaceholder(String viewId, int relationship, float ratio, String refId, boolean showTitle) Adds a standalone view placeholder to this page layout. A view placeholder is used to define the position of a view before the view appears. Initially, it is invisible; however, if the user ever opens a view whose compound id matches the placeholder, the view will appear at the same location as the placeholder. See theIPageLayout
type documentation for more details about compound ids. If the placeholder contains wildcards, it remains in the layout, otherwise it is replaced by the view. If the primary id of the placeholder has no wildcards, it must refer to a view contributed to the workbench's view extension point (named"org.eclipse.ui.views"
).- Parameters:
viewId
- the compound view id (wildcards allowed)relationship
- the position relative to the reference part; one ofTOP
,BOTTOM
,LEFT
, orRIGHT
ratio
- a ratio specifying how to divide the space currently occupied by the reference part, in the range0.05f
to0.95f
. Values outside this range will be clipped to facilitate direct manipulation. For a vertical split, the part on top gets the specified ratio of the current space and the part on bottom gets the rest. Likewise, for a horizontal split, the part at left gets the specified ratio of the current space and the part at right gets the rest.refId
- the id of the reference part; either a view id, a folder id, or the special editor area id returned bygetEditorArea
showTitle
- true to show the view's title, false if not- Since:
- 3.2
-
getDescriptor
IPerspectiveDescriptor getDescriptor()Returns the perspective descriptor for the perspective being layed out.- Returns:
- the perspective descriptor for the perspective being layed out
- Since:
- 3.2
-
getFolderForView
Returns the folder layout for the view or placeholder with the given compound id in this page layout. See theIPageLayout
type documentation for more details about compound ids. Returnsnull
if the specified view or placeholder is unknown to the layout, or the placeholder was not in a folder.- Parameters:
id
- the compound view id or placeholder. Must not benull
.- Returns:
- the folder layout, or
null
- Since:
- 3.3
-
setEditorOnboardingText
Sets the onboarding text. The text is shown in the editor area in case no editor is open.- Parameters:
text
- the onboarding text- Since:
- 3.129
-
setEditorOnboardingImageUri
Sets the onboarding image uri. The corresponding image is shown in the editor area in case no editor is open.- Parameters:
imageUri
- the uri of the onboarding image- Since:
- 3.129
-
addEditorOnboardingCommandId
Adds a command id for the empty editor area.- Parameters:
commandId
- an id of an onboarding command- Since:
- 3.129
-