001: /*******************************************************************************
002: * Copyright (c) 2004, 2007 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: * Stefan Xenos, IBM; Chris Torrence, ITT Visual Information Solutions - bug 51580
011: *******************************************************************************/package org.eclipse.ui.presentations;
012:
013: import org.eclipse.jface.util.IPropertyChangeListener;
014: import org.eclipse.swt.graphics.Image;
015: import org.eclipse.swt.graphics.Rectangle;
016: import org.eclipse.swt.widgets.Control;
017: import org.eclipse.ui.IPropertyListener;
018: import org.eclipse.ui.ISizeProvider;
019: import org.eclipse.ui.IWorkbenchPartConstants;
020:
021: /**
022: * This is a skin's interface to the contents of a view or editor. Note that this
023: * is essentially the same as IWorkbenchPart, except it does not provide access
024: * to lifecycle events and allows repositioning of the part.
025: *
026: * Not intended to be implemented by clients.
027: *
028: * @since 3.0
029: * @since 3.4 now extends {@link org.eclipse.ui.ISizeProvider}
030: */
031: public interface IPresentablePart extends ISizeProvider {
032:
033: /**
034: * The property id for <code>isDirty</code>.
035: */
036: public static final int PROP_DIRTY = IWorkbenchPartConstants.PROP_DIRTY;
037:
038: /**
039: * The property id for <code>getEditorInput</code>.
040: */
041: public static final int PROP_INPUT = IWorkbenchPartConstants.PROP_INPUT;
042:
043: /**
044: * The property id for <code>getTitle</code>, <code>getTitleImage</code>
045: * and <code>getTitleToolTip</code>.
046: */
047: public static final int PROP_TITLE = IWorkbenchPartConstants.PROP_TITLE;
048:
049: /**
050: * The property id for <code>IWorkbenchPart2.getContentDescription()</code>
051: */
052: public static final int PROP_CONTENT_DESCRIPTION = IWorkbenchPartConstants.PROP_CONTENT_DESCRIPTION;
053:
054: /**
055: * The property id for <code>IWorkbenchPart2.getContentDescription()</code>
056: */
057: public static final int PROP_PART_NAME = IWorkbenchPartConstants.PROP_PART_NAME;
058:
059: /**
060: * The property id for <code>isBusy</code>.
061: */
062: public static final int PROP_BUSY = 0x92;
063:
064: /**
065: * The property id for toolbar changes
066: */
067: public static final int PROP_TOOLBAR = 0x93;
068:
069: /**
070: * The property id for highlighting the
071: * part if it is not in front.
072: */
073: public static final int PROP_HIGHLIGHT_IF_BACK = 0x94;
074:
075: /**
076: * The property id for pane menu changes
077: */
078: public static final int PROP_PANE_MENU = 0x302;
079:
080: /**
081: * The property id for preferred size changes
082: */
083: public static final int PROP_PREFERRED_SIZE = IWorkbenchPartConstants.PROP_PREFERRED_SIZE;
084:
085: /**
086: * Sets the bounds of this part.
087: *
088: * @param bounds bounding rectangle (not null)
089: */
090: public void setBounds(Rectangle bounds);
091:
092: /**
093: * Notifies the part whether or not it is visible in the current
094: * perspective. A part is visible iff any part of its widgetry can
095: * be seen.
096: *
097: * @param isVisible true if the part has just become visible, false
098: * if the part has just become hidden
099: */
100: public void setVisible(boolean isVisible);
101:
102: /**
103: * Forces this part to have focus.
104: */
105: public void setFocus();
106:
107: /**
108: * Adds a listener for changes to properties of this workbench part.
109: * Has no effect if an identical listener is already registered.
110: * <p>
111: * The properties ids are defined by the PROP_* constants, above.
112: * </p>
113: *
114: * @param listener a property listener (not null)
115: */
116: public void addPropertyListener(IPropertyListener listener);
117:
118: /**
119: * Remove a listener that was previously added using addPropertyListener.
120: *
121: * @param listener a property listener (not null)
122: */
123: public void removePropertyListener(IPropertyListener listener);
124:
125: /**
126: * Returns the short name of the part. This is used as the text on
127: * the tab when this part is stacked on top of other parts.
128: *
129: * @return the short name of the part (not null)
130: */
131: public String getName();
132:
133: /**
134: * Returns the title of this workbench part. If this value changes
135: * the part must fire a property listener event with
136: * <code>PROP_TITLE</code>.
137: * <p>
138: * The title is used to populate the title bar of this part's visual
139: * container.
140: * </p>
141: *
142: * @return the workbench part title (not null)
143: */
144: public String getTitle();
145:
146: /**
147: * Returns the status message from the part's title, or the empty string if none.
148: * This is a substring of the part's title. A typical title will consist of
149: * the part name, a separator, and a status message describing the current contents.
150: * <p>
151: * Presentations can query getName() and getTitleStatus() if they want to display
152: * the status message and name separately, or they can use getTitle() if they want
153: * to display the entire title.
154: * </p>
155: *
156: * @return the status message or the empty string if none (not null)
157: */
158: public String getTitleStatus();
159:
160: /**
161: * Returns the title image of this workbench part. If this value changes
162: * the part must fire a property listener event with
163: * <code>PROP_TITLE</code>.
164: * <p>
165: * The title image is usually used to populate the title bar of this part's
166: * visual container. Since this image is managed by the part itself, callers
167: * must <b>not</b> dispose the returned image.
168: * </p>
169: *
170: * @return the title image
171: */
172: public Image getTitleImage();
173:
174: /**
175: * Returns the title tool tip text of this workbench part. If this value
176: * changes the part must fire a property listener event with
177: * <code>PROP_TITLE</code>.
178: * <p>
179: * The tool tip text is used to populate the title bar of this part's
180: * visual container.
181: * </p>
182: *
183: * @return the workbench part title tool tip (not null)
184: */
185: public String getTitleToolTip();
186:
187: /**
188: * Returns true iff the contents of this part have changed recently. For
189: * editors, this indicates that the part has changed since the last save.
190: * For views, this indicates that the view contains interesting changes
191: * that it wants to draw the user's attention to.
192: *
193: * @return true iff the part is dirty
194: */
195: public boolean isDirty();
196:
197: /**
198: * Return true if the the receiver is currently in a busy state.
199: * @return boolean true if busy
200: */
201: public boolean isBusy();
202:
203: /**
204: * Returns true iff this part can be closed
205: *
206: * @return true iff this part can be closed
207: * @since 3.1
208: */
209: public boolean isCloseable();
210:
211: /**
212: * Returns the local toolbar for this part, or null if this part does not
213: * have a local toolbar. Callers must not dispose or downcast the return value.
214: *
215: * @return the local toolbar for the part, or null if none
216: */
217: public Control getToolBar();
218:
219: /**
220: * Returns the menu for this part or null if none
221: *
222: * @return the menu for this part or null if none
223: */
224: public IPartMenu getMenu();
225:
226: /**
227: * Returns an SWT control that can be used to indicate the tab order for
228: * this part. This can be returned as part of the result to
229: * {@link StackPresentation#getTabList(IPresentablePart)}. Any other use of this control is
230: * unsupported. This may return a placeholder control that is only
231: * meaningful in the context of <code>getTabList</code>.
232: *
233: * @return the part's control (not null)
234: */
235: public Control getControl();
236:
237: /**
238: * Get a property from the part's arbitrary property set.
239: * <p>
240: * <b>Note:</b> this is a different set of properties than the ones covered
241: * by the PROP_* constants.
242: * </p>
243: *
244: * @param key
245: * The property key to retrieve. Must not be <code>null</code>.
246: * @return the property, or <code>null</code> if that property is not set.
247: * @since 3.3
248: */
249: public String getPartProperty(String key);
250:
251: /**
252: * Add a listener for changes in the arbitrary properties set.
253: * <p>
254: * <b>Note:</b> this is a different set of properties than the ones covered
255: * by the PROP_* constants.
256: * </p>
257: *
258: * @param listener
259: * Must not be <code>null</code>.
260: * @since 3.3
261: */
262: public void addPartPropertyListener(IPropertyChangeListener listener);
263:
264: /**
265: * Remove a change listener from the arbitrary properties set.
266: * <p>
267: * <b>Note:</b> this is a different set of properties than the ones covered
268: * by the PROP_* constants.
269: * </p>
270: *
271: * @param listener
272: * Must not be <code>null</code>.
273: * @since 3.3
274: */
275: public void removePartPropertyListener(
276: IPropertyChangeListener listener);
277: }
|