Class Display
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.
- The event loop for that display must be run from the thread.
-
Some SWT API methods (notably, most of the public methods in
Widget
and its subclasses), may only be called from the thread. (To support multi-threaded user-interface applications, classDisplay
provides inter-thread communication methods which allow threads other than the user-interface thread to request that it perform operations on their behalf.) -
The thread is not allowed to construct other
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.)
Enforcing these attributes allows SWT to be implemented directly on the underlying operating system's event model. This has numerous benefits including smaller footprint, better use of resources, safer memory management, clearer program logic, better performance, and fewer overall operating system threads required. The down side however, is that care must be taken (only) when constructing multi-threaded applications to use the inter-thread communication mechanisms which this class provides when required.
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.
- Styles:
- (none)
- Events:
- Close, Dispose, OpenDocument, Settings, Skin
IMPORTANT: This class is not intended to be subclassed.
- See Also:
- Restriction:
- This class is not intended to be subclassed by clients.
-
Field Summary
Modifier and TypeFieldDescriptionorg.eclipse.swt.internal.win32.MSG
the handle to the OS message queue (Warning: This field is platform dependent)Fields inherited from class org.eclipse.swt.graphics.Device
CurrentDevice, DEBUG, DeviceFinder
-
Constructor Summary
ConstructorDescriptionDisplay()
Constructs a new instance of this class.Display
(DeviceData data) Constructs a new instance of this class using the parameter. -
Method Summary
Modifier and TypeMethodDescriptionvoid
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
Causes therun()
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
Throws anSWTException
if the receiver can not be accessed by the caller.protected void
Checks that this class can be subclassed.void
close()
Requests that the connection between SWT and the underlying operating system be closed.protected void
create
(DeviceData data) Creates the device in the operating system.protected void
destroy()
Destroys the device in the operating system and releases the device's handle.void
disposeExec
(Runnable runnable) Causes therun()
method of the runnable to be invoked by the user-interface thread just before the receiver is disposed.void
Executes the given runnable in the user-interface thread of this Display.static Display
findDisplay
(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.findWidget
(long handle) Given the operating system handle for a widget, returns the instance of theWidget
subclass which represents it in the currently running application, if such exists, or null if no matching widget can be found.findWidget
(long handle, long id) Given the operating system handle for a widget, and widget-specific id, returns the instance of theWidget
subclass which represents the handle/id pair in the currently running application, if such exists, or null if no matching widget can be found.findWidget
(Widget widget, long id) Given a widget and a widget-specific id, returns the instance of theWidget
subclass which represents the widget/id pair in the currently running application, if such exists, or null if no matching widget can be found.Returns the currently activeShell
, or null if no shell belonging to the currently running application is active.static String
Returns the application name.static String
Returns the application version.Returns a rectangle describing the receiver's size and location.Returns a rectangle which describes the area of the receiver which is capable of displaying data.static Display
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.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.Returns the location of the on-screen pointer relative to the top left corner of the screen.Point[]
Returns an array containing the recommended cursor sizes.getData()
Returns the application defined, display specific data associated with the receiver, or null if it has not been set.Returns the application defined property of the receiver with the specified name, or null if it has not been set.static Display
Returns the default display.protected int
Gets the scaling factor from the device and calculates the zoom level.int
Returns the button dismissal alignment, one ofLEFT
orRIGHT
.int
Returns the longest duration, in milliseconds, between two mouse button clicks that will be considered a double click by the underlying operating system.Returns the current exception handler.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
Returns true when the high contrast mode is enabled.int
Returns the maximum allowed depth of icons on this display, in bits per pixel.Point[]
Returns an array containing the recommended icon sizes.Returns the single instance of the application menu bar, ornull
if there is no application menu bar for the platform.Monitor[]
Returns an array of monitors attached to the device.Returns the primary monitor for that device.final Consumer<RuntimeException>
Returns the current exception handler.Shell[]
Returns a (possibly empty) array containing all shells which have not been disposed and have the receiver as their display.Gets the synchronizer used by the display.Returns the thread that has invokedsyncExec
or null if no such runnable is currently being invoked by the user-interface thread.getSystemColor
(int id) Returns the matching standard color for the given constant, which should be one of the color constants specified in classSWT
.getSystemCursor
(int id) Returns the matching standard platform cursor for the given constant, which should be one of the cursor constants specified in classSWT
.Returns a reasonable font for applications to use.getSystemImage
(int id) Returns the matching standard platform image for the given constant, which should be one of the icon constants specified in classSWT
.Returns the single instance of the system-provided menu for the application, ornull
on platforms where no menu is provided for the application.Returns the single instance of the system taskBar or null when there is no system taskBar available for the platform.Returns the single instance of the system tray or null when there is no system tray available for the platform.Returns the user-interface thread for the receiver.boolean
Returns a boolean indicating whether a touch-aware input device is attached to the system and is ready for use.protected void
init()
Initializes any internal resources needed by the device.void
internal_dispose_GC
(long hDC, GCData data) Invokes platform specific functionality to dispose a GC handle.long
internal_new_GC
(GCData data) Invokes platform specific functionality to allocate a new GC handle.boolean
Returns whether rescaling of shells at runtime when the DPI scaling of a shell's monitor changes is activated for this device.static boolean
Returnstrue
if the current OS theme has a dark appearance, else returnsfalse
.Maps a point from one coordinate system to another.Maps a point from one coordinate system to another.Maps a point from one coordinate system to another.Maps a point from one coordinate system to another.boolean
Generate a low level system event.boolean
Reads an event from the operating system's event queue, dispatches it appropriately, and returnstrue
if there is potentially more work to do, orfalse
if the caller can sleep until another event is placed on the event queue.protected void
release()
Releases any internal resources back to the operating system and clears all fields except the device handle.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.void
Sends a SWT.PostExternalEventDispatch event.void
Sends a SWT.PreExternalEventDispatch event.static void
setAppName
(String name) Sets the application name to the argument.static void
setAppVersion
(String version) Sets the application version to the argument.void
setCursorLocation
(int x, int y) Sets the location of the on-screen pointer relative to the top left corner of the screen.void
setCursorLocation
(Point point) Sets the location of the on-screen pointer relative to the top left corner of the screen.void
Sets the application defined, display specific data associated with the receiver, to the argument.void
Sets the application defined property of the receiver with the specified name to the given argument.final void
setErrorHandler
(Consumer<Error> errorHandler) Sets a callback that will be invoked whenever an error is thrown by a listener or external callback function.boolean
setRescalingAtRuntime
(boolean activate) Activates or deactivates rescaling of shells at runtime whenever the DPI scaling of the shell's monitor changes.final void
setRuntimeExceptionHandler
(Consumer<RuntimeException> runtimeExceptionHandler) Sets a callback that will be invoked whenever an exception is thrown by a listener or external callback function.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.<T,
E extends Exception>
TsyncCall
(SwtCallable<T, E> callable) Calls the callable on the user-interface thread at the next reasonable opportunity, and returns the its result from this method.void
Causes therun()
method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity.void
Causes therun()
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()
If the receiver's user-interface thread wassleep
ing, causes it to be awakened and start running again.Methods inherited from class org.eclipse.swt.graphics.Device
dispose, getDepth, getDeviceData, getDPI, getFontList, getWarnings, isDisposed, isTracking, loadFont, setTracking, setWarnings
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface org.eclipse.swt.graphics.Drawable
isAutoScalable
-
Field Details
-
msg
public org.eclipse.swt.internal.win32.MSG msgthe handle to the OS message queue (Warning: This field is platform dependent)IMPORTANT: This field is not part of the SWT public API. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms and should never be accessed from application code.
- Restriction:
- This field is not intended to be referenced by clients.
-
-
Constructor Details
-
Display
public Display()Constructs a new instance of this class.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.
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display
- ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
- See Also:
-
Display
Constructs a new instance of this class using the parameter.- Parameters:
data
- the device data
-
-
Method Details
-
addFilter
Adds the listener to the collection of listeners who will be notified when an event of the given type occurs anywhere in a widget. The event type is one of the event constants defined in classSWT
. When the event does occur, the listener is notified by sending it thehandleEvent()
message.Setting the type of an event to
SWT.None
from within thehandleEvent()
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.- Parameters:
eventType
- the type of event to listen forlistener
- the listener which should be notified when the event occurs- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the listener is null
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.0
- See Also:
-
addListener
Adds the listener to the collection of listeners who will be notified when an event of the given type occurs. The event type is one of the event constants defined in classSWT
. When the event does occur in the display, the listener is notified by sending it thehandleEvent()
message.- Parameters:
eventType
- the type of event to listen forlistener
- the listener which should be notified when the event occurs- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the listener is null
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.0
- See Also:
-
asyncExec
Causes therun()
method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity. The caller of this method continues to run in parallel, and is not notified when the runnable has completed. Specifyingnull
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.
- Parameters:
runnable
- code to run on the user-interface thread ornull
- Throws:
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
execute
Executes the given runnable in the user-interface thread of this Display.- If the calling thread is the user-interface thread of this display it is
executed immediately and the method returns after the command has run, as with
the method
syncExec(Runnable)
. - In all other cases the
run()
method of the runnable is asynchronously executed as with the methodasyncExec(Runnable)
at the next reasonable opportunity. The caller of this method continues to run in parallel, and is not notified when the runnable has completed.
This can be used in cases where one want to execute some piece of code that should be guaranteed to run in the user-interface thread regardless of the current 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 advised to check for this case inside the runnable before accessing the widget.
- Specified by:
execute
in interfaceExecutor
- Parameters:
runnable
- the runnable to execute in the user-interface thread, nevernull
- Throws:
RejectedExecutionException
- if this task cannot be accepted for executionNullPointerException
- if runnable is null
- If the calling thread is the user-interface thread of this display it is
executed immediately and the method returns after the command has run, as with
the method
-
beep
public void beep()Causes the system hardware to emit a short sound (if it supports this capability).- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
checkSubclass
protected void checkSubclass()Checks that this class can be subclassed.IMPORTANT: See the comment in
Widget.checkSubclass()
.- Throws:
SWTException
-- ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
- See Also:
-
checkDevice
protected void checkDevice()Description copied from class:Device
Throws anSWTException
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()
anddispose()
) on a device that has had itsdispose()
method called.In future releases of SWT, there may be more or fewer error checks and exceptions may be thrown for different reasons.
- Overrides:
checkDevice
in classDevice
-
close
public void close()Requests that the connection between SWT and the underlying operating system be closed.- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.0
- See Also:
-
create
Creates the device in the operating system. If the device does not have a handle, this method may do nothing depending on the device.This method is called before
init
. -
destroy
protected void destroy()Destroys the device in the operating system and releases the device's handle. If the device does not have a handle, this method may do nothing depending on the device.This method is called after
release
. -
disposeExec
Causes therun()
method of the runnable to be invoked by the user-interface thread just before the receiver is disposed. Specifying anull
runnable is ignored.- Parameters:
runnable
- code to run at dispose time.- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
findWidget
Given the operating system handle for a widget, returns the instance of theWidget
subclass which represents it in the currently running application, if such exists, or null if no matching widget can be found.IMPORTANT: This method should not be called from application code. The arguments are platform-specific.
- Parameters:
handle
- the handle for the widget- Returns:
- the SWT widget that the handle represents
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Restriction:
- This method is not intended to be referenced by clients.
-
findWidget
Given the operating system handle for a widget, and widget-specific id, returns the instance of theWidget
subclass which represents the handle/id pair in the currently running application, if such exists, or null if no matching widget can be found.IMPORTANT: This method should not be called from application code. The arguments are platform-specific.
- Parameters:
handle
- the handle for the widgetid
- the id for the subwidget (usually an item)- Returns:
- the SWT widget that the handle/id pair represents
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.1
- Restriction:
- This method is not intended to be referenced by clients.
-
findWidget
Given a widget and a widget-specific id, returns the instance of theWidget
subclass which represents the widget/id pair in the currently running application, if such exists, or null if no matching widget can be found.- Parameters:
widget
- the widgetid
- the id for the subwidget (usually an item)- Returns:
- the SWT subwidget (usually an item) that the widget/id pair represents
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.3
- Restriction:
- This method is not intended to be referenced by clients.
-
findDisplay
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. Specifyingnull
as the thread will returnnull
for the display.- Parameters:
thread
- the user-interface thread- Returns:
- the display for the given thread
-
getActiveShell
Returns the currently activeShell
, or null if no shell belonging to the currently running application is active.- Returns:
- the active shell or null
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
getMenuBar
Returns the single instance of the application menu bar, ornull
if there is no application menu bar for the platform.- Returns:
- the application menu bar, or
null
- Throws:
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.7
-
getBounds
Returns a rectangle describing the receiver's size and location. Note that on multi-monitor systems the origin can be negative.- Overrides:
getBounds
in classDevice
- Returns:
- the bounding rectangle
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
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.- Returns:
- the current display
-
getClientArea
Returns a rectangle which describes the area of the receiver which is capable of displaying data.- Overrides:
getClientArea
in classDevice
- Returns:
- the client area
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
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.- Returns:
- the control under the cursor or
null
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
getCursorLocation
Returns the location of the on-screen pointer relative to the top left corner of the screen.- Returns:
- the cursor location
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
getCursorSizes
Returns an array containing the recommended cursor sizes.- Returns:
- the array of cursor sizes
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.0
-
getDefault
Returns the default display. One is created (making the thread that invokes this method its user-interface thread) if it did not already exist.- Returns:
- the default display
-
getDeviceZoom
protected int getDeviceZoom()Description copied from class:Device
Gets the scaling factor from the device and calculates the zoom level.- Overrides:
getDeviceZoom
in classDevice
- Returns:
- zoom in percentage
- Since:
- 3.108
-
getData
Returns the application defined property of the receiver with the specified name, or null if it has not been set.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.- Parameters:
key
- the name of the property- Returns:
- the value of the property or null if it has not been set
- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the key is null
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
getData
Returns the application defined, display specific data associated with the receiver, or null if it has not been set. The display specific data is a single, unnamed field that is stored with every display.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.- Returns:
- the display specific data
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
getDismissalAlignment
public int getDismissalAlignment()Returns the button dismissal alignment, one ofLEFT
orRIGHT
. 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 isLEFT
, the button ordering should be OK/CANCEL. When button dismissal alignment isRIGHT
, the button ordering should be CANCEL/OK.- Returns:
- the button dismissal order
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.1
-
getDoubleClickTime
public int getDoubleClickTime()Returns the longest duration, in milliseconds, between two mouse button clicks that will be considered a double click by the underlying operating system.- Returns:
- the double click time
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
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.- Returns:
- the focus control or
null
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
getHighContrast
public boolean getHighContrast()Returns true when the high contrast mode is enabled. Otherwise, false is returned.Note: This operation is a hint and is not supported on platforms that do not have this concept.
- Returns:
- the high contrast mode
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.0
-
getIconDepth
public int getIconDepth()Returns the maximum allowed depth of icons on this display, in bits per pixel. On some platforms, this may be different than the actual depth of the display.- Returns:
- the maximum icon depth
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
getIconSizes
Returns an array containing the recommended icon sizes.- Returns:
- the array of icon sizes
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.0
- See Also:
-
isSystemDarkTheme
public static boolean isSystemDarkTheme()Returnstrue
if the current OS theme has a dark appearance, else returnsfalse
.Note: This operation is a hint and is not supported on platforms that do not have this concept.
Note: Windows 10 onwards users can separately configure the theme for OS and Application level and this can be read from the Windows registry. Since the application needs to honor the application level theme, this API reads the Application level theme setting.
- Returns:
true
if the current OS theme has a dark appearance, else returnsfalse
.- Since:
- 3.112
-
getMonitors
Returns an array of monitors attached to the device.- Returns:
- the array of monitors
- Since:
- 3.0
-
getPrimaryMonitor
Returns the primary monitor for that device.- Returns:
- the primary monitor
- Since:
- 3.0
-
getShells
Returns a (possibly empty) array containing all shells which have not been disposed and have the receiver as their display.- Returns:
- the receiver's shells
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
getSynchronizer
Gets the synchronizer used by the display.- Returns:
- the receiver's synchronizer
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.4
-
getSyncThread
Returns the thread that has invokedsyncExec
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.
- Returns:
- the receiver's sync-interface thread
- Throws:
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
getSystemColor
Returns the matching standard color for the given constant, which should be one of the color constants specified in classSWT
. 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.- Overrides:
getSystemColor
in classDevice
- Parameters:
id
- the color constant- Returns:
- the matching color
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
getSystemCursor
Returns the matching standard platform cursor for the given constant, which should be one of the cursor constants specified in classSWT
. This cursor should not be free'd because it was allocated by the system, not the application. A value ofnull
will be returned if the supplied constant is not an SWT cursor constant.- Parameters:
id
- the SWT cursor constant- Returns:
- the corresponding cursor or
null
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.0
- See Also:
-
SWT.CURSOR_ARROW
SWT.CURSOR_WAIT
SWT.CURSOR_CROSS
SWT.CURSOR_APPSTARTING
SWT.CURSOR_HELP
SWT.CURSOR_SIZEALL
SWT.CURSOR_SIZENESW
SWT.CURSOR_SIZENS
SWT.CURSOR_SIZENWSE
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_UPARROW
SWT.CURSOR_IBEAM
SWT.CURSOR_NO
SWT.CURSOR_HAND
-
getSystemFont
Returns a reasonable font for applications to use. On some platforms, this will match the "default font" or "system font" if such can be found. This font should not be free'd because it was allocated by the system, not the application.Typically, applications which want the default look should simply not set the font on the widgets they create. Widgets are always created with the correct default font for the class of user-interface component they represent.
- Overrides:
getSystemFont
in classDevice
- Returns:
- a font
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
getSystemImage
Returns the matching standard platform image for the given constant, which should be one of the icon constants specified in classSWT
. This image should not be free'd because it was allocated by the system, not the application. A value ofnull
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.- Parameters:
id
- the SWT icon constant- Returns:
- the corresponding image or
null
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.0
- See Also:
-
getSystemMenu
Returns the single instance of the system-provided menu for the application, ornull
on platforms where no menu is provided for the application.- Returns:
- the system menu, or
null
- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.7
-
getSystemTaskBar
Returns the single instance of the system taskBar or null when there is no system taskBar available for the platform.- Returns:
- the system taskBar or
null
- Throws:
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.6
-
getSystemTray
Returns the single instance of the system tray or null when there is no system tray available for the platform.- Returns:
- the system tray or
null
- Throws:
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.0
-
getThread
Returns the user-interface thread for the receiver.- Returns:
- the receiver's user-interface thread
- Throws:
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
-
getTouchEnabled
public boolean getTouchEnabled()Returns a boolean indicating whether a touch-aware input device is attached to the system and is ready for use.- Returns:
true
if a touch-aware input device is detected, orfalse
otherwise- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.7
-
internal_new_GC
Invokes platform specific functionality to allocate a new GC handle.IMPORTANT: This method is not part of the public API for
Display
. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.- Specified by:
internal_new_GC
in interfaceDrawable
- Specified by:
internal_new_GC
in classDevice
- Parameters:
data
- the platform specific GC data- Returns:
- the platform specific GC handle
- Throws:
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
SWTError
-- ERROR_NO_HANDLES if a handle could not be obtained for gc creation
- Restriction:
- This method is not intended to be referenced by clients.
-
init
protected void init()Initializes any internal resources needed by the device.This method is called after
create
. -
internal_dispose_GC
Invokes platform specific functionality to dispose a GC handle.IMPORTANT: This method is not part of the public API for
Display
. It is marked public only so that it can be shared within the packages provided by SWT. It is not available on all platforms, and should never be called from application code.- Specified by:
internal_dispose_GC
in interfaceDrawable
- Specified by:
internal_dispose_GC
in classDevice
- Parameters:
hDC
- the platform specific GC handledata
- the platform specific GC data- Restriction:
- This method is not intended to be referenced by clients.
-
map
Maps a point from one coordinate system to another. When the control is null, coordinates are mapped to the display.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.
- Parameters:
from
- the sourceControl
ornull
to
- the destinationControl
ornull
point
- to be mapped- Returns:
- point with mapped coordinates
- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the point is null
- ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.1.2
-
map
Maps a point from one coordinate system to another. When the control is null, coordinates are mapped to the display.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.
- Parameters:
from
- the sourceControl
ornull
to
- the destinationControl
ornull
x
- coordinates to be mappedy
- coordinates to be mapped- Returns:
- point with mapped coordinates
- Throws:
IllegalArgumentException
-- ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.1.2
-
map
Maps a point from one coordinate system to another. When the control is null, coordinates are mapped to the display.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.
- Parameters:
from
- the sourceControl
ornull
to
- the destinationControl
ornull
rectangle
- to be mapped- Returns:
- rectangle with mapped coordinates
- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the rectangle is null
- ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.1.2
-
map
Maps a point from one coordinate system to another. When the control is null, coordinates are mapped to the display.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.
- Parameters:
from
- the sourceControl
ornull
to
- the destinationControl
ornull
x
- coordinates to be mappedy
- coordinates to be mappedwidth
- coordinates to be mappedheight
- coordinates to be mapped- Returns:
- rectangle with mapped coordinates
- Throws:
IllegalArgumentException
-- ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.1.2
-
post
Generate a low level system event.post
is used to generate low level keyboard and mouse events. The intent is to enable automated UI testing by simulating the input from the user. Most SWT applications should never need to call this method.Note that this operation can fail when the operating system fails to generate the event for any reason. For example, this can happen when there is no such key or mouse button or when the system event queue is full.
Event Types:
KeyDown, KeyUp
The following fields in the
Event
apply:- (in) type KeyDown or KeyUp
Either one of:
- (in) character a character that corresponds to a keyboard key
- (in) keyCode the key code of the key that was typed,
as defined by the key code constants in class
SWT
Optional (on some platforms):
- (in) stateMask the state of the keyboard modifier,
as defined by the key code constants in class
SWT
MouseDown, MouseUp
The following fields in the
Event
apply:- (in) type MouseDown or MouseUp
- (in) button the button that is pressed or released
MouseMove
The following fields in the
Event
apply:- (in) type MouseMove
- (in) x the x coordinate to move the mouse pointer to in screen coordinates
- (in) y the y coordinate to move the mouse pointer to in screen coordinates
MouseWheel
The following fields in the
Event
apply:- (in) type MouseWheel
- (in) detail either SWT.SCROLL_LINE or SWT.SCROLL_PAGE
- (in) count the number of lines or pages to scroll
- Parameters:
event
- the event to be generated- Returns:
- true if the event was generated or false otherwise
- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the event is null
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 3.0
-
readAndDispatch
public boolean readAndDispatch()Reads an event from the operating system's event queue, dispatches it appropriately, and returnstrue
if there is potentially more work to do, orfalse
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()
orasyncExec()
) are waiting to be processed, and if so handles them before returning.- Returns:
false
if the caller can sleep upon return from this method- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message
- See Also:
-
release
protected void release()Releases any internal resources back to the operating system and clears all fields except the device handle.Disposes all shells which are currently open on the display. After this method has been invoked, all related related shells will answer
true
when sent the messageisDisposed()
.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
This method is called beforerelease
. 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 bydestroy
.destroy
. -
removeFilter
Removes the listener from the collection of listeners who will be notified when an event of the given type occurs anywhere in a widget. The event type is one of the event constants defined in classSWT
.- Parameters:
eventType
- the type of event to listen forlistener
- the listener which should no longer be notified when the event occurs- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the listener is null
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- Since:
- 3.0
- See Also:
-
removeListener
Removes the listener from the collection of listeners who will be notified when an event of the given type occurs. The event type is one of the event constants defined in classSWT
.- Parameters:
eventType
- the type of event to listen forlistener
- the listener which should no longer be notified- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the listener is null
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.0
- See Also:
-
sendPreExternalEventDispatchEvent
public void sendPreExternalEventDispatchEvent()Sends a SWT.PreExternalEventDispatch event.- Restriction:
- This method is not intended to be referenced by clients.
-
sendPostExternalEventDispatchEvent
public void sendPostExternalEventDispatchEvent()Sends a SWT.PostExternalEventDispatch event.- Restriction:
- This method is not intended to be referenced by clients.
-
setCursorLocation
public void setCursorLocation(int x, int y) Sets the location of the on-screen pointer relative to the top left corner of the screen. Note: It is typically considered bad practice for a program to move the on-screen pointer location.- Parameters:
x
- the new x coordinate for the cursory
- the new y coordinate for the cursor- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.1
-
setCursorLocation
Sets the location of the on-screen pointer relative to the top left corner of the screen. Note: It is typically considered bad practice for a program to move the on-screen pointer location.- Parameters:
point
- new position- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_NULL_ARGUMENT - if the point is null
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- Since:
- 2.0
-
setData
Sets the application defined property of the receiver with the specified name to the given argument.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.- Parameters:
key
- the name of the propertyvalue
- the new value for the property- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the key is null
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
setData
Sets the application defined, display specific data associated with the receiver, to the argument. The display specific data is a single, unnamed field that is stored with every display.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.- Parameters:
data
- the new display specific data- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
getAppName
Returns the application name.- Returns:
- the application name
- Since:
- 3.6
- See Also:
-
getAppVersion
Returns the application version.- Returns:
- the application version
- Since:
- 3.6
- See Also:
-
setAppName
Sets the application name to the argument.The application name can be used in several ways, depending on the platform and tools being used. Accessibility tools could ask for the application name. On Windows, if the application name is set to any value other than "SWT" (case insensitive), it is used to set the application user model ID which is used by the OS for taskbar grouping.
Specifying
null
for the name clears it.- Parameters:
name
- the new app name ornull
- See Also:
-
setAppVersion
Sets the application version to the argument.- Parameters:
version
- the new app version- Since:
- 3.6
-
setSynchronizer
Sets the synchronizer used by the display to be the argument, which can not be null.- Parameters:
synchronizer
- the new synchronizer for the display (must not be null)- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the synchronizer is null
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message
-
setRuntimeExceptionHandler
Sets a callback that will be invoked whenever an exception is thrown by a listener or external callback function. The application may use this to set a global exception handling policy: the most common policies are either to log and discard the exception or to re-throw the exception.The default SWT error handling policy is to rethrow exceptions.
- Parameters:
runtimeExceptionHandler
- new exception handler to be registered.- Since:
- 3.106
-
getRuntimeExceptionHandler
Returns the current exception handler. It will receive all exceptions thrown by listeners and external callbacks in this display. If code wishes to temporarily replace the exception handler (for example, during a unit test), it is common practice to invoke this method prior to replacing the exception handler so that the old handler may be restored afterward.- Returns:
- the current exception handler. Never
null
. - Since:
- 3.106
-
setErrorHandler
Sets a callback that will be invoked whenever an error is thrown by a listener or external callback function. The application may use this to set a global exception handling policy: the most common policies are either to log and discard the exception or to re-throw the exception.The default SWT error handling policy is to rethrow exceptions.
- Parameters:
errorHandler
- new error handler to be registered.- Since:
- 3.106
-
getErrorHandler
Returns the current exception handler. It will receive all errors thrown by listeners and external callbacks in this display. If code wishes to temporarily replace the error handler (for example, during a unit test), it is common practice to invoke this method prior to replacing the error handler so that the old handler may be restored afterward.- Returns:
- the current error handler. Never
null
. - Since:
- 3.106
-
sleep
public 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.- Returns:
true
if an event requiring dispatching was placed on the queue.- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
syncExec
Causes therun()
method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity. The thread which calls this method is suspended until the runnable completes. Specifyingnull
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.
- Parameters:
runnable
- code to run on the user-interface thread ornull
- Throws:
SWTException
-- ERROR_FAILED_EXEC - if an exception occurred when executing the runnable
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
syncCall
Calls the callable on the user-interface thread at the next reasonable opportunity, and returns the its result from this method. The thread which calls this method is suspended until the callable completes.Note that at the time the callable 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 callable before accessing the widget.
Any exception that is thrown from the callable is re-thrown in the calling thread. Note: The exception retains its original stack trace from the throwing thread. The call to
syncCall
will not be present in the stack trace.- Parameters:
callable
- the code to call on the user-interface thread- Throws:
SWTException
-ERROR_DEVICE_DISPOSED
- if the receiver has been disposedE
- An exception that is thrown by the callable on the user-interface thread, and re-thrown on the calling thread- Since:
- 3.118
- See Also:
-
timerExec
Causes therun()
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.
- Parameters:
milliseconds
- the delay before running the runnablerunnable
- code to run on the user-interface thread- Throws:
IllegalArgumentException
-- ERROR_NULL_ARGUMENT - if the runnable is null
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
update
public void update()Forces all outstanding paint requests for the display to be processed before this method returns.- Throws:
SWTException
-- ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
wake
public void wake()If the receiver's user-interface thread wassleep
ing, causes it to be awakened and start running again. Note that this method may be called from any thread.- Throws:
SWTException
-- ERROR_DEVICE_DISPOSED - if the receiver has been disposed
- See Also:
-
isRescalingAtRuntime
public boolean isRescalingAtRuntime()Returns whether rescaling of shells at runtime when the DPI scaling of a shell's monitor changes is activated for this device.Note: This functionality is only available on Windows. Calling this method on other operating system will always return false.
- Returns:
- whether rescaling of shells at runtime when the DPI scaling of a shell's monitor changes is activated for this device
- Since:
- 3.127
-
setRescalingAtRuntime
public boolean setRescalingAtRuntime(boolean activate) Activates or deactivates rescaling of shells at runtime whenever the DPI scaling of the shell's monitor changes. This is only safe to call as long as no shell has been created for this display. When changing the value after a shell has been created for this display, the effect is undefined.Note: This functionality is only available on Windows. Calling this method on other operating system will have no effect.
- Parameters:
activate
- whether rescaling shall be activated or deactivated- Returns:
- whether activating or deactivating the rescaling was successful
- Since:
- 3.127
-