org.eclipse.jface.window
Class Window
java.lang.Object
org.eclipse.jface.window.Window
-
All Implemented Interfaces:
-
IShellProvider
-
Direct Known Subclasses:
-
ApplicationWindow,
Dialog,
PopupDialog
-
public abstract class Window
- extends
Object
- implements
IShellProvider
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 methods that subclasses may
override to configure the window, including:
-
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
-
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
(
IShellProvider shellProvider)
Creates a new window which will create its shell as a child of whatever
the given shellProvider returns. |
protected
|
Window
(
Shell parentShell)
Creates a window instance, whose shell will be created under the given
parent shell. |
|
Methods inherited from class java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
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
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. Try passing "(Shell)null" to this method instead of "null"
if your compiler complains about an ambiguity error. -
See Also:
-
setBlockOnOpen(boolean),
getDefaultOrientation()
Window
protected Window(
IShellProvider shellProvider)
- Creates a new window which will create its shell as a child of whatever
the given shellProvider returns.
-
Parameters:
-
shellProvider - object that will return the current parent shell. Not null. -
Since:
- 3.1
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).
Note that in order to prevent recursive calls to this method
it does not call Shell#close(). As a result ShellListeners
will not receive a shellClosed event.
-
-
-
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
getContents(). 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
getContents()
createShell
protected final
Shell createShell()
- Creates and returns this window's shell.
This method creates a new shell and configures
it using configureShell. Subclasses
should override configureShell if the
shell needs to be customized.
-
-
-
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.
-
-
Specified by:
-
getShell
in interface
IShellProvider
-
-
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[])
setParentShell
protected void setParentShell(
Shell newParentShell)
- Changes the parent shell. This is only safe to use when the shell is not
yet realized (i.e., created). Once the shell is created, it must be
disposed (i.e., closed) before this method can be called.
-
-
-
Parameters:
-
newParentShell - The new parent shell; this value may be null if
there is to be no parent. -
Since:
- 3.1
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 the handler may only be set once. Subsequent calls to this method will be
ignored.
-
-
-
Parameters:
-
handler - the exception handler for the application.
setDefaultModalParent
public static void setDefaultModalParent(
IShellProvider provider)
- Sets the default parent for modal Windows. This will be used to locate
the parent for any modal Window constructed with a null parent.
-
-
-
Parameters:
-
provider - shell provider that will be used to locate the parent shell
whenever a Window is created with a null parent -
Since:
- 3.1
getDefaultOrientation
public static int getDefaultOrientation()
- Gets the default orientation for windows. If it is not
set the default value will be unspecified (SWT#NONE).
-
-
-
Returns:
- SWT#NONE, SWT.RIGHT_TO_LEFT or SWT.LEFT_TO_RIGHT
-
Since:
- 3.1
-
See Also:
-
SWT.RIGHT_TO_LEFT,
SWT.LEFT_TO_RIGHT,
SWT.NONE
setDefaultOrientation
public static void setDefaultOrientation(int defaultOrientation)
- Sets the default orientation of windows.
-
-
-
Parameters:
-
defaultOrientation - one of
SWT#RIGHT_TO_LEFT, SWT#LEFT_TO_RIGHT ,SWT#NONE -
Since:
- 3.1
-
See Also:
-
SWT.RIGHT_TO_LEFT,
SWT.LEFT_TO_RIGHT,
SWT.NONE
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.
