diff options
| author | Carolyn MacLeod | 2005-06-22 23:25:22 +0000 |
|---|---|---|
| committer | Carolyn MacLeod | 2005-06-22 23:25:22 +0000 |
| commit | d3fc5580aecd2c59be0ee57018a597315d747dda (patch) | |
| tree | 33a1adaeeacdca1c0c384e6a637d22b759d4b7ee | |
| parent | 9d15374a15440713922dbd7d2e04fcc36ec25dcc (diff) | |
| download | eclipse.platform.swt-d3fc5580aecd2c59be0ee57018a597315d747dda.tar.gz eclipse.platform.swt-d3fc5580aecd2c59be0ee57018a597315d747dda.tar.xz eclipse.platform.swt-d3fc5580aecd2c59be0ee57018a597315d747dda.zip | |
After initial JavadocBash for 3.1 RC4AFTER_JAVADOC_BASH_FOR_31RC4
176 files changed, 5010 insertions, 1026 deletions
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 5dc18d88b2..5efecd45b7 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 @@ public static Frame new_Frame (final Composite parent) { * @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 5d4d2a86a2..4f0b314f63 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 @@ public class Browser extends Composite { * <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 @@ public void addCloseWindowListener(CloseWindowListener listener) { /** * 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 94b827eb30..90568f66ef 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 @@ public class Browser extends Composite { * <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 @@ public void addCloseWindowListener(CloseWindowListener listener) { /** * 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 8f2e79dee8..c48e3de3e9 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 @@ public class Browser extends Composite { * <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 @@ public void addCloseWindowListener(CloseWindowListener listener) { /** * 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 078418e797..144be0ac7e 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 @@ package org.eclipse.swt.dnd; * <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 @@ package org.eclipse.swt.dnd; * } * </code></pre> * - * <code><pre> + * <pre><code> * public class MyTypeTransfer extends ByteArrayTransfer { * * private static final String MYTYPENAME = "my_type_name"; @@ -113,6 +113,7 @@ package org.eclipse.swt.dnd; * 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 c93c41848e..2e353e0e18 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 @@ public class DropTarget extends Widget { * <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 2c9b92e819..b115961471 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 @@ import org.eclipse.swt.internal.carbon.OS; /** * 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 @@ import org.eclipse.swt.internal.carbon.OS; * <code><pre> * String textData = "Hello World"; * </code></pre> + * + * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { @@ -48,11 +49,12 @@ public static TextTransfer getInstance () { /** * 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 @@ 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){ 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 d4c90694b3..c93d6a573f 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 @@ 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 @@ -92,6 +93,10 @@ abstract protected String[] getTypeNames(); * * @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 @@ abstract protected void javaToNative (Object object, TransferData transferData); * 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 11ba0a7d57..3354598168 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 @@ package org.eclipse.swt.dnd; * <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 @@ package org.eclipse.swt.dnd; * } * </code></pre> * - * <code><pre> + * <pre><code> * public class MyTypeTransfer extends ByteArrayTransfer { * * private static final String MYTYPENAME = "my_type_name"; @@ -113,6 +113,7 @@ package org.eclipse.swt.dnd; * 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 be28cad1b4..2f65e4d76d 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 @@ public class DropTarget extends Widget { * <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 4f3c06d38a..c80269c725 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 @@ package org.eclipse.swt.dnd; /** * 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 @@ package org.eclipse.swt.dnd; * <code><pre> * String textData = "Hello World"; * </code></pre> + * + * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { @@ -47,23 +48,23 @@ public static TextTransfer getInstance () { /** * 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 961deb10ff..16682cfd6b 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 @@ 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 @@ -92,6 +93,10 @@ abstract protected int[] getTypeIds(); * * @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 @@ abstract protected void javaToNative (Object object, TransferData transferData); * 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 a37fb1f26d..c79080cb7f 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 @@ import org.eclipse.swt.internal.gtk.*; * <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 @@ import org.eclipse.swt.internal.gtk.*; * } * </code></pre> * - * <code><pre> + * <pre><code> * public class MyTypeTransfer extends ByteArrayTransfer { * * private static final String MYTYPENAME = "my_type_name"; @@ -114,6 +114,7 @@ import org.eclipse.swt.internal.gtk.*; * 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 9ef36ed3b8..f4ee0e5cc8 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 @@ public class DropTarget extends Widget { * <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 378566ac12..c0e4e435db 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 @@ import org.eclipse.swt.internal.gtk.*; /** * 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 @@ import org.eclipse.swt.internal.gtk.*; * <code><pre> * String textData = "Hello World"; * </code></pre> + * + * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { @@ -48,11 +49,12 @@ public static TextTransfer getInstance () { /** * 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 @@ 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){ 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 8beb3eda69..b0b8afc72d 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 @@ 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 @@ -95,6 +96,10 @@ abstract protected int[] getTypeIds(); * * @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 @@ abstract protected void javaToNative (Object object, TransferData transferData); * 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 aba2149ee8..df11116a23 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 @@ import org.eclipse.swt.internal.motif.*; * <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 @@ import org.eclipse.swt.internal.motif.*; * } * </code></pre> * - * <code><pre> + * <pre><code> * public class MyTypeTransfer extends ByteArrayTransfer { * * private static final String MYTYPENAME = "my_type_name"; @@ -114,6 +114,7 @@ import org.eclipse.swt.internal.motif.*; * 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 784c3d8893..d3eb670422 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 @@ public class DropTarget extends Widget { * <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 c36e8f5ad8..b88d646c91 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 @@ import org.eclipse.swt.internal.motif.XTextProperty; /** * 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 @@ import org.eclipse.swt.internal.motif.XTextProperty; * <code><pre> * String textData = "Hello World"; * </code></pre> + * + * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { @@ -50,11 +51,12 @@ public static TextTransfer getInstance () { /** * 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 @@ 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){ 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 28b4f23b01..0df0b58072 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 @@ 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 @@ -96,6 +97,10 @@ abstract protected int[] getTypeIds(); * * @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 @@ abstract protected void javaToNative (Object object, TransferData transferData); * 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 24a2d0c897..73e22f242c 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 @@ import org.eclipse.swt.internal.photon.*; * <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 @@ import org.eclipse.swt.internal.photon.*; * } * </code></pre> * - * <code><pre> + * <pre><code> * public class MyTypeTransfer extends ByteArrayTransfer { * * private static final String MYTYPENAME = "my_type_name"; @@ -115,6 +115,7 @@ import org.eclipse.swt.internal.photon.*; * 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 e492b9dcee..8c2d3c6eb0 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 @@ public class DropTarget extends Widget { * <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 9e3ff38863..4c52fe38bc 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 @@ import org.eclipse.swt.internal.photon.OS; /** * 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 @@ import org.eclipse.swt.internal.photon.OS; * <code><pre> * String textData = "Hello World"; * </code></pre> + * + * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { @@ -46,11 +47,12 @@ public static TextTransfer getInstance () { /** * 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 @@ 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){ 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 3202f561a3..35a7ebaf4e 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 @@ public abstract class Transfer { 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 @@ abstract protected int[] getTypeIds(); * * @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 @@ abstract protected void javaToNative (Object object, TransferData transferData); * 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 5f4759ec2c..1d5726fa24 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 @@ public Rectangle computeTrim(int x, int y, int width, int height) { * 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 dcd2b91a6c..8a53b2c4f2 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 @@ public Printer(PrinterData data) { * 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 d68eea5d3d..619117701d 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 @@ public ImageData getImageData () { * 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 @@ public boolean equals(Object other) { } /** - * 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 58b0aae438..7d04a21f20 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 @@ static boolean launch(Display display, String fileName) { } /** - * 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 @@ public ImageData getImageData() { * 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 593f994794..e844de734c 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 @@ static boolean launch(Display display, String fileName) { } /** - * 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 @@ public ImageData getImageData() { * 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 7d1bd91310..a0e14f0515 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 @@ public ImageData getImageData () { * 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 @@ public boolean equals(Object other) { } /** - * 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 5299c44c87..90e54b1ff1 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.*; 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 @@ public Path (Device device) { 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 @@ public void addArc(float x, float y, float width, float height, float startAngle 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 @@ public void addPath(Path path) { 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 @@ public void addString(String string, float x, float y, Font font) { 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 @@ public boolean contains(float x, float y, GC gc, boolean outline) { 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 @@ public void cubicTo(float cx1, float cy1, float cx2, float cy2, float x, float y 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 @@ public void getBounds(float[] bounds) { 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 @@ public void getCurrentPoint(float[] point) { 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 @@ public PathData getPathData() { 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 @@ public void lineTo(float x, float y) { 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 @@ public void moveTo(float x, float y) { 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 @@ public void quadTo(float cx, float cy, float x, float y) { 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 @@ public void dispose() { 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 2b818f4be7..8cfe85f307 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.*; 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 @@ public Pattern(Device device, Image image) { 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 @@ public Pattern(Device device, float x1, float y1, float x2, float y2, Color colo 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 @@ public void dispose() { 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 6ff290e3a5..848128a4c8 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.*; 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 @@ static float[] checkTransform(float[] elements) { 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 @@ public void dispose() { 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 @@ public void getElements(float[] elements) { 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 @@ public void invert() { } } +/** + * 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 @@ public boolean isIdentity() { 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 @@ public void multiply(Transform matrix) { 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 @@ public void transform(float[] pointArray) { } } +/** + * 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 dac0cefccf..53519bbeb1 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 @@ public int getRed() { /** * 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 e57c19980f..8cd0a4a0c9 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 @@ public boolean equals (Object object) { /** * 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 1a7384ed3d..ef6a46852c 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 @@ public FontData[] getFontList (String faceName, boolean scalable) { * 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 @@ public Color getSystemColor (int id) { * 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 425e8a408c..c3650fea39 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 @@ public static Font carbon_new(Device device, int handle, short id, short style, /** * 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 65bddd4def..d73858c800 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 @@ public int getStyle() { /** * 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 @@ public void setName(String name) { /** * 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 c66cb01918..ba51ca8d47 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 @@ public int getLeading() { /** * 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 f029fef140..cd0a7f3eeb 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 @@ void copyArea (Image image, int x, int y, int srcImage) { 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 @@ public void drawArc(int x, int y, int width, int height, int startAngle, int arc * <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 @@ public void drawOval(int x, int y, int width, int height) { 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 @@ public void fillArc(int x, int y, int width, int height, int startAngle, int arc * <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 @@ public void fillOval(int x, int y, int width, int height) { 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 @@ public void fillPolygon(int[] pointArray) { * <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 @@ public void fillRectangle(int x, int y, int width, int height) { * <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 @@ public Color getBackground() { 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 @@ public int getAlpha() { } /** - * 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 @@ public void getClipping(Region region) { } } +/** + * 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 @@ public Color getForeground() { 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 @@ public int getLineCap() { } /** - * 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 @@ public int getStyle () { } /** - * 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 @@ public boolean getXORMode() { /** * 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 @@ boolean isIdentity(float[] transform) { && 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 @@ public void setAdvanced(boolean advanced) { } /** - * 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 @@ public void setAlpha(int alpha) { } /** - * 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 @@ public void setBackground(Color color) { 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 @@ public void setClipping(int x, int y, int width, int height) { } /** - * 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 @@ public void setClipping(Path path) { /** * 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 @@ public void setClipping(Rectangle rect) { /** * 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 @@ void setCGClipping () { 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 @@ public void setForeground(Color color) { 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 @@ public void setForegroundPattern(Pattern pattern) { 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 @@ public void setLineCap(int cap) { } /** - * 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 @@ public void setLineStyle(int lineStyle) { * 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 @@ int setString(String string, int flags) { * 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 @@ int regionToRects(int message, int rgn, int r, int newRgn) { } /** - * 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 @@ public void setTextAntialias(int antialias) { 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 e706c613e4..4d3782a9b9 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 @@ import java.io.*; * 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 @@ public Image(Device device, ImageData source, ImageData mask) { * 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 @@ public static Image carbon_new(Device device, int type, int handle, int data) { /** * 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 093455c5ff..4cd7e7614d 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.*; 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 @@ public Path (Device device) { 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 @@ public void addArc(float x, float y, float width, float height, float startAngle 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 @@ public void addPath(Path path) { 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 @@ int curveProc(int pt1, int controlPt, int pt2, int data) { 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 @@ int applierFunc(int info, int elementPtr) { 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 @@ public boolean contains(float x, float y, GC gc, boolean outline) { 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 @@ public void dispose() { 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 @@ public void getBounds(float[] bounds) { 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 @@ public void getCurrentPoint(float[] point) { 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 @@ public PathData getPathData() { 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 7f4a4ed923..72e1bb9860 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.*; 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 @@ public class Pattern extends Resource { 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 @@ public Pattern(Device device, Image image) { 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 @@ int createPattern(int context) { 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 @@ int drawPatternProc (int ref, int context) { 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 e7ef188d04..a4383d9b0c 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 @@ public void add(Rectangle rect) { * @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 @@ public static Region carbon_new(Device device, int handle) { /** * 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 @@ public void intersect(Region region) { * <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 @@ public boolean intersects (int x, int y, int width, int height) { * <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 @@ public void subtract(Rectangle rect) { * @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 f47c2bcee5..93a247fc8d 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.Compatibility; 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 @@ static float[] checkTransform(float[] elements) { 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 @@ public void dispose() { 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 @@ public void getElements(float[] elements) { 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 @@ public void invert() { 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 @@ public void multiply(Transform matrix) { 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 @@ public void transform(float[] pointArray) { } } +/** + * 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 40b54ccaa2..5a7dc00558 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 @@ void setDefault (boolean value) { /** * 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 27f4b8c3a6..72f67cf14f 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 @@ Canvas () { * </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 c672b5782c..1ec451b6e8 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 @@ public int getItemHeight () { } /** - * 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 @@ public int getOrientation () { } /** - * 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 @@ public int getSelectionIndex () { /** * 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 @@ public int getTextHeight () { * <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 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize /** * 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 @@ void setText (String string, boolean notify) { /** * 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 @@ void setText (String string, boolean notify) { * <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 d93c0f6106..22f767e5e8 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 @@ import org.eclipse.swt.graphics.*; * 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 @@ void fixTabList (Control control) { } /** - * 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 @@ public boolean getLayoutDeferred () { } /** - * 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 9be57b169d..f115880714 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 @@ void checkBuffered () { * @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 @@ public Point computeSize (int wHint, int hHint) { * @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 @@ public void moveBelow (Control control) { * <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 @@ public void pack () { * <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 @@ public void setMenu (Menu menu) { * @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 @@ public boolean setParent (Composite parent) { * <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 @@ boolean traverseMnemonic (Event event) { * <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 63ee644edc..09027e9465 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 @@ public Image getImage () { * 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 @@ void saveFocus () { * <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 @@ public void setImage (Image image) { * 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 @@ public void setImages (Image [] images) { * 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 @@ public void setMenuBar (Menu menu) { * 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 @@ void setSavedFocus (Control control) { /** * 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 8ba03e078b..b46930bae7 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 @@ public DirectoryDialog (Shell parent, int style) { * the directories it shows. * * @return the filter path + * + * @see #setFilterPath */ public String getFilterPath () { return filterPath; @@ -192,9 +194,15 @@ public void setMessage (String string) { } /** - * 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 312ade58a7..09c8a42ba8 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 @@ void addWidget (int handle, Widget widget) { * 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 @@ int createOverlayWindow () { * </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 @@ public Display () { 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 @@ synchronized static void deregister (Display display) { * <p> * This method is called after <code>release</code>. * </p> - * @see #dispose + * @see Device#dispose * @see #release */ protected void destroy () { @@ -903,7 +915,8 @@ void destroyDisplay () { /** * 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 @@ public Widget findWidget (int handle, int id) { /** * 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 @@ public static synchronized Display getDefault () { * 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 @@ public Object getData (String key) { * 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 @@ public boolean getHighContrast () { } /** - * 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 @@ public boolean getHighContrast () { * <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 @@ public Monitor getPrimaryMonitor () { } /** - * 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 @@ static synchronized void register (Display display) { * </p> * This method is called before <code>destroy</code>. * - * @see #dispose + * @see Device#dispose * @see #destroy */ protected void release () { @@ -3200,9 +3216,10 @@ void sendEvent (int eventType, Event event) { /** * 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 @@ public boolean sleep () { * 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 @@ int textInputProc (int nextHandler, int theEvent, int userData) { * 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 @@ void updateQuitMenu () { } /** - * 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 19486b34f5..7ef3bcdbe4 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 @@ import org.eclipse.swt.internal.carbon.*; * <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 @@ public FileDialog (Shell parent, int style) { /** * 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 @@ public String getFileName () { } /** - * 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 @@ public String [] getFilterExtensions () { } /** - * 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 @@ public void setFileName (String string) { * 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 @@ public void setFilterExtensions (String [] 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; @@ -322,7 +330,14 @@ public void setFilterNames (String [] names) { * 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 b5bbb2f13d..f1ca24ee77 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 @@ import org.eclipse.swt.graphics.*; * <p> * <dl> * <dt><b>Styles:</b></dt> + * <dd>(none)</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -665,7 +666,7 @@ void setFontStyle (Font font) { * 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 e20bd08921..271d9fd2bc 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 @@ import org.eclipse.swt.graphics.*; /** * 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 @@ public int getItemCount () { /** * 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 @@ public int getItemHeight () { } /** - * 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 @@ public String [] getItems () { /** * 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 @@ public int getSelectionCount () { * 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 @@ public int getSelectionIndex () { /** * 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 @@ public void setItems (String [] items) { /** * 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 60bf8a0d1e..7616426e58 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 @@ public MenuItem getDefaultItem () { /** * 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 @@ public int getItemCount () { } /** - * 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 @@ public int indexOf (MenuItem item) { /** * 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 @@ public void setDefaultItem (MenuItem item) { /** * 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 @@ public void setEnabled (boolean enabled) { } /** - * 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 @@ public void setLocation (int x, int y) { } /** - * 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 924a5f287e..2d281349fc 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 @@ public void addHelpListener (HelpListener listener) { /** * 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 @@ void destroyEmptyMenu (int index) { } /** - * 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 @@ public int getAccelerator () { /** * 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 @@ int kEventProcessCommand (int nextHandler, int theEvent, int userData) { /** * 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 @@ void selectRadio () { * 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 @@ public void setAccelerator (int accelerator) { /** * 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 @@ public void setEnabled (boolean enabled) { /** * 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 79f6c5f453..82e859a027 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 @@ int createCFString (String id) { } /** - * 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 d3dd8b3fbc..1448c98500 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 @@ public int getMinimum () { } /** - * 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 @@ public void setMinimum (int 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/carbon/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java index 2b0be7a89d..03b412d705 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java @@ -204,7 +204,7 @@ public int getPageIncrement () { } /** - * Returns the <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 @@ public void setPageIncrement (int value) { } /** - * 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 f1e5bcf58b..336499e395 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 @@ import org.eclipse.swt.graphics.*; * 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 @@ ScrollBar (Scrollable parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: + * <code>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 @@ public int getPageIncrement () { } /** - * 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 @@ public Scrollable getParent () { } /** - * 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 8a3edd469b..7afa7738d5 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 @@ import org.eclipse.swt.graphics.*; * 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 @@ Shell (Display display, Shell parent, int style, int handle) { * @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 @@ public Shell (Shell parent) { * @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 @@ public Shell (Shell parent) { * @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 @@ public void setMinimized (boolean minimized) { } /** - * 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 @@ public void setMinimumSize (int width, int height) { } /** - * 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 30825a433e..96af397359 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 @@ import org.eclipse.swt.graphics.*; * 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 @@ public Slider (Composite parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. + * <code>SWT.NONE</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. @@ -279,7 +279,7 @@ public int getPageIncrement () { } /** - * 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 @@ public void setPageIncrement (int value) { } /** - * 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 45c9ab5678..ac7393a594 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 @@ import org.eclipse.swt.graphics.*; * <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 @@ public class Spinner extends Composite { * </ul> * * @see SWT#READ_ONLY + * @see SWT#WRAP * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -363,6 +364,16 @@ int focusHandle () { 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 @@ void setBackground (float [] color) { 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 b91938872c..d4978646a5 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 @@ public class Table extends Composite { * @see SWT#CHECK * @see SWT#FULL_SELECTION * @see SWT#HIDE_SELECTION + * @see SWT#VIRTUAL * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -1236,8 +1237,8 @@ public int getItemHeight () { } /** - * 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 @@ public boolean getLinesVisible () { /** * 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 @@ public int getSelectionIndex () { /** * 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 @@ boolean setScrollWidth (TableItem [] items, boolean set) { /** * 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 @@ public void setTopIndex (int index) { * @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 2901f4df03..577c533355 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 @@ void clear () { * </ul> * * @since 2.0 - * */ public Color getBackground () { checkWidget (); @@ -298,7 +297,6 @@ public Font getFont (int index) { * </ul> * * @since 2.0 - * */ public Color getForeground () { checkWidget (); @@ -379,7 +377,8 @@ public Image getImage (int index) { /** * 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 @@ void releaseWidget () { * </ul> * * @since 2.0 - * */ public void setBackground (Color color) { checkWidget (); @@ -576,7 +574,6 @@ public void setBackground (Color color) { * </ul> * * @since 3.0 - * */ public void setBackground (int index, Color color) { checkWidget (); @@ -692,7 +689,6 @@ public void setFont (int index, Font font) { * </ul> * * @since 2.0 - * */ public void setForeground (Color color) { checkWidget (); @@ -722,7 +718,6 @@ public void setForeground (Color color) { * </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 3574bee462..54b8e66cd4 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 @@ public class Text extends Scrollable { /** * 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 @@ void drawWidget (int control, int damageRgn, int visibleRgn, int theEvent) { } /** - * 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 @@ public int getCaretLineNumber () { } /** - * 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 @@ public Point getCaretLocation () { } /** - * 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 @@ public int getCaretPosition () { } /** - * Gets the number of characters. + * Returns the number of characters. * * @return number of characters in the widget * @@ -534,7 +539,7 @@ String getClipboardText () { } /** - * 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 @@ public boolean getDoubleClickEnabled () { } /** - * 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 @@ public boolean getDoubleClickEnabled () { * <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 @@ public char getEchoChar () { } /** - * Gets the editable state. + * Returns the editable state. * * @return whether or not the reciever is editable * @@ -590,7 +597,7 @@ public boolean getEditable () { } /** - * Gets the number of lines. + * Returns the number of lines. * * @return the number of lines in the widget * @@ -607,7 +614,7 @@ public int getLineCount () { } /** - * Gets the line delimiter. + * Returns the line delimiter. * * @return a string that is the line delimiter * @@ -615,6 +622,8 @@ public int getLineCount () { * <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 @@ public String getLineDelimiter () { } /** - * Gets the height of a line. + * Returns the height of a line. * * @return the height of a row of text * @@ -639,7 +648,8 @@ public int getLineHeight () { } /** - * 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 @@ public int getOrientation () { } /** - * 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 @@ public Point getSelection () { } /** - * Gets the number of selected characters. + * Returns the number of selected characters. * * @return the number of selected characters. * @@ -695,7 +708,7 @@ public int getSelectionCount () { } /** - * 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 @@ public String getSelectionText () { } /** - * 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 @@ public int getTabs () { } /** - * 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 @@ public String getText () { } /** - * 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 @@ public String getText (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #LIMIT */ public int getTextLimit () { checkWidget(); @@ -815,7 +831,7 @@ public int getTopIndex () { } /** - * 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 @@ Rect inset () { * * @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 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize * 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 @@ public void setDoubleClickEnabled (boolean doubleClick) { * 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 @@ void setFontStyle (Font font) { * 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 @@ public void setSelection (int start) { } /** - * 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 @@ public void setSelection (int start, int end) { } /** - * 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 @@ void setTXNText (int iStartOffset, int iEndOffset, String string) { * 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 @@ void setTXNText (int iStartOffset, int iEndOffset, String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @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 e998fc1065..d31b639df3 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 @@ import org.eclipse.swt.graphics.*; /** * 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 @@ public boolean getHeaderVisible () { 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 @@ public int getItemHeight () { } /** - * 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 @@ public TreeItem getParentItem () { /** * 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 @@ void hookEvents () { 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 @@ public int indexOf (TreeColumn column) { 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 c9d3b0d40c..5031e7c22b 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 @@ public class TreeItem extends Item { * 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 @@ public TreeItem (Tree parent, int style) { * 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 @@ public TreeItem (Tree parent, int style, int index) { * 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 @@ public TreeItem (TreeItem parentItem, int style) { * 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 @@ public Rectangle getImageBounds (int index) { 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 @@ public int getItemCount () { } /** - * 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 @@ public String getText (int index) { 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 @@ void releaseWidget () { 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 4d91a6f251..669d93a375 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 @@ Widget () { * * @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 @@ Rect getControlSize (int control) { * <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 @@ public Object getData () { * <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 @@ public Object getData (String key) { * * @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 @@ int setBounds (int control, int x, int y, int width, int height, boolean move, b * <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 @@ public void setData (Object data) { * <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 bec30ed35a..b4b17c7c6b 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 @@ void calculateChevronTrim () { * @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 0613f50490..d8fdff2792 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 @@ package org.eclipse.swt.graphics; 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 @@ public Path (Device device) { 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 @@ public boolean contains(float x, float y, GC gc, boolean outline) { 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 @@ public void curveTo(float cx1, float cy1, float cx2, float cy2, float x, float y 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 @@ public void dispose() { 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 48967f3677..c0a8d2cfd2 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 @@ package org.eclipse.swt.graphics; 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 @@ public Pattern(Device device, Image image) { 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 @@ public Pattern(Device device, float x1, float y1, float x2, float y2, Color colo 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 @@ public void dispose() { 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 bc158687ca..4d75e26c7f 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 @@ package org.eclipse.swt.graphics; 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 @@ static float[] checkTransform(float[] elements) { 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 @@ public void dispose() { 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 @@ public boolean isIdentity() { 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 fe0616cec1..a55c4a9ac6 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 @@ public boolean isFocusControl() { * @see SWT#CHECK * @see SWT#FULL_SELECTION * @see SWT#HIDE_SELECTION + * @see SWT#VIRTUAL * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -933,8 +934,8 @@ public int getItemHeight () { 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 @@ TableColumn[] getOrderedColumns () { } /** * 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 @@ int getSelectionIndex (TableItem item) { } /** * 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 @@ public void setSelection (TableItem[] items) { } /** * 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 @@ public void setTopIndex (int index) { * @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 ea935ed26d..4465ca10e4 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 @@ public Image getImage (int columnIndex) { /** * 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 1bbae9277e..b7883b4d5e 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 @@ import org.eclipse.swt.internal.*; /** * Instances of this class provide a selectable user interface object - * that displays a hierarchy of items and issue notificiation when an + * 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 @@ public TreeItem getItem (Point point) { * @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 @@ public int getItemHeight () { 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 @@ public TreeItem getParentItem () { } /** * 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 @@ void headerPaintVShadows (GC gc, int x, int y, int width, int height) { 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 e1d6e4cbf6..0cf96c94cb 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 @@ public class TreeItem extends Item { * 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 @@ public TreeItem (Tree parent, int style) { * 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 @@ public TreeItem (Tree parent, int style, int index) { * 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 @@ public TreeItem (TreeItem parentItem, int style) { * 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 @@ int getIndex () { 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 @@ public int getItemCount () { 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 @@ boolean hasAncestor (TreeItem item) { 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 @@ void removeColumn (TreeColumn column, int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @since 3.1 */ public 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 06b52e7852..15f71c6bb0 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 @@ public int getRed() { /** * 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 a7f20b00ed..8c74fd0d44 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 @@ public static Cursor gtk_new(Device device, int /*long*/ handle) { /** * 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 2cd7ac82f5..ca2baf871d 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 @@ public FontData[] getFontList (String faceName, boolean scalable) { * 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 @@ public Color getSystemColor (int id) { * 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 0137471f4a..9b1d8b54df 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 @@ public static Font gtk_new(Device device, int /*long*/ handle) { /** * 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 76b22c812a..68798e380a 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 @@ public int getStyle() { /** * 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 @@ public void setName(String name) { /** * 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 96b962c8da..8abe3cf1c9 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 @@ public static FontMetrics gtk_new(int ascent, int descent, int averageCharWidth, /** * 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 e44ada99a8..8c10ea70c7 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(Image image, int x, int y) { 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 @@ public void drawArc(int x, int y, int width, int height, int startAngle, int arc * <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 @@ public void drawOval(int x, int y, int width, int height) { OS.gdk_draw_arc(data.drawable, handle, 0, x, y, width, height, 0, 23040); } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * 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 @@ public void fillArc(int x, int y, int width, int height, int startAngle, int arc * <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 @@ public void fillOval(int x, int y, int width, int height) { OS.gdk_gc_set_foreground(handle, color); } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * 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 @@ public void fillPolygon(int[] pointArray) { * <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 @@ public void fillRectangle(int x, int y, int width, int height) { * <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 @@ public int getAdvanceWidth(char ch) { 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 @@ public int getAlpha() { } /** - * 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 @@ public Color getBackground() { 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 @@ public void getClipping(Region region) { } } +/** + * 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 @@ public Color getForeground() { 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 @@ public int getLineCap() { } /** - * 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 @@ public int getStyle () { } /** - * 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 @@ public boolean getXORMode() { /** * 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 @@ boolean isIdentity(int /*long*/ matrix) { 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 @@ public void setAdvanced(boolean advanced) { } /** - * 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 @@ public void setAlpha(int alpha) { } /** - * 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 @@ public void setBackground(Color color) { 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 @@ public void setClipping(int x, int y, int width, int height) { } /** - * 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 @@ public void setClipping(Path path) { /** * 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 @@ public void setClipping(Rectangle rect) { /** * 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 @@ public void setFont(Font font) { } } +/** + * 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 @@ public void setForeground(Color color) { 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 @@ public void setForegroundPattern(Pattern pattern) { 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 @@ public void setLineCap(int cap) { } /** - * 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 @@ public void setLineStyle(int lineStyle) { * 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 @@ void setString(String string, int 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); @@ -2855,8 +3187,23 @@ public void setTextAntialias(int antialias) { 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 @@ public void setTransform(Transform transform) { * 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 5d7d965818..775ba8b1e1 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 @@ import java.io.*; * 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 @@ public Image(Device device, ImageData source, ImageData mask) { * 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 @@ public static Image gtk_new(Device device, int type, int /*long*/ pixmap, int /* /** * 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 26006135b8..935ee2098d 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 @@ public void add(Rectangle rect) { * @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 @@ public static Region gtk_new(Device device, int /*long*/ handle) { /** * 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 @@ public void intersect(Region region) { * <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 @@ public boolean intersects (int x, int y, int width, int height) { * <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 @@ public void subtract(Rectangle rect) { * @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 ab8460f110..cd10658ef7 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 @@ void setForegroundColor (GdkColor color) { /** * 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 b6971efa03..b15398c1f8 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 @@ Canvas () {} * </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 377047cfc9..144a51c470 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 @@ public int getItemHeight () { } /** - * 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 @@ public int getOrientation () { } /** - * 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 @@ public int getSelectionIndex () { /** * 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 @@ public int getTextHeight () { * <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 @@ void setForegroundColor (GdkColor color) { /** * 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 @@ public void setText (String string) { /** * 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 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @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 c2b15199b4..5a13446cbc 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 @@ import org.eclipse.swt.graphics.*; * 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 @@ boolean forceFocus (int /*long*/ focusHandle) { } /** - * 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 @@ public boolean getLayoutDeferred () { } /** - * 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 68a7352af0..490a58a819 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 @@ int /*long*/ paintWindow () { * @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 @@ void createWidget (int index) { * @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 @@ public void moveBelow (Control control) { * <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 @@ public void pack () { * <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 @@ void setOrientation () { * @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 @@ boolean setRadioSelection (boolean value) { * <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 @@ boolean traverseMnemonic (char key) { * <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 49140c1c4b..735212c207 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 @@ public Image getImage () { * 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 @@ boolean restoreFocus () { * <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 @@ public void setImage (Image image) { * 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 @@ public void setImages (Image [] images) { * 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 @@ public void setMenuBar (Menu menu) { * 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 @@ void setSavedFocus (Control control) { /** * 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 3a2854758b..f2ba3bc167 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 @@ public DirectoryDialog (Shell parent, int style) { * the directories it shows. * * @return the filter path + * + * @see #setFilterPath */ public String getFilterPath () { return filterPath; @@ -258,9 +260,15 @@ String openClassicDialog () { 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 7b0f169d06..8c04cde11a 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 @@ static void setDevice (Device device) { * </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 @@ public Display () { 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 @@ void addWidget (int /*long*/ handle, Widget widget) { * 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 @@ synchronized void deregister () { * <p> * This method is called after <code>release</code>. * </p> - * @see #dispose + * @see Device#dispose * @see #release */ protected void destroy () { @@ -926,7 +938,9 @@ void destroyDisplay () { /** * 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 @@ public static synchronized Display findDisplay (Thread thread) { /** * 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 @@ public Point [] getCursorSizes () { * 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 @@ public Object getData (String key) { * 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 @@ public int getDepth () { } /** - * 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 @@ public int getDepth () { * <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 @@ public Monitor getPrimaryMonitor () { } /** - * 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 @@ synchronized void register () { * </p> * This method is called before <code>destroy</code>. * - * @see #dispose + * @see Device#dispose * @see #destroy */ protected void release () { @@ -2884,9 +2900,10 @@ boolean runPopups () { /** * 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 @@ public boolean sleep () { * 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 @@ int /*long*/ shellMapProc (int /*long*/ handle, int /*long*/ arg0, int /*long*/ * 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 @@ public void update () { } /** - * 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 18c725656c..95404d5a44 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 @@ import org.eclipse.swt.internal.gtk.*; * <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 @@ String computeResultClassicDialog () { } /** * 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 @@ public String getFileName () { 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 @@ public String [] getFilterExtensions () { 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 @@ public void setFileName (String string) { * 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 @@ public void setFilterExtensions (String [] extensions) { 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 @@ public void setFilterNames (String [] names) { * 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 6c53c6bfbd..1f07d8bf5f 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 @@ import org.eclipse.swt.accessibility.*; * <p> * <dl> * <dt><b>Styles:</b></dt> + * <dd>(none)</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -652,7 +653,7 @@ void setFontDescription (int /*long*/ font) { * 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 910f9625e5..486567d45c 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 @@ import org.eclipse.swt.events.*; /** * 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 @@ public int getItemCount () { /** * 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 @@ public int getItemHeight () { } /** - * 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 @@ public String [] getItems () { /** * 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 @@ public int getSelectionCount () { * 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 @@ public int getSelectionIndex () { /** * 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 @@ public void setItems (String [] items) { /** * 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 6d897bf8ab..626c4631d5 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 @@ public MenuItem getDefaultItem () { /** * 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 @@ public int getItemCount () { } /** - * 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 @@ public int indexOf (MenuItem item) { /** * 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 @@ public void setDefaultItem (MenuItem item) { /** * 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 @@ public void setEnabled (boolean enabled) { } /** - * 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 @@ public void setLocation (int x, int y) { } /** - * 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 dd0de648d3..356e3149c4 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 @@ public void addHelpListener (HelpListener listener) { /** * 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 @@ void fixMenus (Decorations newParent) { } /** - * 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 @@ int /*long*/ getAccelGroup () { /** * 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 @@ void hookEvents () { /** * 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 @@ void selectRadio () { * 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 @@ public void setAccelerator (int accelerator) { /** * 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 @@ public void setEnabled (boolean enabled) { /** * 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 f0396de6c2..90c4f5660b 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 @@ public MessageBox (Shell parent, int 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/gtk/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java index 47f00b6def..0a460894c4 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 @@ public int getMinimum () { } /** - * 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 @@ public void setMinimum (int 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/gtk/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java index c26b47ef8f..aa678750b2 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 @@ public int getPageIncrement () { } /** - * 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 @@ public void setPageIncrement (int value) { } /** - * 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 65ca2a529c..7c31f5b3e9 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 @@ import org.eclipse.swt.events.*; * 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 @@ ScrollBar (Scrollable parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: + * <code>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 @@ public int getPageIncrement () { } /** - * 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 @@ public Scrollable getParent () { } /** - * 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 b97a5397a2..d47f1d9aea 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 @@ import org.eclipse.swt.events.*; * 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 @@ Shell (Display display, Shell parent, int style, int /*long*/ handle) { * @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 @@ public Shell (Shell parent) { * @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 @@ public Shell (Shell parent) { * @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 @@ public void setMinimized (boolean minimized) { } /** - * 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 @@ public void setMinimumSize (int width, int height) { } /** - * 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 83632cda91..4c4dd9a13c 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 @@ import org.eclipse.swt.events.*; * 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 @@ public Slider (Composite parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. + * <code>SWT.NONE</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. @@ -272,7 +272,7 @@ public int getPageIncrement () { } /** - * 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 @@ public void setPageIncrement (int value) { } /** - * 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 fe5e347096..9405d91de7 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 @@ import org.eclipse.swt.events.*; * <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 @@ public class Spinner extends Composite { * </ul> * * @see SWT#READ_ONLY + * @see SWT#WRAP * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -446,6 +447,16 @@ public int getSelection () { 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 @@ public void setSelection (int value) { 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 62aedc5679..426d79283d 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 @@ public class Table extends Composite { * @see SWT#CHECK * @see SWT#FULL_SELECTION * @see SWT#HIDE_SELECTION + * @see SWT#VIRTUAL * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -1200,8 +1201,8 @@ public int getItemHeight () { } /** - * 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 @@ int /*long*/ getPixbufRenderer (int /*long*/ column) { /** * 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 @@ public int getSelectionIndex () { /** * 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 @@ void setScrollWidth (int /*long*/ column, int /*long*/ iter) { /** * 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 @@ public void setTopIndex (int index) { * @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 b3b3e9f189..bcadc137be 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 @@ void clear () { * </ul> * * @since 2.0 - * */ public Color getBackground () { checkWidget (); @@ -346,7 +345,6 @@ public Font getFont (int index) { * </ul> * * @since 2.0 - * */ public Color getForeground () { checkWidget (); @@ -442,7 +440,8 @@ public Image getImage (int index) { /** * 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 @@ void releaseWidget () { * </ul> * * @since 2.0 - * */ public void setBackground (Color color) { checkWidget (); @@ -642,7 +640,6 @@ public void setBackground (Color color) { * </ul> * * @since 3.0 - * */ public void setBackground (int index, Color color) { checkWidget (); @@ -816,7 +813,6 @@ public void setFont (int index, Font font) { * </ul> * * @since 2.0 - * */ public void setForeground (Color color){ checkWidget (); @@ -845,7 +841,6 @@ public void setForeground (Color color){ * </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 7bc11bd191..603d48652f 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 @@ public class Text extends Scrollable { /** * 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 @@ public int getBorderWidth () { } /** - * 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 @@ public int getCaretLineNumber () { } /** - * 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 @@ public Point getCaretLocation () { } /** - * 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 @@ public int getCaretPosition () { } /** - * Gets the number of characters. + * Returns the number of characters. * * @return number of characters in the widget * @@ -549,7 +554,7 @@ public int getCharCount () { } /** - * 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 @@ public boolean getDoubleClickEnabled () { } /** - * 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 @@ public boolean getDoubleClickEnabled () { * <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 @@ public char getEchoChar () { } /** - * Gets the editable state. + * Returns the editable state. * * @return whether or not the reciever is editable * @@ -616,7 +623,7 @@ GdkColor getForegroundColor () { } /** - * Gets the number of lines. + * Returns the number of lines. * * @return the number of lines in the widget * @@ -632,7 +639,7 @@ public int getLineCount () { } /** - * Gets the line delimiter. + * Returns the line delimiter. * * @return a string that is the line delimiter * @@ -640,6 +647,8 @@ public int getLineCount () { * <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 @@ public String getLineDelimiter () { } /** - * Gets the height of a line. + * Returns the height of a line. * * @return the height of a row of text * @@ -662,7 +671,8 @@ public int getLineHeight () { } /** - * 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 @@ public int getOrientation () { } /** - * 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 @@ public Point getSelection () { } /** - * Gets the number of selected characters. + * Returns the number of selected characters. * * @return the number of selected characters. * @@ -724,7 +737,7 @@ public int getSelectionCount () { } /** - * 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 @@ public String getSelectionText () { } /** - * 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 @@ int getTabWidth (int tabs) { } /** - * 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 @@ public String getText () { } /** - * 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 @@ public String getText (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #LIMIT */ public int getTextLimit () { checkWidget (); @@ -889,7 +905,7 @@ public int getTopIndex () { } /** - * 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 @@ int /*long*/ imContext () { * * @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 @@ void setCursor (int /*long*/ cursor) { * 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 @@ public void setDoubleClickEnabled (boolean doubleClick) { * 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 @@ void setForegroundColor (GdkColor color) { * 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 @@ public void setSelection (int start) { } /** - * 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 @@ public void setSelection (int start, int end) { } /** - * 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 @@ public void setText (String string) { * 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 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @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 1810f6844d..f3b4d6773b 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 @@ import org.eclipse.swt.events.*; /** * 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 @@ public boolean getHeaderVisible () { 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 @@ public int getItemHeight () { } /** - * 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 @@ int /*long*/ getPixbufRenderer (int /*long*/ column) { /** * 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 @@ void hookEvents () { * <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 @@ public int indexOf (TreeColumn column) { 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 098e95d2be..a871b72714 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 @@ public class TreeItem extends Item { * 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 @@ public TreeItem (Tree parent, int style) { * 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 @@ public TreeItem (Tree parent, int style, int index) { * 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 @@ public TreeItem (TreeItem parentItem, int style) { * 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 @@ public int getItemCount () { 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 @@ public TreeItem getItem (int index) { } /** - * 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 @@ public String getText (int index) { 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 @@ void releaseWidget () { 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 8a43d58c24..b46bdb8d2f 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 @@ Widget () {} * * @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 @@ void error (int code) { * <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 @@ public Object getData () { * <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 @@ public Object getData (String key) { * * @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 @@ char [] sendIMKeyEvent (int type, GdkEventKey keyEvent, char [] chars) { * <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 @@ public void setData (Object data) { * <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 28b3692ef6..f2257bb25b 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 @@ public RGB getRGB () { } /** * 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 45e20e6cc8..d09c0331c4 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 @@ public boolean equals (Object object) { } /** * 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 54377b2805..01c43ca4f5 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 @@ public FontData [] getFontList (String faceName, boolean scalable) { * 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 @@ public Color getSystemColor (int id) { * 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 2a74951809..cda4864304 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 @@ public FontData[] getFontData() { /** * 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 3bc432ba6e..e74f01f406 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 @@ String getXlfd() { } /** * 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 @@ public void setLocale(String locale) { /** * 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 6216b6ee86..16fab79a4f 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 @@ public int getLeading() { } /** * 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 3fe2e1fc57..4845ab82d9 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 @@ static int checkStyle (int style) { 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 @@ public void drawArc(int x, int y, int width, int height, int startAngle, int arc * <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 @@ public void drawOval(int x, int y, int width, int height) { } 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 @@ public void fillArc(int x, int y, int width, int height, int startAngle, int arc * <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 @@ public void fillOval (int x, int y, int width, int height) { 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 @@ public void fillPolygon(int[] pointArray) { * <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 @@ public void fillRectangle (int x, int y, int width, int height) { * <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 @@ public int getAdvanceWidth(char ch) { 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 @@ public int getAlpha() { 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 @@ public Color getBackground() { 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 @@ public void getClipping(Region region) { 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 @@ public Color getForeground() { 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 @@ public int getLineCap() { 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 @@ public int getStyle () { 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 @@ public boolean getXORMode() { } /** * 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 @@ boolean isIdentity(int /*long*/ matrix) { 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 @@ public void setAdvanced(boolean advanced) { } } /** - * 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 @@ public void setAlpha(int alpha) { 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 @@ public void setBackground (Color color) { 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 @@ public void setClipping (int x, int y, int width, int height) { 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 @@ public void setClipping(Path path) { /** * 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 @@ public void setClipping (Rectangle rect) { /** * 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 @@ public void setClipping (Region region) { 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 @@ public void setForeground (Color color) { } 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 @@ public void setForegroundPattern(Pattern pattern) { } 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 @@ public void setLineCap(int cap) { } } /** - * 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 @@ public void setLineStyle(int lineStyle) { * 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 @@ void setText(String string, int flags) { 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 @@ public void setTextAntialias(int antialias) { } 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 @@ public void setTransform(Transform transform) { * 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 75d8323a38..6ea0bbd957 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 @@ import java.io.*; * 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 @@ public Image(Device device, ImageData source, ImageData mask) { * 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 @@ static boolean getOffsetForMask(int bitspp, int mask, int byteOrder, int[] poff) } /** * 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 adfc1b1a34..7e5bbb75a4 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 @@ public void add (Rectangle rect) { * @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 @@ public Rectangle getBounds() { } /** * 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 @@ public void intersect (Region region) { * <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 @@ public boolean intersects (int x, int y, int width, int height) { * <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 @@ public void subtract (Rectangle rect) { * @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 212587577f..7250019397 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 @@ public void setFont (Font font) { } /** * 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 510e345576..7214d58252 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 @@ Canvas () { * </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 03b09c64e5..80a4c2dce1 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 @@ public int getItemHeight () { 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 @@ public int getOrientation () { 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 @@ public int getSelectionIndex () { } /** * 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 @@ public int getTextHeight () { * <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 @@ void setForegroundPixel (int pixel) { /** * 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 @@ public void setText (String string) { /** * 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 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @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 eaaf7b2114..9fbc7983e8 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 @@ import org.eclipse.swt.graphics.*; * 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 @@ boolean fowardKeyEvent (int event) { 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 @@ public boolean getLayoutDeferred () { 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 f6ea7d7473..8bac8c20a5 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 @@ void checkBuffered () { * @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 @@ public Point computeSize (int wHint, int hHint) { * @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 @@ void overrideTranslations () { * <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 @@ public void pack () { * <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 @@ public void setMenu (Menu menu) { * @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 @@ boolean setRadioSelection (boolean value) { * <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 @@ boolean traverseReturn () { * <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 3d480b27cf..9fce63c9c1 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 @@ public Image getImage () { * 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 @@ void remove (Menu menu) { * <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 @@ public void setImage (Image image) { * 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 @@ public void setImages (Image [] images) { * 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 @@ public void setMenuBar (Menu menu) { * 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 @@ void setSavedFocus (Control control) { /** * 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 9f0c2129c7..2bfe7ad1d7 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 @@ int activate (int widget, int client, int call) { * the directories it shows. * * @return the filter path + * + * @see #setFilterPath */ public String getFilterPath () { return filterPath; @@ -287,9 +289,15 @@ public String open () { 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 33bde7177c..ae5264d8cf 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 @@ static void setDevice (Device device) { * </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 @@ static void setDevice (Device device) { 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 @@ void addPopup (Menu menu) { * 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 @@ synchronized static void deregister (Display display) { * <p> * This method is called after <code>release</code>. * </p> - * @see #dispose + * @see Device#dispose * @see #release */ protected void destroy () { @@ -845,7 +857,8 @@ void destroyDisplay () { /** * 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 @@ public static synchronized Display getCurrent () { /** * 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 @@ public static synchronized Display getDefault () { * 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 @@ public Object getData (String key) { * 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 @@ public boolean getHighContrast () { 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 @@ public boolean getHighContrast () { * <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 @@ public Monitor getPrimaryMonitor () { 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 @@ static synchronized void register (Display display) { * </p> * This method is called before <code>destroy</code>. * - * @see #dispose + * @see Device#dispose * @see #destroy */ protected void release () { @@ -3154,9 +3170,10 @@ public void setCursorLocation (Point point) { /** * 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 @@ public boolean sleep () { * 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 @@ int textWidth (String string, Font font) { * 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 @@ public void update () { 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 db44185874..c06d1fff74 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 @@ import org.eclipse.swt.*; * <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 @@ int cancelPressed (int widget, int client, int call) { } /** * 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 @@ public String getFileName () { } /** - * 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 @@ public String [] getFilterExtensions () { } /** - * 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 @@ public void setFileName (String string) { * 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 @@ public void setFilterExtensions (String [] 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; @@ -513,7 +521,14 @@ public void setFilterNames (String [] names) { * 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 44bd6d0dbd..72f367be2e 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 @@ import org.eclipse.swt.events.*; * <p> * <dl> * <dt><b>Styles:</b></dt> + * <dd>(none)</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -425,7 +426,7 @@ void setForegroundPixel (int pixel) { * 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 312ec35ab1..db5327224d 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 @@ import org.eclipse.swt.events.*; /** * 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 @@ public int getItemCount () { } /** * 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 @@ public int getItemHeight () { 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 @@ public String [] getItems () { } /** * 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 @@ public int getSelectionCount () { * 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 @@ public int getSelectionIndex () { } /** * 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 @@ public void setItems (String [] items) { /** * 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 a9be6ee6d6..31c4005a4f 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 @@ public MenuItem getDefaultItem () { } /** * 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 @@ public int getItemCount () { 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 @@ public int indexOf (MenuItem item) { /** * 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 @@ public void setDefaultItem (MenuItem item) { } /** * 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 @@ public void setEnabled (boolean enabled) { 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 @@ public void setLocation (int x, int y) { 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 a2ba19f5bc..54717f30d5 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 @@ public void addHelpListener (HelpListener listener) { } /** * 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 @@ void destroyWidget () { 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 @@ public int getAccelerator () { } /** * 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 @@ boolean isAccelActive () { /** * 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 @@ void selectRadio () { * 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 @@ public void setAccelerator (int accelerator) { } /** * 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 e1320b429a..b22dfaf18b 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 @@ int createHandle (int parentHandle, int [] argList) { } /** - * 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 ca908c9f80..5bd84a7fcb 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 @@ public int getMinimum () { 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 @@ public void setMinimum (int value) { 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 a84776d6be..b1b55cfb33 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 @@ public int getPageIncrement () { 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 @@ public void setPageIncrement (int pageIncrement) { 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 ab68d5652a..bc4788a1bb 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 @@ import org.eclipse.swt.events.*; * 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 @@ ScrollBar (Scrollable parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: + * <code>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 @@ public int getPageIncrement () { 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 @@ public Scrollable getParent () { 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 d6a2b20e25..703710d4b4 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 @@ import org.eclipse.swt.events.*; * 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 @@ Shell (Display display, Shell parent, int style, int handle) { * @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 @@ public Shell (Shell parent) { * @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 @@ public Shell (Shell parent) { * @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 @@ public void setMinimized (boolean minimized) { } } /** - * 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 @@ public void setMinimumSize (int width, int height) { 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 7da69fafb0..fb890adb63 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 @@ import org.eclipse.swt.graphics.*; * 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 @@ public Slider (Composite parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. + * <code>SWT.NONE</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. @@ -238,7 +238,7 @@ public int getPageIncrement () { 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 @@ public void setPageIncrement (int value) { 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 99b0a48640..e7cc1b2b99 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 @@ import org.eclipse.swt.events.*; * <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 @@ public class Spinner extends Composite { * </ul> * * @see SWT#READ_ONLY + * @see SWT#WRAP * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -310,6 +311,16 @@ int fontHandle () { 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 @@ boolean setBounds (int x, int y, int width, int height, boolean move, boolean re } 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 31cf12085d..cb13de051a 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 @@ public class Text extends Scrollable { /** * 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 @@ int defaultForeground () { 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 @@ public int getCaretLineNumber () { 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 @@ public Point getCaretLocation () { 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 @@ public int getCaretPosition () { 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 @@ public int getCharCount () { 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 @@ public boolean getDoubleClickEnabled () { 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 @@ public boolean getDoubleClickEnabled () { * <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 @@ public boolean getEditable () { 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 @@ public int getLineCount () { return getLineNumber (lastChar) + 1; } /** - * Gets the line delimiter. + * Returns the line delimiter. * * @return a string that is the line delimiter * @@ -577,13 +584,15 @@ public int getLineCount () { * <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 @@ int getNavigationType () { 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 @@ public int getOrientation () { 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 @@ public Point getSelection () { 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 @@ public int getSelectionCount () { 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 @@ public String getSelectionText () { 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 @@ public int getTabs () { 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 @@ public String getText () { 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 @@ public String getText (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #LIMIT */ public int getTextLimit () { checkWidget(); @@ -857,7 +873,7 @@ public int getTopIndex () { 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 @@ int inputContext () { * * @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 @@ boolean setBounds (int x, int y, int width, int height, boolean move, boolean re * 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 @@ public void setDoubleClickEnabled (boolean doubleClick) { * 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 @@ public void setEditable (boolean editable) { * 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 @@ public void setSelection (int start) { 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 @@ public void setSelection (int start, int end) { 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 @@ public void setText (String string) { * 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 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @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 b11318c3fe..f510c01801 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 @@ Widget () { * * @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 @@ String getCodePage () { * <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 @@ public Object getData () { * <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 @@ public Object getData (String key) { * * @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 @@ boolean sendKeyEvent (int type, XKeyEvent xEvent) { * <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 @@ public void setData (Object data) { * <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 3968469a05..6305dbcfe8 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 @@ public RGB getRGB () { /** * 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 9238ab36ea..28788f8eaf 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 @@ public boolean equals (Object object) { /** * 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 2708825e46..bdceaf2444 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 @@ public FontData [] getFontList (String faceName, boolean scalable) { * 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 @@ public Color getSystemColor (int id) { * 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 1e80d678cf..c9197300bb 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 @@ public FontData[] getFontData() { /** * 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 d08ddc9374..bf8927bf3e 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 @@ public int getStyle() { /** * 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 @@ public void setLocale(String locale) { /** * 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 8012b78dd4..4388c80947 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 @@ public int getLeading() { /** * 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 5e07270b85..94660b2a9b 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(Image image, int x, int y) { 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 @@ public void drawArc (int x, int y, int width, int height, int startAngle, int ar * <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 @@ public void drawOval (int x, int y, int width, int height) { } } -/** - * 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 @@ public void fillArc (int x, int y, int width, int height, int startAngle, int ar * <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 @@ public void fillOval (int x, int y, int width, int height) { } } -/** - * 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 @@ public void fillPolygon(int[] pointArray) { * <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 @@ public void fillRectangle (int x, int y, int width, int height) { * <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 @@ public int getAdvanceWidth(char ch) { 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 @@ public int getAlpha() { } /** - * 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 @@ public Color getBackground() { 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 @@ public void getClipping (Region region) { } } +/** + * 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 @@ public Color getForeground() { 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 @@ public int getLineCap() { } /** - * 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 @@ public int getStyle () { } /** - * 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 @@ public boolean getXORMode() { /** * 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 @@ public boolean isDisposed() { 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 @@ public void setAdvanced(boolean advanced) { } /** - * 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 @@ public void setBackground (Color color) { 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 @@ public void setClipping (int x, int y, int width, int height) { } /** - * 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 @@ public void setClipping(Path path) { /** * 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 @@ public void setClipping (Rectangle rect) { /** * 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 @@ public void setClipping (Region region) { 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 @@ public void setForeground (Color color) { 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 @@ public void setInterpolation(int interpolation) { } } +/** + * 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 @@ public void setLineCap(int cap) { } /** - * 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 @@ public void setLineStyle(int lineStyle) { * 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 @@ int getClipping(int widget, int topWidget, boolean clipChildren, boolean clipSib } /** - * 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 @@ public void setTextAntialias(int 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); @@ -2898,12 +3257,19 @@ public void setTransform(Transform transform) { * 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 67fbbab33b..fcb05c35c8 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 @@ import java.io.*; * 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 @@ public Image(Device device, ImageData source, ImageData mask) { * 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 @@ public ImageData getImageData() { /** * 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 6404ed4b80..c44ba7646b 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 @@ public void add (Rectangle rect) { * @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 @@ public Rectangle getBounds() { /** * 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 @@ public void intersect (Region region) { * <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 @@ public boolean intersects (int x, int y, int width, int height) { * <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 @@ public void subtract (Rectangle rect) { * @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 50ec6429b5..faa9f4df36 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 @@ public void setSelection (boolean selected) { /** * 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 f890c3a526..17030b04eb 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 @@ Canvas () { * </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 a41cfbab1b..71b01740be 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 @@ public int getItemHeight () { } /** - * 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 @@ public int getOrientation () { } /** - * 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 @@ public int getSelectionIndex () { /** * 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 @@ public int getTextHeight () { * <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 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize /** * 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 @@ public void setText (String string) { /** * 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 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @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 06d06c4839..c333579ae8 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 @@ import org.eclipse.swt.graphics.*; * 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 @@ int getClipping(int widget, int topWidget, boolean clipChildren, boolean clipSib } /** - * 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 @@ public boolean isLayoutDeferred () { } /** - * 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 974b0b2198..54b5d1a5d2 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 @@ void checkBuffered () { * @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 @@ public Point computeSize (int wHint, int hHint) { * @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 @@ public void moveBelow (Control control) { * <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 @@ public void pack () { * <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 @@ public void setMenu (Menu menu) { * @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 @@ boolean setRadioSelection (boolean value) { * <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 @@ boolean traverseReturn () { * <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 d651c4cc41..306d5e3b51 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 @@ public Image getImage () { * 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 @@ void resizeBounds (int width, int height) { * <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 @@ public void setImage (Image image) { * 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 @@ public void setImages (Image [] images) { * 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 @@ public void setMenuBar (Menu menu) { * 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 @@ public void setMinimized (boolean minimized) { /** * 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 6d1ad39da8..128466af5e 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 @@ public DirectoryDialog (Shell parent, int style) { * the directories it shows. * * @return the filter path + * + * @see #setFilterPath */ public String getFilterPath () { return filterPath; @@ -135,9 +137,15 @@ public String open () { } /** - * 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 d78b93b84a..a80711db0e 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 @@ static void setDevice (Device device) { * </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 @@ public Display () { 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 @@ public void addListener (int eventType, Listener listener) { * 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 @@ synchronized void deregister () { * <p> * This method is called after <code>release</code>. * </p> - * @see #dispose + * @see Device#dispose * @see #release */ protected void destroy () { @@ -565,7 +577,8 @@ void destroyDisplay () { /** * 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 @@ void error (int code) { /** * 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 @@ public static synchronized Display getDefault () { /** * 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 @@ public boolean getHighContrast () { } /** - * 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 @@ public boolean getHighContrast () { * <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 @@ public Monitor getPrimaryMonitor () { } /** - * 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 @@ boolean isValidThread () { * 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 @@ public Object getData (String key) { * 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 @@ synchronized void register () { * </p> * This method is called before <code>destroy</code>. * - * @see #dispose + * @see Device#dispose * @see #destroy */ protected void release () { @@ -2394,9 +2411,16 @@ public boolean sleep () { * 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 @@ int textWidth (String string, byte[] font) { * 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 @@ public void update() { } /** - * 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 964d72164e..dbff1ba7dd 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 @@ import org.eclipse.swt.*; * <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 @@ public FileDialog (Shell parent, int style) { /** * 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 @@ public String getFileName () { } /** - * 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 @@ public String [] getFilterExtensions () { } /** - * 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 @@ public void setFileName (String string) { * 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 @@ public void setFilterExtensions (String [] 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; @@ -252,7 +260,14 @@ public void setFilterNames (String [] names) { * 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 4096f862fe..1b5a08af48 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 @@ import org.eclipse.swt.events.*; * <p> * <dl> * <dt><b>Styles:</b></dt> + * <dd>(none)</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -583,7 +584,7 @@ public void setFont (Font font) { * 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 75783b3b1c..bbab8d47a5 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 @@ import org.eclipse.swt.events.*; /** * 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 @@ public int getItemCount () { /** * 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 @@ public int getItemHeight () { } /** - * 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 @@ public String [] getItems () { /** * 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 @@ public int getSelectionCount () { * 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 @@ public int getSelectionIndex () { /** * 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 @@ public void setSelection (int start, int end) { /** * 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 bc439c37db..efe4970ce9 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 @@ public MenuItem getDefaultItem () { /** * 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 @@ public MenuItem getItem (int index) { } /** - * 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 @@ public int indexOf (MenuItem item) { /** * 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 @@ public void setDefaultItem (MenuItem item) { /** * 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 @@ public void setEnabled (boolean enabled) { } /** - * 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 @@ public void setLocation (int x, int y) { } /** - * 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 dc44683e89..769f6d587a 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 @@ public void addHelpListener (HelpListener listener) { /** * 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 @@ void createHandle (int index) { } /** - * 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 @@ public int getAccelerator () { /** * 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 @@ int hotkeyProc (int widget, int data, int info) { /** * 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 @@ void selectRadio () { * 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 @@ public void setAccelerator (int accelerator) { /** * 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 @@ public void setEnabled (boolean enabled) { /** * 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 a08f6e8d85..a817c89f7f 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 @@ static int checkStyle (int style) { 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 cb24ebd4d7..263add3934 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 @@ public int getMinimum () { } /** - * 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 @@ public void setMinimum (int 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/photon/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java index 95559709d1..414b7a3bf5 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 @@ public int getPageIncrement () { } /** - * 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 @@ public void setPageIncrement (int value) { } /** - * 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 606d8e3cbc..36c5cb677c 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 @@ import org.eclipse.swt.events.*; * 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 @@ static int checkStyle (int style) { * 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 @@ public int getPageIncrement () { } /** - * 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 @@ public Scrollable getParent () { } /** - * 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 f85947899b..0839d574db 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 @@ import org.eclipse.swt.events.*; * 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 @@ Shell (Display display, Shell parent, int style, int handle) { * @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 @@ public Shell (Shell parent) { * @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 @@ public Shell (Shell parent) { * @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 @@ public void setRegion (Region region) { } /** - * 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 @@ public void setMinimumSize (int width, int height) { } /** - * 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 4f4755fa54..0da568e8d7 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 @@ import org.eclipse.swt.events.*; * 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 @@ static int checkStyle (int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. + * <code>SWT.NONE</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. @@ -254,7 +254,7 @@ public int getPageIncrement () { } /** - * 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 @@ public void setPageIncrement (int value) { } /** - * 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 ecf1affc48..89c1c7cfa1 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 @@ import org.eclipse.swt.*; * <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 @@ public class Spinner extends Composite { * </ul> * * @see SWT#READ_ONLY + * @see SWT#WRAP * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -321,6 +322,16 @@ int defaultForeground () { 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 @@ void removeVerifyListener (VerifyListener listener) { 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 eae743d769..0d399da56b 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 @@ public class Text extends Scrollable { /** * 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 @@ int defaultForeground () { } /** - * 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 @@ public int getCaretLineNumber () { } /** - * 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 @@ public Point getCaretLocation () { } /** - * 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 @@ public int getCaretPosition () { } /** - * Gets the number of characters. + * Returns the number of characters. * * @return number of characters in the widget * @@ -475,7 +480,7 @@ public int getCharCount () { } /** - * 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 @@ public boolean getDoubleClickEnabled () { } /** - * 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 @@ public boolean getDoubleClickEnabled () { * <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 @@ public char getEchoChar () { } /** - * Gets the editable state. + * Returns the editable state. * * @return whether or not the reciever is editable * @@ -533,7 +540,7 @@ public boolean getEditable () { } /** - * Gets the number of lines. + * Returns the number of lines. * * @return the number of lines in the widget * @@ -551,7 +558,7 @@ public int getLineCount () { } /** - * Gets the line delimiter. + * Returns the line delimiter. * * @return a string that is the line delimiter * @@ -559,6 +566,8 @@ public int getLineCount () { * <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 @@ public String getLineDelimiter () { } /** - * Gets the height of a line. + * Returns the height of a line. * * @return the height of a row of text * @@ -609,7 +618,8 @@ String getNameText () { } /** - * 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 @@ public int getOrientation () { } /** - * 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 @@ public Point getSelection () { } /** - * Gets the number of selected characters. + * Returns the number of selected characters. * * @return the number of selected characters. * @@ -672,7 +685,7 @@ public int getSelectionCount () { } /** - * 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 @@ public String getSelectionText () { } /** - * 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 @@ int getTabWidth (int tabs) { } /** - * 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 @@ public String getText (int start, int end) { } /** - * 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 @@ public String getText () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #LIMIT */ public int getTextLimit () { checkWidget(); @@ -828,7 +844,7 @@ public int getTopIndex () { } /** - * 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 @@ void hookEvents () { * * @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 @@ public void selectAll () { * 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 @@ public void setEchoChar (char echo) { * 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 @@ public void setFont (Font font) { * 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 @@ public void setSelection (int position) { } /** - * 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 @@ public void setSelection (Point selection) { } /** - * 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 @@ public void setText (String string) { * 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 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @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 2c14640587..ff66efc257 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 @@ Widget () { * * @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 @@ char fixMnemonic (char [] buffer) { * <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 @@ public Object getData () { * <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 @@ public Object getData (String key) { * * @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 @@ void sendEvent (int eventType, Event event, boolean send) { * <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 @@ public void setData (Object data) { * <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(); |