|
 |
|
| |
org.eclipse.ui.presentations
Class StackPresentation
java.lang.Object
org.eclipse.ui.presentations.StackPresentation
-
All Implemented Interfaces:
-
ISizeProvider
-
public abstract class StackPresentation
- extends
Object
- implements
ISizeProvider
This represents an object that can supply trim around a IPresentablePart.
Clients can implement subclasses to provide the appearance for editor workbooks,
view folders, fast views, and detached windows.
StackPresentations do not store any persistent state and cannot
directly make changes to the workbench. They are given an IStackPresentationSite
reference on creation, which allows them to send events and requests to the workbench.
However, the workbench is free to ignore these requests. The workbench will call one
of the public methods on StackPresentation when (and if) the presentation is expected to
change state.
For example, if the user clicks a button that is intended to close a part, the
StackPresentation will send a close request to its site, but should not assume
that the part has been closed until the workbench responds with a call
StackPresentation.remove.
-
Since:
- 3.0
|
Field Summary
|
static int
|
AS_ACTIVE_FOCUS
Activation state indicating that one of the parts in the presentation currently has focus |
static int
|
AS_ACTIVE_NOFOCUS
Activation state indicating that none of the parts in the presentation have focus, but
one of the parts is being used as the context for global menus and toolbars |
static int
|
AS_INACTIVE
Inactive state. |
|
Method Summary
|
abstract void
|
addPart
(
IPresentablePart newPart,
Object cookie)
Adds the given part to the stack. |
Point
|
computeMinimumSize
()
Deprecated. replaced by computePreferredSize
|
int
|
computePreferredSize
(boolean width,
int availableParallel,
int availablePerpendicular,
int preferredResult)
Returns the best size for this part, given the available width and height and the workbench's
preferred size for the part. |
abstract void
|
dispose
()
Disposes all SWT resources being used by the stack. |
abstract
StackDropResult
|
dragOver
(
Control currentControl,
Point location)
This method is invoked whenever a part is dragged over the stack's control. |
abstract
Control
|
getControl
()
Returns the control for this presentation |
protected
IStackPresentationSite
|
getSite
()
Returns the presentation site (not null). |
int
|
getSizeFlags
(boolean width)
Returns a bitwise combination of flags indicating how and when computePreferredSize should
be used. |
abstract
Control[]
|
getTabList
(
IPresentablePart part)
Returns the tab-key traversal order for the given IPresentablePart. |
void
|
movePart
(
IPresentablePart toMove,
Object cookie)
Moves a part to a new location as the result of a drag/drop
operation within this presentation. |
abstract void
|
removePart
(
IPresentablePart oldPart)
Removes the given part from the stack. |
void
|
restoreState
(
IPresentationSerializer context,
IMemento memento)
Restores the state of this presentation to a previously saved state. |
void
|
saveState
(
IPresentationSerializer context,
IMemento memento)
Saves the state of this presentation to the given memento. |
abstract void
|
selectPart
(
IPresentablePart toSelect)
Brings the specified part to the foreground. |
abstract void
|
setActive
(int newState)
This is invoked to notify the presentation that its activation
state has changed. |
abstract void
|
setBounds
(
Rectangle bounds)
Sets the bounding rectangle for this presentation. |
abstract void
|
setState
(int state)
Sets the state of the presentation. |
abstract void
|
setVisible
(boolean isVisible)
This causes the presentation to become visible or invisible. |
abstract void
|
showPaneMenu
()
Instructs the presentation to display the pane menu |
void
|
showPartList
()
Instructs the presentation to display a list of all parts in the stack, and
allow the user to change the selection using the keyboard. |
abstract void
|
showSystemMenu
()
Instructs the presentation to display the system menu |
|
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
AS_INACTIVE
public static final int AS_INACTIVE
- Inactive state. This is the default state for deselected presentations.
-
See Also:
-
Constant Field Values
AS_ACTIVE_FOCUS
public static final int AS_ACTIVE_FOCUS
- Activation state indicating that one of the parts in the presentation currently has focus
-
See Also:
-
Constant Field Values
AS_ACTIVE_NOFOCUS
public static final int AS_ACTIVE_NOFOCUS
- Activation state indicating that none of the parts in the presentation have focus, but
one of the parts is being used as the context for global menus and toolbars
-
See Also:
-
Constant Field Values
StackPresentation
protected StackPresentation(
IStackPresentationSite stackSite)
- Constructs a new stack presentation with the given site.
-
Parameters:
-
stackSite - the stack site
getSite
protected
IStackPresentationSite getSite()
- Returns the presentation site (not null).
-
-
-
Returns:
- IStackPresentationSite
setBounds
public abstract void setBounds(
Rectangle bounds)
- Sets the bounding rectangle for this presentation.
-
-
-
Parameters:
-
bounds - new bounding rectangle (not null)
computeMinimumSize
public
Point computeMinimumSize()
-
Deprecated. replaced by computePreferredSize
- Returns the minimum size for this stack. The stack is prevented
from being resized smaller than this amount, and this is used as
the default size for the stack when it is minimized. Typically,
this is the amount of space required to fit the minimize, close,
and maximize buttons and one tab.
-
-
-
Returns:
- the minimum size for this stack (not null)
getSizeFlags
public int getSizeFlags(boolean width)
-
Description copied from interface:
ISizeProvider
- Returns a bitwise combination of flags indicating how and when computePreferredSize should
be used. When called with horizontal=true, this indicates the usage of computePreferredSize(true,...)
for computing widths. When called with horizontal=false, this indicates the usage of computeSize(false,...)
for computing heights. These flags are used for optimization. Each flag gives the part more control
over its preferred size but slows down the layout algorithm. Parts should return the minimum set
of flags necessary to specify their constraints.
If the return value of this function ever changes, the part must call flushLayout before
the changes will take effect.
- SWT.MAX: The part has a maximum size that will be returned by computePreferredSize(horizontal,
INFINITE, someWidth, INFINITE)
- SWT.MIN: The part has a minimum size that will be returned by computePreferredSize(horizontal,
INFINITE, someWidth, 0)
- SWT.WRAP: Indicates that computePreferredSize makes use of the availablePerpendicular argument. If this
flag is not specified, then the third argument to computePreferredSize will always be set to
INFINITE. The perpendicular size is expensive to compute, and it is usually only used
for wrapping parts.
- SWT.FILL: The part may not return the preferred size verbatim when computePreferredSize is
is given a value between the minimum and maximum sizes. This is commonly used if the part
wants to use a set of predetermined sizes instead of using the workbench-provided size.
For example, computePreferredSize(horizontal, availableSpace, someWidth,
preferredSize) may return the nearest predetermined size. Note that this flag should
be used sparingly. It can prevent layout caching and cause the workbench layout algorithm
to degrade to exponential worst-case runtime. If this flag is omitted, then
computePreferredSize may be used to compute the minimum and maximum sizes, but not for
anything in between.
-
-
Specified by:
-
getSizeFlags
in interface
ISizeProvider
-
-
Parameters:
-
width - a value of true or false determines whether the return value applies when computing
widths or heights respectively. That is, getSizeFlags(true) will be used when calling
computePreferredSize(true,...)
-
Returns:
- any bitwise combination of SWT.MAX, SWT.MIN, SWT.WRAP, and SWT.FILL
computePreferredSize
public int computePreferredSize(boolean width,
int availableParallel,
int availablePerpendicular,
int preferredResult)
-
Description copied from interface:
ISizeProvider
-
Returns the best size for this part, given the available width and height and the workbench's
preferred size for the part. Parts can overload this to enforce a minimum size, maximum size,
or a quantized set of preferred sizes. If width == true, this method computes a width in pixels.
If width == false, this method computes a height. availableParallel and availablePerpendicular
contain the space available, and preferredParallel contains the preferred result.
This method returns an answer that is less than or equal to availableParallel and as
close to preferredParallel as possible. Return values larger than availableParallel will
be truncated.
Most presentations will define a minimum size at all times, and a maximum size that only applies
when maximized.
The getSizeFlags method controls how frequently this method will be called and what information
will be available when it is. Any subclass that specializes this method should also specialize
getSizeFlags. computePreferredSize(width, INFINITE, someSize, 0) returns
the minimum size of the control (if any). computePreferredSize(width, INFINITE, someSize,
INFINITE) returns the maximum size of the control.
Examples:
- To maintain a constant size of 100x300 pixels: {return width ? 100 : 300}, getSizeFlags(boolean) must
return SWT.MIN | SWT.MAX
- To grow without constraints: {return preferredResult;}, getSizeFlags(boolean) must return 0.
- To enforce a width that is always a multiple of 100 pixels, to a minimum of 100 pixels:
{
if (width && preferredResult != INFINITE) {
int result = preferredResult - ((preferredResult + 50) % 100) + 50;
result = Math.max(100, Math.min(result, availableParallel - (availableParallel % 100)));
return result;
}
return preferredResult;
}
In this case, getSizeFlags(boolean width) must return (width ? SWT.FILL | SWT.MIN: 0)
- To maintain a minimum area of 100000 pixels:
{return availablePerpendicular < 100 ? 1000 : 100000 / availablePerpendicular;}
getSizeFlags(boolean width) must return SWT.WRAP | SWT.MIN;
-
-
Specified by:
-
computePreferredSize
in interface
ISizeProvider
-
-
Parameters:
-
width - indicates whether a width (=true) or a height (=false) is being computed -
availableParallel - available space. This is a width (pixels) if width == true, and a height (pixels)
if width == false. A return value larger than this will be ignored. -
availablePerpendicular - available space perpendicular to the direction being measured
or INFINITE if unbounded (pixels). This
is a height if width == true, or a height if width == false. Implementations will generally ignore this
argument unless they contain wrapping widgets. Note this argument will only contain meaningful information
if the part returns the SWT.WRAP flag from getSizeFlags(width) -
preferredResult - preferred size of the control (pixels, <= availableParallel). Set to
INFINITE if unknown or unbounded.
-
Returns:
- returns the preferred size of the control (pixels). This is a width if width == true or a height
if width == false. Callers are responsible for rounding down the return value if it is larger than
availableParallel. If availableParallel is INFINITE, then a return value of INFINITE
is permitted, indicating that the preferred size of the control is unbounded.
-
See Also:
-
ISizeProvider.getSizeFlags(boolean)
dispose
public abstract void dispose()
- Disposes all SWT resources being used by the stack. This is the
last method that will be invoked on the stack.
-
-
setActive
public abstract void setActive(int newState)
- This is invoked to notify the presentation that its activation
state has changed. StackPresentations can have three possible activation
states (see the AS_* constants above)
-
-
-
Parameters:
-
newState - one of AS_INACTIVE, AS_ACTIVE, or AS_ACTIVE_NOFOCUS
setVisible
public abstract void setVisible(boolean isVisible)
- This causes the presentation to become visible or invisible.
When a presentation is invisible, it must not respond to user
input or modify its parts. For example, a presentations will
be made invisible if it belongs to a perspective and the user
switches to another perspective.
-
-
-
Parameters:
-
isVisible - the state to set visibility to -
Since:
- 3.0
setState
public abstract void setState(int state)
- Sets the state of the presentation. That is, notifies the presentation
that is has been minimized, maximized, or restored. Note that this method
is the only way that a presentation is allowed to change its state.
If a presentation wishes to minimize itself, it must call setState
on its associated IStackPresentationSite. If the site chooses to respond
to the state change, it will call this method at the correct time.
The presentation should not call this method directly.
-
-
-
Parameters:
-
state - one of the IStackPresentationSite.STATE_* constants.
getControl
public abstract
Control getControl()
- Returns the control for this presentation
-
-
-
Returns:
- the control for this presentation (not null)
addPart
public abstract void addPart(
IPresentablePart newPart,
Object cookie)
- Adds the given part to the stack. The presentation is free to determine
where the part should be inserted. If the part is being inserted as the
result of a drag/drop operation, it will be given a cookie
identifying the drop location. Has no effect if an identical part is
already in the presentation.
-
-
-
Parameters:
-
newPart - the new part to add (not null) -
cookie - an identifier for a drop location, or null. When the presentation
attaches a cookie to a StackDropResult, that cookie is passed back into
addPart when a part is actually dropped in that location.
removePart
public abstract void removePart(
IPresentablePart oldPart)
- Removes the given part from the stack.
-
-
-
Parameters:
-
oldPart - the part to remove (not null)
movePart
public void movePart(
IPresentablePart toMove,
Object cookie)
- Moves a part to a new location as the result of a drag/drop
operation within this presentation.
-
-
-
Parameters:
-
toMove - a part that already belongs to this presentation -
cookie - a drop cookie returned by StackPresentation#dragOver
-
Since:
- 3.1
selectPart
public abstract void selectPart(
IPresentablePart toSelect)
- Brings the specified part to the foreground. This should not affect
the current focus.
-
-
-
Parameters:
-
toSelect - the new active part (not null)
dragOver
public abstract
StackDropResult dragOver(
Control currentControl,
Point location)
- This method is invoked whenever a part is dragged over the stack's control.
It returns a StackDropResult if and only if the part may be dropped in this
location.
-
-
-
Parameters:
-
currentControl - the control being dragged over -
location - cursor location (display coordinates)
-
Returns:
- a StackDropResult or null if the presentation does not have
a drop target in this location.
showSystemMenu
public abstract void showSystemMenu()
- Instructs the presentation to display the system menu
-
-
showPaneMenu
public abstract void showPaneMenu()
- Instructs the presentation to display the pane menu
-
-
showPartList
public void showPartList()
- Instructs the presentation to display a list of all parts in the stack, and
allow the user to change the selection using the keyboard.
-
-
saveState
public void saveState(
IPresentationSerializer context,
IMemento memento)
- Saves the state of this presentation to the given memento.
-
-
-
Parameters:
-
context - object that can be used to generate unique IDs for IPresentableParts (this
may be a temporary object - the presentation should not keep any references to it) -
memento - memento where the data will be saved
restoreState
public void restoreState(
IPresentationSerializer context,
IMemento memento)
- Restores the state of this presentation to a previously saved state.
-
-
-
Parameters:
-
context - object that can be used to find IPresentableParts given string IDs (this
may be a temporary object - the presentation should not keep any references to it) -
memento - memento where the data will be saved
getTabList
public abstract
Control[] getTabList(
IPresentablePart part)
- Returns the tab-key traversal order for the given
IPresentablePart.
-
-
-
Parameters:
-
part - the part
-
Returns:
- the tab-key traversal order
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
|
|
|
