KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > eclipse > ui > presentations > StackPresentation


1 /*******************************************************************************
2  * Copyright (c) 2004, 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 package org.eclipse.ui.presentations;
12
13 import org.eclipse.core.runtime.Assert;
14 import org.eclipse.jface.util.Geometry;
15 import org.eclipse.swt.SWT;
16 import org.eclipse.swt.graphics.Point;
17 import org.eclipse.swt.graphics.Rectangle;
18 import org.eclipse.swt.widgets.Control;
19 import org.eclipse.ui.IMemento;
20 import org.eclipse.ui.ISizeProvider;
21
22 /**
23  * This represents an object that can supply trim around a IPresentablePart.
24  * Clients can implement subclasses to provide the appearance for editor workbooks,
25  * view folders, fast views, and detached windows.
26  * <p>
27  * StackPresentations do not store any persistent state and cannot
28  * directly make changes to the workbench. They are given an IStackPresentationSite
29  * reference on creation, which allows them to send events and requests to the workbench.
30  * However, the workbench is free to ignore these requests. The workbench will call one
31  * of the public methods on StackPresentation when (and if) the presentation is expected to
32  * change state.
33  * </p>
34  * <p>
35  * For example, if the user clicks a button that is intended to close a part, the
36  * StackPresentation will send a close request to its site, but should not assume
37  * that the part has been closed until the workbench responds with a call
38  * <code>StackPresentation.remove</code>.
39  * </p>
40  *
41  * @since 3.0
42  */
43 public abstract class StackPresentation implements ISizeProvider {
44
45     /**
46      * Inactive state. This is the default state for deselected presentations.
47      */
48     public static final int AS_INACTIVE = 0;
49
50     /**
51      * Activation state indicating that one of the parts in the presentation currently has focus
52      */
53     public static final int AS_ACTIVE_FOCUS = 1;
54
55     /**
56      * Activation state indicating that none of the parts in the presentation have focus, but
57      * one of the parts is being used as the context for global menus and toolbars
58      */
59     public static final int AS_ACTIVE_NOFOCUS = 2;
60
61     /**
62      * The presentation site.
63      */
64     private IStackPresentationSite site;
65
66     /**
67      * Constructs a new stack presentation with the given site.
68      *
69      * @param stackSite the stack site
70      */
71     protected StackPresentation(IStackPresentationSite stackSite) {
72         Assert.isNotNull(stackSite);
73         site = stackSite;
74     }
75
76     /**
77      * Returns the presentation site (not null).
78      * @return IStackPresentationSite
79      */
80     protected IStackPresentationSite getSite() {
81         return site;
82     }
83
84     /**
85      * Sets the bounding rectangle for this presentation.
86      *
87      * @param bounds new bounding rectangle (not null)
88      */
89     public abstract void setBounds(Rectangle bounds);
90
91     /**
92      * Returns the minimum size for this stack. The stack is prevented
93      * from being resized smaller than this amount, and this is used as
94      * the default size for the stack when it is minimized. Typically,
95      * this is the amount of space required to fit the minimize, close,
96      * and maximize buttons and one tab.
97      *
98      * @return the minimum size for this stack (not null)
99      *
100      * @deprecated replaced by computePreferredSize
101      */
102     public Point computeMinimumSize() {
103         return new Point(0,0);
104     }
105     
106     /*
107      * @see ISizeProvider#getSizeFlags(boolean)
108      */
109     public int getSizeFlags(boolean width) {
110         boolean hasMaximumSize = getSite().getState() == IStackPresentationSite.STATE_MINIMIZED;
111         
112         return SWT.MIN | (hasMaximumSize ? SWT.MAX : 0);
113     }
114     
115     /*
116      * @see ISizeProvider#computePreferredSize(boolean, int, int, int)
117      */
118     public int computePreferredSize(boolean width, int availableParallel, int availablePerpendicular, int preferredResult) {
119         int minSize = Geometry.getCoordinate(computeMinimumSize(), width);
120         
121         if (getSite().getState() == IStackPresentationSite.STATE_MINIMIZED || preferredResult < minSize) {
122             return minSize;
123         }
124         
125         return preferredResult;
126     }
127     
128     /**
129      * Disposes all SWT resources being used by the stack. This is the
130      * last method that will be invoked on the stack.
131      */
132     public abstract void dispose();
133
134     /**
135      * This is invoked to notify the presentation that its activation
136      * state has changed. StackPresentations can have three possible activation
137      * states (see the AS_* constants above)
138      *
139      * @param newState one of AS_INACTIVE, AS_ACTIVE, or AS_ACTIVE_NOFOCUS
140      */
141     public abstract void setActive(int newState);
142
143     /**
144      * This causes the presentation to become visible or invisible.
145      * When a presentation is invisible, it must not respond to user
146      * input or modify its parts. For example, a presentations will
147      * be made invisible if it belongs to a perspective and the user
148      * switches to another perspective.
149      *
150      * @param isVisible the state to set visibility to
151      *
152      * @since 3.0
153      */
154     public abstract void setVisible(boolean isVisible);
155
156     /**
157      * Sets the state of the presentation. That is, notifies the presentation
158      * that is has been minimized, maximized, or restored. Note that this method
159      * is the only way that a presentation is allowed to change its state.
160      * <p>
161      * If a presentation wishes to minimize itself, it must call setState
162      * on its associated IStackPresentationSite. If the site chooses to respond
163      * to the state change, it will call this method at the correct time.
164      * The presentation should not call this method directly.
165      * </p>
166      *
167      * @param state one of the IStackPresentationSite.STATE_* constants.
168      */
169     public abstract void setState(int state);
170
171     /**
172      * Returns the control for this presentation
173      *
174      * @return the control for this presentation (not null)
175      */
176     public abstract Control getControl();
177
178     /**
179      * Adds the given part to the stack. The presentation is free to determine
180      * where the part should be inserted. If the part is being inserted as the
181      * result of a drag/drop operation, it will be given a cookie
182      * identifying the drop location. Has no effect if an identical part is
183      * already in the presentation.
184      *
185      * @param newPart the new part to add (not null)
186      * @param cookie an identifier for a drop location, or null. When the presentation
187      * attaches a cookie to a StackDropResult, that cookie is passed back into
188      * addPart when a part is actually dropped in that location.
189      */
190     public abstract void addPart(IPresentablePart newPart, Object JavaDoc cookie);
191
192     /**
193      * Removes the given part from the stack.
194      *
195      * @param oldPart the part to remove (not null)
196      */
197     public abstract void removePart(IPresentablePart oldPart);
198
199     /**
200      * Moves a part to a new location as the result of a drag/drop
201      * operation within this presentation.
202      *
203      * @param toMove a part that already belongs to this presentation
204      * @param cookie a drop cookie returned by <code>StackPresentation#dragOver</code>
205      * @since 3.1
206      */
207     public void movePart(IPresentablePart toMove, Object JavaDoc cookie) {
208         removePart(toMove);
209         addPart(toMove, cookie);
210         
211         if (getSite().getSelectedPart() == toMove) {
212             selectPart(toMove);
213             toMove.setFocus();
214         }
215     }
216     
217     /**
218      * Brings the specified part to the foreground. This should not affect
219      * the current focus.
220      *
221      * @param toSelect the new active part (not null)
222      */
223     public abstract void selectPart(IPresentablePart toSelect);
224
225     /**
226      * This method is invoked whenever a part is dragged over the stack's control.
227      * It returns a StackDropResult if and only if the part may be dropped in this
228      * location.
229      *
230      * @param currentControl the control being dragged over
231      * @param location cursor location (display coordinates)
232      * @return a StackDropResult or null if the presentation does not have
233      * a drop target in this location.
234      */
235     public abstract StackDropResult dragOver(Control currentControl,
236             Point location);
237
238     /**
239      * Instructs the presentation to display the system menu
240      *
241      */
242     public abstract void showSystemMenu();
243
244     /**
245      * Instructs the presentation to display the pane menu
246      */
247     public abstract void showPaneMenu();
248
249     /**
250      * Instructs the presentation to display a list of all parts in the stack, and
251      * allow the user to change the selection using the keyboard.
252      */
253     public void showPartList() {
254
255     }
256
257     /**
258      * Saves the state of this presentation to the given memento.
259      *
260      * @param context object that can be used to generate unique IDs for IPresentableParts (this
261      * may be a temporary object - the presentation should not keep any references to it)
262      * @param memento memento where the data will be saved
263      */
264     public void saveState(IPresentationSerializer context, IMemento memento) {
265
266     }
267
268     /**
269      * Restores the state of this presentation to a previously saved state.
270      *
271      * @param context object that can be used to find IPresentableParts given string IDs (this
272      * may be a temporary object - the presentation should not keep any references to it)
273      * @param memento memento where the data will be saved
274      */
275     public void restoreState(IPresentationSerializer context, IMemento memento) {
276
277     }
278
279     /**
280      * Returns the tab-key traversal order for the given <code>IPresentablePart</code>.
281      *
282      * @param part the part
283      * @return the tab-key traversal order
284      */
285     public abstract Control[] getTabList(IPresentablePart part);
286 }
287
Popular Tags