Eclipse Platform
2.0

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: 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()

Field Summary
 org.eclipse.swt.internal.win32.MSG 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, hPalette
 
Constructor Summary
Display()
          Constructs a new instance of this class.
Display(DeviceData data)
           
 
Method Summary
 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(Runnable runnable)
          Causes the run() method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity.
 void beep()
          Causes the system hardware to emit a short sound (if it supports this capability).
protected  void checkDevice()
          Throws an SWTException if the receiver can not be accessed by the caller.
protected  void checkSubclass()
          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 the run() method of the runnable to be invoked by the user-interface thread just before the receiver is disposed.
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.
 Widget findWidget(int handle)
          Given the operating system handle for a widget, returns the instance of the Widget subclass which represents it in the currently running application, if such exists, or null if no matching widget can be found.
 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.
 Control getCursorControl()
          Returns the control which the on-screen pointer is currently over top of, or null if it is not currently over one of the controls built by the currently running application.
 Point getCursorLocation()
          Returns the location of the on-screen pointer relative to the top left corner of the screen.
 Object getData()
          Returns the application defined, display specific data associated with the receiver, or null if it has not been set.
 Object getData(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 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.
 Shell[] getShells()
          Returns an array containing all shells which have not been disposed and have the receiver as their display.
 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.
 Thread getThread()
          Returns the user-interface thread for the receiver.
protected  void init()
          Initializes any internal resources needed by the device.
 void internal_dispose_GC(int hDC, GCData data)
          Invokes platform specific functionality to dispose a GC handle.
 int internal_new_GC(GCData data)
          Invokes platform specific functionality to allocate a new GC handle.
 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.
protected  void release()
          Releases any internal resources back to the operating system and clears all fields except the device handle.
 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(String name)
          On platforms which support it, sets the application name to be the argument.
 void setCursorLocation(Point point)
          Sets the location of the on-screen pointer relative to the top left corner of the screen.
 void setData(Object data)
          Sets the application defined, display specific data associated with the receiver, to the argument.
 void setData(String key, 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(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, 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 sleep'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, setWarnings
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

msg

public org.eclipse.swt.internal.win32.MSG msg
the handle to the OS message queue (Warning: This field is platform dependent)

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 -
See Also:
getCurrent(), getDefault(), Widget.checkSubclass(), Shell

Display

public Display(DeviceData data)
Method Detail

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:
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:
2.0
See Also:
Listener, removeListener(int, org.eclipse.swt.widgets.Listener)

asyncExec

public void asyncExec(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.

Parameters:
runnable - code to run on the user-interface thread.
See Also:
syncExec(java.lang.Runnable)

beep

public void beep()
Causes the system hardware to emit a short sound (if it supports this capability).


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:
Widget.checkSubclass()

checkDevice

protected void checkDevice()
Description copied from class: Device
Throws an SWTException if the receiver can not be accessed by the caller. This may include both checks on the state of the receiver and more generally on the entire execution context. This method should be called by device implementors to enforce the standard SWT invariants.

Currently, it is an error to invoke any method (other than isDisposed() and dispose()) on a device that has had its dispose() method called.

In future releases of SWT, there may be more or fewer error checks and exceptions may be thrown for different reasons.

Overrides:
checkDevice in class Device

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
Since:
2.0
See Also:
Device.dispose()

create

protected void create(DeviceData data)
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.

Overrides:
create in class Device
Parameters:
data - the DeviceData which describes the receiver
See Also:
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.

Overrides:
destroy in class Device
See Also:
Device.dispose(), release()

disposeExec

public void disposeExec(Runnable runnable)
Causes the run() method of the runnable to be invoked by the user-interface thread just before the receiver is disposed.

Parameters:
runnable - code to run at dispose time.

findWidget

public Widget findWidget(int handle)
Given the operating system handle for a widget, returns the instance of the Widget subclass which represents it in the currently running application, if such exists, or null if no matching widget can be found.

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

findDisplay

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

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

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

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()
Description copied from class: Device
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
See Also:
Device.getBounds()

getCursorControl

public Control getCursorControl()
Returns the control which the on-screen pointer is currently over top of, or null if it is not currently over one of the controls built by the currently running application.

Returns:
the control under the cursor
Throws:
SWTException -
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

getCursorLocation

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

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 Object getData(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 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
See Also:
setData(java.lang.String, java.lang.Object), disposeExec(java.lang.Runnable)

getData

public 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 provide a disposeExec() handler which does so.

Returns:
the display specific data
Throws:
SWTException -
  • ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread
See Also:
setData(java.lang.String, java.lang.Object), disposeExec(java.lang.Runnable)

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

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

getIconDepth

public int getIconDepth()
Returns the maximum allowed depth of icons on this display. 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

getShells

public Shell[] getShells()
Returns an 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

getSyncThread

public 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

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

getThread

public Thread getThread()
Returns the user-interface thread for the receiver.

Returns:
the receiver's user-interface thread

internal_new_GC

public int internal_new_GC(GCData data)
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 interface Drawable
Specified by:
internal_new_GC in class Device
Parameters:
data - the platform specific GC data
Returns:
the platform specific GC handle

init

protected void init()
Initializes any internal resources needed by the device.

This method is called after create.

Overrides:
init in class Device
See Also:
create(org.eclipse.swt.graphics.DeviceData)

internal_dispose_GC

public void internal_dispose_GC(int hDC,
                                GCData data)
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 interface Drawable
Specified by:
internal_dispose_GC in class Device
Parameters:
data - the platform specific GC data

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
See Also:
sleep(), wake()

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 message isDisposed().

When a device is destroyed, resources that were acquired on behalf of the programmer need to be returned to the operating system. For example, if the device allocated a font to be used as the system font, this font would be freed in release. Also,to assist the garbage collector and minimize the amount of memory that is not reclaimed when the programmer keeps a reference to a disposed device, all fields except the handle are zero'd. The handle is needed by destroy.

This method is called before destroy.

Overrides:
release in class Device
See Also:
Device.dispose(), destroy()

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:
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:
2.0
See Also:
Listener, addListener(int, org.eclipse.swt.widgets.Listener)

setCursorLocation

public void setCursorLocation(Point point)
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
Since:
2.0

setData

public void setData(String key,
                    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:
IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the key is null
SWTException -
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
See Also:
setData(java.lang.String, java.lang.Object), disposeExec(java.lang.Runnable)

setData

public void setData(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 - when called from the wrong thread
See Also:
getData(java.lang.String), disposeExec(java.lang.Runnable)

setAppName

public static void setAppName(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:
IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the synchronizer is null
SWTException -
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

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
See Also:
wake()

syncExec

public void syncExec(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.

Parameters:
runnable - code to run on the user-interface thread.
Throws:
SWTException -
  • ERROR_FAILED_EXEC - if an exception occured when executing the runnable
See Also:
asyncExec(java.lang.Runnable)

timerExec

public void timerExec(int milliseconds,
                      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.

Parameters:
milliseconds - the delay before running the runnable
runnable - 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
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.

See Also:
Control.update()

wake

public void wake()
If the receiver's user-interface thread was sleep'ing, causes it to be awakened and start running again. Note that this method may be called from any thread.

See Also:
sleep()

Eclipse Platform
2.0

Copyright (c) IBM Corp. and others 2000, 2002. All Rights Reserved.