Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
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:
  Drawable

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.

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
`handle`

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` | `dispose()` Disposes of the operating system resources associated with the receiver and all its descendents.
`void` | `forceActive()` 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) and forces the window manager to make the shell active.
`Rectangle` | `getBounds()` Returns a rectangle describing the receiver's size and location relative to its parent (or its display if its parent is null), unless the receiver is a shell.
`boolean` | `getEnabled()` Returns `true` if the receiver is enabled, and `false` otherwise.
`int` | `getImeInputMode()` Returns the receiver's input method editor mode.
`Point` | `getLocation()` Returns a point describing the receiver's location relative to its parent (or its display if its parent is null), unless the receiver is a shell.
`Region` | `getRegion()` Returns the region that defines the shape of the shell, or null if the shell has the default shape.
`Shell` | `getShell()` Returns the receiver's shell.
`Shell[]` | `getShells()` Returns an array containing all shells which are descendents of the receiver.
`Point` | `getSize()` Returns a point describing the receiver's size.
`boolean` | `isEnabled()` Returns `true` if the receiver is enabled and all of the receiver's ancestors are enabled, and `false` otherwise.
`boolean` | `isVisible()` Returns `true` if the receiver is visible and all of the receiver's ancestors are visible and `false` otherwise.
`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()` 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) and asks the window manager to make the shell active.
`void` | `setEnabled(boolean enabled)` Enables the receiver if the argument is `true`, and disables it otherwise.
`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` | `setRegion(Region region)` Sets the shape of the shell to the region specified by the argument.
`void` | `setVisible(boolean visible)` Marks the receiver as visible if the argument is `true`, and marks it invisible otherwise.
`static Shell` | `win32_new(Display display, int handle)` Invokes platform specific functionality to allocate a new shell.

Methods inherited from class org.eclipse.swt.widgets.Decorations
`checkSubclass, computeTrim, getClientArea, getDefaultButton, getImage, getImages, getMaximized, getMenuBar, getMinimized, getText, isReparentable, setDefaultButton, setImage, setImages, setMaximized, setMenuBar, setMinimized, setText`

Methods inherited from class org.eclipse.swt.widgets.Canvas
`getCaret, scroll, setCaret, setFont`

Methods inherited from class org.eclipse.swt.widgets.Composite
`computeSize, getChildren, getLayout, getTabList, layout, layout, setFocus, setLayout, setTabList`

Methods inherited from class org.eclipse.swt.widgets.Scrollable
`getHorizontalBar, getVerticalBar`

Methods inherited from class org.eclipse.swt.widgets.Control
`addControlListener, addFocusListener, addHelpListener, addKeyListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addPaintListener, addTraverseListener, computeSize, forceFocus, getAccessible, getBackground, getBorderWidth, getFont, getForeground, getLayoutData, getMenu, getMonitor, getParent, getToolTipText, getVisible, internal_dispose_GC, internal_new_GC, isFocusControl, moveAbove, moveBelow, pack, pack, redraw, redraw, removeControlListener, removeFocusListener, removeHelpListener, removeKeyListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removePaintListener, removeTraverseListener, setBackground, setBounds, setBounds, setCapture, setCursor, setForeground, setLayoutData, setLocation, setLocation, setMenu, setParent, setRedraw, setSize, setSize, setToolTipText, toControl, toControl, toDisplay, toDisplay, traverse, update`

Methods inherited from class org.eclipse.swt.widgets.Widget
`addDisposeListener, addListener, checkWidget, getData, getData, getDisplay, getStyle, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, 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()

  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:
  `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:
  `IllegalArgumentException` -
  - ERROR_NULL_ARGUMENT - if the parent is null
  `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`, `SWT.SYSTEM_MODAL`

Method Detail

### win32_new

    public static Shell win32_new(Display display,
                                  int handle)

  Invokes platform specific functionality to allocate a new shell.

  IMPORTANT: This method is not part of the public API for `Shell`. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.

  Parameters:
    `display` - the display for the shell
    `handle` - the handle for the shell
  Returns:
    a new shell object containing the specified display and handle

### 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
  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`, `dispose()`

### dispose

    public void dispose()

  Description copied from class: `Widget`
  Disposes of the operating system resources associated with the receiver and all its descendents. After this method has been invoked, the receiver and all descendents will answer `true` when sent the message `isDisposed()`. Any internal connections between the widgets in the tree will have been removed to facilitate garbage collection.

  NOTE: This method is not called recursively on the descendents of the receiver. This means that, widget implementers can not detect when a widget is being disposed of by re-implementing this method, but should instead listen for the `Dispose` event.

  Overrides:
    `dispose` in class `Decorations`

### forceActive

    public void forceActive()

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

### getBounds

    public Rectangle getBounds()

  Description copied from class: `Control`
  Returns a rectangle describing the receiver's size and location relative to its parent (or its display if its parent is null), unless the receiver is a shell. In this case, the location is relative to the display.

  Overrides:
    `getBounds` in class `Decorations`

### getEnabled

    public boolean getEnabled()

  Description copied from class: `Control`
  Returns `true` if the receiver is enabled, and `false` otherwise. A disabled control is typically not selectable from the user interface and draws with an inactive or "grayed" look.

  Overrides:
    `getEnabled` in class `Control`
  Returns:
    the receiver's enabled state
  See Also:
    `Control.isEnabled()`

### 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`

### getLocation

    public Point getLocation()

  Description copied from class: `Control`
  Returns a point describing the receiver's location relative to its parent (or its display if its parent is null), unless the receiver is a shell. In this case, the point is relative to the display.

  Overrides:
    `getLocation` in class `Decorations`

### getRegion

    public Region getRegion()

  Returns the region that defines the shape of the shell, or null if the shell has the default shape.

  Returns:
    the region that defines the shape of the shell (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
  Since:
    3.0

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

### getSize

    public Point getSize()

  Description copied from class: `Control`
  Returns a point describing the receiver's size. The x coordinate of the result is the width of the receiver. The y coordinate of the result is the height of the receiver.

  Overrides:
    `getSize` in class `Decorations`

### 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

### isEnabled

    public boolean isEnabled()

  Description copied from class: `Control`
  Returns `true` if the receiver is enabled and all of the receiver's ancestors are enabled, and `false` otherwise. 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 of the receiver's ancestors are visible and `false` otherwise.

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

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

### 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

### 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`

### setRegion

    public void setRegion(Region region)

  Sets the shape of the shell to the region specified by the argument. When the argument is null, the default shape of the shell is restored. The shell must be created with the style SWT.NO_TRIM in order to specify a region.

  Parameters:
    `region` - the region that defines the shape of the shell (or null)
  Throws:
    `IllegalArgumentException` -
    - ERROR_INVALID_ARGUMENT - if the region 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
  Since:
    3.0

### 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 `Decorations`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.