1 /*******************************************************************************
2  * Copyright (c) 2000, 20158 IBM Corporation and others.
3  *
4  * This program and the accompanying materials
5  * are made available under the terms of the Eclipse Public License 2.0
6  * which accompanies this distribution, and is available at
7  * https://www.eclipse.org/legal/epl-2.0/
8  *
9  * SPDX-License-Identifier: EPL-2.0
10  *
11  * Contributors:
12  *     IBM Corporation - initial API and implementation
13  *******************************************************************************/
14 
15 package org.eclipse.ui;
16 
17 import org.eclipse.jface.util.IPropertyChangeListener;
18 import org.eclipse.swt.graphics.Image;
19 
20 /**
21  * Implements a reference to a IWorkbenchPart. The IWorkbenchPart will not be
22  * instantiated until the part becomes visible or the API getPart is sent with
23  * true;
24  * <p>
25  * This interface is not intended to be implemented by clients.
26  * </p>
27  *
28  * @noimplement This interface is not intended to be implemented by clients.
29  */
30 public interface IWorkbenchPartReference {
31 	/**
32 	 * Returns the IWorkbenchPart referenced by this object.
33 	 *
34 	 * @param restore tries to restore the part if <code>true</code>.
35 	 * @return the part, or <code>null</code> if the part was not instantiated or it
36 	 *         failed to be restored.
37 	 */
getPart(boolean restore)38 	IWorkbenchPart getPart(boolean restore);
39 
40 	/**
41 	 * @return the title of the part
42 	 * @see IWorkbenchPart#getTitle
43 	 */
getTitle()44 	String getTitle();
45 
46 	/**
47 	 * @return the title image of the part
48 	 * @see IWorkbenchPart#getTitleImage
49 	 */
getTitleImage()50 	Image getTitleImage();
51 
52 	/**
53 	 * @return the title tooltip
54 	 * @see IWorkbenchPart#getTitleToolTip
55 	 */
getTitleToolTip()56 	String getTitleToolTip();
57 
58 	/**
59 	 * @return the ID of the part
60 	 * @see IWorkbenchPartSite#getId
61 	 */
getId()62 	String getId();
63 
64 	/**
65 	 * @param listener the property listener
66 	 * @see IWorkbenchPart#addPropertyListener
67 	 */
addPropertyListener(IPropertyListener listener)68 	void addPropertyListener(IPropertyListener listener);
69 
70 	/**
71 	 * @param listener the poperty listener to remove
72 	 * @see IWorkbenchPart#removePropertyListener
73 	 */
removePropertyListener(IPropertyListener listener)74 	void removePropertyListener(IPropertyListener listener);
75 
76 	/**
77 	 * @return the workbench page that contains this part
78 	 */
getPage()79 	IWorkbenchPage getPage();
80 
81 	/**
82 	 * Returns the name of the part, as it should be shown in tabs.
83 	 *
84 	 * @return the part name
85 	 *
86 	 * @since 3.0
87 	 */
getPartName()88 	String getPartName();
89 
90 	/**
91 	 * Returns the content description for the part (or the empty string if none)
92 	 *
93 	 * @return the content description for the part
94 	 *
95 	 * @since 3.0
96 	 */
getContentDescription()97 	String getContentDescription();
98 
99 	/**
100 	 * Returns whether the part is dirty (i.e. has unsaved changes).
101 	 *
102 	 * @return <code>true</code> if the part is dirty, <code>false</code> otherwise
103 	 *
104 	 * @since 3.2 (previously existed on IEditorReference)
105 	 */
isDirty()106 	boolean isDirty();
107 
108 	/**
109 	 * Return an arbitrary property from the reference. If the part has been
110 	 * instantiated, it just delegates to the part. If not, then it looks in its own
111 	 * cache of properties. If the property is not available or the part has never
112 	 * been instantiated, it can return <code>null</code>.
113 	 *
114 	 * @param key The property to return. Must not be <code>null</code>.
115 	 * @return The String property, or <code>null</code>.
116 	 * @since 3.3
117 	 */
getPartProperty(String key)118 	String getPartProperty(String key);
119 
120 	/**
121 	 * Add a listener for changes in the arbitrary properties set.
122 	 *
123 	 * @param listener Must not be <code>null</code>.
124 	 * @since 3.3
125 	 */
addPartPropertyListener(IPropertyChangeListener listener)126 	void addPartPropertyListener(IPropertyChangeListener listener);
127 
128 	/**
129 	 * Remove a listener for changes in the arbitrary properties set.
130 	 *
131 	 * @param listener Must not be <code>null</code>.
132 	 * @since 3.3
133 	 */
removePartPropertyListener(IPropertyChangeListener listener)134 	void removePartPropertyListener(IPropertyChangeListener listener);
135 }
136