001: /*******************************************************************************
002: * Copyright (c) 2000, 2007 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: * Chris Gross <schtoo@schtoo.com>
011: * - Fix for 99155 - allow standalone view placeholders
012: * Chris Gross chris.gross@us.ibm.com Bug 107443
013: *******************************************************************************/package org.eclipse.ui;
014:
015: /**
016: * A page layout defines the initial layout for a perspective within a page
017: * in a workbench window.
018: * <p>
019: * This interface is not intended to be implemented by clients.
020: * </p>
021: * <p>
022: * When a perspective is opened, it creates a new page layout with a single editor area.
023: * This layout is then passed to the perspective factory (implementation of
024: * {@link org.eclipse.ui.IPerspectiveFactory#createInitialLayout(IPageLayout)}) where
025: * additional views and other content can be added, using the existing editor area as
026: * the initial point of reference.
027: * </p>
028: * <p>
029: * In some cases, multiple instances of a particular view may need to be added
030: * to the same layout. These are disambiguated using a secondary id.
031: * In layout methods taking a view id, the id can have the compound form:
032: * <strong>primaryId [':' secondaryId]</strong>.
033: * If a secondary id is given, the view must allow multiple instances by
034: * having specified <code>allowMultiple="true"</code> in its extension.
035: * View placeholders may also have a secondary id.
036: * </p>
037: * <p>
038: * Wildcards are permitted in placeholder ids (but not regular view ids).
039: * '*' matches any substring, '?' matches any single character.
040: * Wildcards can be specified for the primary id, the secondary id, or both.
041: * For example, the placeholder "someView:*" will match any occurrence of the view
042: * that has primary id "someView" and that also has some non-null secondary id.
043: * Note that this placeholder will not match the view if it has no secondary id,
044: * since the compound id in this case is simply "someView".
045: * </p>
046: * <p>
047: * Example of populating a layout with standard workbench views:
048: * <pre>
049: * IPageLayout layout = ...
050: * // Get the editor area.
051: * String editorArea = layout.getEditorArea();
052: *
053: * // Top left: Resource Navigator view and Bookmarks view placeholder
054: * IFolderLayout topLeft = layout.createFolder("topLeft", IPageLayout.LEFT, 0.25f,
055: * editorArea);
056: * topLeft.addView(IPageLayout.ID_RES_NAV);
057: * topLeft.addPlaceholder(IPageLayout.ID_BOOKMARKS);
058: *
059: * // Bottom left: Outline view and Property Sheet view
060: * IFolderLayout bottomLeft = layout.createFolder("bottomLeft", IPageLayout.BOTTOM, 0.50f,
061: * "topLeft");
062: * bottomLeft.addView(IPageLayout.ID_OUTLINE);
063: * bottomLeft.addView(IPageLayout.ID_PROP_SHEET);
064: *
065: * // Bottom right: Task List view
066: * layout.addView(IPageLayout.ID_TASK_LIST, IPageLayout.BOTTOM, 0.66f, editorArea);
067: * </pre>
068: * </p>
069: */
070: public interface IPageLayout {
071:
072: /**
073: * The part id for the workbench's editor area. This may only be used
074: * as a reference part for view addition.
075: */
076: public static String ID_EDITOR_AREA = "org.eclipse.ui.editorss"; //$NON-NLS-1$
077:
078: /**
079: * The view id for the workbench's Resource Navigator standard component.
080: */
081: public static String ID_RES_NAV = "org.eclipse.ui.views.ResourceNavigator"; //$NON-NLS-1$
082:
083: /**
084: * The view id for the workbench's Property Sheet standard component.
085: */
086: public static String ID_PROP_SHEET = "org.eclipse.ui.views.PropertySheet"; //$NON-NLS-1$
087:
088: /**
089: * The view id for the workbench's Content Outline standard component.
090: */
091: public static String ID_OUTLINE = "org.eclipse.ui.views.ContentOutline"; //$NON-NLS-1$
092:
093: /**
094: * The view id for the workbench's Bookmark Navigator standard component.
095: */
096: public static String ID_BOOKMARKS = "org.eclipse.ui.views.BookmarkView"; //$NON-NLS-1$
097:
098: /**
099: * The view id for the workbench's Problems View standard component.
100: * @since 3.0
101: */
102: public static String ID_PROBLEM_VIEW = "org.eclipse.ui.views.ProblemView"; //$NON-NLS-1$
103:
104: /**
105: * The view id for the workbench's Progress View standard component.
106: * @since 3.2
107: */
108: public static String ID_PROGRESS_VIEW = "org.eclipse.ui.views.ProgressView"; //$NON-NLS-1$
109:
110: /**
111: * The view id for the workbench's Task List standard component.
112: */
113: public static String ID_TASK_LIST = "org.eclipse.ui.views.TaskList"; //$NON-NLS-1$
114:
115: /**
116: * Id of the navigate action set.
117: * (value <code>"org.eclipse.ui.NavigateActionSet"</code>)
118: * @since 2.1
119: */
120: public static final String ID_NAVIGATE_ACTION_SET = "org.eclipse.ui.NavigateActionSet"; //$NON-NLS-1$
121:
122: /**
123: * Relationship constant indicating a part should be placed to the left of
124: * its relative.
125: */
126: public static final int LEFT = 1;
127:
128: /**
129: * Relationship constant indicating a part should be placed to the right of
130: * its relative.
131: */
132: public static final int RIGHT = 2;
133:
134: /**
135: * Relationship constant indicating a part should be placed above its
136: * relative.
137: */
138: public static final int TOP = 3;
139:
140: /**
141: * Relationship constant indicating a part should be placed below its
142: * relative.
143: */
144: public static final int BOTTOM = 4;
145:
146: /**
147: * Minimum acceptable ratio value when adding a view
148: * @since 2.0
149: */
150: public static final float RATIO_MIN = 0.05f;
151:
152: /**
153: * Maximum acceptable ratio value when adding a view
154: * @since 2.0
155: */
156: public static final float RATIO_MAX = 0.95f;
157:
158: /**
159: * The default fast view ratio width.
160: * @since 2.0
161: */
162: public static final float DEFAULT_FASTVIEW_RATIO = 0.3f;
163:
164: /**
165: * The default view ratio width for regular (non-fast) views.
166: * @since 2.0
167: */
168: public static final float DEFAULT_VIEW_RATIO = 0.5f;
169:
170: /**
171: * A variable used to represent invalid ratios.
172: * @since 2.0
173: */
174: public static final float INVALID_RATIO = -1f;
175:
176: /**
177: * A variable used to represent a ratio which has not been specified.
178: * @since 2.0
179: */
180: public static final float NULL_RATIO = -2f;
181:
182: /**
183: * Adds an action set with the given id to this page layout.
184: * The id must name an action set contributed to the workbench's extension
185: * point (named <code>"org.eclipse.ui.actionSet"</code>).
186: *
187: * @param actionSetId the action set id
188: */
189: public void addActionSet(String actionSetId);
190:
191: /**
192: * Adds the view with the given compound id to the page layout as a fast view.
193: * See the {@link IPageLayout} type documentation for more details about compound ids.
194: * The primary id must name a view contributed to the workbench's view extension
195: * point (named <code>"org.eclipse.ui.views"</code>).
196: *
197: * @param viewId the compound id of the view to be added
198: * @since 2.0
199: */
200: public void addFastView(String viewId);
201:
202: /**
203: * Adds the view with the given compound id to the page layout as a fast view
204: * with the given width ratio.
205: * See the {@link IPageLayout} type documentation for more details about compound ids.
206: * The primary id must name a view contributed to the workbench's view extension
207: * point (named <code>"org.eclipse.ui.views"</code>).
208: *
209: * @param viewId the compound id of the view to be added
210: * @param ratio the percentage of the workbench the fast view will cover
211: * @since 2.0
212: */
213: public void addFastView(String viewId, float ratio);
214:
215: /**
216: * Adds a new wizard shortcut to the page layout.
217: * These are typically shown in the UI to allow rapid navigation to appropriate new wizards.
218: * For example, in the Eclipse IDE, these appear as items under the File > New menu.
219: * The id must name a new wizard extension contributed to the
220: * workbench's new wizards extension point (named <code>"org.eclipse.ui.newWizards"</code>).
221: *
222: * @param id the wizard id
223: */
224: public void addNewWizardShortcut(String id);
225:
226: /**
227: * Adds a perspective shortcut to the page layout.
228: * These are typically shown in the UI to allow rapid navigation to appropriate new wizards.
229: * For example, in the Eclipse IDE, these appear as items under the Window > Open Perspective menu.
230: * The id must name a perspective extension contributed to the
231: * workbench's perspectives extension point (named <code>"org.eclipse.ui.perspectives"</code>).
232: *
233: * @param id the perspective id
234: */
235: public void addPerspectiveShortcut(String id);
236:
237: /**
238: * Adds a view placeholder to this page layout.
239: * A view placeholder is used to define the position of a view before the view
240: * appears. Initially, it is invisible; however, if the user ever opens a view
241: * whose compound id matches the placeholder, the view will appear at the same
242: * location as the placeholder.
243: * See the {@link IPageLayout} type documentation for more details about compound ids.
244: * If the placeholder contains wildcards, it remains in the layout, otherwise
245: * it is replaced by the view.
246: * If the primary id of the placeholder has no wildcards, it must refer to a view
247: * contributed to the workbench's view extension point
248: * (named <code>"org.eclipse.ui.views"</code>).
249: *
250: * @param viewId the compound view id (wildcards allowed)
251: * @param relationship the position relative to the reference part;
252: * one of <code>TOP</code>, <code>BOTTOM</code>, <code>LEFT</code>,
253: * or <code>RIGHT</code>
254: * @param ratio a ratio specifying how to divide the space currently occupied by the reference part,
255: * in the range <code>0.05f</code> to <code>0.95f</code>.
256: * Values outside this range will be clipped to facilitate direct manipulation.
257: * For a vertical split, the part on top gets the specified ratio of the current space
258: * and the part on bottom gets the rest.
259: * Likewise, for a horizontal split, the part at left gets the specified ratio of the current space
260: * and the part at right gets the rest.
261: * @param refId the id of the reference part; either a view id, a folder id,
262: * or the special editor area id returned by <code>getEditorArea</code>
263: */
264: public void addPlaceholder(String viewId, int relationship,
265: float ratio, String refId);
266:
267: /**
268: * Adds an item to the Show In prompter.
269: * The id must name a view contributed to the workbench's view extension point
270: * (named <code>"org.eclipse.ui.views"</code>).
271: *
272: * @param id the view id
273: *
274: * @since 2.1
275: */
276: public void addShowInPart(String id);
277:
278: /**
279: * Adds a show view shortcut to the page layout.
280: * These are typically shown in the UI to allow rapid navigation to appropriate views.
281: * For example, in the Eclipse IDE, these appear as items under the Window > Show View menu.
282: * The id must name a view contributed to the workbench's views extension point
283: * (named <code>"org.eclipse.ui.views"</code>).
284: *
285: * @param id the view id
286: */
287: public void addShowViewShortcut(String id);
288:
289: /**
290: * Adds a view with the given compound id to this page layout.
291: * See the {@link IPageLayout} type documentation for more details about compound ids.
292: * The primary id must name a view contributed to the workbench's view extension point
293: * (named <code>"org.eclipse.ui.views"</code>).
294: *
295: * @param viewId the compound view id
296: * @param relationship the position relative to the reference part;
297: * one of <code>TOP</code>, <code>BOTTOM</code>, <code>LEFT</code>,
298: * or <code>RIGHT</code>
299: * @param ratio a ratio specifying how to divide the space currently occupied by the reference part,
300: * in the range <code>0.05f</code> to <code>0.95f</code>.
301: * Values outside this range will be clipped to facilitate direct manipulation.
302: * For a vertical split, the part on top gets the specified ratio of the current space
303: * and the part on bottom gets the rest.
304: * Likewise, for a horizontal split, the part at left gets the specified ratio of the current space
305: * and the part at right gets the rest.
306: * @param refId the id of the reference part; either a view id, a folder id,
307: * or the special editor area id returned by <code>getEditorArea</code>
308: */
309: public void addView(String viewId, int relationship, float ratio,
310: String refId);
311:
312: /**
313: * Creates and adds a new folder with the given id to this page layout.
314: * The position and relative size of the folder is expressed relative to
315: * a reference part.
316: *
317: * @param folderId the id for the new folder. This must be unique within
318: * the layout to avoid collision with other parts.
319: * @param relationship the position relative to the reference part;
320: * one of <code>TOP</code>, <code>BOTTOM</code>, <code>LEFT</code>,
321: * or <code>RIGHT</code>
322: * @param ratio a ratio specifying how to divide the space currently occupied by the reference part,
323: * in the range <code>0.05f</code> to <code>0.95f</code>.
324: * Values outside this range will be clipped to facilitate direct manipulation.
325: * For a vertical split, the part on top gets the specified ratio of the current space
326: * and the part on bottom gets the rest.
327: * Likewise, for a horizontal split, the part at left gets the specified ratio of the current space
328: * and the part at right gets the rest.
329: * @param refId the id of the reference part; either a view id, a folder id,
330: * or the special editor area id returned by <code>getEditorArea</code>
331: * @return the new folder
332: */
333: public IFolderLayout createFolder(String folderId,
334: int relationship, float ratio, String refId);
335:
336: /**
337: * Creates and adds a placeholder for a new folder with the given id to this page layout.
338: * The position and relative size of the folder is expressed relative to
339: * a reference part.
340: *
341: * @param folderId the id for the new folder. This must be unique within
342: * the layout to avoid collision with other parts.
343: * @param relationship the position relative to the reference part;
344: * one of <code>TOP</code>, <code>BOTTOM</code>, <code>LEFT</code>,
345: * or <code>RIGHT</code>
346: * @param ratio a ratio specifying how to divide the space currently occupied by the reference part,
347: * in the range <code>0.05f</code> to <code>0.95f</code>.
348: * Values outside this range will be clipped to facilitate direct manipulation.
349: * For a vertical split, the part on top gets the specified ratio of the current space
350: * and the part on bottom gets the rest.
351: * Likewise, for a horizontal split, the part at left gets the specified ratio of the current space
352: * and the part at right gets the rest.
353: * @param refId the id of the reference part; either a view id, a folder id,
354: * or the special editor area id returned by <code>getEditorArea</code>
355: * @return a placeholder for the new folder
356: * @since 2.0
357: */
358: public IPlaceholderFolderLayout createPlaceholderFolder(
359: String folderId, int relationship, float ratio, String refId);
360:
361: /**
362: * Returns the special identifier for the editor area in this page
363: * layout. The identifier for the editor area is also stored in
364: * <code>ID_EDITOR_AREA</code>.
365: * <p>
366: * The editor area is automatically added to each layout before anything else.
367: * It should be used as the point of reference when adding views to a layout.
368: * </p>
369: *
370: * @return the special id of the editor area
371: */
372: public String getEditorArea();
373:
374: /**
375: * Returns whether the page's layout will show
376: * the editor area.
377: *
378: * @return <code>true</code> when editor area visible, <code>false</code> otherwise
379: */
380: public boolean isEditorAreaVisible();
381:
382: /**
383: * Show or hide the editor area for the page's layout.
384: *
385: * @param showEditorArea <code>true</code> to show the editor area, <code>false</code> to hide the editor area
386: */
387: public void setEditorAreaVisible(boolean showEditorArea);
388:
389: /**
390: * Returns the number of open editors before reusing editors or -1 if the
391: * preference settings should be used instead.
392: *
393: * @return the number of open editors before reusing editors or -1 if the
394: * preference settings should be used instead.
395: *
396: * @deprecated this always returns -1 as of Eclipse 2.1
397: */
398: public int getEditorReuseThreshold();
399:
400: /**
401: * Sets the number of open editors before reusing editors.
402: * If < 0 the user preference settings will be used.
403: *
404: * @param openEditors the number of open editors
405: *
406: * @deprecated this method has no effect, as of Eclipse 2.1
407: */
408: public void setEditorReuseThreshold(int openEditors);
409:
410: /**
411: * Sets whether this layout is fixed.
412: * In a fixed layout, layout parts cannot be moved or zoomed, and the initial
413: * set of views cannot be closed.
414: *
415: * @param isFixed <code>true</code> if this layout is fixed, <code>false</code> if not
416: * @since 3.0
417: */
418: public void setFixed(boolean isFixed);
419:
420: /**
421: * Returns <code>true</code> if this layout is fixed, <code>false</code> if not.
422: * In a fixed layout, layout parts cannot be moved or zoomed, and the initial
423: * set of views cannot be closed.
424: * The default is <code>false</code>.
425: *
426: * @return <code>true</code> if this layout is fixed, <code>false</code> if not.
427: * @since 3.0
428: */
429: public boolean isFixed();
430:
431: /**
432: * Returns the layout for the view or placeholder with the given compound id in
433: * this page layout.
434: * See the {@link IPageLayout} type documentation for more details about compound ids.
435: * Returns <code>null</code> if the specified view or placeholder is unknown to the layout.
436: *
437: * @param id the compound view id or placeholder
438: * @return the view layout, or <code>null</code>
439: * @since 3.0
440: */
441: public IViewLayout getViewLayout(String id);
442:
443: /**
444: * Adds a standalone view with the given compound id to this page layout.
445: * See the {@link IPageLayout} type documentation for more details about compound ids.
446: * A standalone view cannot be docked together with other views.
447: * A standalone view's title can optionally be hidden. If hidden,
448: * then any controls typically shown with the title (such as the close button)
449: * are also hidden. Any contributions or other content from the view itself
450: * are always shown (e.g. toolbar or view menu contributions, content description).
451: * <p>
452: * The id must name a view contributed to the workbench's view extension point
453: * (named <code>"org.eclipse.ui.views"</code>).
454: * </p>
455: *
456: * @param viewId the compound view id
457: * @param showTitle <code>true</code> to show the title and related controls,
458: * <code>false</code> to hide them
459: * @param relationship the position relative to the reference part;
460: * one of <code>TOP</code>, <code>BOTTOM</code>, <code>LEFT</code>,
461: * or <code>RIGHT</code>
462: * @param ratio a ratio specifying how to divide the space currently occupied by the reference part,
463: * in the range <code>0.05f</code> to <code>0.95f</code>.
464: * Values outside this range will be clipped to facilitate direct manipulation.
465: * For a vertical split, the part on top gets the specified ratio of the current space
466: * and the part on bottom gets the rest.
467: * Likewise, for a horizontal split, the part at left gets the specified ratio of the current space
468: * and the part at right gets the rest.
469: * @param refId the id of the reference part; either a view id, a folder id,
470: * or the special editor area id returned by <code>getEditorArea</code>
471: *
472: * @since 3.0
473: */
474: public void addStandaloneView(String viewId, boolean showTitle,
475: int relationship, float ratio, String refId);
476:
477: /**
478: * Adds a standalone view placeholder to this page layout. A view
479: * placeholder is used to define the position of a view before the view
480: * appears. Initially, it is invisible; however, if the user ever opens a
481: * view whose compound id matches the placeholder, the view will appear at
482: * the same location as the placeholder. See the {@link IPageLayout} type
483: * documentation for more details about compound ids. If the placeholder
484: * contains wildcards, it remains in the layout, otherwise it is replaced by
485: * the view. If the primary id of the placeholder has no wildcards, it must
486: * refer to a view contributed to the workbench's view extension point
487: * (named <code>"org.eclipse.ui.views"</code>).
488: *
489: * @param viewId
490: * the compound view id (wildcards allowed)
491: * @param relationship
492: * the position relative to the reference part; one of
493: * <code>TOP</code>, <code>BOTTOM</code>, <code>LEFT</code>,
494: * or <code>RIGHT</code>
495: * @param ratio
496: * a ratio specifying how to divide the space currently occupied
497: * by the reference part, in the range <code>0.05f</code> to
498: * <code>0.95f</code>. Values outside this range will be
499: * clipped to facilitate direct manipulation. For a vertical
500: * split, the part on top gets the specified ratio of the current
501: * space and the part on bottom gets the rest. Likewise, for a
502: * horizontal split, the part at left gets the specified ratio of
503: * the current space and the part at right gets the rest.
504: * @param refId
505: * the id of the reference part; either a view id, a folder id,
506: * or the special editor area id returned by
507: * <code>getEditorArea</code>
508: * @param showTitle
509: * true to show the view's title, false if not
510: *
511: * @since 3.2
512: */
513: public void addStandaloneViewPlaceholder(String viewId,
514: int relationship, float ratio, String refId,
515: boolean showTitle);
516:
517: /**
518: * Returns the perspective descriptor for the perspective being layed out.
519: *
520: * @return the perspective descriptor for the perspective being layed out
521: * @since 3.2
522: */
523: public IPerspectiveDescriptor getDescriptor();
524:
525: /**
526: * Returns the folder layout for the view or placeholder with the given
527: * compound id in this page layout. See the {@link IPageLayout} type
528: * documentation for more details about compound ids. Returns
529: * <code>null</code> if the specified view or placeholder is unknown to
530: * the layout, or the placeholder was not in a folder.
531: *
532: * @param id
533: * the compound view id or placeholder. Must not be
534: * <code>null</code>.
535: * @return the folder layout, or <code>null</code>
536: * @since 3.3
537: */
538: public IPlaceholderFolderLayout getFolderForView(String id);
539: }
|