Class Window
- All Implemented Interfaces:
IShellProvider
- Direct Known Subclasses:
AbstractNotificationPopup
,ApplicationWindow
,Dialog
,PopupDialog
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 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 changeshandleShellCloseEvent
- extend or reimplement to handle shell closings
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic interface
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
Modifier and TypeFieldDescriptionstatic final int
Standard return code constant (value 1) indicating that the window was canceled.static final int
Standard return code constant (value 0) indicating that the window was opened.protected boolean
Internal fields to detect if shell size has been set -
Constructor Summary
ModifierConstructorDescriptionprotected
Window
(IShellProvider shellProvider) Creates a new window which will create its shell as a child of whatever the given shellProvider returns.protected
Creates a window instance, whose shell will be created under the given parent shell. -
Method Summary
Modifier and TypeMethodDescriptionprotected boolean
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
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 final Shell
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
Returns the top level control for this window.static Image
Returns the default image.static Image[]
Returns the array of default images to use for newly opened windows.static int
Gets the default orientation for windows.protected Point
getInitialLocation
(Point initialSize) Returns the initial location to use for the shell.protected Point
Returns the initial size to use for the shell.protected Layout
Creates the layout for the shell.protected Shell
Returns parent shell, under which this window's shell is created.int
Returns this window's return code.getShell()
Returns this window's shell.protected ShellListener
Returns a shell listener.protected int
Returns the shell style bits.Returns the window manager of this window.protected void
Notifies of a font property change.protected void
Notifies that the window's close button was pressed, the close menu was selected, or the ESCAPE key pressed.protected void
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 theopen
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
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.
-
Field Details
-
OK
public static final int OKStandard return code constant (value 0) indicating that the window was opened.- See Also:
-
CANCEL
public static final int CANCELStandard return code constant (value 1) indicating that the window was canceled.- See Also:
-
resizeHasOccurred
protected boolean resizeHasOccurredInternal fields to detect if shell size has been set- Since:
- 3.9
-
-
Constructor Details
-
Window
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, ornull
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:
-
Window
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
-
-
Method Details
-
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 thehandleShellCloseEvent
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 resultShellListener
s will not receive ashellClosed
event.- Returns:
true
if the window is (or was already) closed, andfalse
if it is still open
-
configureShell
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
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 callingcreateContents
), then initializes this window's shell bounds (by callinginitializeBounds
). -
createContents
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 practice 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
Creates and returns this window's shell.This method creates a new shell and configures it using
configureShell
. Subclasses should overrideconfigureShell
if the shell needs to be customized.- Returns:
- the shell
-
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
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 viasetDefaultImage
.- Returns:
- the default image, or
null
if none - See Also:
-
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:
-
getInitialLocation
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 bygetInitialSize
.- Returns:
- the initial location of the shell
-
getInitialSize
Returns the initial size to use for the shell. The default implementation returns the preferred size of the shell, usingShell.computeSize(SWT.DEFAULT, SWT.DEFAULT, true)
.- Returns:
- the initial size of the 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
andCANCEL
.- Returns:
- the return code
-
getShell
Returns this window's shell.- Specified by:
getShell
in interfaceIShellProvider
- Returns:
- this window's shell, or
null
if this window's shell has not been created yet
-
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
. Subclasses should callsetShellStyle
to change this value, rather than overriding this method.- Returns:
- the shell style bits
-
getWindowManager
Returns the window manager of this window.- Returns:
- the WindowManager, or
null
if none
-
handleFontChange
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 usingclose
. 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 callsgetInitialSize
andgetInitialLocation
and passes the results toShell.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
andCANCEL
.- Returns:
- the return code
- See Also:
-
setBlockOnOpen
public void setBlockOnOpen(boolean shouldBlock) Sets whether theopen
method should block until the window closes.- Parameters:
shouldBlock
-true
if theopen
method should not return until the window closes, andfalse
if theopen
method should return immediately
-
setDefaultImage
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, ornull
if none
-
setDefaultImages
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:
-
setParentShell
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 benull
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 byopen
if block on open is enabled. For non-blocking opens, the return code needs to be retrieved manually usinggetReturnCode
.- Parameters:
code
- the return code
-
getConstrainedShellBounds
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
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, ornull
if none
-
setExceptionHandler
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
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:
-
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:
-