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.jface.window
Class Window

    java.lang.Object
      org.eclipse.jface.window.Window

Direct Known Subclasses:
  ApplicationWindow, Dialog

public abstract class Window
extends Object

A JFace window is an object that has no visual representation (no widgets) until it is told to open.

Creating a window involves the following steps:

- creating an instance of a concrete subclass of `Window`
- creating the window's shell and widget tree by calling `create` (optional)
- assigning the window to a window manager using `WindowManager.add` (optional)
- opening the window by calling `open`

Opening the window will create its shell and widget tree if they have not already been created. When the window is closed, the shell and widget tree are disposed of and are no longer referenced, and the window is automatically removed from its window manager. A window may be reopened.

The JFace window framework (this package) consists of this class, `Window`, the abstract base of all windows, and one concrete window classes (`ApplicationWindow`) which may also be subclassed. Clients may define additional window subclasses as required.

The `Window` class provides the following methods which subclasses may override:

- `close` - extend to free other SWT resources
- `configureShell` - extend or reimplement to set shell properties before window opens
- `createContents` - extend or reimplement to create controls before window opens
- `getInitialSize` - reimplement to give the initial size for the shell
- `getInitialLocation` - reimplement to give the initial location for the shell
- `getShellListener` - extend or reimplement to receive shell events
- `getToolTipText` - reimplement to add tool tips
- `handleFontChange` - reimplement to respond to font changes
- `handleShellCloseEvent` - extend or reimplement to handle shell closings

Nested Class Summary
`static interface` | `Window.IExceptionHandler` This interface defines a Exception Handler which can be set as a global handler and will be called if an exception happens in the event loop.

Field Summary
`static int` | `CANCEL` Standard return code constant (value 1) indicating that the window was canceled.
`static int` | `OK` Standard return code constant (value 0) indicating that the window was opened.

Constructor Summary
`protected` | `Window(Shell parentShell)` Creates a window instance, whose shell will be created under the given parent shell.

Method Summary
`protected boolean` | `canHandleShellCloseEvent()` Determines if the window should handle the close event or do nothing.
`boolean` | `close()` Closes this window, disposes its shell, and removes this window from its window manager (if it has one).
`protected void` | `configureShell(Shell newShell)` Configures the given shell in preparation for opening this window in it.
`protected void` | `constrainShellSize()` Constrain the shell size to be no larger than the display bounds.
`void` | `create()` Creates this window's widgetry in a new top-level shell.
`protected Control` | `createContents(Composite parent)` Creates and returns this window's contents.
`protected Shell` | `createShell()` Creates and returns this window's shell.
`protected Rectangle` | `getConstrainedShellBounds(Rectangle preferredSize)` Given the desired position of the window, this method returns an adjusted position such that the window is no larger than its monitor, and does not extend beyond the edge of the monitor.
`protected Control` | `getContents()` Returns the top level control for this window.
`static Image` | `getDefaultImage()` Returns the default image.
`static Image[]` | `getDefaultImages()` Returns the array of default images to use for newly opened windows.
`protected Point` | `getInitialLocation(Point initialSize)` Returns the initial location to use for the shell.
`protected Point` | `getInitialSize()` Returns the initial size to use for the shell.
`protected Layout` | `getLayout()` Creates the layout for the shell.
`protected Shell` | `getParentShell()` Returns parent shell, under which this window's shell is created.
`int` | `getReturnCode()` Returns this window's return code.
`Shell` | `getShell()` Returns this window's shell.
`protected ShellListener` | `getShellListener()` Returns a shell listener.
`protected int` | `getShellStyle()` Returns the shell style bits.
`WindowManager` | `getWindowManager()` Returns the window manager of this window.
`protected void` | `handleFontChange(PropertyChangeEvent event)` Notifies of a font property change.
`protected void` | `handleShellCloseEvent()` Notifies that the window's close button was pressed, the close menu was selected, or the ESCAPE key pressed.
`protected void` | `initializeBounds()` Initializes the location and size of this window's SWT shell after it has been created.
`int` | `open()` Opens this window, creating it first if it has not yet been created.
`void` | `setBlockOnOpen(boolean shouldBlock)` Sets whether the `open` method should block until the window closes.
`static void` | `setDefaultImage(Image image)` Sets the default image.
`static void` | `setDefaultImages(Image[] images)` Sets the array of default images to use for newly opened windows.
`static void` | `setExceptionHandler(Window.IExceptionHandler handler)` Sets the exception handler for this application.
`protected void` | `setReturnCode(int code)` Sets this window's return code.
`protected void` | `setShellStyle(int newShellStyle)` Sets the shell style bits.
`void` | `setWindowManager(WindowManager manager)` Sets the window manager of this window.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### OK

    public static final int OK

  Standard return code constant (value 0) indicating that the window was opened.

  See Also:
    `open()`, Constant Field Values

### CANCEL

    public static final int CANCEL

  Standard return code constant (value 1) indicating that the window was canceled.

  See Also:
    `open()`, Constant Field Values

Constructor Detail

### Window

    protected Window(Shell parentShell)

  Creates a window instance, whose shell will be created under the given parent shell. Note that the window will have no visual representation until it is told to open. By default, `open` does not block.

Parameters:
  `parentShell` - the parent shell, or `null` to create a top-level shell
See Also:
  `setBlockOnOpen(boolean)`

Method Detail

### canHandleShellCloseEvent

    protected boolean canHandleShellCloseEvent()

  Determines if the window should handle the close event or do nothing.

  The default implementation of this framework method returns `true`, which will allow the `handleShellCloseEvent` method to be called. Subclasses may extend or reimplement.

  Returns:
    whether the window should handle the close event.

### close

    public boolean close()

  Closes this window, disposes its shell, and removes this window from its window manager (if it has one).

  This framework method may be extended (`super.close` must be called).

  Returns:
    `true` if the window is (or was already) closed, and `false` if it is still open

### configureShell

    protected void configureShell(Shell newShell)

  Configures the given shell in preparation for opening this window in it.

  The default implementation of this framework method sets the shell's image and gives it a grid layout. Subclasses may extend or reimplement.

  Parameters:
    `newShell` - the shell

### getLayout

    protected Layout getLayout()

  Creates the layout for the shell. The layout created here will be attached to the composite passed into createContents. The default implementation returns a GridLayout with no margins. Subclasses that change the layout type by overriding this method should also override createContents.

  A return value of null indicates that no layout should be attached to the composite. In this case, the layout may be attached within createContents.

  Returns:
    a newly created Layout or null if no layout should be attached.
  Since:
    3.0

### constrainShellSize

    protected void constrainShellSize()

  Constrain the shell size to be no larger than the display bounds.

  Since:
    2.0

### create

    public void create()

  Creates this window's widgetry in a new top-level shell.

  The default implementation of this framework method creates this window's shell (by calling `createShell`), and its controls (by calling `createContents`), then initializes this window's shell bounds (by calling `initializeBounds`).

### createContents

    protected Control createContents(Composite parent)

  Creates and returns this window's contents. Subclasses may attach any number of children to the parent. As a convenience, the return value of this method will be remembered and returned by subsequent calls to getControl(). Subclasses may modify the parent's layout if they overload getLayout() to return null.

  It is common practise to create and return a single composite that contains the entire window contents.

  The default implementation of this framework method creates an instance of `Composite`. Subclasses may override.

  Parameters:
    `parent` - the parent composite for the controls in this window. The type of layout used is determined by getLayout()
  Returns:
    the control that will be returned by subsequent calls to getControl()

### createShell

    protected final Shell createShell()

  Creates and returns this window's shell.

  The default implementation of this framework method creates a new shell and configures it using ``configureShell. Rather than override this method, subclasses should instead override ``configureShell.

  Returns:
    the shell

### getContents

    protected Control getContents()

  Returns the top level control for this window. The parent of this control is the shell.

  Returns:
    the top level control, or `null` if this window's control has not been created yet

### getDefaultImage

    public static Image getDefaultImage()

  Returns the default image. This is the image that will be used for windows that have no shell image at the time they are opened. There is no default image unless one is installed via `setDefaultImage`.

  Returns:
    the default image, or `null` if none
  See Also:
    `setDefaultImage(org.eclipse.swt.graphics.Image)`

### getDefaultImages

    public static Image[] getDefaultImages()

  Returns the array of default images to use for newly opened windows. It is expected that the array will contain the same icon rendered at different resolutions.

  Returns:
    the array of images to be used when a new window is opened
  Since:
    3.0
  See Also:
    `Decorations.setImages(org.eclipse.swt.graphics.Image[])`, `setDefaultImages(org.eclipse.swt.graphics.Image[])`

### getInitialLocation

    protected Point getInitialLocation(Point initialSize)

  Returns the initial location to use for the shell. The default implementation centers the shell horizontally (1/2 of the difference to the left and 1/2 to the right) and vertically (1/3 above and 2/3 below) relative to the parent shell, or display bounds if there is no parent shell.

  Parameters:
    `initialSize` - the initial size of the shell, as returned by `getInitialSize`.
  Returns:
    the initial location of the shell

### getInitialSize

    protected Point getInitialSize()

  Returns the initial size to use for the shell. The default implementation returns the preferred size of the shell, using `Shell.computeSize(SWT.DEFAULT, SWT.DEFAULT, true)`.

  Returns:
    the initial size of the shell

### getParentShell

    protected Shell getParentShell()

  Returns parent shell, under which this window's shell is created.

  Returns:
    the parent shell, or `null` if there is no parent shell

### getReturnCode

    public int getReturnCode()

  Returns this window's return code. A window's return codes are window-specific, although two standard return codes are predefined: `OK` and `CANCEL`.

  Returns:
    the return code

### getShell

    public Shell getShell()

  Returns this window's shell.

  Returns:
    this window's shell, or `null` if this window's shell has not been created yet

### getShellListener

    protected ShellListener getShellListener()

  Returns a shell listener. This shell listener gets registered with this window's shell.

  The default implementation of this framework method returns a new listener that makes this window the active window for its window manager (if it has one) when the shell is activated, and calls the framework method `handleShellCloseEvent` when the shell is closed. Subclasses may extend or reimplement.

  Returns:
    a shell listener

### getShellStyle

    protected int getShellStyle()

  Returns the shell style bits.

  The default value is `SWT.CLOSE|SWT.MIN|SWT.MAX|SWT.RESIZE`. Subclassers should call `setShellStyle` to change this value, rather than overriding this method.

  Returns:
    the shell style bits

### getWindowManager

    public WindowManager getWindowManager()

  Returns the window manager of this window.

  Returns:
    the WindowManager, or `null` if none

### handleFontChange

    protected void handleFontChange(PropertyChangeEvent event)

  Notifies of a font property change.

  The default implementation of this framework method does nothing. Subclasses may reimplement.

  Parameters:
    `event` - the property change event detailing what changed

### handleShellCloseEvent

    protected void handleShellCloseEvent()

  Notifies that the window's close button was pressed, the close menu was selected, or the ESCAPE key pressed.

  The default implementation of this framework method sets the window's return code to `CANCEL` and closes the window using `close`. Subclasses may extend or reimplement.

### initializeBounds

    protected void initializeBounds()

  Initializes the location and size of this window's SWT shell after it has been created.

  This framework method is called by the `create` framework method. The default implementation calls `getInitialSize` and `getInitialLocation` and passes the results to `Shell.setBounds`. This is only done if the bounds of the shell have not already been modified. Subclasses may extend or reimplement.

### open

    public int open()

  Opens this window, creating it first if it has not yet been created.

  If this window has been configured to block on open (`setBlockOnOpen`), this method waits until the window is closed by the end user, and then it returns the window's return code; otherwise, this method returns immediately. A window's return codes are window-specific, although two standard return codes are predefined: `OK` and `CANCEL`.

  Returns:
    the return code
  See Also:
    `create()`

### setBlockOnOpen

    public void setBlockOnOpen(boolean shouldBlock)

  Sets whether the `open` method should block until the window closes.

  Parameters:
    `shouldBlock` - `true` if the `open` method should not return until the window closes, and `false` if the `open` method should return immediately

### setDefaultImage

    public static void setDefaultImage(Image image)

  Sets the default image. This is the image that will be used for windows that have no shell image at the time they are opened. There is no default image unless one is installed via this method.

  Parameters:
    `image` - the default image, or `null` if none

### setDefaultImages

    public static void setDefaultImages(Image[] images)

  Sets the array of default images to use for newly opened windows. It is expected that the array will contain the same icon rendered at different resolutions.

  Parameters:
    `images` - the array of images to be used when this window is opened
  Since:
    3.0
  See Also:
    `Decorations.setImages(org.eclipse.swt.graphics.Image[])`

### setReturnCode

    protected void setReturnCode(int code)

  Sets this window's return code. The return code is automatically returned by `open` if block on open is enabled. For non-blocking opens, the return code needs to be retrieved manually using `getReturnCode`.

  Parameters:
    `code` - the return code

### getConstrainedShellBounds

    protected Rectangle getConstrainedShellBounds(Rectangle preferredSize)

  Given the desired position of the window, this method returns an adjusted position such that the window is no larger than its monitor, and does not extend beyond the edge of the monitor. This is used for computing the initial window position, and subclasses can use this as a utility method if they want to limit the region in which the window may be moved.

  Parameters:
    `preferredSize` - the preferred position of the window
  Returns:
    a rectangle as close as possible to preferredSize that does not extend outside the monitor
  Since:
    3.0

### setShellStyle

    protected void setShellStyle(int newShellStyle)

  Sets the shell style bits. This method has no effect after the shell is created.

  The shell style bits are used by the framework method `createShell` when creating this window's shell.

  Parameters:
    `newShellStyle` - the new shell style bits

### setWindowManager

    public void setWindowManager(WindowManager manager)

  Sets the window manager of this window.

  Note that this method is used by `WindowManager` to maintain a backpointer. Clients must not call the method directly.

  Parameters:
    `manager` - the window manager, or `null` if none

### setExceptionHandler

    public static void setExceptionHandler(Window.IExceptionHandler handler)

  Sets the exception handler for this application.

  Note that only one handler may be set. Other calls to this method will be ignored.

  Parameters:
    `handler` - the exception handler for the application.

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.