diff options
43 files changed, 1873 insertions, 315 deletions
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java index bfa7775d52..2048aec66a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java @@ -501,7 +501,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java index c790d7d6a9..274bf45164 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java @@ -48,8 +48,7 @@ import org.eclipse.swt.internal.carbon.Rect; * <dd>DefaultSelection, Modify, Selection</dd> * </dl> * <p> - * Note: Only one of the styles DROP_DOWN and SIMPLE - * may be specified. + * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> @@ -123,9 +122,6 @@ public Combo (Composite parent, int style) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String,int) */ @@ -166,9 +162,6 @@ public void add (String string) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String) */ @@ -267,6 +260,8 @@ public void addSelectionListener(SelectionListener listener) { * * @see VerifyListener * @see #removeVerifyListener + * + * @since 3.1 */ public void addVerifyListener (VerifyListener listener) { checkWidget(); @@ -581,9 +576,6 @@ public void deselectAll () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String getItem (int index) { checkWidget (); @@ -615,9 +607,6 @@ public String getItem (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget (); @@ -638,9 +627,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemHeight () { checkWidget (); @@ -663,9 +649,6 @@ public int getItemHeight () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String [] getItems () { checkWidget (); @@ -787,9 +770,6 @@ char [] getText (int start, int end) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getTextHeight () { checkWidget(); @@ -818,6 +798,10 @@ public int getTextLimit () { /** * Gets the number of items that are visible in the drop * down portion of the receiver's list. + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @return the number of items that are visible * @@ -1065,9 +1049,6 @@ void releaseWidget () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget (); @@ -1099,9 +1080,6 @@ public void remove (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -1139,9 +1117,6 @@ public void remove (int start, int end) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (String string) { checkWidget (); @@ -1152,7 +1127,8 @@ public void remove (String string) { } /** - * Removes all of the items from the receiver's list. + * Removes all of the items from the receiver's list and clear the + * contents of receiver's text field. * <p> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1227,7 +1203,7 @@ public void removeSelectionListener (SelectionListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is verified. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1239,6 +1215,8 @@ public void removeSelectionListener (SelectionListener listener) { * * @see VerifyListener * @see #addVerifyListener + * + * @since 3.1 */ public void removeVerifyListener (VerifyListener listener) { checkWidget(); @@ -1343,10 +1321,6 @@ boolean sendKeyEvent (int type, Event event) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li> - * <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li> - * </ul> */ public void setItem (int index, String string) { checkWidget (); @@ -1381,9 +1355,6 @@ public void setItem (int index, String string) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItems (String [] items) { checkWidget(); @@ -1529,6 +1500,10 @@ public void setTextLimit (int limit) { /** * Sets the number of items that are visible in the drop * down portion of the receiver's list. + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @param count the new number of items to be visible * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java index 425305ef06..61ff932456 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java @@ -297,6 +297,7 @@ void fixTabList (Control control) { /** * Returns an array containing the receiver's children. + * Children are returned in the order that they are drawn. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of children, so modifying the array will @@ -304,6 +305,9 @@ void fixTabList (Control control) { * </p> * * @return an array of children + * + * @see Control#moveAbove + * @see Control#moveBelow * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -798,7 +802,7 @@ public void setLayout (Layout layout) { * </ul> * * @see #layout(boolean) - * @see #layout(Control) + * @see #layout(Control[]) * * @since 3.1 */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java index 606a777fed..4ba05b8bb5 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java @@ -1195,9 +1195,10 @@ void invalWindowRgn (int window, int rgn) { /** * Returns <code>true</code> if the receiver is enabled and all - * of the receiver's ancestors are enabled, and <code>false</code> - * otherwise. A disabled control is typically not selectable from the - * user interface and draws with an inactive or "grayed" look. + * ancestors up to and including the receiver's nearest ancestor + * shell are enabled. Otherwise, <code>false</code> is returned. + * A disabled control is typically not selectable from the user + * interface and draws with an inactive or "grayed" look. * * @return the receiver's enabled state * @@ -1324,8 +1325,8 @@ boolean isTabItem () { /** * Returns <code>true</code> if the receiver is visible and all - * of the receiver's ancestors are visible and <code>false</code> - * otherwise. + * ancestors up to and including the receiver's nearest ancestor + * shell are visible. Otherwise, <code>false</code> is returned. * * @return the receiver's visibility state * @@ -1517,7 +1518,8 @@ void markLayout (boolean changed, boolean all) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #moveBelow + * @see Control#moveBelow + * @see Composite#getChildren */ public void moveAbove (Control control) { checkWidget(); @@ -1545,7 +1547,8 @@ public void moveAbove (Control control) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #moveAbove + * @see Control#moveAbove + * @see Composite#getChildren */ public void moveBelow (Control control) { checkWidget(); @@ -1687,7 +1690,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1712,7 +1715,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control gains or loses focus. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1737,7 +1740,7 @@ public void removeFocusListener(FocusListener listener) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1761,7 +1764,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when keys are pressed and released on the system keyboard. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1786,7 +1789,7 @@ public void removeKeyListener(KeyListener listener) { * Removes the listener from the collection of listeners who will * be notified when mouse buttons are pressed and released. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1812,7 +1815,7 @@ public void removeMouseListener(MouseListener listener) { * Removes the listener from the collection of listeners who will * be notified when the mouse moves. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1836,7 +1839,7 @@ public void removeMouseMoveListener(MouseMoveListener listener) { * Removes the listener from the collection of listeners who will * be notified when the mouse passes or hovers over controls. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1862,7 +1865,7 @@ public void removeMouseTrackListener(MouseTrackListener listener) { * Removes the listener from the collection of listeners who will * be notified when the receiver needs to be painted. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1886,7 +1889,7 @@ public void removePaintListener(PaintListener listener) { * Removes the listener from the collection of listeners who will * be notified when traversal events occur. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -2430,9 +2433,9 @@ public void setMenu (Menu menu) { * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> - * @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> + * @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 boolean setParent (Composite parent) { @@ -2447,7 +2450,8 @@ public boolean setParent (Composite parent) { * can occur in the receiver until the flag is set to true. * Graphics operations that occurred while the flag was * <code>false</code> are lost. When the flag is set to <code>true</code>, - * the entire widget is marked as needing to be redrawn. + * the entire widget is marked as needing to be redrawn. Nested calls + * to this method are stacked. * <p> * Note: This operation is a hint and may not be supported on some * platforms or for some widgets. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java index 9de0d89a98..2b8fa092e2 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java @@ -473,7 +473,7 @@ public void setImage (Image image) { * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the array of images is null</li> - * <li>ERROR_INVALID_ARGUMENT - if one of the images has been disposed</li> + * <li>ERROR_INVALID_ARGUMENT - if one of the images is null or has been disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java index bc557f2bb5..4662796306 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java @@ -346,9 +346,19 @@ int appleEventProc (int nextHandler, int theEvent, int userData) { /** * Adds the listener to the collection of listeners who will * be notifed when an event of the given type occurs anywhere - * in this display. When the event does occur, the listener is + * in a widget. When the event does occur, the listener is * notified by sending it the <code>handleEvent()</code> message. - * + * <p> + * Setting the type of an event to <code>SWT.None</code> from + * within the <code>handleEvent()</code> 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. + * </p> + * * @param eventType the type of event to listen for * @param listener the listener which should be notified when the event occurs * @@ -937,6 +947,10 @@ boolean filters (int eventType) { * the instance of the <code>Widget</code> subclass which * represents it in the currently running application, if * such exists, or null if no matching widget can be found. + * <p> + * <b>IMPORTANT:</b> This method should not be called from + * application code. The arguments are platform-specific. + * </p> * * @param handle the handle for the widget * @return the SWT widget that the handle represents @@ -951,6 +965,28 @@ public Widget findWidget (int handle) { return getWidget (handle); } +/** + * Given the operating system handle for a widget, + * and widget-specific id, returns the instance of + * the <code>Widget</code> subclass which represents + * the handle/id pair in the currently running application, + * if such exists, or null if no matching widget can be found. + * <p> + * <b>IMPORTANT:</b> This method should not be called from + * application code. The arguments are platform-specific. + * </p> + * + * @param handle the handle for the widget + * @param id the id for the subwidget (usually an item) + * @return the SWT widget that the handle/id pair represents + * + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public Widget findWidget (int handle, int id) { return null; } @@ -1182,8 +1218,8 @@ public static synchronized Display getDefault () { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #setData(String, Object) + * @see #disposeExec(Runnable) */ public Object getData (String key) { checkDevice (); @@ -1215,8 +1251,8 @@ public Object getData (String key) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #setData(Object) + * @see #disposeExec(Runnable) */ public Object getData () { checkDevice (); @@ -1710,9 +1746,10 @@ public Image getSystemImage (int id) { } /** - * Returns the single instance of the system tray. + * Returns the single instance of the system tray or null + * when there is no system tray available for the platform. * - * @return the receiver's user-interface thread + * @return the system tray or <code>null</code> * * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> @@ -1932,12 +1969,12 @@ void initializeWidgetTable () { * @param data the platform specific GC data * @return the platform specific GC handle * - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li> + * </ul> */ public int internal_new_GC (GCData data) { if (isDisposed()) SWT.error(SWT.ERROR_DEVICE_DISPOSED); @@ -2045,7 +2082,12 @@ int keyboardProc (int nextHandler, int theEvent, int userData) { * and mouse events. The intent is to enable automated UI * testing by simulating the input from the user. Most * SWT applications should never need to call this method. - * + * <p> + * Note that this operation can fail when the operating system + * fails to generate the event for any reason. For example, + * this can happen when there is no such key or mouse button + * or when the system event queue is full. + * </p> * <p> * <b>Event Types:</b> * <p>KeyDown, KeyUp @@ -2223,7 +2265,7 @@ void postEvent (Event event) { * @return point with mapped coordinates * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> * <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> * </ul> * @exception SWTException <ul> @@ -2521,6 +2563,7 @@ int mouseHoverProc (int id, int handle) { * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li> * </ul> * * @see #sleep @@ -2697,7 +2740,7 @@ void releaseDisplay () { /** * Removes the listener from the collection of listeners who will * be notifed when an event of the given type occurs anywhere in - * this display. + * a widget. * * @param eventType the type of event to listen for * @param listener the listener which should no longer be notified when the event occurs @@ -3164,8 +3207,8 @@ public void setCursorLocation (Point point) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #getData(String) + * @see #disposeExec(Runnable) */ public void setData (String key, Object value) { checkDevice (); @@ -3235,8 +3278,8 @@ public void setData (String key, Object value) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #getData - * @see #disposeExec + * @see #getData() + * @see #disposeExec(Runnable) */ public void setData (Object data) { checkDevice (); @@ -3255,6 +3298,7 @@ public void setData (Object data) { * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li> * </ul> */ public void setSynchronizer (Synchronizer synchronizer) { @@ -3442,7 +3486,7 @@ int trackingProc (int browser, int itemID, int property, int theRect, int startP * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see Control#update + * @see Control#update() */ public void update () { checkDevice (); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java index 06fe924f30..172077663d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java @@ -18,6 +18,20 @@ import org.eclipse.swt.events.*; import org.eclipse.swt.graphics.*; /** + * Instances of this class represent a selectable + * user interface object that displays a text with + * links. + * <p> + * <dl> + * <dt><b>Styles:</b></dt> + * <dt><b>Events:</b></dt> + * <dd>Selection</dd> + * </dl> + * <p> + * IMPORTANT: This class is <em>not</em> intended to be subclassed. + * </p> + * + * @since 3.1 */ public class Link extends Control { String text; @@ -621,6 +635,15 @@ void setFontStyle (Font font) { /** * Sets the receiver's text. * <p> + * The string can contain both regular text and hyperlinks. A hyperlink + * is delimited by an anchor tag, <A> and </A>. Within an + * anchor, a single HREF attribute is supported. When a hyperlink is + * selected, the text field of the selection event contains either the + * text of hyperlink or the value of the HREF, if one was specified. + * In the rare case of identical hyperlinks within the same string, the + * HREF tag can be used to distinguish between them. The string may + * include the mnemonic character and line delimiters. + * </p> * * @param string the new text * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java index 2d9ba4ba2a..bf49d18db7 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java @@ -89,9 +89,6 @@ public List (Composite parent, int style) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String,int) */ @@ -130,9 +127,6 @@ public void add (String string) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String) */ @@ -456,9 +450,6 @@ public int getFocusIndex () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String getItem (int index) { checkWidget(); @@ -475,9 +466,6 @@ public String getItem (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget(); @@ -494,9 +482,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemHeight () { checkWidget (); @@ -522,10 +507,6 @@ public int getItemHeight () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li> - * </ul> */ public String [] getItems () { checkWidget(); @@ -549,10 +530,6 @@ public String [] getItems () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure while getting the selection</li> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * </ul> */ public String [] getSelection () { checkWidget (); @@ -584,9 +561,6 @@ public String [] getSelection () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getSelectionCount () { checkWidget (); @@ -607,9 +581,6 @@ public int getSelectionCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li> - * </ul> */ public int getSelectionIndex () { checkWidget(); @@ -632,9 +603,6 @@ public int getSelectionIndex () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li> - * </ul> */ public int [] getSelectionIndices () { checkWidget (); @@ -847,10 +815,6 @@ public int indexOf (String item) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * </ul> */ public int indexOf (String string, int start) { checkWidget(); @@ -893,9 +857,6 @@ public boolean isSelected (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -924,9 +885,6 @@ public void remove (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -953,9 +911,6 @@ public void remove (int start, int end) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (String string) { checkWidget(); @@ -979,9 +934,6 @@ public void remove (String string) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int [] indices) { checkWidget (); @@ -1233,10 +1185,6 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li> - * <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li> - * </ul> */ public void setItem (int index, String string) { checkWidget(); @@ -1260,9 +1208,6 @@ public void setItem (int index, String string) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItems (String [] items) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java index 587ae809bb..dc6f609f48 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java @@ -41,6 +41,13 @@ import org.eclipse.swt.graphics.*; public class Menu extends Widget { /** * the handle to the OS resource + * (Warning: This field is platform dependent) + * <p> + * <b>IMPORTANT:</b> This field 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 is not available on all + * platforms and should never be accessed from application code. + * </p> */ int handle; short id; @@ -791,7 +798,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -815,7 +822,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when the menu events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java index 5791c81904..5cedc53331 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java @@ -456,7 +456,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the arm events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -480,7 +480,7 @@ public void removeArmListener (ArmListener listener) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -504,7 +504,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Sash.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Sash.java index f6a1ef180c..44b9eeeddc 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Sash.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Sash.java @@ -24,7 +24,7 @@ import org.eclipse.swt.events.*; * the parent control. * <dl> * <dt><b>Styles:</b></dt> - * <dd>HORIZONTAL, VERTICAL</dd> + * <dd>HORIZONTAL, VERTICAL, SMOOTH</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -315,7 +315,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java index 50e261b968..2b0be7a89d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java @@ -204,7 +204,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the <em>selection</em>, which is the receiver's position. * * @return the selection * @@ -350,8 +350,8 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal + * Sets the <em>selection</em>, which is the receiver's + * value, to the argument which must be greater than or equal * to zero. * * @param value the new selection (must be zero or greater) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java index 4720a5c496..f1e5bcf58b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java @@ -106,7 +106,6 @@ ScrollBar (Scrollable parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java index 48d4a7734d..62b9a9fc73 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java @@ -648,6 +648,21 @@ public boolean getMinimized () { return OS.IsWindowCollapsed (shellHandle); } +/** + * Returns a point describing the minimum receiver's size. The + * x coordinate of the result is the minimum width of the receiver. + * The y coordinate of the result is the minimum height of the + * receiver. + * + * @return the receiver's size + * + * @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> + * + * @since 3.1 + */ public Point getMinimumSize () { checkWidget(); Rect rect = new Rect (); @@ -1140,8 +1155,8 @@ public void removeShellListener(ShellListener listener) { * If the receiver is visible, moves it to the top of the * drawing order for the display on which it was created * (so that all other shells on that display, which are not - * the receiver's children will be drawn behind it) and forces - * the window manager to make the shell active. + * the receiver's children will be drawn behind it) and asks + * the window manager to make the shell active * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1286,6 +1301,21 @@ public void setMinimized (boolean minimized) { OS.CollapseWindow (shellHandle, minimized); } +/** + * Sets the receiver's minimum size to the point specified by the arguments. + * If the new minimum size is larger than the current size of the receiver, + * the receiver is resized to the new minimum size. + * + * @param width the new minimum width for the receiver + * @param height the new minimum height for the receiver + * + * @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> + * + * @since 3.1 + */ public void setMinimumSize (int width, int height) { checkWidget(); int clientWidth = 0, clientHeight = 0; @@ -1308,6 +1338,23 @@ public void setMinimumSize (int width, int height) { if (newWidth != size.x || newHeight != size.y) setSize (newWidth, newHeight); } +/** + * Sets the receiver's minimum size to the point specified by the argument. + * If the new minimum size is larger than the current size of the receiver, + * the receiver is resized to the new minimum size. + * + * @param size the new minimum size for the receiver + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the point 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> + * + * @since 3.1 + */ public void setMinimumSize (Point size) { checkWidget(); if (size == null) error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java index f99d226a27..30825a433e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java @@ -279,7 +279,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's value. + * Returns the <em>selection</em>, which is the receiver's value. * * @return the selection * @@ -475,8 +475,8 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal + * Sets the <em>selection</em>, which is the receiver's + * value, to the argument which must be greater than or equal * to zero. * * @param value the new selection (must be zero or greater) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java index 4a9405630b..180f7a90c2 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java @@ -23,7 +23,8 @@ import org.eclipse.swt.graphics.*; /** * Instances of this class are selectable user interface - * objects that allow the user to enter and modify number + * objects that allow the user to enter and modify numeric + * values. * <p> * <dl> * <dt><b>Styles:</b></dt> @@ -34,6 +35,8 @@ import org.eclipse.swt.graphics.*; * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @since 3.1 */ public class Spinner extends Composite { int textHandle, buttonHandle; @@ -388,9 +391,8 @@ public int getMinimum () { } /** - * Returns the amount that the receiver's value will be - * modified by when the page increment/decrement areas - * are selected. + * Returns the amount that the receiver's position will be + * modified by when the page up/down keys are pressed. * * @return the page increment * @@ -405,7 +407,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the <em>selection</em>, which is the receiver's position. * * @return the selection * @@ -592,7 +594,7 @@ public void removeModifyListener (ModifyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -758,11 +760,10 @@ void setForeground (float [] color) { /** * Sets the amount that the receiver's value will be - * modified by when the up/down (or right/left) arrows - * are pressed to the argument, which must be at least - * one. + * modified by when the up/down arrows are pressed to + * the argument, which must be at least one. * - * @param increment the new increment (must be greater than zero) + * @param value the new increment (must be greater than zero) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -822,12 +823,11 @@ public void setMinimum (int value) { } /** - * Sets the amount that the receiver's value will be - * modified by when the page increment/decrement areas - * are selected to the argument, which must be at least - * one. + * Sets the amount that the receiver's position will be + * modified by when the page up/down keys are pressed + * to the argument, which must be at least one. * - * @param pageIncrement the page increment (must be greater than zero) + * @param value the page increment (must be greater than zero) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -841,9 +841,10 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal - * to zero. + * Sets the <em>selection</em>, which is the receiver's + * position, to the argument. If the argument is not within + * the range specified by minimum and maximum, it will be + * adjusted to fall within this range. * * @param value the new selection (must be zero or greater) * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java index ecae898ee6..eb45923ca4 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java @@ -529,6 +529,9 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize * * @param items the array of items * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the items array 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> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java index 3690b9fa2d..010290daf4 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java @@ -25,7 +25,7 @@ import org.eclipse.swt.graphics.*; /** * Instances of this class implement a selectable user interface * object that displays a list of images and strings and issue - * notificiation when selected. + * notification when selected. * <p> * The item children that may be added to instances of this class * must be of type <code>TableItem</code>. @@ -232,7 +232,7 @@ protected void checkSubclass () { /** * Clears the item at the given zero-relative index in the receiver. - * The text, icon and other attribues of the item are set to the default + * The text, icon and other attributes of the item are set to the default * value. If the table was created with the SWT.VIRTUAL style, these * attributes are requested again as needed. * @@ -287,7 +287,7 @@ public void clear (int index) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -324,7 +324,7 @@ public void clear (int start, int end) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -354,7 +354,7 @@ public void clear (int [] indices) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -962,7 +962,7 @@ public TableColumn getColumn (int index) { * Returns the number of columns contained in the receiver. * If no <code>TableColumn</code>s were created by the programmer, * this value is zero, despite the fact that visually, one column - * of items is may be visible. This occurs when the programmer uses + * of items may be visible. This occurs when the programmer uses * the table like a list, adding items but never creating a column. * * @return the number of columns @@ -971,9 +971,6 @@ public TableColumn getColumn (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getColumnCount () { checkWidget (); @@ -1001,6 +998,11 @@ public int getColumnCount () { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move + * * @since 3.1 */ public int [] getColumnOrder () { @@ -1691,9 +1693,6 @@ void releaseWidget () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -1726,9 +1725,6 @@ public void remove (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -1758,9 +1754,6 @@ public void remove (int start, int end) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int [] indices) { checkWidget (); @@ -2027,7 +2020,12 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize * <li>ERROR_NULL_ARGUMENT - if the item order is null</li> * <li>ERROR_INVALID_ARGUMENT - if the item order is not the same length as the number of items</li> * </ul> - * + * + * @see Table#getColumnOrder() + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move + * * @since 3.1 */ public void setColumnOrder (int [] order) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java index d47171bd4c..0ab22a5789 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java @@ -237,6 +237,8 @@ public Table getParent () { * * @see Table#getColumnOrder() * @see Table#setColumnOrder(int[]) + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move * * @since 3.1 */ @@ -323,7 +325,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -348,7 +350,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -433,6 +435,8 @@ public void setImage (Image image) { * * @see Table#setColumnOrder(int[]) * @see Table#getColumnOrder() + * @see TableColumn#getMoveable() + * @see SWT#Move * * @since 3.1 */ @@ -450,8 +454,10 @@ public void setMoveable (boolean moveable) { /** * Sets the resizable attribute. A column that is - * not resizable cannot be dragged by the user but - * may be resized by the programmer. + * resizable can be resized by the user dragging the + * edge of the header. A column that is not resizable + * cannot be dragged by the user but may be resized + * by the programmer. * * @param resizable the resize attribute * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java index 780836230c..debc88c635 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java @@ -466,9 +466,6 @@ public String getText () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_TEXT - if the column at index does not exist</li> - * </ul> */ public String getText (int index) { checkWidget(); @@ -738,7 +735,7 @@ public void setGrayed (boolean grayed) { } /** - * Sets the image for multiple columns in the Table. + * Sets the image for multiple columns in the table. * * @param images the array of new images * @@ -817,6 +814,8 @@ public void setImage (Image image) { * <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> + * + * @deprecated this functionality is not supported on most platforms */ public void setImageIndent (int indent) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java index 512714d3fe..b5c832a6da 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java @@ -1076,7 +1076,7 @@ public void removeModifyListener (ModifyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1101,7 +1101,7 @@ public void removeSelectionListener(SelectionListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is verified. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java index 10391d7011..91c630fe66 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java @@ -704,7 +704,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1002,7 +1002,7 @@ public void setToolTipText (String string) { } /** - * Sets the width of the receiver. + * Sets the width of the receiver, for <code>SEPARATOR</code> ToolItems. * * @param width the new width * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java index b9256263b2..e409bfca15 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java @@ -802,7 +802,7 @@ public boolean open () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -827,7 +827,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when keys are pressed and released on the system keyboard. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java index 9631524893..17a55f2400 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java @@ -36,7 +36,7 @@ import org.eclipse.swt.graphics.*; * </p><p> * <dl> * <dt><b>Styles:</b></dt> - * <dd>SINGLE, MULTI, CHECK</dd> + * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION</dd> * <dt><b>Events:</b></dt> * <dd>Selection, DefaultSelection, Collapse, Expand</dd> * </dl> @@ -751,8 +751,8 @@ public Rectangle getClientArea () { * receiver. Throws an exception if the index is out of range. * If no <code>TreeColumn</code>s were created by the programmer, * this method will throw <code>ERROR_INVALID_RANGE</code> despite - * the fact that a single column of data may be visible in the table. - * This occurs when the programmer uses the table like a list, adding + * the fact that a single column of data may be visible in the tree. + * This occurs when the programmer uses the tree like a list, adding * items but never creating a column. * * @param index the index of the column to return @@ -765,6 +765,8 @@ public Rectangle getClientArea () { * <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> + * + * @since 3.1 */ public TreeColumn getColumn (int index) { checkWidget (); @@ -776,8 +778,8 @@ public TreeColumn getColumn (int index) { * Returns the number of columns contained in the receiver. * If no <code>TreeColumn</code>s were created by the programmer, * this value is zero, despite the fact that visually, one column - * of items is may be visible. This occurs when the programmer uses - * the table like a list, adding items but never creating a column. + * of items may be visible. This occurs when the programmer uses + * the tree like a list, adding items but never creating a column. * * @return the number of columns * @@ -785,9 +787,8 @@ public TreeColumn getColumn (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> + * + * @since 3.1 */ public int getColumnCount () { checkWidget (); @@ -799,7 +800,7 @@ public int getColumnCount () { * columns in the receiver. If no <code>TreeColumn</code>s were * created by the programmer, the array is empty, despite the fact * that visually, one column of items may be visible. This occurs - * when the programmer uses the table like a list, adding items but + * when the programmer uses the tree like a list, adding items but * never creating a column. * <p> * Note: This is not the actual structure used by the receiver @@ -813,6 +814,8 @@ public int getColumnCount () { * <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> + * + * @since 3.1 */ public TreeColumn [] getColumns () { checkWidget (); @@ -830,6 +833,8 @@ public TreeColumn [] getColumns () { * <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> + * + * @since 3.1 */ public int getGridLineWidth () { checkWidget (); @@ -846,7 +851,7 @@ public int getGridLineWidth () { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @since 3.1 + * @since 3.1 */ public int getHeaderHeight () { checkWidget (); @@ -871,6 +876,8 @@ public int getHeaderHeight () { * <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> + * + * @since 3.1 */ public boolean getHeaderVisible () { checkWidget (); @@ -1019,6 +1026,8 @@ TreeItem [] getItems (TreeItem item) { * <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> + * + * @since 3.1 */ public boolean getLinesVisible () { checkWidget (); @@ -1668,6 +1677,7 @@ void setFontStyle (Font font) { * <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> + * * @since 3.1 */ public void setHeaderVisible (boolean show) { @@ -1703,6 +1713,8 @@ void setItemHeight (Image image) { * <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> + * + * @since 3.1 */ public void setLinesVisible (boolean show) { checkWidget (); @@ -1863,7 +1875,7 @@ public void setTopItem (TreeItem item) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @since 3.0 + * @since 3.1 */ public void showColumn (TreeColumn column) { checkWidget (); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeColumn.java index 07fd32aac5..cd8cb625fd 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeColumn.java @@ -19,7 +19,7 @@ import org.eclipse.swt.graphics.*; import org.eclipse.swt.events.*; /** - * Instances of this class represent a column in a table widget. + * Instances of this class represent a column in a tree widget. * <dl> * <dt><b>Styles:</b></dt> * <dd>LEFT, RIGHT, CENTER</dd> @@ -31,6 +31,8 @@ import org.eclipse.swt.events.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @since 3.1 */ public class TreeColumn extends Item { Tree parent; @@ -304,7 +306,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -329,7 +331,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java index 684be1ffa3..f2f6e81ae2 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java @@ -298,7 +298,7 @@ public Rectangle getBounds () { /** * Returns a rectangle describing the receiver's size and location - * relative to its parent at a column in the table. + * relative to its parent at a column in the tree. * * @param index the index that specifies the column * @return the receiver's bounding column rectangle @@ -307,6 +307,7 @@ public Rectangle getBounds () { * <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> + * * @since 3.1 */ public Rectangle getBounds (int index) { @@ -514,6 +515,8 @@ public Image getImage (int index) { * <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> + * + * @since 3.1 */ public Rectangle getImageBounds (int index) { checkWidget(); @@ -629,10 +632,7 @@ public String getText () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_TEXT - if the column at index does not exist</li> - * </ul> - * + * * @since 3.1 */ public String getText (int index) { @@ -681,7 +681,7 @@ void releaseWidget () { * if the argument is null. * * @param color the new color (or null) - * + * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> @@ -850,6 +850,8 @@ public void setFont (int index, Font font) { * * @param color the new color (or null) * + * @since 2.0 + * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> @@ -927,7 +929,7 @@ public void setGrayed (boolean grayed) { } /** - * Sets the image for multiple columns in the Table. + * Sets the image for multiple columns in the tree. * * @param images the array of new images * @@ -939,7 +941,7 @@ public void setGrayed (boolean grayed) { * <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> - * + * * @since 3.1 */ public void setImage (Image [] images) { @@ -963,7 +965,7 @@ public void setImage (Image [] images) { * <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> - * + * * @since 3.1 */ public void setImage (int index, Image image) { @@ -1001,7 +1003,7 @@ public void setImage (Image image) { } /** - * Sets the text for multiple columns in the table. + * Sets the text for multiple columns in the tree. * * @param strings the array of new strings * @@ -1012,7 +1014,7 @@ public void setImage (Image image) { * <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> - * + * * @since 3.1 */ public void setText (String [] strings) { @@ -1037,8 +1039,8 @@ public void setText (String [] strings) { * <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> - * - * @since3.1 + * + * @since 3.1 */ public void setText (int index, String string) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolBar.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolBar.java index 43347d6aa4..168c149bd5 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolBar.java @@ -165,9 +165,6 @@ CoolItem getGrabbedItem(int x, int y) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public CoolItem getItem (int index) { checkWidget(); @@ -191,9 +188,6 @@ public CoolItem getItem (int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget(); @@ -214,9 +208,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public CoolItem [] getItems () { checkWidget(); @@ -852,9 +843,6 @@ public void setSize (int width, int height) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public int[] getItemOrder () { checkWidget (); @@ -1064,9 +1052,6 @@ public void setWrapIndices (int[] indices) { * <li>ERROR_NULL_ARGUMENT - if item order or sizes is null</li> * <li>ERROR_INVALID_ARGUMENT - if item order or sizes is not the same length as the number of items</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItemLayout (int[] itemOrder, int[] wrapIndices, Point[] sizes) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java index 081764d473..bec30ed35a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java @@ -382,7 +382,7 @@ void onSelection (Event ev) { * Removes the listener from the collection of listeners that * will be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java index 73f786ce31..f54e25a8e9 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java @@ -12,6 +12,9 @@ package org.eclipse.swt.graphics; import org.eclipse.swt.*; +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public class Path { /** diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java index 186eb177e8..7ae8080338 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java @@ -12,9 +12,12 @@ package org.eclipse.swt.graphics; import org.eclipse.swt.*; +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public class Transform { /** - * the handle to the OS transform resource + * the handle to the OS path resource * (Warning: This field is platform dependent) */ public int handle; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java index dea08abb9e..fb418ad1bd 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/tabfolder/org/eclipse/swt/widgets/TabFolder.java @@ -1079,6 +1079,9 @@ public void setSelection(int index) { * * @param items the array of items * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the items array 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> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java index 2a0c6ab15d..34f55bae58 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java @@ -268,6 +268,9 @@ public void dispose () { * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the gc is null</li> + * </ul> */ public void draw (GC gc, int x, int y) { draw(gc, x, y, -1, -1, null, null); @@ -288,6 +291,9 @@ public void draw (GC gc, int x, int y) { * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the gc is null</li> + * </ul> */ public void draw (GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground) { checkLayout(); @@ -834,6 +840,7 @@ public int getNextOffset (int offset, int movement) { * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1222,7 +1229,7 @@ public void setAlignment (int alignment) { * </ul> * * @see #setDescent(int) - * @see #getLineMetrics() + * @see #getLineMetrics(int) */ public void setAscent (int ascent) { checkLayout(); @@ -1248,7 +1255,7 @@ public void setAscent (int ascent) { * </ul> * * @see #setAscent(int) - * @see #getLineMetrics() + * @see #getLineMetrics(int) */ public void setDescent (int descent) { checkLayout(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java index 8f3f34edc0..7d8b1a45ed 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java @@ -20,7 +20,7 @@ import java.util.Vector; /** * Instances of this class implement a selectable user interface * object that displays a list of images and strings and issue - * notificiation when selected. + * notification when selected. * <p> * The item children that may be added to instances of this class * must be of type <code>TableItem</code>. @@ -246,7 +246,7 @@ protected void checkSubclass () { } /** * Clears the item at the given zero-relative index in the receiver. - * The text, icon and other attribues of the item are set to the default + * The text, icon and other attributes of the item are set to the default * value. If the table was created with the SWT.VIRTUAL style, these * attributes are requested again as needed. * @@ -294,7 +294,7 @@ public void clear (int index) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -330,7 +330,7 @@ public void clear (int start, int end) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -359,7 +359,7 @@ public void clear (int [] indices) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -805,7 +805,7 @@ TableColumn getColumnAtX(int xPosition) { * Returns the number of columns contained in the receiver. * If no <code>TableColumn</code>s were created by the programmer, * this value is zero, despite the fact that visually, one column - * of items is may be visible. This occurs when the programmer uses + * of items may be visible. This occurs when the programmer uses * the table like a list, adding items but never creating a column. * * @return the number of columns @@ -814,9 +814,6 @@ TableColumn getColumnAtX(int xPosition) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getColumnCount() { checkWidget(); @@ -849,6 +846,11 @@ public int getColumnCount() { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move + * * @since 3.1 */ public int[] getColumnOrder () { @@ -2012,9 +2014,6 @@ void reindexColumns(int startIndex) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove(int indices[]) { checkWidget(); @@ -2065,9 +2064,6 @@ public void redraw (int x, int y, int width, int height, boolean all) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove(int index) { checkWidget(); @@ -2100,9 +2096,6 @@ public void remove(int index) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove(int start, int end) { checkWidget(); @@ -2589,7 +2582,7 @@ public void selectAll() { * in terms of the zero-relative ordering of when the items * were added. * - * @param itemOrder the new order to display the items + * @param order the new order to display the items * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2599,7 +2592,12 @@ public void selectAll() { * <li>ERROR_NULL_ARGUMENT - if the item order is null</li> * <li>ERROR_INVALID_ARGUMENT - if the item order is not the same length as the number of items</li> * </ul> - * + * + * @see Table#getColumnOrder() + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move + * * @since 3.1 */ public void setColumnOrder (int [] order) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableColumn.java index b19b51544a..b70c079206 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableColumn.java @@ -297,6 +297,8 @@ public Table getParent() { * * @see Table#getColumnOrder() * @see Table#setColumnOrder(int[]) + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move * * @since 3.1 */ @@ -376,7 +378,7 @@ public void pack() { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -400,7 +402,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -504,6 +506,8 @@ void setIndex(int newIndex) { * * @see Table#setColumnOrder(int[]) * @see Table#getColumnOrder() + * @see TableColumn#getMoveable() + * @see SWT#Move * * @since 3.1 */ @@ -513,8 +517,10 @@ public void setMoveable (boolean moveable) { } /** * Sets the resizable attribute. A column that is - * not resizable cannot be dragged by the user but - * may be resized by the programmer. + * resizable can be resized by the user dragging the + * edge of the header. A column that is not resizable + * cannot be dragged by the user but may be resized + * by the programmer. * * @param resizable the resize attribute * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java index 772eb2a363..b62b3c175b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java @@ -816,9 +816,6 @@ public String getText() { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_TEXT - if the column at index does not exist</li> - * </ul> */ public String getText(int columnIndex) { checkWidget(); @@ -1404,7 +1401,7 @@ public void setForeground (int index, Color color){ redraw (); } /** - * Sets the image for multiple columns in the Table. + * Sets the image for multiple columns in the table. * * @param images the array of new images * @@ -1463,6 +1460,8 @@ public void setImage(Image image) { * <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> + * + * @deprecated this functionality is not supported on most platforms */ public void setImageIndent(int indent) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java index d4bd2fcbcb..02a11447ac 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java @@ -15,6 +15,30 @@ import org.eclipse.swt.events.*; import org.eclipse.swt.graphics.*; import org.eclipse.swt.internal.*; +/** + * Instances of this class provide a selectable user interface object + * that displays a hierarchy of items and issue notificiation when an + * item in the hierarchy is selected. + * <p> + * The item children that may be added to instances of this class + * must be of type <code>TreeItem</code>. + * </p><p> + * Note that although this class is a subclass of <code>Composite</code>, + * it does not make sense to add <code>Control</code> children to it, + * or set a layout on it. + * </p><p> + * <dl> + * <dt><b>Styles:</b></dt> + * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION</dd> + * <dt><b>Events:</b></dt> + * <dd>Selection, DefaultSelection, Collapse, Expand</dd> + * </dl> + * <p> + * Note: Only one of the styles SINGLE and MULTI may be specified. + * </p><p> + * IMPORTANT: This class is <em>not</em> intended to be subclassed. + * </p> + */ public class Tree extends Composite { Canvas header; TreeColumn[] columns = new TreeColumn [0]; @@ -51,6 +75,36 @@ public class Tree extends Composite { static final String ID_CHECKMARK = "CHECKMARK"; //$NON-NLS-1$ static final String ID_CONNECTOR_COLOR = "CONNECTOR_COLOR"; //$NON-NLS-1$ +/** + * 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 + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control 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#SINGLE + * @see SWT#MULTI + * @see SWT#CHECK + * @see Widget#checkSubclass + * @see Widget#getStyle + */ public Tree (Composite parent, int style) { super (parent, checkStyle (style | SWT.H_SCROLL | SWT.V_SCROLL | SWT.NO_REDRAW_RESIZE)); setForeground (display.getSystemColor (SWT.COLOR_LIST_FOREGROUND)); @@ -97,6 +151,33 @@ public Tree (Composite parent, int style) { vBar.addListener (SWT.Selection, listener); hBar.addListener (SWT.Selection, listener); } +/** + * Adds the listener to the collection of listeners who will + * be notified when the receiver's selection changes, by sending + * it one of the messages defined in the <code>SelectionListener</code> + * interface. + * <p> + * When <code>widgetSelected</code> is called, the item field of the event object is valid. + * If the reciever has <code>SWT.CHECK</code> style set and the check selection changes, + * the event object detail field contains the value <code>SWT.CHECK</code>. + * <code>widgetDefaultSelected</code> is typically called when an item is double-clicked. + * The item field of the event object is valid for default selection, but the detail field is not used. + * </p> + * + * @param listener the listener which should be notified + * + * @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 SelectionListener + * @see #removeSelectionListener + * @see SelectionEvent + */ public void addSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -104,6 +185,25 @@ public void addSelectionListener (SelectionListener listener) { addListener (SWT.Selection, typedListener); addListener (SWT.DefaultSelection, typedListener); } +/** + * Adds the listener to the collection of listeners who will + * be notified when an item in the receiver is expanded or collapsed + * by sending it one of the messages defined in the <code>TreeListener</code> + * interface. + * + * @param listener the listener which should be notified + * + * @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 TreeListener + * @see #removeTreeListener + */ public void addTreeListener (TreeListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -211,6 +311,14 @@ void createItem (TreeItem item, int index) { if (redrawIndex > 0 && item.isLastChild ()) redrawIndex--; redrawFromItemDownwards (items [redrawIndex].availableIndex); } +/** + * Deselects all selected items in the receiver. + * + * @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 deselectAll () { checkWidget (); TreeItem[] oldSelection = selectedItems; @@ -363,15 +471,75 @@ public Control[] getChildren () { Image getCollapsedImage () { return (Image) display.getData (ID_COLLAPSED); } +/** + * Returns the column at the given, zero-relative index in the + * receiver. Throws an exception if the index is out of range. + * If no <code>TreeColumn</code>s were created by the programmer, + * this method will throw <code>ERROR_INVALID_RANGE</code> despite + * the fact that a single column of data may be visible in the tree. + * This occurs when the programmer uses the tree like a list, adding + * items but never creating a column. + * + * @param index the index of the column to return + * @return the column at the given index + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</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> + * + * @since 3.1 + */ public TreeColumn getColumn (int index) { checkWidget (); if (!(0 <= index && index < columns.length)) error (SWT.ERROR_INVALID_RANGE); return columns [index]; } +/** + * Returns the number of columns contained in the receiver. + * If no <code>TreeColumn</code>s were created by the programmer, + * this value is zero, despite the fact that visually, one column + * of items may be visible. This occurs when the programmer uses + * the tree like a list, adding items but never creating a column. + * + * @return the number of columns + * + * @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> + * + * @since 3.1 + */ public int getColumnCount () { checkWidget (); return columns.length; } +/** + * Returns an array of <code>TreeColumn</code>s which are the + * columns in the receiver. If no <code>TreeColumn</code>s were + * created by the programmer, the array is empty, despite the fact + * that visually, one column of items may be visible. This occurs + * when the programmer uses the tree like a list, adding items but + * never creating a column. + * <p> + * Note: This is not the actual structure used by the receiver + * to maintain its list of items, so modifying the array will + * not affect the receiver. + * </p> + * + * @return the items in the receiver + * + * @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> + * + * @since 3.1 + */ public TreeColumn[] getColumns () { checkWidget (); TreeColumn[] result = new TreeColumn [columns.length]; @@ -387,10 +555,34 @@ Image getExpandedImage () { Image getGrayUncheckedImage () { return (Image) display.getData (ID_GRAYUNCHECKED); } +/** + * Returns the width in pixels of a grid line. + * + * @return the width of a grid line in pixels + * + * @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> + * + * @since 3.1 + */ public int getGridLineWidth () { checkWidget (); return 1; } +/** + * Returns the height of the receiver's header + * + * @return the height of the header or zero if the header is not visible + * + * @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> + * + * @since 3.1 + */ public int getHeaderHeight () { checkWidget (); if (!header.getVisible ()) return 0; @@ -399,10 +591,45 @@ public int getHeaderHeight () { int getHeaderPadding () { return MARGIN_CELL + WIDTH_HEADER_SHADOW; } +/** + * Returns <code>true</code> if the receiver's header is visible, + * and <code>false</code> otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, this method + * may still indicate that it is considered visible even though + * it may not actually be showing. + * </p> + * + * @return the receiver's header's visibility state + * + * @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> + * + * @since 3.1 + */ public boolean getHeaderVisible () { checkWidget (); return header.getVisible (); } +/** + * Returns the item at the given point in the receiver + * or null if no such item exists. The point is in the + * coordinate system of the receiver. + * + * @param point the point used to locate the item + * @return the item at the given point + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the point 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 TreeItem getItem (Point point) { checkWidget (); int index = (point.y - getHeaderHeight ()) / itemHeight - topIndex; @@ -411,14 +638,55 @@ public TreeItem getItem (Point point) { if (!result.getHitBounds ().contains (point)) return null; /* considers the x value */ return result; } +/** + * Returns the number of items contained in the receiver + * that are direct item children of the receiver. The + * number that is returned is the number of roots in the + * tree. + * + * @return the number of items + * + * @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 getItemCount () { checkWidget (); return items.length; } +/** + * Returns the height of the area which would be used to + * display <em>one</em> of the items in the tree. + * + * @return the height of one item + * + * @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 getItemHeight () { checkWidget (); return itemHeight; } +/** + * Returns the items contained in the receiver + * that are direct item children of the receiver. These + * are the roots of the tree. + * <p> + * Note: This is not the actual structure used by the receiver + * to maintain its list of items, so modifying the array will + * not affect the receiver. + * </p> + * + * @return the items + * + * @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 TreeItem[] getItems () { checkWidget (); TreeItem[] result = new TreeItem [items.length]; @@ -433,20 +701,77 @@ int getItemY (TreeItem item) { if (index == -1) return -1; return (index - topIndex) * itemHeight + getHeaderHeight (); } +/** + * Returns <code>true</code> if the receiver's lines are visible, + * and <code>false</code> otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, this method + * may still indicate that it is considered visible even though + * it may not actually be showing. + * </p> + * + * @return the visibility state of the lines + * + * @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> + * + * @since 3.1 + */ public boolean getLinesVisible () { checkWidget (); return linesVisible; } +/** + * Returns the receiver's parent item, which must be a + * <code>TreeItem</code> or null when the receiver is a + * root. + * + * @return the receiver's parent item + * + * @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 TreeItem getParentItem () { checkWidget (); return null; } +/** + * Returns an array of <code>TreeItem</code>s that are currently + * selected in the receiver. An empty array indicates that no + * items are selected. + * <p> + * Note: This is not the actual structure used by the receiver + * to maintain its selection, so modifying the array will + * not affect the receiver. + * </p> + * @return an array representing the selection + * + * @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 TreeItem[] getSelection () { checkWidget (); TreeItem[] result = new TreeItem [selectedItems.length]; System.arraycopy (selectedItems, 0, result, 0, selectedItems.length); return result; } +/** + * Returns the number of selected items contained in the receiver. + * + * @return the number of selected items + * + * @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 getSelectionCount () { checkWidget (); return selectedItems.length; @@ -461,6 +786,20 @@ int getSelectionIndex (TreeItem item) { } return -1; } +/** + * Returns the item which is currently at the top of the receiver. + * This item can change when items are expanded, collapsed, scrolled + * or new items are added or removed. + * + * @return the item at the top of the receiver + * + * @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> + * + * @since 2.1 + */ public TreeItem getTopItem () { checkWidget (); if (availableItems.length == 0) return null; @@ -2009,6 +2348,14 @@ void redrawItems (int startIndex, int endIndex, boolean focusBoundsOnly) { redraw (0, startY, bounds.width, height, false); } } +/** + * Removes all of the items from the receiver. + * <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> + */ public void removeAll () { checkWidget (); setFocusItem (null, false); @@ -2035,18 +2382,62 @@ void removeSelectedItem (int index) { System.arraycopy (selectedItems, index + 1, newSelectedItems, index, newSelectedItems.length - index); selectedItems = newSelectedItems; } +/** + * Removes the listener from the collection of listeners who will + * be notified when the receiver's selection changes. + * + * @param listener the listener which should no longer be notified + * + * @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 SelectionListener + * @see #addSelectionListener + */ public void removeSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); removeListener (SWT.Selection, listener); removeListener (SWT.DefaultSelection, listener); } +/** + * Removes the listener from the collection of listeners who will + * be notified when items in the receiver are expanded or collapsed.. + * + * @param listener the listener which should no longer be notified + * + * @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 TreeListener + * @see #addTreeListener + */ public void removeTreeListener (TreeListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); removeListener (SWT.Expand, listener); removeListener (SWT.Collapse, listener); } +/** + * Selects all of the items in the receiver. + * <p> + * If the receiver is single-select, do nothing. + * + * @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 selectAll () { checkWidget (); if ((style & SWT.SINGLE) != 0) return; @@ -2130,6 +2521,24 @@ void setHeaderImageHeight (int value) { header.setSize (headerSize.x, newHeaderHeight); } } +/** + * Marks the receiver's header as visible if the argument is <code>true</code>, + * and marks it invisible otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, marking + * it visible may not actually cause it to be displayed. + * </p> + * + * @param show the new visibility state + * + * @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> + * + * @since 3.1 + */ public void setHeaderVisible (boolean value) { checkWidget (); if (header.getVisible () == value) return; /* no change */ @@ -2141,6 +2550,23 @@ void setImageHeight (int value) { imageHeight = value; itemHeight = Math.max (fontHeight, imageHeight) + 2 * getCellPadding (); } +/** + * Display a mark indicating the point at which an item will be inserted. + * The drop insert item has a visual hint to show where a dragged item + * will be inserted when dropped on the tree. + * + * @param item the insert item. Null will clear the insertion mark. + * @param before true places the insert mark above 'item'. false places + * the insert mark below 'item'. + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</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 setInsertMark (TreeItem item, boolean before) { checkWidget (); if (item != null && item.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT); @@ -2157,12 +2583,51 @@ public void setInsertMark (TreeItem item, boolean before) { redrawItem (item.availableIndex, true); } } +/** + * Marks the receiver's lines as visible if the argument is <code>true</code>, + * and marks it invisible otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, marking + * it visible may not actually cause it to be displayed. + * </p> + * + * @param show the new visibility state + * + * @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> + * + * @since 3.1 + */ public void setLinesVisible (boolean value) { checkWidget (); if (linesVisible == value) return; /* no change */ linesVisible = value; redraw (); } +/** + * Sets the receiver's selection to be the given array of items. + * The current selection is cleared before the new items are selected. + * <p> + * Items that are not in the receiver are ignored. + * If the receiver is single-select and multiple items are specified, + * then all items are ignored. + * + * @param items the array of items + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the array of items is null</li> + * <li>ERROR_INVALID_ARGUMENT - if one of the items has been disposed</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 Tree#deselectAll() + */ public void setSelection (TreeItem[] items) { checkWidget (); if (items == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -2203,6 +2668,26 @@ public void setSelection (TreeItem[] items) { } } } +/** + * Sets the item which is currently at the top of the receiver. + * This item can change when items are expanded, collapsed, scrolled + * or new items are added or removed. + * + * @param item the item to be shown + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</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 Tree#getTopItem() + * + * @since 2.1 + */ public void setTopItem (TreeItem item) { checkWidget (); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -2225,6 +2710,24 @@ public void setTopItem (TreeItem item) { gc.copyArea (0, 0, clientArea.width, clientArea.height, 0, change * itemHeight); gc.dispose (); } +/** + * Shows the column. If the column is already showing in the receiver, + * this method simply returns. Otherwise, the columns are scrolled until + * the column is visible. + * + * @param column the column to be shown + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</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> + * + * @since 3.1 + */ public void showColumn (TreeColumn column) { checkWidget (); int x = column.getX (); @@ -2245,6 +2748,24 @@ public void showColumn (TreeColumn column) { getHorizontalBar ().setSelection (horizontalOffset); redraw (); } +/** + * Shows the item. If the item is already showing in the receiver, + * this method simply returns. Otherwise, the items are scrolled + * and expanded until the item is visible. + * + * @param item the item to be shown + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</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 Tree#showSelection() + */ public void showItem (TreeItem item) { checkWidget (); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -2267,6 +2788,18 @@ public void showItem (TreeItem item) { setTopItem (availableItems [Math.min (index - visibleItemCount + 1, availableItems.length - 1)]); } } +/** + * Shows the selection. If the selection is already showing in the receiver, + * this method simply returns. Otherwise, the items are scrolled until + * the selection is visible. + * + * @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 Tree#showItem(TreeItem) + */ public void showSelection () { checkWidget (); if (selectedItems.length == 0) return; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeColumn.java index 8cd1293f69..3e5b9d0fac 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeColumn.java @@ -14,21 +14,121 @@ import org.eclipse.swt.*; import org.eclipse.swt.events.*; import org.eclipse.swt.graphics.*; +/** + * Instances of this class represent a column in a tree widget. + * <dl> + * <dt><b>Styles:</b></dt> + * <dd>LEFT, RIGHT, CENTER</dd> + * <dt><b>Events:</b></dt> + * <dd> Move, Resize, Selection</dd> + * </dl> + * <p> + * Note: Only one of the styles LEFT, RIGHT and CENTER may be specified. + * </p><p> + * IMPORTANT: This class is <em>not</em> intended to be subclassed. + * </p> + * + * @since 3.1 + */ public class TreeColumn extends Item { Tree parent; String displayText; int width; boolean resizable = true; +/** + * Constructs a new instance of this class given its parent + * (which must be a <code>Tree</code>) and a style value + * describing its behavior and appearance. The item is added + * to the end of the items maintained by its parent. + * <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 + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control 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#LEFT + * @see SWT#RIGHT + * @see SWT#CENTER + * @see Widget#checkSubclass + * @see Widget#getStyle + */ public TreeColumn (Tree parent, int style) { this (parent, style, checkNull (parent).columns.length); } +/** + * Constructs a new instance of this class given its parent + * (which must be a <code>Tree</code>), a style value + * describing its behavior and appearance, and the index + * at which to place it in the items maintained by its parent. + * <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 + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control to construct + * @param index the index to store the receiver in its parent + * + * @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#LEFT + * @see SWT#RIGHT + * @see SWT#CENTER + * @see Widget#checkSubclass + * @see Widget#getStyle + */ public TreeColumn (Tree parent, int style, int index) { super (parent, checkStyle (style), index); if (!(0 <= index && index <= parent.columns.length)) error (SWT.ERROR_INVALID_RANGE); this.parent = parent; parent.createItem (this, index); } +/** + * Adds the listener to the collection of listeners who will + * be notified when the control is moved or resized, by sending + * it one of the messages defined in the <code>ControlListener</code> + * interface. + * + * @param listener the listener which should be notified + * + * @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 ControlListener + * @see #removeControlListener + */ public void addControlListener (ControlListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -36,6 +136,30 @@ public void addControlListener (ControlListener listener) { addListener (SWT.Resize, typedListener); addListener (SWT.Move, typedListener); } +/** + * Adds the listener to the collection of listeners who will + * be notified when the control is selected, by sending + * it one of the messages defined in the <code>SelectionListener</code> + * interface. + * <p> + * <code>widgetSelected</code> is called when the column header is selected. + * <code>widgetDefaultSelected</code> is not called. + * </p> + * + * @param listener the listener which should be notified + * + * @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 SelectionListener + * @see #removeSelectionListener + * @see SelectionEvent + */ public void addSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -123,6 +247,18 @@ void dispose (boolean notifyParent) { if (notifyParent) parent.destroyItem (this); parent = null; } +/** + * Returns a value which describes the position of the + * text or image in the receiver. The value will be one of + * <code>LEFT</code>, <code>RIGHT</code> or <code>CENTER</code>. + * + * @return the alignment + * + * @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 getAlignment () { checkWidget (); if ((style & SWT.CENTER) != 0) return SWT.CENTER; @@ -151,6 +287,16 @@ int getIndex () { } return -1; } +/** + * Returns the receiver's parent, which must be a <code>Tree</code>. + * + * @return the receiver's parent + * + * @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 Tree getParent () { checkWidget (); return parent; @@ -162,10 +308,32 @@ int getPreferredWidth () { gc.dispose (); return result + 2 * parent.getHeaderPadding (); } +/** + * Gets the resizable attribute. A column that is + * not resizable cannot be dragged by the user but + * may be resized by the programmer. + * + * @return the resizable attribute + * + * @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 boolean getResizable () { checkWidget (); return resizable; } +/** + * Gets the width of the receiver. + * + * @return the width + * + * @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 getWidth () { checkWidget (); return width; @@ -217,6 +385,17 @@ void paint (GC gc) { gc.drawText (displayText, startX, (headerHeight - fontHeight) / 2, SWT.DRAW_MNEMONIC); } } +/** + * Causes the receiver to be resized to its preferred size. + * For a composite, this involves computing the preferred size + * from its layout, if there is one. + * + * @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 pack () { checkWidget (); TreeItem[] availableItems = parent.availableItems; @@ -228,6 +407,23 @@ public void pack () { } parent.updateColumnWidth (this, width); } +/** + * Removes the listener from the collection of listeners who will + * be notified when the control is moved or resized. + * + * @param listener the listener which should no longer be notified + * + * @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 ControlListener + * @see #addControlListener + */ public void removeControlListener (ControlListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -235,12 +431,41 @@ public void removeControlListener (ControlListener listener) { eventTable.unhook (SWT.Move, listener); eventTable.unhook (SWT.Resize, listener); } +/** + * Removes the listener from the collection of listeners who will + * be notified when the control is selected. + * + * @param listener the listener which should no longer be notified + * + * @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 SelectionListener + * @see #addSelectionListener + */ public void removeSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); removeListener (SWT.Selection, listener); removeListener (SWT.DefaultSelection, listener); } +/** + * Controls how text and images will be displayed in the receiver. + * The argument should be one of <code>LEFT</code>, <code>RIGHT</code> + * or <code>CENTER</code>. + * + * @param alignment the new alignment + * + * @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 setAlignment (int alignment) { checkWidget (); if (getIndex () == 0) return; /* column 0 can only have left-alignment */ @@ -281,6 +506,18 @@ public void setImage (Image value) { parent.header.redraw (getX (), 0, width, parent.getHeaderHeight (), false); } +/** + * Sets the resizable attribute. A column that is + * not resizable cannot be dragged by the user but + * may be resized by the programmer. + * + * @param resizable the resize attribute + * + * @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 setResizable (boolean value) { checkWidget (); resizable = value; @@ -295,6 +532,16 @@ public void setText (String value) { gc.dispose (); parent.header.redraw (getX (), 0, width, parent.getHeaderHeight (), false); } +/** + * Sets the width of the receiver. + * + * @param width the new width + * + * @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 setWidth (int value) { checkWidget (); if (width == value) return; /* same value */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java index 850ab088ad..fdf95241b8 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java @@ -14,6 +14,20 @@ import org.eclipse.swt.SWT; import org.eclipse.swt.graphics.*; import org.eclipse.swt.internal.Compatibility; +/** + * Instances of this class represent a selectable user interface object + * that represents a hierarchy of tree items in a tree widget. + * + * <dl> + * <dt><b>Styles:</b></dt> + * <dd>(none)</dd> + * <dt><b>Events:</b></dt> + * <dd>(none)</dd> + * </dl> + * <p> + * IMPORTANT: This class is <em>not</em> intended to be subclassed. + * </p> + */ public class TreeItem extends Item { Tree parent; TreeItem parentItem; @@ -37,9 +51,70 @@ public class TreeItem extends Item { static final int MARGIN_TEXT = 3; /* the left and right margins within the text's space */ static final TreeItem[] NO_ITEMS = new TreeItem [0]; +/** + * Constructs a new instance of this class given its parent + * (which must be a <code>Tree</code> or a <code>TreeItem</code>) + * and a style value describing its behavior and appearance. + * The item is added to the end of the items maintained by its parent. + * <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 + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control 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 Widget#checkSubclass + * @see Widget#getStyle + */ public TreeItem (Tree parent, int style) { this (parent, style, checkNull (parent).items.length); } +/** + * Constructs a new instance of this class given its parent + * (which must be a <code>Tree</code> or a <code>TreeItem</code>), + * a style value describing its behavior and appearance, and the index + * at which to place it in the items maintained by its parent. + * <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 + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control to construct + * @param index the index to store the receiver in its parent + * + * @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 Widget#checkSubclass + * @see Widget#getStyle + */ public TreeItem (Tree parent, int style, int index) { super (parent, style); int validItemIndex = parent.items.length; @@ -56,9 +131,70 @@ public TreeItem (Tree parent, int style, int index) { } } } +/** + * Constructs a new instance of this class given its parent + * (which must be a <code>Tree</code> or a <code>TreeItem</code>) + * and a style value describing its behavior and appearance. + * The item is added to the end of the items maintained by its parent. + * <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 + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parentItem a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control 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 Widget#checkSubclass + * @see Widget#getStyle + */ public TreeItem (TreeItem parentItem, int style) { this (parentItem, style, checkNull (parentItem).items.length); } +/** + * Constructs a new instance of this class given its parent + * (which must be a <code>Tree</code> or a <code>TreeItem</code>), + * a style value describing its behavior and appearance, and the index + * at which to place it in the items maintained by its parent. + * <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 + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parentItem a composite control which will be the parent of the new instance (cannot be null) + * @param style the style of control to construct + * @param index the index to store the receiver in its parent + * + * @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 Widget#checkSubclass + * @see Widget#getStyle + */ public TreeItem (TreeItem parentItem, int style, int index) { super (checkNull (parentItem).parent, style); this.parentItem = parentItem; @@ -417,11 +553,37 @@ void expandAncestors () { if (parentItem != null) parentItem.expandAncestors (); setExpanded (true); } +/** + * Returns the receiver's background color. + * + * @return the background color + * + * @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> + * + * @since 2.0 + * + */ public Color getBackground () { checkWidget (); if (background != null) return background; return parent.getBackground (); } +/** + * Returns the background color at the given column index in the receiver. + * + * @param index the column index + * @return the background color + * + * @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> + * + * @since 3.1 + */ public Color getBackground (int columnIndex) { checkWidget (); int validColumnCount = Math.max (1, parent.columns.length); @@ -429,12 +591,37 @@ public Color getBackground (int columnIndex) { if (cellBackgrounds == null || cellBackgrounds [columnIndex] == null) return getBackground (); return cellBackgrounds [columnIndex]; } +/** + * Returns a rectangle describing the receiver's size and location + * relative to its parent. + * + * @return the receiver's bounding rectangle + * + * @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 Rectangle getBounds () { checkWidget (); if (!isAvailable()) return new Rectangle (0, 0, 0, 0); int textPaintWidth = textWidths [0] + 2 * MARGIN_TEXT; return new Rectangle (getTextX (0), parent.getItemY (this), textPaintWidth, parent.itemHeight - 1); } +/** + * Returns a rectangle describing the receiver's size and location + * relative to its parent at a column in the tree. + * + * @param index the index that specifies the column + * @return the receiver's bounding column rectangle + * + * @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> + * + * @since 3.1 + */ public Rectangle getBounds (int columnIndex) { checkWidget (); if (!isAvailable ()) return new Rectangle (0, 0, 0, 0); @@ -498,6 +685,19 @@ Rectangle getCheckboxBounds () { result.y = parent.getItemY (this) + (itemHeight - result.height) / 2; return result; } +/** + * Returns <code>true</code> if the receiver is checked, + * and false otherwise. When the parent does not have + * the <code>CHECK style, return false. + * <p> + * + * @return the checked state + * + * @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 boolean getChecked () { checkWidget (); return checked; @@ -552,6 +752,18 @@ int getContentX (int columnIndex) { contentX += parent.expanderBounds.width; return contentX + Tree.MARGIN_IMAGE + INDENT_HIERARCHY; } +/** + * Returns <code>true</code> if the receiver is expanded, + * and false otherwise. + * <p> + * + * @return the expanded state + * + * @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 boolean getExpanded () { checkWidget (); return expanded; @@ -602,11 +814,37 @@ int getFocusX () { } return result; } +/** + * Returns the font that the receiver will use to paint textual information for this item. + * + * @return the receiver's font + * + * @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> + * + * @since 3.0 + */ public Font getFont () { checkWidget (); if (font != null) return font; return parent.getFont (); } +/** + * Returns the font that the receiver will use to paint textual information + * for the specified cell in this item. + * + * @param index the column index + * @return the receiver's font + * + * @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> + * + * @since 3.1 + */ public Font getFont (int columnIndex) { checkWidget (); int validColumnCount = Math.max (1, parent.columns.length); @@ -622,11 +860,38 @@ int getFontHeight (int columnIndex) { if (fontHeights == null || fontHeights [columnIndex] == 0) return getFontHeight (); return fontHeights [columnIndex]; } +/** + * Returns the foreground color that the receiver will use to draw. + * + * @return the receiver's foreground color + * + * @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> + * + * @since 2.0 + * + */ public Color getForeground () { checkWidget (); if (foreground != null) return foreground; return parent.getForeground (); } +/** + * + * Returns the foreground color at the given column index in the receiver. + * + * @param index the column index + * @return the foreground color + * + * @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> + * + * @since 3.1 + */ public Color getForeground (int columnIndex) { checkWidget (); int validColumnCount = Math.max (1, parent.columns.length); @@ -634,6 +899,19 @@ public Color getForeground (int columnIndex) { if (cellForegrounds == null || cellForegrounds [columnIndex] == null) return getForeground (); return cellForegrounds [columnIndex]; } +/** + * Returns <code>true</code> if the receiver is grayed, + * and false otherwise. When the parent does not have + * the <code>CHECK style, return false. + * <p> + * + * @return the grayed state + * + * @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 boolean getGrayed () { checkWidget (); return grayed; @@ -690,6 +968,20 @@ public Image getImage () { checkWidget (); return super.getImage (); } +/** + * Returns the image stored at the given column index in the receiver, + * or null if the image has not been set or if the column does not exist. + * + * @param index the column index + * @return the image stored at the given column index in the receiver + * + * @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> + * + * @since 3.1 + */ public Image getImage (int columnIndex) { checkWidget (); int validColumnCount = Math.max (1, parent.columns.length); @@ -697,6 +989,21 @@ public Image getImage (int columnIndex) { if (columnIndex == 0) return getImage (); return images [columnIndex]; } +/** + * Returns a rectangle describing the size and location + * relative to its parent of an image at a column in the + * table. + * + * @param index the index that specifies the column + * @return the receiver's bounding image rectangle + * + * @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> + * + * @since 3.1 + */ public Rectangle getImageBounds (int columnIndex) { checkWidget (); int validColumnCount = Math.max (1, parent.columns.length); @@ -742,20 +1049,69 @@ int getIndex () { } return -1; } +/** + * Returns the number of items contained in the receiver + * that are direct item children of the receiver. + * + * @return the number of items + * + * @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 getItemCount () { checkWidget (); return items.length; } +/** + * Returns an array of <code>TreeItem</code>s which are the + * direct item children of the receiver. + * <p> + * Note: This is not the actual structure used by the receiver + * to maintain its list of items, so modifying the array will + * not affect the receiver. + * </p> + * + * @return the receiver's items + * + * @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 TreeItem [] getItems () { checkWidget (); TreeItem[] result = new TreeItem [items.length]; System.arraycopy (items, 0, result, 0, items.length); return result; } +/** + * Returns the receiver's parent, which must be a <code>Tree</code>. + * + * @return the receiver's parent + * + * @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 Tree getParent () { checkWidget (); return parent; } +/** + * Returns the receiver's parent item, which must be a + * <code>TreeItem</code> or null when the receiver is a + * root. + * + * @return the receiver's parent item + * + * @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 TreeItem getParentItem () { checkWidget (); return parentItem; @@ -776,6 +1132,20 @@ public String getText () { checkWidget (); return super.getText (); } +/** + * Returns the text stored at the given column index in the receiver, + * or empty string if the text has not been set. + * + * @param index the column index + * @return the text stored at the given column index in the receiver + * + * @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> + * + * @since 3.1 + */ public String getText (int columnIndex) { checkWidget (); int validColumnCount = Math.max (1, parent.columns.length); @@ -1160,6 +1530,24 @@ void removeItem (TreeItem item, int index) { return; } } +/** + * Sets the receiver's background color to the color specified + * by the argument, or to the default system color for the item + * if the argument is null. + * + * @param color the new color (or null) + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</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> + * + * @since 2.0 + * + */ public void setBackground (Color value) { checkWidget (); if (value != null && value.isDisposed ()) { @@ -1170,6 +1558,25 @@ public void setBackground (Color value) { background = value; redrawItem (); } +/** + * Sets the background color at the given column index in the receiver + * to the color specified by the argument, or to the default system color for the item + * if the argument is null. + * + * @param index the column index + * @param color the new color (or null) + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</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> + * + * @since 3.1 + * + */ public void setBackground (int columnIndex, Color value) { checkWidget (); if (value != null && value.isDisposed ()) { @@ -1187,6 +1594,17 @@ public void setBackground (int columnIndex, Color value) { Rectangle bounds = getCellBounds (columnIndex); parent.redraw (bounds.x, bounds.y, bounds.width, bounds.height, false); } +/** + * Sets the checked state of the receiver. + * <p> + * + * @param checked the new checked state + * + * @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 setChecked (boolean value) { checkWidget (); if ((parent.getStyle () & SWT.CHECK) == 0) return; @@ -1196,6 +1614,17 @@ public void setChecked (boolean value) { Rectangle bounds = getCheckboxBounds (); parent.redraw (bounds.x, bounds.y, bounds.width, bounds.height, false); } +/** + * Sets the expanded state of the receiver. + * <p> + * + * @param expanded the new expanded state + * + * @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 setExpanded (boolean value) { checkWidget (); if (expanded == value) return; @@ -1297,6 +1726,23 @@ public void setExpanded (boolean value) { Rectangle bounds = getExpanderBounds (); parent.redraw (bounds.x, bounds.y, bounds.width, bounds.height, false); } +/** + * Sets the font that the receiver will use to paint textual information + * for this item to the font specified by the argument, or to the default font + * for that kind of control if the argument is null. + * + * @param font the new font (or null) + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</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> + * + * @since 3.0 + */ public void setFont (Font value) { checkWidget (); if (value != null && value.isDisposed ()) { @@ -1325,6 +1771,25 @@ public void setFont (Font value) { } redrawItem (); } +/** + * Sets the font that the receiver will use to paint textual information + * for the specified cell in this item to the font specified by the + * argument, or to the default font for that kind of control if the + * argument is null. + * + * @param index the column index + * @param font the new font (or null) + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</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> + * + * @since 3.1 + */ public void setFont (int columnIndex, Font value) { checkWidget (); if (value != null && value.isDisposed ()) { @@ -1351,6 +1816,26 @@ public void setFont (int columnIndex, Font value) { Rectangle bounds = getCellBounds (columnIndex); parent.redraw (bounds.x, bounds.y, bounds.width, bounds.height, false); } +/** + * Sets the receiver's foreground color to the color specified + * by the argument, or to the default system color for the item + * if the argument is null. + * + * @param color the new color (or null) + * + * @since 2.0 + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</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> + * + * @since 2.0 + * + */ public void setForeground (Color value) { checkWidget (); if (value != null && value.isDisposed ()) { @@ -1361,6 +1846,25 @@ public void setForeground (Color value) { foreground = value; redrawItem (); } +/** + * Sets the foreground color at the given column index in the receiver + * to the color specified by the argument, or to the default system color for the item + * if the argument is null. + * + * @param index the column index + * @param color the new color (or null) + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</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> + * + * @since 3.1 + * + */ public void setForeground (int columnIndex, Color value) { checkWidget (); if (value != null && value.isDisposed ()) { @@ -1382,6 +1886,17 @@ public void setForeground (int columnIndex, Color value) { parent.itemHeight, false); } +/** + * Sets the grayed state of the receiver. + * <p> + * + * @param grayed the new grayed state + * + * @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 setGrayed (boolean value) { checkWidget (); if ((parent.getStyle () & SWT.CHECK) == 0) return; @@ -1395,6 +1910,22 @@ public void setImage (Image value) { checkWidget (); setImage (0, value); } +/** + * Sets the image for multiple columns in the tree. + * + * @param images the array of new images + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the array of images is null</li> + * <li>ERROR_INVALID_ARGUMENT - if one of the images has been disposed</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> + * + * @since 3.1 + */ public void setImage (Image[] value) { checkWidget (); if (value == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -1404,6 +1935,22 @@ public void setImage (Image[] value) { if (value [i] != null) setImage (i, value [i]); } } +/** + * Sets the receiver's image at a column. + * + * @param index the column index + * @param image the new image + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</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> + * + * @since 3.1 + */ public void setImage (int columnIndex, Image value) { checkWidget (); if (value != null && value.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT); @@ -1507,6 +2054,21 @@ public void setText (String value) { parent.updateHorizontalBar (newRightX, newRightX - oldRightX); } } +/** + * Sets the text for multiple columns in the tree. + * + * @param strings the array of new strings + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the text 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> + * + * @since 3.1 + */ public void setText (String[] value) { checkWidget (); if (value == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -1523,6 +2085,22 @@ public void setText (String[] value) { parent.updateHorizontalBar (newRightX, newRightX - oldRightX); } } +/** + * Sets the receiver's text at a column + * + * @param index the column index + * @param string the new text + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the text 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> + * + * @since 3.1 + */ public void setText (int columnIndex, String value) { checkWidget (); if (value == null) error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java index 76506fa99c..67b3792c87 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java @@ -191,8 +191,7 @@ public Cursor(Device device, int style) { * <li>ERROR_NULL_ARGUMENT - if the source is null</li> * <li>ERROR_NULL_ARGUMENT - if the mask is null and the source does not have a mask</li> * <li>ERROR_INVALID_ARGUMENT - if the source and the mask are not the same - * size, or either is not of depth one, or if the hotspot is outside - * the bounds of the image</li> + * size, or if the hotspot is outside the bounds of the image</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java index 005f9e44aa..5087118d20 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java @@ -367,12 +367,12 @@ public void drawFocus(int x, int y, int width, int height) { * <li>ERROR_NULL_ARGUMENT - if the image is null</li> * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li> * <li>ERROR_INVALID_ARGUMENT - if the given coordinates are outside the bounds of the image</li> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> + * </ul> */ public void drawImage(Image image, int x, int y) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -406,12 +406,12 @@ public void drawImage(Image image, int x, int y) { * <li>ERROR_INVALID_ARGUMENT - if any of the width or height arguments are negative. * <li>ERROR_INVALID_ARGUMENT - if the source rectangle is not contained within the bounds of the source image</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> + * </ul> */ public void drawImage(Image image, int srcX, int srcY, int srcWidth, int srcHeight, int destX, int destY, int destWidth, int destHeight) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -691,6 +691,9 @@ public void drawOval(int x, int y, int width, int height) { OS.gdk_draw_arc(data.drawable, handle, 0, x, y, width, height, 0, 23040); } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void drawPath(Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path.handle == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT); @@ -855,14 +858,16 @@ public void drawRectangle(Rectangle rect) { * right edges of the rectangle are at <code>x</code> and <code>x + width</code>. * The top and bottom edges are at <code>y</code> and <code>y + height</code>. * The <em>roundness</em> of the corners is specified by the - * <code>arcWidth</code> and <code>arcHeight</code> arguments. + * <code>arcWidth</code> and <code>arcHeight</code> arguments, which + * are respectively the width and height of the ellipse used to draw + * the corners. * * @param x the x coordinate of the rectangle to be drawn * @param y the y coordinate of the rectangle to be drawn * @param width the width of the rectangle to be drawn * @param height the height of the rectangle to be drawn - * @param arcWidth the horizontal diameter of the arc at the four corners - * @param arcHeight the vertical diameter of the arc at the four corners + * @param arcWidth the width of the arc + * @param arcHeight the height of the arc * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1328,6 +1333,9 @@ public void fillOval(int x, int y, int width, int height) { OS.gdk_gc_set_foreground(handle, color); } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void fillPath (Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path.handle == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT); @@ -1464,8 +1472,8 @@ public void fillRectangle(Rectangle rect) { * @param y the y coordinate of the rectangle to be filled * @param width the width of the rectangle to be filled * @param height the height of the rectangle to be filled - * @param arcWidth the horizontal diameter of the arc at the four corners - * @param arcHeight the vertical diameter of the arc at the four corners + * @param arcWidth the width of the arc + * @param arcHeight the height of the arc * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1584,6 +1592,9 @@ public int getAdvanceWidth(char ch) { return stringExtent(new String(new char[]{ch})).x; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public int getAlpha() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); initCairo(); @@ -1758,6 +1769,19 @@ public Color getForeground() { return Color.gtk_new(data.device, color); } +/** + * Returns the receiver's line cap style, which will be one + * of the constants <code>SWT.CAP_FLAT</code>, <code>SWT.CAP_ROUND</code>, + * or <code>SWT.CAP_SQUARE</code>. + * + * @return the cap style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int getLineCap() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); GdkGCValues values = new GdkGCValues(); @@ -1771,6 +1795,17 @@ public int getLineCap() { return cap; } +/** + * Returns the receiver's line dash style. + * + * @return the lin dash style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int[] getLineDash() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); byte[] dash_list = data.dashes; @@ -1782,6 +1817,19 @@ public int[] getLineDash() { return dashes; } +/** + * Returns the receiver's line join style, which will be one + * of the constants <code>SWT.JOIN_MITER</code>, <code>SWT.JOIN_ROUND</code>, + * or <code>SWT.JOIN_BEVEL</code>. + * + * @return the join style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int getLineJoin() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); GdkGCValues values = new GdkGCValues(); @@ -1854,6 +1902,9 @@ public int getStyle () { return data.style; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void getTransform(Transform transform) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (transform == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -2034,6 +2085,9 @@ boolean isIdentity(int /*long*/ matrix) { return a[0] == 1 && b[0] == 0 && c[0] == 0 && d[0] == 1 && tx[0] == 0 && ty[0] == 0; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setAlpha(int alpha) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); initCairo(); @@ -2164,6 +2218,9 @@ public void setClipping(int x, int y, int width, int height) { OS.gdk_region_destroy(clipRgn); } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setClipping(Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path != null && path.isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2202,8 +2259,8 @@ public void setClipping(Rectangle rect) { * by the argument. * * @param region the clipping region. - * - * * @exception IllegalArgumentException <ul> + * + * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li> * </ul> * @exception SWTException <ul> @@ -2289,6 +2346,22 @@ public void setForeground(Color color) { } } +/** + * Sets the receiver's line cap style to the argument, which must be one + * of the constants <code>SWT.CAP_FLAT</code>, <code>SWT.CAP_ROUND</code>, + * or <code>SWT.CAP_SQUARE</code>. + * + * @param cap the cap style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineCap(int cap) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); int cap_style = 0, cairo_style = 0; @@ -2318,6 +2391,20 @@ public void setLineCap(int cap) { } } +/** + * Sets the receiver's line dash style to the argument. + * + * @param dashes the dash style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the values in the array is less than or equal 0</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineDash(int[] dashes) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (dashes != null && dashes.length > 0) { @@ -2352,6 +2439,22 @@ public void setLineDash(int[] dashes) { } } +/** + * Sets the receiver's line join style to the argument, which must be one + * of the constants <code>SWT.JOIN_MITER</code>, <code>SWT.JOIN_ROUND</code>, + * or <code>SWT.JOIN_BEVEL</code>. + * + * @param join the join style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineJoin(int join) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); int join_style = 0, cairo_style = 0; @@ -2389,6 +2492,9 @@ public void setLineJoin(int join) { * * @param lineStyle the style to be used for drawing lines * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> @@ -2507,6 +2613,9 @@ void setString(String string, int flags) { data.drawFlags = flags; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setTransform(Transform transform) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (transform == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java index cea1a8e05f..f31fe2e751 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java @@ -386,12 +386,12 @@ public Image(Device device, Rectangle bounds) { * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * <li>ERROR_NULL_ARGUMENT - if the image data is null</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the ImageData is not supported</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> + * </ul> */ public Image(Device device, ImageData data) { if (device == null) device = Device.getDevice(); @@ -403,10 +403,8 @@ public Image(Device device, ImageData data) { /** * Constructs an instance of this class, whose type is * <code>SWT.ICON</code>, from the two given <code>ImageData</code> - * objects. The two images must be the same size, and the mask image - * must have a color depth of 1. Pixel transparency in either image - * will be ignored. If either image is an icon to begin with, an - * exception is thrown. + * objects. The two images must be the same size. Pixel transparency + * in either image will be ignored. * <p> * The mask image should contain white wherever the icon is to be visible, * and black wherever the icon is to be transparent. In addition, @@ -421,9 +419,7 @@ public Image(Device device, ImageData data) { * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * <li>ERROR_NULL_ARGUMENT - if either the source or mask is null </li> - * <li>ERROR_INVALID_ARGUMENT - if source and mask are different sizes or - * if the mask is not monochrome, or if either the source or mask - * is already an icon</li> + * <li>ERROR_INVALID_ARGUMENT - if source and mask are different sizes</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> @@ -449,7 +445,8 @@ public Image(Device device, ImageData source, ImageData mask) { * Constructs an instance of this class by loading its representation * from the specified input stream. Throws an error if an error * occurs while loading the image, or if the result is an image - * of an unsupported type. + * of an unsupported type. Application code is still responsible + * for closing the input stream. * <p> * This constructor is provided for convenience when loading a single * image only. If the stream contains multiple images, only the first @@ -473,7 +470,8 @@ public Image(Device device, ImageData source, ImageData mask) { * <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li> * <li>ERROR_IO - if an IO error occurs while reading data</li> * <li>ERROR_UNSUPPORTED_DEPTH - if the InputStream describes an image with an unsupported depth</li> - * </ul> + * <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li> + * * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> * </ul> @@ -506,6 +504,7 @@ public Image(Device device, InputStream stream) { * <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li> * <li>ERROR_IO - if an IO error occurs while reading data</li> * <li>ERROR_UNSUPPORTED_DEPTH - if the image file has an unsupported depth</li> + * <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java index 11dcd66eef..2d26d47d0f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java @@ -61,12 +61,12 @@ public Region() { * * @param device the device on which to allocate the region * -* @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li> - * </ul> * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li> + * </ul> * * @see #dispose * @@ -134,9 +134,13 @@ public void add(Rectangle rect) { * Adds the given rectangle to the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to merge with the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> * </ul> * @exception SWTException <ul> @@ -311,7 +315,10 @@ public void intersect(Rectangle rect) { * Intersects the given rectangle to the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to intersect with the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> @@ -486,9 +493,13 @@ public void subtract(Rectangle rect) { * Subtracts the given rectangle from the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to subtract from the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> * </ul> * @exception SWTException <ul> @@ -556,7 +567,7 @@ public void translate (int x, int y) { * Translate all of the polygons the receiver maintains to describe * its area by the specified point. * - * @param point the point to translate + * @param pt the point to translate * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java index d2a972231a..fa7a6108e8 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java @@ -240,6 +240,9 @@ public void dispose() { * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the gc is null</li> + * </ul> */ public void draw(GC gc, int x, int y) { checkLayout (); @@ -264,6 +267,9 @@ public void draw(GC gc, int x, int y) { * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the gc is null</li> + * </ul> */ public void draw(GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground) { checkLayout (); @@ -789,6 +795,7 @@ int _getOffset (int offset, int movement, boolean forward) { * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1102,7 +1109,7 @@ public void setAlignment (int alignment) { * </ul> * * @see #setDescent(int) - * @see #getLineMetrics() + * @see #getLineMetrics(int) */ public void setAscent (int ascent) { checkLayout(); @@ -1128,7 +1135,7 @@ public void setAscent (int ascent) { * </ul> * * @see #setAscent(int) - * @see #getLineMetrics() + * @see #getLineMetrics(int) */ public void setDescent (int descent) { checkLayout(); |