Java > Open Source Codes > org > eclipse > ui > IWorkbenchPage


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  *******************************************************************************/
11 package org.eclipse.ui;
12
13 import org.eclipse.core.runtime.IAdaptable;
14 import org.eclipse.core.runtime.dynamichelpers.IExtensionTracker;
15 import org.eclipse.jface.util.IPropertyChangeListener;
16 import org.eclipse.ui.internal.ICompatibleWorkbenchPage;
17 import org.eclipse.ui.presentations.IStackPresentationSite;
18
19 /**
20  * A workbench page consists of an arrangement of views and editors intended to
21  * be presented together to the user in a single workbench window.
22  * <p>
23  * A page can contain 0 or more views and 0 or more editors. These views and
24  * editors are contained wholly within the page and are not shared with other
25  * pages. The layout and visible action set for the page is defined by a
26  * perspective.
27  * <p>
28  * The number of views and editors within a page is restricted to simplify part
29  * management for the user. In particular:
30  * <ul>
31  * <li>Unless a view explicitly allows for multiple instances in its plugin
32  * declaration there will be only one instance in a given workbench page.</li>
33  * <li>Only one editor can exist for each editor input within a page.
34  * <li>
35  * </ul>
36  * </p>
37  * <p>
38  * This interface is not intended to be implemented by clients.
39  * </p>
40  *
41  * @see IPerspectiveDescriptor
42  * @see IEditorPart
43  * @see IViewPart
44  */
45 public interface IWorkbenchPage extends IPartService, ISelectionService,
46         ICompatibleWorkbenchPage {
47     /**
48      * An optional attribute within a workspace marker (<code>IMarker</code>)
49      * which identifies the preferred editor type to be opened when
50      * <code>openEditor</code> is called.
51      *
52      * @see #openEditor(IEditorInput, String)
53      * @see #openEditor(IEditorInput, String, boolean)
54      * @deprecated in 3.0 since the notion of markers this is not generally
55      * applicable. Use the IDE-specific constant
56      * <code>IDE.EDITOR_ID_ATTR</code>.
57      */
58     public static final String EDITOR_ID_ATTR = "org.eclipse.ui.editorID"; //$NON-NLS-1$
59
60     /**
61      * Change event id when the perspective is reset to its original state.
62      *
63      * @see IPerspectiveListener
64      */
65     public static final String CHANGE_RESET = "reset"; //$NON-NLS-1$
66
67     /**
68      * Change event id when the perspective has completed a reset to its
69      * original state.
70      *
71      * @since 3.0
72      * @see IPerspectiveListener
73      */
74     public static final String CHANGE_RESET_COMPLETE = "resetComplete"; //$NON-NLS-1$
75
76     /**
77      * Change event id when one or more views are shown in a perspective.
78      *
79      * @see IPerspectiveListener
80      */
81     public static final String CHANGE_VIEW_SHOW = "viewShow"; //$NON-NLS-1$
82
83     /**
84      * Change event id when one or more views are hidden in a perspective.
85      *
86      * @see IPerspectiveListener
87      */
88     public static final String CHANGE_VIEW_HIDE = "viewHide"; //$NON-NLS-1$
89
90     /**
91      * Change event id when one or more editors are opened in a perspective.
92      *
93      * @see IPerspectiveListener
94      */
95     public static final String CHANGE_EDITOR_OPEN = "editorOpen"; //$NON-NLS-1$
96
97     /**
98      * Change event id when one or more editors are closed in a perspective.
99      *
100      * @see IPerspectiveListener
101      */
102     public static final String CHANGE_EDITOR_CLOSE = "editorClose"; //$NON-NLS-1$
103
104     /**
105      * Change event id when the editor area is shown in a perspective.
106      *
107      * @see IPerspectiveListener
108      */
109     public static final String CHANGE_EDITOR_AREA_SHOW = "editorAreaShow"; //$NON-NLS-1$
110
111     /**
112      * Change event id when the editor area is hidden in a perspective.
113      *
114      * @see IPerspectiveListener
115      */
116     public static final String CHANGE_EDITOR_AREA_HIDE = "editorAreaHide"; //$NON-NLS-1$
117
118     /**
119      * Change event id when an action set is shown in a perspective.
120      *
121      * @see IPerspectiveListener
122      */
123     public static final String CHANGE_ACTION_SET_SHOW = "actionSetShow"; //$NON-NLS-1$
124
125     /**
126      * Change event id when an action set is hidden in a perspective.
127      *
128      * @see IPerspectiveListener
129      */
130     public static final String CHANGE_ACTION_SET_HIDE = "actionSetHide"; //$NON-NLS-1$
131
132     /**
133      * Change event id when a fast view is added in a perspective.
134      *
135      * @see IPerspectiveListener
136      */
137     public static final String CHANGE_FAST_VIEW_ADD = "fastViewAdd"; //$NON-NLS-1$
138
139     /**
140      * Change event id when a fast view is removed in a perspective.
141      *
142      * @see IPerspectiveListener
143      */
144     public static final String CHANGE_FAST_VIEW_REMOVE = "fastViewRemove"; //$NON-NLS-1$
145
146     /**
147      * Change event id when the page working set was replaced
148      *
149      * @see IPropertyChangeListener
150      */
151     public static final String CHANGE_WORKING_SET_REPLACE = "workingSetReplace"; //$NON-NLS-1$
152
153     /**
154      * Change event id when the page working set list was replaced
155      *
156      * @see IPropertyChangeListener
157      * @since 3.2
158      */
159     public static final String CHANGE_WORKING_SETS_REPLACE = "workingSetsReplace"; //$NON-NLS-1$
160
161     /**
162      * Show view mode that indicates the view should be made visible and
163      * activated. Use of this mode has the same effect as calling
164      * {@link #showView(String)}.
165      *
166      * @since 3.0
167      */
168     public static final int VIEW_ACTIVATE = 1;
169
170     /**
171      * Show view mode that indicates the view should be made visible. If the
172      * view is opened in the container that contains the active view then this
173      * has the same effect as <code>VIEW_CREATE</code>.
174      *
175      * @since 3.0
176      */
177     public static final int VIEW_VISIBLE = 2;
178
179     /**
180      * Show view mode that indicates the view should be made created but not
181      * necessarily be made visible. It will only be made visible in the event
182      * that it is opened in its own container. In other words, only if it is not
183      * stacked with another view.
184      *
185      * @since 3.0
186      */
187     public static final int VIEW_CREATE = 3;
188
189     /**
190      * Editor opening match mode specifying that no matching against existing
191      * editors should be done.
192      *
193      * @since 3.2
194      */
195     public static final int MATCH_NONE = 0;
196
197     /**
198      * Editor opening match mode specifying that the editor input should be
199      * considered when matching against existing editors.
200      *
201      * @since 3.2
202      */
203     public static final int MATCH_INPUT = 1;
204
205     /**
206      * Editor opening match mode specifying that the editor id should be
207      * considered when matching against existing editors.
208      *
209      * @since 3.2
210      */
211     public static final int MATCH_ID = 2;
212
213     /**
214      * State of a view in a given page when the view stack is minimized.
215      *
216      * @since 3.2
217      */
218     public static final int STATE_MINIMIZED = IStackPresentationSite.STATE_MINIMIZED;
219
220     /**
221      * State of a view in a given page when the page is zoomed in on the view
222      * stack.
223      *
224      * @since 3.2
225      */
226     public static final int STATE_MAXIMIZED = IStackPresentationSite.STATE_MAXIMIZED;
227
228     /**
229      * State of a view in a given page when the view stack is in it's normal
230      * state.
231      *
232      * @since 3.2
233      */
234     public static final int STATE_RESTORED = IStackPresentationSite.STATE_RESTORED;
235
236     /**
237      * Activates the given part. The part will be brought to the front and given
238      * focus. The part must belong to this page.
239      *
240      * @param part
241      * the part to activate
242      */
243     public void activate(IWorkbenchPart part);
244
245     /**
246      * Adds a property change listener.
247      *
248      * @param listener
249      * the property change listener to add
250      * @since 2.0
251      */
252     public void addPropertyChangeListener(IPropertyChangeListener listener);
253
254     /**
255      * Moves the given part forward in the Z order of this page so as to make it
256      * visible, without changing which part has focus. The part must belong to
257      * this page.
258      *
259      * @param part
260      * the part to bring forward
261      */
262     public void bringToTop(IWorkbenchPart part);
263
264     /**
265      * Closes this workbench page. If this page is the active one, this honor is
266      * passed along to one of the window's other pages if possible.
267      * <p>
268      * If the page has an open editor with unsaved content, the user will be
269      * given the opportunity to save it.
270      * </p>
271      *
272      * @return <code>true</code> if the page was successfully closed, and
273      * <code>false</code> if it is still open
274      */
275     public boolean close();
276
277     /**
278      * Closes all of the editors belonging to this workbench page.
279      * <p>
280      * If the page has open editors with unsaved content and <code>save</code>
281      * is <code>true</code>, the user will be given the opportunity to save
282      * them.
283      * </p>
284      *
285      * @param save
286      *
287      * @return <code>true</code> if all editors were successfully closed, and
288      * <code>false</code> if at least one is still open
289      */
290     public boolean closeAllEditors(boolean save);
291
292     /**
293      * Closes the given <code>Array</code> of editor references. The editors
294      * must belong to this workbench page.
295      * <p>
296      * If any of the editors have unsaved content and <code>save</code> is
297      * <code>true</code>, the user will be given the opportunity to save
298      * them.
299      * </p>
300      *
301      * @param editorRefs
302      * the editors to close
303      * @param save
304      * <code>true</code> to save the editor contents if required
305      * (recommended), and <code>false</code> to discard any unsaved
306      * changes
307      * @return <code>true</code> if the editors were successfully closed, and
308      * <code>false</code> if the editors are still open
309      * @since 3.0
310      */
311     public boolean closeEditors(IEditorReference[] editorRefs, boolean save);
312
313     /**
314      * Closes the given editor. The editor must belong to this workbench page.
315      * <p>
316      * If the editor has unsaved content and <code>save</code> is
317      * <code>true</code>, the user will be given the opportunity to save it.
318      * </p>
319      *
320      * @param editor
321      * the editor to close
322      * @param save
323      * <code>true</code> to save the editor contents if required
324      * (recommended), and <code>false</code> to discard any unsaved
325      * changes
326      * @return <code>true</code> if the editor was successfully closed, and
327      * <code>false</code> if the editor is still open
328      */
329     public boolean closeEditor(IEditorPart editor, boolean save);
330
331     /**
332      * Returns the view in this page with the specified id. There is at most one
333      * view in the page with the specified id.
334      *
335      * @param viewId
336      * the id of the view extension to use
337      * @return the view, or <code>null</code> if none is found
338      */
339     public IViewPart findView(String viewId);
340
341     /**
342      * Returns the view reference with the specified id.
343      *
344      * @param viewId
345      * the id of the view extension to use
346      * @return the view reference, or <code>null</code> if none is found
347      * @since 3.0
348      */
349     public IViewReference findViewReference(String viewId);
350
351     /**
352      * Returns the view reference with the specified id and secondary id.
353      *
354      * @param viewId
355      * the id of the view extension to use
356      * @param secondaryId
357      * the secondary id to use, or <code>null</code> for no
358      * secondary id
359      * @return the view reference, or <code>null</code> if none is found
360      * @since 3.0
361      */
362     public IViewReference findViewReference(String viewId, String secondaryId);
363
364     /**
365      * Returns the active editor open in this page.
366      * <p>
367      * This is the visible editor on the page, or, if there is more than one
368      * visible editor, this is the one most recently brought to top.
369      * </p>
370      *
371      * @return the active editor, or <code>null</code> if no editor is active
372      */
373     public IEditorPart getActiveEditor();
374
375     /**
376      * Returns the editor with the specified input. Returns null if there is no
377      * opened editor with that input.
378      *
379      * @param input
380      * the editor input
381      * @return an editor with input equals to <code>input</code>
382      */
383     public IEditorPart findEditor(IEditorInput input);
384
385     /**
386      * Returns an array of editor references that match the given input and/or
387      * editor id, as specified by the given match flags. Returns an empty array
388      * if there are no matching editors, or if matchFlags is MATCH_NONE.
389      *
390      * @param input
391      * the editor input, or <code>null</code> if MATCH_INPUT is not
392      * specified in matchFlags
393      * @param editorId
394      * the editor id, or <code>null</code> if MATCH_ID is not
395      * specified in matchFlags
396      * @param matchFlags
397      * a bit mask consisting of zero or more of the MATCH_* constants
398      * OR-ed together
399      * @return the references for the matching editors
400      *
401      * @see #MATCH_NONE
402      * @see #MATCH_INPUT
403      * @see #MATCH_ID
404      * @since 3.2
405      */
406     public IEditorReference[] findEditors(IEditorInput input, String editorId,
407             int matchFlags);
408
409     /**
410      * Returns a list of the editors open in this page.
411      * <p>
412      * Note that each page has its own editors; editors are never shared between
413      * pages.
414      * </p>
415      *
416      * @return a list of open editors
417      *
418      * @deprecated use #getEditorReferences() instead
419      */
420     public IEditorPart[] getEditors();
421
422     /**
423      * Returns an array of references to open editors in this page.
424      * <p>
425      * Note that each page has its own editors; editors are never shared between
426      * pages.
427      * </p>
428      *
429      * @return a list of open editors
430      */
431     public IEditorReference[] getEditorReferences();
432
433     /**
434      * Returns a list of dirty editors in this page.
435      *
436      * @return a list of dirty editors
437      */
438     public IEditorPart[] getDirtyEditors();
439
440     /**
441      * Returns the input for this page.
442      *
443      * @return the input for this page, or <code>null</code> if none
444      */
445     public IAdaptable getInput();
446
447     /**
448      * Returns the page label. This will be a unique identifier within the
449      * containing workbench window.
450      *
451      * @return the page label
452      */
453     public String getLabel();
454
455     /**
456      * Returns the current perspective descriptor for this page, or
457      * <code>null</code> if there is no current perspective.
458      *
459      * @return the current perspective descriptor or <code>null</code>
460      * @see #setPerspective
461      * @see #savePerspective
462      */
463     public IPerspectiveDescriptor getPerspective();
464
465     /**
466      * Returns a list of the reference to views visible on this page.
467      * <p>
468      * Note that each page has its own views; views are never shared between
469      * pages.
470      * </p>
471      *
472      * @return a list of references to visible views
473      */
474     public IViewReference[] getViewReferences();
475
476     /**
477      * Returns a list of the views visible on this page.
478      * <p>
479      * Note that each page has its own views; views are never shared between
480      * pages.
481      * </p>
482      *
483      * @return a list of visible views
484      *
485      * @deprecated use #getViewReferences() instead.
486      */
487     public IViewPart[] getViews();
488
489     /**
490      * Returns the workbench window of this page.
491      *
492      * @return the workbench window
493      */
494     public IWorkbenchWindow getWorkbenchWindow();
495
496     /**
497      * Returns the working set of this page.
498      *
499      * @return the working set of this page.
500      * @since 2.0
501      * @deprecated individual views should store a working set if needed
502      */
503     public IWorkingSet getWorkingSet();
504
505     /**
506      * Hides an action set in this page.
507      * <p>
508      * In most cases where this method is used the caller is tightly coupled to
509      * a particular action set. They define it in the registry and may make it
510      * visible in certain scenarios by calling <code>showActionSet</code>. A
511      * static variable is often used to identify the action set id in caller
512      * code.
513      * </p>
514      *
515      * @param actionSetID
516      * the action set to hide
517      */
518     public void hideActionSet(String actionSetID);
519
520     /**
521      * Hides the given view. The view must belong to this page.
522      *
523      * @param view
524      * the view to hide
525      */
526     public void hideView(IViewPart view);
527
528     /**
529      * Hides the given view that belongs to the reference, if any.
530      *
531      * @param view
532      * the references whos view is to be hidden
533      * @since 3.0
534      */
535     public void hideView(IViewReference view);
536
537     /**
538      * Returns whether the specified part is visible.
539      *
540      * @param part
541      * the part to test
542      * @return boolean <code>true</code> if part is visible
543      */
544     public boolean isPartVisible(IWorkbenchPart part);
545
546     /**
547      * Returns whether the page's current perspective is showing the editor
548      * area.
549      *
550      * @return <code>true</code> when editor area visible, <code>false</code>
551      * otherwise
552      */
553     public boolean isEditorAreaVisible();
554
555     /**
556      * Reuses the specified editor by setting its new input.
557      *
558      * @param editor
559      * the editor to be reused
560      * @param input
561      * the new input for the reusable editor
562      */
563     public void reuseEditor(IReusableEditor editor, IEditorInput input);
564
565     /**
566      * Opens an editor on the given input.
567      * <p>
568      * If this page already has an editor open on the target input that editor
569      * is activated; otherwise, a new editor is opened. Two editor inputs,
570      * input1 and input2, are considered the same if
571      *
572      * <pre>
573      * input1.equals(input2) == true
574      * </pre>.
575      * </p>
576      * <p>
577      * The editor type is determined by mapping <code>editorId</code> to an
578      * editor extension registered with the workbench. An editor id is passed
579      * rather than an editor object to prevent the accidental creation of more
580      * than one editor for the same input. It also guarantees a consistent
581      * lifecycle for editors, regardless of whether they are created by the user
582      * or restored from saved data.
583      * </p>
584      *
585      * @param input
586      * the editor input
587      * @param editorId
588      * the id of the editor extension to use
589      * @return an open and active editor, or <code>null</code> if an external
590      * editor was opened
591      * @exception PartInitException
592      * if the editor could not be created or initialized
593      */
594     public IEditorPart openEditor(IEditorInput input, String editorId)
595             throws PartInitException;
596
597     /**
598      * Opens an editor on the given input.
599      * <p>
600      * If this page already has an editor open on the target input that editor
601      * is brought to the front; otherwise, a new editor is opened. Two editor
602      * inputs are considered the same if they equal. See
603      * <code>Object.equals(Object)<code>
604      * and <code>IEditorInput</code>. If <code>activate == true</code> the editor
605      * will be activated.
606      * </p><p>
607      * The editor type is determined by mapping <code>editorId</code> to an editor
608      * extension registered with the workbench. An editor id is passed rather than
609      * an editor object to prevent the accidental creation of more than one editor
610      * for the same input. It also guarantees a consistent lifecycle for editors,
611      * regardless of whether they are created by the user or restored from saved
612      * data.
613      * </p>
614      *
615      * @param input the editor input
616      * @param editorId the id of the editor extension to use
617      * @param activate if <code>true</code> the editor will be activated
618      * @return an open editor, or <code>null</code> if an external editor was opened
619      * @exception PartInitException if the editor could not be created or initialized
620      */
621     public IEditorPart openEditor(IEditorInput input, String editorId,
622             boolean activate) throws PartInitException;
623
624     /**
625      * Opens an editor on the given input.
626      * <p>
627      * If this page already has an editor open that matches the given input
628      * and/or editor id (as specified by the matchFlags argument), that editor
629      * is brought to the front; otherwise, a new editor is opened. Two editor
630      * inputs are considered the same if they equal. See
631      * <code>Object.equals(Object)<code>
632      * and <code>IEditorInput</code>. If <code>activate == true</code> the editor
633      * will be activated.
634      * </p><p>
635      * The editor type is determined by mapping <code>editorId</code> to an editor
636      * extension registered with the workbench. An editor id is passed rather than
637      * an editor object to prevent the accidental creation of more than one editor
638      * for the same input. It also guarantees a consistent lifecycle for editors,
639      * regardless of whether they are created by the user or restored from saved
640      * data.
641      * </p>
642      *
643      * @param input the editor input
644      * @param editorId the id of the editor extension to use
645      * @param activate if <code>true</code> the editor will be activated
646      * @param matchFlags a bit mask consisting of zero or more of the MATCH_* constants OR-ed together
647      * @return an open editor, or <code>null</code> if an external editor was opened
648      * @exception PartInitException if the editor could not be created or initialized
649      *
650      * @see #MATCH_NONE
651      * @see #MATCH_INPUT
652      * @see #MATCH_ID
653      * @since 3.2
654      */
655     public IEditorPart openEditor(final IEditorInput input,
656             final String editorId, final boolean activate, final int matchFlags)
657             throws PartInitException;
658
659     /**
660      * Removes the property change listener.
661      *
662      * @param listener
663      * the property change listener to remove
664      * @since 2.0
665      */
666     public void removePropertyChangeListener(IPropertyChangeListener listener);
667
668     /**
669      * Changes the visible views, their layout, and the visible action sets
670      * within the page to match the current perspective descriptor. This is a
671      * rearrangement of components and not a replacement. The contents of the
672      * current perspective descriptor are unaffected.
673      * <p>
674      * For more information on perspective change see
675      * <code>setPerspective()</code>.
676      * </p>
677      */
678     public void resetPerspective();
679
680     /**
681      * Saves the contents of all dirty editors belonging to this workbench page.
682      * If there are no dirty editors this method returns without effect.
683      * <p>
684      * If <code>confirm</code> is <code>true</code> the user is prompted to
685      * confirm the command.
686      * </p>
687      * <p>
688      * Note that as of 3.2, this method also saves views that implement
689      * ISaveablePart and are dirty.
690      * </p>
691      *
692      * @param confirm <code>true</code> to ask the user before saving unsaved
693      * changes (recommended), and <code>false</code> to save
694      * unsaved changes without asking
695      * @return <code>true</code> if the command succeeded, and
696      * <code>false</code> if the operation was canceled by the user or
697      * an error occurred while saving
698      */
699     public boolean saveAllEditors(boolean confirm);
700
701     /**
702      * Saves the contents of the given editor if dirty. If not, this method
703      * returns without effect.
704      * <p>
705      * If <code>confirm</code> is <code>true</code> the user is prompted to
706      * confirm the command. Otherwise, the save happens without prompt.
707      * </p>
708      * <p>
709      * The editor must belong to this workbench page.
710      * </p>
711      *
712      * @param editor
713      * the editor to close
714      * @param confirm
715      * <code>true</code> to ask the user before saving unsaved
716      * changes (recommended), and <code>false</code> to save
717      * unsaved changes without asking
718      * @return <code>true</code> if the command succeeded, and
719      * <code>false</code> if the editor was not saved
720      */
721     public boolean saveEditor(IEditorPart editor, boolean confirm);
722
723     /**
724      * Saves the visible views, their layout, and the visible action sets for
725      * this page to the current perspective descriptor. The contents of the
726      * current perspective descriptor are overwritten.
727      */
728     public void savePerspective();
729
730     /**
731      * Saves the visible views, their layout, and the visible action sets for
732      * this page to the given perspective descriptor. The contents of the given
733      * perspective descriptor are overwritten and it is made the current one for
734      * this page.
735      *
736      * @param perspective
737      * the perspective descriptor to save to
738      */
739     public void savePerspectiveAs(IPerspectiveDescriptor perspective);
740
741     /**
742      * Show or hide the editor area for the page's active perspective.
743      *
744      * @param showEditorArea
745      * <code>true</code> to show the editor area,
746      * <code>false</code> to hide the editor area
747      */
748     public void setEditorAreaVisible(boolean showEditorArea);
749
750     /**
751      * Changes the visible views, their layout, and the visible action sets
752      * within the page to match the given perspective descriptor. This is a
753      * rearrangement of components and not a replacement. The contents of the
754      * old perspective descriptor are unaffected.
755      * <p>
756      * When a perspective change occurs the old perspective is deactivated
757      * (hidden) and cached for future reference. Then the new perspective is
758      * activated (shown). The views within the page are shared by all existing
759      * perspectives to make it easy for the user to switch between one
760      * perspective and another quickly without loss of context.
761      * </p>
762      * <p>
763      * During activation the action sets are modified. If an action set is
764      * specified in the new perspective which is not visible in the old one it
765      * will be created. If an old action set is not specified in the new
766      * perspective it will be disposed.
767      * </p>
768      * <p>
769      * The visible views and their layout within the page also change. If a view
770      * is specified in the new perspective which is not visible in the old one a
771      * new instance of the view will be created. If an old view is not specified
772      * in the new perspective it will be hidden. This view may reappear if the
773      * user selects it from the View menu or if they switch to a perspective
774      * (which may be the old one) where the view is visible.
775      * </p>
776      * <p>
777      * The open editors are not modified by this method.
778      * </p>
779      *
780      * @param perspective
781      * the perspective descriptor
782      */
783     public void setPerspective(IPerspectiveDescriptor perspective);
784
785     /**
786      * Shows an action set in this page.
787      * <p>
788      * In most cases where this method is used the caller is tightly coupled to
789      * a particular action set. They define it in the registry and may make it
790      * visible in certain scenarios by calling <code>showActionSet</code>. A
791      * static variable is often used to identify the action set id in caller
792      * code.
793      * </p>
794      *
795      * @param actionSetID
796      * the action set to show
797      */
798     public void showActionSet(String actionSetID);
799
800     /**
801      * Shows the view identified by the given view id in this page and gives it
802      * focus. If there is a view identified by the given view id (and with no
803      * secondary id) already open in this page, it is given focus.
804      *
805      * @param viewId
806      * the id of the view extension to use
807      * @return the shown view
808      * @exception PartInitException
809      * if the view could not be initialized
810      */
811     public IViewPart showView(String viewId) throws PartInitException;
812
813     /**
814      * Shows a view in this page with the given id and secondary id. The
815      * behaviour of this method varies based on the supplied mode. If
816      * <code>VIEW_ACTIVATE</code> is supplied, the view is focus. If
817      * <code>VIEW_VISIBLE</code> is supplied, then it is made visible but not
818      * given focus. Finally, if <code>VIEW_CREATE</code> is supplied the view
819      * is created and will only be made visible if it is not created in a folder
820      * that already contains visible views.
821      * <p>
822      * This allows multiple instances of a particular view to be created. They
823      * are disambiguated using the secondary id. If a secondary id is given, the
824      * view must allow multiple instances by having specified
825      * allowMultiple="true" in its extension.
826      * </p>
827      *
828      * @param viewId
829      * the id of the view extension to use
830      * @param secondaryId
831      * the secondary id to use, or <code>null</code> for no
832      * secondary id
833      * @param mode
834      * the activation mode. Must be {@link #VIEW_ACTIVATE},
835      * {@link #VIEW_VISIBLE} or {@link #VIEW_CREATE}
836      * @return a view
837      * @exception PartInitException
838      * if the view could not be initialized
839      * @exception IllegalArgumentException
840      * if the supplied mode is not valid
841      * @since 3.0
842      */
843     public IViewPart showView(String viewId, String secondaryId, int mode)
844             throws PartInitException;
845
846     /**
847      * Returns <code>true</code> if the editor is pinned and should not be
848      * reused.
849      *
850      * @param editor
851      * the editor to test
852      * @return boolean whether the editor is pinned
853      */
854     public boolean isEditorPinned(IEditorPart editor);
855
856     /**
857      * Returns the number of open editors before reusing editors.
858      *
859      * @return a int
860      *
861      * @deprecated
862      */
863     public int getEditorReuseThreshold();
864
865     /**
866      * Set the number of open editors before reusing editors. If < 0 the user
867      * preference settings will be used.
868      *
869      * @param openEditors
870      * the threshold
871      * @deprecated use IPageLayout.setEditorReuseThreshold(int openEditors)
872      * instead.
873      */
874     public void setEditorReuseThreshold(int openEditors);
875
876     /**
877      * Returns the navigation history which manages a list of entries keeping
878      * the history of places (positions, selection and editors) the user visited
879      * making it easier to the user to move back and forward without losing
880      * context.
881      *
882      * @return the navigation history
883      * @since 2.1
884      */
885     public INavigationHistory getNavigationHistory();
886
887     /**
888      * Returns an array of IViewParts that are stacked with the given part.
889      *
890      * @param part
891      * the part to test
892      * @return the parts that are stacked with this part, including the part in
893      * question. <code>null</code> is returned if the part does not
894      * belong to this page.
895      * @since 3.0
896      */
897     IViewPart[] getViewStack(IViewPart part);
898
899     /**
900      * Returns the new wizard shortcuts associated with the current perspective.
901      * Returns an empty array if there is no current perspective.
902      *
903      * @see IPageLayout#addNewWizardShortcut(String)
904      * @return an array of wizard identifiers
905      * @since 3.1
906      */
907     public String [] getNewWizardShortcuts();
908
909     /**
910      * Returns the perspective shortcuts associated with the current
911      * perspective. Returns an empty array if there is no current perspective.
912      *
913      * @see IPageLayout#addPerspectiveShortcut(String)
914      * @return an array of perspective identifiers
915      * @since 3.1
916      */
917     public String [] getPerspectiveShortcuts();
918
919     /**
920      * Returns the show view shortcuts associated with the current perspective.
921      * Returns an empty array if there is no current perspective.
922      *
923      * @see IPageLayout#addShowViewShortcut(String)
924      * @return an array of view identifiers
925      * @since 3.1
926      */
927     public String [] getShowViewShortcuts();
928
929     /**
930      * Returns the descriptors for the perspectives that are open in this page,
931      * in the order in which they were opened.
932      *
933      * @return the open perspective descriptors, in order of opening
934      * @since 3.1
935      */
936     public IPerspectiveDescriptor[] getOpenPerspectives();
937
938     /**
939      * Returns the descriptors for the perspectives that are open in this page,
940      * in the order in which they were activated (oldest first).
941      *
942      * @return the open perspective descriptors, in order of activation
943      * @since 3.1
944      */
945     public IPerspectiveDescriptor[] getSortedPerspectives();
946
947     /**
948      * Closes the specified perspective in this page. If the last perspective in
949      * this page is closed, then all editors are closed. Views that are not
950      * shown in other perspectives are closed as well. If <code>saveParts</code>
951      * is <code>true</code>, the user will be prompted to save any unsaved
952      * changes for parts that are being closed. The page itself is closed if
953      * <code>closePage</code> is <code>true</code>.
954      *
955      * @param desc
956      * the descriptor of the perspective to be closed
957      * @param saveParts
958      * whether the page's parts should be saved if closed
959      * @param closePage
960      * whether the page itself should be closed if last perspective
961      * @since 3.1
962      */
963     public void closePerspective(IPerspectiveDescriptor desc,
964             boolean saveParts, boolean closePage);
965
966     /**
967      * Closes all perspectives in this page. All editors are closed, prompting
968      * to save any unsaved changes if <code>saveEditors</code> is
969      * <code>true</code>. The page itself is closed if <code>closePage</code>
970      * is <code>true</code>.
971      *
972      * @param saveEditors
973      * whether the page's editors should be saved
974      * @param closePage
975      * whether the page itself should be closed
976      * @since 3.1
977      */
978     public void closeAllPerspectives(boolean saveEditors, boolean closePage);
979
980     /**
981      * <p>
982      * Return the extension tracker for the workbench. This tracker may be used
983      * by plug-ins to ensure responsiveness to changes to the plug-in registry.
984      * </p>
985      * <p>
986      * The tracker at this level of the workbench is typically used to track
987      * elements that only exist over the lifespan of a page. For example,
988      * <code>ViewPart</code> objects fall into this category.
989      * </p>
990      *
991      * @return the extension tracker
992      * @see IWorkbench#getExtensionTracker()
993      * @see IWorkbenchWindow#getExtensionTracker()
994      * @since 3.1
995      */
996     public IExtensionTracker getExtensionTracker();
997
998     /**
999      * Return the visible working sets for this page. Please note that this
1000     * array is not filtered by activities. Clients should attempt to ensure
1001     * that any use of this method is consistant with the currently enabled
1002     * activity set.
1003     *
1004     * @return the visible working sets for this page
1005     * @see IWorkbench#getActivitySupport()
1006     * @since 3.2
1007     */
1008    public IWorkingSet[] getWorkingSets();
1009
1010    /**
1011     * Set the working sets for this page. Any duplicate entries will be removed
1012     * from the array by this method.
1013     *
1014     * @param sets
1015     * the new working sets for this page. The array may be empty,
1016     * but no element in the array may be <code>null</code>.
1017     * @since 3.2
1018     */
1019    public void setWorkingSets(IWorkingSet[] sets);
1020
1021    /**
1022     * Return a working set that contains all of the elements contained in the
1023     * array of working sets provided by {@link #getWorkingSets()}. Should this
1024     * array or the underlying elements in any of the working sets change this
1025     * set will be updated.
1026     *
1027     * <p>
1028     * This working set is never <code>null</code>, even if there are no
1029     * working sets assigned to this page via
1030     * {@link #setWorkingSets(IWorkingSet[])}. It is recommended that any
1031     * client that uses this API be aware of this and act accordingly.
1032     * Specifically, it is recommended that any client utilizing this or any
1033     * other IWorkingSet whose {@link IWorkingSet#isAggregateWorkingSet()}
1034     * returns <code>true</code> act as if they are not using any working set
1035     * if the set is empty. These clients should also maintain an awareness of
1036     * the contents of aggregate working sets and toggle this behavior should
1037     * the contents of the aggregate either become empty or non-empty.
1038     * </p>
1039     * <p>
1040     * Example: <br/> Here we have pseudocode showing how some workingset
1041     * utilizing component could react to changes in aggregate working sets.
1042     * <br/> <code>
1043     * private IWorkingSet myWorkingSet;
1044     *
1045     * IPropertyChangeListener workingSetListener = new IPropertyChangeListener() {
1046     * public void propertyChange(PropertyChangeEvent event) {
1047     * if (isMyCurrentWorkingSet(event)) {
1048     * if (isEmptyAggregate(myWorkingSet)) {
1049     * showNoSet();
1050     * }
1051     * else {
1052     * showSet();
1053     * }
1054     * }
1055     * }
1056     * };
1057     *
1058     * public void setWorkingSet(IWorkingSet newSet) {
1059     * myWorkingSet = newSet;
1060     * if (myWorkingSet == null || isEmptyAggregate(myWorkingSet)){
1061     * showNoSet();
1062     * }
1063     * else {
1064     * showSet();
1065     * }
1066     * }
1067     * </code>
1068     * </p>
1069     *
1070     * @return the aggregate working set for this page
1071     * @since 3.2
1072     */
1073    public IWorkingSet getAggregateWorkingSet();
1074
1075    /**
1076     * Returns the page "zoomed" state.
1077     *
1078     * @return <code>true</code> if the page is zoomed in the workbench
1079     * window, <code>false</code> otherwise.
1080     * @since 3.2
1081     */
1082    public boolean isPageZoomed();
1083
1084    /**
1085     * Zooms out the zoomed-in part. If the page does not have a zoomed part, it
1086     * does nothing.
1087     *
1088     * @since 3.2
1089     */
1090    public void zoomOut();
1091
1092    /**
1093     * Zoom the page in on a part. If the part is already in zoom then zoom out.
1094     *
1095     * @param ref
1096     * the workbench part to zoom in on. Must not be
1097     * <code>null</code>.
1098     * @since 3.2
1099     */
1100    public void toggleZoom(IWorkbenchPartReference ref);
1101
1102    /**
1103     * Returns the maximized/minimized/restored state of the given part
1104     * reference.
1105     *
1106     * @param ref
1107     * the workbench part to query. Must not be <code>null</code>.
1108     * @return one of the STATE_* contants.
1109     * @since 3.2
1110     */
1111    public int getPartState(IWorkbenchPartReference ref);
1112
1113    /**
1114     * Set the state of the given part reference. Setting the state of one part
1115     * can effect the state of other parts.
1116     *
1117     * @param ref
1118     * the workbench part reference. Must not be <code>null</code>.
1119     * @param state
1120     * one of the STATE_* constants.
1121     * @since 3.2
1122     */
1123    public void setPartState(IWorkbenchPartReference ref, int state);
1124
1125    /**
1126     * Find the part reference for the given part. A convenience method to
1127     * quickly go from part to part reference.
1128     *
1129     * @param part
1130     * The part to search for. It can be <code>null</code>.
1131     * @return The reference for the given part, or <code>null</code> if no
1132     * reference can be found.
1133     * @since 3.2
1134     */
1135    public IWorkbenchPartReference getReference(IWorkbenchPart part);
1136}
1137

A to Z: JavaDoc & Examples

---

Daily Java News & Articles

---

Open Source Projects

---

Open Source Codes

---

Free Computer Books

---

Remove Frame

---

Popular Tags