org.eclipse.ui
Interface IPageLayout

public interface IPageLayout

A page layout defines the initial layout for a page in a workbench window.

This interface is not intended to be implemented by clients.

When the workbench needs to create a new page, it uses a perspective to creates a new page layout with a single editor area. This layout is then passed to client code (implementation of IPerspectiveFactory.createInitialLayout) where additional views can be added, using the existing editor area as the initial point of reference.

Example of populating a layout with standard workbench views:

 IPageLayout layout = ...
 // Get the editor area.
 String editorArea = layout.getEditorArea();

 // Top left: Resource Navigator view and Bookmarks view placeholder
 IFolderLayout topLeft = layout.createFolder("topLeft", IPageLayout.LEFT, 0.25f,
    editorArea);
 topLeft.addView(IPageLayout.ID_RES_NAV);
 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);
 

Field Summary

static int	BOTTOM Relationship constant indicating a part should be placed below its relative.
static float	DEFAULT_FASTVIEW_RATIO The default fast view ratio width.
static float	DEFAULT_VIEW_RATIO The default view ratio width for regular (non-fast) views.
static String	ID_BOOKMARKS The view id for the workbench's Bookmark Navigator standard component.
static String	ID_EDITOR_AREA The part id for the workbench's editor area.
static String	ID_OUTLINE The view id for the workbench's Content Outline standard component.
static String	ID_PROP_SHEET The view id for the workbench's Property Sheet standard component.
static String	ID_RES_NAV The view id for the workbench's Resource Navigator standard component.
static String	ID_TASK_LIST The view id for the workbench's Task List standard component.
static float	INVALID_RATIO A variable used to represent invalid ratios.
static int	LEFT Relationship constant indicating a part should be placed to the left of its relative.
static float	NULL_RATIO A variable used to represent a ratio which has not been specified.
static float	RATIO_MAX Maximum acceptable ratio value when adding a view
static float	RATIO_MIN Minimum acceptable ratio value when adding a view
static int	RIGHT Relationship constant indicating a part should be placed to the right of its relative.
static int	TOP Relationship constant indicating a part should be placed above its relative.

Method Summary

void	addActionSet(String actionSetId) Adds an action set with the given id to this page layout.
void	addFastView(String id) Adds the view with the given id to the page layout as a fast view.
void	addFastView(String id, float ratio) Adds the view with the given id to the page layout as a fast view with the given width ratio.
void	addNewWizardShortcut(String id) Adds a creation wizard to the File New menu.
void	addPerspectiveShortcut(String id) Adds a perspective shortcut to the Perspective menu.
void	addPlaceholder(String viewId, int relationship, float ratio, String refId) Adds a placeholder for a view with the given id to this page layout.
void	addShowViewShortcut(String id) Adds a view to the Show View menu.
void	addView(String viewId, int relationship, float ratio, String refId) Adds a view with the given id to this page layout.
IFolderLayout	createFolder(String folderId, int relationship, float ratio, String refId) Creates and adds a new folder with the given id to this page layout.
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.
String	getEditorArea() Returns the special identifier for the editor area in this page layout.
int	getEditorReuseThreshold() Deprecated.
boolean	isEditorAreaVisible() Returns whether the page's layout will show the editor area.
void	setEditorAreaVisible(boolean showEditorArea) Show or hide the editor area for the page's layout.
void	setEditorReuseThreshold(int openEditors) Deprecated.

Field Detail

ID_EDITOR_AREA

public static final String 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:

Constant Field Values

ID_RES_NAV

public static final String ID_RES_NAV

The view id for the workbench's Resource Navigator standard component.

See Also:

Constant Field Values

ID_PROP_SHEET

public static final String ID_PROP_SHEET

The view id for the workbench's Property Sheet standard component.

See Also:

Constant Field Values

ID_OUTLINE

public static final String ID_OUTLINE

The view id for the workbench's Content Outline standard component.

See Also:

Constant Field Values

ID_TASK_LIST

public static final String ID_TASK_LIST

The view id for the workbench's Task List standard component.

See Also:

Constant Field Values

ID_BOOKMARKS

public static final String ID_BOOKMARKS

The view id for the workbench's Bookmark Navigator standard component.

See Also:

Constant Field Values

LEFT

public static final int LEFT

Relationship constant indicating a part should be placed to the left of its relative.

See Also:

Constant Field Values

RIGHT

public static final int RIGHT

Relationship constant indicating a part should be placed to the right of its relative.

See Also:

Constant Field Values

TOP

public static final int TOP

Relationship constant indicating a part should be placed above its relative.

See Also:

Constant Field Values

BOTTOM

public static final int BOTTOM

Relationship constant indicating a part should be placed below its relative.

See Also:

Constant Field Values

RATIO_MIN

public static final float RATIO_MIN

Minimum acceptable ratio value when adding a view

Since:

2.0

See Also:

Constant Field Values

RATIO_MAX

public static final float RATIO_MAX

Maximum acceptable ratio value when adding a view

Since:

2.0

See Also:

Constant Field Values

DEFAULT_FASTVIEW_RATIO

public static final float DEFAULT_FASTVIEW_RATIO

The default fast view ratio width.

Since:

2.0

See Also:

Constant Field Values

DEFAULT_VIEW_RATIO

public static final float DEFAULT_VIEW_RATIO

The default view ratio width for regular (non-fast) views.

Since:

2.0

See Also:

Constant Field Values

INVALID_RATIO

public static final float INVALID_RATIO

A variable used to represent invalid ratios.

Since:

2.0

See Also:

Constant Field Values

NULL_RATIO

public static final float NULL_RATIO

A variable used to represent a ratio which has not been specified.

See Also:

Constant Field Values

Method Detail

addActionSet

public void addActionSet(String actionSetId)

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

public void addFastView(String id)

Adds the view with the given id to the page layout as a fast view. The id must name a view contributed to the workbench's view extension point (named "org.eclipse.ui.views").

Parameters:

id - the id of the view to be added

Since:

2.0

addFastView

public void addFastView(String id,
                        float ratio)

Adds the view with the given id to the page layout as a fast view with the given width ratio. The id must name a view contributed to the workbench's view extension point (named "org.eclipse.ui.views").

Parameters:

id - the id of the view to be added

ratio - the percentage of the workbench the fast view will cover

Since:

2.0

addNewWizardShortcut

public void addNewWizardShortcut(String id)

Adds a creation wizard to the File New menu. The id must name a new wizard extension contributed to the workbench's extension point (named "org.eclipse.ui.newWizards").

Parameters:

id - the wizard id

addPerspectiveShortcut

public void addPerspectiveShortcut(String id)

Adds a perspective shortcut to the Perspective menu. The id must name a perspective extension contributed to the workbench's extension point (named "org.eclipse.ui.perspectives").

Parameters:

id - the perspective id

addPlaceholder

public void addPlaceholder(String viewId,
                           int relationship,
                           float ratio,
                           String refId)

Adds a placeholder for a view with the given id 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 with the same id as a placeholder, the view will replace the placeholder as it is being made visible. The id must name a view contributed to the workbench's view extension point (named "org.eclipse.ui.views").

Parameters:

viewId - the view id

relationship - the position relative to the reference part; one of TOP, BOTTOM, LEFT, or RIGHT

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.

refId - the id of the reference part; either a view id, a folder id, or the special editor area id returned by getEditorArea

addShowViewShortcut

public void addShowViewShortcut(String id)

Adds a view to the Show View menu. The id must name a view extension contributed to the workbench's extension point (named "org.eclipse.ui.views").

Parameters:

id - the view id

addView

public void addView(String viewId,
                    int relationship,
                    float ratio,
                    String refId)

Adds a view with the given id to this page layout. The id must name a view contributed to the workbench's view extension point (named "org.eclipse.ui.views").

Parameters:

viewId - the view id

relationship - the position relative to the reference part; one of TOP, BOTTOM, LEFT, or RIGHT

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.

refId - the id of the reference part; either a view id, a folder id, or the special editor area id returned by getEditorArea

createFolder

public IFolderLayout createFolder(String folderId,
                                  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.

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 of TOP, BOTTOM, LEFT, or RIGHT

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.

refId - the id of the reference part; either a view id, a folder id, or the special editor area id returned by getEditorArea

Returns:

the new folder

createPlaceholderFolder

public 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 of TOP, BOTTOM, LEFT, or RIGHT

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.

refId - the id of the reference part; either a view id, a folder id, or the special editor area id returned by getEditorArea

Returns:

a placeholder for the new folder

Since:

2.0

getEditorArea

public String getEditorArea()

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.

Returns:

the special id of the editor area

isEditorAreaVisible

public boolean isEditorAreaVisible()

Returns whether the page's layout will show the editor area.

Returns:

true when editor area visible, false otherwise

setEditorAreaVisible

public 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

public int getEditorReuseThreshold()

Deprecated.

Returns the number of open editors before reusing editors or -1 if the preference settings should be used instead. Note: For EXPERIMENTAL use only. IT MAY CHANGE IN NEAR FUTURE.

Returns:

a int

setEditorReuseThreshold

public void setEditorReuseThreshold(int openEditors)

Deprecated.

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.

Parameters:

openEditors - the number of open editors.