After initial JavadocBash for 3.1 RC4
diff --git a/bundles/org.eclipse.swt/Eclipse SWT AWT/emulated/org/eclipse/swt/awt/SWT_AWT.java b/bundles/org.eclipse.swt/Eclipse SWT AWT/emulated/org/eclipse/swt/awt/SWT_AWT.java
index 5dc18d8..5efecd4 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT AWT/emulated/org/eclipse/swt/awt/SWT_AWT.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT AWT/emulated/org/eclipse/swt/awt/SWT_AWT.java
@@ -75,6 +75,7 @@
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if the display is null</li>
* <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent's peer is not created</li>
* </ul>
*
* @since 3.0
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java
index 5d4d2a8..4f0b314 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java
@@ -94,7 +94,7 @@
* <li>ERROR_NO_HANDLES if a handle could not be obtained for browser creation</li>
* </ul>
*
- * @see #getStyle
+ * @see Widget#getStyle
*
* @since 3.0
*/
@@ -377,7 +377,7 @@
/**
* Adds the listener to the collection of listeners who will be
- * notified when the current location is changed or about to be changed.
+ * notified when the current location has changed or is about to change.
* <p>
* This notification typically occurs when the application navigates
* to a new location with {@link #setUrl(String)} or when the user
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java
index 94b827e..90568f6 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java
@@ -107,7 +107,7 @@
* <li>ERROR_NO_HANDLES if a handle could not be obtained for browser creation</li>
* </ul>
*
- * @see #getStyle
+ * @see Widget#getStyle
*
* @since 3.0
*/
@@ -376,7 +376,7 @@
/**
* Adds the listener to the collection of listeners who will be
- * notified when the current location is changed or about to be changed.
+ * notified when the current location has changed or is about to change.
* <p>
* This notification typically occurs when the application navigates
* to a new location with {@link #setUrl(String)} or when the user
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java
index 8f2e79d..c48e3de 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java
@@ -81,7 +81,7 @@
* <li>ERROR_NO_HANDLES if a handle could not be obtained for browser creation</li>
* </ul>
*
- * @see #getStyle
+ * @see Widget#getStyle
*
* @since 3.0
*/
@@ -208,7 +208,7 @@
/**
* Adds the listener to the collection of listeners who will be
- * notified when the current location is changed or about to be changed.
+ * notified when the current location has changed or is about to change.
* <p>
* This notification typically occurs when the application navigates
* to a new location with {@link #setUrl(String)} or when the user
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/ByteArrayTransfer.java
index 078418e..144be0a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -25,7 +25,7 @@
* <code>byte[]</code>, you should sub-class <code>Transfer</code> directly
* and do your own mapping to a platform data type.</p>
*
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
* data defined by the class <code>MyType</code>.</p>
*
* <pre><code>
@@ -36,7 +36,7 @@
* }
* </code></pre>
*
- * <code><pre>
+ * <pre><code>
* public class MyTypeTransfer extends ByteArrayTransfer {
*
* private static final String MYTYPENAME = "my_type_name";
@@ -113,6 +113,7 @@
* return new int[] {MYTYPEID};
* }
* }
+ * </code></pre>
*/
public abstract class ByteArrayTransfer extends Transfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DropTarget.java
index c93c418..2e353e0 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DropTarget.java
@@ -132,7 +132,7 @@
* <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
* recoverable error, but can not be changed due to backward compatability.</p>
*
- * @see DropTarget#dispose
+ * @see Widget#dispose
* @see DropTarget#checkSubclass
* @see DND#DROP_NONE
* @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
index 2c9b92e..b115961 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TextTransfer.java
@@ -16,8 +16,7 @@
/**
* The class <code>TextTransfer</code> provides a platform specific mechanism
* for converting plain text represented as a java <code>String</code>
- * to a platform specific representation of the data and vice versa. See
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
*
* <p>An example of a java <code>String</code> containing plain text is shown
* below:</p>
@@ -25,6 +24,8 @@
* <code><pre>
* String textData = "Hello World";
* </code></pre>
+ *
+ * @see Transfer
*/
public class TextTransfer extends ByteArrayTransfer {
@@ -48,11 +49,12 @@
/**
* This implementation of <code>javaToNative</code> converts plain text
* represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
*
* @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- * object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ * will be filled in on return with the platform specific format of the data
+ *
+ * @see Transfer#javaToNative
*/
public void javaToNative (Object object, TransferData transferData) {
if (!checkText(object) || !isSupportedType(transferData)) {
@@ -99,12 +101,11 @@
/**
* This implementation of <code>nativeToJava</code> converts a platform specific
* representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
*
- * @param transferData the platform specific representation of the data to be
- * been converted
- * @return a java <code>String</code> containing text if the
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ *
+ * @see Transfer#nativeToJava
*/
public Object nativeToJava(TransferData transferData){
if (!isSupportedType(transferData) || transferData.data == null) return null;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Transfer.java
index d4c9069..c93d6a5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/Transfer.java
@@ -38,7 +38,8 @@
/**
* Returns true if the <code>TransferData</code> data type can be converted
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
*
* @param transferData a platform specific description of a data type; only the data
* type fields of the <code>TransferData</code> object need to be filled in
@@ -92,6 +93,10 @@
*
* @param transferData an empty TransferData object; this object will be
* filled in on return with the platform specific representation of the data
+ *
+ * @exception org.eclipse.swt.SWTException <ul>
+ * <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
*/
abstract protected void javaToNative (Object object, TransferData transferData);
@@ -102,8 +107,9 @@
* converted
*
* @return a java representation of the converted data if the conversion was
- * successful; otherwise null. The type of Object that is returned is dependant
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null. If transferData is <code>null</code> then
+ * <code>null</code> is returned. The type of Object that is returned is
+ * dependant on the <code>Transfer</code> subclass.
*/
abstract protected Object nativeToJava(TransferData transferData);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/ByteArrayTransfer.java
index 11ba0a7..3354598 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -25,7 +25,7 @@
* <code>byte[]</code>, you should sub-class <code>Transfer</code> directly
* and do your own mapping to a platform data type.</p>
*
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
* data defined by the class <code>MyType</code>.</p>
*
* <pre><code>
@@ -36,7 +36,7 @@
* }
* </code></pre>
*
- * <code><pre>
+ * <pre><code>
* public class MyTypeTransfer extends ByteArrayTransfer {
*
* private static final String MYTYPENAME = "my_type_name";
@@ -113,6 +113,7 @@
* return new int[] {MYTYPEID};
* }
* }
+ * </code></pre>
*/
public abstract class ByteArrayTransfer extends Transfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/DropTarget.java
index be28cad..2f65e4d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/DropTarget.java
@@ -99,7 +99,7 @@
* <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
* recoverable error, but can not be changed due to backward compatability.</p>
*
- * @see DropTarget#dispose
+ * @see Widget#dispose
* @see DropTarget#checkSubclass
* @see DND#DROP_NONE
* @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
index 4f3c06d..c80269c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TextTransfer.java
@@ -14,8 +14,7 @@
/**
* The class <code>TextTransfer</code> provides a platform specific mechanism
* for converting plain text represented as a java <code>String</code>
- * to a platform specific representation of the data and vice versa. See
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
*
* <p>An example of a java <code>String</code> containing plain text is shown
* below:</p>
@@ -23,6 +22,8 @@
* <code><pre>
* String textData = "Hello World";
* </code></pre>
+ *
+ * @see Transfer
*/
public class TextTransfer extends ByteArrayTransfer {
@@ -47,23 +48,23 @@
/**
* This implementation of <code>javaToNative</code> converts plain text
* represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
*
* @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- * object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ * will be filled in on return with the platform specific format of the data
+ *
+ * @see Transfer#javaToNative
*/
public void javaToNative (Object object, TransferData transferData){
}
/**
* This implementation of <code>nativeToJava</code> converts a platform specific
* representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
*
- * @param transferData the platform specific representation of the data to be
- * been converted
- * @return a java <code>String</code> containing text if the
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ *
+ * @see Transfer#nativeToJava
*/
public Object nativeToJava(TransferData transferData){
return null;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Transfer.java
index 961deb1..16682cf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Transfer.java
@@ -38,7 +38,8 @@
/**
* Returns true if the <code>TransferData</code> data type can be converted
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
*
* @param transferData a platform specific description of a data type; only the data
* type fields of the <code>TransferData</code> object need to be filled in
@@ -92,6 +93,10 @@
*
* @param transferData an empty TransferData object; this object will be
* filled in on return with the platform specific representation of the data
+ *
+ * @exception org.eclipse.swt.SWTException <ul>
+ * <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
*/
abstract protected void javaToNative (Object object, TransferData transferData);
@@ -102,8 +107,9 @@
* converted
*
* @return a java representation of the converted data if the conversion was
- * successful; otherwise null. The type of Object that is returned is dependant
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null. If transferData is <code>null</code> then
+ * <code>null</code> is returned. The type of Object that is returned is
+ * dependant on the <code>Transfer</code> subclass.
*/
abstract protected Object nativeToJava(TransferData transferData);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/ByteArrayTransfer.java
index a37fb1f..c79080c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -26,7 +26,7 @@
* <code>byte[]</code>, you should sub-class <code>Transfer</code> directly
* and do your own mapping to a platform data type.</p>
*
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
* data defined by the class <code>MyType</code>.</p>
*
* <pre><code>
@@ -37,7 +37,7 @@
* }
* </code></pre>
*
- * <code><pre>
+ * <pre><code>
* public class MyTypeTransfer extends ByteArrayTransfer {
*
* private static final String MYTYPENAME = "my_type_name";
@@ -114,6 +114,7 @@
* return new int[] {MYTYPEID};
* }
* }
+ * </code></pre>
*/
public abstract class ByteArrayTransfer extends Transfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/DropTarget.java
index 9ef36ed..f4ee0e5 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/DropTarget.java
@@ -135,6 +135,7 @@
* <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
* recoverable error, but can not be changed due to backward compatability.</p>
*
+ * @see Widget#dispose
* @see DropTarget#checkSubclass
* @see DND#DROP_NONE
* @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
index 378566a..c0e4e43 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TextTransfer.java
@@ -16,8 +16,7 @@
/**
* The class <code>TextTransfer</code> provides a platform specific mechanism
* for converting plain text represented as a java <code>String</code>
- * to a platform specific representation of the data and vice versa. See
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
*
* <p>An example of a java <code>String</code> containing plain text is shown
* below:</p>
@@ -25,6 +24,8 @@
* <code><pre>
* String textData = "Hello World";
* </code></pre>
+ *
+ * @see Transfer
*/
public class TextTransfer extends ByteArrayTransfer {
@@ -48,11 +49,12 @@
/**
* This implementation of <code>javaToNative</code> converts plain text
* represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
*
* @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- * object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ * will be filled in on return with the platform specific format of the data
+ *
+ * @see Transfer#javaToNative
*/
public void javaToNative (Object object, TransferData transferData) {
transferData.result = 0;
@@ -89,12 +91,11 @@
/**
* This implementation of <code>nativeToJava</code> converts a platform specific
* representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
*
- * @param transferData the platform specific representation of the data to be
- * been converted
- * @return a java <code>String</code> containing text if the
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ *
+ * @see Transfer#nativeToJava
*/
public Object nativeToJava(TransferData transferData){
if (!isSupportedType(transferData) || transferData.pValue == 0) return null;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Transfer.java
index 8beb3ed..b0b8afc 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/Transfer.java
@@ -41,7 +41,8 @@
/**
* Returns true if the <code>TransferData</code> data type can be converted
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
*
* @param transferData a platform specific description of a data type; only the data
* type fields of the <code>TransferData</code> object need to be filled in
@@ -95,6 +96,10 @@
*
* @param transferData an empty TransferData object; this object will be
* filled in on return with the platform specific representation of the data
+ *
+ * @exception org.eclipse.swt.SWTException <ul>
+ * <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
*/
abstract protected void javaToNative (Object object, TransferData transferData);
@@ -105,8 +110,9 @@
* converted
*
* @return a java representation of the converted data if the conversion was
- * successful; otherwise null. The type of Object that is returned is dependant
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null. If transferData is <code>null</code> then
+ * <code>null</code> is returned. The type of Object that is returned is
+ * dependant on the <code>Transfer</code> subclass.
*/
abstract protected Object nativeToJava(TransferData transferData);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/ByteArrayTransfer.java
index aba2149..df11116 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -26,7 +26,7 @@
* <code>byte[]</code>, you should sub-class <code>Transfer</code> directly
* and do your own mapping to a platform data type.</p>
*
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
* data defined by the class <code>MyType</code>.</p>
*
* <pre><code>
@@ -37,7 +37,7 @@
* }
* </code></pre>
*
- * <code><pre>
+ * <pre><code>
* public class MyTypeTransfer extends ByteArrayTransfer {
*
* private static final String MYTYPENAME = "my_type_name";
@@ -114,6 +114,7 @@
* return new int[] {MYTYPEID};
* }
* }
+ * </code></pre>
*/
public abstract class ByteArrayTransfer extends Transfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/DropTarget.java
index 784c3d8..d3eb670 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/DropTarget.java
@@ -142,7 +142,7 @@
* <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
* recoverable error, but can not be changed due to backward compatability.</p>
*
- * @see DropTarget#dispose
+ * @see Widget#dispose
* @see DropTarget#checkSubclass
* @see DND#DROP_NONE
* @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
index c36e8f5..b88d646 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TextTransfer.java
@@ -18,8 +18,7 @@
/**
* The class <code>TextTransfer</code> provides a platform specific mechanism
* for converting plain text represented as a java <code>String</code>
- * to a platform specific representation of the data and vice versa. See
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
*
* <p>An example of a java <code>String</code> containing plain text is shown
* below:</p>
@@ -27,6 +26,8 @@
* <code><pre>
* String textData = "Hello World";
* </code></pre>
+ *
+ * @see Transfer
*/
public class TextTransfer extends ByteArrayTransfer {
@@ -50,11 +51,12 @@
/**
* This implementation of <code>javaToNative</code> converts plain text
* represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
*
* @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- * object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ * will be filled in on return with the platform specific format of the data
+ *
+ * @see Transfer#javaToNative
*/
public void javaToNative (Object object, TransferData transferData) {
transferData.result = 0;
@@ -102,12 +104,11 @@
/**
* This implementation of <code>nativeToJava</code> converts a platform specific
* representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
*
- * @param transferData the platform specific representation of the data to be
- * been converted
- * @return a java <code>String</code> containing text if the
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ *
+ * @see Transfer#nativeToJava
*/
public Object nativeToJava(TransferData transferData){
if (!isSupportedType(transferData) || transferData.pValue == 0) return null;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Transfer.java
index 28b4f23..0df0b58 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/Transfer.java
@@ -42,7 +42,8 @@
/**
* Returns true if the <code>TransferData</code> data type can be converted
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
*
* @param transferData a platform specific description of a data type; only the data
* type fields of the <code>TransferData</code> object need to be filled in
@@ -96,6 +97,10 @@
*
* @param transferData an empty TransferData object; this object will be
* filled in on return with the platform specific representation of the data
+ *
+ * @exception org.eclipse.swt.SWTException <ul>
+ * <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
*/
abstract protected void javaToNative (Object object, TransferData transferData);
@@ -106,8 +111,9 @@
* converted
*
* @return a java representation of the converted data if the conversion was
- * successful; otherwise null. The type of Object that is returned is dependant
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null. If transferData is <code>null</code> then
+ * <code>null</code> is returned. The type of Object that is returned is
+ * dependant on the <code>Transfer</code> subclass.
*/
abstract protected Object nativeToJava(TransferData transferData);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
index 24a2d0c..73e22f2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/ByteArrayTransfer.java
@@ -27,7 +27,7 @@
* <code>byte[]</code>, you should sub-class <code>Transfer</code> directly
* and do your own mapping to a platform data type.</p>
*
- * <p>The following snippet shows a sublcass of ByteArrayTransfer that transfers
+ * <p>The following snippet shows a subclass of ByteArrayTransfer that transfers
* data defined by the class <code>MyType</code>.</p>
*
* <pre><code>
@@ -38,7 +38,7 @@
* }
* </code></pre>
*
- * <code><pre>
+ * <pre><code>
* public class MyTypeTransfer extends ByteArrayTransfer {
*
* private static final String MYTYPENAME = "my_type_name";
@@ -115,6 +115,7 @@
* return new int[] {MYTYPEID};
* }
* }
+ * </code></pre>
*/
public abstract class ByteArrayTransfer extends Transfer {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
index e492b9d..8c2d3c6 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/DropTarget.java
@@ -99,7 +99,7 @@
* <p>NOTE: ERROR_CANNOT_INIT_DROP should be an SWTException, since it is a
* recoverable error, but can not be changed due to backward compatability.</p>
*
- * @see DropTarget#dispose
+ * @see Widget#dispose
* @see DropTarget#checkSubclass
* @see DND#DROP_NONE
* @see DND#DROP_COPY
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
index 9e3ff38..4c52fe3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TextTransfer.java
@@ -17,8 +17,7 @@
/**
* The class <code>TextTransfer</code> provides a platform specific mechanism
* for converting plain text represented as a java <code>String</code>
- * to a platform specific representation of the data and vice versa. See
- * <code>Transfer</code> for additional information.
+ * to a platform specific representation of the data and vice versa.
*
* <p>An example of a java <code>String</code> containing plain text is shown
* below:</p>
@@ -26,6 +25,8 @@
* <code><pre>
* String textData = "Hello World";
* </code></pre>
+ *
+ * @see Transfer
*/
public class TextTransfer extends ByteArrayTransfer {
@@ -46,11 +47,12 @@
/**
* This implementation of <code>javaToNative</code> converts plain text
* represented by a java <code>String</code> to a platform specific representation.
- * For additional information see <code>Transfer#javaToNative</code>.
*
* @param object a java <code>String</code> containing text
- * @param transferData an empty <code>TransferData</code> object; this
- * object will be filled in on return with the platform specific format of the data
+ * @param transferData an empty <code>TransferData</code> object; this object
+ * will be filled in on return with the platform specific format of the data
+ *
+ * @see Transfer#javaToNative
*/
public void javaToNative (Object object, TransferData transferData){
if (!checkText(object) || !isSupportedType(transferData)) {
@@ -63,12 +65,11 @@
/**
* This implementation of <code>nativeToJava</code> converts a platform specific
* representation of plain text to a java <code>String</code>.
- * For additional information see <code>Transfer#nativeToJava</code>.
*
- * @param transferData the platform specific representation of the data to be
- * been converted
- * @return a java <code>String</code> containing text if the
- * conversion was successful; otherwise null
+ * @param transferData the platform specific representation of the data to be converted
+ * @return a java <code>String</code> containing text if the conversion was successful; otherwise null
+ *
+ * @see Transfer#nativeToJava
*/
public Object nativeToJava(TransferData transferData){
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Transfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Transfer.java
index 3202f56..35a7eba 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Transfer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/Transfer.java
@@ -37,7 +37,8 @@
abstract public TransferData[] getSupportedTypes();
/**
* Returns true if the <code>TransferData</code> data type can be converted
- * using this transfer agent.
+ * using this transfer agent, or false otherwise (including if transferData is
+ * <code>null</code>).
*
* @param transferData a platform specific description of a data type; only the data
* type fields of the <code>TransferData</code> object need to be filled in
@@ -91,6 +92,10 @@
*
* @param transferData an empty TransferData object; this object will be
* filled in on return with the platform specific representation of the data
+ *
+ * @exception org.eclipse.swt.SWTException <ul>
+ * <li>ERROR_INVALID_DATA - if object does not contain data in a valid format or is <code>null</code></li>
+ * </ul>
*/
abstract protected void javaToNative (Object object, TransferData transferData);
@@ -101,8 +106,9 @@
* converted
*
* @return a java representation of the converted data if the conversion was
- * successful; otherwise null. The type of Object that is returned is dependant
- * on the <code>Transfer</code> subclass
+ * successful; otherwise null. If transferData is <code>null</code> then
+ * <code>null</code> is returned. The type of Object that is returned is
+ * dependant on the <code>Transfer</code> subclass.
*/
abstract protected Object nativeToJava(TransferData transferData);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
index 5f4759e..1d5726f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/carbon/org/eclipse/swt/printing/Printer.java
@@ -232,6 +232,7 @@
* Creates the printer handle.
* This method is called internally by the instance creation
* mechanism of the <code>Device</code> class.
+ * @param deviceData the device data
*/
protected void create(DeviceData deviceData) {
data = (PrinterData)deviceData;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
index dcd2b91..8a53b2c 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Printing/motif/org/eclipse/swt/printing/Printer.java
@@ -275,6 +275,7 @@
* Creates the printer handle.
* This method is called internally by the instance creation
* mechanism of the <code>Device</code> class.
+ * @param deviceData the device data
*/
protected void create(DeviceData deviceData) {
data = (PrinterData)deviceData;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/carbon/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/carbon/org/eclipse/swt/program/Program.java
index d68eea5..6191177 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/carbon/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/carbon/org/eclipse/swt/program/Program.java
@@ -282,17 +282,21 @@
* the program has no descriptive name, this string may
* be the executable name, path or empty.
*
- * @return an the name of the program
+ * @return the name of the program
*/
public String getName () {
return name;
}
/**
- * Returns true if the receiver and the argument represent
- * the same program.
- *
- * @return true if the programs are the same
+ * Compares the argument to the receiver, and returns true
+ * if they represent the <em>same</em> object using a class
+ * specific comparison.
+ *
+ * @param other the object to compare with this object
+ * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
+ *
+ * @see #hashCode()
*/
public boolean equals(Object other) {
if (this == other) return true;
@@ -305,14 +309,25 @@
}
/**
- * Returns a hash code suitable for this object.
- *
- * @return a hash code
+ * Returns an integer hash code for the receiver. Any two
+ * objects that return <code>true</code> when passed to
+ * <code>equals</code> must return the same value for this
+ * method.
+ *
+ * @return the receiver's hash
+ *
+ * @see #equals(Object)
*/
public int hashCode() {
return name.hashCode() ^ command.hashCode() ^ iconName.hashCode();
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the event
+ */
public String toString () {
return "Program {" + name + "}";
}
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/gtk/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/gtk/org/eclipse/swt/program/Program.java
index 58b0aae..7d04a21 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/gtk/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/gtk/org/eclipse/swt/program/Program.java
@@ -711,10 +711,14 @@
}
/**
- * Returns true if the receiver and the argument represent
- * the same program.
- *
- * @return true if the programs are the same
+ * Compares the argument to the receiver, and returns true
+ * if they represent the <em>same</em> object using a class
+ * specific comparison.
+ *
+ * @param other the object to compare with this object
+ * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
+ *
+ * @see #hashCode()
*/
public boolean equals(Object other) {
if (this == other) return true;
@@ -769,21 +773,32 @@
* the program has no descriptive name, this string may
* be the executable name, path or empty.
*
- * @return an the name of the program
+ * @return the name of the program
*/
public String getName() {
return name;
}
/**
- * Returns a hash code suitable for this object.
- *
- * @return a hash code
+ * Returns an integer hash code for the receiver. Any two
+ * objects that return <code>true</code> when passed to
+ * <code>equals</code> must return the same value for this
+ * method.
+ *
+ * @return the receiver's hash
+ *
+ * @see #equals(Object)
*/
public int hashCode() {
return name.hashCode() ^ command.hashCode() ^ display.hashCode();
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the event
+ */
public String toString() {
return "Program {" + name + "}";
}
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/motif/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/motif/org/eclipse/swt/program/Program.java
index 593f994..e844de7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/motif/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/motif/org/eclipse/swt/program/Program.java
@@ -746,10 +746,14 @@
}
/**
- * Returns true if the receiver and the argument represent
- * the same program.
- *
- * @return true if the programs are the same
+ * Compares the argument to the receiver, and returns true
+ * if they represent the <em>same</em> object using a class
+ * specific comparison.
+ *
+ * @param other the object to compare with this object
+ * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
+ *
+ * @see #hashCode()
*/
public boolean equals(Object other) {
if (this == other) return true;
@@ -804,21 +808,32 @@
* the program has no descriptive name, this string may
* be the executable name, path or empty.
*
- * @return an the name of the program
+ * @return the name of the program
*/
public String getName() {
return name;
}
/**
- * Returns a hash code suitable for this object.
- *
- * @return a hash code
+ * Returns an integer hash code for the receiver. Any two
+ * objects that return <code>true</code> when passed to
+ * <code>equals</code> must return the same value for this
+ * method.
+ *
+ * @return the receiver's hash
+ *
+ * @see #equals(Object)
*/
public int hashCode() {
return name.hashCode() ^ command.hashCode() ^ display.hashCode();
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the event
+ */
public String toString() {
return "Program {" + name + "}";
}
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/photon/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/photon/org/eclipse/swt/program/Program.java
index 7d1bd91..a0e14f0 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT Program/photon/org/eclipse/swt/program/Program.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT Program/photon/org/eclipse/swt/program/Program.java
@@ -319,17 +319,21 @@
* the program has no descriptive name, this string may
* be the executable name, path or empty.
*
- * @return an the name of the program
+ * @return the name of the program
*/
public String getName () {
return name;
}
/**
- * Returns true if the receiver and the argument represent
- * the same program.
- *
- * @return true if the programs are the same
+ * Compares the argument to the receiver, and returns true
+ * if they represent the <em>same</em> object using a class
+ * specific comparison.
+ *
+ * @param other the object to compare with this object
+ * @return <code>true</code> if the object is the same as this object and <code>false</code> otherwise
+ *
+ * @see #hashCode()
*/
public boolean equals(Object other) {
if (this == other) return true;
@@ -342,14 +346,25 @@
}
/**
- * Returns a hash code suitable for this object.
- *
- * @return a hash code
+ * Returns an integer hash code for the receiver. Any two
+ * objects that return <code>true</code> when passed to
+ * <code>equals</code> must return the same value for this
+ * method.
+ *
+ * @return the receiver's hash
+ *
+ * @see #equals(Object)
*/
public int hashCode() {
return extension.hashCode() ^ name.hashCode() ^ command.hashCode();
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the event
+ */
public String toString () {
return "Program {" + name + "}";
}
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 5299c44..90e54b1 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
@@ -14,16 +14,49 @@
import org.eclipse.swt.internal.*;
import org.eclipse.swt.internal.cairo.*;
+/**
+ * Instances of this class represent paths through the two-dimensional
+ * coordinate system. Paths do not have to be continuous, and can be
+ * described using lines, rectangles, arcs, cubic or quadratic bezier curves,
+ * glyphs, or other paths.
+ * <p>
+ * Application code must explicitly invoke the <code>Path.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
+ */
public class Path extends Resource {
/**
- * the handle to the OS path resource
+ * the OS resource for the Path
* (Warning: This field is platform dependent)
+ * <p>
+ * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+ * public API. It is marked public only so that it can be shared
+ * within the packages provided by SWT. It is not available on all
+ * platforms and should never be accessed from application code.
+ * </p>
*/
public int /*long*/ handle;
boolean move;
+/**
+ * Constructs a new empty Path.
+ *
+ * @param device the device on which to allocate the path
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the path could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Path (Device device) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -34,6 +67,35 @@
if (device.tracking) device.new_Object(this);
}
+/**
+ * Adds to the receiver a circular or elliptical arc that lies within
+ * the specified rectangular area.
+ * <p>
+ * The resulting arc begins at <code>startAngle</code> and extends
+ * for <code>arcAngle</code> degrees.
+ * Angles are interpreted such that 0 degrees is at the 3 o'clock
+ * position. A positive value indicates a counter-clockwise rotation
+ * while a negative value indicates a clockwise rotation.
+ * </p><p>
+ * The center of the arc is the center of the rectangle whose origin
+ * is (<code>x</code>, <code>y</code>) and whose size is specified by the
+ * <code>width</code> and <code>height</code> arguments.
+ * </p><p>
+ * The resulting arc covers an area <code>width + 1</code> pixels wide
+ * by <code>height + 1</code> pixels tall.
+ * </p>
+ *
+ * @param x the x coordinate of the upper-left corner of the arc
+ * @param y the y coordinate of the upper-left corner of the arc
+ * @param width the width of the arc
+ * @param height the height of the arc
+ * @param startAngle the beginning angle
+ * @param arcAngle the angular extent of the arc, relative to the start angle
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addArc(float x, float y, float width, float height, float startAngle, float arcAngle) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
move = true;
@@ -49,6 +111,19 @@
Cairo.cairo_destroy(matrix);
}
+/**
+ * Adds to the receiver the path described by the parameter.
+ *
+ * @param path the path to add to the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addPath(Path path) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (path == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -57,12 +132,41 @@
Cairo.cairo_add_path(handle, path.handle);
}
+/**
+ * Adds to the receiver the rectangle specified by x, y, width and height.
+ *
+ * @param x the x coordinate of the rectangle to add
+ * @param y the y coordinate of the rectangle to add
+ * @param width the width of the rectangle to add
+ * @param height the height of the rectangle to add
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addRectangle(float x, float y, float width, float height) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
move = false;
Cairo.cairo_rectangle(handle, x, y, width, height);
}
+/**
+ * Adds to the receiver the pattern of glyphs generated by drawing
+ * the given string using the given font starting at the point (x, y).
+ *
+ * @param string the text to use
+ * @param x the x coordinate of the starting point
+ * @param y the y coordinate of the starting point
+ * @param font the font to use
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the font is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the font has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addString(String string, float x, float y, Font font) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (font == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -77,12 +181,44 @@
Cairo.cairo_text_path(handle, buffer);
}
+/**
+ * Closes the current sub path by adding to the receiver a line
+ * from the current point of the path back to the starting point
+ * of the sub path.
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void close() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
Cairo.cairo_close_path(handle);
move = false;
}
+/**
+ * Returns <code>true</code> if the specified point is contained by
+ * the receiver and false otherwise.
+ * <p>
+ * If outline is <code>true</code>, the point (x, y) checked for containment in
+ * the receiver's outline. If outline is <code>false</code>, the point is
+ * checked to see if it is contained within the bounds of the (closed) area
+ * covered by the receiver.
+ *
+ * @param x the x coordinate of the point to test for containment
+ * @param y the y coordinate of the point to test for containment
+ * @param gc the GC to use when testing for containment
+ * @param outline controls wether to check the outline or contained area of the path
+ * @return <code>true</code> if the path contains the point and <code>false</code> otherwise
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public boolean contains(float x, float y, GC gc, boolean outline) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (gc == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -101,6 +237,20 @@
return result;
}
+/**
+ * Adds to the receiver a cubic bezier curve based on the parameters.
+ *
+ * @param cx1 the x coordinate of the first control point of the spline
+ * @param cy1 the y coordinate of the first control of the spline
+ * @param cx2 the x coordinate of the second control of the spline
+ * @param cy2 the y coordinate of the second control of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (!move) {
@@ -112,6 +262,21 @@
Cairo.cairo_curve_to(handle, cx1, cy1, cx2, cy2, x, y);
}
+/**
+ * Replaces the first four elements in the parameter with values that
+ * describe the smallest rectangle that will completely contain the
+ * receiver (i.e. the bounding box).
+ *
+ * @param bounds the array to hold the result
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the bounding box</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void getBounds(float[] bounds) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (bounds == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -124,6 +289,20 @@
bounds[3] = (float)(extents[3] - extents[1]);
}
+/**
+ * Replaces the first two elements in the parameter with values that
+ * describe the current point of the path.
+ *
+ * @param point the array to hold the result
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the end point</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void getCurrentPoint(float[] point) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (point == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -134,6 +313,17 @@
point[1] = (float)y[0];
}
+/**
+ * Returns a device independent representation of the receiver.
+ *
+ * @return the PathData for the receiver
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see PathData
+ */
public PathData getPathData() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
int[] n_types = new int[1];
@@ -148,6 +338,17 @@
return result;
}
+/**
+ * Adds to the receiver a line from the current point to
+ * the point specified by (x, y).
+ *
+ * @param x the x coordinate of the end of the line to add
+ * @param y the y coordinate of the end of the line to add
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void lineTo(float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (!move) {
@@ -159,6 +360,18 @@
Cairo.cairo_line_to(handle, x, y);
}
+/**
+ * Sets the current point of the receiver to the point
+ * specified by (x, y). Note that this starts a new
+ * sub path.
+ *
+ * @param x the x coordinate of the new end point
+ * @param y the y coordinate of the new end point
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void moveTo(float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
/*
@@ -172,6 +385,18 @@
Cairo.cairo_move_to(handle, x, y);
}
+/**
+ * Adds to the receiver a quadratic curve based on the parameters.
+ *
+ * @param cx the x coordinate of the control point of the spline
+ * @param cy the y coordinate of the control point of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void quadTo(float cx, float cy, float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
double[] currentX = new double[1], currentY = new double[1];
@@ -189,6 +414,11 @@
Cairo.cairo_curve_to(handle, cx1, cy1, cx2, cy2, x, y);
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Path. Applications must dispose of all Paths that
+ * they allocate.
+ */
public void dispose() {
if (handle == 0) return;
Cairo.cairo_destroy(handle);
@@ -197,10 +427,26 @@
device = null;
}
+/**
+ * Returns <code>true</code> if the Path has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Path.
+ * When a Path has been disposed, it is an error to
+ * invoke any other method using the Path.
+ *
+ * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return handle == 0;
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString() {
if (isDisposed()) return "Path {*DISPOSED*}";
return "Path {" + handle + "}";
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 2b818f4..8cfe85f 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
@@ -14,16 +14,47 @@
import org.eclipse.swt.internal.cairo.*;
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent patterns to use while drawing. Patterns
+ * can be specified either as bitmaps or gradients.
+ * <p>
+ * Application code must explicitly invoke the <code>Pattern.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
*/
public class Pattern extends Resource {
/**
- * the handle to the OS path resource
+ * the OS resource for the Pattern
* (Warning: This field is platform dependent)
+ * <p>
+ * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+ * public API. It is marked public only so that it can be shared
+ * within the packages provided by SWT. It is not available on all
+ * platforms and should never be accessed from application code.
+ * </p>
*/
public int /*long*/ handle;
+/**
+ * Constructs a new Pattern given an image. Drawing with the resulting
+ * pattern will cause the image to be tiled over the resulting area.
+ *
+ * @param device the device on which to allocate the pattern
+ * @param image the image that the pattern will draw
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, or the image is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Pattern(Device device, Image image) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -38,6 +69,30 @@
if (device.tracking) device.new_Object(this);
}
+/**
+ * Constructs a new Pattern that represents a linear, two color
+ * gradient. Drawing with the pattern will cause the resulting area to be
+ * tiled with the gradient specified by the arguments.
+ *
+ * @param device the device on which to allocate the pattern
+ * @param x1 the x coordinate of the starting corner of the gradient
+ * @param y1 the y coordinate of the starting corner of the gradient
+ * @param x2 the x coordinate of the ending corner of the gradient
+ * @param y2 the y coordinate of the ending corner of the gradient
+ * @param color1 the starting color of the gradient
+ * @param color2 the ending color of the gradient
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device,
+ * or if either color1 or color2 is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if either color1 or color2 has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Pattern(Device device, float x1, float y1, float x2, float y2, Color color1, Color color2) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -56,6 +111,11 @@
if (device.tracking) device.new_Object(this);
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Pattern. Applications must dispose of all Patterns that
+ * they allocate.
+ */
public void dispose() {
if (handle == 0) return;
if (device.isDisposed()) return;
@@ -65,10 +125,26 @@
device = null;
}
+/**
+ * Returns <code>true</code> if the Pattern has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Pattern.
+ * When a Pattern has been disposed, it is an error to
+ * invoke any other method using the Pattern.
+ *
+ * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return handle == 0;
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString() {
if (isDisposed()) return "Pattern {*DISPOSED*}";
return "Pattern {" + handle + "}";
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 6ff290e..848128a 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
@@ -14,21 +14,90 @@
import org.eclipse.swt.internal.*;
import org.eclipse.swt.internal.cairo.*;
+/**
+ * Instances of this class represent transformation matrices for
+ * points expressed as (x, y) pairs of floating point numbers.
+ * <p>
+ * Application code must explicitly invoke the <code>Transform.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
+ */
public class Transform extends Resource {
/**
- * the handle to the OS transform resource
+ * the OS resource for the Transform
* (Warning: This field is platform dependent)
+ * <p>
+ * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+ * public API. It is marked public only so that it can be shared
+ * within the packages provided by SWT. It is not available on all
+ * platforms and should never be accessed from application code.
+ * </p>
*/
public int /*long*/ handle;
+/**
+ * Constructs a new identity Transform.
+ *
+ * @param device the device on which to allocate the Transform
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform (Device device) {
this(device, 1, 0, 0, 1, 0, 0);
}
+/**
+ * Constructs a new Transform given an array of elements that represent the
+ * matrix that describes the transformation.
+ *
+ * @param device the device on which to allocate the Transform
+ * @param elements an array of floats that describe the transformation matrix
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device, or the elements array is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the elements array is too small to hold the matrix values</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform(Device device, float[] elements) {
this (device, checkTransform(elements)[0], elements[1], elements[2], elements[3], elements[4], elements[5]);
}
+/**
+ * Constructs a new Transform given all of the elements that represent the
+ * matrix that describes the transformation.
+ *
+ * @param device the device on which to allocate the Transform
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform (Device device, float m11, float m12, float m21, float m22, float dx, float dy) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -46,6 +115,11 @@
return elements;
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Transform. Applications must dispose of all Transforms that
+ * they allocate.
+ */
public void dispose() {
if (handle == 0) return;
if (device.isDisposed()) return;
@@ -55,6 +129,21 @@
device = null;
}
+/**
+ * Fills the parameter with the values of the transformation matrix
+ * that the receiver represents, in the order {m11, m12, m21, m22, dx, dy}.
+ *
+ * @param elements array to hold the matrix values
+ * @return (in elements array) the transformation matrix represented by the receiver
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the matrix values</li>
+ * </ul>
+ */
public void getElements(float[] elements) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -70,6 +159,15 @@
elements[5] = (float)ty[0];
}
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the mathematical inverse of the matrix it previously represented.
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_CANNOT_INVERT_MATRIX - if the matrix is not invertable</li>
+ * </ul>
+ */
public void invert() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (Cairo.cairo_matrix_invert(handle) != 0) {
@@ -77,10 +175,26 @@
}
}
+/**
+ * Returns <code>true</code> if the Transform has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Transform.
+ * When a Transform has been disposed, it is an error to
+ * invoke any other method using the Transform.
+ *
+ * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return handle == 0;
}
+/**
+ * Returns <code>true</code> if the Transform represents the identity matrix
+ * and false otherwise.
+ *
+ * @return <code>true</code> if the receiver is an identity Transform, and <code>false</code> otherwise
+ */
public boolean isIdentity() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
float[] m = new float[6];
@@ -88,6 +202,21 @@
return m[0] == 1 && m[1] == 0 && m[2] == 0 && m[3] == 1 && m[4] == 0 && m[5] == 0;
}
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the result of multiplying the matrix it previously represented by the
+ * argument.
+ *
+ * @param matrix the matrix to multiply the receiver by
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ */
public void multiply(Transform matrix) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (matrix == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -95,21 +224,74 @@
Cairo.cairo_matrix_multiply(handle, matrix.handle, handle);
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation rotated by the specified angle.
+ * The angle is specified in degrees and for the identity transform 0 degrees
+ * is at the 3 o'clock position. A positive value indicates a clockwise rotation
+ * while a negative value indicates a counter-clockwise rotation.
+ *
+ * @param angle the angle to rotate the transformation by
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void rotate(float angle) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
Cairo.cairo_matrix_rotate(handle, angle * (float)Compatibility.PI / 180);
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation scaled by (scaleX, scaleY).
+ *
+ * @param scaleX the amount to scale in the X direction
+ * @param scaleY the amount to scale in the Y direction
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void scale(float scaleX, float scaleY) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
Cairo.cairo_matrix_scale(handle, scaleX, scaleY);
}
+/**
+ * Modifies the receiver to represent a new transformation given all of
+ * the elements that represent the matrix that describes that transformation.
+ *
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void setElements(float m11, float m12, float m21, float m22, float dx, float dy) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
Cairo.cairo_matrix_set_affine(handle, m11, m12, m21, m22, dx, dy);
}
+/**
+ * Given an array containing points described by alternating x and y values,
+ * modify that array such that each point has been replaced with the result of
+ * applying the transformation represented by the receiver to that point.
+ *
+ * @param pointArray an array of alternating x and y values to be transformed
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the point array is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void transform(float[] pointArray) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -124,11 +306,28 @@
}
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation translated by (offsetX, offsetY).
+ *
+ * @param offsetX the distance to translate in the X direction
+ * @param offsetY the distance to translate in the Y direction
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void translate(float offsetX, float offsetY) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
Cairo.cairo_matrix_translate(handle, offsetX, offsetY);
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString() {
if (isDisposed()) return "Transform {*DISPOSED*}";
float[] elements = new float[6];
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java
index dac0cef..53519bb 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java
@@ -176,7 +176,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java
index e57c199..8cd0a4a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java
@@ -496,7 +496,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java
index 1a7384e..ef6a468 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java
@@ -416,7 +416,7 @@
* specified in class <code>SWT</code>. Any value other
* than one of the SWT color constants which is passed
* in will result in the color black. This color should
- * not be free'd because it was allocated by the system,
+ * not be freed because it was allocated by the system,
* not the application.
*
* @param id the color constant
@@ -455,7 +455,7 @@
* Returns a reasonable font for applications to use.
* On some platforms, this will match the "default font"
* or "system font" if such can be found. This font
- * should not be free'd because it was allocated by the
+ * should not be freed because it was allocated by the
* system, not the application.
* <p>
* Typically, applications which want the default look
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java
index 425e8a4..c3650fe 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java
@@ -311,7 +311,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java
index 65bddd4..d73858c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java
@@ -278,7 +278,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -378,7 +378,8 @@
/**
* Sets the style of the receiver to the argument which must
* be a bitwise OR of one or more of the <code>SWT</code>
- * constants NORMAL, BOLD and ITALIC.
+ * constants NORMAL, BOLD and ITALIC. All other style bits are
+ * ignored.
*
* @param style the new style for this <code>FontData</code>
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java
index c66cb01..ba51ca8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java
@@ -117,7 +117,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java
index f029fef..cd0a7f3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java
@@ -260,6 +260,24 @@
public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY) {
copyArea(srcX, srcY, width, height, destX, destY, true);
}
+/**
+ * Copies a rectangular area of the receiver at the source
+ * position onto the receiver at the destination position.
+ *
+ * @param srcX the x coordinate in the receiver of the area to be copied
+ * @param srcY the y coordinate in the receiver of the area to be copied
+ * @param width the width of the area to copy
+ * @param height the height of the area to copy
+ * @param destX the x coordinate in the receiver of the area to copy to
+ * @param destY the y coordinate in the receiver of the area to copy to
+ * @param paint if <code>true</code> paint events will be generated for old and obscured areas
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY, boolean paint) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (data.updateClip) setCGClipping();
@@ -505,7 +523,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void drawFocus(int x, int y, int width, int height) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -704,8 +722,22 @@
flush();
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Draws the path described by the parameter.
+ *
+ * @param path the path to draw
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void drawPath(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1215,7 +1247,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1291,8 +1323,22 @@
flush();
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Fills the path described by the parameter.
+ *
+ * @param path the path to fill
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void fillPath(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1360,7 +1406,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillRectangle(int x, int y, int width, int height) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1395,7 +1441,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillRectangle(Rectangle rect) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1509,21 +1555,64 @@
return Color.carbon_new (data.device, data.background);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the background pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's background pattern
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public Pattern getBackgroundPattern() {
if (handle == 0) SWT.error(SWT.ERROR_WIDGET_DISPOSED);
return data.backgroundPattern;
}
+/**
+ * Returns <code>true</code> if receiver is using the operating system's
+ * advanced graphics subsystem. Otherwise, <code>false</code> is returned
+ * to indicate that normal graphics are in use.
+ * <p>
+ * Advanced graphics may not be installed for the operating system. In this
+ * case, <code>false</code> is always returned. Some operating system have
+ * only one graphics subsystem. If this subsystem supports advanced graphics,
+ * then <code>true</code> is always returned. If any graphics operation such
+ * as alpha, antialias, patterns, interpolation, paths, clipping or transformation
+ * has caused the receiver to switch from regular to advanced graphics mode,
+ * <code>true</code> is returned. If the receiver has been explicitly switched
+ * to advanced mode and this mode is supported, <code>true</code> is returned.
+ * </p>
+ *
+ * @return the advanced value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAdvanced
+ * @since 3.1
+ */
public boolean getAdvanced() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return true;
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's alpha value.
+ *
+ * @return the alpha value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public int getAlpha() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1531,7 +1620,20 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's anti-aliasing setting value, which will be
+ * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getTextAntialias
+ *
+ * @since 3.1
*/
public int getAntialias() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1648,6 +1750,18 @@
}
}
+/**
+ * Returns the receiver's fill rule, which will be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @return the receiver's fill rule
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int getFillRule() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return data.fillRule;
@@ -1708,16 +1822,37 @@
return Color.carbon_new(data.device, data.foreground);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the foreground pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's foreground pattern
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public Pattern getForegroundPattern() {
if (handle == 0) SWT.error(SWT.ERROR_WIDGET_DISPOSED);
return data.foregroundPattern;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the receiver's interpolation setting, which will be one of
+ * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>,
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @return the receiver's interpolation setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public int getInterpolation() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1750,7 +1885,8 @@
}
/**
- * Returns the receiver's line dash style.
+ * Returns the receiver's line dash style. The default value is
+ * <code>null</code>.
*
* @return the lin dash style used for drawing lines
*
@@ -1845,15 +1981,43 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's text drawing anti-aliasing setting value,
+ * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing
+ * <em>only</em> for text drawing operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getAntialias
+ *
+ * @since 3.1
*/
public int getTextAntialias() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return data.textAntialias;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the parameter to the transform that is currently being
+ * used by the receiver.
+ *
+ * @param transform the destination to copy the transform into
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Transform
+ *
+ * @since 3.1
*/
public void getTransform (Transform transform) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1884,7 +2048,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -1956,6 +2120,48 @@
&& transform[3] == 1 && transform[4] == 0 && transform[5] == 0;
}
+/**
+ * Sets the receiver to always use the operating system's advanced graphics
+ * subsystem for all graphics operations if the argument is <code>true</code>.
+ * If the argument is <code>false</code>, the advanced graphics subsystem is
+ * no longer used, advanced graphics state is cleared and the normal graphics
+ * subsystem is used from now on.
+ * <p>
+ * Normally, the advanced graphics subsystem is invoked automatically when
+ * any one of the alpha, antialias, patterns, interpolation, paths, clipping
+ * or transformation operations in the receiver is requested. When the receiver
+ * is switched into advanced mode, the advanced graphics subsystem performs both
+ * advanced and normal graphics operations. Because the two subsystems are
+ * different, their output may differ. Switching to advanced graphics before
+ * any graphics operations are performed ensures that the output is consistent.
+ * </p>
+ * <p>
+ * Advanced graphics may not be installed for the operating system. In this
+ * case, this operation does nothing. Some operating system have only one
+ * graphics subsystem, so switching from normal to advanced graphics does
+ * nothing. However, switching from advanced to normal graphics will always
+ * clear the advanced graphics state, even for operating systems that have
+ * only one graphics subsystem.
+ * </p>
+ *
+ * @param advanced the new advanced graphics state
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAlpha
+ * @see #setAntialias
+ * @see #setBackgroundPattern
+ * @see #setClipping(Path)
+ * @see #setForegroundPattern
+ * @see #setInterpolation
+ * @see #setTextAntialias
+ * @see #setTransform
+ * @see #getAdvanced
+ *
+ * @since 3.1
+ */
public void setAdvanced(boolean advanced) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (!advanced) {
@@ -1971,7 +2177,15 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's alpha value.
+ *
+ * @param alpha the alpha value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public void setAlpha(int alpha) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1980,7 +2194,24 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's anti-aliasing value to the parameter,
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setTextAntialias
+ *
+ * @since 3.1
*/
public void setAntialias(int antialias) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2027,6 +2258,22 @@
data.backgroundPattern = null;
}
+/**
+ * Sets the background pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new background pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
+ */
public void setBackgroundPattern(Pattern pattern) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (pattern != null && pattern.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
@@ -2094,7 +2341,22 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the area of the receiver which can be changed
+ * by drawing operations to the path specified
+ * by the argument.
+ *
+ * @param path the clipping path.
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void setClipping(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2109,9 +2371,11 @@
/**
* Sets the area of the receiver which can be changed
* by drawing operations to the rectangular area specified
- * by the argument.
+ * by the argument. Specifying <code>null</code> for the
+ * rectangle reverts the receiver's clipping area to its
+ * original value.
*
- * @param rect the clipping rectangle
+ * @param rect the clipping rectangle or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
@@ -2129,9 +2393,11 @@
/**
* Sets the area of the receiver which can be changed
* by drawing operations to the region specified
- * by the argument.
+ * by the argument. Specifying <code>null</code> for the
+ * region reverts the receiver's clipping area to its
+ * original value.
*
- * @param region the clipping region.
+ * @param region the clipping region or <code>null</code>
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li>
@@ -2186,6 +2452,22 @@
OS.CGContextTranslateCTM(handle, rect.left, -(portRect.bottom - portRect.top) + rect.top);
}
+/**
+ * Sets the receiver's fill rule to the parameter, which must be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @param rule the new fill rule
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code>
+ * or <code>SWT.FILL_WINDING</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void setFillRule(int rule) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
switch (rule) {
@@ -2264,8 +2546,21 @@
data.foregroundPattern = null;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the foreground pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new foreground pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public void setForegroundPattern(Pattern pattern) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2287,8 +2582,22 @@
data.foregroundPattern = pattern;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the receiver's interpolation setting to the parameter, which
+ * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>,
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @param interpolation the new interpolation setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public void setInterpolation(int interpolation) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2341,7 +2650,10 @@
}
/**
- * Sets the receiver's line dash style to the argument.
+ * Sets the receiver's line dash style to the argument. The default
+ * value is <code>null</code>. If the argument is not <code>null</code>,
+ * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise
+ * it is set to <code>SWT.LINE_SOLID</code>.
*
* @param dashes the dash style to be used for drawing lines
*
@@ -2468,6 +2780,12 @@
* for all of the figure drawing operations (that is,
* <code>drawLine</code>, <code>drawRectangle</code>,
* <code>drawPolyline</code>, and so forth.
+ * <p>
+ * Note that line width of zero is used as a hint to
+ * indicate that the fastest possible line drawing
+ * algorithms should be used. This means that the
+ * output may be different from line width one.
+ * </p>
*
* @param lineWidth the width of a line
*
@@ -2566,12 +2884,19 @@
* and the destination, and if the argument is <code>false</code>,
* puts the receiver in a drawing mode where the destination color
* is replaced with the source color value.
+ * <p>
+ * Note that this mode in fundamentally unsupportable on certain
+ * platforms, notably Carbon (Mac OS X). Clients that want their
+ * code to run on all platforms need to avoid this method.
+ * </p>
*
* @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ *
+ * @deprecated this functionality is not supported on some platforms
*/
public void setXORMode(boolean xor) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2610,7 +2935,24 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's text anti-aliasing value to the parameter,
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing only
+ * for all <em>text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAntialias
+ *
+ * @since 3.1
*/
public void setTextAntialias(int antialias) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2625,8 +2967,23 @@
data.textAntialias = antialias;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the transform that is currently being used by the receiver. If
+ * the argument is <code>null</code>, the current transform is set to
+ * the identity transform.
+ *
+ * @param transform the transform to set
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Transform
+ *
+ * @since 3.1
*/
public void setTransform(Transform transform) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java
index e706c61..4d3782a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java
@@ -53,7 +53,7 @@
* loading process should use the support provided in class
* <code>ImageLoader</code>.
* </p><p>
- * Application code must explicitely invoke the <code>Image.dispose()</code>
+ * Application code must explicitly invoke the <code>Image.dispose()</code>
* method to release the operating system resources managed by each instance
* when those instances are no longer required.
* </p>
@@ -415,7 +415,20 @@
* This constructor may be used to load a resource as follows:
* </p>
* <pre>
- * new Image(device, clazz.getResourceAsStream("file.gif"));
+ * static Image loadImage (Display display, Class clazz, String string) {
+ * InputStream stream = clazz.getResourceAsStream (string);
+ * if (stream == null) return null;
+ * Image image = null;
+ * try {
+ * image = new Image (display, stream);
+ * } catch (SWTException ex) {
+ * } finally {
+ * try {
+ * stream.close ();
+ * } catch (IOException ex) {}
+ * }
+ * return image;
+ * }
* </pre>
*
* @param device the device on which to create the image
@@ -672,7 +685,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
index 093455c..4cd7e76 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java
@@ -15,16 +15,46 @@
import org.eclipse.swt.internal.carbon.*;
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent paths through the two-dimensional
+ * coordinate system. Paths do not have to be continuous, and can be
+ * described using lines, rectangles, arcs, cubic or quadratic bezier curves,
+ * glyphs, or other paths.
+ * <p>
+ * Application code must explicitly invoke the <code>Path.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
*/
public class Path extends Resource {
/**
- * the handle to the OS path resource
+ * the OS resource for the Path
* (Warning: This field is platform dependent)
+ * <p>
+ * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+ * public API. It is marked public only so that it can be shared
+ * within the packages provided by SWT. It is not available on all
+ * platforms and should never be accessed from application code.
+ * </p>
*/
public int handle;
+/**
+ * Constructs a new empty Path.
+ *
+ * @param device the device on which to allocate the path
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the path could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Path (Device device) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -34,6 +64,35 @@
if (device.tracking) device.new_Object(this);
}
+/**
+ * Adds to the receiver a circular or elliptical arc that lies within
+ * the specified rectangular area.
+ * <p>
+ * The resulting arc begins at <code>startAngle</code> and extends
+ * for <code>arcAngle</code> degrees.
+ * Angles are interpreted such that 0 degrees is at the 3 o'clock
+ * position. A positive value indicates a counter-clockwise rotation
+ * while a negative value indicates a clockwise rotation.
+ * </p><p>
+ * The center of the arc is the center of the rectangle whose origin
+ * is (<code>x</code>, <code>y</code>) and whose size is specified by the
+ * <code>width</code> and <code>height</code> arguments.
+ * </p><p>
+ * The resulting arc covers an area <code>width + 1</code> pixels wide
+ * by <code>height + 1</code> pixels tall.
+ * </p>
+ *
+ * @param x the x coordinate of the upper-left corner of the arc
+ * @param y the y coordinate of the upper-left corner of the arc
+ * @param width the width of the arc
+ * @param height the height of the arc
+ * @param startAngle the beginning angle
+ * @param arcAngle the angular extent of the arc, relative to the start angle
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addArc(float x, float y, float width, float height, float startAngle, float arcAngle) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
float[] cmt = new float[6];
@@ -41,6 +100,19 @@
OS.CGPathAddArc(handle, cmt, 0, 0, 1, -startAngle * (float)Compatibility.PI / 180, -(startAngle + arcAngle) * (float)Compatibility.PI / 180, true);
}
+/**
+ * Adds to the receiver the path described by the parameter.
+ *
+ * @param path the path to add to the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addPath(Path path) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (path == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -48,6 +120,18 @@
OS.CGPathAddPath(handle, null, path.handle);
}
+/**
+ * Adds to the receiver the rectangle specified by x, y, width and height.
+ *
+ * @param x the x coordinate of the rectangle to add
+ * @param y the y coordinate of the rectangle to add
+ * @param width the width of the rectangle to add
+ * @param height the height of the rectangle to add
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addRectangle(float x, float y, float width, float height) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
CGRect rect = new CGRect();
@@ -95,6 +179,23 @@
float originX, originY;
float[] point = new float[2];
boolean first;
+/**
+ * Adds to the receiver the pattern of glyphs generated by drawing
+ * the given string using the given font starting at the point (x, y).
+ *
+ * @param string the text to use
+ * @param x the x coordinate of the starting point
+ * @param y the y coordinate of the starting point
+ * @param font the font to use
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the font is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the font has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addString(String string, float x, float y, Font font) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (font == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -195,11 +296,43 @@
return 0;
}
+/**
+ * Closes the current sub path by adding to the receiver a line
+ * from the current point of the path back to the starting point
+ * of the sub path.
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void close() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGPathCloseSubpath(handle);
}
+/**
+ * Returns <code>true</code> if the specified point is contained by
+ * the receiver and false otherwise.
+ * <p>
+ * If outline is <code>true</code>, the point (x, y) checked for containment in
+ * the receiver's outline. If outline is <code>false</code>, the point is
+ * checked to see if it is contained within the bounds of the (closed) area
+ * covered by the receiver.
+ *
+ * @param x the x coordinate of the point to test for containment
+ * @param y the y coordinate of the point to test for containment
+ * @param gc the GC to use when testing for containment
+ * @param outline controls wether to check the outline or contained area of the path
+ * @return <code>true</code> if the path contains the point and <code>false</code> otherwise
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public boolean contains(float x, float y, GC gc, boolean outline) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (gc == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -235,11 +368,30 @@
return buffer[0] != 0xFFFFFFFF;
}
+/**
+ * Adds to the receiver a cubic bezier curve based on the parameters.
+ *
+ * @param cx1 the x coordinate of the first control point of the spline
+ * @param cy1 the y coordinate of the first control of the spline
+ * @param cx2 the x coordinate of the second control of the spline
+ * @param cy2 the y coordinate of the second control of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGPathAddCurveToPoint(handle, null, cx1, cy1, cx2, cy2, x, y);
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Path. Applications must dispose of all Paths that
+ * they allocate.
+ */
public void dispose() {
if (handle == 0) return;
OS.CGPathRelease(handle);
@@ -248,6 +400,21 @@
device = null;
}
+/**
+ * Replaces the first four elements in the parameter with values that
+ * describe the smallest rectangle that will completely contain the
+ * receiver (i.e. the bounding box).
+ *
+ * @param bounds the array to hold the result
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the bounding box</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void getBounds(float[] bounds) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (bounds == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -260,6 +427,20 @@
bounds[3] = rect.height;
}
+/**
+ * Replaces the first two elements in the parameter with values that
+ * describe the current point of the path.
+ *
+ * @param point the array to hold the result
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the end point</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void getCurrentPoint(float[] point) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (point == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -270,6 +451,17 @@
point[1] = pt.y;
}
+/**
+ * Returns a device independent representation of the receiver.
+ *
+ * @return the PathData for the receiver
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see PathData
+ */
public PathData getPathData() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
Callback callback = new Callback(this, "applierFunc", 2);
@@ -294,25 +486,76 @@
return result;
}
+/**
+ * Returns <code>true</code> if the Path has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Path.
+ * When a Path has been disposed, it is an error to
+ * invoke any other method using the Path.
+ *
+ * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return handle == 0;
}
+/**
+ * Adds to the receiver a line from the current point to
+ * the point specified by (x, y).
+ *
+ * @param x the x coordinate of the end of the line to add
+ * @param y the y coordinate of the end of the line to add
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void lineTo(float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGPathAddLineToPoint(handle, null, x, y);
}
+/**
+ * Sets the current point of the receiver to the point
+ * specified by (x, y). Note that this starts a new
+ * sub path.
+ *
+ * @param x the x coordinate of the new end point
+ * @param y the y coordinate of the new end point
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void moveTo(float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGPathMoveToPoint(handle, null, x, y);
}
+/**
+ * Adds to the receiver a quadratic curve based on the parameters.
+ *
+ * @param cx the x coordinate of the control point of the spline
+ * @param cy the y coordinate of the control point of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void quadTo(float cx, float cy, float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGPathAddQuadCurveToPoint(handle, null, cx, cy, x, y);
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString () {
if (isDisposed()) return "Path {*DISPOSED*}";
return "Path {" + handle + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
index 7f4a4ed..72e1bb9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java
@@ -14,7 +14,15 @@
import org.eclipse.swt.internal.carbon.*;
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent patterns to use while drawing. Patterns
+ * can be specified either as bitmaps or gradients.
+ * <p>
+ * Application code must explicitly invoke the <code>Pattern.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
*/
public class Pattern extends Resource {
int jniRef;
@@ -23,6 +31,23 @@
float x1, y1, x2, y2;
int shading;
+/**
+ * Constructs a new Pattern given an image. Drawing with the resulting
+ * pattern will cause the image to be tiled over the resulting area.
+ *
+ * @param device the device on which to allocate the pattern
+ * @param image the image that the pattern will draw
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, or the image is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Pattern(Device device, Image image) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -36,6 +61,30 @@
if (device.tracking) device.new_Object(this);
}
+/**
+ * Constructs a new Pattern that represents a linear, two color
+ * gradient. Drawing with the pattern will cause the resulting area to be
+ * tiled with the gradient specified by the arguments.
+ *
+ * @param device the device on which to allocate the pattern
+ * @param x1 the x coordinate of the starting corner of the gradient
+ * @param y1 the y coordinate of the starting corner of the gradient
+ * @param x2 the x coordinate of the ending corner of the gradient
+ * @param y2 the y coordinate of the ending corner of the gradient
+ * @param color1 the starting color of the gradient
+ * @param color2 the ending color of the gradient
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device,
+ * or if either color1 or color2 is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if either color1 or color2 has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Pattern(Device device, float x1, float y1, float x2, float y2, Color color1, Color color2) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -105,6 +154,11 @@
return pattern;
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Pattern. Applications must dispose of all Patterns that
+ * they allocate.
+ */
public void dispose() {
if (jniRef == 0) return;
if (device.isDisposed()) return;
@@ -133,10 +187,26 @@
return 0;
}
+/**
+ * Returns <code>true</code> if the Pattern has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Pattern.
+ * When a Pattern has been disposed, it is an error to
+ * invoke any other method using the Pattern.
+ *
+ * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return jniRef == 0;
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString() {
if (isDisposed()) return "Pattern {*DISPOSED*}";
return "Pattern {" + jniRef + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java
index e7ef188..a4383d9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java
@@ -143,7 +143,6 @@
* @param height the height coordinate of the rectangle
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
* <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
* </ul>
* @exception SWTException <ul>
@@ -281,7 +280,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -383,7 +382,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
*/
public boolean intersects (int x, int y, int width, int height) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -407,7 +406,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
*/
public boolean intersects(Rectangle rect) {
if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -507,7 +506,6 @@
* @param height the height coordinate of the rectangle
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
* <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
* </ul>
* @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
index f47c2bc..93a247f 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java
@@ -15,23 +15,89 @@
import org.eclipse.swt.internal.carbon.*;
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent transformation matrices for
+ * points expressed as (x, y) pairs of floating point numbers.
+ * <p>
+ * Application code must explicitly invoke the <code>Transform.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
*/
public class Transform extends Resource {
/**
- * the handle to the OS path resource
+ * the OS resource for the Transform
* (Warning: This field is platform dependent)
+ * <p>
+ * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+ * public API. It is marked public only so that it can be shared
+ * within the packages provided by SWT. It is not available on all
+ * platforms and should never be accessed from application code.
+ * </p>
*/
public float[] handle;
+/**
+ * Constructs a new identity Transform.
+ *
+ * @param device the device on which to allocate the Transform
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform (Device device) {
this(device, 1, 0, 0, 1, 0, 0);
}
+/**
+ * Constructs a new Transform given an array of elements that represent the
+ * matrix that describes the transformation.
+ *
+ * @param device the device on which to allocate the Transform
+ * @param elements an array of floats that describe the transformation matrix
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device, or the elements array is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the elements array is too small to hold the matrix values</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform(Device device, float[] elements) {
this (device, checkTransform(elements)[0], elements[1], elements[2], elements[3], elements[4], elements[5]);
}
+/**
+ * Constructs a new Transform given all of the elements that represent the
+ * matrix that describes the transformation.
+ *
+ * @param device the device on which to allocate the Transform
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform (Device device, float m11, float m12, float m21, float m22, float dx, float dy) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -48,6 +114,11 @@
return elements;
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Transform. Applications must dispose of all Transforms that
+ * they allocate.
+ */
public void dispose() {
if (handle == null) return;
if (device.isDisposed()) return;
@@ -56,6 +127,21 @@
device = null;
}
+/**
+ * Fills the parameter with the values of the transformation matrix
+ * that the receiver represents, in the order {m11, m12, m21, m22, dx, dy}.
+ *
+ * @param elements array to hold the matrix values
+ * @return (in elements array) the transformation matrix represented by the receiver
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the matrix values</li>
+ * </ul>
+ */
public void getElements(float[] elements) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -63,6 +149,15 @@
System.arraycopy(handle, 0, elements, 0, handle.length);
}
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the mathematical inverse of the matrix it previously represented.
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_CANNOT_INVERT_MATRIX - if the matrix is not invertable</li>
+ * </ul>
+ */
public void invert() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if ((handle [0] * handle [3] - handle [1] * handle [2]) == 0) {
@@ -71,15 +166,46 @@
OS.CGAffineTransformInvert(handle, handle);
}
+/**
+ * Returns <code>true</code> if the Transform has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Transform.
+ * When a Transform has been disposed, it is an error to
+ * invoke any other method using the Transform.
+ *
+ * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return handle == null;
}
+/**
+ * Returns <code>true</code> if the Transform represents the identity matrix
+ * and false otherwise.
+ *
+ * @return <code>true</code> if the receiver is an identity Transform, and <code>false</code> otherwise
+ */
public boolean isIdentity() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return handle[0] == 1 && handle[1] == 0 && handle[2] == 0 && handle[3] == 1 && handle[4] == 0 && handle[5] == 0;
}
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the result of multiplying the matrix it previously represented by the
+ * argument.
+ *
+ * @param matrix the matrix to multiply the receiver by
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ */
public void multiply(Transform matrix) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (matrix == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -87,21 +213,74 @@
OS.CGAffineTransformConcat(matrix.handle, handle, handle);
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation rotated by the specified angle.
+ * The angle is specified in degrees and for the identity transform 0 degrees
+ * is at the 3 o'clock position. A positive value indicates a clockwise rotation
+ * while a negative value indicates a counter-clockwise rotation.
+ *
+ * @param angle the angle to rotate the transformation by
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void rotate(float angle) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGAffineTransformRotate(handle, angle * (float)Compatibility.PI / 180, handle);
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation scaled by (scaleX, scaleY).
+ *
+ * @param scaleX the amount to scale in the X direction
+ * @param scaleY the amount to scale in the Y direction
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void scale(float scaleX, float scaleY) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGAffineTransformScale(handle, scaleX, scaleY, handle);
}
+/**
+ * Modifies the receiver to represent a new transformation given all of
+ * the elements that represent the matrix that describes that transformation.
+ *
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void setElements(float m11, float m12, float m21, float m22, float dx, float dy) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGAffineTransformMake(m11, m12, m21, m22, dx, dy, handle);
}
+/**
+ * Given an array containing points described by alternating x and y values,
+ * modify that array such that each point has been replaced with the result of
+ * applying the transformation represented by the receiver to that point.
+ *
+ * @param pointArray an array of alternating x and y values to be transformed
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the point array is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void transform(float[] pointArray) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -116,11 +295,28 @@
}
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation translated by (offsetX, offsetY).
+ *
+ * @param offsetX the distance to translate in the X direction
+ * @param offsetY the distance to translate in the Y direction
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void translate(float offsetX, float offsetY) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
OS.CGAffineTransformTranslate(handle, offsetX, offsetY, handle);
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString() {
if (isDisposed()) return "Transform {*DISPOSED*}";
float[] elements = new float[6];
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java
index 40b54cc..5a7dc0055 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java
@@ -610,9 +610,9 @@
/**
* Sets the receiver's image to the argument, which may be
- * null indicating that no image should be displayed.
+ * <code>null</code> indicating that no image should be displayed.
*
- * @param image the image to display on the receiver (may be null)
+ * @param image the image to display on the receiver (may be <code>null</code>)
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
index 27f4b8c..72f67cf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java
@@ -63,7 +63,6 @@
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
- * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
* </ul>
*
* @see SWT
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java
index c672b57..1ec451b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java
@@ -647,8 +647,8 @@
}
/**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver's list.
+ * Returns a (possibly empty) array of <code>String</code>s which are
+ * the items in the receiver's list.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -692,11 +692,16 @@
}
/**
- * Returns a <code>Point</code> whose x coordinate is the start
- * of the selection in the receiver's text field, and whose y
- * coordinate is the end of the selection. The returned values
- * are zero-relative. An "empty" selection as indicated by
- * the the x and y coordinates having the same value.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selection
+ * in the receiver's text field, and whose y coordinate is the
+ * character position representing the end of the selection.
+ * An "empty" selection is indicated by the x and y coordinates
+ * having the same value.
+ * <p>
+ * Indexing is zero based. The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
+ * </p>
*
* @return a point representing the selection start and end
*
@@ -738,7 +743,8 @@
/**
* Returns a string containing a copy of the contents of the
- * receiver's text field.
+ * receiver's text field, or an empty string if there are no
+ * contents.
*
* @return the receiver's text
*
@@ -805,6 +811,8 @@
* <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 #LIMIT
*/
public int getTextLimit () {
checkWidget();
@@ -1358,8 +1366,8 @@
/**
* Sets the text of the item in the receiver's list at the given
* zero-relative index to the string argument. This is equivalent
- * to <code>remove</code>'ing the old item at the index, and then
- * <code>add</code>'ing the new item at that index.
+ * to removing the old item at the index, and then adding the new
+ * item at that index.
*
* @param index the index for the item
* @param string the new text for the item
@@ -1531,7 +1539,11 @@
/**
* Sets the maximum number of characters that the receiver's
* text field is capable of holding to be the argument.
- *
+ * <p>
+ * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the
+ * receiver's limit to <code>Combo.LIMIT</code>.
+ * </p>
* @param limit new text limit
*
* @exception IllegalArgumentException <ul>
@@ -1541,6 +1553,8 @@
* <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 #LIMIT
*/
public void setTextLimit (int limit) {
checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java
index d93c0f6..22f767e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java
@@ -21,7 +21,7 @@
* of containing other controls.
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd>
* <dt><b>Events:</b></dt>
* <dd>(none)</dd>
* </dl>
@@ -305,7 +305,7 @@
}
/**
- * Returns an array containing the receiver's children.
+ * Returns a (possibly empty) array containing the receiver's children.
* Children are returned in the order that they are drawn.
* <p>
* Note: This is not the actual structure used by the receiver
@@ -376,7 +376,7 @@
}
/**
- * Gets the last specified tabbing order for the control.
+ * Gets the (possibly empty) tabbing order for the control.
*
* @return tabList the ordered list of controls representing the tab order
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java
index 9be57b1..f115880 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java
@@ -398,7 +398,7 @@
* @see #getBorderWidth
* @see #getBounds
* @see #getSize
- * @see #pack
+ * @see #pack(boolean)
* @see "computeTrim, getClientArea for controls that implement them"
*/
public Point computeSize (int wHint, int hHint) {
@@ -436,7 +436,7 @@
* @see #getBorderWidth
* @see #getBounds
* @see #getSize
- * @see #pack
+ * @see #pack(boolean)
* @see "computeTrim, getClientArea for controls that implement them"
*/
public Point computeSize (int wHint, int hHint, boolean changed) {
@@ -1613,7 +1613,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
*/
public void pack () {
checkWidget();
@@ -1639,7 +1639,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
*/
public void pack (boolean changed) {
checkWidget();
@@ -2489,7 +2489,8 @@
* @return <code>true</code> if the parent is changed and <code>false</code> otherwise.
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2522,7 +2523,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
* @see #update
*/
public void setRedraw (boolean redraw) {
@@ -3012,7 +3013,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
* @see PaintListener
* @see SWT#Paint
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java
index 63ee644..09027e9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java
@@ -225,9 +225,9 @@
* marked as iconified, and may also be displayed somewhere
* in the trim when the instance is in normal or maximized
* states. Depending where the icon is displayed, the platform
- * chooses the icon with the "best" size. It is expected that
- * the array will contain the same icon rendered at different
- * resolutions.
+ * chooses the icon with the "best" attributes. It is expected
+ * that the array will contain the same icon rendered at different
+ * sizes, with different depth and transparency attributes.
*
* <p>
* Note: This method will return an empty array if called before
@@ -392,7 +392,11 @@
* <em>saved default button</em>). If no default button had
* previously been set, or the saved default button was
* disposed, the receiver's default button will be set to
- * null.
+ * null.
+ * <p>
+ * The default button is the button that is selected when
+ * the receiver is active and the user presses ENTER.
+ * </p>
*
* @param button the new default button
*
@@ -457,8 +461,9 @@
* and may also be displayed somewhere in the trim when the
* instance is in normal or maximized states. Depending where
* the icon is displayed, the platform chooses the icon with
- * the "best" size. It is expected that the array will contain
- * the same icon rendered at different resolutions.
+ * the "best" attributes. It is expected that the array will
+ * contain the same icon rendered at different sizes, with
+ * different depth and transparency attributes.
*
* @param images the new image array
*
@@ -503,7 +508,7 @@
* causes the receiver to switch back to either the minimized
* or normal states.
* <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
* and <code>setMinimized(true)</code> will vary by platform. Typically,
* the behavior will match the platform user's expectations, but not
* always. This should be avoided if possible.
@@ -557,7 +562,7 @@
* causes the receiver to switch back to either the maximized
* or normal states.
* <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
* and <code>setMinimized(true)</code> will vary by platform. Typically,
* the behavior will match the platform user's expectations, but not
* always. This should be avoided if possible.
@@ -584,7 +589,7 @@
/**
* 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 may not be null.
+ * <em>title</em>, to the argument, which must not be null.
*
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java
index 8ba03e0..b46930b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java
@@ -83,6 +83,8 @@
* the directories it shows.
*
* @return the filter path
+ *
+ * @see #setFilterPath
*/
public String getFilterPath () {
return filterPath;
@@ -192,9 +194,15 @@
}
/**
- * Sets the path which the dialog will use to filter
- * the directories it shows to the argument, which may be
- * null.
+ * Sets the path that the dialog will use to filter
+ * the directories it shows to the argument, which may
+ * be null. If the string is null, then the operating
+ * system's default filter path will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
*
* @param string the filter path
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java
index 312ade5..09c8a42 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java
@@ -491,9 +491,16 @@
* be invoked by the user-interface thread at the next
* reasonable opportunity. The caller of this method continues
* to run in parallel, and is not notified when the
- * runnable has completed.
+ * runnable has completed. Specifying <code>null</code> as the
+ * runnable simply wakes the user-interface thread when run.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
*
- * @param runnable code to run on the user-interface thread.
+ * @param runnable code to run on the user-interface thread or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -647,7 +654,7 @@
* </p>
*
* @exception SWTException <ul>
- * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li>
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
* </ul>
*
@@ -660,6 +667,11 @@
this (null);
}
+/**
+ * Constructs a new instance of this class using the parameter.
+ *
+ * @param data the device data
+ */
public Display (DeviceData data) {
super (data);
}
@@ -888,7 +900,7 @@
* <p>
* This method is called after <code>release</code>.
* </p>
- * @see #dispose
+ * @see Device#dispose
* @see #release
*/
protected void destroy () {
@@ -903,7 +915,8 @@
/**
* Causes the <code>run()</code> method of the runnable to
* be invoked by the user-interface thread just before the
- * receiver is disposed.
+ * receiver is disposed. Specifying a <code>null</code> runnable
+ * is ignored.
*
* @param runnable code to run at dispose time.
*
@@ -1021,7 +1034,9 @@
/**
* Returns the display which the given thread is the
* user-interface thread for, or null if the given thread
- * is not a user-interface thread for any display.
+ * is not a user-interface thread for any display. Specifying
+ * <code>null</code> as the thread will return <code>null</code>
+ * for the display.
*
* @param thread the user-interface thread
* @return the display for the given thread
@@ -1230,7 +1245,7 @@
* Applications may have associated arbitrary objects with the
* receiver in this fashion. If the objects stored in the
* properties need to be notified when the display is disposed
- * of, it is the application's responsibility provide a
+ * of, it is the application's responsibility to provide a
* <code>disposeExec()</code> handler which does so.
* </p>
*
@@ -1267,7 +1282,7 @@
* Applications may put arbitrary objects in this field. If
* the object stored in the display specific data needs to
* be notified when the display is disposed of, it is the
- * application's responsibility provide a
+ * application's responsibility to provide a
* <code>disposeExec()</code> handler which does so.
* </p>
*
@@ -1386,9 +1401,8 @@
}
/**
- * Returns the maximum allowed depth of icons on this display.
- * On some platforms, this may be different than the actual
- * depth of the display.
+ * Returns the maximum allowed depth of icons on this display, in bits per pixel.
+ * On some platforms, this may be different than the actual depth of the display.
*
* @return the maximum icon depth
*
@@ -1396,6 +1410,8 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ *
+ * @see Device#getDepth
*/
public int getIconDepth () {
return getDepth ();
@@ -1539,8 +1555,8 @@
}
/**
- * Returns an array containing all shells which have not been
- * disposed and have the receiver as their display.
+ * Returns a (possibly empty) array containing all shells which have
+ * not been disposed and have the receiver as their display.
*
* @return the receiver's shells
*
@@ -2733,7 +2749,7 @@
* </p>
* This method is called before <code>destroy</code>.
*
- * @see #dispose
+ * @see Device#dispose
* @see #destroy
*/
protected void release () {
@@ -3200,9 +3216,10 @@
/**
* On platforms which support it, sets the application name
* to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * to set the name used for resource lookup. Specifying
+ * <code>null</code> for the name clears it.
*
- * @param name the new app name
+ * @param name the new app name or <code>null</code>
*/
public static void setAppName (String name) {
APP_NAME = name;
@@ -3470,9 +3487,16 @@
* Causes the <code>run()</code> method of the runnable to
* be invoked by the user-interface thread at the next
* reasonable opportunity. The thread which calls this method
- * is suspended until the runnable completes.
- *
- * @param runnable code to run on the user-interface thread.
+ * is suspended until the runnable completes. Specifying <code>null</code>
+ * as the runnable simply wakes the user-interface thread.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
+ *
+ * @param runnable code to run on the user-interface thread or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li>
@@ -3512,6 +3536,12 @@
* be invoked by the user-interface thread after the specified
* number of milliseconds have elapsed. If milliseconds is less
* than zero, the runnable is not executed.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
*
* @param milliseconds the delay before running the runnable
* @param runnable code to run on the user-interface thread
@@ -3651,7 +3681,7 @@
}
/**
- * If the receiver's user-interface thread was <code>sleep</code>'ing,
+ * If the receiver's user-interface thread was <code>sleep</code>ing,
* causes it to be awakened and start running again. Note that this
* method may be called from any thread.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java
index 19486b3..7ef3bcd 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java
@@ -24,6 +24,8 @@
* <dd>(none)</dd>
* </dl>
* <p>
+ * Note: Only one of the styles SAVE and OPEN may be specified.
+ * </p><p>
* IMPORTANT: This class is intended to be subclassed <em>only</em>
* within the SWT implementation.
* </p>
@@ -82,7 +84,8 @@
/**
* Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path, or an
+ * empty string if no such file has been selected.
*
* @return the relative path of the file
*/
@@ -91,8 +94,8 @@
}
/**
- * Returns the paths of all files that were selected
- * in the dialog relative to the filter path.
+ * Returns a (possibly empty) array with the paths of all files
+ * that were selected in the dialog relative to the filter path.
*
* @return the relative paths of the files
*/
@@ -111,19 +114,19 @@
}
/**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
*
- * @return the file name filter
+ * @return the list of filter names
*/
public String [] getFilterNames () {
return filterNames;
}
/**
- * Returns the directory path that the dialog will use.
- * File names in this path will appear in the dialog,
- * filtered according to the filter extensions.
+ * Returns the directory path that the dialog will use, or an empty
+ * string if this is not set. File names in this path will appear
+ * in the dialog, filtered according to the filter extensions.
*
* @return the directory path string
*
@@ -300,6 +303,11 @@
* Set the file extensions which the dialog will
* use to filter the files it shows to the argument,
* which may be null.
+ * <p>
+ * The strings are platform specific. For example, on
+ * Windows, an extension filter string is typically of
+ * the form "*.extension", where "*.*" matches all files.
+ * </p>
*
* @param extensions the file extension filter
*/
@@ -308,11 +316,11 @@
}
/**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
*
- * @param names the file name filter
+ * @param names the list of filter names
*/
public void setFilterNames (String [] names) {
filterNames = names;
@@ -322,7 +330,14 @@
* Sets the directory path that the dialog will use
* to the argument, which may be null. File names in this
* path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
*
* @param string the directory path
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
index b5bbb2f..f1ca24e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java
@@ -24,6 +24,7 @@
* <p>
* <dl>
* <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
* <dt><b>Events:</b></dt>
* <dd>Selection</dd>
* </dl>
@@ -665,7 +666,7 @@
* is delimited by an anchor tag, <A> and </A>. Within an
* anchor, a single HREF attribute is supported. When a hyperlink is
* selected, the text field of the selection event contains either the
- * text of hyperlink or the value of the HREF, if one was specified.
+ * text of the hyperlink or the value of its HREF, if one was specified.
* In the rare case of identical hyperlinks within the same string, the
* HREF tag can be used to distinguish between them. The string may
* include the mnemonic character and line delimiters.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java
index e20bd08..271d9fd 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java
@@ -22,7 +22,7 @@
/**
* Instances of this class represent a selectable user interface
- * object that displays a list of strings and issues notificiation
+ * object that displays a list of strings and issues notification
* when a string selected. A list may be single or multi select.
* <p>
* <dl>
@@ -504,7 +504,7 @@
/**
* Returns the height of the area which would be used to
- * display <em>one</em> of the items in the tree.
+ * display <em>one</em> of the items in the list.
*
* @return the height of one item
*
@@ -523,8 +523,8 @@
}
/**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>String</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -547,8 +547,8 @@
/**
* Returns an array of <code>String</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -605,7 +605,7 @@
* Returns the zero-relative index of the item which is currently
* selected in the receiver, or -1 if no item is selected.
*
- * @return the index of the selected item
+ * @return the index of the selected item or -1
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -621,7 +621,8 @@
/**
* Returns the zero-relative indices of the items which are currently
- * selected in the receiver. The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1258,7 +1259,7 @@
/**
* Selects the item at the given zero-relative index in the receiver.
* If the item at the index was already selected, it remains selected.
- * The current selected is first cleared, then the new items are selected.
+ * The current selection is first cleared, then the new item is selected.
* Indices that are out of range are ignored.
*
* @param index the index of the item to select
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java
index 60bf8a0..7616426 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java
@@ -366,7 +366,7 @@
/**
* Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -422,8 +422,8 @@
}
/**
- * Returns an array of <code>MenuItem</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>MenuItem</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -806,7 +806,7 @@
/**
* Returns <code>true</code> if the receiver is enabled and all
* of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu is typically not selectable from the
* user interface and draws with an inactive or "grayed" look.
*
* @return the receiver's enabled state
@@ -961,7 +961,7 @@
/**
* Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -984,11 +984,15 @@
}
/**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
* <p>
- * Note: This is different from most widgets where the
+ * Note that this is different from most widgets where the
* location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
* </p>
*
* @param x the new x coordinate for the receiver
@@ -1007,11 +1011,15 @@
}
/**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
* <p>
- * Note: This is different from most widgets where the
+ * Note that this is different from most widgets where the
* location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
* </p>
*
* @param location the new location for the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java
index 924a5f2..2d28134 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java
@@ -172,7 +172,7 @@
/**
* Adds the listener to the collection of listeners who will
- * be notified when the control is selected, by sending
+ * be notified when the menu item is selected, by sending
* it one of the messages defined in the <code>SelectionListener</code>
* interface.
* <p>
@@ -241,11 +241,13 @@
}
/**
- * Return the widget accelerator. An accelerator is the bit-wise
+ * Returns the widget accelerator. An accelerator is the bit-wise
* OR of zero or more modifier masks and a key. Examples:
* <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
*
- * @return the accelerator
+ * @return the accelerator or 0
*
* </ul>
* @exception SWTException <ul>
@@ -285,7 +287,7 @@
/**
* Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu item is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -392,7 +394,7 @@
/**
* Returns <code>true</code> if the receiver is enabled and all
* of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu item is typically not selectable from the
* user interface and draws with an inactive or "grayed" look.
*
* @return the receiver's enabled state
@@ -552,6 +554,8 @@
* OR of zero or more modifier masks and a key. Examples:
* <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>.
* <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
*
* @param accelerator an integer that is the bit-wise OR of masks and a key
*
@@ -595,7 +599,7 @@
/**
* Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu item is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -627,8 +631,9 @@
/**
* Sets the image the receiver will display to the argument.
* <p>
- * Note: This feature is not available on all window systems (for example, Window NT),
- * in which case, calling this method will silently do nothing.
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept (for example, Windows NT).
+ * </p>
*
* @param image the image to display
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java
index 79f6c5f..82e859a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java
@@ -102,9 +102,9 @@
}
/**
- * Returns the dialog's message, which is a description of
- * the purpose for which it was opened. This message will be
- * visible on the dialog while it is open.
+ * Returns the dialog's message, or an empty string if it does not have one.
+ * The message is a description of the purpose for which the dialog was opened.
+ * This message will be visible in the dialog while it is open.
*
* @return the message
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java
index d3dd8b3..1448c98 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java
@@ -134,7 +134,7 @@
}
/**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the single 'selection' that is the receiver's position.
*
* @return the selection
*
@@ -193,7 +193,7 @@
}
/**
- * Sets the single <em>selection</em> that is the receiver's
+ * Sets the single 'selection' that is the receiver's
* position to the argument which must be greater than or equal
* to zero.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java
index 2b0be7a..03b412d 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java
@@ -204,7 +204,7 @@
}
/**
- * Returns the <em>selection</em>, which is the receiver's position.
+ * Returns the 'selection', which is the receiver's position.
*
* @return the selection
*
@@ -350,9 +350,8 @@
}
/**
- * Sets the <em>selection</em>, which is the receiver's
- * value, to the argument which must be greater than or equal
- * to zero.
+ * Sets the 'selection', which is the receiver's value,
+ * to the argument which must be greater than or equal to zero.
*
* @param value the new selection (must be zero or greater)
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java
index f1e5bcf..336499e 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java
@@ -23,7 +23,7 @@
* objects that represent a range of positive, numeric values.
* <p>
* At any given moment, a given scroll bar will have a
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
* value, which is constrained to be within the range of
* values the scroll bar represents (that is, between its
* <em>minimum</em> and <em>maximum</em> values).
@@ -106,6 +106,7 @@
* interface.
* <p>
* When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
+ * <code>SWT.NONE</code> - for the end of a drag.
* <code>SWT.DRAG</code>.
* <code>SWT.HOME</code>.
* <code>SWT.END</code>.
@@ -301,7 +302,7 @@
}
/**
- * Returns the receiver's parent, which must be scrollable.
+ * Returns the receiver's parent, which must be a Scrollable.
*
* @return the receiver's parent
*
@@ -316,7 +317,7 @@
}
/**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the single 'selection' that is the receiver's value.
*
* @return the selection
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
index 8a3edd4..7afa773 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java
@@ -70,7 +70,7 @@
* it would be upgraded to <code>APPLICATION_MODAL</code>.
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd>
+ * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd>
* <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd>
* <dt><b>Events:</b></dt>
* <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd>
@@ -268,7 +268,7 @@
* @param parent a shell which will be the parent of the new instance
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -302,6 +302,9 @@
* @param parent a shell which will be the parent of the new instance
* @param style the style of control to construct
*
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
+ * </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
@@ -316,6 +319,8 @@
* @see SWT#NO_TRIM
* @see SWT#SHELL_TRIM
* @see SWT#DIALOG_TRIM
+ * @see SWT#ON_TOP
+ * @see SWT#TOOL
* @see SWT#MODELESS
* @see SWT#PRIMARY_MODAL
* @see SWT#APPLICATION_MODAL
@@ -1297,7 +1302,7 @@
}
/**
- * Sets the receiver's minimum size to the point specified by the arguments.
+ * Sets the receiver's minimum size to the size specified by the arguments.
* If the new minimum size is larger than the current size of the receiver,
* the receiver is resized to the new minimum size.
*
@@ -1334,7 +1339,7 @@
}
/**
- * Sets the receiver's minimum size to the point specified by the argument.
+ * Sets the receiver's minimum size to the size specified by the argument.
* If the new minimum size is larger than the current size of the receiver,
* the receiver is resized to the new minimum size.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java
index 30825a4..96af397 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java
@@ -23,7 +23,7 @@
* objects that represent a range of positive, numeric values.
* <p>
* At any given moment, a given slider will have a
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
* value, which is constrained to be within the range of
* values the slider represents (that is, between its
* <em>minimum</em> and <em>maximum</em> values).
@@ -111,7 +111,7 @@
* interface.
* <p>
* When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
- * <code>0</code> - for the end of a drag.
+ * <code>SWT.NONE</code> - for the end of a drag.
* <code>SWT.DRAG</code>.
* <code>SWT.HOME</code>.
* <code>SWT.END</code>.
@@ -279,7 +279,7 @@
}
/**
- * Returns the <em>selection</em>, which is the receiver's value.
+ * Returns the 'selection', which is the receiver's value.
*
* @return the selection
*
@@ -475,7 +475,7 @@
}
/**
- * Sets the <em>selection</em>, which is the receiver's
+ * Sets the 'selection', which is the receiver's
* value, to the argument which must be greater than or equal
* to zero.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
index 45c9ab5..ac7393a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java
@@ -27,7 +27,7 @@
* <p>
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>READ_ONLY</dd>
+ * <dd>READ_ONLY, WRAP</dd>
* <dt><b>Events:</b></dt>
* <dd>Selection, Modify</dd>
* </dl>
@@ -69,6 +69,7 @@
* </ul>
*
* @see SWT#READ_ONLY
+ * @see SWT#WRAP
* @see Widget#checkSubclass
* @see Widget#getStyle
*/
@@ -363,6 +364,16 @@
return textHandle;
}
+/**
+ * Returns the number of decimal places used by the receiver.
+ *
+ * @return the digits
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
public int getDigits () {
checkWidget ();
return digits;
@@ -797,6 +808,25 @@
setBackground (textHandle, color);
}
+/**
+ * Sets the number of decimal places used by the receiver.
+ * <p>
+ * The digit setting is used to allow for floating point values in the receiver.
+ * For example, to set the selection to a floating point value of 1.37 call setDigits() with
+ * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value
+ * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all
+ * numeric APIs.
+ *
+ * @param value the new digits (must be greater than or equal to zero)
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
public void setDigits (int value) {
checkWidget ();
if (value < 0) error (SWT.ERROR_INVALID_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java
index b919388..d497864 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java
@@ -90,6 +90,7 @@
* @see SWT#CHECK
* @see SWT#FULL_SELECTION
* @see SWT#HIDE_SELECTION
+ * @see SWT#VIRTUAL
* @see Widget#checkSubclass
* @see Widget#getStyle
*/
@@ -1236,8 +1237,8 @@
}
/**
- * Returns an array of <code>TableItem</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>TableItem</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -1288,8 +1289,8 @@
/**
* Returns an array of <code>TableItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1362,7 +1363,8 @@
/**
* Returns the zero-relative indices of the items which are currently
- * selected in the receiver. The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -2313,7 +2315,7 @@
/**
* Selects the item at the given zero-relative index in the receiver.
- * The current selected is first cleared, then the new item is selected.
+ * The current selection is first cleared, then the new item is selected.
*
* @param index the index of the item to select
*
@@ -2507,8 +2509,8 @@
* @param column the column to be shown
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the item is null</li>
- * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li>
+ * <li>ERROR_NULL_ARGUMENT - if the column is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the column has been disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java
index 2901f4d..577c533 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java
@@ -160,7 +160,6 @@
* </ul>
*
* @since 2.0
- *
*/
public Color getBackground () {
checkWidget ();
@@ -298,7 +297,6 @@
* </ul>
*
* @since 2.0
- *
*/
public Color getForeground () {
checkWidget ();
@@ -379,7 +377,8 @@
/**
* Returns a rectangle describing the size and location
* relative to its parent of an image at a column in the
- * table.
+ * table. An empty rectangle is returned if index exceeds
+ * the index of the table's last column.
*
* @param index the index that specifies the column
* @return the receiver's bounding image rectangle
@@ -546,7 +545,6 @@
* </ul>
*
* @since 2.0
- *
*/
public void setBackground (Color color) {
checkWidget ();
@@ -576,7 +574,6 @@
* </ul>
*
* @since 3.0
- *
*/
public void setBackground (int index, Color color) {
checkWidget ();
@@ -692,7 +689,6 @@
* </ul>
*
* @since 2.0
- *
*/
public void setForeground (Color color) {
checkWidget ();
@@ -722,7 +718,6 @@
* </ul>
*
* @since 3.0
- *
*/
public void setForeground (int index, Color color){
checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java
index 3574bee..54b8e66 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java
@@ -45,6 +45,10 @@
/**
* The maximum number of characters that can be entered
* into a text widget.
+ * <p>
+ * Note that this value is platform dependent, based upon
+ * the native widget implementation.
+ * </p>
*/
public static final int LIMIT;
/**
@@ -446,7 +450,7 @@
}
/**
- * Gets the line number of the caret.
+ * Returns the line number of the caret.
* <p>
* The line number of the caret is returned.
* </p>
@@ -465,7 +469,8 @@
}
/**
- * Gets the location the caret.
+ * 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>
@@ -489,9 +494,9 @@
}
/**
- * Gets the position of the caret.
+ * Returns the character position of the caret.
* <p>
- * The character position of the caret is returned.
+ * Indexing is zero based.
* </p>
*
* @return the position of the caret
@@ -509,7 +514,7 @@
}
/**
- * Gets the number of characters.
+ * Returns the number of characters.
*
* @return number of characters in the widget
*
@@ -534,7 +539,7 @@
}
/**
- * Gets the double click enabled flag.
+ * Returns the double click enabled flag.
* <p>
* The double click flag enables or disables the
* default action of the text widget when the user
@@ -555,7 +560,7 @@
}
/**
- * Gets the echo character.
+ * Returns the echo character.
* <p>
* The echo character is the character that is
* displayed when the user enters text or the
@@ -568,6 +573,8 @@
* <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 #setEchoChar
*/
public char getEchoChar () {
checkWidget();
@@ -575,7 +582,7 @@
}
/**
- * Gets the editable state.
+ * Returns the editable state.
*
* @return whether or not the reciever is editable
*
@@ -590,7 +597,7 @@
}
/**
- * Gets the number of lines.
+ * Returns the number of lines.
*
* @return the number of lines in the widget
*
@@ -607,7 +614,7 @@
}
/**
- * Gets the line delimiter.
+ * Returns the line delimiter.
*
* @return a string that is the line delimiter
*
@@ -615,6 +622,8 @@
* <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 #DELIMITER
*/
public String getLineDelimiter () {
checkWidget();
@@ -622,7 +631,7 @@
}
/**
- * Gets the height of a line.
+ * Returns the height of a line.
*
* @return the height of a row of text
*
@@ -639,7 +648,8 @@
}
/**
- * Returns the orientation of the receiver.
+ * Returns the orientation of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
*
* @return the orientation style
*
@@ -656,14 +666,17 @@
}
/**
- * Gets the position of the selected text.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selected
+ * text, and whose y coordinate is the character position
+ * representing the end of the selection. An "empty" selection
+ * is indicated by the x and y coordinates having the same value.
* <p>
- * Indexing is zero based. The range of
- * a selection is from 0..N where N is
- * the number of characters in the widget.
+ * Indexing is zero based. The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
* </p>
- *
- * @return the start and end of the selection
+ *
+ * @return a point representing the selection start and end
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -678,7 +691,7 @@
}
/**
- * Gets the number of selected characters.
+ * Returns the number of selected characters.
*
* @return the number of selected characters.
*
@@ -695,7 +708,7 @@
}
/**
- * Gets the selected text.
+ * Gets the selected text, or an empty string if there is no current selection.
*
* @return the selected text
*
@@ -710,7 +723,7 @@
}
/**
- * Gets the number of tabs.
+ * Returns the number of tabs.
* <p>
* Tab stop spacing is specified in terms of the
* space (' ') character. The width of a single
@@ -731,9 +744,10 @@
}
/**
- * Gets the widget text.
+ * Returns the widget text.
* <p>
- * The text for a text widget is the characters in the widget.
+ * The text for a text widget is the characters in the widget, or
+ * an empty string if this has never been set.
* </p>
*
* @return the widget text
@@ -749,7 +763,7 @@
}
/**
- * Gets a range of text. Returns an empty string if the
+ * Returns a range of text. Returns an empty string if the
* start of the range is greater than the end.
* <p>
* Indexing is zero based. The range of
@@ -788,6 +802,8 @@
* <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 #LIMIT
*/
public int getTextLimit () {
checkWidget();
@@ -815,7 +831,7 @@
}
/**
- * Gets the top pixel.
+ * Returns the top pixel.
* <p>
* The top pixel is the pixel position of the line
* that is currently at the top of the widget. On
@@ -888,6 +904,9 @@
*
* @param string the string
*
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></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>
@@ -1228,6 +1247,9 @@
* The double click flag enables or disables the
* default action of the text widget when the user
* double clicks.
+ * </p><p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
* </p>
*
* @param doubleClick the new double click flag
@@ -1251,8 +1273,9 @@
* the echo character to '\0' clears the echo
* character and redraws the original text.
* If for any reason the echo character is invalid,
- * the default echo character for the platform
- * is used.
+ * or if the platform does not allow modification
+ * of the echo character, the default echo character
+ * for the platform is used.
* </p>
*
* @param echo the new echo character
@@ -1336,6 +1359,9 @@
* Sets the orientation of the receiver, which must be one
* of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
* <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
*
* @param orientation new orientation style
*
@@ -1379,7 +1405,8 @@
}
/**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given start and end indices.
* <p>
* Indexing is zero based. The range of
* a selection is from 0..N where N is
@@ -1412,7 +1439,10 @@
}
/**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given point, where the x coordinate
+ * represents the start index and the y coordinate
+ * represents the end index.
* <p>
* Indexing is zero based. The range of
* a selection is from 0..N where N is
@@ -1556,6 +1586,8 @@
* creating a read-only text widget.
* </p><p>
* To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Text.LIMIT</code> sets the
+ * receiver's limit to <code>Text.LIMIT</code>.
* </p>
*
* @param limit new text limit
@@ -1567,6 +1599,8 @@
* <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 #LIMIT
*/
public void setTextLimit (int limit) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java
index e998fc1..d31b639 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java
@@ -24,7 +24,7 @@
/**
* Instances of this class provide a selectable user interface object
- * that displays a hierarchy of items and issue notificiation when an
+ * that displays a hierarchy of items and issue notification when an
* item in the hierarchy is selected.
* <p>
* The item children that may be added to instances of this class
@@ -921,6 +921,23 @@
return height [0] != 0;
}
+/**
+ * Returns the item at the given, zero-relative index in the
+ * receiver. Throws an exception if the index is out of range.
+ *
+ * @param index the index of the item to return
+ * @return the item at the given index
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public TreeItem getItem (int index) {
checkWidget ();
if (index < 0) error (SWT.ERROR_INVALID_RANGE);
@@ -1024,8 +1041,8 @@
}
/**
- * Returns the items contained in the receiver
- * that are direct item children of the receiver. These
+ * Returns a (possibly empty) array of items contained in the
+ * receiver that are direct item children of the receiver. These
* are the roots of the tree.
* <p>
* Note: This is not the actual structure used by the receiver
@@ -1103,8 +1120,8 @@
/**
* Returns an array of <code>TreeItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1219,6 +1236,25 @@
OS.SetDataBrowserCustomCallbacks (handle, custom);
}
+/**
+ * Searches the receiver's list starting at the first column
+ * (index 0) until a column is found that is equal to the
+ * argument, and returns the index of that column. If no column
+ * is found, returns -1.
+ *
+ * @param column the search column
+ * @return the index of the column
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the string is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int indexOf (TreeColumn column) {
checkWidget ();
if (column == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -1229,6 +1265,26 @@
return -1;
}
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int indexOf (TreeItem item) {
checkWidget ();
if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java
index c9d3b0d..5031e7c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java
@@ -58,7 +58,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
*
* @exception IllegalArgumentException <ul>
@@ -94,7 +94,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
* @param index the index to store the receiver in its parent
*
@@ -132,7 +132,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
*
* @exception IllegalArgumentException <ul>
@@ -169,7 +169,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
* @param index the index to store the receiver in its parent
*
@@ -544,6 +544,23 @@
return new Rectangle (x, y, width, height);
}
+/**
+ * Returns the item at the given, zero-relative index in the
+ * receiver. Throws an exception if the index is out of range.
+ *
+ * @param index the index of the item to return
+ * @return the item at the given index
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public TreeItem getItem (int index) {
checkWidget ();
if (index < 0) error (SWT.ERROR_INVALID_RANGE);
@@ -577,8 +594,8 @@
}
/**
- * Returns an array of <code>TreeItem</code>s which are the
- * direct item children of the receiver.
+ * Returns a (possibly empty) array of <code>TreeItem</code>s which
+ * are the direct item children of the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -663,6 +680,26 @@
return "";
}
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int indexOf (TreeItem item) {
checkWidget ();
if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -723,6 +760,16 @@
cellFont = null;
}
+/**
+ * Removes all of the items from the receiver.
+ * <p>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void removeAll () {
checkWidget ();
TreeItem [] items = parent.items;
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
index 4d91a6f..669d93a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java
@@ -96,6 +96,7 @@
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -741,7 +742,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
* </ul>
*
- * @see #setData
+ * @see #setData(Object)
*/
public Object getData () {
checkWidget();
@@ -770,7 +771,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #setData
+ * @see #setData(String, Object)
*/
public Object getData (String key) {
checkWidget();
@@ -797,7 +798,6 @@
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
- * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*/
public Display getDisplay () {
@@ -1544,6 +1544,8 @@
* <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li>
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
* </ul>
+ *
+ * @see #getData()
*/
public void setData (Object data) {
checkWidget();
@@ -1576,7 +1578,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #getData
+ * @see #getData(String)
*/
public void setData (String key, Object value) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java
index bec30ed..b4b17c7 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/coolbar/org/eclipse/swt/widgets/CoolItem.java
@@ -201,9 +201,9 @@
* @see Layout
* @see #getBounds
* @see #getSize
- * @see CoolBar#getBorderWidth
- * @see CoolBar#computeTrim
- * @see CoolBar#getClientArea
+ * @see Control#getBorderWidth
+ * @see Scrollable#computeTrim
+ * @see Scrollable#getClientArea
*/
public Point computeSize (int wHint, int hHint) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
index 0613f50..d8fdff2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Path.java
@@ -13,16 +13,46 @@
import org.eclipse.swt.*;
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent paths through the two-dimensional
+ * coordinate system. Paths do not have to be continuous, and can be
+ * described using lines, rectangles, arcs, cubic or quadratic bezier curves,
+ * glyphs, or other paths.
+ * <p>
+ * Application code must explicitly invoke the <code>Path.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
*/
public class Path extends Resource {
/**
- * the handle to the OS path resource
+ * the OS resource for the Path
* (Warning: This field is platform dependent)
+ * <p>
+ * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+ * public API. It is marked public only so that it can be shared
+ * within the packages provided by SWT. It is not available on all
+ * platforms and should never be accessed from application code.
+ * </p>
*/
public int handle;
+/**
+ * Constructs a new empty Path.
+ *
+ * @param device the device on which to allocate the path
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the path could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Path (Device device) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -32,26 +62,120 @@
if (device.tracking) device.new_Object(this);
}
+/**
+ * Adds to the receiver a circular or elliptical arc that lies within
+ * the specified rectangular area.
+ * <p>
+ * The resulting arc begins at <code>startAngle</code> and extends
+ * for <code>arcAngle</code> degrees.
+ * Angles are interpreted such that 0 degrees is at the 3 o'clock
+ * position. A positive value indicates a counter-clockwise rotation
+ * while a negative value indicates a clockwise rotation.
+ * </p><p>
+ * The center of the arc is the center of the rectangle whose origin
+ * is (<code>x</code>, <code>y</code>) and whose size is specified by the
+ * <code>width</code> and <code>height</code> arguments.
+ * </p><p>
+ * The resulting arc covers an area <code>width + 1</code> pixels wide
+ * by <code>height + 1</code> pixels tall.
+ * </p>
+ *
+ * @param x the x coordinate of the upper-left corner of the arc
+ * @param y the y coordinate of the upper-left corner of the arc
+ * @param width the width of the arc
+ * @param height the height of the arc
+ * @param startAngle the beginning angle
+ * @param arcAngle the angular extent of the arc, relative to the start angle
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addArc(float x, float y, float width, float height, float startAngle, float arcAngle) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Adds to the receiver the path described by the parameter.
+ *
+ * @param path the path to add to the receiver
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addPath(Path path) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (path == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
if (path.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
}
+/**
+ * Adds to the receiver the rectangle specified by x, y, width and height.
+ *
+ * @param x the x coordinate of the rectangle to add
+ * @param y the y coordinate of the rectangle to add
+ * @param width the width of the rectangle to add
+ * @param height the height of the rectangle to add
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addRectangle(float x, float y, float width, float height) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Adds to the receiver the pattern of glyphs generated by drawing
+ * the given string using the given font starting at the point (x, y).
+ *
+ * @param string the text to use
+ * @param x the x coordinate of the starting point
+ * @param y the y coordinate of the starting point
+ * @param font the font to use
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the font is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the font has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void addString(String string, float x, float y, Font font) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (font == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
if (font.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
}
+/**
+ * Returns <code>true</code> if the specified point is contained by
+ * the receiver and false otherwise.
+ * <p>
+ * If outline is <code>true</code>, the point (x, y) checked for containment in
+ * the receiver's outline. If outline is <code>false</code>, the point is
+ * checked to see if it is contained within the bounds of the (closed) area
+ * covered by the receiver.
+ *
+ * @param x the x coordinate of the point to test for containment
+ * @param y the y coordinate of the point to test for containment
+ * @param gc the GC to use when testing for containment
+ * @param outline controls wether to check the outline or contained area of the path
+ * @return <code>true</code> if the path contains the point and <code>false</code> otherwise
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the gc is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public boolean contains(float x, float y, GC gc, boolean outline) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (gc == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -59,6 +183,15 @@
return false;
}
+/**
+ * Closes the current sub path by adding to the receiver a line
+ * from the current point of the path back to the starting point
+ * of the sub path.
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void close() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
@@ -67,30 +200,99 @@
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Replaces the first four elements in the parameter with values that
+ * describe the smallest rectangle that will completely contain the
+ * receiver (i.e. the bounding box).
+ *
+ * @param bounds the array to hold the result
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the bounding box</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void getBounds(float[] bounds) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (bounds == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
if (bounds.length < 4) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
}
+/**
+ * Replaces the first two elements in the parameter with values that
+ * describe the current point of the path.
+ *
+ * @param point the array to hold the result
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the end point</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void getCurrentPoint(float[] point) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (point == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
if (point.length < 2) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
}
+/**
+ * Adds to the receiver a line from the current point to
+ * the point specified by (x, y).
+ *
+ * @param x the x coordinate of the end of the line to add
+ * @param y the y coordinate of the end of the line to add
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void lineTo(float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Sets the current point of the receiver to the point
+ * specified by (x, y). Note that this starts a new
+ * sub path.
+ *
+ * @param x the x coordinate of the new end point
+ * @param y the y coordinate of the new end point
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void moveTo(float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Adds to the receiver a quadratic curve based on the parameters.
+ *
+ * @param cx the x coordinate of the control point of the spline
+ * @param cy the y coordinate of the control point of the spline
+ * @param x the x coordinate of the end point of the spline
+ * @param y the y coordinate of the end point of the spline
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void quadTo(float cx, float cy, float x, float y) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Path. Applications must dispose of all Paths that
+ * they allocate.
+ */
public void dispose() {
if (handle == 0) return;
handle = 0;
@@ -98,10 +300,26 @@
device = null;
}
+/**
+ * Returns <code>true</code> if the Path has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Path.
+ * When a Path has been disposed, it is an error to
+ * invoke any other method using the Path.
+ *
+ * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return handle == 0;
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString() {
if (isDisposed()) return "Path {*DISPOSED*}";
return "Path {" + handle + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
index 48967f3..c0a8d2c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Pattern.java
@@ -13,16 +13,47 @@
import org.eclipse.swt.*;
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent patterns to use while drawing. Patterns
+ * can be specified either as bitmaps or gradients.
+ * <p>
+ * Application code must explicitly invoke the <code>Pattern.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
*/
public class Pattern extends Resource {
/**
- * the handle to the OS path resource
+ * the OS resource for the Pattern
* (Warning: This field is platform dependent)
+ * <p>
+ * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+ * public API. It is marked public only so that it can be shared
+ * within the packages provided by SWT. It is not available on all
+ * platforms and should never be accessed from application code.
+ * </p>
*/
public int handle;
+/**
+ * Constructs a new Pattern given an image. Drawing with the resulting
+ * pattern will cause the image to be tiled over the resulting area.
+ *
+ * @param device the device on which to allocate the pattern
+ * @param image the image that the pattern will draw
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device, or the image is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Pattern(Device device, Image image) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -33,6 +64,30 @@
if (device.tracking) device.new_Object(this);
}
+/**
+ * Constructs a new Pattern that represents a linear, two color
+ * gradient. Drawing with the pattern will cause the resulting area to be
+ * tiled with the gradient specified by the arguments.
+ *
+ * @param device the device on which to allocate the pattern
+ * @param x1 the x coordinate of the starting corner of the gradient
+ * @param y1 the y coordinate of the starting corner of the gradient
+ * @param x2 the x coordinate of the ending corner of the gradient
+ * @param y2 the y coordinate of the ending corner of the gradient
+ * @param color1 the starting color of the gradient
+ * @param color2 the ending color of the gradient
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device,
+ * or if either color1 or color2 is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if either color1 or color2 has been disposed</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the pattern could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Pattern(Device device, float x1, float y1, float x2, float y2, Color color1, Color color2) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -45,6 +100,11 @@
if (device.tracking) device.new_Object(this);
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Pattern. Applications must dispose of all Patterns that
+ * they allocate.
+ */
public void dispose() {
if (handle == 0) return;
if (device.isDisposed()) return;
@@ -53,10 +113,26 @@
device = null;
}
+/**
+ * Returns <code>true</code> if the Pattern has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Pattern.
+ * When a Pattern has been disposed, it is an error to
+ * invoke any other method using the Pattern.
+ *
+ * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return handle == 0;
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString() {
if (isDisposed()) return "Pattern {*DISPOSED*}";
return "Pattern {" + handle + "}";
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
index bc15868..4d75e26 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/graphics/org/eclipse/swt/graphics/Transform.java
@@ -13,23 +13,89 @@
import org.eclipse.swt.*;
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Instances of this class represent transformation matrices for
+ * points expressed as (x, y) pairs of floating point numbers.
+ * <p>
+ * Application code must explicitly invoke the <code>Transform.dispose()</code>
+ * method to release the operating system resources managed by each instance
+ * when those instances are no longer required.
+ * </p>
+ *
+ * @since 3.1
*/
public class Transform extends Resource {
/**
- * the handle to the OS path resource
+ * the OS resource for the Transform
* (Warning: This field is platform dependent)
+ * <p>
+ * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
+ * public API. It is marked public only so that it can be shared
+ * within the packages provided by SWT. It is not available on all
+ * platforms and should never be accessed from application code.
+ * </p>
*/
public int handle;
+/**
+ * Constructs a new identity Transform.
+ *
+ * @param device the device on which to allocate the Transform
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform (Device device) {
this(device, 1, 0, 0, 1, 0, 0);
}
+/**
+ * Constructs a new Transform given an array of elements that represent the
+ * matrix that describes the transformation.
+ *
+ * @param device the device on which to allocate the Transform
+ * @param elements an array of floats that describe the transformation matrix
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device, or the elements array is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the elements array is too small to hold the matrix values</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform(Device device, float[] elements) {
this (device, checkTransform(elements)[0], elements[1], elements[2], elements[3], elements[4], elements[5]);
}
+/**
+ * Constructs a new Transform given all of the elements that represent the
+ * matrix that describes the transformation.
+ *
+ * @param device the device on which to allocate the Transform
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ * </ul>
+ * @exception SWTError <ul>
+ * <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained/li>
+ * </ul>
+ *
+ * @see #dispose()
+ */
public Transform (Device device, float m11, float m12, float m21, float m22, float dx, float dy) {
if (device == null) device = Device.getDevice();
if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -44,6 +110,11 @@
return elements;
}
+/**
+ * Disposes of the operating system resources associated with
+ * the Transform. Applications must dispose of all Transforms that
+ * they allocate.
+ */
public void dispose() {
if (handle == 0) return;
if (device.isDisposed()) return;
@@ -52,20 +123,60 @@
device = null;
}
+/**
+ * Fills the parameter with the values of the transformation matrix
+ * that the receiver represents, in the order {m11, m12, m21, m22, dx, dy}.
+ *
+ * @param elements array to hold the matrix values
+ * @return (in elements array) the transformation matrix represented by the receiver
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the matrix values</li>
+ * </ul>
+ */
public void getElements(float[] elements) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
if (elements.length < 6) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
}
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the mathematical inverse of the matrix it previously represented.
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_CANNOT_INVERT_MATRIX - if the matrix is not invertable</li>
+ * </ul>
+ */
public void invert() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Returns <code>true</code> if the Transform has been disposed,
+ * and <code>false</code> otherwise.
+ * <p>
+ * This method gets the dispose state for the Transform.
+ * When a Transform has been disposed, it is an error to
+ * invoke any other method using the Transform.
+ *
+ * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
+ */
public boolean isDisposed() {
return handle == 0;
}
+/**
+ * Returns <code>true</code> if the Transform represents the identity matrix
+ * and false otherwise.
+ *
+ * @return <code>true</code> if the receiver is an identity Transform, and <code>false</code> otherwise
+ */
public boolean isIdentity() {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
float[] m = new float[6];
@@ -73,33 +184,118 @@
return m[0] == 1 && m[1] == 0 && m[2] == 0 && m[3] == 1 && m[4] == 0 && m[5] == 0;
}
+/**
+ * Modifies the receiver such that the matrix it represents becomes the
+ * the result of multiplying the matrix it previously represented by the
+ * argument.
+ *
+ * @param matrix the matrix to multiply the receiver by
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ */
public void multiply(Transform matrix) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (matrix == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
if (matrix.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation rotated by the specified angle.
+ * The angle is specified in degrees and for the identity transform 0 degrees
+ * is at the 3 o'clock position. A positive value indicates a clockwise rotation
+ * while a negative value indicates a counter-clockwise rotation.
+ *
+ * @param angle the angle to rotate the transformation by
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void rotate(float angle) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation scaled by (scaleX, scaleY).
+ *
+ * @param scaleX the amount to scale in the X direction
+ * @param scaleY the amount to scale in the Y direction
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void scale(float scaleX, float scaleY) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Modifies the receiver to represent a new transformation given all of
+ * the elements that represent the matrix that describes that transformation.
+ *
+ * @param m11 the first element of the first row of the matrix
+ * @param m12 the second element of the first row of the matrix
+ * @param m21 the first element of the second row of the matrix
+ * @param m22 the second element of the second row of the matrix
+ * @param dx the third element of the first row of the matrix
+ * @param dy the third element of the second row of the matrix
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void setElements(float m11, float m12, float m21, float m22, float dx, float dy) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Given an array containing points described by alternating x and y values,
+ * modify that array such that each point has been replaced with the result of
+ * applying the transformation represented by the receiver to that point.
+ *
+ * @param pointArray an array of alternating x and y values to be transformed
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the point array is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void transform(float[] pointArray) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
}
+/**
+ * Modifies the receiver so that it represents a transformation that is
+ * equivalent to its previous transformation translated by (offsetX, offsetY).
+ *
+ * @param offsetX the distance to translate in the X direction
+ * @param offsetY the distance to translate in the Y direction
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ */
public void translate(float offsetX, float offsetY) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
+/**
+ * Returns a string containing a concise, human-readable
+ * description of the receiver.
+ *
+ * @return a string representation of the receiver
+ */
public String toString() {
if (isDisposed()) return "Transform {*DISPOSED*}";
float[] elements = new float[6];
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java
index fe0616c..a55c4a9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Table.java
@@ -105,6 +105,7 @@
* @see SWT#CHECK
* @see SWT#FULL_SELECTION
* @see SWT#HIDE_SELECTION
+ * @see SWT#VIRTUAL
* @see Widget#checkSubclass
* @see Widget#getStyle
*/
@@ -933,8 +934,8 @@
return itemHeight;
}
/**
- * Returns an array of <code>TableItem</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>TableItem</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -987,8 +988,8 @@
}
/**
* Returns an array of <code>TableItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1049,7 +1050,8 @@
}
/**
* Returns the zero-relative indices of the items which are currently
- * selected in the receiver. The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -3171,7 +3173,7 @@
}
/**
* Selects the item at the given zero-relative index in the receiver.
- * The current selected is first cleared, then the new item is selected.
+ * The current selection is first cleared, then the new item is selected.
*
* @param index the index of the item to select
*
@@ -3300,8 +3302,8 @@
* @param column the column to be shown
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the item is null</li>
- * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li>
+ * <li>ERROR_NULL_ARGUMENT - if the column is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the column has been disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
index ea935ed..4465ca1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TableItem.java
@@ -753,7 +753,8 @@
/**
* Returns a rectangle describing the size and location
* relative to its parent of an image at a column in the
- * table.
+ * table. An empty rectangle is returned if index exceeds
+ * the index of the table's last column.
*
* @param index the index that specifies the column
* @return the receiver's bounding image rectangle
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java
index 1bbae92..b7883b4 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/Tree.java
@@ -17,7 +17,7 @@
/**
* Instances of this class provide a selectable user interface object
- * that displays a hierarchy of items and issue notificiation when an
+ * that displays a hierarchy of items and issue notification when an
* item in the hierarchy is selected.
* <p>
* The item children that may be added to instances of this class
@@ -694,12 +694,14 @@
* @return the item at the given index
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of root elements minus 1 (inclusive)</li>
+ * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
+ *
+ * @since 3.1
*/
public TreeItem getItem (int index) {
checkWidget ();
@@ -739,8 +741,8 @@
return itemHeight;
}
/**
- * Returns the items contained in the receiver
- * that are direct item children of the receiver. These
+ * Returns a (possibly empty) array of items contained in the
+ * receiver that are direct item children of the receiver. These
* are the roots of the tree.
* <p>
* Note: This is not the actual structure used by the receiver
@@ -810,8 +812,8 @@
}
/**
* Returns an array of <code>TreeItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1078,12 +1080,51 @@
gc.setForeground (display.getSystemColor (SWT.COLOR_WIDGET_DARK_SHADOW));
gc.drawLine (endX - 1, y, endX - 1, height - 1); /* dark outer shadow */
}
+/**
+ * Searches the receiver's list starting at the first column
+ * (index 0) until a column is found that is equal to the
+ * argument, and returns the index of that column. If no column
+ * is found, returns -1.
+ *
+ * @param column the search column
+ * @return the index of the column
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the string is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int indexOf (TreeColumn column) {
checkWidget ();
if (column == null) error (SWT.ERROR_NULL_ARGUMENT);
if (column.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT);
return column.getIndex ();
}
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int indexOf (TreeItem item) {
checkWidget ();
if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
index e1d6e4c..0cf96c9 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java
@@ -66,7 +66,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
*
* @exception IllegalArgumentException <ul>
@@ -111,7 +111,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
* @param index the index to store the receiver in its parent
*
@@ -158,7 +158,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
*
* @exception IllegalArgumentException <ul>
@@ -205,7 +205,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
* @param index the index to store the receiver in its parent
*
@@ -1082,19 +1082,21 @@
return -1;
}
/**
- * Returns the child item with the given, zero-relative index in the
+ * Returns the item at the given, zero-relative index in the
* receiver. Throws an exception if the index is out of range.
*
* @param index the index of the item to return
* @return the item at the given index
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of child elements minus 1 (inclusive)</li>
+ * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
+ *
+ * @since 3.1
*/
public TreeItem getItem (int index) {
checkWidget ();
@@ -1117,8 +1119,8 @@
return items.length;
}
/**
- * Returns an array of <code>TreeItem</code>s which are the
- * direct item children of the receiver.
+ * Returns a (possibly empty) array of <code>TreeItem</code>s which
+ * are the direct item children of the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -1238,6 +1240,26 @@
if (parentItem == null) return false;
return parentItem.hasAncestor (item);
}
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int indexOf (TreeItem item) {
checkWidget ();
if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -1578,6 +1600,8 @@
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
+ *
+ * @since 3.1
*/
public void removeAll () {
checkWidget ();
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 06b52e7..15f71c6 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
@@ -191,7 +191,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
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 a7f20b0..8c74fd0 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
@@ -417,7 +417,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java
index 2cd7ac8..ca2baf8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java
@@ -433,7 +433,7 @@
* specified in class <code>SWT</code>. Any value other
* than one of the SWT color constants which is passed
* in will result in the color black. This color should
- * not be free'd because it was allocated by the system,
+ * not be freed because it was allocated by the system,
* not the application.
*
* @param id the color constant
@@ -472,7 +472,7 @@
* Returns a reasonable font for applications to use.
* On some platforms, this will match the "default font"
* or "system font" if such can be found. This font
- * should not be free'd because it was allocated by the
+ * should not be freed because it was allocated by the
* system, not the application.
* <p>
* Typically, applications which want the default look
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 0137471..9b1d8b5 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
@@ -227,7 +227,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java
index 76b22c8..68798e3 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java
@@ -290,7 +290,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -392,7 +392,8 @@
/**
* Sets the style of the receiver to the argument which must
* be a bitwise OR of one or more of the <code>SWT</code>
- * constants NORMAL, BOLD and ITALIC.
+ * constants NORMAL, BOLD and ITALIC. All other style bits are
+ * ignored.
*
* @param style the new style for this <code>FontData</code>
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java
index 96b962c..8abe3cf 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java
@@ -117,7 +117,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
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 e44ada9..8c10ea7 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
@@ -195,6 +195,24 @@
public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY) {
copyArea(srcX, srcY, width, height, destX, destY, true);
}
+/**
+ * Copies a rectangular area of the receiver at the source
+ * position onto the receiver at the destination position.
+ *
+ * @param srcX the x coordinate in the receiver of the area to be copied
+ * @param srcY the y coordinate in the receiver of the area to be copied
+ * @param width the width of the area to copy
+ * @param height the height of the area to copy
+ * @param destX the x coordinate in the receiver of the area to copy to
+ * @param destY the y coordinate in the receiver of the area to copy to
+ * @param paint if <code>true</code> paint events will be generated for old and obscured areas
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY, boolean paint) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (width <= 0 || height <= 0) return;
@@ -354,7 +372,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void drawFocus(int x, int y, int width, int height) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -713,8 +731,22 @@
OS.gdk_draw_arc(data.drawable, handle, 0, x, y, width, height, 0, 23040);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Draws the path described by the parameter.
+ *
+ * @param path the path to draw
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void drawPath(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1259,7 +1291,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1372,8 +1404,22 @@
OS.gdk_gc_set_foreground(handle, color);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Fills the path described by the parameter.
+ *
+ * @param path the path to fill
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void fillPath (Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1458,7 +1504,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillRectangle(int x, int y, int width, int height) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1508,7 +1554,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillRectangle(Rectangle rect) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1648,13 +1694,45 @@
return stringExtent(new String(new char[]{ch})).x;
}
+/**
+ * Returns <code>true</code> if receiver is using the operating system's
+ * advanced graphics subsystem. Otherwise, <code>false</code> is returned
+ * to indicate that normal graphics are in use.
+ * <p>
+ * Advanced graphics may not be installed for the operating system. In this
+ * case, <code>false</code> is always returned. Some operating system have
+ * only one graphics subsystem. If this subsystem supports advanced graphics,
+ * then <code>true</code> is always returned. If any graphics operation such
+ * as alpha, antialias, patterns, interpolation, paths, clipping or transformation
+ * has caused the receiver to switch from regular to advanced graphics mode,
+ * <code>true</code> is returned. If the receiver has been explicitly switched
+ * to advanced mode and this mode is supported, <code>true</code> is returned.
+ * </p>
+ *
+ * @return the advanced value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAdvanced
+ * @since 3.1
+ */
public boolean getAdvanced() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return data.cairo != 0;
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's alpha value.
+ *
+ * @return the alpha value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public int getAlpha() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1663,7 +1741,20 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's anti-aliasing setting value, which will be
+ * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getTextAntialias
+ *
+ * @since 3.1
*/
public int getAntialias() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1691,8 +1782,19 @@
return Color.gtk_new(data.device, color);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the background pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's background pattern
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public Pattern getBackgroundPattern() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1791,6 +1893,18 @@
}
}
+/**
+ * Returns the receiver's fill rule, which will be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @return the receiver's fill rule
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int getFillRule() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
int /*long*/ cairo = data.cairo;
@@ -1858,16 +1972,37 @@
return Color.gtk_new(data.device, color);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the foreground pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's foreground pattern
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public Pattern getForegroundPattern() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return data.foregroundPattern;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the receiver's interpolation setting, which will be one of
+ * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>,
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @return the receiver's interpolation setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public int getInterpolation() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1901,7 +2036,8 @@
}
/**
- * Returns the receiver's line dash style.
+ * Returns the receiver's line dash style. The default value is
+ * <code>null</code>.
*
* @return the lin dash style used for drawing lines
*
@@ -2006,15 +2142,43 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's text drawing anti-aliasing setting value,
+ * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing
+ * <em>only</em> for text drawing operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getAntialias
+ *
+ * @since 3.1
*/
public int getTextAntialias() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return data.textAntialias;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the parameter to the transform that is currently being
+ * used by the receiver.
+ *
+ * @param transform the destination to copy the transform into
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Transform
+ *
+ * @since 3.1
*/
public void getTransform(Transform transform) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2051,7 +2215,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -2200,6 +2364,48 @@
return a[0] == 1 && b[0] == 0 && c[0] == 0 && d[0] == 1 && tx[0] == 0 && ty[0] == 0;
}
+/**
+ * Sets the receiver to always use the operating system's advanced graphics
+ * subsystem for all graphics operations if the argument is <code>true</code>.
+ * If the argument is <code>false</code>, the advanced graphics subsystem is
+ * no longer used, advanced graphics state is cleared and the normal graphics
+ * subsystem is used from now on.
+ * <p>
+ * Normally, the advanced graphics subsystem is invoked automatically when
+ * any one of the alpha, antialias, patterns, interpolation, paths, clipping
+ * or transformation operations in the receiver is requested. When the receiver
+ * is switched into advanced mode, the advanced graphics subsystem performs both
+ * advanced and normal graphics operations. Because the two subsystems are
+ * different, their output may differ. Switching to advanced graphics before
+ * any graphics operations are performed ensures that the output is consistent.
+ * </p>
+ * <p>
+ * Advanced graphics may not be installed for the operating system. In this
+ * case, this operation does nothing. Some operating system have only one
+ * graphics subsystem, so switching from normal to advanced graphics does
+ * nothing. However, switching from advanced to normal graphics will always
+ * clear the advanced graphics state, even for operating systems that have
+ * only one graphics subsystem.
+ * </p>
+ *
+ * @param advanced the new advanced graphics state
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAlpha
+ * @see #setAntialias
+ * @see #setBackgroundPattern
+ * @see #setClipping(Path)
+ * @see #setForegroundPattern
+ * @see #setInterpolation
+ * @see #setTextAntialias
+ * @see #setTransform
+ * @see #getAdvanced
+ *
+ * @since 3.1
+ */
public void setAdvanced(boolean advanced) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (advanced && data.cairo != 0) return;
@@ -2222,7 +2428,15 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's alpha value.
+ *
+ * @param alpha the alpha value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public void setAlpha(int alpha) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2232,7 +2446,24 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's anti-aliasing value to the parameter,
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setTextAntialias
+ *
+ * @since 3.1
*/
public void setAntialias(int antialias) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2272,8 +2503,21 @@
data.backgroundPattern = null;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the background pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new background pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public void setBackgroundPattern(Pattern pattern) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2391,7 +2635,22 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the area of the receiver which can be changed
+ * by drawing operations to the path specified
+ * by the argument.
+ *
+ * @param path the clipping path.
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void setClipping(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2409,9 +2668,11 @@
/**
* Sets the area of the receiver which can be changed
* by drawing operations to the rectangular area specified
- * by the argument.
+ * by the argument. Specifying <code>null</code> for the
+ * rectangle reverts the receiver's clipping area to its
+ * original value.
*
- * @param rect the clipping rectangle
+ * @param rect the clipping rectangle or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
@@ -2428,9 +2689,11 @@
/**
* Sets the area of the receiver which can be changed
* by drawing operations to the region specified
- * by the argument.
+ * by the argument. Specifying <code>null</code> for the
+ * region reverts the receiver's clipping area to its
+ * original value.
*
- * @param region the clipping region.
+ * @param region the clipping region or <code>null</code>
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li>
@@ -2473,6 +2736,22 @@
}
}
+/**
+ * Sets the receiver's fill rule to the parameter, which must be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @param rule the new fill rule
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code>
+ * or <code>SWT.FILL_WINDING</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void setFillRule(int rule) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
int cairo_mode = Cairo.CAIRO_FILL_RULE_EVEN_ODD;
@@ -2519,8 +2798,21 @@
data.foregroundPattern = null;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the foreground pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new foreground pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public void setForegroundPattern(Pattern pattern) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2542,8 +2834,22 @@
data.foregroundPattern = pattern;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the receiver's interpolation setting to the parameter, which
+ * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>,
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @param interpolation the new interpolation setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public void setInterpolation(int interpolation) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2607,7 +2913,10 @@
}
/**
- * Sets the receiver's line dash style to the argument.
+ * Sets the receiver's line dash style to the argument. The default
+ * value is <code>null</code>. If the argument is not <code>null</code>,
+ * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise
+ * it is set to <code>SWT.LINE_SOLID</code>.
*
* @param dashes the dash style to be used for drawing lines
*
@@ -2771,6 +3080,12 @@
* for all of the figure drawing operations (that is,
* <code>drawLine</code>, <code>drawRectangle</code>,
* <code>drawPolyline</code>, and so forth.
+ * <p>
+ * Note that line width of zero is used as a hint to
+ * indicate that the fastest possible line drawing
+ * algorithms should be used. This means that the
+ * output may be different from line width one.
+ * </p>
*
* @param lineWidth the width of a line
*
@@ -2840,7 +3155,24 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's text anti-aliasing value to the parameter,
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing only
+ * for all <em>text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAntialias
+ *
+ * @since 3.1
*/
public void setTextAntialias(int antialias) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2855,8 +3187,23 @@
data.textAntialias = antialias;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the transform that is currently being used by the receiver. If
+ * the argument is <code>null</code>, the current transform is set to
+ * the identity transform.
+ *
+ * @param transform the transform to set
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Transform
+ *
+ * @since 3.1
*/
public void setTransform(Transform transform) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2923,12 +3270,19 @@
* and the destination, and if the argument is <code>false</code>,
* puts the receiver in a drawing mode where the destination color
* is replaced with the source color value.
+ * <p>
+ * Note that this mode in fundamentally unsupportable on certain
+ * platforms, notably Carbon (Mac OS X). Clients that want their
+ * code to run on all platforms need to avoid this method.
+ * </p>
*
* @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ *
+ * @deprecated this functionality is not supported on some platforms
*/
public void setXORMode(boolean xor) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
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 5d7d965..775ba8b 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
@@ -54,7 +54,7 @@
* loading process should use the support provided in class
* <code>ImageLoader</code>.
* </p><p>
- * Application code must explicitely invoke the <code>Image.dispose()</code>
+ * Application code must explicitly invoke the <code>Image.dispose()</code>
* method to release the operating system resources managed by each instance
* when those instances are no longer required.
* </p>
@@ -451,7 +451,20 @@
* This constructor may be used to load a resource as follows:
* </p>
* <pre>
- * new Image(device, clazz.getResourceAsStream("file.gif"));
+ * static Image loadImage (Display display, Class clazz, String string) {
+ * InputStream stream = clazz.getResourceAsStream (string);
+ * if (stream == null) return null;
+ * Image image = null;
+ * try {
+ * image = new Image (display, stream);
+ * } catch (SWTException ex) {
+ * } finally {
+ * try {
+ * stream.close ();
+ * } catch (IOException ex) {}
+ * }
+ * return image;
+ * }
* </pre>
*
* @param device the device on which to create the image
@@ -806,7 +819,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
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 2600613..935ee20 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
@@ -135,7 +135,6 @@
* @param height the height coordinate of the rectangle
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
* <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
* </ul>
* @exception SWTException <ul>
@@ -272,7 +271,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -376,7 +375,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
*/
public boolean intersects (int x, int y, int width, int height) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -402,7 +401,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
*/
public boolean intersects(Rectangle rect) {
if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -494,7 +493,6 @@
* @param height the height coordinate of the rectangle
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
* <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
* </ul>
* @exception SWTException <ul>
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 ab8460f..cd10658 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
@@ -614,9 +614,9 @@
/**
* Sets the receiver's image to the argument, which may be
- * null indicating that no image should be displayed.
+ * <code>null</code> indicating that no image should be displayed.
*
- * @param image the image to display on the receiver (may be null)
+ * @param image the image to display on the receiver (may be <code>null</code>)
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
index b6971ef..b15398c1 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java
@@ -60,7 +60,6 @@
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
- * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
* </ul>
*
* @see SWT
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 377047c..144a51c 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
@@ -662,8 +662,8 @@
}
/**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver's list.
+ * Returns a (possibly empty) array of <code>String</code>s which are
+ * the items in the receiver's list.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -702,11 +702,16 @@
}
/**
- * Returns a <code>Point</code> whose x coordinate is the start
- * of the selection in the receiver's text field, and whose y
- * coordinate is the end of the selection. The returned values
- * are zero-relative. An "empty" selection as indicated by
- * the the x and y coordinates having the same value.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selection
+ * in the receiver's text field, and whose y coordinate is the
+ * character position representing the end of the selection.
+ * An "empty" selection is indicated by the x and y coordinates
+ * having the same value.
+ * <p>
+ * Indexing is zero based. The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
+ * </p>
*
* @return a point representing the selection start and end
*
@@ -754,7 +759,8 @@
/**
* Returns a string containing a copy of the contents of the
- * receiver's text field.
+ * receiver's text field, or an empty string if there are no
+ * contents.
*
* @return the receiver's text
*
@@ -808,6 +814,8 @@
* <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 #LIMIT
*/
public int getTextLimit () {
checkWidget();
@@ -1338,8 +1346,8 @@
/**
* Sets the text of the item in the receiver's list at the given
* zero-relative index to the string argument. This is equivalent
- * to <code>remove</code>'ing the old item at the index, and then
- * <code>add</code>'ing the new item at that index.
+ * to removing the old item at the index, and then adding the new
+ * item at that index.
*
* @param index the index for the item
* @param string the new text for the item
@@ -1532,7 +1540,11 @@
/**
* Sets the maximum number of characters that the receiver's
* text field is capable of holding to be the argument.
- *
+ * <p>
+ * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the
+ * receiver's limit to <code>Combo.LIMIT</code>.
+ * </p>
* @param limit new text limit
*
* @exception IllegalArgumentException <ul>
@@ -1542,6 +1554,8 @@
* <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 #LIMIT
*/
public void setTextLimit (int limit) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
index c2b1519..5a13446 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java
@@ -20,7 +20,7 @@
* of containing other controls.
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd>
* <dt><b>Events:</b></dt>
* <dd>(none)</dd>
* </dl>
@@ -386,7 +386,7 @@
}
/**
- * Returns an array containing the receiver's children.
+ * Returns a (possibly empty) array containing the receiver's children.
* Children are returned in the order that they are drawn.
* <p>
* Note: This is not the actual structure used by the receiver
@@ -474,7 +474,7 @@
}
/**
- * Gets the last specified tabbing order for the control.
+ * Gets the (possibly empty) tabbing order for the control.
*
* @return tabList the ordered list of controls representing the tab order
*
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 68a7352..490a58a 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
@@ -270,7 +270,7 @@
* @see #getBorderWidth
* @see #getBounds
* @see #getSize
- * @see #pack
+ * @see #pack(boolean)
* @see "computeTrim, getClientArea for controls that implement them"
*/
public Point computeSize (int wHint, int hHint) {
@@ -355,7 +355,7 @@
* @see #getBorderWidth
* @see #getBounds
* @see #getSize
- * @see #pack
+ * @see #pack(boolean)
* @see "computeTrim, getClientArea for controls that implement them"
*/
public Point computeSize (int wHint, int hHint, boolean changed) {
@@ -821,7 +821,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
*/
public void pack () {
pack (true);
@@ -846,7 +846,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
*/
public void pack (boolean changed) {
setSize (computeSize (SWT.DEFAULT, SWT.DEFAULT, changed));
@@ -2846,7 +2846,8 @@
* @return <code>true</code> if the parent is changed and <code>false</code> otherwise.
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2903,7 +2904,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
* @see #update
*/
public void setRedraw (boolean redraw) {
@@ -3363,7 +3364,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
* @see PaintListener
* @see SWT#Paint
*/
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 49140c1..735212c 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
@@ -326,9 +326,9 @@
* marked as iconified, and may also be displayed somewhere
* in the trim when the instance is in normal or maximized
* states. Depending where the icon is displayed, the platform
- * chooses the icon with the "best" size. It is expected that
- * the array will contain the same icon rendered at different
- * resolutions.
+ * chooses the icon with the "best" attributes. It is expected
+ * that the array will contain the same icon rendered at different
+ * sizes, with different depth and transparency attributes.
*
* <p>
* Note: This method will return an empty array if called before
@@ -501,7 +501,11 @@
* <em>saved default button</em>). If no default button had
* previously been set, or the saved default button was
* disposed, the receiver's default button will be set to
- * null.
+ * null.
+ * <p>
+ * The default button is the button that is selected when
+ * the receiver is active and the user presses ENTER.
+ * </p>
*
* @param button the new default button
*
@@ -554,8 +558,9 @@
* and may also be displayed somewhere in the trim when the
* instance is in normal or maximized states. Depending where
* the icon is displayed, the platform chooses the icon with
- * the "best" size. It is expected that the array will contain
- * the same icon rendered at different resolutions.
+ * the "best" attributes. It is expected that the array will
+ * contain the same icon rendered at different sizes, with
+ * different depth and transparency attributes.
*
* @param images the new image array
*
@@ -588,7 +593,7 @@
* causes the receiver to switch back to either the minimized
* or normal states.
* <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
* and <code>setMinimized(true)</code> will vary by platform. Typically,
* the behavior will match the platform user's expectations, but not
* always. This should be avoided if possible.
@@ -641,7 +646,7 @@
* causes the receiver to switch back to either the maximized
* or normal states.
* <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
* and <code>setMinimized(true)</code> will vary by platform. Typically,
* the behavior will match the platform user's expectations, but not
* always. This should be avoided if possible.
@@ -669,7 +674,7 @@
/**
* 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 may not be null.
+ * <em>title</em>, to the argument, which must not be null.
*
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java
index 3a28547..f2ba3bc 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java
@@ -82,6 +82,8 @@
* the directories it shows.
*
* @return the filter path
+ *
+ * @see #setFilterPath
*/
public String getFilterPath () {
return filterPath;
@@ -258,9 +260,15 @@
return answer;
}
/**
- * Sets the path which the dialog will use to filter
- * the directories it shows to the argument, which may be
- * null.
+ * Sets the path that the dialog will use to filter
+ * the directories it shows to the argument, which may
+ * be null. If the string is null, then the operating
+ * system's default filter path will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
*
* @param string the filter path
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java
index 7b0f169..8c04cde 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java
@@ -407,7 +407,7 @@
* </p>
*
* @exception SWTException <ul>
- * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li>
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
* </ul>
*
@@ -420,6 +420,11 @@
this (null);
}
+/**
+ * Constructs a new instance of this class using the parameter.
+ *
+ * @param data the device data
+ */
public Display (DeviceData data) {
super (data);
}
@@ -574,9 +579,16 @@
* be invoked by the user-interface thread at the next
* reasonable opportunity. The caller of this method continues
* to run in parallel, and is not notified when the
- * runnable has completed.
+ * runnable has completed. Specifying <code>null</code> as the
+ * runnable simply wakes the user-interface thread when run.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
*
- * @param runnable code to run on the user-interface thread.
+ * @param runnable code to run on the user-interface thread or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -911,7 +923,7 @@
* <p>
* This method is called after <code>release</code>.
* </p>
- * @see #dispose
+ * @see Device#dispose
* @see #release
*/
protected void destroy () {
@@ -926,7 +938,9 @@
/**
* Returns the display which the given thread is the
* user-interface thread for, or null if the given thread
- * is not a user-interface thread for any display.
+ * is not a user-interface thread for any display. Specifying
+ * <code>null</code> as the thread will return <code>null</code>
+ * for the display.
*
* @param thread the user-interface thread
* @return the display for the given thread
@@ -944,7 +958,8 @@
/**
* Causes the <code>run()</code> method of the runnable to
* be invoked by the user-interface thread just before the
- * receiver is disposed.
+ * receiver is disposed. Specifying a <code>null</code> runnable
+ * is ignored.
*
* @param runnable code to run at dispose time.
*
@@ -1314,7 +1329,7 @@
* Applications may have associated arbitrary objects with the
* receiver in this fashion. If the objects stored in the
* properties need to be notified when the display is disposed
- * of, it is the application's responsibility provide a
+ * of, it is the application's responsibility to provide a
* <code>disposeExec()</code> handler which does so.
* </p>
*
@@ -1354,7 +1369,7 @@
* Applications may put arbitrary objects in this field. If
* the object stored in the display specific data needs to
* be notified when the display is disposed of, it is the
- * application's responsibility provide a
+ * application's responsibility to provide a
* <code>disposeExec()</code> handler which does so.
* </p>
*
@@ -1518,9 +1533,8 @@
}
/**
- * Returns the maximum allowed depth of icons on this display.
- * On some platforms, this may be different than the actual
- * depth of the display.
+ * Returns the maximum allowed depth of icons on this display, in bits per pixel.
+ * On some platforms, this may be different than the actual depth of the display.
*
* @return the maximum icon depth
*
@@ -1528,6 +1542,8 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ *
+ * @see Device#getDepth
*/
public int getIconDepth () {
checkDevice ();
@@ -1624,8 +1640,8 @@
}
/**
- * Returns an array containing all shells which have not been
- * disposed and have the receiver as their display.
+ * Returns a (possibly empty) array containing all shells which have
+ * not been disposed and have the receiver as their display.
*
* @return the receiver's shells
*
@@ -2593,7 +2609,7 @@
* </p>
* This method is called before <code>destroy</code>.
*
- * @see #dispose
+ * @see Device#dispose
* @see #destroy
*/
protected void release () {
@@ -2884,9 +2900,10 @@
/**
* On platforms which support it, sets the application name
* to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * to set the name used for resource lookup. Specifying
+ * <code>null</code> for the name clears it.
*
- * @param name the new app name
+ * @param name the new app name or <code>null</code>
*/
public static void setAppName (String name) {
APP_NAME = name;
@@ -3192,6 +3209,12 @@
* be invoked by the user-interface thread after the specified
* number of milliseconds have elapsed. If milliseconds is less
* than zero, the runnable is not executed.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
*
* @param milliseconds the delay before running the runnable
* @param runnable code to run on the user-interface thread
@@ -3320,9 +3343,16 @@
* Causes the <code>run()</code> method of the runnable to
* be invoked by the user-interface thread at the next
* reasonable opportunity. The thread which calls this method
- * is suspended until the runnable completes.
- *
- * @param runnable code to run on the user-interface thread.
+ * is suspended until the runnable completes. Specifying <code>null</code>
+ * as the runnable simply wakes the user-interface thread.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
+ *
+ * @param runnable code to run on the user-interface thread or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li>
@@ -3368,7 +3398,7 @@
}
/**
- * If the receiver's user-interface thread was <code>sleep</code>'ing,
+ * If the receiver's user-interface thread was <code>sleep</code>ing,
* causes it to be awakened and start running again. Note that this
* method may be called from any thread.
*
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 18c7256..95404d5 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
@@ -25,6 +25,8 @@
* <dd>(none)</dd>
* </dl>
* <p>
+ * Note: Only one of the styles SAVE and OPEN may be specified.
+ * </p><p>
* IMPORTANT: This class is intended to be subclassed <em>only</em>
* within the SWT implementation.
* </p>
@@ -233,7 +235,8 @@
}
/**
* Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path, or an
+ * empty string if no such file has been selected.
*
* @return the relative path of the file
*/
@@ -241,8 +244,8 @@
return fileName;
}
/**
- * Returns the paths of all files that were selected
- * in the dialog relative to the filter path.
+ * Returns a (possibly empty) array with the paths of all files
+ * that were selected in the dialog relative to the filter path.
*
* @return the relative paths of the files
*/
@@ -259,18 +262,18 @@
return filterExtensions;
}
/**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
*
- * @return the file name filter
+ * @return the list of filter names
*/
public String [] getFilterNames () {
return filterNames;
}
/**
- * Returns the directory path that the dialog will use.
- * File names in this path will appear in the dialog,
- * filtered according to the filter extensions.
+ * Returns the directory path that the dialog will use, or an empty
+ * string if this is not set. File names in this path will appear
+ * in the dialog, filtered according to the filter extensions.
*
* @return the directory path string
*
@@ -467,6 +470,11 @@
* Set the file extensions which the dialog will
* use to filter the files it shows to the argument,
* which may be null.
+ * <p>
+ * The strings are platform specific. For example, on
+ * Windows, an extension filter string is typically of
+ * the form "*.extension", where "*.*" matches all files.
+ * </p>
*
* @param extensions the file extension filter
*/
@@ -474,11 +482,11 @@
filterExtensions = extensions;
}
/**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
*
- * @param names the file name filter
+ * @param names the list of filter names
*/
public void setFilterNames (String [] names) {
filterNames = names;
@@ -487,7 +495,14 @@
* Sets the directory path that the dialog will use
* to the argument, which may be null. File names in this
* path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
*
* @param string the directory path
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
index 6c53c6b..1f07d8b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java
@@ -23,6 +23,7 @@
* <p>
* <dl>
* <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
* <dt><b>Events:</b></dt>
* <dd>Selection</dd>
* </dl>
@@ -652,7 +653,7 @@
* is delimited by an anchor tag, <A> and </A>. Within an
* anchor, a single HREF attribute is supported. When a hyperlink is
* selected, the text field of the selection event contains either the
- * text of hyperlink or the value of the HREF, if one was specified.
+ * text of the hyperlink or the value of its HREF, if one was specified.
* In the rare case of identical hyperlinks within the same string, the
* HREF tag can be used to distinguish between them. The string may
* include the mnemonic character and line delimiters.
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 910f962..486567d 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
@@ -19,7 +19,7 @@
/**
* Instances of this class represent a selectable user interface
- * object that displays a list of strings and issues notificiation
+ * object that displays a list of strings and issues notification
* when a string selected. A list may be single or multi select.
* <p>
* <dl>
@@ -420,7 +420,7 @@
/**
* Returns the height of the area which would be used to
- * display <em>one</em> of the items in the tree.
+ * display <em>one</em> of the items in the list.
*
* @return the height of one item
*
@@ -449,8 +449,8 @@
}
/**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>String</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -487,8 +487,8 @@
/**
* Returns an array of <code>String</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -534,7 +534,7 @@
* Returns the zero-relative index of the item which is currently
* selected in the receiver, or -1 if no item is selected.
*
- * @return the index of the selected item
+ * @return the index of the selected item or -1
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -554,7 +554,8 @@
/**
* Returns the zero-relative indices of the items which are currently
- * selected in the receiver. The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1224,7 +1225,7 @@
/**
* Selects the item at the given zero-relative index in the receiver.
* If the item at the index was already selected, it remains selected.
- * The current selected is first cleared, then the new items are selected.
+ * The current selection is first cleared, then the new item is selected.
* Indices that are out of range are ignored.
*
* @param index the index of the item to select
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 6d897bf..626c463 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
@@ -344,7 +344,7 @@
/**
* Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -413,8 +413,8 @@
}
/**
- * Returns an array of <code>MenuItem</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>MenuItem</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -622,7 +622,7 @@
/**
* Returns <code>true</code> if the receiver is enabled and all
* of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu is typically not selectable from the
* user interface and draws with an inactive or "grayed" look.
*
* @return the receiver's enabled state
@@ -808,7 +808,7 @@
/**
* Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -829,11 +829,15 @@
}
/**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
* <p>
- * Note: This is different from most widgets where the
+ * Note that this is different from most widgets where the
* location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
* </p>
*
* @param x the new x coordinate for the receiver
@@ -853,11 +857,15 @@
}
/**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
* <p>
- * Note: This is different from most widgets where the
+ * Note that this is different from most widgets where the
* location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
* </p>
*
* @param location the new location for the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java
index dd0de64..356e314 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java
@@ -186,7 +186,7 @@
/**
* Adds the listener to the collection of listeners who will
- * be notified when the control is selected, by sending
+ * be notified when the menu item is selected, by sending
* it one of the messages defined in the <code>SelectionListener</code>
* interface.
* <p>
@@ -277,11 +277,13 @@
}
/**
- * Return the widget accelerator. An accelerator is the bit-wise
+ * Returns the widget accelerator. An accelerator is the bit-wise
* OR of zero or more modifier masks and a key. Examples:
* <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
*
- * @return the accelerator
+ * @return the accelerator or 0
*
* </ul>
* @exception SWTException <ul>
@@ -318,7 +320,7 @@
/**
* Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu item is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -460,7 +462,7 @@
/**
* Returns <code>true</code> if the receiver is enabled and all
* of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu item is typically not selectable from the
* user interface and draws with an inactive or "grayed" look.
*
* @return the receiver's enabled state
@@ -593,6 +595,8 @@
* OR of zero or more modifier masks and a key. Examples:
* <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>.
* <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
*
* @param accelerator an integer that is the bit-wise OR of masks and a key
*
@@ -613,7 +617,7 @@
/**
* Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu item is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -636,8 +640,9 @@
/**
* Sets the image the receiver will display to the argument.
* <p>
- * Note: This feature is not available on all window systems (for example, Window NT),
- * in which case, calling this method will silently do nothing.
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept (for example, Windows NT).
+ * </p>
*
* @param image the image to display
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java
index f0396de..90c4f56 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java
@@ -85,9 +85,9 @@
}
/**
- * Returns the dialog's message, which is a description of
- * the purpose for which it was opened. This message will be
- * visible on the dialog while it is open.
+ * Returns the dialog's message, or an empty string if it does not have one.
+ * The message is a description of the purpose for which the dialog was opened.
+ * This message will be visible in the dialog while it is open.
*
* @return the message
*/
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 47f00b6..0a46089 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
@@ -120,7 +120,7 @@
}
/**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the single 'selection' that is the receiver's position.
*
* @return the selection
*
@@ -196,7 +196,7 @@
}
/**
- * Sets the single <em>selection</em> that is the receiver's
+ * Sets the single 'selection' that is the receiver's
* position to the argument which must be greater than or equal
* to zero.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java
index c26b47e..aa67875 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java
@@ -213,7 +213,7 @@
}
/**
- * Returns the <em>selection</em>, which is the receiver's position.
+ * Returns the 'selection', which is the receiver's position.
*
* @return the selection
*
@@ -348,9 +348,8 @@
}
/**
- * Sets the <em>selection</em>, which is the receiver's
- * value, to the argument which must be greater than or equal
- * to zero.
+ * Sets the 'selection', which is the receiver's value,
+ * to the argument which must be greater than or equal to zero.
*
* @param value the new selection (must be zero or greater)
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java
index 65ca2a5..7c31f5b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java
@@ -21,7 +21,7 @@
* objects that represent a range of positive, numeric values.
* <p>
* At any given moment, a given scroll bar will have a
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
* value, which is constrained to be within the range of
* values the scroll bar represents (that is, between its
* <em>minimum</em> and <em>maximum</em> values).
@@ -102,6 +102,7 @@
* interface.
* <p>
* When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
+ * <code>SWT.NONE</code> - for the end of a drag.
* <code>SWT.DRAG</code>.
* <code>SWT.HOME</code>.
* <code>SWT.END</code>.
@@ -237,7 +238,7 @@
}
/**
- * Returns the receiver's parent, which must be scrollable.
+ * Returns the receiver's parent, which must be a Scrollable.
*
* @return the receiver's parent
*
@@ -252,7 +253,7 @@
}
/**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the single 'selection' that is the receiver's value.
*
* @return the selection
*
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 b97a539..d47f1d9 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
@@ -67,7 +67,7 @@
* it would be upgraded to <code>APPLICATION_MODAL</code>.
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd>
+ * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd>
* <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd>
* <dt><b>Events:</b></dt>
* <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd>
@@ -262,7 +262,7 @@
* @param parent a shell which will be the parent of the new instance
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -296,6 +296,9 @@
* @param parent a shell which will be the parent of the new instance
* @param style the style of control to construct
*
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
+ * </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
@@ -310,6 +313,8 @@
* @see SWT#NO_TRIM
* @see SWT#SHELL_TRIM
* @see SWT#DIALOG_TRIM
+ * @see SWT#ON_TOP
+ * @see SWT#TOOL
* @see SWT#MODELESS
* @see SWT#PRIMARY_MODAL
* @see SWT#APPLICATION_MODAL
@@ -1262,7 +1267,7 @@
}
/**
- * Sets the receiver's minimum size to the point specified by the arguments.
+ * Sets the receiver's minimum size to the size specified by the arguments.
* If the new minimum size is larger than the current size of the receiver,
* the receiver is resized to the new minimum size.
*
@@ -1285,7 +1290,7 @@
}
/**
- * Sets the receiver's minimum size to the point specified by the argument.
+ * Sets the receiver's minimum size to the size specified by the argument.
* If the new minimum size is larger than the current size of the receiver,
* the receiver is resized to the new minimum size.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java
index 83632cd..4c4dd9a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java
@@ -21,7 +21,7 @@
* objects that represent a range of positive, numeric values.
* <p>
* At any given moment, a given slider will have a
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
* value, which is constrained to be within the range of
* values the slider represents (that is, between its
* <em>minimum</em> and <em>maximum</em> values).
@@ -106,7 +106,7 @@
* interface.
* <p>
* When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
- * <code>0</code> - for the end of a drag.
+ * <code>SWT.NONE</code> - for the end of a drag.
* <code>SWT.DRAG</code>.
* <code>SWT.HOME</code>.
* <code>SWT.END</code>.
@@ -272,7 +272,7 @@
}
/**
- * Returns the <em>selection</em>, which is the receiver's value.
+ * Returns the 'selection', which is the receiver's value.
*
* @return the selection
*
@@ -444,7 +444,7 @@
}
/**
- * Sets the <em>selection</em>, which is the receiver's
+ * Sets the 'selection', which is the receiver's
* value, to the argument which must be greater than or equal
* to zero.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
index fe5e347..9405d91 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java
@@ -24,7 +24,7 @@
* <p>
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>READ_ONLY</dd>
+ * <dd>READ_ONLY, WRAP</dd>
* <dt><b>Events:</b></dt>
* <dd>Selection, Modify</dd>
* </dl>
@@ -65,6 +65,7 @@
* </ul>
*
* @see SWT#READ_ONLY
+ * @see SWT#WRAP
* @see Widget#checkSubclass
* @see Widget#getStyle
*/
@@ -446,6 +447,16 @@
return (int) adjustment.value;
}
+/**
+ * Returns the number of decimal places used by the receiver.
+ *
+ * @return the digits
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
public int getDigits () {
checkWidget ();
return OS.gtk_spin_button_get_digits (handle);
@@ -871,6 +882,25 @@
OS.g_signal_handlers_unblock_matched (handle, OS.G_SIGNAL_MATCH_DATA, 0, 0, 0, 0, VALUE_CHANGED);
}
+/**
+ * Sets the number of decimal places used by the receiver.
+ * <p>
+ * The digit setting is used to allow for floating point values in the receiver.
+ * For example, to set the selection to a floating point value of 1.37 call setDigits() with
+ * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value
+ * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all
+ * numeric APIs.
+ *
+ * @param value the new digits (must be greater than or equal to zero)
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
public void setDigits (int value) {
checkWidget ();
if (value < 0) error (SWT.ERROR_INVALID_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java
index 62aedc5..426d792 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java
@@ -93,6 +93,7 @@
* @see SWT#CHECK
* @see SWT#FULL_SELECTION
* @see SWT#HIDE_SELECTION
+ * @see SWT#VIRTUAL
* @see Widget#checkSubclass
* @see Widget#getStyle
*/
@@ -1200,8 +1201,8 @@
}
/**
- * Returns an array of <code>TableItem</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>TableItem</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -1270,8 +1271,8 @@
/**
* Returns an array of <code>TableItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1337,7 +1338,8 @@
/**
* Returns the zero-relative indices of the items which are currently
- * selected in the receiver. The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -2361,7 +2363,7 @@
/**
* Selects the item at the given zero-relative index in the receiver.
- * The current selected is first cleared, then the new item is selected.
+ * The current selection is first cleared, then the new item is selected.
*
* @param index the index of the item to select
*
@@ -2531,8 +2533,8 @@
* @param column the column to be shown
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the item is null</li>
- * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li>
+ * <li>ERROR_NULL_ARGUMENT - if the column is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the column has been disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java
index b3b3e9f..bcadc13 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
@@ -170,7 +170,6 @@
* </ul>
*
* @since 2.0
- *
*/
public Color getBackground () {
checkWidget ();
@@ -346,7 +345,6 @@
* </ul>
*
* @since 2.0
- *
*/
public Color getForeground () {
checkWidget ();
@@ -442,7 +440,8 @@
/**
* Returns a rectangle describing the size and location
* relative to its parent of an image at a column in the
- * table.
+ * table. An empty rectangle is returned if index exceeds
+ * the index of the table's last column.
*
* @param index the index that specifies the column
* @return the receiver's bounding image rectangle
@@ -613,7 +612,6 @@
* </ul>
*
* @since 2.0
- *
*/
public void setBackground (Color color) {
checkWidget ();
@@ -642,7 +640,6 @@
* </ul>
*
* @since 3.0
- *
*/
public void setBackground (int index, Color color) {
checkWidget ();
@@ -816,7 +813,6 @@
* </ul>
*
* @since 2.0
- *
*/
public void setForeground (Color color){
checkWidget ();
@@ -845,7 +841,6 @@
* </ul>
*
* @since 3.0
- *
*/
public void setForeground (int index, Color color){
checkWidget ();
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 7bc11bd..603d486 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
@@ -45,6 +45,10 @@
/**
* The maximum number of characters that can be entered
* into a text widget.
+ * <p>
+ * Note that this value is platform dependent, based upon
+ * the native widget implementation.
+ * </p>
*/
public final static int LIMIT;
/**
@@ -457,7 +461,7 @@
}
/**
- * Gets the line number of the caret.
+ * Returns the line number of the caret.
* <p>
* The line number of the caret is returned.
* </p>
@@ -479,7 +483,8 @@
}
/**
- * Gets the location the caret.
+ * 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>
@@ -506,9 +511,9 @@
}
/**
- * Gets the position of the caret.
+ * Returns the character position of the caret.
* <p>
- * The character position of the caret is returned.
+ * Indexing is zero based.
* </p>
*
* @return the position of the caret
@@ -530,7 +535,7 @@
}
/**
- * Gets the number of characters.
+ * Returns the number of characters.
*
* @return number of characters in the widget
*
@@ -549,7 +554,7 @@
}
/**
- * Gets the double click enabled flag.
+ * Returns the double click enabled flag.
* <p>
* The double click flag enables or disables the
* default action of the text widget when the user
@@ -569,7 +574,7 @@
}
/**
- * Gets the echo character.
+ * Returns the echo character.
* <p>
* The echo character is the character that is
* displayed when the user enters text or the
@@ -582,6 +587,8 @@
* <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 #setEchoChar
*/
public char getEchoChar () {
checkWidget ();
@@ -594,7 +601,7 @@
}
/**
- * Gets the editable state.
+ * Returns the editable state.
*
* @return whether or not the reciever is editable
*
@@ -616,7 +623,7 @@
}
/**
- * Gets the number of lines.
+ * Returns the number of lines.
*
* @return the number of lines in the widget
*
@@ -632,7 +639,7 @@
}
/**
- * Gets the line delimiter.
+ * Returns the line delimiter.
*
* @return a string that is the line delimiter
*
@@ -640,6 +647,8 @@
* <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 #DELIMITER
*/
public String getLineDelimiter () {
checkWidget ();
@@ -647,7 +656,7 @@
}
/**
- * Gets the height of a line.
+ * Returns the height of a line.
*
* @return the height of a row of text
*
@@ -662,7 +671,8 @@
}
/**
- * Returns the orientation of the receiver.
+ * Returns the orientation of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
*
* @return the orientation style
*
@@ -679,14 +689,17 @@
}
/**
- * Gets the position of the selected text.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selected
+ * text, and whose y coordinate is the character position
+ * representing the end of the selection. An "empty" selection
+ * is indicated by the x and y coordinates having the same value.
* <p>
- * Indexing is zero based. The range of
- * a selection is from 0..N where N is
- * the number of characters in the widget.
+ * Indexing is zero based. The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
* </p>
- *
- * @return the start and end of the selection
+ *
+ * @return a point representing the selection start and end
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -708,7 +721,7 @@
}
/**
- * Gets the number of selected characters.
+ * Returns the number of selected characters.
*
* @return the number of selected characters.
*
@@ -724,7 +737,7 @@
}
/**
- * Gets the selected text.
+ * Gets the selected text, or an empty string if there is no current selection.
*
* @return the selected text
*
@@ -740,7 +753,7 @@
}
/**
- * Gets the number of tabs.
+ * Returns the number of tabs.
* <p>
* Tab stop spacing is specified in terms of the
* space (' ') character. The width of a single
@@ -770,9 +783,10 @@
}
/**
- * Gets the widget text.
+ * Returns the widget text.
* <p>
- * The text for a text widget is the characters in the widget.
+ * The text for a text widget is the characters in the widget, or
+ * an empty string if this has never been set.
* </p>
*
* @return the widget text
@@ -802,7 +816,7 @@
}
/**
- * Gets a range of text. Returns an empty string if the
+ * Returns a range of text. Returns an empty string if the
* start of the range is greater than the end.
* <p>
* Indexing is zero based. The range of
@@ -856,6 +870,8 @@
* <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 #LIMIT
*/
public int getTextLimit () {
checkWidget ();
@@ -889,7 +905,7 @@
}
/**
- * Gets the top pixel.
+ * Returns the top pixel.
* <p>
* The top pixel is the pixel position of the line
* that is currently at the top of the widget. On
@@ -1141,6 +1157,9 @@
*
* @param string the string
*
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></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>
@@ -1342,6 +1361,9 @@
* The double click flag enables or disables the
* default action of the text widget when the user
* double clicks.
+ * </p><p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
* </p>
*
* @param doubleClick the new double click flag
@@ -1365,8 +1387,9 @@
* the echo character to '\0' clears the echo
* character and redraws the original text.
* If for any reason the echo character is invalid,
- * the default echo character for the platform
- * is used.
+ * or if the platform does not allow modification
+ * of the echo character, the default echo character
+ * for the platform is used.
* </p>
*
* @param echo the new echo character
@@ -1419,6 +1442,9 @@
* Sets the orientation of the receiver, which must be one
* of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
* <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
*
* @param orientation new orientation style
*
@@ -1470,7 +1496,8 @@
}
/**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given start and end indices.
* <p>
* Indexing is zero based. The range of
* a selection is from 0..N where N is
@@ -1511,7 +1538,10 @@
}
/**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given point, where the x coordinate
+ * represents the start index and the y coordinate
+ * represents the end index.
* <p>
* Indexing is zero based. The range of
* a selection is from 0..N where N is
@@ -1635,6 +1665,8 @@
* creating a read-only text widget.
* </p><p>
* To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Text.LIMIT</code> sets the
+ * receiver's limit to <code>Text.LIMIT</code>.
* </p>
*
* @param limit new text limit
@@ -1646,6 +1678,8 @@
* <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 #LIMIT
*/
public void setTextLimit (int limit) {
checkWidget ();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
index 1810f68..f3b4d67 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java
@@ -18,7 +18,7 @@
/**
* Instances of this class provide a selectable user interface object
- * that displays a hierarchy of items and issue notificiation when an
+ * that displays a hierarchy of items and issue notification when an
* item in the hierarchy is selected.
* <p>
* The item children that may be added to instances of this class
@@ -891,6 +891,23 @@
return OS.gtk_tree_view_get_headers_visible (handle);
}
+/**
+ * Returns the item at the given, zero-relative index in the
+ * receiver. Throws an exception if the index is out of range.
+ *
+ * @param index the index of the item to return
+ * @return the item at the given index
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public TreeItem getItem (int index) {
checkWidget();
int length = OS.gtk_tree_model_iter_n_children (modelHandle, 0);
@@ -1011,8 +1028,8 @@
}
/**
- * Returns the items contained in the receiver
- * that are direct item children of the receiver. These
+ * Returns a (possibly empty) array of items contained in the
+ * receiver that are direct item children of the receiver. These
* are the roots of the tree.
* <p>
* Note: This is not the actual structure used by the receiver
@@ -1115,8 +1132,8 @@
/**
* Returns an array of <code>TreeItem</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1503,6 +1520,7 @@
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
+ *
* @since 3.1
*/
public int indexOf (TreeColumn column) {
@@ -1514,6 +1532,26 @@
return -1;
}
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int indexOf (TreeItem item) {
checkWidget();
if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
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 098e95d..a871b72 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
@@ -52,7 +52,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
*
* @exception IllegalArgumentException <ul>
@@ -88,7 +88,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parent a composite control which will be the parent of the new instance (cannot be null)
+ * @param parent a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
* @param index the index to store the receiver in its parent
*
@@ -126,7 +126,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
*
* @exception IllegalArgumentException <ul>
@@ -162,7 +162,7 @@
* Style bits are also inherited from superclasses.
* </p>
*
- * @param parentItem a composite control which will be the parent of the new instance (cannot be null)
+ * @param parentItem a tree control which will be the parent of the new instance (cannot be null)
* @param style the style of control to construct
* @param index the index to store the receiver in its parent
*
@@ -680,6 +680,23 @@
return OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle);
}
+/**
+ * Returns the item at the given, zero-relative index in the
+ * receiver. Throws an exception if the index is out of range.
+ *
+ * @param index the index of the item to return
+ * @return the item at the given index
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public TreeItem getItem (int index) {
checkWidget();
int length = OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle);
@@ -694,8 +711,8 @@
}
/**
- * Returns an array of <code>TreeItem</code>s which are the
- * direct item children of the receiver.
+ * Returns a (possibly empty) array of <code>TreeItem</code>s which
+ * are the direct item children of the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -797,6 +814,26 @@
return new String (Converter.mbcsToWcs (null, buffer));
}
+/**
+ * Searches the receiver's list starting at the first item
+ * (index 0) until an item is found that is equal to the
+ * argument, and returns the index of that item. If no item
+ * is found, returns -1.
+ *
+ * @param item the search item
+ * @return the index of the item
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int indexOf (TreeItem item) {
checkWidget();
if (item == null) error (SWT.ERROR_NULL_ARGUMENT);
@@ -839,6 +876,16 @@
cellFont = null;
}
+/**
+ * Removes all of the items from the receiver.
+ * <p>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void removeAll () {
checkWidget ();
int length = OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
index 8a43d58..b46bdb8 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java
@@ -157,6 +157,7 @@
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -427,7 +428,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
* </ul>
*
- * @see #setData
+ * @see #setData(Object)
*/
public Object getData () {
checkWidget();
@@ -455,7 +456,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #setData
+ * @see #setData(String, Object)
*/
public Object getData (String key) {
checkWidget();
@@ -482,7 +483,6 @@
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
- * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*/
public Display getDisplay () {
@@ -1148,6 +1148,8 @@
* <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li>
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
* </ul>
+ *
+ * @see #getData()
*/
public void setData (Object data) {
checkWidget();
@@ -1180,7 +1182,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #getData
+ * @see #getData(String)
*/
public void setData (String key, Object value) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Color.java
index 28b3692..f2257bb 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Color.java
@@ -197,7 +197,7 @@
}
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Cursor.java
index 45e20e6..d09c033 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Cursor.java
@@ -394,7 +394,7 @@
}
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Device.java
index 54377b2..01c43ca 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Device.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Device.java
@@ -487,7 +487,7 @@
* specified in class <code>SWT</code>. Any value other
* than one of the SWT color constants which is passed
* in will result in the color black. This color should
- * not be free'd because it was allocated by the system,
+ * not be freed because it was allocated by the system,
* not the application.
*
* @param id the color constant
@@ -526,7 +526,7 @@
* Returns a reasonable font for applications to use.
* On some platforms, this will match the "default font"
* or "system font" if such can be found. This font
- * should not be free'd because it was allocated by the
+ * should not be freed because it was allocated by the
* system, not the application.
* <p>
* Typically, applications which want the default look
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
index 2a74951..cda4864 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Font.java
@@ -381,7 +381,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontData.java
index 3bc432b..e74f01f 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontData.java
@@ -445,7 +445,7 @@
}
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -552,7 +552,8 @@
/**
* Sets the style of the receiver to the argument which must
* be a bitwise OR of one or more of the <code>SWT</code>
- * constants NORMAL, BOLD and ITALIC.
+ * constants NORMAL, BOLD and ITALIC. All other style bits are
+ * ignored.
*
* @param style the new style for this <code>FontData</code>
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontMetrics.java
index 6216b6e..16fab79 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontMetrics.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/FontMetrics.java
@@ -99,7 +99,7 @@
}
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/GC.java
index 3fe2e1f..4845ab8 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/GC.java
@@ -156,6 +156,24 @@
public void copyArea(int x, int y, int width, int height, int destX, int destY) {
copyArea(x, y, width, height, destX, destY, true);
}
+/**
+ * Copies a rectangular area of the receiver at the source
+ * position onto the receiver at the destination position.
+ *
+ * @param srcX the x coordinate in the receiver of the area to be copied
+ * @param srcY the y coordinate in the receiver of the area to be copied
+ * @param width the width of the area to copy
+ * @param height the height of the area to copy
+ * @param destX the x coordinate in the receiver of the area to copy to
+ * @param destY the y coordinate in the receiver of the area to copy to
+ * @param paint if <code>true</code> paint events will be generated for old and obscured areas
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void copyArea(int x, int y, int width, int height, int destX, int destY, boolean paint) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (width <= 0 || height <= 0) return;
@@ -331,7 +349,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void drawFocus (int x, int y, int width, int height) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -813,8 +831,22 @@
}
OS.XDrawArc(data.display, data.drawable, handle, x, y, width, height, 0, 23040);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Draws the path described by the parameter.
+ *
+ * @param path the path to draw
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void drawPath(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1436,7 +1468,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1586,8 +1618,22 @@
OS.XFillArc (display, data.drawable, handle, x, y, width, height, 0, 23040);
OS.XSetForeground (display, handle, values.foreground);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Fills the path described by the parameter.
+ *
+ * @param path the path to fill
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void fillPath (Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1673,7 +1719,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillRectangle (int x, int y, int width, int height) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1721,7 +1767,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillRectangle (Rectangle rect) {
if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -1982,12 +2028,44 @@
OS.XmFontListFreeFontContext(context);
return 0;
}
+/**
+ * Returns <code>true</code> if receiver is using the operating system's
+ * advanced graphics subsystem. Otherwise, <code>false</code> is returned
+ * to indicate that normal graphics are in use.
+ * <p>
+ * Advanced graphics may not be installed for the operating system. In this
+ * case, <code>false</code> is always returned. Some operating system have
+ * only one graphics subsystem. If this subsystem supports advanced graphics,
+ * then <code>true</code> is always returned. If any graphics operation such
+ * as alpha, antialias, patterns, interpolation, paths, clipping or transformation
+ * has caused the receiver to switch from regular to advanced graphics mode,
+ * <code>true</code> is returned. If the receiver has been explicitly switched
+ * to advanced mode and this mode is supported, <code>true</code> is returned.
+ * </p>
+ *
+ * @return the advanced value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAdvanced
+ * @since 3.1
+ */
public boolean getAdvanced() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return data.cairo != 0;
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's alpha value.
+ *
+ * @return the alpha value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public int getAlpha() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1995,7 +2073,20 @@
return (int)(Cairo.cairo_current_alpha(data.cairo) * 255);
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's anti-aliasing setting value, which will be
+ * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getTextAntialias
+ *
+ * @since 3.1
*/
public int getAntialias() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2022,8 +2113,19 @@
return Color.motif_new(data.device, xColor);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the background pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's background pattern
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public Pattern getBackgroundPattern() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2272,6 +2374,18 @@
String getCodePage () {
return data.font.codePage;
}
+/**
+ * Returns the receiver's fill rule, which will be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @return the receiver's fill rule
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int getFillRule() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
XGCValues values = new XGCValues();
@@ -2548,15 +2662,36 @@
return Color.motif_new(data.device, xColor);
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the foreground pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's foreground pattern
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public Pattern getForegroundPattern() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return data.foregroundPattern;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the receiver's interpolation setting, which will be one of
+ * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>,
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @return the receiver's interpolation setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public int getInterpolation() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2588,7 +2723,8 @@
return cap;
}
/**
- * Returns the receiver's line dash style.
+ * Returns the receiver's line dash style. The default value is
+ * <code>null</code>.
*
* @return the lin dash style used for drawing lines
*
@@ -2688,14 +2824,42 @@
return data.style;
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's text drawing anti-aliasing setting value,
+ * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing
+ * <em>only</em> for text drawing operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getAntialias
+ *
+ * @since 3.1
*/
public int getTextAntialias() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return data.textAntialias;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the parameter to the transform that is currently being
+ * used by the receiver.
+ *
+ * @param transform the destination to copy the transform into
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Transform
+ *
+ * @since 3.1
*/
public void getTransform(Transform transform) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2730,7 +2894,7 @@
}
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -2848,6 +3012,48 @@
Cairo.cairo_matrix_get_affine(matrix, a, b, c, d, tx, ty);
return a[0] == 1 && b[0] == 0 && c[0] == 0 && d[0] == 1 && tx[0] == 0 && ty[0] == 0;
}
+/**
+ * Sets the receiver to always use the operating system's advanced graphics
+ * subsystem for all graphics operations if the argument is <code>true</code>.
+ * If the argument is <code>false</code>, the advanced graphics subsystem is
+ * no longer used, advanced graphics state is cleared and the normal graphics
+ * subsystem is used from now on.
+ * <p>
+ * Normally, the advanced graphics subsystem is invoked automatically when
+ * any one of the alpha, antialias, patterns, interpolation, paths, clipping
+ * or transformation operations in the receiver is requested. When the receiver
+ * is switched into advanced mode, the advanced graphics subsystem performs both
+ * advanced and normal graphics operations. Because the two subsystems are
+ * different, their output may differ. Switching to advanced graphics before
+ * any graphics operations are performed ensures that the output is consistent.
+ * </p>
+ * <p>
+ * Advanced graphics may not be installed for the operating system. In this
+ * case, this operation does nothing. Some operating system have only one
+ * graphics subsystem, so switching from normal to advanced graphics does
+ * nothing. However, switching from advanced to normal graphics will always
+ * clear the advanced graphics state, even for operating systems that have
+ * only one graphics subsystem.
+ * </p>
+ *
+ * @param advanced the new advanced graphics state
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAlpha
+ * @see #setAntialias
+ * @see #setBackgroundPattern
+ * @see #setClipping(Path)
+ * @see #setForegroundPattern
+ * @see #setInterpolation
+ * @see #setTextAntialias
+ * @see #setTransform
+ * @see #getAdvanced
+ *
+ * @since 3.1
+ */
public void setAdvanced(boolean advanced) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (advanced && data.cairo != 0) return;
@@ -2869,7 +3075,15 @@
}
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's alpha value.
+ *
+ * @param alpha the alpha value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public void setAlpha(int alpha) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2878,7 +3092,24 @@
Cairo.cairo_set_alpha(data.cairo, (alpha & 0xff) / 255f);
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's anti-aliasing value to the parameter,
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setTextAntialias
+ *
+ * @since 3.1
*/
public void setAntialias(int antialias) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2957,8 +3188,21 @@
OS.XSetBackground(data.display, handle, color.handle.pixel);
data.backgroundPattern = null;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the background pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new background pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public void setBackgroundPattern(Pattern pattern) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3060,7 +3304,22 @@
OS.XDestroyRegion(clipRgn);
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the area of the receiver which can be changed
+ * by drawing operations to the path specified
+ * by the argument.
+ *
+ * @param path the clipping path.
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void setClipping(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3077,9 +3336,11 @@
/**
* Sets the area of the receiver which can be changed
* by drawing operations to the rectangular area specified
- * by the argument.
+ * by the argument. Specifying <code>null</code> for the
+ * rectangle reverts the receiver's clipping area to its
+ * original value.
*
- * @param rect the clipping rectangle
+ * @param rect the clipping rectangle or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
@@ -3096,9 +3357,11 @@
/**
* Sets the area of the receiver which can be changed
* by drawing operations to the region specified
- * by the argument.
+ * by the argument. Specifying <code>null</code> for the
+ * region reverts the receiver's clipping area to its
+ * original value.
*
- * @param region the clipping region.
+ * @param region the clipping region or <code>null</code>
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li>
@@ -3112,6 +3375,22 @@
if (region != null && region.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
setClipping(region != null ? region.handle : 0);
}
+/**
+ * Sets the receiver's fill rule to the parameter, which must be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @param rule the new fill rule
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code>
+ * or <code>SWT.FILL_WINDING</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void setFillRule(int rule) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
int mode = OS.EvenOddRule, cairo_mode = Cairo.CAIRO_FILL_RULE_EVEN_ODD;
@@ -3183,8 +3462,21 @@
}
data.foregroundPattern = null;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the foreground pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new foreground pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
*/
public void setForegroundPattern(Pattern pattern) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3205,8 +3497,22 @@
}
data.foregroundPattern = pattern;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the receiver's interpolation setting to the parameter, which
+ * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>,
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @param interpolation the new interpolation setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public void setInterpolation(int interpolation) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3269,7 +3575,10 @@
}
}
/**
- * Sets the receiver's line dash style to the argument.
+ * Sets the receiver's line dash style to the argument. The default
+ * value is <code>null</code>. If the argument is not <code>null</code>,
+ * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise
+ * it is set to <code>SWT.LINE_SOLID</code>.
*
* @param dashes the dash style to be used for drawing lines
*
@@ -3433,6 +3742,12 @@
* for all of the figure drawing operations (that is,
* <code>drawLine</code>, <code>drawRectangle</code>,
* <code>drawPolyline</code>, and so forth.
+ * <p>
+ * Note that line width of zero is used as a hint to
+ * indicate that the fastest possible line drawing
+ * algorithms should be used. This means that the
+ * output may be different from line width one.
+ * </p>
*
* @param lineWidth the width of a line
*
@@ -3498,7 +3813,24 @@
data.drawFlags = flags;
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's text anti-aliasing value to the parameter,
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing only
+ * for all <em>text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAntialias
+ *
+ * @since 3.1
*/
public void setTextAntialias(int antialias) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3512,8 +3844,23 @@
}
data.textAntialias = antialias;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the transform that is currently being used by the receiver. If
+ * the argument is <code>null</code>, the current transform is set to
+ * the identity transform.
+ *
+ * @param transform the transform to set
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Transform
+ *
+ * @since 3.1
*/
public void setTransform(Transform transform) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -3575,12 +3922,19 @@
* and the destination, and if the argument is <code>false</code>,
* puts the receiver in a drawing mode where the destination color
* is replaced with the source color value.
+ * <p>
+ * Note that this mode in fundamentally unsupportable on certain
+ * platforms, notably Carbon (Mac OS X). Clients that want their
+ * code to run on all platforms need to avoid this method.
+ * </p>
*
* @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ *
+ * @deprecated this functionality is not supported on some platforms
*/
public void setXORMode(boolean xor) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Image.java
index 75d8323..6ea0bbd 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Image.java
@@ -54,7 +54,7 @@
* loading process should use the support provided in class
* <code>ImageLoader</code>.
* </p><p>
- * Application code must explicitely invoke the <code>Image.dispose()</code>
+ * Application code must explicitly invoke the <code>Image.dispose()</code>
* method to release the operating system resources managed by each instance
* when those instances are no longer required.
* </p>
@@ -590,7 +590,20 @@
* This constructor may be used to load a resource as follows:
* </p>
* <pre>
- * new Image(device, clazz.getResourceAsStream("file.gif"));
+ * static Image loadImage (Display display, Class clazz, String string) {
+ * InputStream stream = clazz.getResourceAsStream (string);
+ * if (stream == null) return null;
+ * Image image = null;
+ * try {
+ * image = new Image (display, stream);
+ * } catch (SWTException ex) {
+ * } finally {
+ * try {
+ * stream.close ();
+ * } catch (IOException ex) {}
+ * }
+ * return image;
+ * }
* </pre>
*
* @param device the device on which to create the image
@@ -981,7 +994,7 @@
}
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Region.java
index adfc1b1..7e5bbb7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/Region.java
@@ -134,7 +134,6 @@
* @param height the height coordinate of the rectangle
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
* <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
* </ul>
* @exception SWTException <ul>
@@ -260,7 +259,7 @@
}
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -361,7 +360,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
*/
public boolean intersects (int x, int y, int width, int height) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -382,7 +381,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
*/
public boolean intersects (Rectangle rect) {
if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -476,7 +475,6 @@
* @param height the height coordinate of the rectangle
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
* <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
* </ul>
* @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Button.java
index 2125875..7250019 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Button.java
@@ -632,9 +632,9 @@
}
/**
* Sets the receiver's image to the argument, which may be
- * null indicating that no image should be displayed.
+ * <code>null</code> indicating that no image should be displayed.
*
- * @param image the image to display on the receiver (may be null)
+ * @param image the image to display on the receiver (may be <code>null</code>)
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
index 510e345..7214d58 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Canvas.java
@@ -61,7 +61,6 @@
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
- * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
* </ul>
*
* @see SWT
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Combo.java
index 03b09c6..80a4c2d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Combo.java
@@ -559,8 +559,8 @@
return getFontHeight (fontList) + spacing + (2 * highlight);
}
/**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver's list.
+ * Returns a (possibly empty) array of <code>String</code>s which are
+ * the items in the receiver's list.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -627,11 +627,16 @@
return style & (SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT);
}
/**
- * Returns a <code>Point</code> whose x coordinate is the start
- * of the selection in the receiver's text field, and whose y
- * coordinate is the end of the selection. The returned values
- * are zero-relative. An "empty" selection as indicated by
- * the the x and y coordinates having the same value.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selection
+ * in the receiver's text field, and whose y coordinate is the
+ * character position representing the end of the selection.
+ * An "empty" selection is indicated by the x and y coordinates
+ * having the same value.
+ * <p>
+ * Indexing is zero based. The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
+ * </p>
*
* @return a point representing the selection start and end
*
@@ -680,7 +685,8 @@
}
/**
* Returns a string containing a copy of the contents of the
- * receiver's text field.
+ * receiver's text field, or an empty string if there are no
+ * contents.
*
* @return the receiver's text
*
@@ -757,6 +763,8 @@
* <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 #LIMIT
*/
public int getTextLimit () {
checkWidget();
@@ -1228,8 +1236,8 @@
/**
* Sets the text of the item in the receiver's list at the given
* zero-relative index to the string argument. This is equivalent
- * to <code>remove</code>'ing the old item at the index, and then
- * <code>add</code>'ing the new item at that index.
+ * to removing the old item at the index, and then adding the new
+ * item at that index.
*
* @param index the index for the item
* @param string the new text for the item
@@ -1440,7 +1448,11 @@
/**
* Sets the maximum number of characters that the receiver's
* text field is capable of holding to be the argument.
- *
+ * <p>
+ * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the
+ * receiver's limit to <code>Combo.LIMIT</code>.
+ * </p>
* @param limit new text limit
*
* @exception IllegalArgumentException <ul>
@@ -1450,6 +1462,8 @@
* <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 #LIMIT
*/
public void setTextLimit (int limit) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Composite.java
index eaaf7b2..9fbc798 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Composite.java
@@ -21,7 +21,7 @@
* of containing other controls.
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd>
* <dt><b>Events:</b></dt>
* <dd>(none)</dd>
* </dl>
@@ -349,7 +349,7 @@
return true;
}
/**
- * Returns an array containing the receiver's children.
+ * Returns a (possibly empty) array containing the receiver's children.
* Children are returned in the order that they are drawn.
* <p>
* Note: This is not the actual structure used by the receiver
@@ -430,7 +430,7 @@
return layoutCount > 0 ;
}
/**
- * Gets the last specified tabbing order for the control.
+ * Gets the (possibly empty) tabbing order for the control.
*
* @return tabList the ordered list of controls representing the tab order
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Control.java
index f6ea7d7..8bac8c2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Control.java
@@ -344,7 +344,7 @@
* @see #getBorderWidth
* @see #getBounds
* @see #getSize
- * @see #pack
+ * @see #pack(boolean)
* @see "computeTrim, getClientArea for controls that implement them"
*/
public Point computeSize (int wHint, int hHint) {
@@ -381,7 +381,7 @@
* @see #getBorderWidth
* @see #getBounds
* @see #getSize
- * @see #pack
+ * @see #pack(boolean)
* @see "computeTrim, getClientArea for controls that implement them"
*/
public Point computeSize (int wHint, int hHint, boolean changed) {
@@ -1356,7 +1356,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
*/
public void pack () {
checkWidget();
@@ -1381,7 +1381,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
*/
public void pack (boolean changed) {
checkWidget();
@@ -2233,7 +2233,8 @@
* @return <code>true</code> if the parent is changed and <code>false</code> otherwise.
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2286,7 +2287,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
* @see #update
*/
public void setRedraw (boolean redraw) {
@@ -2811,7 +2812,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
* @see PaintListener
* @see SWT#Paint
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java
index 3d480b2..9fce63c 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java
@@ -304,9 +304,9 @@
* marked as iconified, and may also be displayed somewhere
* in the trim when the instance is in normal or maximized
* states. Depending where the icon is displayed, the platform
- * chooses the icon with the "best" size. It is expected that
- * the array will contain the same icon rendered at different
- * resolutions.
+ * chooses the icon with the "best" attributes. It is expected
+ * that the array will contain the same icon rendered at different
+ * sizes, with different depth and transparency attributes.
*
* <p>
* Note: This method will return an empty array if called before
@@ -470,7 +470,11 @@
* <em>saved default button</em>). If no default button had
* previously been set, or the saved default button was
* disposed, the receiver's default button will be set to
- * null.
+ * null.
+ * <p>
+ * The default button is the button that is selected when
+ * the receiver is active and the user presses ENTER.
+ * </p>
*
* @param button the new default button
*
@@ -538,8 +542,9 @@
* and may also be displayed somewhere in the trim when the
* instance is in normal or maximized states. Depending where
* the icon is displayed, the platform chooses the icon with
- * the "best" size. It is expected that the array will contain
- * the same icon rendered at different resolutions.
+ * the "best" attributes. It is expected that the array will
+ * contain the same icon rendered at different sizes, with
+ * different depth and transparency attributes.
*
* @param images the new image array
*
@@ -572,7 +577,7 @@
* causes the receiver to switch back to either the minimized
* or normal states.
* <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
* and <code>setMinimized(true)</code> will vary by platform. Typically,
* the behavior will match the platform user's expectations, but not
* always. This should be avoided if possible.
@@ -692,7 +697,7 @@
* causes the receiver to switch back to either the maximized
* or normal states.
* <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
* and <code>setMinimized(true)</code> will vary by platform. Typically,
* the behavior will match the platform user's expectations, but not
* always. This should be avoided if possible.
@@ -718,7 +723,7 @@
/**
* 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 may not be null.
+ * <em>title</em>, to the argument, which must not be null.
*
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/DirectoryDialog.java
index 9f0c212..2bfe7ad 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/DirectoryDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/DirectoryDialog.java
@@ -89,6 +89,8 @@
* the directories it shows.
*
* @return the filter path
+ *
+ * @see #setFilterPath
*/
public String getFilterPath () {
return filterPath;
@@ -287,9 +289,15 @@
return directoryPath;
}
/**
- * Sets the path which the dialog will use to filter
- * the directories it shows to the argument, which may be
- * null.
+ * Sets the path that the dialog will use to filter
+ * the directories it shows to the argument, which may
+ * be null. If the string is null, then the operating
+ * system's default filter path will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
*
* @param string the filter path
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java
index 33bde71..ae5264d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java
@@ -385,7 +385,7 @@
* </p>
*
* @exception SWTException <ul>
- * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li>
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
* </ul>
*
@@ -397,6 +397,11 @@
public Display () {
this (null);
}
+/**
+ * Constructs a new instance of this class using the parameter.
+ *
+ * @param data the device data
+ */
public Display (DeviceData data) {
super (checkNull (data));
}
@@ -546,9 +551,16 @@
* be invoked by the user-interface thread at the next
* reasonable opportunity. The caller of this method continues
* to run in parallel, and is not notified when the
- * runnable has completed.
+ * runnable has completed. Specifying <code>null</code> as the
+ * runnable simply wakes the user-interface thread when run.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
*
- * @param runnable code to run on the user-interface thread.
+ * @param runnable code to run on the user-interface thread or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -804,7 +816,7 @@
* <p>
* This method is called after <code>release</code>.
* </p>
- * @see #dispose
+ * @see Device#dispose
* @see #release
*/
protected void destroy () {
@@ -845,7 +857,8 @@
/**
* Causes the <code>run()</code> method of the runnable to
* be invoked by the user-interface thread just before the
- * receiver is disposed.
+ * receiver is disposed. Specifying a <code>null</code> runnable
+ * is ignored.
*
* @param runnable code to run at dispose time.
*
@@ -1184,7 +1197,9 @@
/**
* Returns the display which the given thread is the
* user-interface thread for, or null if the given thread
- * is not a user-interface thread for any display.
+ * is not a user-interface thread for any display. Specifying
+ * <code>null</code> as the thread will return <code>null</code>
+ * for the display.
*
* @param thread the user-interface thread
* @return the display for the given thread
@@ -1293,7 +1308,7 @@
* Applications may have associated arbitrary objects with the
* receiver in this fashion. If the objects stored in the
* properties need to be notified when the display is disposed
- * of, it is the application's responsibility provide a
+ * of, it is the application's responsibility to provide a
* <code>disposeExec()</code> handler which does so.
* </p>
*
@@ -1332,7 +1347,7 @@
* Applications may put arbitrary objects in this field. If
* the object stored in the display specific data needs to
* be notified when the display is disposed of, it is the
- * application's responsibility provide a
+ * application's responsibility to provide a
* <code>disposeExec()</code> handler which does so.
* </p>
*
@@ -1441,9 +1456,8 @@
return false;
}
/**
- * Returns the maximum allowed depth of icons on this display.
- * On some platforms, this may be different than the actual
- * depth of the display.
+ * Returns the maximum allowed depth of icons on this display, in bits per pixel.
+ * On some platforms, this may be different than the actual depth of the display.
*
* @return the maximum icon depth
*
@@ -1451,6 +1465,8 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ *
+ * @see Device#getDepth
*/
public int getIconDepth () {
return getDepth ();
@@ -1600,8 +1616,8 @@
return monitor;
}
/**
- * Returns an array containing all shells which have not been
- * disposed and have the receiver as their display.
+ * Returns a (possibly empty) array containing all shells which have
+ * not been disposed and have the receiver as their display.
*
* @return the receiver's shells
*
@@ -2767,7 +2783,7 @@
* </p>
* This method is called before <code>destroy</code>.
*
- * @see #dispose
+ * @see Device#dispose
* @see #destroy
*/
protected void release () {
@@ -3154,9 +3170,10 @@
/**
* On platforms which support it, sets the application name
* to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * to set the name used for resource lookup. Specifying
+ * <code>null</code> for the name clears it.
*
- * @param name the new app name
+ * @param name the new app name or <code>null</code>
*/
public static void setAppName (String name) {
APP_NAME = name;
@@ -3435,9 +3452,16 @@
* Causes the <code>run()</code> method of the runnable to
* be invoked by the user-interface thread at the next
* reasonable opportunity. The thread which calls this method
- * is suspended until the runnable completes.
- *
- * @param runnable code to run on the user-interface thread.
+ * is suspended until the runnable completes. Specifying <code>null</code>
+ * as the runnable simply wakes the user-interface thread.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
+ *
+ * @param runnable code to run on the user-interface thread or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li>
@@ -3465,6 +3489,12 @@
* be invoked by the user-interface thread after the specified
* number of milliseconds have elapsed. If milliseconds is less
* than zero, the runnable is not executed.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
*
* @param milliseconds the delay before running the runnable
* @param runnable code to run on the user-interface thread
@@ -3562,7 +3592,7 @@
OS.XtFree (event);
}
/**
- * If the receiver's user-interface thread was <code>sleep</code>'ing,
+ * If the receiver's user-interface thread was <code>sleep</code>ing,
* causes it to be awakened and start running again. Note that this
* method may be called from any thread.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FileDialog.java
index db44185..c06d1ff 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/FileDialog.java
@@ -25,6 +25,8 @@
* <dd>(none)</dd>
* </dl>
* <p>
+ * Note: Only one of the styles SAVE and OPEN may be specified.
+ * </p><p>
* IMPORTANT: This class is intended to be subclassed <em>only</em>
* within the SWT implementation.
* </p>
@@ -92,7 +94,8 @@
}
/**
* Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path, or an
+ * empty string if no such file has been selected.
*
* @return the relative path of the file
*/
@@ -101,8 +104,8 @@
}
/**
- * Returns the paths of all files that were selected
- * in the dialog relative to the filter path.
+ * Returns a (possibly empty) array with the paths of all files
+ * that were selected in the dialog relative to the filter path.
*
* @return the relative paths of the files
*/
@@ -121,19 +124,19 @@
}
/**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
*
- * @return the file name filter
+ * @return the list of filter names
*/
public String [] getFilterNames () {
return filterNames;
}
/**
- * Returns the directory path that the dialog will use.
- * File names in this path will appear in the dialog,
- * filtered according to the filter extensions.
+ * Returns the directory path that the dialog will use, or an empty
+ * string if this is not set. File names in this path will appear
+ * in the dialog, filtered according to the filter extensions.
*
* @return the directory path string
*
@@ -491,6 +494,11 @@
* Set the file extensions which the dialog will
* use to filter the files it shows to the argument,
* which may be null.
+ * <p>
+ * The strings are platform specific. For example, on
+ * Windows, an extension filter string is typically of
+ * the form "*.extension", where "*.*" matches all files.
+ * </p>
*
* @param extensions the file extension filter
*/
@@ -499,11 +507,11 @@
}
/**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
*
- * @param names the file name filter
+ * @param names the list of filter names
*/
public void setFilterNames (String [] names) {
filterNames = names;
@@ -513,7 +521,14 @@
* Sets the directory path that the dialog will use
* to the argument, which may be null. File names in this
* path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
*
* @param string the directory path
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
index 44bd6d0..72f367b 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Link.java
@@ -22,6 +22,7 @@
* <p>
* <dl>
* <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
* <dt><b>Events:</b></dt>
* <dd>Selection</dd>
* </dl>
@@ -425,7 +426,7 @@
* is delimited by an anchor tag, <A> and </A>. Within an
* anchor, a single HREF attribute is supported. When a hyperlink is
* selected, the text field of the selection event contains either the
- * text of hyperlink or the value of the HREF, if one was specified.
+ * text of the hyperlink or the value of its HREF, if one was specified.
* In the rare case of identical hyperlinks within the same string, the
* HREF tag can be used to distinguish between them. The string may
* include the mnemonic character and line delimiters.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java
index 312ec35..db53272 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java
@@ -20,7 +20,7 @@
/**
* Instances of this class represent a selectable user interface
- * object that displays a list of strings and issues notificiation
+ * object that displays a list of strings and issues notification
* when a string selected. A list may be single or multi select.
* <p>
* <dl>
@@ -465,7 +465,7 @@
}
/**
* Returns the height of the area which would be used to
- * display <em>one</em> of the items in the tree.
+ * display <em>one</em> of the items in the list.
*
* @return the height of one item
*
@@ -487,8 +487,8 @@
return getFontHeight (font.handle) + spacing + highlight + 1;
}
/**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>String</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -534,8 +534,8 @@
}
/**
* Returns an array of <code>String</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -598,7 +598,7 @@
* Returns the zero-relative index of the item which is currently
* selected in the receiver, or -1 if no item is selected.
*
- * @return the index of the selected item
+ * @return the index of the selected item or -1
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -620,7 +620,8 @@
}
/**
* Returns the zero-relative indices of the items which are currently
- * selected in the receiver. The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1304,7 +1305,7 @@
/**
* Selects the item at the given zero-relative index in the receiver.
* If the item at the index was already selected, it remains selected.
- * The current selected is first cleared, then the new items are selected.
+ * The current selection is first cleared, then the new item is selected.
* Indices that are out of range are ignored.
*
* @param index the index of the item to select
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java
index a9be6ee..31c4005 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java
@@ -366,7 +366,7 @@
}
/**
* Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -444,8 +444,8 @@
return count;
}
/**
- * Returns an array of <code>MenuItem</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>MenuItem</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -627,7 +627,7 @@
/**
* Returns <code>true</code> if the receiver is enabled and all
* of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu is typically not selectable from the
* user interface and draws with an inactive or "grayed" look.
*
* @return the receiver's enabled state
@@ -761,7 +761,7 @@
}
/**
* Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -778,11 +778,15 @@
OS.XtSetValues (handle, argList, argList.length / 2);
}
/**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
* <p>
- * Note: This is different from most widgets where the
+ * Note that this is different from most widgets where the
* location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
* </p>
*
* @param x the new x coordinate for the receiver
@@ -801,11 +805,15 @@
hasLocation = true;
}
/**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
* <p>
- * Note: This is different from most widgets where the
+ * Note that this is different from most widgets where the
* location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
* </p>
*
* @param location the new location for the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
index a2ba19f..54717f3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MenuItem.java
@@ -218,7 +218,7 @@
}
/**
* Adds the listener to the collection of listeners who will
- * be notified when the control is selected, by sending
+ * be notified when the menu item is selected, by sending
* it one of the messages defined in the <code>SelectionListener</code>
* interface.
* <p>
@@ -318,11 +318,13 @@
super.destroyWidget ();
}
/**
- * Return the widget accelerator. An accelerator is the bit-wise
+ * Returns the widget accelerator. An accelerator is the bit-wise
* OR of zero or more modifier masks and a key. Examples:
* <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
*
- * @return the accelerator
+ * @return the accelerator or 0
*
* </ul>
* @exception SWTException <ul>
@@ -343,7 +345,7 @@
}
/**
* Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu item is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -447,7 +449,7 @@
/**
* Returns <code>true</code> if the receiver is enabled and all
* of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu item is typically not selectable from the
* user interface and draws with an inactive or "grayed" look.
*
* @return the receiver's enabled state
@@ -616,6 +618,8 @@
* OR of zero or more modifier masks and a key. Examples:
* <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>.
* <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
*
* @param accelerator an integer that is the bit-wise OR of masks and a key
*
@@ -639,7 +643,7 @@
}
/**
* Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu item is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MessageBox.java
index e1320b4..b22dfaf 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MessageBox.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/MessageBox.java
@@ -109,9 +109,9 @@
}
/**
- * Returns the dialog's message, which is a description of
- * the purpose for which it was opened. This message will be
- * visible on the dialog while it is open.
+ * Returns the dialog's message, or an empty string if it does not have one.
+ * The message is a description of the purpose for which the dialog was opened.
+ * This message will be visible in the dialog while it is open.
*
* @return the message
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ProgressBar.java
index ca908c9..5bd84a7 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ProgressBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ProgressBar.java
@@ -173,7 +173,7 @@
return argList [1];
}
/**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the single 'selection' that is the receiver's position.
*
* @return the selection
*
@@ -270,7 +270,7 @@
setThumb(selection - value);
}
/**
- * Sets the single <em>selection</em> that is the receiver's
+ * Sets the single 'selection' that is the receiver's
* position to the argument which must be greater than or equal
* to zero.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java
index a84776d..b1b55cf 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java
@@ -203,7 +203,7 @@
return argList [1];
}
/**
- * Returns the <em>selection</em>, which is the receiver's position.
+ * Returns the 'selection', which is the receiver's position.
*
* @return the selection
*
@@ -347,9 +347,8 @@
display.setWarnings (warnings);
}
/**
- * Sets the <em>selection</em>, which is the receiver's
- * value, to the argument which must be greater than or equal
- * to zero.
+ * Sets the 'selection', which is the receiver's value,
+ * to the argument which must be greater than or equal to zero.
*
* @param value the new selection (must be zero or greater)
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java
index ab68d56..bc4788a 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java
@@ -21,7 +21,7 @@
* objects that represent a range of positive, numeric values.
* <p>
* At any given moment, a given scroll bar will have a
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
* value, which is constrained to be within the range of
* values the scroll bar represents (that is, between its
* <em>minimum</em> and <em>maximum</em> values).
@@ -96,6 +96,7 @@
* interface.
* <p>
* When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
+ * <code>SWT.NONE</code> - for the end of a drag.
* <code>SWT.DRAG</code>.
* <code>SWT.HOME</code>.
* <code>SWT.END</code>.
@@ -232,7 +233,7 @@
return argList [1];
}
/**
- * Returns the receiver's parent, which must be scrollable.
+ * Returns the receiver's parent, which must be a Scrollable.
*
* @return the receiver's parent
*
@@ -246,7 +247,7 @@
return parent;
}
/**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the single 'selection' that is the receiver's value.
*
* @return the selection
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
index d6a2b20..703710d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java
@@ -67,7 +67,7 @@
* it would be upgraded to <code>APPLICATION_MODAL</code>.
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd>
+ * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd>
* <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd>
* <dt><b>Events:</b></dt>
* <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd>
@@ -261,7 +261,7 @@
* @param parent a shell which will be the parent of the new instance
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -294,6 +294,9 @@
* @param parent a shell which will be the parent of the new instance
* @param style the style of control to construct
*
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
+ * </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
@@ -308,6 +311,8 @@
* @see SWT#NO_TRIM
* @see SWT#SHELL_TRIM
* @see SWT#DIALOG_TRIM
+ * @see SWT#ON_TOP
+ * @see SWT#TOOL
* @see SWT#MODELESS
* @see SWT#PRIMARY_MODAL
* @see SWT#APPLICATION_MODAL
@@ -1405,7 +1410,7 @@
}
}
/**
- * Sets the receiver's minimum size to the point specified by the arguments.
+ * Sets the receiver's minimum size to the size specified by the arguments.
* If the new minimum size is larger than the current size of the receiver,
* the receiver is resized to the new minimum size.
*
@@ -1428,7 +1433,7 @@
OS.XtSetValues (shellHandle, argList, argList.length / 2);
}
/**
- * Sets the receiver's minimum size to the point specified by the argument.
+ * Sets the receiver's minimum size to the size specified by the argument.
* If the new minimum size is larger than the current size of the receiver,
* the receiver is resized to the new minimum size.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Slider.java
index 7da69fa..fb890ad 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Slider.java
@@ -21,7 +21,7 @@
* objects that represent a range of positive, numeric values.
* <p>
* At any given moment, a given slider will have a
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
* value, which is constrained to be within the range of
* values the slider represents (that is, between its
* <em>minimum</em> and <em>maximum</em> values).
@@ -104,7 +104,7 @@
* interface.
* <p>
* When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
- * <code>0</code> - for the end of a drag.
+ * <code>SWT.NONE</code> - for the end of a drag.
* <code>SWT.DRAG</code>.
* <code>SWT.HOME</code>.
* <code>SWT.END</code>.
@@ -238,7 +238,7 @@
return argList [1];
}
/**
- * Returns the <em>selection</em>, which is the receiver's value.
+ * Returns the 'selection', which is the receiver's value.
*
* @return the selection
*
@@ -416,7 +416,7 @@
OS.XtSetValues (handle, argList, argList.length / 2);
}
/**
- * Sets the <em>selection</em>, which is the receiver's
+ * Sets the 'selection', which is the receiver's
* value, to the argument which must be greater than or equal
* to zero.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
index 99b0a48..e7cc1b2 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java
@@ -24,7 +24,7 @@
* <p>
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>READ_ONLY</dd>
+ * <dd>READ_ONLY, WRAP</dd>
* <dt><b>Events:</b></dt>
* <dd>Selection, Modify</dd>
* </dl>
@@ -61,6 +61,7 @@
* </ul>
*
* @see SWT#READ_ONLY
+ * @see SWT#WRAP
* @see Widget#checkSubclass
* @see Widget#getStyle
*/
@@ -310,6 +311,16 @@
OS.XtGetValues (handle, argList, argList.length / 2);
return argList [1];
}
+/**
+ * Returns the number of decimal places used by the receiver.
+ *
+ * @return the digits
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
public int getDigits () {
checkWidget ();
int [] argList = {OS.XmNdecimalPoints, 0};
@@ -552,6 +563,25 @@
}
return super.setBounds (x, y, width, height, move, resize);
}
+/**
+ * Sets the number of decimal places used by the receiver.
+ * <p>
+ * The digit setting is used to allow for floating point values in the receiver.
+ * For example, to set the selection to a floating point value of 1.37 call setDigits() with
+ * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value
+ * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all
+ * numeric APIs.
+ *
+ * @param value the new digits (must be greater than or equal to zero)
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
public void setDigits (int value) {
checkWidget ();
if (value < 0) error (SWT.ERROR_INVALID_ARGUMENT);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Text.java
index 31cf120..cb13de0 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Text.java
@@ -43,6 +43,10 @@
/**
* The maximum number of characters that can be entered
* into a text widget.
+ * <p>
+ * Note that this value is platform dependent, based upon
+ * the native widget implementation.
+ * </p>
*/
public static final int LIMIT;
/**
@@ -421,7 +425,7 @@
return display.textForeground;
}
/**
- * Gets the line number of the caret.
+ * Returns the line number of the caret.
* <p>
* The line number of the caret is returned.
* </p>
@@ -438,7 +442,8 @@
return getLineNumber (OS.XmTextGetInsertionPosition (handle));
}
/**
- * Gets the location the caret.
+ * 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>
@@ -459,9 +464,9 @@
return new Point (x [0], y [0] - getFontAscent (font.handle));
}
/**
- * Gets the position of the caret.
+ * Returns the character position of the caret.
* <p>
- * The character position of the caret is returned.
+ * Indexing is zero based.
* </p>
*
* @return the position of the caret
@@ -476,7 +481,7 @@
return OS.XmTextGetInsertionPosition (handle);
}
/**
- * Gets the number of characters.
+ * Returns the number of characters.
*
* @return number of characters in the widget
*
@@ -490,7 +495,7 @@
return OS.XmTextGetLastPosition (handle);
}
/**
- * Gets the double click enabled flag.
+ * Returns the double click enabled flag.
* <p>
* The double click flag enables or disables the
* default action of the text widget when the user
@@ -511,7 +516,7 @@
return argList [1] != 1;
}
/**
- * Gets the echo character.
+ * Returns the echo character.
* <p>
* The echo character is the character that is
* displayed when the user enters text or the
@@ -524,13 +529,15 @@
* <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 #setEchoChar
*/
public char getEchoChar () {
checkWidget();
return echoCharacter;
}
/**
- * Gets the editable state.
+ * Returns the editable state.
*
* @return whether or not the reciever is editable
*
@@ -553,7 +560,7 @@
return argList [1] != 0;
}
/**
- * Gets the number of lines.
+ * Returns the number of lines.
*
* @return the number of lines in the widget
*
@@ -569,7 +576,7 @@
return getLineNumber (lastChar) + 1;
}
/**
- * Gets the line delimiter.
+ * Returns the line delimiter.
*
* @return a string that is the line delimiter
*
@@ -577,13 +584,15 @@
* <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 #DELIMITER
*/
public String getLineDelimiter () {
checkWidget();
return "\n";
}
/**
- * Gets the height of a line.
+ * Returns the height of a line.
*
* @return the height of a row of text
*
@@ -651,7 +660,8 @@
return buffer [0];
}
/**
- * Returns the orientation of the receiver.
+ * Returns the orientation of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
*
* @return the orientation style
*
@@ -667,14 +677,17 @@
return style & (SWT.LEFT_TO_RIGHT | SWT.RIGHT_TO_LEFT);
}
/**
- * Gets the position of the selected text.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selected
+ * text, and whose y coordinate is the character position
+ * representing the end of the selection. An "empty" selection
+ * is indicated by the x and y coordinates having the same value.
* <p>
- * Indexing is zero based. The range of
- * a selection is from 0..N where N is
- * the number of characters in the widget.
+ * Indexing is zero based. The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
* </p>
- *
- * @return the start and end of the selection
+ *
+ * @return a point representing the selection start and end
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -691,7 +704,7 @@
return new Point (start [0], end [0]);
}
/**
- * Gets the number of selected characters.
+ * Returns the number of selected characters.
*
* @return the number of selected characters.
*
@@ -707,7 +720,7 @@
return end [0] - start [0];
}
/**
- * Gets the selected text.
+ * Gets the selected text, or an empty string if there is no current selection.
*
* @return the selected text
*
@@ -731,7 +744,7 @@
return new String (Converter.mbcsToWcs (getCodePage (), buffer));
}
/**
- * Gets the number of tabs.
+ * Returns the number of tabs.
* <p>
* Tab stop spacing is specified in terms of the
* space (' ') character. The width of a single
@@ -751,9 +764,10 @@
return 8;
}
/**
- * Gets the widget text.
+ * Returns the widget text.
* <p>
- * The text for a text widget is the characters in the widget.
+ * The text for a text widget is the characters in the widget, or
+ * an empty string if this has never been set.
* </p>
*
* @return the widget text
@@ -775,7 +789,7 @@
return new String (Converter.mbcsToWcs (getCodePage (), buffer));
}
/**
- * Gets a range of text. Returns an empty string if the
+ * Returns a range of text. Returns an empty string if the
* start of the range is greater than the end.
* <p>
* Indexing is zero based. The range of
@@ -826,6 +840,8 @@
* <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 #LIMIT
*/
public int getTextLimit () {
checkWidget();
@@ -857,7 +873,7 @@
return argList2 [1];
}
/**
- * Gets the top pixel.
+ * Returns the top pixel.
* <p>
* The top pixel is the pixel position of the line
* that is currently at the top of the widget. On
@@ -902,6 +918,9 @@
*
* @param string the string
*
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></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>
@@ -1088,6 +1107,9 @@
* The double click flag enables or disables the
* default action of the text widget when the user
* double clicks.
+ * </p><p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
* </p>
*
* @param doubleClick the new double click flag
@@ -1111,8 +1133,9 @@
* the echo character to '\0' clears the echo
* character and redraws the original text.
* If for any reason the echo character is invalid,
- * the default echo character for the platform
- * is used.
+ * or if the platform does not allow modification
+ * of the echo character, the default echo character
+ * for the platform is used.
* </p>
*
* @param echo the new echo character
@@ -1164,6 +1187,9 @@
* Sets the orientation of the receiver, which must be one
* of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
* <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
*
* @param orientation new orientation style
*
@@ -1226,7 +1252,8 @@
display.setWarnings (warnings);
}
/**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given start and end indices.
* <p>
* Indexing is zero based. The range of
* a selection is from 0..N where N is
@@ -1279,7 +1306,10 @@
display.setWarnings (warnings);
}
/**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given point, where the x coordinate
+ * represents the start index and the y coordinate
+ * represents the end index.
* <p>
* Indexing is zero based. The range of
* a selection is from 0..N where N is
@@ -1368,6 +1398,8 @@
* creating a read-only text widget.
* </p><p>
* To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Text.LIMIT</code> sets the
+ * receiver's limit to <code>Text.LIMIT</code>.
* </p>
*
* @param limit new text limit
@@ -1379,6 +1411,8 @@
* <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 #LIMIT
*/
public void setTextLimit (int limit) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
index b11318c..f510c01 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Widget.java
@@ -121,6 +121,7 @@
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -382,7 +383,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
* </ul>
*
- * @see #setData
+ * @see #setData(Object)
*/
public Object getData () {
checkWidget();
@@ -411,7 +412,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #setData
+ * @see #setData(String, Object)
*/
public Object getData (String key) {
checkWidget();
@@ -438,7 +439,6 @@
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
- * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*/
public Display getDisplay () {
@@ -889,6 +889,8 @@
* <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li>
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
* </ul>
+ *
+ * @see #getData()
*/
public void setData (Object data) {
checkWidget();
@@ -921,7 +923,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #getData
+ * @see #getData(String)
*/
public void setData (String key, Object value) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java
index 3968469..6305dbc 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Color.java
@@ -194,7 +194,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Cursor.java
index 9238ab3..28788f8 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Cursor.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Cursor.java
@@ -412,7 +412,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Device.java
index 2708825..bdceaf2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Device.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Device.java
@@ -390,7 +390,7 @@
* specified in class <code>SWT</code>. Any value other
* than one of the SWT color constants which is passed
* in will result in the color black. This color should
- * not be free'd because it was allocated by the system,
+ * not be freed because it was allocated by the system,
* not the application.
*
* @param id the color constant
@@ -430,7 +430,7 @@
* Returns a reasonable font for applications to use.
* On some platforms, this will match the "default font"
* or "system font" if such can be found. This font
- * should not be free'd because it was allocated by the
+ * should not be freed because it was allocated by the
* system, not the application.
* <p>
* Typically, applications which want the default look
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
index 1e80d67..c919730 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Font.java
@@ -193,7 +193,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontData.java
index d08ddc9..bf8927b 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontData.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontData.java
@@ -312,7 +312,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -414,7 +414,8 @@
/**
* Sets the style of the receiver to the argument which must
* be a bitwise OR of one or more of the <code>SWT</code>
- * constants NORMAL, BOLD and ITALIC.
+ * constants NORMAL, BOLD and ITALIC. All other style bits are
+ * ignored.
*
* @param style the new style for this <code>FontData</code>
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontMetrics.java
index 8012b78..4388c80 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontMetrics.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/FontMetrics.java
@@ -140,7 +140,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/GC.java
index 5e07270..94660b2 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/GC.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/GC.java
@@ -256,6 +256,24 @@
public void copyArea(int x, int y, int width, int height, int destX, int destY) {
copyArea(x, y, width, height, destX, destY, true);
}
+/**
+ * Copies a rectangular area of the receiver at the source
+ * position onto the receiver at the destination position.
+ *
+ * @param srcX the x coordinate in the receiver of the area to be copied
+ * @param srcY the y coordinate in the receiver of the area to be copied
+ * @param width the width of the area to copy
+ * @param height the height of the area to copy
+ * @param destX the x coordinate in the receiver of the area to copy to
+ * @param destY the y coordinate in the receiver of the area to copy to
+ * @param paint if <code>true</code> paint events will be generated for old and obscured areas
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void copyArea(int x, int y, int width, int height, int destX, int destY, boolean paint) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (width == 0 || height == 0) return;
@@ -516,7 +534,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void drawFocus (int x, int y, int width, int height) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -996,8 +1014,22 @@
}
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Draws the path described by the parameter.
+ *
+ * @param path the path to draw
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void drawPath(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1598,7 +1630,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1677,8 +1709,22 @@
}
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Fills the path described by the parameter.
+ *
+ * @param path the path to fill
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void fillPath (Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1738,7 +1784,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillRectangle (int x, int y, int width, int height) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1767,7 +1813,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see #drawRectangle
+ * @see #drawRectangle(int, int, int, int)
*/
public void fillRectangle (Rectangle rect) {
if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -1841,13 +1887,45 @@
return getCharWidth(ch);
}
+/**
+ * Returns <code>true</code> if receiver is using the operating system's
+ * advanced graphics subsystem. Otherwise, <code>false</code> is returned
+ * to indicate that normal graphics are in use.
+ * <p>
+ * Advanced graphics may not be installed for the operating system. In this
+ * case, <code>false</code> is always returned. Some operating system have
+ * only one graphics subsystem. If this subsystem supports advanced graphics,
+ * then <code>true</code> is always returned. If any graphics operation such
+ * as alpha, antialias, patterns, interpolation, paths, clipping or transformation
+ * has caused the receiver to switch from regular to advanced graphics mode,
+ * <code>true</code> is returned. If the receiver has been explicitly switched
+ * to advanced mode and this mode is supported, <code>true</code> is returned.
+ * </p>
+ *
+ * @return the advanced value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAdvanced
+ * @since 3.1
+ */
public boolean getAdvanced() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return false;
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's alpha value.
+ *
+ * @return the alpha value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public int getAlpha() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1855,7 +1933,20 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's anti-aliasing setting value, which will be
+ * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getTextAntialias
+ *
+ * @since 3.1
*/
public int getAntialias() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -1876,6 +1967,20 @@
return Color.photon_new(data.device, data.background);
}
+/**
+ * Returns the background pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's background pattern
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
+ */
public Pattern getBackgroundPattern() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return null;
@@ -2007,6 +2112,18 @@
}
}
+/**
+ * Returns the receiver's fill rule, which will be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @return the receiver's fill rule
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public int getFillRule() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
//TODO - implement fill rule
@@ -2060,13 +2177,37 @@
return Color.photon_new(data.device, data.foreground);
}
+/**
+ * Returns the foreground pattern. The default value is
+ * <code>null</code>.
+ *
+ * @return the receiver's foreground pattern
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
+ */
public Pattern getForegroundPattern() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return null;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Returns the receiver's interpolation setting, which will be one of
+ * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>,
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @return the receiver's interpolation setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public int getInterpolation() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2092,7 +2233,8 @@
}
/**
- * Returns the receiver's line dash style.
+ * Returns the receiver's line dash style. The default value is
+ * <code>null</code>.
*
* @return the lin dash style used for drawing lines
*
@@ -2189,15 +2331,43 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Returns the receiver's text drawing anti-aliasing setting value,
+ * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or
+ * <code>SWT.ON</code>. Note that this controls anti-aliasing
+ * <em>only</em> for text drawing operations.
+ *
+ * @return the anti-aliasing setting
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #getAntialias
+ *
+ * @since 3.1
*/
public int getTextAntialias() {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
return SWT.DEFAULT;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the parameter to the transform that is currently being
+ * used by the receiver.
+ *
+ * @param transform the destination to copy the transform into
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Transform
+ *
+ * @since 3.1
*/
public void getTransform(Transform transform) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2226,7 +2396,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -2309,6 +2479,48 @@
return handle == 0;
}
+/**
+ * Sets the receiver to always use the operating system's advanced graphics
+ * subsystem for all graphics operations if the argument is <code>true</code>.
+ * If the argument is <code>false</code>, the advanced graphics subsystem is
+ * no longer used, advanced graphics state is cleared and the normal graphics
+ * subsystem is used from now on.
+ * <p>
+ * Normally, the advanced graphics subsystem is invoked automatically when
+ * any one of the alpha, antialias, patterns, interpolation, paths, clipping
+ * or transformation operations in the receiver is requested. When the receiver
+ * is switched into advanced mode, the advanced graphics subsystem performs both
+ * advanced and normal graphics operations. Because the two subsystems are
+ * different, their output may differ. Switching to advanced graphics before
+ * any graphics operations are performed ensures that the output is consistent.
+ * </p>
+ * <p>
+ * Advanced graphics may not be installed for the operating system. In this
+ * case, this operation does nothing. Some operating system have only one
+ * graphics subsystem, so switching from normal to advanced graphics does
+ * nothing. However, switching from advanced to normal graphics will always
+ * clear the advanced graphics state, even for operating systems that have
+ * only one graphics subsystem.
+ * </p>
+ *
+ * @param advanced the new advanced graphics state
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAlpha
+ * @see #setAntialias
+ * @see #setBackgroundPattern
+ * @see #setClipping(Path)
+ * @see #setForegroundPattern
+ * @see #setInterpolation
+ * @see #setTextAntialias
+ * @see #setTransform
+ * @see #getAdvanced
+ *
+ * @since 3.1
+ */
public void setAdvanced(boolean advanced) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (!advanced) {
@@ -2324,14 +2536,39 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's alpha value.
+ *
+ * @param alpha the alpha value
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public void setAlpha(int alpha) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's anti-aliasing value to the parameter,
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all
+ * <em>non-text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setTextAntialias
+ *
+ * @since 3.1
*/
public void setAntialias(int antialias) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2368,6 +2605,22 @@
dirtyBits |= DIRTY_BACKGROUND;
}
+/**
+ * Sets the background pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new background pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
+ */
public void setBackgroundPattern (Pattern pattern) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (pattern == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -2415,7 +2668,22 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the area of the receiver which can be changed
+ * by drawing operations to the path specified
+ * by the argument.
+ *
+ * @param path the clipping path.
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Path
+ *
+ * @since 3.1
*/
public void setClipping(Path path) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2425,9 +2693,11 @@
/**
* Sets the area of the receiver which can be changed
* by drawing operations to the rectangular area specified
- * by the argument.
+ * by the argument. Specifying <code>null</code> for the
+ * rectangle reverts the receiver's clipping area to its
+ * original value.
*
- * @param rect the clipping rectangle
+ * @param rect the clipping rectangle or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
@@ -2449,9 +2719,11 @@
/**
* Sets the area of the receiver which can be changed
* by drawing operations to the region specified
- * by the argument.
+ * by the argument. Specifying <code>null</code> for the
+ * region reverts the receiver's clipping area to its
+ * original value.
*
- * @param region the clipping region.
+ * @param region the clipping region or <code>null</code>
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li>
@@ -2483,6 +2755,22 @@
dirtyBits |= DIRTY_CLIPPING;
}
+/**
+ * Sets the receiver's fill rule to the parameter, which must be one of
+ * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>.
+ *
+ * @param rule the new fill rule
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code>
+ * or <code>SWT.FILL_WINDING</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
+ */
public void setFillRule(int rule) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
switch (rule) {
@@ -2539,8 +2827,22 @@
dirtyBits |= DIRTY_FOREGROUND;
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the receiver's interpolation setting to the parameter, which
+ * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>,
+ * <code>SWT.LOW</code> or <code>SWT.HIGH</code>.
+ *
+ * @param interpolation the new interpolation setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @since 3.1
*/
public void setInterpolation(int interpolation) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2555,6 +2857,22 @@
}
}
+/**
+ * Sets the foreground pattern. The default value is <code>null</code>.
+ *
+ * @param pattern the new foreground pattern
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Pattern
+ *
+ * @since 3.1
+ */
public void setForegroundPattern (Pattern pattern) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
if (pattern == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -2592,7 +2910,10 @@
}
/**
- * Sets the receiver's line dash style to the argument.
+ * Sets the receiver's line dash style to the argument. The default
+ * value is <code>null</code>. If the argument is not <code>null</code>,
+ * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise
+ * it is set to <code>SWT.LINE_SOLID</code>.
*
* @param dashes the dash style to be used for drawing lines
*
@@ -2691,6 +3012,12 @@
* for all of the figure drawing operations (that is,
* <code>drawLine</code>, <code>drawRectangle</code>,
* <code>drawPolyline</code>, and so forth.
+ * <p>
+ * Note that line width of zero is used as a hint to
+ * indicate that the fastest possible line drawing
+ * algorithms should be used. This means that the
+ * output may be different from line width one.
+ * </p>
*
* @param lineWidth the width of a line
*
@@ -2870,7 +3197,24 @@
}
/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+ * Sets the receiver's text anti-aliasing value to the parameter,
+ * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code>
+ * or <code>SWT.ON</code>. Note that this controls anti-aliasing only
+ * for all <em>text drawing</em> operations.
+ *
+ * @param antialias the anti-aliasing setting
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>,
+ * <code>SWT.OFF</code> or <code>SWT.ON</code></li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see #setAntialias
+ *
+ * @since 3.1
*/
public void setTextAntialias(int antialias) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2883,8 +3227,23 @@
}
}
-/**
- * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE
+/**
+ * Sets the transform that is currently being used by the receiver. If
+ * the argument is <code>null</code>, the current transform is set to
+ * the identity transform.
+ *
+ * @param transform the transform to set
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
+ * </ul>
+ *
+ * @see Transform
+ *
+ * @since 3.1
*/
public void setTransform(Transform transform) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -2898,12 +3257,19 @@
* and the destination, and if the argument is <code>false</code>,
* puts the receiver in a drawing mode where the destination color
* is replaced with the source color value.
+ * <p>
+ * Note that this mode in fundamentally unsupportable on certain
+ * platforms, notably Carbon (Mac OS X). Clients that want their
+ * code to run on all platforms need to avoid this method.
+ * </p>
*
* @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used
*
* @exception SWTException <ul>
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ *
+ * @deprecated this functionality is not supported on some platforms
*/
public void setXORMode(boolean xor) {
if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Image.java
index 67fbbab..fcb05c3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Image.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Image.java
@@ -53,7 +53,7 @@
* loading process should use the support provided in class
* <code>ImageLoader</code>.
* </p><p>
- * Application code must explicitely invoke the <code>Image.dispose()</code>
+ * Application code must explicitly invoke the <code>Image.dispose()</code>
* method to release the operating system resources managed by each instance
* when those instances are no longer required.
* </p>
@@ -414,7 +414,20 @@
* This constructor may be used to load a resource as follows:
* </p>
* <pre>
- * new Image(device, clazz.getResourceAsStream("file.gif"));
+ * static Image loadImage (Display display, Class clazz, String string) {
+ * InputStream stream = clazz.getResourceAsStream (string);
+ * if (stream == null) return null;
+ * Image image = null;
+ * try {
+ * image = new Image (display, stream);
+ * } catch (SWTException ex) {
+ * } finally {
+ * try {
+ * stream.close ();
+ * } catch (IOException ex) {}
+ * }
+ * return image;
+ * }
* </pre>
*
* @param device the device on which to create the image
@@ -678,7 +691,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Region.java
index 6404ed4..c44ba76 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Region.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/graphics/Region.java
@@ -134,7 +134,6 @@
* @param height the height coordinate of the rectangle
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
* <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
* </ul>
* @exception SWTException <ul>
@@ -298,7 +297,7 @@
/**
* Returns an integer hash code for the receiver. Any two
- * objects which return <code>true</code> when passed to
+ * objects that return <code>true</code> when passed to
* <code>equals</code> must return the same value for this
* method.
*
@@ -412,7 +411,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
*/
public boolean intersects (int x, int y, int width, int height) {
if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
@@ -446,7 +445,7 @@
* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
* </ul>
*
- * @see Rectangle#intersects
+ * @see Rectangle#intersects(Rectangle)
*/
public boolean intersects (Rectangle rect) {
if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
@@ -540,7 +539,6 @@
* @param height the height coordinate of the rectangle
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the argument is null</li>
* <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li>
* </ul>
* @exception SWTException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Button.java
index 50ec642..faa9f4d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Button.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Button.java
@@ -507,9 +507,9 @@
/**
* Sets the receiver's image to the argument, which may be
- * null indicating that no image should be displayed.
+ * <code>null</code> indicating that no image should be displayed.
*
- * @param image the image to display on the receiver (may be null)
+ * @param image the image to display on the receiver (may be <code>null</code>)
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
index f890c3a..17030b0 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Canvas.java
@@ -61,7 +61,6 @@
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
- * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
* </ul>
*
* @see SWT
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Combo.java
index a41cfba..71b0174 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Combo.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Combo.java
@@ -587,8 +587,8 @@
}
/**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver's list.
+ * Returns a (possibly empty) array of <code>String</code>s which are
+ * the items in the receiver's list.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -644,11 +644,16 @@
}
/**
- * Returns a <code>Point</code> whose x coordinate is the start
- * of the selection in the receiver's text field, and whose y
- * coordinate is the end of the selection. The returned values
- * are zero-relative. An "empty" selection as indicated by
- * the the x and y coordinates having the same value.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selection
+ * in the receiver's text field, and whose y coordinate is the
+ * character position representing the end of the selection.
+ * An "empty" selection is indicated by the x and y coordinates
+ * having the same value.
+ * <p>
+ * Indexing is zero based. The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
+ * </p>
*
* @return a point representing the selection start and end
*
@@ -705,7 +710,8 @@
/**
* Returns a string containing a copy of the contents of the
- * receiver's text field.
+ * receiver's text field, or an empty string if there are no
+ * contents.
*
* @return the receiver's text
*
@@ -761,6 +767,8 @@
* <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 #LIMIT
*/
public int getTextLimit () {
checkWidget();
@@ -1119,8 +1127,8 @@
/**
* Sets the text of the item in the receiver's list at the given
* zero-relative index to the string argument. This is equivalent
- * to <code>remove</code>'ing the old item at the index, and then
- * <code>add</code>'ing the new item at that index.
+ * to removing the old item at the index, and then adding the new
+ * item at that index.
*
* @param index the index for the item
* @param string the new text for the item
@@ -1268,7 +1276,11 @@
/**
* Sets the maximum number of characters that the receiver's
* text field is capable of holding to be the argument.
- *
+ * <p>
+ * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the
+ * receiver's limit to <code>Combo.LIMIT</code>.
+ * </p>
* @param limit new text limit
*
* @exception IllegalArgumentException <ul>
@@ -1278,6 +1290,8 @@
* <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 #LIMIT
*/
public void setTextLimit (int limit) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Composite.java
index 06d06c4..c333579 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Composite.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Composite.java
@@ -20,7 +20,7 @@
* of containing other controls.
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd>
+ * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd>
* <dt><b>Events:</b></dt>
* <dd>(none)</dd>
* </dl>
@@ -437,7 +437,7 @@
}
/**
- * Returns an array containing the receiver's children.
+ * Returns a (possibly empty) array containing the receiver's children.
* Children are returned in the order that they are drawn.
* <p>
* Note: This is not the actual structure used by the receiver
@@ -544,7 +544,7 @@
}
/**
- * Gets the last specified tabbing order for the control.
+ * Gets the (possibly empty) tabbing order for the control.
*
* @return tabList the ordered list of controls representing the tab order
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
index 974b0b2..54b5d1a 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Control.java
@@ -380,7 +380,7 @@
* @see #getBorderWidth
* @see #getBounds
* @see #getSize
- * @see #pack
+ * @see #pack(boolean)
* @see "computeTrim, getClientArea for controls that implement them"
*/
public Point computeSize (int wHint, int hHint) {
@@ -418,7 +418,7 @@
* @see #getBorderWidth
* @see #getBounds
* @see #getSize
- * @see #pack
+ * @see #pack(boolean)
* @see "computeTrim, getClientArea for controls that implement them"
*/
public Point computeSize (int wHint, int hHint, boolean changed) {
@@ -1226,7 +1226,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
*/
public void pack () {
checkWidget();
@@ -1252,7 +1252,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #computeSize
+ * @see #computeSize(int, int, boolean)
*/
public void pack (boolean changed) {
checkWidget();
@@ -2314,7 +2314,8 @@
* @return <code>true</code> if the parent is changed and <code>false</code> otherwise.
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li>
+ * <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -2384,7 +2385,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
* @see #update
*/
public void setRedraw (boolean redraw) {
@@ -2775,7 +2776,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #redraw
+ * @see #redraw(int, int, int, int, boolean)
* @see PaintListener
* @see SWT#Paint
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java
index d651c4c..306d5e3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java
@@ -237,9 +237,9 @@
* marked as iconified, and may also be displayed somewhere
* in the trim when the instance is in normal or maximized
* states. Depending where the icon is displayed, the platform
- * chooses the icon with the "best" size. It is expected that
- * the array will contain the same icon rendered at different
- * resolutions.
+ * chooses the icon with the "best" attributes. It is expected
+ * that the array will contain the same icon rendered at different
+ * sizes, with different depth and transparency attributes.
*
* <p>
* Note: This method will return an empty array if called before
@@ -415,7 +415,11 @@
* <em>saved default button</em>). If no default button had
* previously been set, or the saved default button was
* disposed, the receiver's default button will be set to
- * null.
+ * null.
+ * <p>
+ * The default button is the button that is selected when
+ * the receiver is active and the user presses ENTER.
+ * </p>
*
* @param button the new default button
*
@@ -483,8 +487,9 @@
* and may also be displayed somewhere in the trim when the
* instance is in normal or maximized states. Depending where
* the icon is displayed, the platform chooses the icon with
- * the "best" size. It is expected that the array will contain
- * the same icon rendered at different resolutions.
+ * the "best" attributes. It is expected that the array will
+ * contain the same icon rendered at different sizes, with
+ * different depth and transparency attributes.
*
* @param images the new image array
*
@@ -516,7 +521,7 @@
* causes the receiver to switch back to either the minimized
* or normal states.
* <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
* and <code>setMinimized(true)</code> will vary by platform. Typically,
* the behavior will match the platform user's expectations, but not
* always. This should be avoided if possible.
@@ -564,7 +569,7 @@
* causes the receiver to switch back to either the maximized
* or normal states.
* <p>
- * Note: The result of intermixing calls to<code>setMaximized(true)</code>
+ * Note: The result of intermixing calls to <code>setMaximized(true)</code>
* and <code>setMinimized(true)</code> will vary by platform. Typically,
* the behavior will match the platform user's expectations, but not
* always. This should be avoided if possible.
@@ -586,7 +591,7 @@
/**
* 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 may not be null.
+ * <em>title</em>, to the argument, which must not be null.
*
* @param string the new text
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/DirectoryDialog.java
index 6d1ad39..128466a 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/DirectoryDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/DirectoryDialog.java
@@ -83,6 +83,8 @@
* the directories it shows.
*
* @return the filter path
+ *
+ * @see #setFilterPath
*/
public String getFilterPath () {
return filterPath;
@@ -135,9 +137,15 @@
}
/**
- * Sets the path which the dialog will use to filter
- * the directories it shows to the argument, which may be
- * null.
+ * Sets the path that the dialog will use to filter
+ * the directories it shows to the argument, which may
+ * be null. If the string is null, then the operating
+ * system's default filter path will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
*
* @param string the filter path
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
index d78b93b..a80711d 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java
@@ -313,7 +313,7 @@
* </p>
*
* @exception SWTException <ul>
- * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li>
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
* </ul>
*
@@ -326,6 +326,11 @@
this (null);
}
+/**
+ * Constructs a new instance of this class using the parameter.
+ *
+ * @param data the device data
+ */
public Display (DeviceData data) {
super (data);
}
@@ -404,9 +409,16 @@
* be invoked by the user-interface thread at the next
* reasonable opportunity. The caller of this method continues
* to run in parallel, and is not notified when the
- * runnable has completed.
+ * runnable has completed. Specifying <code>null</code> as the
+ * runnable simply wakes the user-interface thread when run.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
*
- * @param runnable code to run on the user-interface thread.
+ * @param runnable code to run on the user-interface thread or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
@@ -549,7 +561,7 @@
* <p>
* This method is called after <code>release</code>.
* </p>
- * @see #dispose
+ * @see Device#dispose
* @see #release
*/
protected void destroy () {
@@ -565,7 +577,8 @@
/**
* Causes the <code>run()</code> method of the runnable to
* be invoked by the user-interface thread just before the
- * receiver is disposed.
+ * receiver is disposed. Specifying a <code>null</code> runnable
+ * is ignored.
*
* @param runnable code to run at dispose time.
*
@@ -611,7 +624,9 @@
/**
* Returns the display which the given thread is the
* user-interface thread for, or null if the given thread
- * is not a user-interface thread for any display.
+ * is not a user-interface thread for any display. Specifying
+ * <code>null</code> as the thread will return <code>null</code>
+ * for the display.
*
* @param thread the user-interface thread
* @return the display for the given thread
@@ -824,9 +839,10 @@
/**
* On platforms which support it, sets the application name
* to be the argument. On Motif, for example, this can be used
- * to set the name used for resource lookup.
+ * to set the name used for resource lookup. Specifying
+ * <code>null</code> for the name clears it.
*
- * @param name the new app name
+ * @param name the new app name or <code>null</code>
*/
public static void setAppName (String name) {
/* Do nothing */
@@ -929,9 +945,8 @@
}
/**
- * Returns the maximum allowed depth of icons on this display.
- * On some platforms, this may be different than the actual
- * depth of the display.
+ * Returns the maximum allowed depth of icons on this display, in bits per pixel.
+ * On some platforms, this may be different than the actual depth of the display.
*
* @return the maximum icon depth
*
@@ -939,6 +954,8 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li>
* </ul>
+ *
+ * @see Device#getDepth
*/
public int getIconDepth () {
return getDepth ();
@@ -1024,8 +1041,8 @@
}
/**
- * Returns an array containing all shells which have not been
- * disposed and have the receiver as their display.
+ * Returns a (possibly empty) array containing all shells which have
+ * not been disposed and have the receiver as their display.
*
* @return the receiver's shells
*
@@ -1585,7 +1602,7 @@
* Applications may have associated arbitrary objects with the
* receiver in this fashion. If the objects stored in the
* properties need to be notified when the display is disposed
- * of, it is the application's responsibility provide a
+ * of, it is the application's responsibility to provide a
* <code>disposeExec()</code> handler which does so.
* </p>
*
@@ -1622,7 +1639,7 @@
* Applications may put arbitrary objects in this field. If
* the object stored in the display specific data needs to
* be notified when the display is disposed of, it is the
- * application's responsibility provide a
+ * application's responsibility to provide a
* <code>disposeExec()</code> handler which does so.
* </p>
*
@@ -2003,7 +2020,7 @@
* </p>
* This method is called before <code>destroy</code>.
*
- * @see #dispose
+ * @see Device#dispose
* @see #destroy
*/
protected void release () {
@@ -2394,9 +2411,16 @@
* Causes the <code>run()</code> method of the runnable to
* be invoked by the user-interface thread at the next
* reasonable opportunity. The thread which calls this method
- * is suspended until the runnable completes.
- *
- * @param runnable code to run on the user-interface thread.
+ * is suspended until the runnable completes. Specifying <code>null</code>
+ * as the runnable simply wakes the user-interface thread.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
+ *
+ * @param runnable code to run on the user-interface thread or <code>null</code>
*
* @exception SWTException <ul>
* <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li>
@@ -2424,6 +2448,12 @@
* be invoked by the user-interface thread after the specified
* number of milliseconds have elapsed. If milliseconds is less
* than zero, the runnable is not executed.
+ * <p>
+ * Note that at the time the runnable is invoked, widgets
+ * that have the receiver as their display may have been
+ * disposed. Therefore, it is necessary to check for this
+ * case inside the runnable before accessing the widget.
+ * </p>
*
* @param milliseconds the delay before running the runnable
* @param runnable code to run on the user-interface thread
@@ -2529,7 +2559,7 @@
}
/**
- * If the receiver's user-interface thread was <code>sleep</code>'ing,
+ * If the receiver's user-interface thread was <code>sleep</code>ing,
* causes it to be awakened and start running again. Note that this
* method may be called from any thread.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/FileDialog.java
index 964d721..dbff1ba 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/FileDialog.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/FileDialog.java
@@ -25,6 +25,8 @@
* <dd>(none)</dd>
* </dl>
* <p>
+ * Note: Only one of the styles SAVE and OPEN may be specified.
+ * </p><p>
* IMPORTANT: This class is intended to be subclassed <em>only</em>
* within the SWT implementation.
* </p>
@@ -83,7 +85,8 @@
/**
* Returns the path of the first file that was
- * selected in the dialog relative to the filter path
+ * selected in the dialog relative to the filter path, or an
+ * empty string if no such file has been selected.
*
* @return the relative path of the file
*/
@@ -92,8 +95,8 @@
}
/**
- * Returns the paths of all files that were selected
- * in the dialog relative to the filter path.
+ * Returns a (possibly empty) array with the paths of all files
+ * that were selected in the dialog relative to the filter path.
*
* @return the relative paths of the files
*/
@@ -113,19 +116,19 @@
}
/**
- * Returns the file names which the dialog will
- * use to filter the files it shows.
+ * Returns the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows.
*
- * @return the file name filter
+ * @return the list of filter names
*/
public String [] getFilterNames () {
return filterNames;
}
/**
- * Returns the directory path that the dialog will use.
- * File names in this path will appear in the dialog,
- * filtered according to the filter extensions.
+ * Returns the directory path that the dialog will use, or an empty
+ * string if this is not set. File names in this path will appear
+ * in the dialog, filtered according to the filter extensions.
*
* @return the directory path string
*
@@ -230,6 +233,11 @@
* Set the file extensions which the dialog will
* use to filter the files it shows to the argument,
* which may be null.
+ * <p>
+ * The strings are platform specific. For example, on
+ * Windows, an extension filter string is typically of
+ * the form "*.extension", where "*.*" matches all files.
+ * </p>
*
* @param extensions the file extension filter
*/
@@ -238,11 +246,11 @@
}
/**
- * Sets the file names which the dialog will
- * use to filter the files it shows to the argument,
- * which may be null.
+ * Sets the the names that describe the filter extensions
+ * which the dialog will use to filter the files it shows
+ * to the argument, which may be null.
*
- * @param names the file name filter
+ * @param names the list of filter names
*/
public void setFilterNames (String [] names) {
filterNames = names;
@@ -252,7 +260,14 @@
* Sets the directory path that the dialog will use
* to the argument, which may be null. File names in this
* path will appear in the dialog, filtered according
- * to the filter extensions.
+ * to the filter extensions. If the string is null,
+ * then the operating system's default filter path
+ * will be used.
+ * <p>
+ * Note that the path string is platform dependent.
+ * For convenience, either '/' or '\' can be used
+ * as a path separator.
+ * </p>
*
* @param string the directory path
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
index 4096f86..1b5a08a 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Link.java
@@ -22,6 +22,7 @@
* <p>
* <dl>
* <dt><b>Styles:</b></dt>
+ * <dd>(none)</dd>
* <dt><b>Events:</b></dt>
* <dd>Selection</dd>
* </dl>
@@ -583,7 +584,7 @@
* is delimited by an anchor tag, <A> and </A>. Within an
* anchor, a single HREF attribute is supported. When a hyperlink is
* selected, the text field of the selection event contains either the
- * text of hyperlink or the value of the HREF, if one was specified.
+ * text of the hyperlink or the value of its HREF, if one was specified.
* In the rare case of identical hyperlinks within the same string, the
* HREF tag can be used to distinguish between them. The string may
* include the mnemonic character and line delimiters.
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java
index 75783b3..bbab8d4 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java
@@ -19,7 +19,7 @@
/**
* Instances of this class represent a selectable user interface
- * object that displays a list of strings and issues notificiation
+ * object that displays a list of strings and issues notification
* when a string selected. A list may be single or multi select.
* <p>
* <dl>
@@ -415,7 +415,7 @@
/**
* Returns the height of the area which would be used to
- * display <em>one</em> of the items in the tree.
+ * display <em>one</em> of the items in the list.
*
* @return the height of one item
*
@@ -445,8 +445,8 @@
}
/**
- * Returns an array of <code>String</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>String</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -483,8 +483,8 @@
/**
* Returns an array of <code>String</code>s that are currently
- * selected in the receiver. An empty array indicates that no
- * items are selected.
+ * selected in the receiver. The order of the items is unspecified.
+ * An empty array indicates that no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -528,7 +528,7 @@
* Returns the zero-relative index of the item which is currently
* selected in the receiver, or -1 if no item is selected.
*
- * @return the index of the selected item
+ * @return the index of the selected item or -1
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -550,7 +550,8 @@
/**
* Returns the zero-relative indices of the items which are currently
- * selected in the receiver. The array is empty if no items are selected.
+ * selected in the receiver. The order of the indices is unspecified.
+ * The array is empty if no items are selected.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its selection, so modifying the array will
@@ -1107,7 +1108,7 @@
/**
* Selects the item at the given zero-relative index in the receiver.
* If the item at the index was already selected, it remains selected.
- * The current selected is first cleared, then the new items are selected.
+ * The current selection is first cleared, then the new item is selected.
* Indices that are out of range are ignored.
*
* @param index the index of the item to select
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java
index bc439c3..efe4970 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java
@@ -259,7 +259,7 @@
/**
* Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -333,8 +333,8 @@
}
/**
- * Returns an array of <code>MenuItem</code>s which are the items
- * in the receiver.
+ * Returns a (possibly empty) array of <code>MenuItem</code>s which
+ * are the items in the receiver.
* <p>
* Note: This is not the actual structure used by the receiver
* to maintain its list of items, so modifying the array will
@@ -528,7 +528,7 @@
/**
* Returns <code>true</code> if the receiver is enabled and all
* of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu is typically not selectable from the
* user interface and draws with an inactive or "grayed" look.
*
* @return the receiver's enabled state
@@ -687,7 +687,7 @@
/**
* Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -706,11 +706,15 @@
}
/**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the arguments which are relative
+ * to the display.
* <p>
- * Note: This is different from most widgets where the
+ * Note that this is different from most widgets where the
* location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
* </p>
*
* @param x the new x coordinate for the receiver
@@ -729,11 +733,15 @@
}
/**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the display.
+ * Sets the location of the receiver, which must be a popup,
+ * to the point specified by the argument which is relative
+ * to the display.
* <p>
- * Note: This is different from most widgets where the
+ * Note that this is different from most widgets where the
* location of the widget is relative to the parent.
+ * </p><p>
+ * Note that the platform window manager ultimately has control
+ * over the location of popup menus.
* </p>
*
* @param location the new location for the receiver
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
index dc44683..769f6d5 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MenuItem.java
@@ -186,7 +186,7 @@
/**
* Adds the listener to the collection of listeners who will
- * be notified when the control is selected, by sending
+ * be notified when the menu item is selected, by sending
* it one of the messages defined in the <code>SelectionListener</code>
* interface.
* <p>
@@ -261,11 +261,13 @@
}
/**
- * Return the widget accelerator. An accelerator is the bit-wise
+ * Returns the widget accelerator. An accelerator is the bit-wise
* OR of zero or more modifier masks and a key. Examples:
* <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
*
- * @return the accelerator
+ * @return the accelerator or 0
*
* </ul>
* @exception SWTException <ul>
@@ -280,7 +282,7 @@
/**
* Returns <code>true</code> if the receiver is enabled, and
- * <code>false</code> otherwise. A disabled control is typically
+ * <code>false</code> otherwise. A disabled menu item is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -385,7 +387,7 @@
/**
* Returns <code>true</code> if the receiver is enabled and all
* of the receiver's ancestors are enabled, and <code>false</code>
- * otherwise. A disabled control is typically not selectable from the
+ * otherwise. A disabled menu item is typically not selectable from the
* user interface and draws with an inactive or "grayed" look.
*
* @return the receiver's enabled state
@@ -576,6 +578,8 @@
* OR of zero or more modifier masks and a key. Examples:
* <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>.
* <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>.
+ * The default value is zero, indicating that the menu item does
+ * not have an accelerator.
*
* @param accelerator an integer that is the bit-wise OR of masks and a key
*
@@ -595,7 +599,7 @@
/**
* Enables the receiver if the argument is <code>true</code>,
- * and disables it otherwise. A disabled control is typically
+ * and disables it otherwise. A disabled menu item is typically
* not selectable from the user interface and draws with an
* inactive or "grayed" look.
*
@@ -621,8 +625,9 @@
/**
* Sets the image the receiver will display to the argument.
* <p>
- * Note: This feature is not available on all window systems (for example, Window NT),
- * in which case, calling this method will silently do nothing.
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept (for example, Windows NT).
+ * </p>
*
* @param image the image to display
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MessageBox.java
index a08f6e8..a817c89 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MessageBox.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/MessageBox.java
@@ -91,9 +91,9 @@
return style;
}
/**
- * Returns the dialog's message, which is a description of
- * the purpose for which it was opened. This message will be
- * visible on the dialog while it is open.
+ * Returns the dialog's message, or an empty string if it does not have one.
+ * The message is a description of the purpose for which the dialog was opened.
+ * This message will be visible in the dialog while it is open.
*
* @return the message
*/
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ProgressBar.java
index cb24ebd..263add3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ProgressBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ProgressBar.java
@@ -156,7 +156,7 @@
}
/**
- * Returns the single <em>selection</em> that is the receiver's position.
+ * Returns the single 'selection' that is the receiver's position.
*
* @return the selection
*
@@ -215,7 +215,7 @@
}
/**
- * Sets the single <em>selection</em> that is the receiver's
+ * Sets the single 'selection' that is the receiver's
* position to the argument which must be greater than or equal
* to zero.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java
index 9555970..414b7a3 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java
@@ -221,7 +221,7 @@
}
/**
- * Returns the <em>selection</em>, which is the receiver's position.
+ * Returns the 'selection', which is the receiver's position.
*
* @return the selection
*
@@ -347,9 +347,8 @@
}
/**
- * Sets the <em>selection</em>, which is the receiver's
- * value, to the argument which must be greater than or equal
- * to zero.
+ * Sets the 'selection', which is the receiver's value,
+ * to the argument which must be greater than or equal to zero.
*
* @param value the new selection (must be zero or greater)
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
index 606d8e3..36c5cb6 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java
@@ -21,7 +21,7 @@
* objects that represent a range of positive, numeric values.
* <p>
* At any given moment, a given scroll bar will have a
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
* value, which is constrained to be within the range of
* values the scroll bar represents (that is, between its
* <em>minimum</em> and <em>maximum</em> values).
@@ -107,6 +107,7 @@
* interface.
* <p>
* When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
+ * <code>SWT.NONE</code> - for the end of a drag.
* <code>SWT.DRAG</code>.
* <code>SWT.HOME</code>.
* <code>SWT.END</code>.
@@ -263,7 +264,7 @@
}
/**
- * Returns the receiver's parent, which must be scrollable.
+ * Returns the receiver's parent, which must be a Scrollable.
*
* @return the receiver's parent
*
@@ -278,7 +279,7 @@
}
/**
- * Returns the single <em>selection</em> that is the receiver's value.
+ * Returns the single 'selection' that is the receiver's value.
*
* @return the selection
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
index f859478..0839d57 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java
@@ -67,7 +67,7 @@
* it would be upgraded to <code>APPLICATION_MODAL</code>.
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd>
+ * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd>
* <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd>
* <dt><b>Events:</b></dt>
* <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd>
@@ -260,7 +260,7 @@
* @param parent a shell which will be the parent of the new instance
*
* @exception IllegalArgumentException <ul>
- * <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -294,6 +294,9 @@
* @param parent a shell which will be the parent of the new instance
* @param style the style of control to construct
*
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
+ * </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
* <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li>
@@ -308,6 +311,8 @@
* @see SWT#NO_TRIM
* @see SWT#SHELL_TRIM
* @see SWT#DIALOG_TRIM
+ * @see SWT#ON_TOP
+ * @see SWT#TOOL
* @see SWT#MODELESS
* @see SWT#PRIMARY_MODAL
* @see SWT#APPLICATION_MODAL
@@ -1124,7 +1129,7 @@
}
/**
- * Sets the receiver's minimum size to the point specified by the arguments.
+ * Sets the receiver's minimum size to the size specified by the arguments.
* If the new minimum size is larger than the current size of the receiver,
* the receiver is resized to the new minimum size.
*
@@ -1156,7 +1161,7 @@
}
/**
- * Sets the receiver's minimum size to the point specified by the argument.
+ * Sets the receiver's minimum size to the size specified by the argument.
* If the new minimum size is larger than the current size of the receiver,
* the receiver is resized to the new minimum size.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
index 4f4755f..0da568e 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Slider.java
@@ -21,7 +21,7 @@
* objects that represent a range of positive, numeric values.
* <p>
* At any given moment, a given slider will have a
- * single <em>selection</em> that is considered to be its
+ * single 'selection' that is considered to be its
* value, which is constrained to be within the range of
* values the slider represents (that is, between its
* <em>minimum</em> and <em>maximum</em> values).
@@ -110,7 +110,7 @@
* interface.
* <p>
* When <code>widgetSelected</code> is called, the event object detail field contains one of the following values:
- * <code>0</code> - for the end of a drag.
+ * <code>SWT.NONE</code> - for the end of a drag.
* <code>SWT.DRAG</code>.
* <code>SWT.HOME</code>.
* <code>SWT.END</code>.
@@ -254,7 +254,7 @@
}
/**
- * Returns the <em>selection</em>, which is the receiver's value.
+ * Returns the 'selection', which is the receiver's value.
*
* @return the selection
*
@@ -467,7 +467,7 @@
}
/**
- * Sets the <em>selection</em>, which is the receiver's
+ * Sets the 'selection', which is the receiver's
* value, to the argument which must be greater than or equal
* to zero.
*
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
index ecf1aff..89c1c7c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java
@@ -22,7 +22,7 @@
* <p>
* <dl>
* <dt><b>Styles:</b></dt>
- * <dd>READ_ONLY</dd>
+ * <dd>READ_ONLY, WRAP</dd>
* <dt><b>Events:</b></dt>
* <dd>Selection, Modify</dd>
* </dl>
@@ -59,6 +59,7 @@
* </ul>
*
* @see SWT#READ_ONLY
+ * @see SWT#WRAP
* @see Widget#checkSubclass
* @see Widget#getStyle
*/
@@ -321,6 +322,16 @@
return display.TEXT_FOREGROUND;
}
+/**
+ * Returns the number of decimal places used by the receiver.
+ *
+ * @return the digits
+ *
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
public int getDigits () {
checkWidget ();
return 0;
@@ -550,6 +561,25 @@
eventTable.unhook (SWT.Verify, listener);
}
+/**
+ * Sets the number of decimal places used by the receiver.
+ * <p>
+ * The digit setting is used to allow for floating point values in the receiver.
+ * For example, to set the selection to a floating point value of 1.37 call setDigits() with
+ * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value
+ * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all
+ * numeric APIs.
+ *
+ * @param value the new digits (must be greater than or equal to zero)
+ *
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</li>
+ * </ul>
+ * @exception SWTException <ul>
+ * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
+ * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
+ * </ul>
+ */
public void setDigits (int value) {
checkWidget ();
}
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
index eae743d..0d399da 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Text.java
@@ -43,6 +43,10 @@
/**
* The maximum number of characters that can be entered
* into a text widget.
+ * <p>
+ * Note that this value is platform dependent, based upon
+ * the native widget implementation.
+ * </p>
*/
public static final int LIMIT;
/**
@@ -399,7 +403,7 @@
}
/**
- * Gets the line number of the caret.
+ * Returns the line number of the caret.
* <p>
* The line number of the caret is returned.
* </p>
@@ -418,7 +422,8 @@
}
/**
- * Gets the location the caret.
+ * 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>
@@ -437,9 +442,9 @@
}
/**
- * Gets the position of the caret.
+ * Returns the character position of the caret.
* <p>
- * The character position of the caret is returned.
+ * Indexing is zero based.
* </p>
*
* @return the position of the caret
@@ -457,7 +462,7 @@
}
/**
- * Gets the number of characters.
+ * Returns the number of characters.
*
* @return number of characters in the widget
*
@@ -475,7 +480,7 @@
}
/**
- * Gets the double click enabled flag.
+ * Returns the double click enabled flag.
* <p>
* The double click flag enables or disables the
* default action of the text widget when the user
@@ -496,7 +501,7 @@
}
/**
- * Gets the echo character.
+ * Returns the echo character.
* <p>
* The echo character is the character that is
* displayed when the user enters text or the
@@ -509,6 +514,8 @@
* <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 #setEchoChar
*/
public char getEchoChar () {
checkWidget();
@@ -516,7 +523,7 @@
}
/**
- * Gets the editable state.
+ * Returns the editable state.
*
* @return whether or not the reciever is editable
*
@@ -533,7 +540,7 @@
}
/**
- * Gets the number of lines.
+ * Returns the number of lines.
*
* @return the number of lines in the widget
*
@@ -551,7 +558,7 @@
}
/**
- * Gets the line delimiter.
+ * Returns the line delimiter.
*
* @return a string that is the line delimiter
*
@@ -559,6 +566,8 @@
* <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 #DELIMITER
*/
public String getLineDelimiter () {
checkWidget();
@@ -566,7 +575,7 @@
}
/**
- * Gets the height of a line.
+ * Returns the height of a line.
*
* @return the height of a row of text
*
@@ -609,7 +618,8 @@
}
/**
- * Returns the orientation of the receiver.
+ * Returns the orientation of the receiver, which will be one of the
+ * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
*
* @return the orientation style
*
@@ -626,14 +636,17 @@
}
/**
- * Gets the position of the selected text.
+ * Returns a <code>Point</code> whose x coordinate is the
+ * character position representing the start of the selected
+ * text, and whose y coordinate is the character position
+ * representing the end of the selection. An "empty" selection
+ * is indicated by the x and y coordinates having the same value.
* <p>
- * Indexing is zero based. The range of
- * a selection is from 0..N where N is
- * the number of characters in the widget.
+ * Indexing is zero based. The range of a selection is from
+ * 0..N where N is the number of characters in the widget.
* </p>
- *
- * @return the start and end of the selection
+ *
+ * @return a point representing the selection start and end
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
@@ -656,7 +669,7 @@
}
/**
- * Gets the number of selected characters.
+ * Returns the number of selected characters.
*
* @return the number of selected characters.
*
@@ -672,7 +685,7 @@
}
/**
- * Gets the selected text.
+ * Gets the selected text, or an empty string if there is no current selection.
*
* @return the selected text
*
@@ -693,7 +706,7 @@
}
/**
- * Gets the number of tabs.
+ * Returns the number of tabs.
* <p>
* Tab stop spacing is specified in terms of the
* space (' ') character. The width of a single
@@ -725,7 +738,7 @@
}
/**
- * Gets a range of text. Returns an empty string if the
+ * Returns a range of text. Returns an empty string if the
* start of the range is greater than the end.
* <p>
* Indexing is zero based. The range of
@@ -759,9 +772,10 @@
}
/**
- * Gets the widget text.
+ * Returns the widget text.
* <p>
- * The text for a text widget is the characters in the widget.
+ * The text for a text widget is the characters in the widget, or
+ * an empty string if this has never been set.
* </p>
*
* @return the widget text
@@ -797,6 +811,8 @@
* <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 #LIMIT
*/
public int getTextLimit () {
checkWidget();
@@ -828,7 +844,7 @@
}
/**
- * Gets the top pixel.
+ * Returns the top pixel.
* <p>
* The top pixel is the pixel position of the line
* that is currently at the top of the widget. On
@@ -868,6 +884,9 @@
*
* @param string the string
*
+ * @exception IllegalArgumentException <ul>
+ * <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></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>
@@ -1147,8 +1166,9 @@
* the echo character to '\0' clears the echo
* character and redraws the original text.
* If for any reason the echo character is invalid,
- * the default echo character for the platform
- * is used.
+ * or if the platform does not allow modification
+ * of the echo character, the default echo character
+ * for the platform is used.
* </p>
*
* @param echo the new echo character
@@ -1184,6 +1204,9 @@
* The double click flag enables or disables the
* default action of the text widget when the user
* double clicks.
+ * </p><p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
* </p>
*
* @param doubleClick the new double click flag
@@ -1225,6 +1248,9 @@
* Sets the orientation of the receiver, which must be one
* of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>.
* <p>
+ * Note: This operation is a hint and is not supported on
+ * platforms that do not have this concept.
+ * </p>
*
* @param orientation new orientation style
*
@@ -1279,7 +1305,10 @@
}
/**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given point, where the x coordinate
+ * represents the start index and the y coordinate
+ * represents the end index.
* <p>
* Indexing is zero based. The range of
* a selection is from 0..N where N is
@@ -1311,7 +1340,8 @@
}
/**
- * Sets the selection.
+ * Sets the selection to the range specified
+ * by the given start and end indices.
* <p>
* Indexing is zero based. The range of
* a selection is from 0..N where N is
@@ -1413,6 +1443,8 @@
* creating a read-only text widget.
* </p><p>
* To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>.
+ * Specifying a limit value larger than <code>Text.LIMIT</code> sets the
+ * receiver's limit to <code>Text.LIMIT</code>.
* </p>
*
* @param limit new text limit
@@ -1424,6 +1456,8 @@
* <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 #LIMIT
*/
public void setTextLimit (int limit) {
checkWidget();
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
index 2c14640..ff66efc 100755
--- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
+++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Widget.java
@@ -96,6 +96,7 @@
*
* @exception IllegalArgumentException <ul>
* <li>ERROR_NULL_ARGUMENT - if the parent is null</li>
+ * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li>
* </ul>
* @exception SWTException <ul>
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li>
@@ -473,7 +474,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
* </ul>
*
- * @see #setData
+ * @see #setData(Object)
*/
public Object getData () {
checkWidget();
@@ -502,7 +503,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #setData
+ * @see #setData(String, Object)
*/
public Object getData (String key) {
checkWidget();
@@ -529,7 +530,6 @@
*
* @exception SWTException <ul>
* <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li>
- * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*/
public Display getDisplay () {
@@ -940,6 +940,8 @@
* <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li>
* <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li>
* </ul>
+ *
+ * @see #getData()
*/
public void setData (Object data) {
checkWidget();
@@ -972,7 +974,7 @@
* <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li>
* </ul>
*
- * @see #getData
+ * @see #getData(String)
*/
public void setData (String key, Object value) {
checkWidget();
