org.eclipse.swt.widgets
Class Shell

java.lang.Object
  extended by org.eclipse.swt.widgets.Widget
      extended by org.eclipse.swt.widgets.Control
          extended by org.eclipse.swt.widgets.Scrollable
              extended by org.eclipse.swt.widgets.Composite
                  extended by org.eclipse.swt.widgets.Canvas
                      extended by org.eclipse.swt.widgets.Decorations
                          extended by org.eclipse.swt.widgets.Shell
All Implemented Interfaces:
Drawable
Direct Known Subclasses:
MobileShell, MultiPageDialog.MultiPageShell

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:

Note: The styles supported by this class must be 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.

Styles:
BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE
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:
Decorations, SWT

Field Summary
 
Fields inherited from class org.eclipse.swt.widgets.Control
enableTraverse, internal_parent
 
Fields inherited from class org.eclipse.swt.widgets.Widget
internal_handle, internal_style
 
Constructor Summary
Shell()
          Constructs a new instance of this class.
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.
 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.
 int getImeInputMode()
          Returns the receiver's input method editor mode.
 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.
protected  void internal_createHandle(int index)
           
protected  int internal_getNativeStyle()
           
protected  boolean isValidSubclass()
           
 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 setImage(Image image)
          Sets the receiver's image to the argument, which may be null.
 void setImeInputMode(int mode)
          Sets the input method editor mode to the argument which should be the result of bitwise OR'ing together one or more of the following constants defined in class SWT: NONE, ROMAN, DBCS, PHONETIC, NATIVE, ALPHA.
 void setMaximized(boolean maximized)
          Sets the maximized state of the receiver.
 void setMenuBar(Menu menu)
          Sets the receiver's menu bar to the argument, which may be null.
 void setMinimized(boolean minimized)
          Sets the minimized stated of the receiver.
 void setText(java.lang.String string)
          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.
 java.lang.String toString()
          Returns a string containing a concise, human-readable description of the receiver.
 
Methods inherited from class org.eclipse.swt.widgets.Decorations
getDefaultButton, getImage, getMenuBar, getText, isReparentable, setBounds, setDefaultButton, setLocation
 
Methods inherited from class org.eclipse.swt.widgets.Canvas
removeInternalFilter, scroll, traverse
 
Methods inherited from class org.eclipse.swt.widgets.Composite
allowTraverseByArrowKey, checkSubclass, computeSize, getChildren, getLayout, getTabList, internal_removeChild, layout, layout, setFocus, setLayout, setSize, setTabList, traverse
 
Methods inherited from class org.eclipse.swt.widgets.Scrollable
computeTrim, getClientArea, getHorizontalBar, getVerticalBar
 
Methods inherited from class org.eclipse.swt.widgets.Control
addControlListener, addFocusListener, addKeyListener, addMouseListener, addMouseMoveListener, addPaintListener, addTraverseListener, computeSize, dispose, forceFocus, getBackground, getBorderWidth, getBounds, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getParent, getSize, getToolTipText, getVisible, internal_copyArea, internal_dispose_GC, internal_getBounds, internal_getDefaultClipping, internal_new_GC, isEnabled, isEnableTraverse, isFocusControl, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removePaintListener, removeTraverseListener, setBackground, setBounds, setCapture, setEnabled, setFont, setForeground, setLayoutData, setLocation, setMenu, setParent, setRedraw, setSize, setToolTipText, setVisible, toControl, toControl, toDisplay, toDisplay, traverseByArrowKey, traverseGroup, update
 
Methods inherited from class org.eclipse.swt.widgets.Widget
addDisposeListener, addListener, checkWidget, getData, getData, getDisplay, getStyle, internal_sendEvent, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, sendEvent, setData, setData
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

Shell

public Shell()
Constructs a new instance of this class. This is equivalent to calling Shell((Display) null).

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(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, SWT.DIALOG_TRIM, SWT.MODELESS, SWT.PRIMARY_MODAL, SWT.APPLICATION_MODAL, SWT.SYSTEM_MODAL

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.

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.

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
style - the style of control to construct
Throws:
java.lang.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
See Also:
SWT.BORDER, SWT.CLOSE, SWT.MIN, SWT.MAX, SWT.RESIZE, SWT.TITLE, SWT.NO_TRIM, SWT.SHELL_TRIM, SWT.DIALOG_TRIM, SWT.MODELESS, SWT.PRIMARY_MODAL, SWT.APPLICATION_MODAL, SWT.SYSTEM_MODAL

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:
java.lang.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.

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.

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
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, SWT.DIALOG_TRIM, SWT.MODELESS, SWT.PRIMARY_MODAL, SWT.APPLICATION_MODAL
Method Detail

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:
java.lang.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
See Also:
ShellListener, removeShellListener(org.eclipse.swt.events.ShellListener)

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, Control.dispose()

internal_createHandle

protected void internal_createHandle(int index)
Overrides:
internal_createHandle in class Composite

forceActive

public 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.

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:
2.0
See Also:
Control.moveAbove(org.eclipse.swt.widgets.Control), Control.setFocus(), Control.setVisible(boolean), Display.getActiveShell(), Decorations.setDefaultButton(org.eclipse.swt.widgets.Button), open(), setActive()

getImeInputMode

public int getImeInputMode()
Returns the receiver's input method editor mode. This will be the result of bitwise OR'ing together one or more of the following constants defined in class SWT: NONE, ROMAN, DBCS, PHONETIC, NATIVE, ALPHA.

Returns:
the IME mode
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

internal_getNativeStyle

protected int internal_getNativeStyle()
Overrides:
internal_getNativeStyle in class Decorations

getMaximized

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

Overrides:
getMaximized in class Decorations
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)

getMinimized

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

Overrides:
getMinimized in class Decorations
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)

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.

Overrides:
setImage in class Decorations
Parameters:
image - the new image (or null)
Throws:
java.lang.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

getShell

public Shell getShell()
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
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:
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

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()

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
See Also:
Control.moveAbove(org.eclipse.swt.widgets.Control), Control.setFocus(), Control.setVisible(boolean), Display.getActiveShell(), Decorations.setDefaultButton(org.eclipse.swt.widgets.Button), setActive(), forceActive()

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:
java.lang.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
See Also:
ShellListener, addShellListener(org.eclipse.swt.events.ShellListener)

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
Since:
2.0
See Also:
Control.moveAbove(org.eclipse.swt.widgets.Control), Control.setFocus(), Control.setVisible(boolean), Display.getActiveShell(), Decorations.setDefaultButton(org.eclipse.swt.widgets.Button), open(), setActive()

setImeInputMode

public void setImeInputMode(int mode)
Sets the input method editor mode to the argument which should be the result of bitwise OR'ing together one or more of the following constants defined in class SWT: NONE, ROMAN, DBCS, PHONETIC, NATIVE, ALPHA.

Parameters:
mode - the new IME mode
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

setMaximized

public void setMaximized(boolean maximized)
Description copied from class: Decorations
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.

Note: The result of intermixing calls to setMaximized(true) and setMinimized(true) will vary by platform. Typically, the behavior will match the platform user's expectations, but not always. This should be avoided if possible.

Overrides:
setMaximized in class Decorations
Parameters:
maximized - the new maximized state
See Also:
Decorations.setMinimized(boolean)

setMinimized

public void setMinimized(boolean minimized)
Description copied from class: Decorations
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.

Note: The result of intermixing calls to setMaximized(true) and setMinimized(true) will vary by platform. Typically, the behavior will match the platform user's expectations, but not always. This should be avoided if possible.

Overrides:
setMinimized in class Decorations
Parameters:
minimized - the new maximized state
See Also:
Decorations.setMaximized(boolean)

setMenuBar

public void setMenuBar(Menu menu)
Description copied from class: Decorations
Sets the receiver's menu bar to the argument, which may be null.

Overrides:
setMenuBar in class Decorations
Parameters:
menu - the new menu bar

setText

public void setText(java.lang.String string)
Description copied from class: Decorations
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.

Overrides:
setText in class Decorations
Parameters:
string - the new text

toString

public java.lang.String toString()
Description copied from class: Widget
Returns a string containing a concise, human-readable description of the receiver.

Overrides:
toString in class Widget
Returns:
a string representation of the receiver

isValidSubclass

protected boolean isValidSubclass()