diff options
author | Carolyn MacLeod <Carolyn_MacLeod@ca.ibm.com> | 2012-05-28 16:28:51 -0400 |
---|---|---|
committer | Carolyn MacLeod <Carolyn_MacLeod@ca.ibm.com> | 2012-05-28 16:28:51 -0400 |
commit | 1587016128f120779b698d8ab37efa85ed9c8e7c (patch) | |
tree | 43fd0f0215cf93617860377f7f1492ab17e5ff1b | |
parent | 4e462dca85eb559e9eafb7c043add508ebb9e7fb (diff) | |
download | eclipse.platform.swt-1587016128f120779b698d8ab37efa85ed9c8e7c.tar.gz eclipse.platform.swt-1587016128f120779b698d8ab37efa85ed9c8e7c.tar.xz eclipse.platform.swt-1587016128f120779b698d8ab37efa85ed9c8e7c.zip |
Bug 380560 - Do the annual javadoc/copyright bash for 3.8 and 4.2
14 files changed, 267 insertions, 21 deletions
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java index 256c9f6af3..c03fa48bcc 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java @@ -21,7 +21,7 @@ import org.eclipse.swt.internal.cocoa.*; * issues notification when pressed and released. * <dl> * <dt><b>Styles:</b></dt> - * <dd>ARROW, CHECK, PUSH, RADIO, TOGGLE, FLAT</dd> + * <dd>ARROW, CHECK, PUSH, RADIO, TOGGLE, FLAT, WRAP</dd> * <dd>UP, DOWN, LEFT, RIGHT, CENTER</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ColorDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ColorDialog.java index 0c73f60583..7482cecba3 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ColorDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ColorDialog.java @@ -218,6 +218,10 @@ public void setRGB(RGB rgb) { * * @param rgbs the array of RGBs, which may be null * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if an RGB in the rgbs array is null</li> + * </ul> + * * @since 3.8 */ public void setRGBs(RGB[] rgbs) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java index c9f026356c..02a983fc22 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java @@ -601,11 +601,39 @@ Cursor findCursor () { return (cursor != null || (style & SWT.READ_ONLY) != 0) ? cursor : display.getSystemCursor (SWT.CURSOR_IBEAM); } +/** + * Returns the character position of the caret. + * <p> + * Indexing is zero based. + * </p> + * + * @return the position of the caret + * + * @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.8 + */ public int getCaretPosition() { checkWidget(); return selectionRange != null ? (int)/*64*/selectionRange.location : 0; } +/** + * Returns a point describing the location of the caret relative + * to the receiver. + * + * @return a point, the location of the caret + * + * @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.8 + */ public Point getCaretLocation() { checkWidget(); NSTextView widget = null; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/FontDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/FontDialog.java index b71a193269..b1ec63df48 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/FontDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/FontDialog.java @@ -99,6 +99,8 @@ void changeFont(int /*long*/ id, int /*long*/ sel, int /*long*/ arg0) { * * @return <code>true</code> if the dialog's effects selection controls * are visible and <code>false</code> otherwise + * + * @since 3.8 */ public boolean getEffectsVisible () { return effectsVisible; @@ -208,6 +210,8 @@ void setColor_forAttribute(int /*long*/ id, int /*long*/ sel, int /*long*/ color * </p> * * @param visible whether or not the dialog will show the effects selection controls + * + * @since 3.8 */ public void setEffectsVisible(boolean visible) { effectsVisible = visible; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ProgressBar.java index 92b7d4388e..68acfb6dfd 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ProgressBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ProgressBar.java @@ -288,7 +288,11 @@ public void setSelection (int value) { * <li>{@link SWT#ERROR}</li> * <li>{@link SWT#PAUSED}</li> * </ul> - * + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> + * * @param state the new state * * @exception SWTException <ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java index 6f3dd94b05..ad5506dd13 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java @@ -190,6 +190,38 @@ public void addModifyListener (ModifyListener listener) { addListener (SWT.Modify, typedListener); } +/** + * Adds a segment listener. + * <p> + * A <code>SegmentEvent</code> is sent whenever text content is being modified. The user can + * customize appearance of text by indicating certain characters to be inserted + * at certain text offsets. This may be used for bidi purposes, e.g. when + * adjacent segments of right-to-left text should not be reordered relative to + * each other. + * E.g., Multiple Java string literals in a right-to-left language + * should generally remain in logical order to each other, that is, the + * way they are stored. + * <br> + * After SegmentListener is added, user may call <code>setText(String)</code> + * for segments to take effect. + * </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 SegmentEvent + * @see SegmentListener + * @see #removeSegmentListener + * + * @since 3.8 + */ public void addSegmentListener (SegmentListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -204,8 +236,10 @@ public void addSegmentListener (SegmentListener listener) { * <p> * <code>widgetSelected</code> is not called for texts. * <code>widgetDefaultSelected</code> is typically called when ENTER is pressed in a single-line text, - * or when ENTER is pressed in a search text. If the receiver has the <code>SWT.SEARCH | SWT.CANCEL</code> style - * and the user cancels the search, the event object detail field contains the value <code>SWT.CANCEL</code>. + * or when ENTER is pressed in a search text. If the receiver has the <code>SWT.SEARCH | SWT.ICON_CANCEL</code> style + * and the user cancels the search, the event object detail field contains the value <code>SWT.ICON_CANCEL</code>. + * Likewise, if the receiver has the <code>SWT.ICON_SEARCH</code> style and the icon search is selected, the + * event object detail field contains the value <code>SWT.ICON_SEARCH</code>. * </p> * * @param listener the listener which should be notified when the control is selected by the user @@ -699,11 +733,8 @@ boolean acceptsFirstResponder(int /*long*/ id, int /*long*/ sel) { } /** - * Returns a point describing the receiver's location relative - * to its parent (or its display if its parent is null). - * <p> - * The location of the caret is returned. - * </p> + * Returns a point describing the location of the caret relative + * to the receiver. * * @return a point, the location of the caret * @@ -1464,6 +1495,30 @@ public void removeModifyListener (ModifyListener listener) { eventTable.unhook (SWT.Modify, listener); } +/** + * Removes the listener from the collection of listeners who will + * be notified when the receiver's text is modified. + * <p> + * After SegmentListener is removed, user may call <code>setText(String)</code> + * for segments to take effect. + * </p> + * + * @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 SegmentEvent + * @see SegmentListener + * @see #addSegmentListener + * + * @since 3.8 + */ public void removeSegmentListener (SegmentListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TrayItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TrayItem.java index d7e3bd8039..78f7dff12a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TrayItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TrayItem.java @@ -169,6 +169,19 @@ void destroyWidget () { releaseHandle (); } +/** + * Returns the receiver's highlight image if it has one, or null + * if it does not. + * + * @return the receiver's highlight image + * + * @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.8 + */ public Image getHighlightImage () { checkWidget(); return highlightImage; @@ -348,6 +361,21 @@ public void setImage (Image image) { updateImage (); } +/** + * Sets the receiver's highlight image. + * + * @param image the new highlight 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.8 + */ public void setHighlightImage (Image image) { checkWidget (); if (image != null && image.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java index 33681fb533..77d5d6b13d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java @@ -22,7 +22,7 @@ import org.eclipse.swt.events.*; * issues notification when pressed and released. * <dl> * <dt><b>Styles:</b></dt> - * <dd>ARROW, CHECK, PUSH, RADIO, TOGGLE, FLAT</dd> + * <dd>ARROW, CHECK, PUSH, RADIO, TOGGLE, FLAT, WRAP</dd> * <dd>UP, DOWN, LEFT, RIGHT, CENTER</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ColorDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ColorDialog.java index e602bc95af..aab32855cd 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ColorDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ColorDialog.java @@ -254,11 +254,15 @@ public void setRGB (RGB rgb) { } /** * Sets the receiver's list of custom colors to be the given array - * of <code>RGB</code>s. + * of <code>RGB</code>s, which may be null to let the platform select + * a default when open() is called. * - * @param rgbs the array of RGBs, which may be null to let the platform - * select a default when open() is called + * @param rgbs the array of RGBs, which may be null * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if an RGB in the rgbs array is null</li> + * </ul> + * * @since 3.8 */ public void setRGBs(RGB[] rgbs) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java index e9ee34b2df..5adc42c51e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java @@ -713,6 +713,19 @@ GdkColor getBackgroundColor () { return getBaseColor (); } +/** + * Returns a point describing the location of the caret relative + * to the receiver. + * + * @return a point, the location of the caret + * + * @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.8 + */ public Point getCaretLocation () { checkWidget (); if ((style & SWT.READ_ONLY) != 0) { @@ -732,6 +745,21 @@ public Point getCaretLocation () { return new Point (x, y); } +/** + * Returns the character position of the caret. + * <p> + * Indexing is zero based. + * </p> + * + * @return the position of the caret + * + * @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.8 + */ public int getCaretPosition () { checkWidget (); if ((style & SWT.READ_ONLY) != 0) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FontDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FontDialog.java index 3a60997973..81e2e1d8ea 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FontDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FontDialog.java @@ -91,6 +91,8 @@ public FontDialog (Shell parent, int style) { * * @return <code>true</code> if the dialog's effects selection controls * are visible and <code>false</code> otherwise + * + * @since 3.8 */ public boolean getEffectsVisible () { // The GTK FontDialog does not have any effects selection controls. @@ -230,6 +232,8 @@ public FontData open () { * </p> * * @param visible whether or not the dialog will show the effects selection controls + * + * @since 3.8 */ public void setEffectsVisible(boolean visible) { // The GTK FontDialog does not have any effects selection controls. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java index 811cecd5bf..ad416a46ce 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java @@ -256,7 +256,11 @@ public void setSelection (int value) { * <li>{@link SWT#ERROR}</li> * <li>{@link SWT#PAUSED}</li> * </ul> - * + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> + * * @param state the new state * * @exception SWTException <ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java index 75646e91cf..2e018aba52 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java @@ -262,6 +262,38 @@ public void addModifyListener (ModifyListener listener) { addListener (SWT.Modify, typedListener); } +/** + * Adds a segment listener. + * <p> + * A <code>SegmentEvent</code> is sent whenever text content is being modified. The user can + * customize appearance of text by indicating certain characters to be inserted + * at certain text offsets. This may be used for bidi purposes, e.g. when + * adjacent segments of right-to-left text should not be reordered relative to + * each other. + * E.g., Multiple Java string literals in a right-to-left language + * should generally remain in logical order to each other, that is, the + * way they are stored. + * <br> + * After SegmentListener is added, user may call <code>setText(String)</code> + * for segments to take effect. + * </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 SegmentEvent + * @see SegmentListener + * @see #removeSegmentListener + * + * @since 3.8 + */ public void addSegmentListener (SegmentListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -276,8 +308,10 @@ public void addSegmentListener (SegmentListener listener) { * <p> * <code>widgetSelected</code> is not called for texts. * <code>widgetDefaultSelected</code> is typically called when ENTER is pressed in a single-line text, - * or when ENTER is pressed in a search text. If the receiver has the <code>SWT.SEARCH | SWT.CANCEL</code> style - * and the user cancels the search, the event object detail field contains the value <code>SWT.CANCEL</code>. + * or when ENTER is pressed in a search text. If the receiver has the <code>SWT.SEARCH | SWT.ICON_CANCEL</code> style + * and the user cancels the search, the event object detail field contains the value <code>SWT.ICON_CANCEL</code>. + * Likewise, if the receiver has the <code>SWT.ICON_SEARCH</code> style and the icon search is selected, the + * event object detail field contains the value <code>SWT.ICON_SEARCH</code>. * </p> * * @param listener the listener which should be notified when the control is selected by the user @@ -759,11 +793,8 @@ public int getCaretLineNumber () { } /** - * Returns a point describing the receiver's location relative - * to its parent (or its display if its parent is null). - * <p> - * The location of the caret is returned. - * </p> + * Returns a point describing the location of the caret relative + * to the receiver. * * @return a point, the location of the caret * @@ -1907,6 +1938,30 @@ public void removeModifyListener (ModifyListener listener) { eventTable.unhook (SWT.Modify, listener); } +/** + * Removes the listener from the collection of listeners who will + * be notified when the receiver's text is modified. + * <p> + * After SegmentListener is removed, user may call <code>setText(String)</code> + * for segments to take effect. + * </p> + * + * @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 SegmentEvent + * @see SegmentListener + * @see #addSegmentListener + * + * @since 3.8 + */ public void removeSegmentListener (SegmentListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java index ae1774b853..2a82fb8e45 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java @@ -221,6 +221,19 @@ public Tray getParent () { return parent; } +/** + * Returns the receiver's highlight image if it has one, or null + * if it does not. + * + * @return the receiver's highlight image + * + * @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.8 + */ public Image getHighlightImage () { checkWidget (); return highlightImage; @@ -458,6 +471,21 @@ public void removeSelectionListener (SelectionListener listener) { eventTable.unhook (SWT.DefaultSelection, listener); } +/** + * Sets the receiver's highlight image. + * + * @param image the new highlight 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.8 + */ public void setHighlightImage (Image image) { checkWidget (); if (image != null && image.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT); |