Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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` | `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(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.
`Point[]` | `getCursorSizes()` Returns an array containing the recommended cursor sizes.
`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` | `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.
`boolean` | `getHighContrast()` Returns true when the high contrast mode is enabled.
`int` | `getIconDepth()` Returns the maximum allowed depth of icons on this display.
`Point[]` | `getIconSizes()` Returns an array containing the recommended icon sizes.
`Monitor[]` | `getMonitors()` Returns an array of monitors attached to the device.
`Monitor` | `getPrimaryMonitor()` Returns the primary monitor for that device.
`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`.
`Cursor` | `getSystemCursor(int id)` Returns the matching standard platform cursor for the given constant, which should be one of the cursor constants specified in class `SWT`.
`Font` | `getSystemFont()` Returns a reasonable font for applications to use.
`Image` | `getSystemImage(int id)` Returns the matching standard platform image for the given constant, which should be one of the icon constants specified in class `SWT`.
`Tray` | `getSystemTray()` Returns the single instance of the system tray.
`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.
`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.
`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 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(String name)` On platforms which support it, sets the application name to be 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` | `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` -
  - ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent
  - ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass
See Also:
  `getCurrent()`, `getDefault()`, `Widget.checkSubclass()`, `Shell`

### Display

    public Display(DeviceData data)

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.

  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
    - 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:
    `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(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.
  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

### 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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  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.
  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

    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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### 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
    - 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()`

### 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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### 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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### getCursorSizes

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

    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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  See Also:
    `setData(String, Object)`, `disposeExec(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 - 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

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

### getIconSizes

    public Point[] 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:
    `Decorations.setImages(Image[])`

### getMonitors

    public Monitor[] getMonitors()

  Returns an array of monitors attached to the device.

  Returns:
    the array of monitors
  Since:
    3.0

### getPrimaryMonitor

    public Monitor getPrimaryMonitor()

  Returns the primary monitor for that device.

  Returns:
    the primary monitor
  Since:
    3.0

### 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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

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

### getSystemCursor

    public Cursor getSystemCursor(int id)

  Returns the matching standard platform cursor for the given constant, which should be one of the cursor constants specified in class `SWT`. This cursor should not be free'd because it was allocated by the system, not the application. A value of `null` will be returned if the supplied constant is not an swt cursor constant.

  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

    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

### getSystemImage

    public Image getSystemImage(int id)

  Returns the matching standard platform image for the given constant, which should be one of the icon constants specified in class `SWT`. This image should not be free'd because it was allocated by the system, not the application. A value of `null` will be returned either if the supplied constant is not an swt icon constant or if the platform does not define an image that corresponds to the constant.

  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:
    `SWT.ICON_ERROR`, `SWT.ICON_INFORMATION`, `SWT.ICON_QUESTION`, `SWT.ICON_WARNING`, `SWT.ICON_WORKING`

### getSystemTray

    public Tray getSystemTray()

  Returns the single instance of the system tray.

  Returns:
    the receiver's user-interface thread
  Throws:
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  Since:
    3.0

### getThread

    public 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

### 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
  Throws:
    `SWTError` -
    - ERROR_NO_HANDLES if a handle could not be obtained for image creation
    `SWTException` -
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### 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:
    `hDC` - the platform specific GC handle
    `data` - the platform specific GC data

### 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:
    `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

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

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

    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.

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

### 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:
    `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:
    `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)`

### 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 cursor
    `y` - 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

    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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  See Also:
    `getData(String)`, `disposeExec(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 - 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(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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed

### 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(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
    - ERROR_DEVICE_DISPOSED - if the receiver has been disposed
  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
    - 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 `sleep`'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:
    `sleep()`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.