public abstract class Window extends Object implements IShellProvider
Creating a window involves the following steps:
Window
create
(optional)WindowManager.add
(optional)open
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 resourcesconfigureShell
- extend or reimplement to set shell
properties before window openscreateContents
- extend or reimplement to create controls
before window opensgetInitialSize
- reimplement to give the initial size for
the shellgetInitialLocation
- reimplement to give the initial
location for the shellgetShellListener
- extend or reimplement to receive shell
eventshandleFontChange
- reimplement to respond to font changes
handleShellCloseEvent
- extend or reimplement to handle
shell closingsModifier and Type | Class and Description |
---|---|
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.
|
Modifier and Type | Field and Description |
---|---|
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.
|
protected boolean |
resizeHasOccurred
Internal fields to detect if shell size has been set
|
Modifier | Constructor and Description |
---|---|
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.
|
Modifier and Type | Method and Description |
---|---|
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.
|
static int |
getDefaultOrientation()
Gets the default orientation for 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 |
setDefaultModalParent(IShellProvider provider)
Sets the default parent for modal Windows.
|
static void |
setDefaultOrientation(int defaultOrientation)
Sets the default orientation of windows.
|
static void |
setExceptionHandler(Window.IExceptionHandler handler)
Sets the exception handler for this application.
|
protected void |
setParentShell(Shell newParentShell)
Changes the parent shell.
|
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.
|
public static final int OK
open()
,
Constant Field Valuespublic static final int CANCEL
open()
,
Constant Field Valuesprotected boolean resizeHasOccurred
protected Window(Shell parentShell)
open
does not block.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.setBlockOnOpen(boolean)
,
getDefaultOrientation()
protected Window(IShellProvider shellProvider)
shellProvider
- object that will return the current parent shell. Not null.protected boolean canHandleShellCloseEvent()
The default implementation of this framework method returns
true
, which will allow the
handleShellCloseEvent
method to be called. Subclasses may
extend or reimplement.
public boolean close()
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 ShellListener
s
will not receive a shellClosed
event.
true
if the window is (or was already) closed, and
false
if it is still openprotected void configureShell(Shell newShell)
The default implementation of this framework method sets the shell's image and gives it a grid layout. Subclasses may extend or reimplement.
newShell
- the shellprotected Layout getLayout()
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.
protected void constrainShellSize()
public void create()
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
).
protected Control createContents(Composite parent)
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.
parent
- the parent composite for the controls in this window. The type
of layout used is determined by getLayout()protected final Shell createShell()
This method creates a new shell and configures
it using configureShell
. Subclasses
should override configureShell
if the
shell needs to be customized.
protected Control getContents()
null
if this window's
control has not been created yetpublic static Image getDefaultImage()
setDefaultImage
.null
if nonesetDefaultImage(org.eclipse.swt.graphics.Image)
public static Image[] getDefaultImages()
Decorations.setImages(org.eclipse.swt.graphics.Image[])
,
setDefaultImages(org.eclipse.swt.graphics.Image[])
protected Point getInitialLocation(Point initialSize)
initialSize
- the initial size of the shell, as returned by
getInitialSize
.protected Point getInitialSize()
Shell.computeSize(SWT.DEFAULT, SWT.DEFAULT, true)
.protected Shell getParentShell()
null
if there is no parent
shellpublic int getReturnCode()
OK
and CANCEL
.public Shell getShell()
getShell
in interface IShellProvider
null
if this window's
shell has not been created yetprotected ShellListener getShellListener()
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.
protected int getShellStyle()
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.
public WindowManager getWindowManager()
null
if noneprotected void handleFontChange(PropertyChangeEvent event)
The default implementation of this framework method does nothing. Subclasses may reimplement.
event
- the property change event detailing what changedprotected void handleShellCloseEvent()
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.
protected void initializeBounds()
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.
public int open()
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
.
create()
public void setBlockOnOpen(boolean shouldBlock)
open
method should block until the window
closes.shouldBlock
- true
if the open
method should
not return until the window closes, and false
if the open
method should return immediatelypublic static void setDefaultImage(Image image)
image
- the default image, or null
if nonepublic static void setDefaultImages(Image[] images)
images
- the array of images to be used when this window is openedDecorations.setImages(org.eclipse.swt.graphics.Image[])
protected void setParentShell(Shell newParentShell)
newParentShell
- The new parent shell; this value may be null
if
there is to be no parent.protected void setReturnCode(int code)
open
if block on open is enabled. For non-blocking
opens, the return code needs to be retrieved manually using
getReturnCode
.code
- the return codeprotected Rectangle getConstrainedShellBounds(Rectangle preferredSize)
preferredSize
- the preferred position of the windowprotected void setShellStyle(int newShellStyle)
The shell style bits are used by the framework method
createShell
when creating this window's shell.
newShellStyle
- the new shell style bitspublic void setWindowManager(WindowManager manager)
Note that this method is used by WindowManager
to maintain
a backpointer. Clients must not call the method directly.
manager
- the window manager, or null
if nonepublic static void setExceptionHandler(Window.IExceptionHandler handler)
Note that the handler may only be set once. Subsequent calls to this method will be ignored.
handler
- the exception handler for the application.public static void setDefaultModalParent(IShellProvider provider)
provider
- shell provider that will be used to locate the parent shell
whenever a Window is created with a null parentpublic static int getDefaultOrientation()
SWT.RIGHT_TO_LEFT
,
SWT.LEFT_TO_RIGHT
,
SWT.NONE
public static void setDefaultOrientation(int defaultOrientation)
defaultOrientation
- one of
SWT#RIGHT_TO_LEFT, SWT#LEFT_TO_RIGHT ,SWT#NONESWT.RIGHT_TO_LEFT
,
SWT.LEFT_TO_RIGHT
,
SWT.NONE
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.