org.eclipse.ui.ISaveablesSource Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2006, 2015 IBM Corporation and others.
*
* This program and the accompanying materials
* are made available under the terms of the Eclipse Public License 2.0
* which accompanies this distribution, and is available at
* https://www.eclipse.org/legal/epl-2.0/
*
* SPDX-License-Identifier: EPL-2.0
*
* Contributors:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.ui;
import org.eclipse.ui.part.EditorPart;
/**
* Represents a source of Saveable objects (units of saveability). Workbench
* parts that show more than one unit of saveability, or whose units of
* saveability change over time, should implement this interface in order to
* provide better integration with workbench facilities like the Save command,
* prompts to save on part close or shutdown, etc.
*
* IMPORTANT: As of 3.2, implementers of ISaveablesSource must
* satisfy the following conditions:
*
*
* - If ISaveablesSource is implemented by an IWorkbenchPart:
*
* - the part must implement
ISaveablePart
* - if any of its Saveable objects are dirty, the part must return
*
true from {@link ISaveablePart#isDirty()}
* - the part must return
true from
* {@link ISaveablePart#isSaveOnCloseNeeded()} if it is dirty (the default
* behaviour implemented by {@link EditorPart})
* - the part must not implement {@link ISaveablePart2}
*
*
* - If ISaveablesSource is implemented by a non-part (possible as of 3.2.1
* and 3.3):
*
* - the Workbench's {@link ISaveablesLifecycleListener} (obtained from the
* Workbench by calling
*
workbench.getService(ISaveablesLifecycleListener.class)) must be
* notified of any change to the result of {@link #getSaveables()}
* - getActiveSaveables() should be implemented to return an empty array
*
*
*
* If any of these conditions are not met, it is undefined whether the Workbench
* will prompt to save dirty Saveables when closing parts or the Workbench.
*
*
* These conditions may be relaxed in future releases.
*
*
* @since 3.2
*/
public interface ISaveablesSource {
/**
* Returns the saveables presented by the workbench part. If the return value of
* this method changes during the lifetime of this part (i.e. after
* initialization and control creation but before disposal) the part must notify
* an implicit listener using
* {@link ISaveablesLifecycleListener#handleLifecycleEvent(SaveablesLifecycleEvent)}.
*
* Additions of saveables to the list of saveables of this part are announced
* using an event of type {@link SaveablesLifecycleEvent#POST_OPEN}. Removals
* are announced in a two-stage process, first using an event of type
* {@link SaveablesLifecycleEvent#PRE_CLOSE} followed by an event of type
* {@link SaveablesLifecycleEvent#POST_CLOSE}. Since firing the
* PRE_CLOSE event may trigger prompts to save dirty saveables, the
* cancellation status of the event must be checked by the part after the
* notification. When removing only non-dirty saveables, POST_CLOSE
* notification is sufficient.
*
*
* The listener is obtained from the part site by calling
* partSite.getService(ISaveablesLifecycleListener.class).
*
*
* The part must not notify from its initialization methods (e.g.
* init or createPartControl), or from its dispose
* method. Parts that implement {@link IReusableEditor} must notify when their
* input is changed through {@link IReusableEditor#setInput(IEditorInput)}.
*
*
* @return the saveables presented by the workbench part
*
* @see ISaveablesLifecycleListener
*/
Saveable[] getSaveables();
/**
* Returns the saveables currently active in the workbench part.
*
* Certain workbench actions, such as Save, target only the active saveables in
* the active part. For example, the active saveables could be determined based
* on the current selection in the part.
*
*
* @return the saveables currently active in the workbench part
*/
Saveable[] getActiveSaveables();
}