public class Display extends Device implements Adaptable
Applications which are built with SWT will almost always
require only a single display. In particular, some platforms
which SWT supports will not allow more than one active
display. In other words, some platforms do not support
creating a new display if one already exists that has not been
sent the dispose()
message.
In SWT, the thread which creates a Display
instance is distinguished as the user-interface thread
for that display.
Widget
and its subclasses), may only be called
from the thread. (To support multi-threaded user-interface
applications, class Display
provides inter-thread
communication methods which allow threads other than the
user-interface thread to request that it perform operations
on their behalf.)
Display
s until that display has been disposed.
(Note that, this is in addition to the restriction mentioned
above concerning platform support for multiple displays. Thus,
the only way to have multiple simultaneously active displays,
even on platforms which support it, is to have multiple threads.)
All SWT API methods which may only be called from the user-interface
thread are distinguished in their documentation by indicating that
they throw the "ERROR_THREAD_INVALID_ACCESS
"
SWT exception.
IMPORTANT: This class is not intended to be subclassed.
syncExec(java.lang.Runnable)
,
asyncExec(java.lang.Runnable)
,
wake()
,
readAndDispatch()
,
sleep()
,
Device.dispose()
deviceLock
Constructor and Description |
---|
Display()
Constructs a new instance of this class.
|
Modifier and Type | Method and Description |
---|---|
void |
addFilter(int eventType,
Listener listener)
Adds the listener to the collection of listeners who will be notified when
an event of the given type occurs anywhere in a widget.
|
void |
addListener(int eventType,
Listener listener)
Adds the listener to the collection of listeners who will
be notified when an event of the given type occurs.
|
void |
asyncExec(java.lang.Runnable runnable)
Causes the
run() method of the runnable to
be invoked by the user-interface thread at the next
reasonable opportunity. |
void |
beep()
Causes the system hardware to emit a short sound
(if it supports this capability).
|
protected void |
checkDevice()
Throws an
SWTException if the receiver can not
be accessed by the caller. |
void |
close()
Requests that the connection between SWT and the underlying
operating system be closed.
|
protected void |
destroy()
Destroys the device .
|
void |
disposeExec(java.lang.Runnable runnable)
Causes the
run() method of the runnable to
be invoked by the user-interface thread just before the
receiver is disposed. |
static Display |
findDisplay(java.lang.Thread thread)
Returns the display which the given thread is the
user-interface thread for, or null if the given thread
is not a user-interface thread for any display.
|
Shell |
getActiveShell()
Returns the currently active
Shell , or null
if no shell belonging to the currently running application
is active. |
<T> T |
getAdapter(java.lang.Class<T> adapter)
Returns an object which is an instance of the given class parameter
associated with this object or
null if no association
exists. |
static java.lang.String |
getAppName()
Returns the application name.
|
static java.lang.String |
getAppVersion()
Returns the application version.
|
Rectangle |
getBounds()
Returns a rectangle describing the receiver's size and location.
|
static Display |
getCurrent()
Returns the display which the currently running thread is
the user-interface thread for, or null if the currently
running thread is not a user-interface thread for any display.
|
Control |
getCursorControl()
Returns the control which the on-screen pointer is currently
over top of, or null if it is not currently over one of the
controls built by the currently running application.
|
Point |
getCursorLocation()
Returns the location of the on-screen pointer relative
to the top left corner of the screen.
|
java.lang.Object |
getData()
Returns the application defined, display specific data
associated with the receiver, or null if it has not been
set.
|
java.lang.Object |
getData(java.lang.String key)
Returns the application defined property of the receiver
with the specified name, or null if it has not been set.
|
static Display |
getDefault()
Returns the default display.
|
int |
getDepth()
Returns the bit depth of the screen, which is the number of
bits it takes to represent the number of unique colors that
the screen is currently capable of displaying.
|
int |
getDismissalAlignment()
Returns the button dismissal alignment, one of
LEFT or RIGHT . |
int |
getDoubleClickTime()
Returns the longest duration, in milliseconds, between
two mouse button clicks that will be considered a
double click .
|
Point |
getDPI()
Returns a point whose x coordinate is the horizontal
dots per inch of the display, and whose y coordinate
is the vertical dots per inch of the display.
|
Control |
getFocusControl()
Returns the control which currently has keyboard focus,
or null if keyboard events are not currently going to
any of the controls built by the currently running
application.
|
boolean |
getHighContrast()
Returns true when the high contrast mode is enabled.
|
Menu |
getMenuBar()
Returns the single instance of the application menu bar or null
when there is no application menu bar for the platform.
|
Monitor[] |
getMonitors()
Returns an array of monitors attached to the device.
|
Monitor |
getPrimaryMonitor()
Returns the primary monitor for that device.
|
Shell[] |
getShells()
Returns a (possibly empty) array containing all shells which have
not been disposed and have the receiver as their display.
|
Synchronizer |
getSynchronizer()
Gets the synchronizer used by the display.
|
java.lang.Thread |
getSyncThread()
Returns the thread that has invoked
syncExec
or null if no such runnable is currently being invoked by
the user-interface thread. |
Color |
getSystemColor(int id)
Returns the matching standard color for the given
constant, which should be one of the color constants
specified in class
SWT . |
Cursor |
getSystemCursor(int id)
Returns the matching standard platform cursor for the given
constant, which should be one of the cursor constants
specified in class
SWT . |
Image |
getSystemImage(int id)
Returns the matching standard platform image for the given
constant, which should be one of the icon constants
specified in class
SWT . |
Menu |
getSystemMenu()
Returns the single instance of the system-provided menu for the application.
|
TaskBar |
getSystemTaskBar()
Returns the single instance of the system taskBar or null
when there is no system taskBar available for the platform.
|
Tray |
getSystemTray()
Returns the single instance of the system tray or null when there is no
system tray available for the platform.
|
java.lang.Thread |
getThread()
Returns the user-interface thread for the receiver.
|
boolean |
getTouchEnabled()
Returns true if a touch-aware input device is attached to the system,
enabled, and ready for use.
|
Point |
map(Control from,
Control to,
int x,
int y)
Maps a point from one coordinate system to another.
|
Rectangle |
map(Control from,
Control to,
int x,
int y,
int width,
int height)
Maps a point from one coordinate system to another.
|
Point |
map(Control from,
Control to,
Point point)
Maps a point from one coordinate system to another.
|
Rectangle |
map(Control from,
Control to,
Rectangle rectangle)
Maps a point from one coordinate system to another.
|
boolean |
readAndDispatch()
Reads an event from the event queue,
dispatches it appropriately, and returns
true
if there is potentially more work to do, or false
if the caller can sleep until another event is placed on
the event queue. |
protected void |
release()
Releases any internal resources .
|
void |
removeFilter(int eventType,
Listener listener)
Removes the listener from the collection of listeners who will be notified
when an event of the given type occurs anywhere in a widget.
|
void |
removeListener(int eventType,
Listener listener)
Removes the listener from the collection of listeners who will
be notified when an event of the given type occurs.
|
static void |
setAppName(java.lang.String name)
Sets the application name to the argument.
|
static void |
setAppVersion(java.lang.String version)
Sets the application version to the argument.
|
void |
setData(java.lang.Object data)
Sets the application defined, display specific data
associated with the receiver, to the argument.
|
void |
setData(java.lang.String key,
java.lang.Object value)
Sets the application defined property of the receiver
with the specified name to the given argument.
|
void |
setSynchronizer(Synchronizer synchronizer)
Sets the synchronizer used by the display to be
the argument, which can not be null.
|
boolean |
sleep()
Causes the user-interface thread to sleep (that is,
to be put in a state where it does not consume CPU cycles)
until an event is received or it is otherwise awakened.
|
void |
syncExec(java.lang.Runnable runnable)
Causes the
run() method of the runnable to
be invoked by the user-interface thread at the next
reasonable opportunity. |
void |
timerExec(int milliseconds,
java.lang.Runnable runnable)
Causes the
run() method of the runnable to
be invoked by the user-interface thread after the specified
number of milliseconds have elapsed. |
void |
update()
Forces all outstanding paint requests for the display
to be processed before this method returns.
|
void |
wake()
Notifies the client to send a request in order to wake up a sleeping UI thread and to perform
pending UI updates.
|
protected void |
wakeThread() |
dispose, getClientArea, getFontList, getSystemFont, isDisposed
public Display()
Note: The resulting display is marked as the current display. If this is the first display which has been constructed since the application started, it is also marked as the default display.
SWTException
- getCurrent()
,
getDefault()
,
Widget.checkSubclass()
,
Shell
public static Display getCurrent()
public static Display getDefault()
Note: In RWT, a new display is only created if the calling thread is the user-interface thread.
public Rectangle getBounds()
getBounds
in class Device
SWTException
- public Point getDPI()
Device
public int getDepth()
Device
public Control getFocusControl()
SWTException
- public Point map(Control from, Control to, Point point)
NOTE: On right-to-left platforms where the coordinate systems are mirrored, special care needs to be taken when mapping coordinates from one control to another to ensure the result is correctly mirrored. Mapping a point that is the origin of a rectangle and then adding the width and height is not equivalent to mapping the rectangle. When one control is mirrored and the other is not, adding the width and height to a point that was mapped causes the rectangle to extend in the wrong direction. Mapping the entire rectangle instead of just one point causes both the origin and the corner of the rectangle to be mapped.
from
- the source Control
or null
to
- the destination Control
or null
point
- to be mappedjava.lang.IllegalArgumentException
- SWTException
- public Point map(Control from, Control to, int x, int y)
NOTE: On right-to-left platforms where the coordinate systems are mirrored, special care needs to be taken when mapping coordinates from one control to another to ensure the result is correctly mirrored. Mapping a point that is the origin of a rectangle and then adding the width and height is not equivalent to mapping the rectangle. When one control is mirrored and the other is not, adding the width and height to a point that was mapped causes the rectangle to extend in the wrong direction. Mapping the entire rectangle instead of just one point causes both the origin and the corner of the rectangle to be mapped.
from
- the source Control
or null
to
- the destination Control
or null
x
- coordinates to be mappedy
- coordinates to be mappedjava.lang.IllegalArgumentException
- SWTException
- public Rectangle map(Control from, Control to, Rectangle rectangle)
NOTE: On right-to-left platforms where the coordinate systems are mirrored, special care needs to be taken when mapping coordinates from one control to another to ensure the result is correctly mirrored. Mapping a point that is the origin of a rectangle and then adding the width and height is not equivalent to mapping the rectangle. When one control is mirrored and the other is not, adding the width and height to a point that was mapped causes the rectangle to extend in the wrong direction. Mapping the entire rectangle instead of just one point causes both the origin and the corner of the rectangle to be mapped.
from
- the source Control
or null
to
- the destination Control
or null
rectangle
- to be mappedjava.lang.IllegalArgumentException
- SWTException
- public Rectangle map(Control from, Control to, int x, int y, int width, int height)
NOTE: On right-to-left platforms where the coordinate systems are mirrored, special care needs to be taken when mapping coordinates from one control to another to ensure the result is correctly mirrored. Mapping a point that is the origin of a rectangle and then adding the width and height is not equivalent to mapping the rectangle. When one control is mirrored and the other is not, adding the width and height to a point that was mapped causes the rectangle to extend in the wrong direction. Mapping the entire rectangle instead of just one point causes both the origin and the corner of the rectangle to be mapped.
from
- the source Control
or null
to
- the destination Control
or null
x
- coordinates to be mappedy
- coordinates to be mappedwidth
- coordinates to be mappedheight
- coordinates to be mappedjava.lang.IllegalArgumentException
- SWTException
- public void addListener(int eventType, Listener listener)
SWT
.
When the event does occur in the display, the listener is notified by
sending it the handleEvent()
message.eventType
- the type of event to listen forlistener
- the listener which should be notified when the event occursjava.lang.IllegalArgumentException
- SWTException
- Listener
,
SWT
,
removeListener(int, org.eclipse.swt.widgets.Listener)
public void removeListener(int eventType, Listener listener)
SWT
.eventType
- the type of event to listen forlistener
- the listener which should no longer be notifiedjava.lang.IllegalArgumentException
- SWTException
- Listener
,
SWT
,
addListener(int, org.eclipse.swt.widgets.Listener)
public void disposeExec(java.lang.Runnable runnable)
run()
method of the runnable to
be invoked by the user-interface thread just before the
receiver is disposed. Specifying a null
runnable
is ignored.runnable
- code to run at dispose time.SWTException
- public void close()
SWTException
- Device.dispose()
protected void release()
Device
When a device is destroyed, resources that were acquired
on behalf of the programmer need to be returned to the
operating system. For example, if the device allocated a
font to be used as the system font, this font would be
freed in release
. Also,to assist the garbage
collector and minimize the amount of memory that is not
reclaimed when the programmer keeps a reference to a
disposed device, all fields except the handle are zero'd.
The handle is needed by destroy
.
destroy
.
If subclasses reimplement this method, they must
call the super
implementation.
release
in class Device
Device.dispose()
,
Device.destroy()
protected void destroy()
Device
This method is called after release
.
Subclasses are supposed to reimplement this method and not
call the super
implementation.
destroy
in class Device
Device.dispose()
,
Device.release()
public <T> T getAdapter(java.lang.Class<T> adapter)
Adaptable
Returns an object which is an instance of the given class parameter
associated with this object or null
if no association
exists.
getAdapter
in interface Adaptable
adapter
- the lookup classnull
if
there is no adapter associated with the given class.public Shell[] getShells()
SWTException
- public Shell getActiveShell()
Shell
, or null
if no shell belonging to the currently running application
is active.SWTException
- public java.lang.Thread getThread()
SWTException
- public static Display findDisplay(java.lang.Thread thread)
null
as the thread will return null
for the display.thread
- the user-interface threadpublic void setSynchronizer(Synchronizer synchronizer)
synchronizer
- the new synchronizer for the display (must not be null)java.lang.IllegalArgumentException
- SWTException
- public Synchronizer getSynchronizer()
SWTException
- public java.lang.Thread getSyncThread()
syncExec
or null if no such runnable is currently being invoked by
the user-interface thread.
Note: If a runnable invoked by asyncExec is currently running, this method will return null.
SWTException
- public void asyncExec(java.lang.Runnable runnable)
run()
method of the runnable to
be invoked by the user-interface thread at the next
reasonable opportunity. Note that the user-interface thread may change
per user-request. The caller of this method continues
to run in parallel, and is not notified when the
runnable has completed. Specifying null
as the
runnable simply wakes the user-interface thread when run.
Note that at the time the runnable is invoked, widgets that have the receiver as their display may have been disposed. Therefore, it is necessary to check for this case inside the runnable before accessing the widget.
runnable
- code to run on the user-interface thread or null
SWTException
- syncExec(java.lang.Runnable)
public void syncExec(java.lang.Runnable runnable)
run()
method of the runnable to
be invoked by the user-interface thread at the next
reasonable opportunity. Note that the user-interface thread may change
per user-request. The thread which calls this method
is suspended until the runnable completes. Specifying null
as the runnable simply wakes the user-interface thread.
Note that at the time the runnable is invoked, widgets that have the receiver as their display may have been disposed. Therefore, it is necessary to check for this case inside the runnable before accessing the widget.
runnable
- code to run on the user-interface thread or null
SWTException
- asyncExec(java.lang.Runnable)
public void timerExec(int milliseconds, java.lang.Runnable runnable)
run()
method of the runnable to
be invoked by the user-interface thread after the specified
number of milliseconds have elapsed. If milliseconds is less
than zero, the runnable is not executed.
Note that at the time the runnable is invoked, widgets that have the receiver as their display may have been disposed. Therefore, it is necessary to check for this case inside the runnable before accessing the widget.
milliseconds
- the delay before running the runnablerunnable
- code to run on the user-interface threadjava.lang.IllegalArgumentException
- SWTException
- asyncExec(java.lang.Runnable)
public boolean readAndDispatch()
true
if there is potentially more work to do, or false
if the caller can sleep until another event is placed on
the event queue.
In addition to checking the system event queue, this method also
checks if any inter-thread messages (created by syncExec()
or asyncExec()
) are waiting to be processed, and if
so handles them before returning.
false
if the caller can sleep upon return from this methodSWTException
- sleep()
,
wake()
public boolean sleep()
true
if an event requiring dispatching was placed on the queue.SWTException
- wake()
public void wake()
Note that this method has no effect unless a ServerPushSession
is active.
SWTException
- protected void wakeThread()
public Tray getSystemTray()
null
SWTException
- public Menu getMenuBar()
null
SWTException
- public TaskBar getSystemTaskBar()
null
SWTException
- public Menu getSystemMenu()
null
SWTException
- public Color getSystemColor(int id)
Device
SWT
. Any value other
than one of the SWT color constants which is passed
in will result in the color black. This color should
not be free'd because it was allocated by the system,
not the application.getSystemColor
in class Device
id
- the color constantSWT
public Image getSystemImage(int id)
SWT
. This image should
not be free'd because it was allocated by the system,
not the application. A value of null
will
be returned either if the supplied constant is not an
SWT icon constant or if the platform does not define an
image that corresponds to the constant.id
- the SWT icon constantnull
SWTException
- SWT.ICON_ERROR
,
SWT.ICON_INFORMATION
,
SWT.ICON_QUESTION
,
SWT.ICON_WARNING
,
SWT.ICON_WORKING
public Cursor getSystemCursor(int id)
SWT
. This cursor should
not be free'd because it was allocated by the system,
not the application. A value of null
will
be returned if the supplied constant is not an SWT cursor
constant.id
- the SWT cursor constantnull
SWTException
- SWT.CURSOR_ARROW
,
SWT.CURSOR_WAIT
,
SWT.CURSOR_CROSS
,
SWT.CURSOR_HELP
,
SWT.CURSOR_SIZEALL
,
SWT.CURSOR_SIZENS
,
SWT.CURSOR_SIZEWE
,
SWT.CURSOR_SIZEN
,
SWT.CURSOR_SIZES
,
SWT.CURSOR_SIZEE
,
SWT.CURSOR_SIZEW
,
SWT.CURSOR_SIZENE
,
SWT.CURSOR_SIZESE
,
SWT.CURSOR_SIZESW
,
SWT.CURSOR_SIZENW
,
SWT.CURSOR_IBEAM
,
SWT.CURSOR_HAND
public int getDoubleClickTime()
SWTException
- public Control getCursorControl()
null
SWTException
- public int getDismissalAlignment()
LEFT
or RIGHT
.
The button dismissal alignment is the ordering that should be used when positioning the
default dismissal button for a dialog. For example, in a dialog that contains an OK and
CANCEL button, on platforms where the button dismissal alignment is LEFT
, the
button ordering should be OK/CANCEL. When button dismissal alignment is RIGHT
,
the button ordering should be CANCEL/OK.SWTException
- public boolean getHighContrast()
Note: This operation is a hint and is not supported on platforms that do not have this concept.
SWTException
- public Point getCursorLocation()
SWTException
- public void addFilter(int eventType, Listener listener)
SWT
. When the
event does occur, the listener is notified by sending it the
handleEvent()
message.
Setting the type of an event to SWT.None
from within the
handleEvent()
method can be used to change the event type
and stop subsequent Java listeners from running. Because event filters run
before other listeners, event filters can both block other listeners and
set arbitrary fields within an event. For this reason, event filters are
both powerful and dangerous. They should generally be avoided for
performance, debugging and code maintenance reasons.
NOTE: In RAP, only events that have a matching listener registered on the
event's source widget are processed on the server. One exception are key events, for which a
whitelist can be define using RWT#ACTIVE_KEYS
.
eventType
- the type of event to listen forlistener
- the listener which should be notified when the event occursjava.lang.IllegalArgumentException
- SWTException
- Listener
,
SWT
,
removeFilter(int, org.eclipse.swt.widgets.Listener)
,
removeListener(int, org.eclipse.swt.widgets.Listener)
public void removeFilter(int eventType, Listener listener)
SWT
.eventType
- the type of event to listen forlistener
- the listener which should no longer be notified when the
event occursjava.lang.IllegalArgumentException
- SWTException
- Listener
,
SWT
,
addFilter(int, org.eclipse.swt.widgets.Listener)
,
addListener(int, org.eclipse.swt.widgets.Listener)
public java.lang.Object getData()
Applications may put arbitrary objects in this field. If
the object stored in the display specific data needs to
be notified when the display is disposed of, it is the
application's responsibility to provide a
disposeExec()
handler which does so.
SWTException
- setData(Object)
,
disposeExec(Runnable)
public void setData(java.lang.Object data)
Applications may put arbitrary objects in this field. If
the object stored in the display specific data needs to
be notified when the display is disposed of, it is the
application's responsibility provide a
disposeExec()
handler which does so.
data
- the new display specific dataSWTException
- getData()
,
disposeExec(Runnable)
public void setData(java.lang.String key, java.lang.Object value)
Applications may have associated arbitrary objects with the
receiver in this fashion. If the objects stored in the
properties need to be notified when the display is disposed
of, it is the application's responsibility provide a
disposeExec()
handler which does so.
key
- the name of the propertyvalue
- the new value for the propertyjava.lang.IllegalArgumentException
- SWTException
- getData(String)
,
disposeExec(Runnable)
public java.lang.Object getData(java.lang.String key)
Applications may have associated arbitrary objects with the
receiver in this fashion. If the objects stored in the
properties need to be notified when the display is disposed
of, it is the application's responsibility to provide a
disposeExec()
handler which does so.
key
- the name of the propertyjava.lang.IllegalArgumentException
- SWTException
- setData(String, Object)
,
disposeExec(Runnable)
public Monitor[] getMonitors()
public Monitor getPrimaryMonitor()
public static java.lang.String getAppName()
setAppName(String)
public static java.lang.String getAppVersion()
setAppVersion(String)
public static void setAppName(java.lang.String name)
Specifying null
for the name clears it.
name
- the new app name or null
public static void setAppVersion(java.lang.String version)
version
- the new app versionpublic void update()
SWTException
- Control.update()
public void beep()
SWTException
- public boolean getTouchEnabled()
protected void checkDevice()
Device
SWTException
if the receiver can not
be accessed by the caller. This may include both checks on
the state of the receiver and more generally on the entire
execution context. This method should be called by
device implementors to enforce the standard SWT invariants.
Currently, it is an error to invoke any method (other than
isDisposed()
and dispose()
) on a
device that has had its dispose()
method called.
In future releases of SWT, there may be more or fewer error checks and exceptions may be thrown for different reasons.
checkDevice
in class Device
Copyright (c) EclipseSource and others 2002, 2020.
All rights reserved. This program and the accompanying materials
are made available under the terms of the
Eclipse Public License v1.0