001: /*******************************************************************************
002: * Copyright (c) 2006 IBM Corporation and others.
003: * All rights reserved. This program and the accompanying materials
004: * are made available under the terms of the Eclipse Public License v1.0
005: * which accompanies this distribution, and is available at
006: * http://www.eclipse.org/legal/epl-v10.html
007: *
008: * Contributors:
009: * IBM Corporation - initial API and implementation
010: ******************************************************************************/package org.eclipse.ui;
011:
012: import org.eclipse.ui.part.EditorPart;
013:
014: /**
015: * Represents a source of Saveable objects (units of saveability). Workbench
016: * parts that show more than one unit of saveability, or whose units of
017: * saveability change over time, should implement this interface in order to
018: * provide better integration with workbench facilities like the Save command,
019: * prompts to save on part close or shutdown, etc.
020: * <p>
021: * IMPORTANT: As of 3.2, implementers of <code>ISaveablesSource</code> must
022: * satisfy the following conditions:
023: * <ul>
024: * <li>If ISaveablesSource is implemented by an IWorkbenchPart:
025: * <ul>
026: * <li>the part must implement <code>ISaveablePart</code></li>
027: * <li>if any of its Saveable objects are dirty, the part must return
028: * <code>true</code> from {@link ISaveablePart#isDirty()}</li>
029: * <li>the part must return <code>true</code> from
030: * {@link ISaveablePart#isSaveOnCloseNeeded()} if it is dirty (the default
031: * behaviour implemented by {@link EditorPart})</li>
032: * <li>the part must not implement {@link ISaveablePart2}</li>
033: * </ul>
034: * </li>
035: * <li>If ISaveablesSource is implemented by a non-part (possible as of 3.2.1 and 3.3):
036: * <ul>
037: * <li>the Workbench's {@link ISaveablesLifecycleListener} (obtained from the
038: * Workbench by calling
039: * <code>workbench.getService(ISaveablesLifecycleListener.class)</code>) must
040: * be notified of any change to the result of {@link #getSaveables()} </li>
041: * <li>getActiveSaveables() should be implemented to return an empty array
042: * </li>
043: * </ul>
044: * </ul>
045: * If any of these conditions are not met, it is undefined whether the Workbench
046: * will prompt to save dirty Saveables when closing parts or the Workbench.
047: * </p>
048: * <p>
049: * These conditions may be relaxed in future releases.
050: * </p>
051: *
052: * @since 3.2
053: */
054: public interface ISaveablesSource {
055:
056: /**
057: * Returns the saveables presented by the workbench part. If the return
058: * value of this method changes during the lifetime of
059: * this part (i.e. after initialization and control creation but before disposal)
060: * the part must notify an implicit listener using
061: * {@link ISaveablesLifecycleListener#handleLifecycleEvent(SaveablesLifecycleEvent)}.
062: * <p>
063: * Additions of saveables to the list of saveables of this part are
064: * announced using an event of type
065: * {@link SaveablesLifecycleEvent#POST_OPEN}. Removals are announced in a
066: * two-stage process, first using an event of type
067: * {@link SaveablesLifecycleEvent#PRE_CLOSE} followed by an event of type
068: * {@link SaveablesLifecycleEvent#POST_CLOSE}. Since firing the
069: * <code>PRE_CLOSE</code> event may trigger prompts to save dirty
070: * saveables, the cancellation status of the event must be checked by the
071: * part after the notification. When removing only non-dirty saveables,
072: * <code>POST_CLOSE</code> notification is sufficient.
073: * </p>
074: * <p>
075: * The listener is obtained from the part site by calling
076: * <code>partSite.getService(ISaveablesLifecycleListener.class)</code>.
077: * </p>
078: * <p>
079: * The part must not notify from its initialization methods (e.g. <code>init</code>
080: * or <code>createPartControl</code>), or from its dispose method. Parts that
081: * implement {@link IReusableEditor} must notify when their input is changed
082: * through {@link IReusableEditor#setInput(IEditorInput)}.
083: * </p>
084: *
085: * @return the saveables presented by the workbench part
086: *
087: * @see ISaveablesLifecycleListener
088: */
089: Saveable[] getSaveables();
090:
091: /**
092: * Returns the saveables currently active in the workbench part.
093: * <p>
094: * Certain workbench actions, such as Save, target only the active saveables
095: * in the active part. For example, the active saveables could be determined
096: * based on the current selection in the part.
097: * </p>
098: *
099: * @return the saveables currently active in the workbench part
100: */
101: Saveable[] getActiveSaveables();
102: }
|