KickJava   Java API By Example, From Geeks To Geeks.

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


1 /*******************************************************************************
2  * Copyright (c) 2006 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
12 package org.eclipse.ui;
13
14 import org.eclipse.ui.part.EditorPart;
15
16 /**
17  * Represents a source of Saveable objects (units of saveability). Workbench
18  * parts that show more than one unit of saveability, or whose units of
19  * saveability change over time, should implement this interface in order to
20  * provide better integration with workbench facilities like the Save command,
21  * prompts to save on part close or shutdown, etc.
22  * <p>
23  * IMPORTANT: As of 3.2, implementers of <code>ISaveablesSource</code> must
24  * satisfy the following conditions:
25  * <ul>
26  * <li>If ISaveablesSource is implemented by an IWorkbenchPart:
27  * <ul>
28  * <li>the part must implement <code>ISaveablePart</code></li>
29  * <li>if any of its Saveable objects are dirty, the part must return
30  * <code>true</code> from {@link ISaveablePart#isDirty()}</li>
31  * <li>the part must return <code>true</code> from
32  * {@link ISaveablePart#isSaveOnCloseNeeded()} if it is dirty (the default
33  * behaviour implemented by {@link EditorPart})</li>
34  * <li>the part must not implement {@link ISaveablePart2}</li>
35  * </ul>
36  * </li>
37  * <li>If ISaveablesSource is implemented by a non-part (possible as of 3.2.1 and 3.3):
38  * <ul>
39  * <li>the Workbench's {@link ISaveablesLifecycleListener} (obtained from the
40  * Workbench by calling
41  * <code>workbench.getService(ISaveablesLifecycleListener.class)</code>) must
42  * be notified of any change to the result of {@link #getSaveables()} </li>
43  * <li>getActiveSaveables() should be implemented to return an empty array
44  * </li>
45  * </ul>
46  * </ul>
47  * If any of these conditions are not met, it is undefined whether the Workbench
48  * will prompt to save dirty Saveables when closing parts or the Workbench.
49  * </p>
50  * <p>
51  * These conditions may be relaxed in future releases.
52  * </p>
53  *
54  * @since 3.2
55  */
56 public interface ISaveablesSource {
57
58     /**
59      * Returns the saveables presented by the workbench part. If the return
60      * value of this method changes during the lifetime of
61      * this part (i.e. after initialization and control creation but before disposal)
62      * the part must notify an implicit listener using
63      * {@link ISaveablesLifecycleListener#handleLifecycleEvent(SaveablesLifecycleEvent)}.
64      * <p>
65      * Additions of saveables to the list of saveables of this part are
66      * announced using an event of type
67      * {@link SaveablesLifecycleEvent#POST_OPEN}. Removals are announced in a
68      * two-stage process, first using an event of type
69      * {@link SaveablesLifecycleEvent#PRE_CLOSE} followed by an event of type
70      * {@link SaveablesLifecycleEvent#POST_CLOSE}. Since firing the
71      * <code>PRE_CLOSE</code> event may trigger prompts to save dirty
72      * saveables, the cancellation status of the event must be checked by the
73      * part after the notification. When removing only non-dirty saveables,
74      * <code>POST_CLOSE</code> notification is sufficient.
75      * </p>
76      * <p>
77      * The listener is obtained from the part site by calling
78      * <code>partSite.getService(ISaveablesLifecycleListener.class)</code>.
79      * </p>
80      * <p>
81      * The part must not notify from its initialization methods (e.g. <code>init</code>
82      * or <code>createPartControl</code>), or from its dispose method. Parts that
83      * implement {@link IReusableEditor} must notify when their input is changed
84      * through {@link IReusableEditor#setInput(IEditorInput)}.
85      * </p>
86      *
87      * @return the saveables presented by the workbench part
88      *
89      * @see ISaveablesLifecycleListener
90      */
91     Saveable[] getSaveables();
92
93     /**
94      * Returns the saveables currently active in the workbench part.
95      * <p>
96      * Certain workbench actions, such as Save, target only the active saveables
97      * in the active part. For example, the active saveables could be determined
98      * based on the current selection in the part.
99      * </p>
100      *
101      * @return the saveables currently active in the workbench part
102      */
103     Saveable[] getActiveSaveables();
104 }
105
Popular Tags