IPageLayout


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