Bug 468439 - Do the annual javadoc bash for 4.5
- javadoc changes.
Change-Id: I7407abcffd09e1e2e5f65aff39fdd4d6e4448ad6
Signed-off-by: Lakshmi Shanmugam <lshanmug@in.ibm.com>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
index 2cccef0..59065b8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Path.java
@@ -60,6 +60,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the path
*
@@ -97,6 +100,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the path
* @param path the path to make a copy
@@ -146,12 +152,15 @@
}
/**
- * Constructs a new Path with the specifed PathData.
+ * Constructs a new Path with the specified PathData.
* <p>
* This operation requires the operating system's advanced
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the path
* @param data the data for the path
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
index 9b1d49c..d3f7052 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Pattern.java
@@ -58,6 +58,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the pattern
* @param image the image that the pattern will draw
@@ -97,6 +100,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the pattern
* @param x1 the x coordinate of the starting corner of the gradient
@@ -132,6 +138,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the pattern
* @param x1 the x coordinate of the starting corner of the gradient
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
index 11b3711..1900f3f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cairo/org/eclipse/swt/graphics/Transform.java
@@ -54,6 +54,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the transform when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the Transform
*
@@ -81,6 +84,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the transform when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the Transform
* @param elements an array of floats that describe the transformation matrix
@@ -110,6 +116,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the transform when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the Transform
* @param m11 the first element of the first row of the matrix
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
index dc79e6d..387bcb9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java
@@ -17,7 +17,7 @@
* Instances of this class manage the operating system resources that
* implement SWT's RGB color model. To create a color you can either
* specify the individual color components as integers in the range
- * 0 to 255 or provide an instance of an <code>RGB</code>.
+ * 0 to 255 or provide an instance of an <code>RGB</code> or <code>RGBA</code>.
* <p>
* Application code must explicitly invoke the <code>Color.dispose()</code>
* method to release the operating system resources managed by each instance
@@ -25,6 +25,7 @@
* </p>
*
* @see RGB
+ * @see RGBA
* @see Device#getSystemColor
* @see <a href="http://www.eclipse.org/swt/snippets/#color">Color and RGB snippets</a>
* @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: PaintExample</a>
@@ -95,7 +96,7 @@
* @param red the amount of red in the color
* @param green the amount of green in the color
* @param blue the amount of blue in the color
- * @param alpha the amount of alpha in the color(Currently SWT honors extreme values for alpha ie. 0 or 255)
+ * @param alpha the amount of alpha in the color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -142,7 +143,7 @@
/**
* Constructs a new instance of this class given a device and an
- * <code>RGBA</code> describing the desired red, green, blue & alpah values.
+ * <code>RGBA</code> describing the desired red, green, blue & alpha values.
* On limited color devices, the color instance created by this call
* may not have the same RGBA values as the ones specified by the
* argument. The RGBA values on the returned instance will be the color
@@ -152,7 +153,7 @@
* </p>
*
* @param device the device on which to allocate the color
- * @param rgba the RGBA values of the desired color
+ * @param rgba the RGBA values of the desired color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -184,7 +185,7 @@
*
* @param device the device on which to allocate the color
* @param rgb the RGB values of the desired color
- * @param alpha the alpha value of the desired color(Currently SWT honors extreme values for alpha ie. 0 or 255)
+ * @param alpha the alpha value of the desired color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -231,13 +232,14 @@
}
/**
- * Returns the amount of alpha in the color, from 0 to 255.
+ * Returns the amount of alpha in the color, from 0 (transparent) to 255 (opaque).
*
* @return the alpha component of the color
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ * @since 3.104
*/
public int getAlpha() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
index 2991f9b..c3cfc20 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java
@@ -146,6 +146,7 @@
* @see SWT#CURSOR_IBEAM
* @see SWT#CURSOR_NO
* @see SWT#CURSOR_HAND
+ * @see #dispose()
*/
public Cursor(Device device, int style) {
super(device);
@@ -241,6 +242,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Cursor(Device device, ImageData source, ImageData mask, int hotspotX, int hotspotY) {
super(device);
@@ -341,6 +344,8 @@
* <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
* </ul>
*
+ * @see #dispose()
+ *
* @since 3.0
*/
public Cursor(Device device, ImageData source, int hotspotX, int hotspotY) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
index 4586247..20c7dd2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java
@@ -90,6 +90,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES - if a font could not be created from the given font data</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Font(Device device, FontData fd) {
super(device);
@@ -125,6 +127,8 @@
* <li>ERROR_NO_HANDLES - if a font could not be created from the given font data</li>
* </ul>
*
+ * @see #dispose()
+ *
* @since 2.1
*/
public Font(Device device, FontData[] fds) {
@@ -166,6 +170,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES - if a font could not be created from the given arguments</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Font(Device device, String name, int height, int style) {
super(device);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
index 55a5b53..104b876 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java
@@ -129,6 +129,7 @@
* <li>ERROR_NO_HANDLES if a handle could not be obtained for GC creation</li>
* <li>ERROR_THREAD_INVALID_ACCESS if not called from the thread that created the drawable</li>
* </ul>
+ * @see #dispose()
*/
public GC(Drawable drawable) {
this(drawable, 0);
@@ -158,7 +159,9 @@
* <li>ERROR_NO_HANDLES if a handle could not be obtained for GC creation</li>
* <li>ERROR_THREAD_INVALID_ACCESS if not called from the thread that created the drawable</li>
* </ul>
- *
+ *
+ * @see #dispose()
+ *
* @since 2.1.2
*/
public GC(Drawable drawable, int style) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
index 49114f8..3f39395 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
@@ -161,6 +161,9 @@
* and depth). For example, Windows 95, 98, and ME do not allow
* images larger than 16M.
* </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param width the width of the new image
@@ -173,6 +176,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, int width, int height) {
super(device);
@@ -198,6 +203,9 @@
* <dt><b>{@link SWT#IMAGE_GRAY}</b></dt>
* <dd>the result is a copy of srcImage which has a <em>gray scale</em> look</dd>
* </dl>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param srcImage the image to use as the source
@@ -216,6 +224,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, Image srcImage, int flag) {
super(device);
@@ -355,6 +365,9 @@
* and depth). For example, Windows 95, 98, and ME do not allow
* images larger than 16M.
* </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param bounds a rectangle specifying the image's width and height (must not be null)
@@ -367,6 +380,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, Rectangle bounds) {
super(device);
@@ -384,6 +399,9 @@
/**
* Constructs an instance of this class from the given
* <code>ImageData</code>.
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param data the image data to create the image from (must not be null)
@@ -398,6 +416,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, ImageData data) {
super(device);
@@ -422,6 +442,9 @@
* the source image should contain black wherever the icon is to be
* transparent.
* </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the icon
* @param source the color data for the icon
@@ -435,6 +458,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, ImageData source, ImageData mask) {
super(device);
@@ -486,6 +511,9 @@
* return image;
* }
* </pre>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param stream the input stream to load the image from
@@ -503,6 +531,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, InputStream stream) {
super(device);
@@ -525,6 +555,9 @@
* This constructor is provided for convenience when loading
* a single image only. If the specified file contains
* multiple images, only the first one will be used.
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param filename the name of the file to load the image from
@@ -542,6 +575,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, String filename) {
super(device);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
index e1bb639..43586e9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java
@@ -59,6 +59,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the path
*
@@ -100,6 +103,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the path
* @param path the path to make a copy
@@ -145,12 +151,15 @@
}
/**
- * Constructs a new Path with the specifed PathData.
+ * Constructs a new Path with the specified PathData.
* <p>
* This operation requires the operating system's advanced
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the path when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the path
* @param data the data for the path
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
index 3489ddd..04bb99b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java
@@ -48,6 +48,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the pattern
* @param image the image that the pattern will draw
@@ -90,6 +93,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the pattern
* @param x1 the x coordinate of the starting corner of the gradient
@@ -125,6 +131,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the pattern when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the pattern
* @param x1 the x coordinate of the starting corner of the gradient
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
index 15c0c39..dbe3ff2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java
@@ -45,10 +45,15 @@
/**
* Constructs a new empty region.
+ * <p>
+ * You must dispose the region when it is no longer required.
+ * </p>
*
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Region() {
this(null);
@@ -69,7 +74,7 @@
* <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
* </ul>
*
- * @see #dispose
+ * @see #dispose()
*
* @since 3.0
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
index cc9dcc5..30e7dd3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java
@@ -53,6 +53,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the transform when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the Transform
*
@@ -80,6 +83,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the transform when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the Transform
* @param elements an array of floats that describe the transformation matrix
@@ -109,6 +115,9 @@
* graphics subsystem which may not be available on some
* platforms.
* </p>
+ * <p>
+ * You must dispose the transform when it is no longer required.
+ * </p>
*
* @param device the device on which to allocate the Transform
* @param m11 the first element of the first row of the matrix
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 acd4043..c7d276b 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
@@ -886,6 +886,9 @@
* on Windows (starting with XP), GTK+ and OSX. On other platforms,
* a Button that has an image and text set into it will display the
* image or text that was set most recently.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
* @param string the new text
*
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 df6d352..52bb739 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
@@ -117,7 +117,10 @@
/**
* Adds the argument to the end of the receiver's list.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param string the new item
*
* @exception IllegalArgumentException <ul>
@@ -157,6 +160,9 @@
* Note: To add an item at the end of the list, use the
* result of calling <code>getItemCount()</code> as the
* index or use <code>add(String)</code>.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
*
* @param string the new item
@@ -1748,6 +1754,9 @@
* setting the text to a string containing line breaks or
* other special characters will probably cause it to
* display incorrectly.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
*
* @param string the new text
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
index aa28a44..366da3d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
@@ -4151,8 +4151,11 @@
/**
* Sets the base text direction (a.k.a. "paragraph direction") of the receiver,
- * which must be one of the constants <code>SWT.LEFT_TO_RIGHT</code> or
- * <code>SWT.RIGHT_TO_LEFT</code>.
+ * which must be one of the constants <code>SWT.LEFT_TO_RIGHT</code>,
+ * <code>SWT.RIGHT_TO_LEFT</code>, or a bitwise disjunction
+ * <code>SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT</code>. The latter stands for an
+ * "auto" direction, which implies that a control containing text derives the
+ * direction from the directionality of the first strong bidi character.
* <p>
* <code>setOrientation</code> would override this value with the text direction
* that is consistent with the new orientation.
@@ -4169,6 +4172,8 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
+ * @see SWT#LEFT_TO_RIGHT
+ * @see SWT#RIGHT_TO_LEFT
* @see SWT#FLIP_TEXT_DIRECTION
*
* @since 3.102
@@ -4410,6 +4415,10 @@
* argument, which is specified in display relative coordinates,
* to coordinates relative to the receiver.
* <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
* @param x the x coordinate to be translated
* @param y the y coordinate to be translated
* @return the translated coordinates
@@ -4431,6 +4440,10 @@
* argument, which is specified in display relative coordinates,
* to coordinates relative to the receiver.
* <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
* @param point the point to be translated (must not be null)
* @return the translated coordinates
*
@@ -4453,6 +4466,10 @@
* argument, which is specified in coordinates relative to
* the receiver, to display relative coordinates.
* <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
* @param x the x coordinate to be translated
* @param y the y coordinate to be translated
* @return the translated coordinates
@@ -4474,6 +4491,10 @@
* argument, which is specified in coordinates relative to
* the receiver, to display relative coordinates.
* <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
* @param point the point to be translated (must not be null)
* @return the translated coordinates
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Decorations.java
index 02d5199..fbfead2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Decorations.java
@@ -639,6 +639,10 @@
* Sets the receiver's text, which is the string that the
* window manager will typically display as the receiver's
* <em>title</em>, to the argument, which must not be null.
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
*
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Group.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Group.java
index 02f2a8b..4e5fe88 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Group.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Group.java
@@ -247,6 +247,9 @@
* platform specific manner. The mnemonic indicator character
* '&' can be escaped by doubling it in the string, causing
* a single '&' to be displayed.
+ * </p><p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Label.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Label.java
index eadd840..a48d22a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Label.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Label.java
@@ -503,6 +503,10 @@
* '&' can be escaped by doubling it in the string, causing
* a single '&' to be displayed.
* </p>
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
*
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/List.java
index 33ab4ba..e94fde4 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/List.java
@@ -102,7 +102,10 @@
/**
* Adds the argument to the end of the receiver's list.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param string the new item
*
* @exception IllegalArgumentException <ul>
@@ -135,6 +138,9 @@
* Note: To add an item at the end of the list, use the
* result of calling <code>getItemCount()</code> as the
* index or use <code>add(String)</code>.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
*
* @param string the new item
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
index 27a45f9..156f105 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java
@@ -1012,7 +1012,10 @@
/**
* Sets the text for multiple columns in the table.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param strings the array of new strings
*
* @exception IllegalArgumentException <ul>
@@ -1034,7 +1037,10 @@
/**
* Sets the receiver's text at a column
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param index the column index
* @param string the new text
*
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 7c5af67..226bdbd 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
@@ -2108,7 +2108,10 @@
* Sets the contents of the receiver to the given string. If the receiver has style
* SINGLE and the argument contains multiple lines of text, the result of this
* operation is undefined and may vary from platform to platform.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param string the new text
*
* @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
index 608b1c4..de0a34c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java
@@ -1107,6 +1107,9 @@
* manner. The mnemonic indicator character '&' can be
* escaped by doubling it in the string, causing a single
* '&' to be displayed.
+ * </p><p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
*
* @param string the new text
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
index 1186df7..880838f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java
@@ -1417,7 +1417,10 @@
/**
* Sets the text for multiple columns in the tree.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param strings the array of new strings
*
* @exception IllegalArgumentException <ul>
@@ -1441,7 +1444,10 @@
/**
* Sets the receiver's text at a column
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param index the column index
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java
index 2d6cfe6..fcebe63 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java
@@ -18,7 +18,7 @@
* Instances of this class manage the operating system resources that
* implement SWT's RGB color model. To create a color you can either
* specify the individual color components as integers in the range
- * 0 to 255 or provide an instance of an <code>RGB</code>.
+ * 0 to 255 or provide an instance of an <code>RGB</code> or <code>RGBA</code>.
* <p>
* Application code must explicitly invoke the <code>Color.dispose()</code>
* method to release the operating system resources managed by each instance
@@ -26,6 +26,7 @@
* </p>
*
* @see RGB
+ * @see RGBA
* @see Device#getSystemColor
* @see <a href="http://www.eclipse.org/swt/snippets/#color">Color and RGB snippets</a>
* @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: PaintExample</a>
@@ -97,7 +98,7 @@
* @param red the amount of red in the color
* @param green the amount of green in the color
* @param blue the amount of blue in the color
- * @param alpha the amount of alpha in the color(Currently SWT honors extreme values for alpha ie. 0 or 255)
+ * @param alpha the amount of alpha in the color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -144,7 +145,7 @@
/**
* Constructs a new instance of this class given a device and an
- * <code>RGBA</code> describing the desired red, green, blue & alpah values.
+ * <code>RGBA</code> describing the desired red, green, blue & alpha values.
* On limited color devices, the color instance created by this call
* may not have the same RGBA values as the ones specified by the
* argument. The RGBA values on the returned instance will be the color
@@ -154,7 +155,7 @@
* </p>
*
* @param device the device on which to allocate the color
- * @param rgba the RGBA values of the desired color
+ * @param rgba the RGBA values of the desired color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -186,7 +187,7 @@
*
* @param device the device on which to allocate the color
* @param rgb the RGB values of the desired color
- * @param alpha the alpha value of the desired color(Currently SWT honors extreme values for alpha ie. 0 or 255)
+ * @param alpha the alpha value of the desired color. Currently, SWT only honors extreme values for alpha i.e. 0 (transparent) or 255 (opaque).
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -243,13 +244,14 @@
}
/**
- * Returns the amount of alpha in the color, from 0 to 255.
+ * Returns the amount of alpha in the color, from 0 (transparent) to 255 (opaque).
*
* @return the alpha component of the color
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ * @since 3.104
*/
public int getAlpha() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
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 7dec05b..b112419 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
@@ -130,6 +130,7 @@
* @see SWT#CURSOR_IBEAM
* @see SWT#CURSOR_NO
* @see SWT#CURSOR_HAND
+ * @see #dispose()
*/
public Cursor(Device device, int style) {
super(device);
@@ -203,6 +204,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Cursor(Device device, ImageData source, ImageData mask, int hotspotX, int hotspotY) {
super(device);
@@ -285,6 +288,8 @@
* <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li>
* </ul>
*
+ * @see #dispose()
+ *
* @since 3.0
*/
public Cursor(Device device, ImageData source, int hotspotX, int hotspotY) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
index 001fcd8..e0c0449 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java
@@ -67,6 +67,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES - if a font could not be created from the given font data</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Font(Device device, FontData fd) {
super(device);
@@ -95,7 +97,9 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES - if a font could not be created from the given font data</li>
* </ul>
- *
+ *
+ * @see #dispose()
+ *
* @since 2.1
*/
public Font(Device device, FontData[] fds) {
@@ -131,6 +135,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES - if a font could not be created from the given arguments</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Font(Device device, String name, int height, int style) {
super(device);
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 6fe597f..4675ea8 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
@@ -120,6 +120,7 @@
* <li>ERROR_NO_HANDLES if a handle could not be obtained for GC creation</li>
* <li>ERROR_THREAD_INVALID_ACCESS if not called from the thread that created the drawable</li>
* </ul>
+ * @see #dispose()
*/
public GC(Drawable drawable) {
this(drawable, 0);
@@ -150,6 +151,8 @@
* <li>ERROR_THREAD_INVALID_ACCESS if not called from the thread that created the drawable</li>
* </ul>
*
+ * @see #dispose()
+ *
* @since 2.1.2
*/
public GC(Drawable drawable, int style) {
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 e4c5450..217b1ad 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
@@ -197,6 +197,9 @@
* and depth). For example, Windows 95, 98, and ME do not allow
* images larger than 16M.
* </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param width the width of the new image
@@ -209,6 +212,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, int width, int height) {
super(device);
@@ -228,6 +233,9 @@
* <dt><b>{@link SWT#IMAGE_GRAY}</b></dt>
* <dd>the result is a copy of srcImage which has a <em>gray scale</em> look</dd>
* </dl>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param srcImage the image to use as the source
@@ -246,6 +254,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, Image srcImage, int flag) {
super(device);
@@ -511,6 +521,9 @@
* and depth). For example, Windows 95, 98, and ME do not allow
* images larger than 16M.
* </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param bounds a rectangle specifying the image's width and height (must not be null)
@@ -523,6 +536,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, Rectangle bounds) {
super(device);
@@ -534,6 +549,9 @@
/**
* Constructs an instance of this class from the given
* <code>ImageData</code>.
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param data the image data to create the image from (must not be null)
@@ -548,6 +566,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, ImageData data) {
super(device);
@@ -566,6 +586,9 @@
* the source image should contain black wherever the icon is to be
* transparent.
* </p>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the icon
* @param source the color data for the icon
@@ -579,6 +602,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, ImageData source, ImageData mask) {
super(device);
@@ -625,6 +650,9 @@
* return image;
* }
* </pre>
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param stream the input stream to load the image from
@@ -642,6 +670,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, InputStream stream) {
super(device);
@@ -658,6 +688,9 @@
* This constructor is provided for convenience when loading
* a single image only. If the specified file contains
* multiple images, only the first one will be used.
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
*
* @param device the device on which to create the image
* @param filename the name of the file to load the image from
@@ -675,6 +708,8 @@
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Image(Device device, String filename) {
super(device);
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 2288eda..52a582b 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
@@ -45,10 +45,15 @@
/**
* Constructs a new empty region.
- *
+ * <p>
+ * You must dispose the region when it is no longer required.
+ * </p>
+ *
* @exception SWTError <ul>
* <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
* </ul>
+ *
+ * @see #dispose()
*/
public Region() {
this(null);
@@ -69,7 +74,7 @@
* <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li>
* </ul>
*
- * @see #dispose
+ * @see #dispose()
*
* @since 3.0
*/
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 77d4253..7fef861 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
@@ -1092,6 +1092,9 @@
* on Windows (starting with XP), GTK+ and OSX. On other platforms,
* a Button that has an image and text set into it will display the
* image or text that was set most recently.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
* @param string the new text
*
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 7edd29d..be06855 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
@@ -116,7 +116,10 @@
/**
* Adds the argument to the end of the receiver's list.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param string the new item
*
* @exception IllegalArgumentException <ul>
@@ -142,6 +145,9 @@
* Note: To add an item at the end of the list, use the
* result of calling <code>getItemCount()</code> as the
* index or use <code>add(String)</code>.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
*
* @param string the new item
@@ -2152,6 +2158,9 @@
* setting the text to a string containing line breaks or
* other special characters will probably cause it to
* display incorrectly.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
*
* @param string the new text
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java
index 8414438..8f5fe71 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java
@@ -1383,6 +1383,10 @@
* argument, which is specified in display relative coordinates,
* to coordinates relative to the receiver.
* <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
* @param x the x coordinate to be translated
* @param y the y coordinate to be translated
* @return the translated coordinates
@@ -1410,6 +1414,10 @@
* argument, which is specified in display relative coordinates,
* to coordinates relative to the receiver.
* <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
* @param point the point to be translated (must not be null)
* @return the translated coordinates
*
@@ -1432,6 +1440,10 @@
* argument, which is specified in coordinates relative to
* the receiver, to display relative coordinates.
* <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
* @param x the x coordinate to be translated
* @param y the y coordinate to be translated
* @return the translated coordinates
@@ -1459,6 +1471,10 @@
* argument, which is specified in coordinates relative to
* the receiver, to display relative coordinates.
* <p>
+ * NOTE: To properly map a rectangle or a corner of a rectangle on a right-to-left platform, use
+ * {@link Display#map(Control, Control, Rectangle)}.
+ * </p>
+ *
* @param point the point to be translated (must not be null)
* @return the translated coordinates
*
@@ -4751,8 +4767,11 @@
/**
* Sets the base text direction (a.k.a. "paragraph direction") of the receiver,
- * which must be one of the constants <code>SWT.LEFT_TO_RIGHT</code> or
- * <code>SWT.RIGHT_TO_LEFT</code>.
+ * which must be one of the constants <code>SWT.LEFT_TO_RIGHT</code>,
+ * <code>SWT.RIGHT_TO_LEFT</code>, or a bitwise disjunction
+ * <code>SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT</code>. The latter stands for an
+ * "auto" direction, which implies that a control containing text derives the
+ * direction from the directionality of the first strong bidi character.
* <p>
* <code>setOrientation</code> would override this value with the text direction
* that is consistent with the new orientation.
@@ -4769,6 +4788,8 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
+ * @see SWT#LEFT_TO_RIGHT
+ * @see SWT#RIGHT_TO_LEFT
* @see SWT#FLIP_TEXT_DIRECTION
*
* @since 3.102
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java
index 1d0e384..c77e7aa 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java
@@ -725,6 +725,10 @@
* Sets the receiver's text, which is the string that the
* window manager will typically display as the receiver's
* <em>title</em>, to the argument, which must not be null.
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
*
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java
index fec04ab..255119a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java
@@ -563,6 +563,14 @@
* For filters with multiple extensions, use semicolon as
* a separator, e.g. "*.jpg;*.png".
* </p>
+ * <p>
+ * Note: On Mac, setting the file extension filter affects how
+ * app bundles are treated by the dialog. When a filter extension
+ * having the app extension (.app) is selected, bundles are treated
+ * as files. For all other extension filters, bundles are treated
+ * as directories. When no filter extension is set, bundles are
+ * treated as files.
+ * </p>
*
* @param extensions the file extension filter
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
index f0f59cd..1e25600 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Group.java
@@ -334,6 +334,9 @@
* platform specific manner. The mnemonic indicator character
* '&' can be escaped by doubling it in the string, causing
* a single '&' to be displayed.
+ * </p><p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Label.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Label.java
index 3d05a18..c971970 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Label.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Label.java
@@ -612,7 +612,11 @@
* '&' can be escaped by doubling it in the string, causing
* a single '&' to be displayed.
* </p>
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
+ *
* @param string the new text
*
* @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java
index effeb89..9a45a90 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java
@@ -79,6 +79,10 @@
/**
* Adds the argument to the end of the receiver's list.
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
*
* @param string the new item
*
@@ -110,6 +114,9 @@
* Note: To add an item at the end of the list, use the
* result of calling <code>getItemCount()</code> as the
* index or use <code>add(String)</code>.
+ * </p><p>
+ * Also note, if control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
*
* @param string the new item
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java
index d39fe47..c854070 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java
@@ -599,9 +599,10 @@
* Returns the receiver's shell. For all controls other than
* shells, this simply returns the control's nearest ancestor
* shell. Shells return themselves, even if they are children
- * of other shells.
+ * of other shells. Returns null if receiver or its ancestor
+ * is the application menubar.
*
- * @return the receiver's shell
+ * @return the receiver's shell or null
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
index 56a6ad6..60856c8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java
@@ -2141,6 +2141,11 @@
* default shape of the shell is restored. The shell
* must be created with the style SWT.NO_TRIM in order
* to specify a region.
+ * <p>
+ * NOTE: This method also sets the size of the shell. Clients should
+ * not call {@link #setSize} or {@link #setBounds} on this shell.
+ * Furthermore, the passed region should not be modified any more.
+ * </p>
*
* @param region the region that defines the shape of the shell (or null)
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java
index 22fd786..63f4964 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java
@@ -1145,7 +1145,10 @@
/**
* Sets the receiver's text at a column
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param index the column index
* @param string the new text
*
@@ -1177,7 +1180,10 @@
/**
* Sets the text for multiple columns in the table.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param strings the array of new strings
*
* @exception IllegalArgumentException <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 3c05eb5..ec609a2 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
@@ -2463,6 +2463,10 @@
* Sets the contents of the receiver to the given string. If the receiver has style
* SINGLE and the argument contains multiple lines of text, the result of this
* operation is undefined and may vary from platform to platform.
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
*
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
index 7ecf9cc..e64ecc9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java
@@ -1110,6 +1110,9 @@
* manner. The mnemonic indicator character '&' can be
* escaped by doubling it in the string, causing a single
* '&' to be displayed.
+ * </p><p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
* </p>
*
* @param string the new text
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java
index 824f2f5..41d75b4 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java
@@ -1513,7 +1513,10 @@
/**
* Sets the receiver's text at a column
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param index the column index
* @param string the new text
*
@@ -1547,7 +1550,10 @@
/**
* Sets the text for multiple columns in the tree.
- *
+ * <p>
+ * Note: If control characters like '\n', '\t' etc. are used
+ * in the string, then the behavior is platform dependent.
+ * </p>
* @param strings the array of new strings
*
* @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Menu.java
index d877a39..967f18c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Menu.java
@@ -610,6 +610,7 @@
redraw ();
}
+@Override
void destroyWidget () {
MenuItem cascade = this.cascade;
long /*int*/ hMenu = handle, hCB = hwndCB;
@@ -913,6 +914,7 @@
return OS.GetMenuItemCount (handle);
}
+@Override
String getNameText () {
String result = "";
MenuItem [] items = getItems ();
@@ -998,9 +1000,10 @@
* Returns the receiver's shell. For all controls other than
* shells, this simply returns the control's nearest ancestor
* shell. Shells return themselves, even if they are children
- * of other shells.
+ * of other shells. Returns null if receiver or its ancestor
+ * is the application menubar.
*
- * @return the receiver's shell
+ * @return the receiver's shell or null
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -1171,12 +1174,14 @@
}
}
+@Override
void releaseHandle () {
super.releaseHandle ();
handle = hwndCB = 0;
cascade = null;
}
+@Override
void releaseChildren (boolean destroy) {
MenuItem [] items = getItems ();
for (int i=0; i<items.length; i++) {
@@ -1192,6 +1197,7 @@
super.releaseChildren (destroy);
}
+@Override
void releaseParent () {
super.releaseParent ();
if ((style & SWT.BAR) != 0) {
@@ -1206,6 +1212,7 @@
}
}
+@Override
void releaseWidget () {
super.releaseWidget ();
backgroundImage = null;
@@ -1271,6 +1278,7 @@
eventTable.unhook (SWT.Show, listener);
}
+@Override
void reskinChildren (int flags) {
MenuItem [] items = getItems ();
for (int i=0; i<items.length; i++) {