org.eclipse.swt.widgets
Class Display

java.lang.Object
  org.eclipse.swt.graphics.Device
      org.eclipse.swt.widgets.Display

All Implemented Interfaces:

Drawable

public class Display

extends Device

Instances of this class are responsible for managing the connection between SWT and the underlying operating system. Their most important function is to implement the SWT event loop in terms of the platform event model. They also provide various methods for accessing information about the operating system, and have overall control over the operating system resources which SWT allocates.

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 user-interface thread for a particular display has the following special attributes:

• 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, 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.)
• The thread is not allowed to construct other Displays 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

IMPORTANT: This class is not intended to be subclassed.

See Also:

syncExec(java.lang.Runnable), asyncExec(java.lang.Runnable), wake(), readAndDispatch(), sleep(), Device.dispose()

Constructor Summary

Display()
Constructs a new instance of this class.

Method Summary

void	addFilter(int eventType, Listener listener) Adds the listener to the collection of listeners who will be notifed when an event of the given type occurs anywhere in this display.
void	addListener(int eventType, Listener listener) Adds the listener to the collection of listeners who will be notifed 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).
void	close() Requests that the connection between SWT and the underlying operating system be closed.
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.
Rectangle	getBounds() Returns a rectangle describing the receiver's size and location.
Rectangle	getClientArea() Returns a rectangle which describes the area of the receiver which is capable of displaying data.
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.
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	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 by the underlying operating system.
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.
int	getIconDepth() Returns the maximum allowed depth of icons on this display, in bits per pixel.
Shell[]	getShells() Returns a (possibly empty) array containing all shells which have not been disposed and have the receiver as their 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.
Font	getSystemFont() Returns a reasonable font for applications to use.
java.lang.Thread	getThread() Returns the user-interface thread for the receiver.
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	post(Event event) Generate a low level system event.
boolean	readAndDispatch() Reads an event from the operating system's 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.
void	removeFilter(int eventType, Listener listener) Removes the listener from the collection of listeners who will be notifed when an event of the given type occurs anywhere in this display.
void	removeListener(int eventType, Listener listener) Removes the listener from the collection of listeners who will be notifed when an event of the given type occurs.
static void	setAppName(java.lang.String name) On platforms which support it, sets the application name to be 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() If the receiver's user-interface thread was sleeping, causes it to be awakened and start running again.

Methods inherited from class org.eclipse.swt.graphics.Device

checkDevice, destroy, dispose, getDepth, getDPI, getFontList, getWarnings, init, isDisposed, release, setWarnings

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

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:

getCurrent(), getDefault(), Widget.checkSubclass(), Shell

Method Detail

addFilter

public void addFilter(int eventType,
                      Listener listener)

Adds the listener to the collection of listeners who will be notifed when an event of the given type occurs anywhere in this display. 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.

Parameters:

eventType - the type of event to listen for

listener - the listener which should be notified when the event occurs

Throws:

java.lang.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:

Listener, removeFilter(int, org.eclipse.swt.widgets.Listener), removeListener(int, org.eclipse.swt.widgets.Listener)

addListener

public void addListener(int eventType,
                        Listener listener)

Adds the listener to the collection of listeners who will be notifed when an event of the given type occurs. When the event does occur in the display, the listener is notified by sending it the handleEvent() message.

Parameters:

eventType - the type of event to listen for

listener - the listener which should be notified when the event occurs

Throws:

java.lang.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:

Listener, removeListener(int, org.eclipse.swt.widgets.Listener)

asyncExec

public 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. 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.

Parameters:

runnable - code to run on the user-interface thread or null

Throws:

SWTException -

• ERROR_DEVICE_DISPOSED - if the receiver has been disposed

See Also:

syncExec(java.lang.Runnable)

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

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:

Device.dispose()

disposeExec

public 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. Specifying a null 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

findDisplay

public 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.

Parameters:

thread - the user-interface thread

Returns:

the display for the given thread

getActiveShell

public Shell getActiveShell()

Returns the currently active Shell, 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

getBounds

public Rectangle getBounds()

Returns a rectangle describing the receiver's size and location.

Overrides:

getBounds in class Device

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

public 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.

Returns:

the current display

getClientArea

public Rectangle getClientArea()

Returns a rectangle which describes the area of the receiver which is capable of displaying data.

Overrides:

getClientArea in class Device

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:

getBounds()

getDefault

public static Display 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

getData

public 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.

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:

java.lang.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(String, Object), disposeExec(Runnable)

getData

public java.lang.Object 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:

setData(Object), disposeExec(Runnable)

getDismissalAlignment

public int getDismissalAlignment()

Returns the button dismissal alignment, one of 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.

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

public 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.

Returns:

the control under 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

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:

Device.getDepth()

getShells

public Shell[] 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

getSyncThread

public 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.

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

public 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. 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 class Device

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:

SWT

getSystemFont

public Font 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 class Device

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

getThread

public java.lang.Thread 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

map

public Point map(Control from,
                 Control to,
                 Point point)

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 source Control or null

to - the destination Control or null

point - to be mapped

Returns:

point with mapped coordinates

Throws:

java.lang.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

public Point map(Control from,
                 Control to,
                 int x,
                 int y)

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 source Control or null

to - the destination Control or null

x - coordinates to be mapped

y - coordinates to be mapped

Returns:

point with mapped coordinates

Throws:

java.lang.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

public Rectangle map(Control from,
                     Control to,
                     Rectangle rectangle)

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 source Control or null

to - the destination Control or null

rectangle - to be mapped

Returns:

rectangle with mapped coordinates

Throws:

java.lang.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

post

public boolean post(Event event)

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

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

Parameters:

event - the event to be generated

Returns:

true if the event was generated or false otherwise

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the event is null

SWTException -

• ERROR_DEVICE_DISPOSED - if the receiver has been disposed

Since:

3.0

map

public Rectangle map(Control from,
                     Control to,
                     int x,
                     int y,
                     int width,
                     int height)

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 source Control or null

to - the destination Control or null

x - coordinates to be mapped

y - coordinates to be mapped

width - coordinates to be mapped

height - coordinates to be mapped

Returns:

rectangle with mapped coordinates

Throws:

java.lang.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

readAndDispatch

public boolean readAndDispatch()

Reads an event from the operating system's 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.

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.

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:

sleep(), wake()

removeFilter

public void removeFilter(int eventType,
                         Listener listener)

Removes the listener from the collection of listeners who will be notifed when an event of the given type occurs anywhere in this display.

Parameters:

eventType - the type of event to listen for

listener - the listener which should no longer be notified when the event occurs

Throws:

java.lang.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:

Listener, addFilter(int, org.eclipse.swt.widgets.Listener), addListener(int, org.eclipse.swt.widgets.Listener)

removeListener

public void removeListener(int eventType,
                           Listener listener)

Removes the listener from the collection of listeners who will be notifed when an event of the given type occurs.

Parameters:

eventType - the type of event to listen for

listener - the listener which should no longer be notified when the event occurs

Throws:

java.lang.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:

Listener, addListener(int, org.eclipse.swt.widgets.Listener)

setData

public 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.

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 property

value - the new value for the property

Throws:

java.lang.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(String), disposeExec(Runnable)

setData

public void setData(java.lang.Object data)

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:

getData(), disposeExec(Runnable)

setAppName

public static void setAppName(java.lang.String name)

On platforms which support it, sets the application name to be the argument. On Motif, for example, this can be used to set the name used for resource lookup.

Parameters:

name - the new app name

setSynchronizer

public void setSynchronizer(Synchronizer synchronizer)

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:

java.lang.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

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:

wake()

syncExec

public 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. 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.

Parameters:

runnable - code to run on the user-interface thread or null

Throws:

SWTException -

• ERROR_FAILED_EXEC - if an exception occured when executing the runnable
• ERROR_DEVICE_DISPOSED - if the receiver has been disposed

See Also:

asyncExec(java.lang.Runnable)

timerExec

public 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. 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 runnable

runnable - code to run on the user-interface thread

Throws:

java.lang.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:

asyncExec(java.lang.Runnable)

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:

Control.update()

wake

public void wake()

If the receiver's user-interface thread was sleeping, 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:

sleep()