diff options
Diffstat (limited to 'bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java')
| -rwxr-xr-x | bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java | 514 |
1 files changed, 311 insertions, 203 deletions
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java index 6aaaa08b44..d3c445d4f8 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java @@ -1,16 +1,10 @@ package org.eclipse.swt.widgets;
/*
-* Licensed Materials - Property of IBM,
-* SWT - The Simple Widget Toolkit,
-* (c) Copyright IBM Corp 1998, 1999.
-*/
-
-/**
-* See JavaDoc for Windows.
-*/
+ * (c) Copyright IBM Corp. 2000, 2001.
+ * All Rights Reserved
+ */
-/* Imports */
import org.eclipse.swt.internal.*;
import org.eclipse.swt.internal.motif.*;
import org.eclipse.swt.*;
@@ -18,7 +12,32 @@ import org.eclipse.swt.graphics.*; import org.eclipse.swt.events.*;
import java.util.EventListener;
-/* Class Definition */
+/** + * 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 {
public int handle;
@@ -73,42 +92,59 @@ public abstract class Widget { Widget () {
/* Do nothing */
}
-/**
-* Creates a widget.
-* <p>
-* This method creates a child widget using style bits
-* to select a particular look or set of properties.
-*
-* @param parent a composite widget (cannot be null)
-* @param style the bitwise OR'ing of widget styles
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_ERROR_NULL_ARGUMENT)
-* when the parent is null
-*/
+/** + * 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) {
if (parent == null) error (SWT.ERROR_NULL_ARGUMENT);
if (!parent.isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
this.style = style;
}
-/**
-* Adds a listener for an event.
-* <p>
-* This method adds a listener for an event. When the
-* event occurs in the widget, the listener is notified
-* using <code>handleEvent ()</code>.
-*
-* @param eventType the desired SWT event
-* @param handler the event handler
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-* @exception SWTError(ERROR_NULL_ARGUMENT)
-* when handler is null
-*/
+/** + * 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 handler) {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
if (!isValidWidget ()) error (SWT.ERROR_WIDGET_DISPOSED);
@@ -116,19 +152,25 @@ public void addListener (int eventType, Listener handler) { if (eventTable == null) eventTable = new EventTable ();
eventTable.hook (eventType, handler);
}
-/**
-* Adds the listener to receive events.
-* <p>
-*
-* @param listener the listener
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-* @exception SWTError(ERROR_NULL_ARGUMENT)
-* when listener is null
-*/
+/** + * 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) {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
if (!isValidWidget ()) error (SWT.ERROR_WIDGET_DISPOSED);
@@ -218,18 +260,29 @@ void destroyWidget () { OS.XtDestroyWidget (topHandle);
}
}
-/**
-* Disposes a widget.
-* <p>
-* This method destroys the widget and all children
-* and releases all platform resources associated with
-* the widget tree.
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-*/
+/** + * 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
@@ -244,37 +297,57 @@ public void dispose () { void error (int code) {
SWT.error(code);
}
-/**
-* Gets the widget data.
-* <p>
-* This method gets the application defined data that
-* is associated with the widget.
-*
-* @return the widget data
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-*/
+/** + * 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 () {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
if (!isValidWidget ()) error (SWT.ERROR_WIDGET_DISPOSED);
return data;
}
-/**
- * Searches for the property with the specified name.
- * If the property is not found, null is returned.
- *
- * @param key the name of the property to find
- * @return the named property value
- *
- * @exception SWTError <ul>
- * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
- * <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
- * <li>ERROR_NULL_ARGUMENT when the name is null</li>
- * </ul>
+/** + * 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) {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
@@ -287,19 +360,22 @@ public Object getData (String key) { return null;
}
-/**
-* Gets the Display.
-* <p>
-* This method gets the Display that is associated
-* with the widget.
-*
-* @return the widget data
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-*/
+/** + * 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 ();
String getName () {
String string = getClass ().getName ();
@@ -310,18 +386,26 @@ String getName () { String getNameText () {
return "";
}
-/**
-* Gets the widget style.
-* <p>
-* This method gets the widget style bits.
-*
-* @return an integer that is the widget style bits.
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-*/
+/** + * 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 () {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
if (!isValidWidget ()) error (SWT.ERROR_WIDGET_DISPOSED);
@@ -334,18 +418,17 @@ boolean hooks (int eventType) { if (eventTable == null) return false;
return eventTable.hooks (eventType);
}
-/**
-* Gets the disposed state.
-* <p>
-* This method gets the dispose state for the widget.
-* When a widget has been disposed, it is an error to
-* to invoke any other method on the widget.
-*
-* @return true when the widget is disposed
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-*/
+/** + * 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 () {
if (handle != 0) return false;
if ((state & HANDLE) != 0) return true;
@@ -401,22 +484,22 @@ char mbcsToWcs (char ch) { if (result.length == 0) return 0;
return result [0];
}
-/**
-* Notify listeners of an event.
-* <p>
-* This method notifies all listeners that an event
-* has occurred.
-*
-* @param eventType the desired SWT event
-* @param event the event data
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-* @exception SWTError(ERROR_NULL_ARGUMENT)
-* when handler is null
-*/
+/** + * 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) {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
if (!isValidWidget ()) error (SWT.ERROR_WIDGET_DISPOSED);
@@ -548,23 +631,24 @@ void releaseWidget () { keys = null;
values = null;
}
-/**
-* Removes a listener for an event.
-* <p>
-* This method removes a listener for an event. When the
-* event occurs in the widget, the listener is no longer
-* notified.
-*
-* @param eventType the desired SWT event
-* @param handler the event handler
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-* @exception SWTError(ERROR_NULL_ARGUMENT)
-* when handler is 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 handler) {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
if (!isValidWidget ()) error (SWT.ERROR_WIDGET_DISPOSED);
@@ -582,19 +666,23 @@ protected void removeListener (int eventType, EventListener handler) { if (eventTable == null) return;
eventTable.unhook (eventType, handler);
}
-/**
-* Removes the listener.
-* <p>
-*
-* @param listener the listener
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-* @exception SWTError(ERROR_NULL_ARGUMENT)
-* when listener is null
-*/
+/** + * 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) {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
if (!isValidWidget ()) error (SWT.ERROR_WIDGET_DISPOSED);
@@ -616,38 +704,55 @@ void sendEvent (int eventType, Event event) { }
eventTable.sendEvent (event);
}
-/**
-* Sets the widget data.
-* <p>
-* This method sets the application defined data that
-* is associated with the widget.
-*
-* @param the widget data
-*
-* @exception SWTError(ERROR_THREAD_INVALID_ACCESS)
-* when called from the wrong thread
-* @exception SWTError(ERROR_WIDGET_DISPOSED)
-* when the widget has been disposed
-*/
+/** + * 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) {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
if (!isValidWidget ()) error (SWT.ERROR_WIDGET_DISPOSED);
this.data = data;
}
-/**
- * Maps the specified key to the specified value.
- * If the key already exists, the old value is replaced.
- * The key cannot be null.
- *
- * @param key the name of the property
- * @param value the value of the property
- *
- * @exception SWTError <ul>
- * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li>
- * <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li>
- * <li>ERROR_NULL_ARGUMENT when the name is null</li>
- * </ul>
+/** + * 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) {
if (!isValidThread ()) error (SWT.ERROR_THREAD_INVALID_ACCESS);
@@ -698,9 +803,12 @@ public void setData (String key, Object value) { values = newValues;
}
-/**
-* Returns a string representation of the object.
-*/
+/** + * 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 ()) {
|