001: /*******************************************************************************
002: * Copyright (c) 2004, 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.presentations;
011:
012: import org.eclipse.core.runtime.Assert;
013: import org.eclipse.jface.util.Geometry;
014: import org.eclipse.swt.SWT;
015: import org.eclipse.swt.graphics.Point;
016: import org.eclipse.swt.graphics.Rectangle;
017: import org.eclipse.swt.widgets.Control;
018: import org.eclipse.ui.IMemento;
019: import org.eclipse.ui.ISizeProvider;
020:
021: /**
022: * This represents an object that can supply trim around a IPresentablePart.
023: * Clients can implement subclasses to provide the appearance for editor workbooks,
024: * view folders, fast views, and detached windows.
025: * <p>
026: * StackPresentations do not store any persistent state and cannot
027: * directly make changes to the workbench. They are given an IStackPresentationSite
028: * reference on creation, which allows them to send events and requests to the workbench.
029: * However, the workbench is free to ignore these requests. The workbench will call one
030: * of the public methods on StackPresentation when (and if) the presentation is expected to
031: * change state.
032: * </p>
033: * <p>
034: * For example, if the user clicks a button that is intended to close a part, the
035: * StackPresentation will send a close request to its site, but should not assume
036: * that the part has been closed until the workbench responds with a call
037: * <code>StackPresentation.remove</code>.
038: * </p>
039: *
040: * @since 3.0
041: */
042: public abstract class StackPresentation implements ISizeProvider {
043:
044: /**
045: * Inactive state. This is the default state for deselected presentations.
046: */
047: public static final int AS_INACTIVE = 0;
048:
049: /**
050: * Activation state indicating that one of the parts in the presentation currently has focus
051: */
052: public static final int AS_ACTIVE_FOCUS = 1;
053:
054: /**
055: * Activation state indicating that none of the parts in the presentation have focus, but
056: * one of the parts is being used as the context for global menus and toolbars
057: */
058: public static final int AS_ACTIVE_NOFOCUS = 2;
059:
060: /**
061: * The presentation site.
062: */
063: private IStackPresentationSite site;
064:
065: /**
066: * Constructs a new stack presentation with the given site.
067: *
068: * @param stackSite the stack site
069: */
070: protected StackPresentation(IStackPresentationSite stackSite) {
071: Assert.isNotNull(stackSite);
072: site = stackSite;
073: }
074:
075: /**
076: * Returns the presentation site (not null).
077: * @return IStackPresentationSite
078: */
079: protected IStackPresentationSite getSite() {
080: return site;
081: }
082:
083: /**
084: * Sets the bounding rectangle for this presentation.
085: *
086: * @param bounds new bounding rectangle (not null)
087: */
088: public abstract void setBounds(Rectangle bounds);
089:
090: /**
091: * Returns the minimum size for this stack. The stack is prevented
092: * from being resized smaller than this amount, and this is used as
093: * the default size for the stack when it is minimized. Typically,
094: * this is the amount of space required to fit the minimize, close,
095: * and maximize buttons and one tab.
096: *
097: * @return the minimum size for this stack (not null)
098: *
099: * @deprecated replaced by computePreferredSize
100: */
101: public Point computeMinimumSize() {
102: return new Point(0, 0);
103: }
104:
105: /*
106: * @see ISizeProvider#getSizeFlags(boolean)
107: */
108: public int getSizeFlags(boolean width) {
109: boolean hasMaximumSize = getSite().getState() == IStackPresentationSite.STATE_MINIMIZED;
110:
111: return SWT.MIN | (hasMaximumSize ? SWT.MAX : 0);
112: }
113:
114: /*
115: * @see ISizeProvider#computePreferredSize(boolean, int, int, int)
116: */
117: public int computePreferredSize(boolean width,
118: int availableParallel, int availablePerpendicular,
119: int preferredResult) {
120: int minSize = Geometry.getCoordinate(computeMinimumSize(),
121: width);
122:
123: if (getSite().getState() == IStackPresentationSite.STATE_MINIMIZED
124: || preferredResult < minSize) {
125: return minSize;
126: }
127:
128: return preferredResult;
129: }
130:
131: /**
132: * Disposes all SWT resources being used by the stack. This is the
133: * last method that will be invoked on the stack.
134: */
135: public abstract void dispose();
136:
137: /**
138: * This is invoked to notify the presentation that its activation
139: * state has changed. StackPresentations can have three possible activation
140: * states (see the AS_* constants above)
141: *
142: * @param newState one of AS_INACTIVE, AS_ACTIVE, or AS_ACTIVE_NOFOCUS
143: */
144: public abstract void setActive(int newState);
145:
146: /**
147: * This causes the presentation to become visible or invisible.
148: * When a presentation is invisible, it must not respond to user
149: * input or modify its parts. For example, a presentations will
150: * be made invisible if it belongs to a perspective and the user
151: * switches to another perspective.
152: *
153: * @param isVisible the state to set visibility to
154: *
155: * @since 3.0
156: */
157: public abstract void setVisible(boolean isVisible);
158:
159: /**
160: * Sets the state of the presentation. That is, notifies the presentation
161: * that is has been minimized, maximized, or restored. Note that this method
162: * is the only way that a presentation is allowed to change its state.
163: * <p>
164: * If a presentation wishes to minimize itself, it must call setState
165: * on its associated IStackPresentationSite. If the site chooses to respond
166: * to the state change, it will call this method at the correct time.
167: * The presentation should not call this method directly.
168: * </p>
169: *
170: * @param state one of the IStackPresentationSite.STATE_* constants.
171: */
172: public abstract void setState(int state);
173:
174: /**
175: * Returns the control for this presentation
176: *
177: * @return the control for this presentation (not null)
178: */
179: public abstract Control getControl();
180:
181: /**
182: * Adds the given part to the stack. The presentation is free to determine
183: * where the part should be inserted. If the part is being inserted as the
184: * result of a drag/drop operation, it will be given a cookie
185: * identifying the drop location. Has no effect if an identical part is
186: * already in the presentation.
187: *
188: * @param newPart the new part to add (not null)
189: * @param cookie an identifier for a drop location, or null. When the presentation
190: * attaches a cookie to a StackDropResult, that cookie is passed back into
191: * addPart when a part is actually dropped in that location.
192: */
193: public abstract void addPart(IPresentablePart newPart, Object cookie);
194:
195: /**
196: * Removes the given part from the stack.
197: *
198: * @param oldPart the part to remove (not null)
199: */
200: public abstract void removePart(IPresentablePart oldPart);
201:
202: /**
203: * Moves a part to a new location as the result of a drag/drop
204: * operation within this presentation.
205: *
206: * @param toMove a part that already belongs to this presentation
207: * @param cookie a drop cookie returned by <code>StackPresentation#dragOver</code>
208: * @since 3.1
209: */
210: public void movePart(IPresentablePart toMove, Object cookie) {
211: removePart(toMove);
212: addPart(toMove, cookie);
213:
214: if (getSite().getSelectedPart() == toMove) {
215: selectPart(toMove);
216: toMove.setFocus();
217: }
218: }
219:
220: /**
221: * Brings the specified part to the foreground. This should not affect
222: * the current focus.
223: *
224: * @param toSelect the new active part (not null)
225: */
226: public abstract void selectPart(IPresentablePart toSelect);
227:
228: /**
229: * This method is invoked whenever a part is dragged over the stack's control.
230: * It returns a StackDropResult if and only if the part may be dropped in this
231: * location.
232: *
233: * @param currentControl the control being dragged over
234: * @param location cursor location (display coordinates)
235: * @return a StackDropResult or null if the presentation does not have
236: * a drop target in this location.
237: */
238: public abstract StackDropResult dragOver(Control currentControl,
239: Point location);
240:
241: /**
242: * Instructs the presentation to display the system menu
243: *
244: */
245: public abstract void showSystemMenu();
246:
247: /**
248: * Instructs the presentation to display the pane menu
249: */
250: public abstract void showPaneMenu();
251:
252: /**
253: * Instructs the presentation to display a list of all parts in the stack, and
254: * allow the user to change the selection using the keyboard.
255: */
256: public void showPartList() {
257:
258: }
259:
260: /**
261: * Saves the state of this presentation to the given memento.
262: *
263: * @param context object that can be used to generate unique IDs for IPresentableParts (this
264: * may be a temporary object - the presentation should not keep any references to it)
265: * @param memento memento where the data will be saved
266: */
267: public void saveState(IPresentationSerializer context,
268: IMemento memento) {
269:
270: }
271:
272: /**
273: * Restores the state of this presentation to a previously saved state.
274: *
275: * @param context object that can be used to find IPresentableParts given string IDs (this
276: * may be a temporary object - the presentation should not keep any references to it)
277: * @param memento memento where the data will be saved
278: */
279: public void restoreState(IPresentationSerializer context,
280: IMemento memento) {
281:
282: }
283:
284: /**
285: * Returns the tab-key traversal order for the given <code>IPresentablePart</code>.
286: *
287: * @param part the part
288: * @return the tab-key traversal order
289: */
290: public abstract Control[] getTabList(IPresentablePart part);
291: }
|