|
Eclipse Platform 2.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--org.eclipse.swt.graphics.Device | +--org.eclipse.swt.widgets.Display
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.
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.)
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.)
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.
IMPORTANT: This class is not intended to be subclassed.
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 |
public org.eclipse.swt.internal.win32.MSG msg
Constructor Detail |
public Display()
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.
SWTException
- getCurrent()
,
getDefault()
,
Widget.checkSubclass()
,
Shell
public Display(DeviceData data)
Method Detail |
public void addListener(int eventType, Listener listener)
handleEvent()
message.
eventType
- the type of event to listen forlistener
- the listener which should be notified when the event occurs
IllegalArgumentException
- SWTException
- Listener
,
removeListener(int, org.eclipse.swt.widgets.Listener)
public void asyncExec(Runnable runnable)
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.
runnable
- code to run on the user-interface thread.syncExec(java.lang.Runnable)
public void beep()
protected void checkSubclass()
IMPORTANT: See the comment in Widget.checkSubclass()
.
SWTException
- Widget.checkSubclass()
protected void checkDevice()
Device
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.
checkDevice
in class Device
public void close()
SWTException
- Device.dispose()
protected void create(DeviceData data)
This method is called before init
.
create
in class Device
data
- the DeviceData which describes the receiverinit()
protected void destroy()
This method is called after release
.
destroy
in class Device
Device.dispose()
,
release()
public void disposeExec(Runnable runnable)
run()
method of the runnable to
be invoked by the user-interface thread just before the
receiver is disposed.
runnable
- code to run at dispose time.public Widget findWidget(int handle)
Widget
subclass which
represents it in the currently running application, if
such exists, or null if no matching widget can be found.
handle
- the handle for the widget
SWTException
- public static Display findDisplay(Thread thread)
thread
- the user-interface thread
public Shell getActiveShell()
Shell
, or null
if no shell belonging to the currently running application
is active.
SWTException
- public Rectangle getBounds()
getBounds
in class Device
SWTException
- public static Display getCurrent()
public Rectangle getClientArea()
Device
getClientArea
in class Device
Device.getBounds()
public Control getCursorControl()
SWTException
- public Point getCursorLocation()
SWTException
- public static Display getDefault()
public Object getData(String key)
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.
key
- the name of the property
IllegalArgumentException
- SWTException
- setData(java.lang.String, java.lang.Object)
,
disposeExec(java.lang.Runnable)
public Object getData()
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.
SWTException
- setData(java.lang.String, java.lang.Object)
,
disposeExec(java.lang.Runnable)
public int getDoubleClickTime()
SWTException
- public Control getFocusControl()
SWTException
- public int getIconDepth()
SWTException
- public Shell[] getShells()
SWTException
- public Thread getSyncThread()
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.
public Color getSystemColor(int id)
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.
getSystemColor
in class Device
id
- the color constant
SWTException
- SWT
public Font getSystemFont()
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.
getSystemFont
in class Device
SWTException
- public Thread getThread()
public int internal_new_GC(GCData data)
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.
internal_new_GC
in interface Drawable
internal_new_GC
in class Device
data
- the platform specific GC data
protected void init()
This method is called after create
.
init
in class Device
create(org.eclipse.swt.graphics.DeviceData)
public void internal_dispose_GC(int hDC, GCData data)
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.
internal_dispose_GC
in interface Drawable
internal_dispose_GC
in class Device
data
- the platform specific GC datapublic boolean readAndDispatch()
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.
false
if the caller can sleep upon return from this method
SWTException
- sleep()
,
wake()
protected void release()
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
.
destroy
.
release
in class Device
Device.dispose()
,
destroy()
public void removeListener(int eventType, Listener listener)
eventType
- the type of event to listen forlistener
- the listener which should no longer be notified when the event occurs
IllegalArgumentException
- SWTException
- Listener
,
addListener(int, org.eclipse.swt.widgets.Listener)
public void setCursorLocation(Point point)
point
- new position
SWTException
- public void setData(String key, Object value)
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.
key
- the name of the propertyvalue
- the new value for the property
IllegalArgumentException
- SWTException
- setData(java.lang.String, java.lang.Object)
,
disposeExec(java.lang.Runnable)
public void setData(Object data)
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.
data
- the new display specific data
SWTException
- getData(java.lang.String)
,
disposeExec(java.lang.Runnable)
public static void setAppName(String name)
name
- the new app namepublic void setSynchronizer(Synchronizer synchronizer)
synchronizer
- the new synchronizer for the display (must not be null)
IllegalArgumentException
- SWTException
- public boolean sleep()
true
if an event requiring dispatching was placed on the queue.
SWTException
- wake()
public void syncExec(Runnable runnable)
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.
runnable
- code to run on the user-interface thread.
SWTException
- asyncExec(java.lang.Runnable)
public void timerExec(int milliseconds, Runnable runnable)
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.
milliseconds
- the delay before running the runnablerunnable
- code to run on the user-interface thread
IllegalArgumentException
- SWTException
- asyncExec(java.lang.Runnable)
public void update()
Control.update()
public void wake()
sleep
'ing,
causes it to be awakened and start running again. Note that this
method may be called from any thread.
sleep()
|
Eclipse Platform 2.0 |
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |