org.eclipse.ui.IPageLayout Maven / Gradle / Ivy
The newest version!
/*******************************************************************************
* Copyright (c) 2000, 2019 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
* Chris Gross
* - Fix for 99155 - allow standalone view placeholders
* Chris Gross [email protected] Bug 107443
* Denis Zygann - Bug 457390
*******************************************************************************/
package org.eclipse.ui;
/**
* A page layout defines the initial layout for a perspective within a page in a
* workbench window.
*
* 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
* {@link org.eclipse.ui.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);
*
*
* @noimplement This interface is not intended to be implemented by clients.
*/
public interface IPageLayout {
/**
* The part id for the workbench's editor area. This may only be used as a
* reference part for view addition.
*/
String ID_EDITOR_AREA = "org.eclipse.ui.editorss"; //$NON-NLS-1$
/**
* The view id for the Project Explorer.
*
* @since 3.5
*/
String ID_PROJECT_EXPLORER = "org.eclipse.ui.navigator.ProjectExplorer"; //$NON-NLS-1$
/**
* The view id for the workbench's Property Sheet standard component.
*/
String ID_PROP_SHEET = "org.eclipse.ui.views.PropertySheet"; //$NON-NLS-1$
/**
* The view id for the workbench's Content Outline standard component.
*/
String ID_OUTLINE = "org.eclipse.ui.views.ContentOutline"; //$NON-NLS-1$
/**
* The view id for the workbench's Bookmark Navigator standard component.
*/
String ID_BOOKMARKS = "org.eclipse.ui.views.BookmarkView"; //$NON-NLS-1$
/**
* The view id for the workbench's Problems View standard component.
*
* @since 3.0
*/
String ID_PROBLEM_VIEW = "org.eclipse.ui.views.ProblemView"; //$NON-NLS-1$
/**
* The view id for the workbench's Progress View standard component.
*
* @since 3.2
*/
String ID_PROGRESS_VIEW = "org.eclipse.ui.views.ProgressView"; //$NON-NLS-1$
/**
* The view id for the workbench's Task List standard component.
*/
String ID_TASK_LIST = "org.eclipse.ui.views.TaskList"; //$NON-NLS-1$
/**
* The view id for the workbench's Minimap standard component.
*
* @since 3.117
*/
String ID_MINIMAP_VIEW = "org.eclipse.ui.views.minimap.MinimapView"; //$NON-NLS-1$
/**
* Id of the navigate action set. (value
* "org.eclipse.ui.NavigateActionSet")
*
* @since 2.1
*/
String ID_NAVIGATE_ACTION_SET = "org.eclipse.ui.NavigateActionSet"; //$NON-NLS-1$
/**
* Relationship constant indicating a part should be placed to the left of its
* relative.
*/
int LEFT = 1;
/**
* Relationship constant indicating a part should be placed to the right of its
* relative.
*/
int RIGHT = 2;
/**
* Relationship constant indicating a part should be placed above its relative.
*/
int TOP = 3;
/**
* Relationship constant indicating a part should be placed below its relative.
*/
int BOTTOM = 4;
/**
* Minimum acceptable ratio value when adding a view
*
* @since 2.0
*/
float RATIO_MIN = 0.05f;
/**
* Maximum acceptable ratio value when adding a view
*
* @since 2.0
*/
float RATIO_MAX = 0.95f;
/**
* The default fast view ratio width.
*
* @since 2.0
* @deprecated discontinued support for fast views
*/
@Deprecated(forRemoval = true, since = "2023-12")
float DEFAULT_FASTVIEW_RATIO = 0.3f;
/**
* The default view ratio width for regular (non-fast) views.
*
* @since 2.0
*/
float DEFAULT_VIEW_RATIO = 0.5f;
/**
* A variable used to represent invalid ratios.
*
* @since 2.0
*/
float INVALID_RATIO = -1f;
/**
* A variable used to represent a ratio which has not been specified.
*
* @since 2.0
*/
float NULL_RATIO = -2f;
/**
* 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").
*
* @param actionSetId the action set id
*/
void addActionSet(String actionSetId);
/**
* Adds the view with the given compound id to the page layout as a fast view.
* See the {@link IPageLayout} 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").
*
* @param viewId the compound id of the view to be added
* @since 2.0
* @deprecated discontinued support for fast views
*/
@Deprecated(forRemoval = true, since = "2023-12")
void addFastView(String viewId);
/**
* Adds the view with the given compound id to the page layout as a fast view
* with the given width ratio. See the {@link IPageLayout} 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").
*
* @param viewId the compound id of the view to be added
* @param ratio the percentage of the workbench the fast view will cover
* @since 2.0
* @deprecated discontinued support for fast views
*/
@Deprecated(forRemoval = true, since = "2023-12")
void addFastView(String viewId, float ratio);
/**
* 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").
*
* @param id the wizard id
*/
void addNewWizardShortcut(String id);
/**
* 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").
*
* @param id the perspective id
*/
void addPerspectiveShortcut(String id);
/**
* 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 the {@link IPageLayout} 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").
*
* @param viewId the compound view id (wildcards allowed)
* @param relationship the position relative to the reference part; one of
* TOP, BOTTOM, LEFT,
* or RIGHT
* @param ratio a ratio specifying how to divide the space currently
* occupied by the reference part, in the range
* 0.05f to 0.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.
* @param refId the id of the reference part; either a view id, a folder
* id, or the special editor area id returned by
* getEditorArea
*/
void addPlaceholder(String viewId, int relationship, float ratio, String refId);
/**
* 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").
*
* @param id the view id
*
* @since 2.1
*/
void addShowInPart(String id);
/**
* 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").
*
* @param id the view id
*/
void addShowViewShortcut(String id);
/**
* Adds a view with the given compound id to this page layout. See the
* {@link IPageLayout} 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").
*
* @param viewId the compound view id
* @param relationship the position relative to the reference part; one of
* TOP, BOTTOM, LEFT,
* or RIGHT
* @param ratio a ratio specifying how to divide the space currently
* occupied by the reference part, in the range
* 0.05f to 0.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.
* @param refId the id of the reference part; either a view id, a folder
* id, or the special editor area id returned by
* getEditorArea
*/
void addView(String viewId, int relationship, float ratio, String refId);
/**
* 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.
*
* @param folderId the id for the new folder. This must be unique within the
* layout to avoid collision with other parts.
* @param relationship the position relative to the reference part; one of
* TOP, BOTTOM, LEFT,
* or RIGHT
* @param ratio a ratio specifying how to divide the space currently
* occupied by the reference part, in the range
* 0.05f to 0.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.
* @param refId the id of the reference part; either a view id, a folder
* id, or the special editor area id returned by
* getEditorArea
* @return the new folder
*/
IFolderLayout createFolder(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.
*
* @param folderId the id for the new folder. This must be unique within the
* layout to avoid collision with other parts.
* @param relationship the position relative to the reference part; one of
* TOP, BOTTOM, LEFT,
* or RIGHT
* @param ratio a ratio specifying how to divide the space currently
* occupied by the reference part, in the range
* 0.05f to 0.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.
* @param refId the id of the reference part; either a view id, a folder
* id, or the special editor area id returned by
* getEditorArea
* @return a placeholder for the new folder
* @since 2.0
*/
IPlaceholderFolderLayout createPlaceholderFolder(String folderId, int relationship, float ratio, String refId);
/**
* Returns the special identifier for the editor area in this page layout. The
* identifier for the editor area is also stored in ID_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.
*
*
* @return the special id of the editor area
*/
String getEditorArea();
/**
* Returns whether the page's layout will show the editor area.
*
* @return true when editor area visible, false
* otherwise
*/
boolean isEditorAreaVisible();
/**
* Show or hide the editor area for the page's layout.
*
* @param showEditorArea true to show the editor area,
* false to hide the editor area
*/
void setEditorAreaVisible(boolean showEditorArea);
/**
* Returns the number of open editors before reusing editors or -1 if the
* preference settings should be used instead.
*
* @return the number of open editors before reusing editors or -1 if the
* preference settings should be used instead.
*
* @deprecated this always returns -1 as of Eclipse 2.1
*/
@Deprecated(forRemoval = true, since = "2023-12")
int getEditorReuseThreshold();
/**
* Sets the number of open editors before reusing editors. If < 0 the user
* preference settings will be used.
*
* @param openEditors the number of open editors
*
* @deprecated this method has no effect, as of Eclipse 2.1
*/
@Deprecated(forRemoval = true, since = "2023-12")
void setEditorReuseThreshold(int openEditors);
/**
* 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.
*
* @param isFixed true if this layout is fixed, false
* if not
* @since 3.0
*/
void setFixed(boolean isFixed);
/**
* Returns true 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 is false.
*
* @return true if this layout is fixed, false if not.
* @since 3.0
*/
boolean isFixed();
/**
* Returns the layout for the view or placeholder with the given compound id in
* this page layout. See the {@link IPageLayout} type documentation for more
* details about compound ids. Returns null if the specified view
* or placeholder is unknown to the layout.
*
* @param id the compound view id or placeholder
* @return the view layout, or null
* @since 3.0
*/
IViewLayout getViewLayout(String id);
/**
* Adds a standalone view with the given compound id to this page layout. See
* the {@link IPageLayout} 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").
*
*
* @param viewId the compound view id
* @param showTitle true to show the title and related controls,
* false to hide them
* @param relationship the position relative to the reference part; one of
* TOP, BOTTOM, LEFT,
* or RIGHT
* @param ratio a ratio specifying how to divide the space currently
* occupied by the reference part, in the range
* 0.05f to 0.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.
* @param refId the id of the reference part; either a view id, a folder
* id, or the special editor area id returned by
* getEditorArea
*
* @since 3.0
*/
void addStandaloneView(String viewId, boolean showTitle, int relationship, float ratio, String refId);
/**
* 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 the {@link IPageLayout} 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").
*
* @param viewId the compound view id (wildcards allowed)
* @param relationship the position relative to the reference part; one of
* TOP, BOTTOM, LEFT,
* or RIGHT
* @param ratio a ratio specifying how to divide the space currently
* occupied by the reference part, in the range
* 0.05f to 0.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.
* @param refId the id of the reference part; either a view id, a folder
* id, or the special editor area id returned by
* getEditorArea
* @param showTitle true to show the view's title, false if not
*
* @since 3.2
*/
void addStandaloneViewPlaceholder(String viewId, int relationship, float ratio, String refId, boolean showTitle);
/**
* Returns the perspective descriptor for the perspective being layed out.
*
* @return the perspective descriptor for the perspective being layed out
* @since 3.2
*/
IPerspectiveDescriptor getDescriptor();
/**
* Returns the folder layout for the view or placeholder with the given compound
* id in this page layout. See the {@link IPageLayout} type documentation for
* more details about compound ids. Returns null if the specified
* view or placeholder is unknown to the layout, or the placeholder was not in a
* folder.
*
* @param id the compound view id or placeholder. Must not be null.
* @return the folder layout, or null
* @since 3.3
*/
IPlaceholderFolderLayout getFolderForView(String id);
/**
* Sets the onboarding text. The text is shown in the editor area in case no
* editor is open.
*
* @param text the onboarding text
* @since 3.129
*/
void setEditorOnboardingText(String text);
/**
* Sets the onboarding image uri. The corresponding image is shown in the editor
* area in case no editor is open.
*
* @param imageUri the uri of the onboarding image
* @since 3.129
*/
void setEditorOnboardingImageUri(String imageUri);
/**
* Adds a command id for the empty editor area.
*
* @param commandId an id of an onboarding command
* @since 3.129
*/
void addEditorOnboardingCommandId(String commandId);
}