Bug 380560 - Do the annual javadoc/copyright bash for 3.8 and 4.2
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 256c9f6..c03fa48 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 @@
* 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 0c73f60..7482cec 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 @@
*
* @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 c9f0263..02a983f 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 @@
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 b71a193..b1ec63d 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 @@
*
* @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 @@
* </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 92b7d43..68acfb6 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 @@
* <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 6f3dd94..ad5506d 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 @@
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 @@
* <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 @@
}
/**
- * 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 @@
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 d7e3bd8..78f7dff 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 @@
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 @@
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 33681fb..77d5d6b 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 @@
* 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 e602bc9..aab3285 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 @@
}
/**
* 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 e9ee34b..5adc42c 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 @@
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 @@
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 3a60997..81e2e1d 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 @@
*
* @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 @@
* </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 811cecd..ad416a4 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 @@
* <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 75646e9..2e018ab 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 @@
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 @@
* <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 @@
}
/**
- * 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 @@
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 ae1774b..2a82fb8 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 @@
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 @@
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);
