Eclipse RAP Development Guide (Galileo) - Shell (Eclipse Rich Ajax Platform API Specification)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Rich Ajax Platform
Release 1.2

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.swt.widgets
Class Shell


java.lang.Object
  

org.eclipse.swt.widgets.Widget
      

org.eclipse.swt.widgets.Control
          

org.eclipse.swt.widgets.Scrollable
              

org.eclipse.swt.widgets.Composite
                  

org.eclipse.swt.widgets.Canvas
                      

org.eclipse.swt.widgets.Decorations
                          
org.eclipse.swt.widgets.Shell

All Implemented Interfaces:: Adaptable

public class Shell
extends Decorations

Instances of this class represent the "windows" which the desktop or "window manager" is managing. Instances that do not have a parent (that is, they are built using the constructor, which takes a Display as the argument) are described as top level shells. Instances that do have a parent are described as secondary or dialog shells.

Instances are always displayed in one of the maximized, minimized or normal states:

When an instance is marked as maximized, the window manager will typically resize it to fill the entire visible area of the display, and the instance is usually put in a state where it can not be resized (even if it has style RESIZE) until it is no longer maximized.
When an instance is in the normal state (neither maximized or minimized), its appearance is controlled by the style constants which were specified when it was created and the restrictions of the window manager (see below).
When an instance has been marked as minimized, its contents (client area) will usually not be visible, and depending on the window manager, it may be "iconified" (that is, replaced on the desktop by a small simplified representation of itself), relocated to a distinguished area of the screen, or hidden. Combinations of these changes are also possible.

The modality of an instance may be specified using style bits. The modality style bits are used to determine whether input is blocked for other shells on the display. The PRIMARY_MODAL style allows an instance to block input to its parent. The APPLICATION_MODAL style allows an instance to block input to every other shell in the display. The SYSTEM_MODAL style allows an instance to block input to all shells, including shells belonging to different applications.

Note: The styles supported by this class are treated as HINTs, since the window manager for the desktop on which the instance is visible has ultimate control over the appearance and behavior of decorations and modality. For example, some window managers only support resizable windows and will always assume the RESIZE style, even if it is not set. In addition, if a modality style is not supported, it is "upgraded" to a more restrictive modality style that is supported. For example, if PRIMARY_MODAL is not supported, it would be upgraded to APPLICATION_MODAL. A modality style may also be "downgraded" to a less restrictive style. For example, most operating systems no longer support SYSTEM_MODAL because it can freeze up the desktop, so this is typically downgraded to APPLICATION_MODAL.

Styles:: BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL; APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL
Events:: Activate, Close, Deactivate, Deiconify, Iconify

Class SWT provides two "convenience constants" for the most commonly required style combinations:

SHELL_TRIM: the result of combining the constants which are required to produce a typical application top level shell: (that is, CLOSE | TITLE | MIN | MAX | RESIZE)
DIALOG_TRIM: the result of combining the constants which are required to produce a typical application dialog shell: (that is, TITLE | CLOSE | BORDER)

Note: Only one of the styles APPLICATION_MODAL, MODELESS, PRIMARY_MODAL and SYSTEM_MODAL may be specified.

IMPORTANT: This class is not intended to be subclassed.

See Also:: SWT

Constructor Summary

Shell ( Display display)
          Constructs a new instance of this class given only the display to create it on.

Shell ( Display display, int style)
          Constructs a new instance of this class given the display to create it on and a style value describing its behavior and appearance.

Shell (int style)
          Constructs a new instance of this class given only the style value describing its behavior and appearance.

Shell ( Shell parent)
          Constructs a new instance of this class given only its parent.

Shell ( Shell parent, int style)
          Constructs a new instance of this class given its parent and a style value describing its behavior and appearance.

Method Summary

void addShellListener ( ShellListener listener)
          Adds the listener to the collection of listeners who will be notified when operations are performed on the receiver, by sending the listener one of the messages defined in the ShellListener interface.

void close ()
          Requests that the window manager close the receiver in the same way it would be closed when the user clicks on the "close box" or performs some other platform specific key or mouse combination that indicates the window should be removed.

Rectangle computeTrim (int x, int y, int width, int height)
          Given a desired client area for the receiver (as described by the arguments), returns the bounding rectangle which would be required to produce that client area.

void forceActive ()
          If the receiver is visible, moves it to the top of the drawing order for the display on which it was created (so that all other shells on that display, which are not the receiver's children will be drawn behind it) and forces the window manager to make the shell active.

Object getAdapter ( Class adapter)
          Implementation of the Adaptable interface.

int getAlpha ()
          Returns the receiver's alpha value.

Rectangle getClientArea ()
          Returns a rectangle which describes the area of the receiver which is capable of displaying data (that is, not covered by the "trimmings").

Button getDefaultButton ()
          Returns the receiver's default button if one had previously been set, otherwise returns null.

Image getImage ()
          Returns the receiver's image if it had previously been set using setImage().

boolean getMaximized ()
          Returns true if the receiver is currently maximized, and false otherwise.

boolean getMinimized ()
          Returns true if the receiver is currently minimized, and false otherwise.

Shell getShell ()
          Returns the receiver's shell.

Shell[] getShells ()
          Returns an array containing all shells which are descendents of the receiver.

String getText ()
          Returns the receiver's text, which is the string that the window manager will typically display as the receiver's title.

boolean isEnabled ()
          Returns true if the receiver is enabled and all ancestors up to and including the receiver's nearest ancestor shell are enabled.

boolean isVisible ()
          Returns true if the receiver is visible and all ancestors up to and including the receiver's nearest ancestor shell are visible.

void open ()
          Moves the receiver to the top of the drawing order for the display on which it was created (so that all other shells on that display, which are not the receiver's children will be drawn behind it), marks it visible, sets the focus and asks the window manager to make the shell active.

void removeShellListener ( ShellListener listener)
          Removes the listener from the collection of listeners who will be notified when operations are performed on the receiver.

void setActive ()
          If the receiver is visible, moves it to the top of the drawing order for the display on which it was created (so that all other shells on that display, which are not the receiver's children will be drawn behind it) and asks the window manager to make the shell active

void setAlpha (int alpha)
          Sets the receiver's alpha value.

void setDefaultButton ( Button button)
          If the argument is not null, sets the receiver's default button to the argument, and if the argument is null, sets the receiver's default button to the first button which was set as the receiver's default button (called the saved default button).

void setEnabled (boolean enabled)
          Enables the receiver if the argument is true, and disables it otherwise.

void setImage ( Image image)
          Sets the receiver's image to the argument, which may be null.

void setMaximized (boolean maximized)
          Sets the maximized state of the receiver.

void setMinimized (boolean minimized)
          Sets the minimized stated of the receiver.

void setText ( String text)
          Sets the receiver's text, which is the string that the window manager will typically display as the receiver's title, to the argument, which must not be null.

void setVisible (boolean visible)
          Marks the receiver as visible if the argument is true, and marks it invisible otherwise.

Methods inherited from class org.eclipse.swt.widgets. Decorations

getMenuBar, setMenuBar

Methods inherited from class org.eclipse.swt.widgets. Composite

changed, computeSize, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, setBackgroundMode, setFocus, setLayout, setTabList

Methods inherited from class org.eclipse.swt.widgets. Control

addControlListener, addFocusListener, addKeyListener, addMouseListener, addTraverseListener, computeSize, forceFocus, getBackground, getBackgroundImage, getBorderWidth, getBounds, getCursor, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getParent, getSize, getToolTipText, getVisible, isFocusControl, moveAbove, moveBelow, pack, pack, redraw, removeControlListener, removeFocusListener, removeKeyListener, removeMouseListener, removeTraverseListener, setBackground, setBackgroundImage, setBounds, setBounds, setCursor, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setRedraw, setSize, setSize, setToolTipText, toControl, toControl, toDisplay, toDisplay

Methods inherited from class org.eclipse.swt.widgets. Widget

addDisposeListener, addListener, checkSubclass, checkWidget, dispose, getData, getData, getDisplay, getStyle, isDisposed, notifyListeners, removeDisposeListener, removeListener, setData, setData, toString

Methods inherited from class java.lang. Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Shell

public Shell(int style)

Constructs a new instance of this class given only the style value describing its behavior and appearance. This is equivalent to calling Shell((Display) null, style).

The style value is either one of the style constants defined in class SWT which is applicable to instances of this class, or must be built by bitwise OR'ing together (that is, using the int "|" operator) two or more of those SWT style constants. The class description lists the style constants that are applicable to the class. Style bits are also inherited from superclasses.

Parameters:

style - the style of control to construct

Throws:

SWTException -

ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

SWT.BORDER, SWT.CLOSE, SWT.MIN, SWT.MAX, SWT.RESIZE, SWT.TITLE, SWT.NO_TRIM, SWT.SHELL_TRIM, ,

Shell

public Shell(
Display display)

Constructs a new instance of this class given only the display to create it on. It is created with style SWT.SHELL_TRIM.

Note: Currently, null can be passed in for the display argument. This has the effect of creating the shell on the currently active display if there is one. If there is no current display, the shell is created on a "default" display. Passing in null as the display argument is not considered to be good coding style, and may not be supported in a future release of SWT.

Parameters:

display - the display to create the shell on

Throws:

SWTException -

ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

Shell

public Shell(
Display display,
             int style)

Constructs a new instance of this class given the display to create it on and a style value describing its behavior and appearance.

Parameters:

display - the display to create the shell on

style - the style of control to construct

Throws:

SWTException -

ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

See Also:

SWT.BORDER, SWT.CLOSE, SWT.MIN, SWT.MAX, SWT.RESIZE, SWT.TITLE, SWT.NO_TRIM, SWT.SHELL_TRIM, ,

Shell

public Shell(
Shell parent)

Constructs a new instance of this class given only its parent. It is created with style SWT.DIALOG_TRIM.

Note: Currently, null can be passed in for the parent. This has the effect of creating the shell on the currently active display if there is one. If there is no current display, the shell is created on a "default" display. Passing in null as the parent is not considered to be good coding style, and may not be supported in a future release of SWT.

Parameters:

parent - a shell which will be the parent of the new instance

Throws:


IllegalArgumentException

ERROR_INVALID_ARGUMENT - if the parent is disposed

SWTException -

ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

Shell

public Shell(
Shell parent,
             int style)

Constructs a new instance of this class given its parent and a style value describing its behavior and appearance.

Parameters:

parent - a shell which will be the parent of the new instance

style - the style of control to construct

Throws:


IllegalArgumentException

ERROR_INVALID_ARGUMENT - if the parent is disposed

SWTException -

ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass

Method Detail

getShell

public 
Shell getShell()

Description copied from class: Control

Returns the receiver's shell. For all controls other than shells, this simply returns the control's nearest ancestor shell. Shells return themselves, even if they are children of other shells.

Overrides:: getShell in class Control

Returns:: the receiver's shell
See Also:: Control.getParent()

getShells

public 
Shell[] getShells()

Returns an array containing all shells which are descendents of the receiver.

Returns:

the dialog shells

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setActive

public void setActive()

If the receiver is visible, moves it to the top of the drawing order for the display on which it was created (so that all other shells on that display, which are not the receiver's children will be drawn behind it) and asks the window manager to make the shell active

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

forceActive

public void forceActive()

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

Since:

1.2

getClientArea

public 
Rectangle getClientArea()

Description copied from class: Scrollable

Returns a rectangle which describes the area of the receiver which is capable of displaying data (that is, not covered by the "trimmings").

Overrides:: getClientArea in class Scrollable

Returns:: the client area
See Also:: Scrollable.computeTrim(int, int, int, int)

computeTrim

public 
Rectangle computeTrim(int x,
                             int y,
                             int width,
                             int height)

Description copied from class: Scrollable

Given a desired client area for the receiver (as described by the arguments), returns the bounding rectangle which would be required to produce that client area.

In other words, it returns a rectangle such that, if the receiver's bounds were set to that rectangle, the area of the receiver which is capable of displaying data (that is, not covered by the "trimmings") would be the rectangle described by the arguments (relative to the receiver's parent).

Overrides:: computeTrim in class Scrollable

Parameters:: x - the desired x coordinate of the client area; y - the desired y coordinate of the client area; width - the desired width of the client area; height - the desired height of the client area
Returns:: the required bounds to produce the given client area
See Also:: Scrollable.getClientArea()

getAdapter

public 
Object getAdapter(
Class adapter)

Description copied from class: Widget

Implementation of the Adaptable interface.

IMPORTANT: This method is not part of the RWT public API. It is marked public only so that it can be shared within the packages provided by RWT. It should never be accessed from application code.

Specified by:: getAdapter in interface Adaptable
Overrides:: getAdapter in class Decorations

setEnabled

public void setEnabled(boolean enabled)

Description copied from class: Control

Enables the receiver if the argument is true, and disables it otherwise. A disabled control is typically not selectable from the user interface and draws with an inactive or "grayed" look.

Overrides:: setEnabled in class Control

Parameters:: enabled - the new enabled state

isEnabled

public boolean isEnabled()

Description copied from class: Control

Returns true if the receiver is enabled and all ancestors up to and including the receiver's nearest ancestor shell are enabled. Otherwise, false is returned. A disabled control is typically not selectable from the user interface and draws with an inactive or "grayed" look.

Overrides:: isEnabled in class Control

Returns:: the receiver's enabled state
See Also:: Control.getEnabled()

isVisible

public boolean isVisible()

Description copied from class: Control

Returns true if the receiver is visible and all ancestors up to and including the receiver's nearest ancestor shell are visible. Otherwise, false is returned.

Overrides:: isVisible in class Control

Returns:: the receiver's visibility state
See Also:: Control.getVisible()

setVisible

public void setVisible(boolean visible)

Description copied from class: Control

Marks the receiver as visible if the argument is true, and marks it invisible otherwise.

If one of the receiver's ancestors is not visible or some other condition makes the receiver not visible, marking it visible may not actually cause it to be displayed.

Overrides:: setVisible in class Control

Parameters:: visible - the new visibility state

open

public void open()

Moves the receiver to the top of the drawing order for the display on which it was created (so that all other shells on that display, which are not the receiver's children will be drawn behind it), marks it visible, sets the focus and asks the window manager to make the shell active.

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

close

public void close()

Requests that the window manager close the receiver in the same way it would be closed when the user clicks on the "close box" or performs some other platform specific key or mouse combination that indicates the window should be removed.

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

SWT.Close, Widget.dispose()

setText

public void setText(
String text)

Sets the receiver's text, which is the string that the window manager will typically display as the receiver's title, to the argument, which must not be null.

Parameters:

text - the new text

Throws:


IllegalArgumentException

ERROR_NULL_ARGUMENT - if the text is null

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

getText

public 
String getText()

Returns the receiver's text, which is the string that the window manager will typically display as the receiver's title. If the text has not previously been set, returns an empty string.

Returns:

the text

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setImage

public void setImage(
Image image)

Sets the receiver's image to the argument, which may be null. The image is typically displayed by the window manager when the instance is marked as iconified, and may also be displayed somewhere in the trim when the instance is in normal or maximized states.

Parameters:

image - the new image (or null)

Throws:


IllegalArgumentException

ERROR_INVALID_ARGUMENT - if the image has been disposed

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

getImage

public 
Image getImage()

Returns the receiver's image if it had previously been set using setImage(). The image is typically displayed by the window manager when the instance is marked as iconified, and may also be displayed somewhere in the trim when the instance is in normal or maximized states.

Note: This method will return null if called before setImage() is called. It does not provide access to a window manager provided, "default" image even if one exists.

Returns:

the image

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setDefaultButton

public void setDefaultButton(
Button button)

If the argument is not null, sets the receiver's default button to the argument, and if the argument is null, sets the receiver's default button to the first button which was set as the receiver's default button (called the saved default button). If no default button had previously been set, or the saved default button was disposed, the receiver's default button will be set to null.

The default button is the button that is selected when the receiver is active and the user presses ENTER.

Parameters:

button - the new default button

Throws:


IllegalArgumentException

ERROR_INVALID_ARGUMENT - if the button has been disposed
ERROR_INVALID_PARENT - if the control is not in the same widget tree

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

getDefaultButton

public 
Button getDefaultButton()

Returns the receiver's default button if one had previously been set, otherwise returns null.

Returns:

the default button or null

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

setDefaultButton(Button)

setAlpha

public void setAlpha(int alpha)

Sets the receiver's alpha value.

This operation may not be available on some platforms.

Parameters:

alpha - the alpha value

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

Since:

1.1

getAlpha

public int getAlpha()

Returns the receiver's alpha value.

Returns:

the alpha value

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

Since:

1.1

addShellListener

public void addShellListener(
ShellListener listener)

Adds the listener to the collection of listeners who will be notified when operations are performed on the receiver, by sending the listener one of the messages defined in the ShellListener interface.

Parameters:

listener - the listener which should be notified

Throws:


IllegalArgumentException

ERROR_NULL_ARGUMENT - if the listener is null

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

removeShellListener

public void removeShellListener(
ShellListener listener)

Removes the listener from the collection of listeners who will be notified when operations are performed on the receiver.

Parameters:

listener - the listener which should no longer be notified

Throws:


IllegalArgumentException

ERROR_NULL_ARGUMENT - if the listener is null

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

setMinimized

public void setMinimized(boolean minimized)

Sets the minimized stated of the receiver. If the argument is true causes the receiver to switch to the minimized state, and if the argument is false and the receiver was previously minimized, causes the receiver to switch back to either the maximized or normal states.

Parameters:

minimized - the new maximized state

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

setMaximized(boolean)

setMaximized

public void setMaximized(boolean maximized)

Sets the maximized state of the receiver. If the argument is true causes the receiver to switch to the maximized state, and if the argument is false and the receiver was previously maximized, causes the receiver to switch back to either the minimized or normal states.

Parameters:

maximized - the new maximized state

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

setMinimized(boolean)

getMinimized

public boolean getMinimized()

Returns true if the receiver is currently minimized, and false otherwise.

Returns:

the minimized state

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

setMinimized(boolean)

getMaximized

public boolean getMaximized()

Returns true if the receiver is currently maximized, and false otherwise.

Returns:

the maximized state

Throws:

SWTException -

ERROR_WIDGET_DISPOSED - if the receiver has been disposed
ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

setMaximized(boolean)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

Eclipse Rich Ajax Platform
Release 1.2

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.eclipse.swt.widgets Class Shell

Shell

Shell

Shell

Shell

Shell

getShell

getShells

setActive

forceActive

getClientArea

computeTrim

getAdapter

setEnabled

isEnabled

isVisible

setVisible

open

close

setText

getText

setImage

getImage

setDefaultButton

getDefaultButton

setAlpha

getAlpha

addShellListener

removeShellListener

setMinimized

setMaximized

getMinimized

getMaximized

org.eclipse.swt.widgets
Class Shell