KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc viewId, int relationship, float ratio,
266             String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc viewId, int relationship, float ratio,
311             String JavaDoc 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 JavaDoc folderId, int relationship,
335             float ratio, String JavaDoc 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 JavaDoc folderId,
360             int relationship, float ratio, String JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc viewId, boolean showTitle,
476             int relationship, float ratio, String JavaDoc 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 JavaDoc viewId, int relationship,
515             float ratio, String JavaDoc 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 JavaDoc id);
540 }
541
Popular Tags