Follow Techotopia on Twitter

On-line Guides
All Guides
eBook Store
iOS / Android
Linux for Beginners
Office Productivity
Linux Installation
Linux Security
Linux Utilities
Linux Virtualization
Linux Kernel
System/Network Admin
Programming
Scripting Languages
Development Tools
Web Development
GUI Toolkits/Desktop
Databases
Mail Systems
openSolaris
Eclipse Documentation
Techotopia.com
Virtuatopia.com
Answertopia.com

How To Guides
Virtualization
General System Admin
Linux Security
Linux Filesystems
Web Servers
Graphics & Desktop
PC Hardware
Windows
Problem Solutions
Privacy Policy

  




 

 

Eclipse Rich Ajax Platform
Release 1.2

org.eclipse.swt.widgets
Class Display


java.lang.Object
  extended by

org.eclipse.swt.graphics.Device
      extended by
org.eclipse.swt.widgets.Display
All Implemented Interfaces:
Adaptable

public class Display
extends Device
implements Adaptable

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.

Since:
1.0
See Also:
syncExec(java.lang.Runnable), asyncExec(java.lang.Runnable), wake(), readAndDispatch(),

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 notified when an event of the given type occurs anywhere in a widget.
 void asyncExec ( Runnable runnable)
          Causes the run() method of the runnable to be invoked by the user-interface thread at the next reasonable opportunity.
  Shell getActiveShell ()
          Returns the currently active Shell, or null if no shell belonging to the currently running application is active.
  Object getAdapter ( Class adapter)
          Returns an object which is an instance of the given class parameter associated with this object or null if no association exists.
  Rectangle getBounds ()
          Returns a rectangle describing the receiver's size and location.
static  Display getCurrent ()
          Returns the display which the currently running thread is the user-interface thread for, or null if the currently running thread is not a user-interface thread for any display.
  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 .
  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.
  Monitor[] getMonitors ()
          Returns an array of monitors attached to the device.
  Monitor getPrimaryMonitor ()
          Returns the primary monitor for that device.
  Shell[] getShells ()
          Returns a (possibly empty) array containing all shells which have not been disposed and have the receiver as their display.
  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.
  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.
  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 readAndDispatch ()
          Reads an event from the event queue, dispatches it appropriately, and returns true if there is potentially more work to do, or false if the caller can sleep until another event is placed on the event queue.
 void release ()
          Releases any internal resources .
 void removeFilter (int eventType, Listener listener)
          Removes the listener from the collection of listeners who will be notified when an event of the given type occurs anywhere in a widget.
 void 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.
 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 wake ()
          Notifies the client side to send a life cycle request as UI thread to perform UI-updates.
 
Methods inherited from class org.eclipse.swt.graphics. Device
checkDevice, destroy, dispose, getClientArea, getSystemFont, isDisposed
 
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

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

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.

RWT specific: This will not return a new display if there is none available. This may be fixed in the future.

Returns:
the default display

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

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

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

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

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

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

release

public void release()
Description copied from class: Device
Releases any internal resources .

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.

If subclasses reimplement this method, they must call the super implementation.

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

getAdapter

public 
Object getAdapter(
Class adapter)
Description copied from interface: Adaptable

Returns an object which is an instance of the given class parameter associated with this object or null if no association exists.

Specified by:
getAdapter in interface Adaptable
Parameters:
adapter - the lookup class
Returns:
a object castable to the given class or null if there is no adapter associated with the given class.

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

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

getThread

public 
Thread getThread()
Returns the user-interface thread for the receiver. Note that the user-interface thread may change per user-request.

Returns:
the receiver's user-interface thread or null if there's no current user-request executed that belongs to the display.
Throws:
SWTException -
  • ERROR_DEVICE_DISPOSED - if the receiver has been disposed

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. Note that the user-interface thread may change per user-request. The caller of this method continues to run in parallel, and is not notified when the runnable has completed. Specifying null as the runnable simply wakes the user-interface thread when run.

Note that at the time the runnable is invoked, widgets that have the receiver as their display may have been disposed. Therefore, it is necessary to check for this case inside the runnable before accessing the widget.

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)

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. Note that the user-interface thread may change per user-request. The thread which calls this method is suspended until the runnable completes. Specifying null as the runnable simply wakes the user-interface thread.

Note that at the time the runnable is invoked, widgets that have the receiver as their display may have been disposed. Therefore, it is necessary to check for this case inside the runnable before accessing the widget.

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,
                      
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:
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
Since:
1.2
See Also:
asyncExec(java.lang.Runnable)

readAndDispatch

public boolean readAndDispatch()
Reads an event from the event queue, dispatches it appropriately, and returns true if there is potentially more work to do, or false if the caller can sleep until another event is placed on the event queue.

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

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

wake

public void wake()
Notifies the client side to send a life cycle request as UI thread to perform UI-updates. Note that this method may be called from any thread.

Note that this only works as expected if the UICallBack mechanism is activated.

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

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

getDoubleClickTime

public int getDoubleClickTime()
Returns the longest duration, in milliseconds, between two mouse button clicks that will be considered a double click .

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
Since:
1.2

addFilter

public void addFilter(int eventType,
                      
Listener listener)
Adds the listener to the collection of listeners who will be notified when an event of the given type occurs anywhere in a widget. The event type is one of the event constants defined in class SWT. When the event does occur, the listener is notified by sending it the handleEvent() message.

Setting the type of an event to SWT.None from within the handleEvent() method can be used to change the event type and stop subsequent Java listeners from running. Because event filters run before other listeners, event filters can both block other listeners and set arbitrary fields within an event. For this reason, event filters are both powerful and dangerous. They should generally be avoided for performance, debugging and code maintenance reasons.

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
See Also:
Listener, SWT,

removeFilter

public void removeFilter(int eventType,
                         
Listener listener)
Removes the listener from the collection of listeners who will be notified when an event of the given type occurs anywhere in a widget. The event type is one of the event constants defined in class SWT.

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
See Also:
Listener, SWT,

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 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
Since:
1.2
See Also:
setData(Object), #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
Since:
1.2
See Also:
getData(), #disposeExec(Runnable)

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
Since:
1.2
See Also:
getData(String), #disposeExec(Runnable)

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

Parameters:
key - the name of the property
Returns:
the value of the property or null if it has not been set
Throws:
IllegalArgumentException -
  • ERROR_NULL_ARGUMENT - if the key is null
SWTException -
  • ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver
  • ERROR_DEVICE_DISPOSED - if the receiver has been disposed
Since:
1.2
See Also:
setData(String, Object), #disposeExec(Runnable)

getMonitors

public 
Monitor[] getMonitors()
Returns an array of monitors attached to the device.

Returns:
the array of monitors
Since:
1.2

getPrimaryMonitor

public 
Monitor getPrimaryMonitor()
Returns the primary monitor for that device.

Returns:
the primary monitor
Since:
1.2

Eclipse Rich Ajax Platform
Release 1.2

Copyright (c) Innoopract Informationssysteme GmbH and others 2002, 2008. All rights reserved.


 
 
  Published under the terms of the Eclipse Public License Version 1.0 ("EPL") Design by Interspire