0001: /*******************************************************************************
0002: * Copyright (c) 2000, 2007 IBM Corporation and others.
0003: * All rights reserved. This program and the accompanying materials
0004: * are made available under the terms of the Eclipse Public License v1.0
0005: * which accompanies this distribution, and is available at
0006: * http://www.eclipse.org/legal/epl-v10.html
0007: *
0008: * Contributors:
0009: * IBM Corporation - initial API and implementation
0010: *******************************************************************************/package org.eclipse.ui;
0011:
0012: import org.eclipse.core.runtime.IAdaptable;
0013: import org.eclipse.core.runtime.dynamichelpers.IExtensionTracker;
0014: import org.eclipse.jface.util.IPropertyChangeListener;
0015: import org.eclipse.ui.internal.ICompatibleWorkbenchPage;
0016: import org.eclipse.ui.presentations.IStackPresentationSite;
0017:
0018: /**
0019: * A workbench page consists of an arrangement of views and editors intended to
0020: * be presented together to the user in a single workbench window.
0021: * <p>
0022: * A page can contain 0 or more views and 0 or more editors. These views and
0023: * editors are contained wholly within the page and are not shared with other
0024: * pages. The layout and visible action set for the page is defined by a
0025: * perspective.
0026: * <p>
0027: * The number of views and editors within a page is restricted to simplify part
0028: * management for the user. In particular:
0029: * <ul>
0030: * <li>Unless a view explicitly allows for multiple instances in its plugin
0031: * declaration there will be only one instance in a given workbench page.</li>
0032: * <li>Only one editor can exist for each editor input within a page.
0033: * <li>
0034: * </ul>
0035: * </p>
0036: * <p>
0037: * This interface is not intended to be implemented by clients.
0038: * </p>
0039: *
0040: * @see IPerspectiveDescriptor
0041: * @see IEditorPart
0042: * @see IViewPart
0043: */
0044: public interface IWorkbenchPage extends IPartService,
0045: ISelectionService, ICompatibleWorkbenchPage {
0046: /**
0047: * An optional attribute within a workspace marker (<code>IMarker</code>)
0048: * which identifies the preferred editor type to be opened when
0049: * <code>openEditor</code> is called.
0050: *
0051: * @see #openEditor(IEditorInput, String)
0052: * @see #openEditor(IEditorInput, String, boolean)
0053: * @deprecated in 3.0 since the notion of markers this is not generally
0054: * applicable. Use the IDE-specific constant
0055: * <code>IDE.EDITOR_ID_ATTR</code>.
0056: */
0057: public static final String EDITOR_ID_ATTR = "org.eclipse.ui.editorID"; //$NON-NLS-1$
0058:
0059: /**
0060: * Change event id when the perspective is reset to its original state.
0061: *
0062: * @see IPerspectiveListener
0063: */
0064: public static final String CHANGE_RESET = "reset"; //$NON-NLS-1$
0065:
0066: /**
0067: * Change event id when the perspective has completed a reset to its
0068: * original state.
0069: *
0070: * @since 3.0
0071: * @see IPerspectiveListener
0072: */
0073: public static final String CHANGE_RESET_COMPLETE = "resetComplete"; //$NON-NLS-1$
0074:
0075: /**
0076: * Change event id when one or more views are shown in a perspective.
0077: *
0078: * @see IPerspectiveListener
0079: */
0080: public static final String CHANGE_VIEW_SHOW = "viewShow"; //$NON-NLS-1$
0081:
0082: /**
0083: * Change event id when one or more views are hidden in a perspective.
0084: *
0085: * @see IPerspectiveListener
0086: */
0087: public static final String CHANGE_VIEW_HIDE = "viewHide"; //$NON-NLS-1$
0088:
0089: /**
0090: * Change event id when one or more editors are opened in a perspective.
0091: *
0092: * @see IPerspectiveListener
0093: */
0094: public static final String CHANGE_EDITOR_OPEN = "editorOpen"; //$NON-NLS-1$
0095:
0096: /**
0097: * Change event id when one or more editors are closed in a perspective.
0098: *
0099: * @see IPerspectiveListener
0100: */
0101: public static final String CHANGE_EDITOR_CLOSE = "editorClose"; //$NON-NLS-1$
0102:
0103: /**
0104: * Change event id when the editor area is shown in a perspective.
0105: *
0106: * @see IPerspectiveListener
0107: */
0108: public static final String CHANGE_EDITOR_AREA_SHOW = "editorAreaShow"; //$NON-NLS-1$
0109:
0110: /**
0111: * Change event id when the editor area is hidden in a perspective.
0112: *
0113: * @see IPerspectiveListener
0114: */
0115: public static final String CHANGE_EDITOR_AREA_HIDE = "editorAreaHide"; //$NON-NLS-1$
0116:
0117: /**
0118: * Change event id when an action set is shown in a perspective.
0119: *
0120: * @see IPerspectiveListener
0121: */
0122: public static final String CHANGE_ACTION_SET_SHOW = "actionSetShow"; //$NON-NLS-1$
0123:
0124: /**
0125: * Change event id when an action set is hidden in a perspective.
0126: *
0127: * @see IPerspectiveListener
0128: */
0129: public static final String CHANGE_ACTION_SET_HIDE = "actionSetHide"; //$NON-NLS-1$
0130:
0131: /**
0132: * Change event id when a fast view is added in a perspective.
0133: *
0134: * @see IPerspectiveListener
0135: */
0136: public static final String CHANGE_FAST_VIEW_ADD = "fastViewAdd"; //$NON-NLS-1$
0137:
0138: /**
0139: * Change event id when a fast view is removed in a perspective.
0140: *
0141: * @see IPerspectiveListener
0142: */
0143: public static final String CHANGE_FAST_VIEW_REMOVE = "fastViewRemove"; //$NON-NLS-1$
0144:
0145: /**
0146: * Change event id when the page working set was replaced
0147: *
0148: * @see IPropertyChangeListener
0149: */
0150: public static final String CHANGE_WORKING_SET_REPLACE = "workingSetReplace"; //$NON-NLS-1$
0151:
0152: /**
0153: * Change event id when the page working set list was replaced
0154: *
0155: * @see IPropertyChangeListener
0156: * @since 3.2
0157: */
0158: public static final String CHANGE_WORKING_SETS_REPLACE = "workingSetsReplace"; //$NON-NLS-1$
0159:
0160: /**
0161: * Show view mode that indicates the view should be made visible and
0162: * activated. Use of this mode has the same effect as calling
0163: * {@link #showView(String)}.
0164: *
0165: * @since 3.0
0166: */
0167: public static final int VIEW_ACTIVATE = 1;
0168:
0169: /**
0170: * Show view mode that indicates the view should be made visible. If the
0171: * view is opened in the container that contains the active view then this
0172: * has the same effect as <code>VIEW_CREATE</code>.
0173: *
0174: * @since 3.0
0175: */
0176: public static final int VIEW_VISIBLE = 2;
0177:
0178: /**
0179: * Show view mode that indicates the view should be made created but not
0180: * necessarily be made visible. It will only be made visible in the event
0181: * that it is opened in its own container. In other words, only if it is not
0182: * stacked with another view.
0183: *
0184: * @since 3.0
0185: */
0186: public static final int VIEW_CREATE = 3;
0187:
0188: /**
0189: * Editor opening match mode specifying that no matching against existing
0190: * editors should be done.
0191: *
0192: * @since 3.2
0193: */
0194: public static final int MATCH_NONE = 0;
0195:
0196: /**
0197: * Editor opening match mode specifying that the editor input should be
0198: * considered when matching against existing editors.
0199: *
0200: * @since 3.2
0201: */
0202: public static final int MATCH_INPUT = 1;
0203:
0204: /**
0205: * Editor opening match mode specifying that the editor id should be
0206: * considered when matching against existing editors.
0207: *
0208: * @since 3.2
0209: */
0210: public static final int MATCH_ID = 2;
0211:
0212: /**
0213: * State of a view in a given page when the view stack is minimized.
0214: *
0215: * @since 3.2
0216: */
0217: public static final int STATE_MINIMIZED = IStackPresentationSite.STATE_MINIMIZED;
0218:
0219: /**
0220: * State of a view in a given page when the page is zoomed in on the view
0221: * stack.
0222: *
0223: * @since 3.2
0224: */
0225: public static final int STATE_MAXIMIZED = IStackPresentationSite.STATE_MAXIMIZED;
0226:
0227: /**
0228: * State of a view in a given page when the view stack is in it's normal
0229: * state.
0230: *
0231: * @since 3.2
0232: */
0233: public static final int STATE_RESTORED = IStackPresentationSite.STATE_RESTORED;
0234:
0235: /**
0236: * Activates the given part. The part will be brought to the front and given
0237: * focus. The part must belong to this page.
0238: *
0239: * @param part
0240: * the part to activate
0241: */
0242: public void activate(IWorkbenchPart part);
0243:
0244: /**
0245: * Adds a property change listener.
0246: *
0247: * @param listener
0248: * the property change listener to add
0249: * @since 2.0
0250: */
0251: public void addPropertyChangeListener(
0252: IPropertyChangeListener listener);
0253:
0254: /**
0255: * Moves the given part forward in the Z order of this page so as to make it
0256: * visible, without changing which part has focus. The part must belong to
0257: * this page.
0258: *
0259: * @param part
0260: * the part to bring forward
0261: */
0262: public void bringToTop(IWorkbenchPart part);
0263:
0264: /**
0265: * Closes this workbench page. If this page is the active one, this honor is
0266: * passed along to one of the window's other pages if possible.
0267: * <p>
0268: * If the page has an open editor with unsaved content, the user will be
0269: * given the opportunity to save it.
0270: * </p>
0271: *
0272: * @return <code>true</code> if the page was successfully closed, and
0273: * <code>false</code> if it is still open
0274: */
0275: public boolean close();
0276:
0277: /**
0278: * Closes all of the editors belonging to this workbench page.
0279: * <p>
0280: * If the page has open editors with unsaved content and <code>save</code>
0281: * is <code>true</code>, the user will be given the opportunity to save
0282: * them.
0283: * </p>
0284: *
0285: * @param save
0286: *
0287: * @return <code>true</code> if all editors were successfully closed, and
0288: * <code>false</code> if at least one is still open
0289: */
0290: public boolean closeAllEditors(boolean save);
0291:
0292: /**
0293: * Closes the given <code>Array</code> of editor references. The editors
0294: * must belong to this workbench page.
0295: * <p>
0296: * If any of the editors have unsaved content and <code>save</code> is
0297: * <code>true</code>, the user will be given the opportunity to save
0298: * them.
0299: * </p>
0300: *
0301: * @param editorRefs
0302: * the editors to close
0303: * @param save
0304: * <code>true</code> to save the editor contents if required
0305: * (recommended), and <code>false</code> to discard any unsaved
0306: * changes
0307: * @return <code>true</code> if the editors were successfully closed, and
0308: * <code>false</code> if the editors are still open
0309: * @since 3.0
0310: */
0311: public boolean closeEditors(IEditorReference[] editorRefs,
0312: boolean save);
0313:
0314: /**
0315: * Closes the given editor. The editor must belong to this workbench page.
0316: * <p>
0317: * If the editor has unsaved content and <code>save</code> is
0318: * <code>true</code>, the user will be given the opportunity to save it.
0319: * </p>
0320: *
0321: * @param editor
0322: * the editor to close
0323: * @param save
0324: * <code>true</code> to save the editor contents if required
0325: * (recommended), and <code>false</code> to discard any unsaved
0326: * changes
0327: * @return <code>true</code> if the editor was successfully closed, and
0328: * <code>false</code> if the editor is still open
0329: */
0330: public boolean closeEditor(IEditorPart editor, boolean save);
0331:
0332: /**
0333: * Returns the view in this page with the specified id. There is at most one
0334: * view in the page with the specified id.
0335: *
0336: * @param viewId
0337: * the id of the view extension to use
0338: * @return the view, or <code>null</code> if none is found
0339: */
0340: public IViewPart findView(String viewId);
0341:
0342: /**
0343: * Returns the view reference with the specified id.
0344: *
0345: * @param viewId
0346: * the id of the view extension to use
0347: * @return the view reference, or <code>null</code> if none is found
0348: * @since 3.0
0349: */
0350: public IViewReference findViewReference(String viewId);
0351:
0352: /**
0353: * Returns the view reference with the specified id and secondary id.
0354: *
0355: * @param viewId
0356: * the id of the view extension to use
0357: * @param secondaryId
0358: * the secondary id to use, or <code>null</code> for no
0359: * secondary id
0360: * @return the view reference, or <code>null</code> if none is found
0361: * @since 3.0
0362: */
0363: public IViewReference findViewReference(String viewId,
0364: String secondaryId);
0365:
0366: /**
0367: * Returns the active editor open in this page.
0368: * <p>
0369: * This is the visible editor on the page, or, if there is more than one
0370: * visible editor, this is the one most recently brought to top.
0371: * </p>
0372: *
0373: * @return the active editor, or <code>null</code> if no editor is active
0374: */
0375: public IEditorPart getActiveEditor();
0376:
0377: /**
0378: * Returns the editor with the specified input. Returns null if there is no
0379: * opened editor with that input.
0380: *
0381: * @param input
0382: * the editor input
0383: * @return an editor with input equals to <code>input</code>
0384: */
0385: public IEditorPart findEditor(IEditorInput input);
0386:
0387: /**
0388: * Returns an array of editor references that match the given input and/or
0389: * editor id, as specified by the given match flags. Returns an empty array
0390: * if there are no matching editors, or if matchFlags is MATCH_NONE.
0391: *
0392: * @param input
0393: * the editor input, or <code>null</code> if MATCH_INPUT is not
0394: * specified in matchFlags
0395: * @param editorId
0396: * the editor id, or <code>null</code> if MATCH_ID is not
0397: * specified in matchFlags
0398: * @param matchFlags
0399: * a bit mask consisting of zero or more of the MATCH_* constants
0400: * OR-ed together
0401: * @return the references for the matching editors
0402: *
0403: * @see #MATCH_NONE
0404: * @see #MATCH_INPUT
0405: * @see #MATCH_ID
0406: * @since 3.2
0407: */
0408: public IEditorReference[] findEditors(IEditorInput input,
0409: String editorId, int matchFlags);
0410:
0411: /**
0412: * Returns a list of the editors open in this page.
0413: * <p>
0414: * Note that each page has its own editors; editors are never shared between
0415: * pages.
0416: * </p>
0417: *
0418: * @return a list of open editors
0419: *
0420: * @deprecated use #getEditorReferences() instead
0421: */
0422: public IEditorPart[] getEditors();
0423:
0424: /**
0425: * Returns an array of references to open editors in this page.
0426: * <p>
0427: * Note that each page has its own editors; editors are never shared between
0428: * pages.
0429: * </p>
0430: *
0431: * @return a list of open editors
0432: */
0433: public IEditorReference[] getEditorReferences();
0434:
0435: /**
0436: * Returns a list of dirty editors in this page.
0437: *
0438: * @return a list of dirty editors
0439: */
0440: public IEditorPart[] getDirtyEditors();
0441:
0442: /**
0443: * Returns the input for this page.
0444: *
0445: * @return the input for this page, or <code>null</code> if none
0446: */
0447: public IAdaptable getInput();
0448:
0449: /**
0450: * Returns the page label. This will be a unique identifier within the
0451: * containing workbench window.
0452: *
0453: * @return the page label
0454: */
0455: public String getLabel();
0456:
0457: /**
0458: * Returns the current perspective descriptor for this page, or
0459: * <code>null</code> if there is no current perspective.
0460: *
0461: * @return the current perspective descriptor or <code>null</code>
0462: * @see #setPerspective
0463: * @see #savePerspective
0464: */
0465: public IPerspectiveDescriptor getPerspective();
0466:
0467: /**
0468: * Returns a list of the reference to views visible on this page.
0469: * <p>
0470: * Note that each page has its own views; views are never shared between
0471: * pages.
0472: * </p>
0473: *
0474: * @return a list of references to visible views
0475: */
0476: public IViewReference[] getViewReferences();
0477:
0478: /**
0479: * Returns a list of the views visible on this page.
0480: * <p>
0481: * Note that each page has its own views; views are never shared between
0482: * pages.
0483: * </p>
0484: *
0485: * @return a list of visible views
0486: *
0487: * @deprecated use #getViewReferences() instead.
0488: */
0489: public IViewPart[] getViews();
0490:
0491: /**
0492: * Returns the workbench window of this page.
0493: *
0494: * @return the workbench window
0495: */
0496: public IWorkbenchWindow getWorkbenchWindow();
0497:
0498: /**
0499: * Returns the working set of this page.
0500: *
0501: * @return the working set of this page.
0502: * @since 2.0
0503: * @deprecated individual views should store a working set if needed
0504: */
0505: public IWorkingSet getWorkingSet();
0506:
0507: /**
0508: * Hides an action set in this page.
0509: * <p>
0510: * In most cases where this method is used the caller is tightly coupled to
0511: * a particular action set. They define it in the registry and may make it
0512: * visible in certain scenarios by calling <code>showActionSet</code>. A
0513: * static variable is often used to identify the action set id in caller
0514: * code.
0515: * </p>
0516: *
0517: * @param actionSetID
0518: * the action set to hide
0519: */
0520: public void hideActionSet(String actionSetID);
0521:
0522: /**
0523: * Hides the given view. The view must belong to this page.
0524: *
0525: * @param view
0526: * the view to hide
0527: */
0528: public void hideView(IViewPart view);
0529:
0530: /**
0531: * Hides the given view that belongs to the reference, if any.
0532: *
0533: * @param view
0534: * the references whos view is to be hidden
0535: * @since 3.0
0536: */
0537: public void hideView(IViewReference view);
0538:
0539: /**
0540: * Returns whether the specified part is visible.
0541: *
0542: * @param part
0543: * the part to test
0544: * @return boolean <code>true</code> if part is visible
0545: */
0546: public boolean isPartVisible(IWorkbenchPart part);
0547:
0548: /**
0549: * Returns whether the page's current perspective is showing the editor
0550: * area.
0551: *
0552: * @return <code>true</code> when editor area visible, <code>false</code>
0553: * otherwise
0554: */
0555: public boolean isEditorAreaVisible();
0556:
0557: /**
0558: * Reuses the specified editor by setting its new input.
0559: *
0560: * @param editor
0561: * the editor to be reused
0562: * @param input
0563: * the new input for the reusable editor
0564: */
0565: public void reuseEditor(IReusableEditor editor, IEditorInput input);
0566:
0567: /**
0568: * Opens an editor on the given input.
0569: * <p>
0570: * If this page already has an editor open on the target input that editor
0571: * is activated; otherwise, a new editor is opened. Two editor inputs,
0572: * input1 and input2, are considered the same if
0573: *
0574: * <pre>
0575: * input1.equals(input2) == true
0576: * </pre>.
0577: * </p>
0578: * <p>
0579: * The editor type is determined by mapping <code>editorId</code> to an
0580: * editor extension registered with the workbench. An editor id is passed
0581: * rather than an editor object to prevent the accidental creation of more
0582: * than one editor for the same input. It also guarantees a consistent
0583: * lifecycle for editors, regardless of whether they are created by the user
0584: * or restored from saved data.
0585: * </p>
0586: *
0587: * @param input
0588: * the editor input
0589: * @param editorId
0590: * the id of the editor extension to use
0591: * @return an open and active editor, or <code>null</code> if an external
0592: * editor was opened
0593: * @exception PartInitException
0594: * if the editor could not be created or initialized
0595: */
0596: public IEditorPart openEditor(IEditorInput input, String editorId)
0597: throws PartInitException;
0598:
0599: /**
0600: * Opens an editor on the given input.
0601: * <p>
0602: * If this page already has an editor open on the target input that editor
0603: * is brought to the front; otherwise, a new editor is opened. Two editor
0604: * inputs are considered the same if they equal. See
0605: * <code>Object.equals(Object)<code>
0606: * and <code>IEditorInput</code>. If <code>activate == true</code> the editor
0607: * will be activated.
0608: * </p><p>
0609: * The editor type is determined by mapping <code>editorId</code> to an editor
0610: * extension registered with the workbench. An editor id is passed rather than
0611: * an editor object to prevent the accidental creation of more than one editor
0612: * for the same input. It also guarantees a consistent lifecycle for editors,
0613: * regardless of whether they are created by the user or restored from saved
0614: * data.
0615: * </p>
0616: *
0617: * @param input the editor input
0618: * @param editorId the id of the editor extension to use
0619: * @param activate if <code>true</code> the editor will be activated
0620: * @return an open editor, or <code>null</code> if an external editor was opened
0621: * @exception PartInitException if the editor could not be created or initialized
0622: */
0623: public IEditorPart openEditor(IEditorInput input, String editorId,
0624: boolean activate) throws PartInitException;
0625:
0626: /**
0627: * Opens an editor on the given input.
0628: * <p>
0629: * If this page already has an editor open that matches the given input
0630: * and/or editor id (as specified by the matchFlags argument), that editor
0631: * is brought to the front; otherwise, a new editor is opened. Two editor
0632: * inputs are considered the same if they equal. See
0633: * <code>Object.equals(Object)<code>
0634: * and <code>IEditorInput</code>. If <code>activate == true</code> the editor
0635: * will be activated.
0636: * </p><p>
0637: * The editor type is determined by mapping <code>editorId</code> to an editor
0638: * extension registered with the workbench. An editor id is passed rather than
0639: * an editor object to prevent the accidental creation of more than one editor
0640: * for the same input. It also guarantees a consistent lifecycle for editors,
0641: * regardless of whether they are created by the user or restored from saved
0642: * data.
0643: * </p>
0644: *
0645: * @param input the editor input
0646: * @param editorId the id of the editor extension to use
0647: * @param activate if <code>true</code> the editor will be activated
0648: * @param matchFlags a bit mask consisting of zero or more of the MATCH_* constants OR-ed together
0649: * @return an open editor, or <code>null</code> if an external editor was opened
0650: * @exception PartInitException if the editor could not be created or initialized
0651: *
0652: * @see #MATCH_NONE
0653: * @see #MATCH_INPUT
0654: * @see #MATCH_ID
0655: * @since 3.2
0656: */
0657: public IEditorPart openEditor(final IEditorInput input,
0658: final String editorId, final boolean activate,
0659: final int matchFlags) throws PartInitException;
0660:
0661: /**
0662: * Removes the property change listener.
0663: *
0664: * @param listener
0665: * the property change listener to remove
0666: * @since 2.0
0667: */
0668: public void removePropertyChangeListener(
0669: IPropertyChangeListener listener);
0670:
0671: /**
0672: * Changes the visible views, their layout, and the visible action sets
0673: * within the page to match the current perspective descriptor. This is a
0674: * rearrangement of components and not a replacement. The contents of the
0675: * current perspective descriptor are unaffected.
0676: * <p>
0677: * For more information on perspective change see
0678: * <code>setPerspective()</code>.
0679: * </p>
0680: */
0681: public void resetPerspective();
0682:
0683: /**
0684: * Saves the contents of all dirty editors belonging to this workbench page.
0685: * If there are no dirty editors this method returns without effect.
0686: * <p>
0687: * If <code>confirm</code> is <code>true</code> the user is prompted to
0688: * confirm the command.
0689: * </p>
0690: * <p>
0691: * Note that as of 3.2, this method also saves views that implement
0692: * ISaveablePart and are dirty.
0693: * </p>
0694: *
0695: * @param confirm <code>true</code> to ask the user before saving unsaved
0696: * changes (recommended), and <code>false</code> to save
0697: * unsaved changes without asking
0698: * @return <code>true</code> if the command succeeded, and
0699: * <code>false</code> if the operation was canceled by the user or
0700: * an error occurred while saving
0701: */
0702: public boolean saveAllEditors(boolean confirm);
0703:
0704: /**
0705: * Saves the contents of the given editor if dirty. If not, this method
0706: * returns without effect.
0707: * <p>
0708: * If <code>confirm</code> is <code>true</code> the user is prompted to
0709: * confirm the command. Otherwise, the save happens without prompt.
0710: * </p>
0711: * <p>
0712: * The editor must belong to this workbench page.
0713: * </p>
0714: *
0715: * @param editor
0716: * the editor to close
0717: * @param confirm
0718: * <code>true</code> to ask the user before saving unsaved
0719: * changes (recommended), and <code>false</code> to save
0720: * unsaved changes without asking
0721: * @return <code>true</code> if the command succeeded, and
0722: * <code>false</code> if the editor was not saved
0723: */
0724: public boolean saveEditor(IEditorPart editor, boolean confirm);
0725:
0726: /**
0727: * Saves the visible views, their layout, and the visible action sets for
0728: * this page to the current perspective descriptor. The contents of the
0729: * current perspective descriptor are overwritten.
0730: */
0731: public void savePerspective();
0732:
0733: /**
0734: * Saves the visible views, their layout, and the visible action sets for
0735: * this page to the given perspective descriptor. The contents of the given
0736: * perspective descriptor are overwritten and it is made the current one for
0737: * this page.
0738: *
0739: * @param perspective
0740: * the perspective descriptor to save to
0741: */
0742: public void savePerspectiveAs(IPerspectiveDescriptor perspective);
0743:
0744: /**
0745: * Show or hide the editor area for the page's active perspective.
0746: *
0747: * @param showEditorArea
0748: * <code>true</code> to show the editor area,
0749: * <code>false</code> to hide the editor area
0750: */
0751: public void setEditorAreaVisible(boolean showEditorArea);
0752:
0753: /**
0754: * Changes the visible views, their layout, and the visible action sets
0755: * within the page to match the given perspective descriptor. This is a
0756: * rearrangement of components and not a replacement. The contents of the
0757: * old perspective descriptor are unaffected.
0758: * <p>
0759: * When a perspective change occurs the old perspective is deactivated
0760: * (hidden) and cached for future reference. Then the new perspective is
0761: * activated (shown). The views within the page are shared by all existing
0762: * perspectives to make it easy for the user to switch between one
0763: * perspective and another quickly without loss of context.
0764: * </p>
0765: * <p>
0766: * During activation the action sets are modified. If an action set is
0767: * specified in the new perspective which is not visible in the old one it
0768: * will be created. If an old action set is not specified in the new
0769: * perspective it will be disposed.
0770: * </p>
0771: * <p>
0772: * The visible views and their layout within the page also change. If a view
0773: * is specified in the new perspective which is not visible in the old one a
0774: * new instance of the view will be created. If an old view is not specified
0775: * in the new perspective it will be hidden. This view may reappear if the
0776: * user selects it from the View menu or if they switch to a perspective
0777: * (which may be the old one) where the view is visible.
0778: * </p>
0779: * <p>
0780: * The open editors are not modified by this method.
0781: * </p>
0782: *
0783: * @param perspective
0784: * the perspective descriptor
0785: */
0786: public void setPerspective(IPerspectiveDescriptor perspective);
0787:
0788: /**
0789: * Shows an action set in this page.
0790: * <p>
0791: * In most cases where this method is used the caller is tightly coupled to
0792: * a particular action set. They define it in the registry and may make it
0793: * visible in certain scenarios by calling <code>showActionSet</code>. A
0794: * static variable is often used to identify the action set id in caller
0795: * code.
0796: * </p>
0797: *
0798: * @param actionSetID
0799: * the action set to show
0800: */
0801: public void showActionSet(String actionSetID);
0802:
0803: /**
0804: * Shows the view identified by the given view id in this page and gives it
0805: * focus. If there is a view identified by the given view id (and with no
0806: * secondary id) already open in this page, it is given focus.
0807: *
0808: * @param viewId
0809: * the id of the view extension to use
0810: * @return the shown view
0811: * @exception PartInitException
0812: * if the view could not be initialized
0813: */
0814: public IViewPart showView(String viewId) throws PartInitException;
0815:
0816: /**
0817: * Shows a view in this page with the given id and secondary id. The
0818: * behaviour of this method varies based on the supplied mode. If
0819: * <code>VIEW_ACTIVATE</code> is supplied, the view is focus. If
0820: * <code>VIEW_VISIBLE</code> is supplied, then it is made visible but not
0821: * given focus. Finally, if <code>VIEW_CREATE</code> is supplied the view
0822: * is created and will only be made visible if it is not created in a folder
0823: * that already contains visible views.
0824: * <p>
0825: * This allows multiple instances of a particular view to be created. They
0826: * are disambiguated using the secondary id. If a secondary id is given, the
0827: * view must allow multiple instances by having specified
0828: * allowMultiple="true" in its extension.
0829: * </p>
0830: *
0831: * @param viewId
0832: * the id of the view extension to use
0833: * @param secondaryId
0834: * the secondary id to use, or <code>null</code> for no
0835: * secondary id
0836: * @param mode
0837: * the activation mode. Must be {@link #VIEW_ACTIVATE},
0838: * {@link #VIEW_VISIBLE} or {@link #VIEW_CREATE}
0839: * @return a view
0840: * @exception PartInitException
0841: * if the view could not be initialized
0842: * @exception IllegalArgumentException
0843: * if the supplied mode is not valid
0844: * @since 3.0
0845: */
0846: public IViewPart showView(String viewId, String secondaryId,
0847: int mode) throws PartInitException;
0848:
0849: /**
0850: * Returns <code>true</code> if the editor is pinned and should not be
0851: * reused.
0852: *
0853: * @param editor
0854: * the editor to test
0855: * @return boolean whether the editor is pinned
0856: */
0857: public boolean isEditorPinned(IEditorPart editor);
0858:
0859: /**
0860: * Returns the number of open editors before reusing editors.
0861: *
0862: * @return a int
0863: *
0864: * @deprecated
0865: */
0866: public int getEditorReuseThreshold();
0867:
0868: /**
0869: * Set the number of open editors before reusing editors. If < 0 the user
0870: * preference settings will be used.
0871: *
0872: * @param openEditors
0873: * the threshold
0874: * @deprecated use IPageLayout.setEditorReuseThreshold(int openEditors)
0875: * instead.
0876: */
0877: public void setEditorReuseThreshold(int openEditors);
0878:
0879: /**
0880: * Returns the navigation history which manages a list of entries keeping
0881: * the history of places (positions, selection and editors) the user visited
0882: * making it easier to the user to move back and forward without losing
0883: * context.
0884: *
0885: * @return the navigation history
0886: * @since 2.1
0887: */
0888: public INavigationHistory getNavigationHistory();
0889:
0890: /**
0891: * Returns an array of IViewParts that are stacked with the given part.
0892: *
0893: * @param part
0894: * the part to test
0895: * @return the parts that are stacked with this part, including the part in
0896: * question. <code>null</code> is returned if the part does not
0897: * belong to this page.
0898: * @since 3.0
0899: */
0900: IViewPart[] getViewStack(IViewPart part);
0901:
0902: /**
0903: * Returns the new wizard shortcuts associated with the current perspective.
0904: * Returns an empty array if there is no current perspective.
0905: *
0906: * @see IPageLayout#addNewWizardShortcut(String)
0907: * @return an array of wizard identifiers
0908: * @since 3.1
0909: */
0910: public String[] getNewWizardShortcuts();
0911:
0912: /**
0913: * Returns the perspective shortcuts associated with the current
0914: * perspective. Returns an empty array if there is no current perspective.
0915: *
0916: * @see IPageLayout#addPerspectiveShortcut(String)
0917: * @return an array of perspective identifiers
0918: * @since 3.1
0919: */
0920: public String[] getPerspectiveShortcuts();
0921:
0922: /**
0923: * Returns the show view shortcuts associated with the current perspective.
0924: * Returns an empty array if there is no current perspective.
0925: *
0926: * @see IPageLayout#addShowViewShortcut(String)
0927: * @return an array of view identifiers
0928: * @since 3.1
0929: */
0930: public String[] getShowViewShortcuts();
0931:
0932: /**
0933: * Returns the descriptors for the perspectives that are open in this page,
0934: * in the order in which they were opened.
0935: *
0936: * @return the open perspective descriptors, in order of opening
0937: * @since 3.1
0938: */
0939: public IPerspectiveDescriptor[] getOpenPerspectives();
0940:
0941: /**
0942: * Returns the descriptors for the perspectives that are open in this page,
0943: * in the order in which they were activated (oldest first).
0944: *
0945: * @return the open perspective descriptors, in order of activation
0946: * @since 3.1
0947: */
0948: public IPerspectiveDescriptor[] getSortedPerspectives();
0949:
0950: /**
0951: * Closes the specified perspective in this page. If the last perspective in
0952: * this page is closed, then all editors are closed. Views that are not
0953: * shown in other perspectives are closed as well. If <code>saveParts</code>
0954: * is <code>true</code>, the user will be prompted to save any unsaved
0955: * changes for parts that are being closed. The page itself is closed if
0956: * <code>closePage</code> is <code>true</code>.
0957: *
0958: * @param desc
0959: * the descriptor of the perspective to be closed
0960: * @param saveParts
0961: * whether the page's parts should be saved if closed
0962: * @param closePage
0963: * whether the page itself should be closed if last perspective
0964: * @since 3.1
0965: */
0966: public void closePerspective(IPerspectiveDescriptor desc,
0967: boolean saveParts, boolean closePage);
0968:
0969: /**
0970: * Closes all perspectives in this page. All editors are closed, prompting
0971: * to save any unsaved changes if <code>saveEditors</code> is
0972: * <code>true</code>. The page itself is closed if <code>closePage</code>
0973: * is <code>true</code>.
0974: *
0975: * @param saveEditors
0976: * whether the page's editors should be saved
0977: * @param closePage
0978: * whether the page itself should be closed
0979: * @since 3.1
0980: */
0981: public void closeAllPerspectives(boolean saveEditors,
0982: boolean closePage);
0983:
0984: /**
0985: * <p>
0986: * Return the extension tracker for the workbench. This tracker may be used
0987: * by plug-ins to ensure responsiveness to changes to the plug-in registry.
0988: * </p>
0989: * <p>
0990: * The tracker at this level of the workbench is typically used to track
0991: * elements that only exist over the lifespan of a page. For example,
0992: * <code>ViewPart</code> objects fall into this category.
0993: * </p>
0994: *
0995: * @return the extension tracker
0996: * @see IWorkbench#getExtensionTracker()
0997: * @see IWorkbenchWindow#getExtensionTracker()
0998: * @since 3.1
0999: */
1000: public IExtensionTracker getExtensionTracker();
1001:
1002: /**
1003: * Return the visible working sets for this page. Please note that this
1004: * array is not filtered by activities. Clients should attempt to ensure
1005: * that any use of this method is consistant with the currently enabled
1006: * activity set.
1007: *
1008: * @return the visible working sets for this page
1009: * @see IWorkbench#getActivitySupport()
1010: * @since 3.2
1011: */
1012: public IWorkingSet[] getWorkingSets();
1013:
1014: /**
1015: * Set the working sets for this page. Any duplicate entries will be removed
1016: * from the array by this method.
1017: *
1018: * @param sets
1019: * the new working sets for this page. The array may be empty,
1020: * but no element in the array may be <code>null</code>.
1021: * @since 3.2
1022: */
1023: public void setWorkingSets(IWorkingSet[] sets);
1024:
1025: /**
1026: * Return a working set that contains all of the elements contained in the
1027: * array of working sets provided by {@link #getWorkingSets()}. Should this
1028: * array or the underlying elements in any of the working sets change this
1029: * set will be updated.
1030: *
1031: * <p>
1032: * This working set is never <code>null</code>, even if there are no
1033: * working sets assigned to this page via
1034: * {@link #setWorkingSets(IWorkingSet[])}. It is recommended that any
1035: * client that uses this API be aware of this and act accordingly.
1036: * Specifically, it is recommended that any client utilizing this or any
1037: * other IWorkingSet whose {@link IWorkingSet#isAggregateWorkingSet()}
1038: * returns <code>true</code> act as if they are not using any working set
1039: * if the set is empty. These clients should also maintain an awareness of
1040: * the contents of aggregate working sets and toggle this behavior should
1041: * the contents of the aggregate either become empty or non-empty.
1042: * </p>
1043: * <p>
1044: * Example: <br/> Here we have pseudocode showing how some workingset
1045: * utilizing component could react to changes in aggregate working sets.
1046: * <br/> <code>
1047: * private IWorkingSet myWorkingSet;
1048: *
1049: * IPropertyChangeListener workingSetListener = new IPropertyChangeListener() {
1050: * public void propertyChange(PropertyChangeEvent event) {
1051: * if (isMyCurrentWorkingSet(event)) {
1052: * if (isEmptyAggregate(myWorkingSet)) {
1053: * showNoSet();
1054: * }
1055: * else {
1056: * showSet();
1057: * }
1058: * }
1059: * }
1060: * };
1061: *
1062: * public void setWorkingSet(IWorkingSet newSet) {
1063: * myWorkingSet = newSet;
1064: * if (myWorkingSet == null || isEmptyAggregate(myWorkingSet)){
1065: * showNoSet();
1066: * }
1067: * else {
1068: * showSet();
1069: * }
1070: * }
1071: * </code>
1072: * </p>
1073: *
1074: * @return the aggregate working set for this page
1075: * @since 3.2
1076: */
1077: public IWorkingSet getAggregateWorkingSet();
1078:
1079: /**
1080: * Returns the page "zoomed" state.
1081: *
1082: * @return <code>true</code> if the page is zoomed in the workbench
1083: * window, <code>false</code> otherwise.
1084: * @since 3.2
1085: */
1086: public boolean isPageZoomed();
1087:
1088: /**
1089: * Zooms out the zoomed-in part. If the page does not have a zoomed part, it
1090: * does nothing.
1091: *
1092: * @since 3.2
1093: */
1094: public void zoomOut();
1095:
1096: /**
1097: * Zoom the page in on a part. If the part is already in zoom then zoom out.
1098: *
1099: * @param ref
1100: * the workbench part to zoom in on. Must not be
1101: * <code>null</code>.
1102: * @since 3.2
1103: */
1104: public void toggleZoom(IWorkbenchPartReference ref);
1105:
1106: /**
1107: * Returns the maximized/minimized/restored state of the given part
1108: * reference.
1109: *
1110: * @param ref
1111: * the workbench part to query. Must not be <code>null</code>.
1112: * @return one of the STATE_* contants.
1113: * @since 3.2
1114: */
1115: public int getPartState(IWorkbenchPartReference ref);
1116:
1117: /**
1118: * Set the state of the given part reference. Setting the state of one part
1119: * can effect the state of other parts.
1120: *
1121: * @param ref
1122: * the workbench part reference. Must not be <code>null</code>.
1123: * @param state
1124: * one of the STATE_* constants.
1125: * @since 3.2
1126: */
1127: public void setPartState(IWorkbenchPartReference ref, int state);
1128:
1129: /**
1130: * Find the part reference for the given part. A convenience method to
1131: * quickly go from part to part reference.
1132: *
1133: * @param part
1134: * The part to search for. It can be <code>null</code>.
1135: * @return The reference for the given part, or <code>null</code> if no
1136: * reference can be found.
1137: * @since 3.2
1138: */
1139: public IWorkbenchPartReference getReference(IWorkbenchPart part);
1140: }
|