package org.eclipse.swt.widgets; | |
/* | |
* (c) Copyright IBM Corp. 2000, 2001. | |
* All Rights Reserved | |
*/ | |
import org.eclipse.swt.internal.*; | |
import org.eclipse.swt.internal.win32.*; | |
import org.eclipse.swt.*; | |
import org.eclipse.swt.graphics.*; | |
import org.eclipse.swt.events.*; | |
import java.util.EventListener; | |
/** | |
* This class is the abstract superclass of all user interface objects. | |
* Widgets are created, disposed and issue notification to listeners | |
* when events occur which affect them. | |
* <dl> | |
* <dt><b>Styles:</b></dt> | |
* <dd>(none)</dd> | |
* <dt><b>Events:</b></dt> | |
* <dd>Dispose</dd> | |
* </dl> | |
* <p> | |
* IMPORTANT: This class is intended to be subclassed <em>only</em> | |
* within the SWT implementation. However, it has not been marked | |
* final to allow those outside of the SWT development team to implement | |
* patched versions of the class in order to get around specific | |
* limitations in advance of when those limitations can be addressed | |
* by the team. Any class built using subclassing to access the internals | |
* of this class will likely fail to compile or run between releases and | |
* may be strongly platform specific. Subclassing should not be attempted | |
* without an intimate and detailed understanding of the workings of the | |
* hierarchy. No support is provided for user-written classes which are | |
* implemented as subclasses of this class. | |
* </p> | |
* | |
* @see #checkSubclass | |
*/ | |
public abstract class Widget { | |
int style, state; | |
EventTable eventTable; | |
Object data; | |
String [] keys; | |
Object [] values; | |
/* Global state flags */ | |
// static final int AUTOMATIC = 1<<0; | |
// static final int ACTIVE = 1<<1; | |
// static final int AUTOGRAB = 1<<2; | |
// static final int MULTIEXPOSE = 1<<3; | |
// static final int RESIZEREDRAW = 1<<4; | |
// static final int WRAP = 1<<5; | |
static final int DISABLED = 1<<6; | |
static final int HIDDEN = 1<<7; | |
// static final int FOREGROUND = 1<<8; | |
// static final int BACKGROUND = 1<<9; | |
static final int DISPOSED = 1<<10; | |
// static final int HANDLE = 1<<11; | |
static final int CANVAS = 1<<12; | |
/* Default widths for widgets */ | |
static final int DEFAULT_WIDTH = 64; | |
static final int DEFAULT_HEIGHT = 64; | |
static final char Mnemonic = '&'; | |
/* Windows, DBCS and COMCTL32.DLL flags */ | |
static final boolean IsWinNT, IsDBLocale; | |
static final int WIN32_MAJOR, WIN32_MINOR; | |
static final int COMCTL32_MAJOR, COMCTL32_MINOR; | |
static { | |
/* Get the Windows version */ | |
int version = OS.GetVersion (); | |
IsWinNT = (version & 0x80000000) == 0; | |
WIN32_MAJOR = version & 0x00FF; | |
WIN32_MINOR = (version & 0xFFFF) >> 8; | |
/* Get the DBCS flag */ | |
boolean isDBLocale = false; | |
for (int i = 0; i <= 0xFF; i++) { | |
if (OS.IsDBCSLeadByte ((byte) i)) { | |
isDBLocale = true; | |
break; | |
} | |
} | |
IsDBLocale = isDBLocale; | |
/* Get the COMCTL32.DLL version */ | |
DLLVERSIONINFO dvi = new DLLVERSIONINFO (); | |
dvi.cbSize = DLLVERSIONINFO.sizeof; | |
dvi.dwMajorVersion = 4; | |
dvi.dwMinorVersion = 0; | |
byte[] lpLibFileName = Converter.wcsToMbcs (0, "comctl32.dll\0"); | |
int hModule = OS.LoadLibrary (lpLibFileName); | |
if (hModule != 0) { | |
byte [] lpProcName = Converter.wcsToMbcs (0, "DllGetVersion\0"); | |
int DllGetVersion = OS.GetProcAddress (hModule, lpProcName); | |
if (DllGetVersion != 0) OS.Call (DllGetVersion, dvi); | |
OS.FreeLibrary (hModule); | |
} | |
COMCTL32_MAJOR = dvi.dwMajorVersion; | |
COMCTL32_MINOR = dvi.dwMinorVersion; | |
if ((COMCTL32_MAJOR << 16 | COMCTL32_MINOR) < (4 << 16 | 71)) { | |
System.out.println ("***WARNING: SWT requires comctl32.dll version 4.71 or greater"); | |
} | |
/* Initialize the Common Controls DLL */ | |
OS.InitCommonControls (); | |
} | |
/** | |
* Prevents uninitialized instances from being created outside the package. | |
*/ | |
Widget () { | |
} | |
/** | |
* Constructs a new instance of this class given its parent | |
* and a style value describing its behavior and appearance. | |
* <p> | |
* The style value is either one of the style constants defined in | |
* class <code>SWT</code> which is applicable to instances of this | |
* class, or must be built by <em>bitwise OR</em>'ing together | |
* (that is, using the <code>int</code> "|" operator) two or more | |
* of those <code>SWT</code> style constants. The class description | |
* for all SWT widget classes should include a comment which | |
* describes the style constants which are applicable to the class. | |
* </p> | |
* | |
* @param parent a widget which will be the parent of the new instance (cannot be null) | |
* @param style the style of widget to construct | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the parent is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> | |
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> | |
* </ul> | |
* | |
* @see SWT | |
* @see #checkSubclass | |
* @see #getStyle | |
*/ | |
public Widget (Widget parent, int style) { | |
checkSubclass (); | |
checkParent (parent); | |
this.style = style; | |
} | |
/** | |
* 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 widget, the listener is notified by | |
* sending it the <code>handleEvent()</code> message. | |
* | |
* @param eventType the type of event to listen for | |
* @param listener the listener which should be notified when the event occurs | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the listener is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
* | |
* @see Listener | |
* @see #removeListener | |
*/ | |
public void addListener (int eventType, Listener listener) { | |
checkWidget(); | |
if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); | |
if (eventTable == null) eventTable = new EventTable (); | |
eventTable.hook (eventType, listener); | |
} | |
/** | |
* Adds the listener to the collection of listeners who will | |
* be notifed when the widget is disposed. When the widget is | |
* disposed, the listener is notified by sending it the | |
* <code>widgetDisposed()</code> message. | |
* | |
* @param listener the listener which should be notified when the receiver is disposed | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the listener is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
* | |
* @see DisposeListener | |
* @see #removeDisposeListener | |
*/ | |
public void addDisposeListener (DisposeListener listener) { | |
checkWidget(); | |
if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); | |
TypedListener typedListener = new TypedListener (listener); | |
addListener (SWT.Dispose, typedListener); | |
} | |
/** | |
* Returns a style with exactly one style bit set out of | |
* the specified set of exclusive style bits. All other | |
* possible bits are cleared when the first matching bit | |
* is found. Bits that are not part of the possible set | |
* are untouched. | |
* | |
* @param style the original style bits | |
* @param int0 the 0th possible style bit | |
* @param int1 the 1st possible style bit | |
* @param int2 the 2nd possible style bit | |
* @param int3 the 3rd possible style bit | |
* @param int4 the 4th possible style bit | |
* @param int5 the 5th possible style bit | |
* | |
* @return the new style bits | |
*/ | |
static int checkBits (int style, int int0, int int1, int int2, int int3, int int4, int int5) { | |
int mask = int0 | int1 | int2 | int3 | int4 | int5; | |
if ((style & mask) == 0) style |= int0; | |
if ((style & int0) != 0) style = (style & ~mask) | int0; | |
if ((style & int1) != 0) style = (style & ~mask) | int1; | |
if ((style & int2) != 0) style = (style & ~mask) | int2; | |
if ((style & int3) != 0) style = (style & ~mask) | int3; | |
if ((style & int4) != 0) style = (style & ~mask) | int4; | |
if ((style & int5) != 0) style = (style & ~mask) | int5; | |
return style; | |
} | |
/** | |
* Throws an exception if the specified widget can not be | |
* used as a parent for the receiver. | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the parent is null</li> | |
* <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> | |
* </ul> | |
*/ | |
void checkParent (Widget parent) { | |
if (parent == null) error (SWT.ERROR_NULL_ARGUMENT); | |
if (!parent.isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS); | |
if (parent.isDisposed()) error (SWT.ERROR_INVALID_ARGUMENT); | |
} | |
/** | |
* Checks that this class can be subclassed. | |
* <p> | |
* The SWT class library is intended to be subclassed | |
* only at specific, controlled points (most notably, | |
* <code>Composite</code> and <code>Canvas</code> when | |
* implementing new widgets). This method enforces this | |
* rule unless it is overridden. | |
* </p><p> | |
* <em>IMPORTANT:</em> By providing an implementation of this | |
* method that allows a subclass of a class which does not | |
* normally allow subclassing to be created, the implementer | |
* agrees to be fully responsible for the fact that any such | |
* subclass will likely fail between SWT releases and will be | |
* strongly platform specific. No support is provided for | |
* user-written classes which are implemented in this fashion. | |
* </p><p> | |
* The ability to subclass outside of the allowed SWT classes, | |
* is intended purely to enable those not on the SWT development | |
* team to implement patches in order to get around specific | |
* limitations in advance of when those limitations can be | |
* addressed by the team. Subclassing should not be attempted | |
* without an intimate and detailed understanding of the hierarchy. | |
* </p> | |
* | |
* @exception SWTException <ul> | |
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> | |
* </ul> | |
*/ | |
protected void checkSubclass () { | |
if (!isValidSubclass ()) error (SWT.ERROR_INVALID_SUBCLASS); | |
} | |
/** | |
* Throws an <code>SWTException</code> 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 <em>should</em> be called by | |
* widget implementors to enforce the standard SWT invariants. | |
* <p> | |
* Currently, it is an error to invoke any method (other than | |
* <code>isDisposed()</code>) on a widget that has had its | |
* <code>dispose()</code> method called. It is also an error | |
* to call widget methods from any thread that is different | |
* from the thread that created the widget. | |
* </p><p> | |
* In future releases of SWT, there may be more or fewer error | |
* checks and exceptions may be thrown for different reasons. | |
* </p> | |
* | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
*/ | |
protected void checkWidget () { | |
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS); | |
if (isDisposed ()) error (SWT.ERROR_WIDGET_DISPOSED); | |
} | |
/** | |
* Destroys the widget in the operating system and releases | |
* the widget's handle. If the widget does not have a handle, | |
* this method may hide the widget, mark the widget as destroyed | |
* or do nothing, depending on the widget. | |
* <p> | |
* When a widget is destroyed in the operating system, its | |
* descendents are also destroyed by the operating system. | |
* This means that it is only necessary to call <code>destroyWidget</code> | |
* on the root of the widget tree. | |
* </p><p> | |
* This method is called after <code>releaseWidget</code>. | |
* </p> | |
* @see #dispose | |
* @see #releaseChild | |
* @see #releaseWidget | |
* @see #releaseHandle | |
*/ | |
void destroyWidget () { | |
} | |
/** | |
* Disposes of the operating system resources associated with | |
* the receiver and all its descendents. After this method has | |
* been invoked, the receiver and all descendents will answer | |
* <code>true</code> when sent the message <code>isDisposed()</code>. | |
* Any internal connections between the widgets in the tree will | |
* have been removed to facilitate garbage collection. | |
* <p> | |
* NOTE: This method is not called recursively on the descendents | |
* of the receiver. This means that, widget implementers can not | |
* detect when a widget is being disposed of by re-implementing | |
* this method, but should instead listen for the <code>Dispose</code> | |
* event. | |
* </p> | |
* | |
* @exception SWTException <ul> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
* | |
* @see #addDisposeListener | |
* @see #removeDisposeListener | |
* @see #checkWidget | |
*/ | |
public void dispose () { | |
/* | |
* Note: It is valid to attempt to dispose a widget | |
* more than once. If this happens, fail silently. | |
*/ | |
if (isDisposed ()) return; | |
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS); | |
releaseChild (); | |
releaseWidget (); | |
destroyWidget (); | |
} | |
/** | |
* Does whatever widget specific cleanup is required, and then | |
* uses the code in <code>SWTError.error</code> to handle the error. | |
* | |
* @param code the descriptive error code | |
* | |
* @see SWTError#error | |
*/ | |
void error (int code) { | |
SWT.error(code); | |
} | |
/** | |
* Returns the application defined widget data associated | |
* with the receiver, or null if it has not been set. The | |
* <em>widget data</em> is a single, unnamed field that is | |
* stored with every widget. | |
* <p> | |
* Applications may put arbitrary objects in this field. If | |
* the object stored in the widget data needs to be notified | |
* when the widget is disposed of, it is the application's | |
* responsibility to hook the Dispose event on the widget and | |
* do so. | |
* </p> | |
* | |
* @return the widget data | |
* | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li> | |
* </ul> | |
* | |
* @see #setData | |
*/ | |
public Object getData () { | |
checkWidget(); | |
return data; | |
} | |
/** | |
* Returns the application defined property of the receiver | |
* with the specified name, or null if it has not been set. | |
* <p> | |
* 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 widget is disposed | |
* of, it is the application's responsibility to hook the | |
* Dispose event on the widget and do so. | |
* </p> | |
* | |
* @param key the name of the property | |
* @return the value of the property or null if it has not been set | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the key is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
* | |
* @see #setData | |
*/ | |
public Object getData (String key) { | |
checkWidget(); | |
if (key == null) error (SWT.ERROR_NULL_ARGUMENT); | |
if (keys == null) return null; | |
for (int i=0; i<keys.length; i++) { | |
if (keys [i].equals (key)) return values [i]; | |
} | |
return null; | |
} | |
/** | |
* Returns the <code>Display</code> that is associated with | |
* the receiver. | |
* <p> | |
* A widget's display is either provided when it is created | |
* (for example, top level <code>Shell</code>s) or is the | |
* same as its parent's display. | |
* </p> | |
* | |
* @return the receiver's display | |
* | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
*/ | |
public abstract Display getDisplay (); | |
/** | |
* Returns the name of the widget. This is the name of | |
* the class without the package name. | |
* | |
* @return the name of the widget | |
*/ | |
String getName () { | |
String string = getClass ().getName (); | |
int index = string.lastIndexOf ('.'); | |
if (index == -1) return string; | |
return string.substring (index + 1, string.length ()); | |
} | |
/* | |
* Returns a short printable representation for the contents | |
* of a widget. For example, a button may answer the label | |
* text. This is used by <code>toString</code> to provide a | |
* more meaningful description of the widget. | |
* | |
* @return the contents string for the widget | |
* | |
* @see toString | |
*/ | |
String getNameText () { | |
return ""; | |
} | |
/** | |
* Returns the receiver's style information. | |
* <p> | |
* Note that the value which is returned by this method <em>may | |
* not match</em> the value which was provided to the constructor | |
* when the receiver was created. This can occur when the underlying | |
* operating system does not support a particular combination of | |
* requested styles. For example, if the platform widget used to | |
* implement a particular SWT widget always has scroll bars, the | |
* result of calling this method would always have the | |
* <code>SWT.H_SCROLL</code> and <code>SWT.V_SCROLL</code> bits set. | |
* </p> | |
* | |
* @return the style bits | |
* | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
*/ | |
public int getStyle () { | |
checkWidget(); | |
return style; | |
} | |
/* | |
* Returns <code>true</code> if the specified eventType is | |
* hooked, and <code>false</code> otherwise. Implementations | |
* of SWT can avoid creating objects and sending events | |
* when an event happens in the operating system but | |
* there are no listeners hooked for the event. | |
* | |
* @param eventType the event to be checked | |
* | |
* @return <code>true</code> when the eventType is hooked and <code>false</code> otherwise | |
* | |
* @see #isListening | |
*/ | |
boolean hooks (int eventType) { | |
if (eventTable == null) return false; | |
return eventTable.hooks (eventType); | |
} | |
/** | |
* Returns <code>true</code> if the widget has been disposed, | |
* and <code>false</code> otherwise. | |
* <p> | |
* This method gets the dispose state for the widget. | |
* When a widget has been disposed, it is an error to | |
* invoke any other method using the widget. | |
* </p> | |
* | |
* @return <code>true</code> when the widget is disposed and <code>false</code> otherwise | |
*/ | |
public boolean isDisposed () { | |
return (state & DISPOSED) != 0; | |
} | |
/** | |
* Returns <code>true</code> if there are any listeners | |
* for the specified event type associated with the receiver, | |
* and <code>false</code> otherwise. | |
* | |
* @param eventType the type of event | |
* @return true if the event is hooked | |
* | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
*/ | |
protected boolean isListening (int eventType) { | |
checkWidget(); | |
return hooks (eventType); | |
} | |
/* | |
* Returns <code>true</code> when subclassing is | |
* allowed and <code>false</code> otherwise | |
* | |
* @return <code>true</code> when subclassing is allowed and <code>false</code> otherwise | |
*/ | |
boolean isValidSubclass () { | |
return Display.isValidClass (getClass ()); | |
} | |
/* | |
* Returns <code>true</code> when the current thread is | |
* the thread that created the widget and <code>false</code> | |
* otherwise. | |
* | |
* @return <code>true</code> when the current thread is the thread that created the widget and <code>false</code> otherwise | |
*/ | |
boolean isValidThread () { | |
return getDisplay ().isValidThread (); | |
} | |
/* | |
* Returns a single character, converted from the default | |
* multi-byte character set (MBCS) used by the operating | |
* system widgets to a wide character set (WCS) used by Java. | |
* | |
* @param ch the MBCS character | |
* @return the WCS character | |
*/ | |
char mbcsToWcs (char ch) { | |
return mbcsToWcs (ch, 0); | |
} | |
/* | |
* Returns a single character, converted from the specified | |
* multi-byte character set (MBCS) used by the operating | |
* system widgets to a wide character set (WCS) used by Java. | |
* | |
* @param ch the MBCS character | |
* @param codePage the code page used to convert the character | |
* @return the WCS character | |
*/ | |
char mbcsToWcs (char ch, int codePage) { | |
int key = ch & 0xFFFF; | |
if (key <= 0x7F) return ch; | |
byte [] buffer; | |
if (key <= 0xFF) { | |
buffer = new byte [1]; | |
buffer [0] = (byte) key; | |
} else { | |
buffer = new byte [2]; | |
buffer [0] = (byte) ((key >> 8) & 0xFF); | |
buffer [1] = (byte) (key & 0xFF); | |
} | |
char [] result = Converter.mbcsToWcs (codePage, buffer); | |
if (result.length == 0) return 0; | |
return result [0]; | |
} | |
/** | |
* Notifies all of the receiver's listeners for events | |
* of the given type that one such event has occurred by | |
* invoking their <code>handleEvent()</code> method. | |
* | |
* @param eventType the type of event which has occurred | |
* @param event the event data | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the event is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
*/ | |
public void notifyListeners (int eventType, Event event) { | |
checkWidget(); | |
if (event == null) error (SWT.ERROR_NULL_ARGUMENT); | |
if (eventTable == null) return; | |
event.type = eventType; | |
event.widget = this; | |
eventTable.sendEvent (event); | |
} | |
void postEvent (int eventType) { | |
if (eventTable == null) return; | |
postEvent (eventType, new Event ()); | |
} | |
void postEvent (int eventType, Event event) { | |
if (eventTable == null) return; | |
event.type = eventType; | |
event.widget = this; | |
if (event.time == 0) { | |
event.time = OS.GetMessageTime (); | |
} | |
getDisplay ().postEvent (event); | |
} | |
/* | |
* Releases the receiver, a child in a widget hierarchy, | |
* from its parent. | |
* <p> | |
* When a widget is destroyed, it may be necessary to remove | |
* it from an internal data structure of the parent. When | |
* a widget has no handle, it may also be necessary for the | |
* parent to hide the widget or otherwise indicate that the | |
* widget has been disposed. For example, disposing a menu | |
* bar requires that the menu bar first be released from the | |
* shell when the menu bar is active. This could not be done | |
* in <code>destroyWidget</code> for the menu bar because the | |
* parent shell as well as other fields have been null'd out | |
* already by <code>releaseWidget</code>. | |
* </p> | |
* This method is called first when a widget is disposed. | |
* | |
* @see #dispose | |
* @see #releaseChild | |
* @see #releaseWidget | |
* @see #releaseHandle | |
*/ | |
void releaseChild () { | |
} | |
/* | |
* Releases the widget's handle by zero'ing it out. | |
* Does not destroy or release any operating system | |
* resources. | |
* <p> | |
* This method is called after <code>releaseWidget</code> | |
* or from <code>destroyWidget</code> when a widget is being | |
* destroyed to ensure that the widget is marked as destroyed | |
* in case the act of destroying the widget in the operating | |
* system causes application code to run in callback that | |
* could access the widget. | |
* </p> | |
* | |
* @see #dispose | |
* @see #releaseChild | |
* @see #releaseWidget | |
* @see #releaseHandle | |
*/ | |
void releaseHandle () { | |
} | |
/* | |
* Releases any internal resources back to the operating | |
* system and clears all fields except the widget handle. | |
* <p> | |
* When a widget is destroyed, resources that were acquired | |
* on behalf of the programmer need to be returned to the | |
* operating system. For example, if the widget made a | |
* copy of an icon, supplied by the programmer, this copy | |
* would be freed in <code>releaseWidget</code>. 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 widget, all fields except the | |
* handle are zero'd. The handle is needed by <code>destroyWidget</code>. | |
* </p> | |
* <p> | |
* Typically, a widget with children will broadcast this | |
* message to all children so that they too can release their | |
* resources. The <code>releaseHandle</code> method is used | |
* as part of this broadcast to zero the handle fields of the | |
* children without calling <code>destroyWidget</code>. In | |
* this scenario, the children are actually destroyed later, | |
* when the operating system destroys the widget tree. | |
* </p> | |
* This method is called after <code>releaseChild</code>. | |
* | |
* @see #dispose | |
* @see #releaseChild | |
* @see #releaseWidget | |
* @see #releaseHandle | |
*/ | |
void releaseWidget () { | |
sendEvent (SWT.Dispose); | |
state |= DISPOSED; | |
eventTable = null; | |
data = null; | |
keys = null; | |
values = null; | |
} | |
/** | |
* Removes the listener from the collection of listeners who will | |
* be notifed when an event of the given type occurs. | |
* | |
* @param eventType the type of event to listen for | |
* @param listener the listener which should no longer be notified when the event occurs | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the listener is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
* | |
* @see Listener | |
* @see #addListener | |
*/ | |
public void removeListener (int eventType, Listener listener) { | |
checkWidget(); | |
if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); | |
if (eventTable == null) return; | |
eventTable.unhook (eventType, listener); | |
} | |
/** | |
* Removes the listener from the collection of listeners who will | |
* be notifed when an event of the given type occurs. | |
* <p> | |
* <b>IMPORTANT:</b> This method is <em>not</em> part of the SWT | |
* public API. It is marked public only so that it can be shared | |
* within the packages provided by SWT. It should never be | |
* referenced from application code. | |
* </p> | |
* | |
* @param eventType the type of event to listen for | |
* @param listener the listener which should no longer be notified when the event occurs | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the listener is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
* | |
* @see Listener | |
* @see #addListener | |
*/ | |
protected void removeListener (int eventType, EventListener listener) { | |
checkWidget(); | |
if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); | |
if (eventTable == null) return; | |
eventTable.unhook (eventType, listener); | |
} | |
/** | |
* Removes the listener from the collection of listeners who will | |
* be notifed when the widget is disposed. | |
* | |
* @param listener the listener which should no longer be notified when the receiver is disposed | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the listener is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
* | |
* @see DisposeListener | |
* @see #removeDisposeListener | |
*/ | |
public void removeDisposeListener (DisposeListener listener) { | |
checkWidget(); | |
if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); | |
if (eventTable == null) return; | |
eventTable.unhook (SWT.Dispose, listener); | |
} | |
void sendEvent (int eventType) { | |
if (eventTable == null) return; | |
sendEvent (eventType, new Event ()); | |
} | |
void sendEvent (int eventType, Event event) { | |
if (eventTable == null) return; | |
event.widget = this; | |
event.type = eventType; | |
if (event.time == 0) { | |
event.time = OS.GetMessageTime (); | |
} | |
eventTable.sendEvent (event); | |
} | |
/** | |
* Sets the application defined widget data associated | |
* with the receiver to be the argument. The <em>widget | |
* data</em> is a single, unnamed field that is stored | |
* with every widget. | |
* <p> | |
* Applications may put arbitrary objects in this field. If | |
* the object stored in the widget data needs to be notified | |
* when the widget is disposed of, it is the application's | |
* responsibility to hook the Dispose event on the widget and | |
* do so. | |
* </p> | |
* | |
* @param data the widget data | |
* | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li> | |
* </ul> | |
*/ | |
public void setData (Object data) { | |
checkWidget(); | |
this.data = data; | |
} | |
/** | |
* Sets the application defined property of the receiver | |
* with the specified name to the given value. | |
* <p> | |
* Applications may associate arbitrary objects with the | |
* receiver in this fashion. If the objects stored in the | |
* properties need to be notified when the widget is disposed | |
* of, it is the application's responsibility to hook the | |
* Dispose event on the widget and do so. | |
* </p> | |
* | |
* @param key the name of the property | |
* @param value the new value for the property | |
* | |
* @exception IllegalArgumentException <ul> | |
* <li>ERROR_NULL_ARGUMENT - if the key is null</li> | |
* </ul> | |
* @exception SWTException <ul> | |
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> | |
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> | |
* </ul> | |
* | |
* @see #getData | |
*/ | |
public void setData (String key, Object value) { | |
checkWidget(); | |
if (key == null) error (SWT.ERROR_NULL_ARGUMENT); | |
/* Remove the key/value pair */ | |
if (value == null) { | |
if (keys == null) return; | |
int index = 0; | |
while (index < keys.length && !keys [index].equals (key)) index++; | |
if (index == keys.length) return; | |
if (keys.length == 1) { | |
keys = null; | |
values = null; | |
} else { | |
String [] newKeys = new String [keys.length - 1]; | |
Object [] newValues = new Object [values.length - 1]; | |
System.arraycopy (keys, 0, newKeys, 0, index); | |
System.arraycopy (keys, index + 1, newKeys, index, newKeys.length - index); | |
System.arraycopy (values, 0, newValues, 0, index); | |
System.arraycopy (values, index + 1, newValues, index, newValues.length - index); | |
keys = newKeys; | |
values = newValues; | |
} | |
return; | |
} | |
/* Add the key/value pair */ | |
if (keys == null) { | |
keys = new String [] {key}; | |
values = new Object [] {value}; | |
return; | |
} | |
for (int i=0; i<keys.length; i++) { | |
if (keys [i].equals (key)) { | |
values [i] = value; | |
return; | |
} | |
} | |
String [] newKeys = new String [keys.length + 1]; | |
Object [] newValues = new Object [values.length + 1]; | |
System.arraycopy (keys, 0, newKeys, 0, keys.length); | |
System.arraycopy (values, 0, newValues, 0, values.length); | |
newKeys [keys.length] = key; | |
newValues [values.length] = value; | |
keys = newKeys; | |
values = newValues; | |
} | |
/** | |
* Returns a string containing a concise, human-readable | |
* description of the receiver. | |
* | |
* @return a string representation of the receiver | |
*/ | |
public String toString () { | |
String string = "*Disposed*"; | |
if (!isDisposed ()) { | |
string = "*Wrong Thread*"; | |
if (isValidThread ()) string = getNameText (); | |
} | |
return getName () + " {" + string + "}"; | |
} | |
/* | |
* Returns a single character, converted from the wide | |
* character set (WCS) used by Java to the default | |
* multi-byte character set used by the operating system | |
* widgets. | |
* | |
* @param ch the WCS character | |
* @return the MBCS character | |
*/ | |
char wcsToMbcs (char ch) { | |
return wcsToMbcs (ch, 0); | |
} | |
/* | |
* Returns a single character, converted from the wide | |
* character set (WCS) used by Java to the specified | |
* multi-byte character set used by the operating system | |
* widgets. | |
* | |
* @param ch the WCS character | |
* @param codePage the code page used to convert the character | |
* @return the MBCS character | |
*/ | |
char wcsToMbcs (char ch, int codePage) { | |
int key = ch & 0xFFFF; | |
if (key <= 0x7F) return ch; | |
byte [] buffer = Converter.wcsToMbcs (codePage, new char [] {ch}, false); | |
if (buffer.length == 1) return (char) buffer [0]; | |
if (buffer.length == 2) { | |
return (char) (((buffer [0] & 0xFF) << 8) | (buffer [1] & 0xFF)); | |
} | |
return 0; | |
} | |
} |