diff options
Diffstat (limited to 'bundles/org.eclipse.swt')
173 files changed, 2435 insertions, 347 deletions
diff --git a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/carbon/org/eclipse/swt/accessibility/Accessible.java b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/carbon/org/eclipse/swt/accessibility/Accessible.java index ab856c3af9..1a85e8f725 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/carbon/org/eclipse/swt/accessibility/Accessible.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/carbon/org/eclipse/swt/accessibility/Accessible.java @@ -1557,13 +1557,46 @@ public class Accessible { * indicating that something has changed within a custom control. * * @param event an <code>ACC</code> constant beginning with EVENT_* indicating the message to send - * @param eventData an object containing event-specific data + * @param eventData an object containing event-specific data, or null if there is no event-specific data * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver's control has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li> * </ul> * + * @see ACC#EVENT_ACTION_CHANGED + * @see ACC#EVENT_ATTRIBUTE_CHANGED + * @see ACC#EVENT_DESCRIPTION_CHANGED + * @see ACC#EVENT_DOCUMENT_LOAD_COMPLETE + * @see ACC#EVENT_DOCUMENT_LOAD_STOPPED + * @see ACC#EVENT_DOCUMENT_RELOAD + * @see ACC#EVENT_HYPERLINK_ACTIVATED + * @see ACC#EVENT_HYPERLINK_ANCHOR_COUNT_CHANGED + * @see ACC#EVENT_HYPERLINK_END_INDEX_CHANGED + * @see ACC#EVENT_HYPERLINK_SELECTED_LINK_CHANGED + * @see ACC#EVENT_HYPERLINK_START_INDEX_CHANGED + * @see ACC#EVENT_HYPERTEXT_LINK_COUNT_CHANGED + * @see ACC#EVENT_HYPERTEXT_LINK_SELECTED + * @see ACC#EVENT_LOCATION_CHANGED + * @see ACC#EVENT_NAME_CHANGED + * @see ACC#EVENT_PAGE_CHANGED + * @see ACC#EVENT_SECTION_CHANGED + * @see ACC#EVENT_SELECTION_CHANGED + * @see ACC#EVENT_STATE_CHANGED + * @see ACC#EVENT_TABLE_CAPTION_CHANGED + * @see ACC#EVENT_TABLE_CHANGED + * @see ACC#EVENT_TABLE_COLUMN_DESCRIPTION_CHANGED + * @see ACC#EVENT_TABLE_COLUMN_HEADER_CHANGED + * @see ACC#EVENT_TABLE_ROW_DESCRIPTION_CHANGED + * @see ACC#EVENT_TABLE_ROW_HEADER_CHANGED + * @see ACC#EVENT_TABLE_SUMMARY_CHANGED + * @see ACC#EVENT_TEXT_ATTRIBUTE_CHANGED + * @see ACC#EVENT_TEXT_CARET_MOVED + * @see ACC#EVENT_TEXT_CHANGED + * @see ACC#EVENT_TEXT_COLUMN_CHANGED + * @see ACC#EVENT_TEXT_SELECTION_CHANGED + * @see ACC#EVENT_VALUE_CHANGED + * * @since 3.6 */ public void sendEvent(int event, Object eventData) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/cocoa/org/eclipse/swt/accessibility/Accessible.java b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/cocoa/org/eclipse/swt/accessibility/Accessible.java index bb3c5cc05f..0ab7cc9a77 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/cocoa/org/eclipse/swt/accessibility/Accessible.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/cocoa/org/eclipse/swt/accessibility/Accessible.java @@ -2981,13 +2981,46 @@ public class Accessible { * indicating that something has changed within a custom control. * * @param event an <code>ACC</code> constant beginning with EVENT_* indicating the message to send - * @param eventData an object containing event-specific data + * @param eventData an object containing event-specific data, or null if there is no event-specific data * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver's control has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li> * </ul> * + * @see ACC#EVENT_ACTION_CHANGED + * @see ACC#EVENT_ATTRIBUTE_CHANGED + * @see ACC#EVENT_DESCRIPTION_CHANGED + * @see ACC#EVENT_DOCUMENT_LOAD_COMPLETE + * @see ACC#EVENT_DOCUMENT_LOAD_STOPPED + * @see ACC#EVENT_DOCUMENT_RELOAD + * @see ACC#EVENT_HYPERLINK_ACTIVATED + * @see ACC#EVENT_HYPERLINK_ANCHOR_COUNT_CHANGED + * @see ACC#EVENT_HYPERLINK_END_INDEX_CHANGED + * @see ACC#EVENT_HYPERLINK_SELECTED_LINK_CHANGED + * @see ACC#EVENT_HYPERLINK_START_INDEX_CHANGED + * @see ACC#EVENT_HYPERTEXT_LINK_COUNT_CHANGED + * @see ACC#EVENT_HYPERTEXT_LINK_SELECTED + * @see ACC#EVENT_LOCATION_CHANGED + * @see ACC#EVENT_NAME_CHANGED + * @see ACC#EVENT_PAGE_CHANGED + * @see ACC#EVENT_SECTION_CHANGED + * @see ACC#EVENT_SELECTION_CHANGED + * @see ACC#EVENT_STATE_CHANGED + * @see ACC#EVENT_TABLE_CAPTION_CHANGED + * @see ACC#EVENT_TABLE_CHANGED + * @see ACC#EVENT_TABLE_COLUMN_DESCRIPTION_CHANGED + * @see ACC#EVENT_TABLE_COLUMN_HEADER_CHANGED + * @see ACC#EVENT_TABLE_ROW_DESCRIPTION_CHANGED + * @see ACC#EVENT_TABLE_ROW_HEADER_CHANGED + * @see ACC#EVENT_TABLE_SUMMARY_CHANGED + * @see ACC#EVENT_TEXT_ATTRIBUTE_CHANGED + * @see ACC#EVENT_TEXT_CARET_MOVED + * @see ACC#EVENT_TEXT_CHANGED + * @see ACC#EVENT_TEXT_COLUMN_CHANGED + * @see ACC#EVENT_TEXT_SELECTION_CHANGED + * @see ACC#EVENT_VALUE_CHANGED + * * @since 3.6 */ public void sendEvent(int event, Object eventData) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/emulated/org/eclipse/swt/accessibility/Accessible.java b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/emulated/org/eclipse/swt/accessibility/Accessible.java index 066ad1bc10..41eb5f5e4f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/emulated/org/eclipse/swt/accessibility/Accessible.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/emulated/org/eclipse/swt/accessibility/Accessible.java @@ -576,13 +576,46 @@ public class Accessible { * indicating that something has changed within a custom control. * * @param event an <code>ACC</code> constant beginning with EVENT_* indicating the message to send - * @param eventData an object containing event-specific data + * @param eventData an object containing event-specific data, or null if there is no event-specific data * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver's control has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li> * </ul> * + * @see ACC#EVENT_ACTION_CHANGED + * @see ACC#EVENT_ATTRIBUTE_CHANGED + * @see ACC#EVENT_DESCRIPTION_CHANGED + * @see ACC#EVENT_DOCUMENT_LOAD_COMPLETE + * @see ACC#EVENT_DOCUMENT_LOAD_STOPPED + * @see ACC#EVENT_DOCUMENT_RELOAD + * @see ACC#EVENT_HYPERLINK_ACTIVATED + * @see ACC#EVENT_HYPERLINK_ANCHOR_COUNT_CHANGED + * @see ACC#EVENT_HYPERLINK_END_INDEX_CHANGED + * @see ACC#EVENT_HYPERLINK_SELECTED_LINK_CHANGED + * @see ACC#EVENT_HYPERLINK_START_INDEX_CHANGED + * @see ACC#EVENT_HYPERTEXT_LINK_COUNT_CHANGED + * @see ACC#EVENT_HYPERTEXT_LINK_SELECTED + * @see ACC#EVENT_LOCATION_CHANGED + * @see ACC#EVENT_NAME_CHANGED + * @see ACC#EVENT_PAGE_CHANGED + * @see ACC#EVENT_SECTION_CHANGED + * @see ACC#EVENT_SELECTION_CHANGED + * @see ACC#EVENT_STATE_CHANGED + * @see ACC#EVENT_TABLE_CAPTION_CHANGED + * @see ACC#EVENT_TABLE_CHANGED + * @see ACC#EVENT_TABLE_COLUMN_DESCRIPTION_CHANGED + * @see ACC#EVENT_TABLE_COLUMN_HEADER_CHANGED + * @see ACC#EVENT_TABLE_ROW_DESCRIPTION_CHANGED + * @see ACC#EVENT_TABLE_ROW_HEADER_CHANGED + * @see ACC#EVENT_TABLE_SUMMARY_CHANGED + * @see ACC#EVENT_TEXT_ATTRIBUTE_CHANGED + * @see ACC#EVENT_TEXT_CARET_MOVED + * @see ACC#EVENT_TEXT_CHANGED + * @see ACC#EVENT_TEXT_COLUMN_CHANGED + * @see ACC#EVENT_TEXT_SELECTION_CHANGED + * @see ACC#EVENT_VALUE_CHANGED + * * @since 3.6 */ public void sendEvent(int event, Object eventData) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/gtk/org/eclipse/swt/accessibility/Accessible.java b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/gtk/org/eclipse/swt/accessibility/Accessible.java index 683d944a36..f1b21b906f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Accessibility/gtk/org/eclipse/swt/accessibility/Accessible.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Accessibility/gtk/org/eclipse/swt/accessibility/Accessible.java @@ -770,13 +770,46 @@ public class Accessible { * indicating that something has changed within a custom control. * * @param event an <code>ACC</code> constant beginning with EVENT_* indicating the message to send - * @param eventData an object containing event-specific data + * @param eventData an object containing event-specific data, or null if there is no event-specific data * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver's control has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver's control</li> * </ul> * + * @see ACC#EVENT_ACTION_CHANGED + * @see ACC#EVENT_ATTRIBUTE_CHANGED + * @see ACC#EVENT_DESCRIPTION_CHANGED + * @see ACC#EVENT_DOCUMENT_LOAD_COMPLETE + * @see ACC#EVENT_DOCUMENT_LOAD_STOPPED + * @see ACC#EVENT_DOCUMENT_RELOAD + * @see ACC#EVENT_HYPERLINK_ACTIVATED + * @see ACC#EVENT_HYPERLINK_ANCHOR_COUNT_CHANGED + * @see ACC#EVENT_HYPERLINK_END_INDEX_CHANGED + * @see ACC#EVENT_HYPERLINK_SELECTED_LINK_CHANGED + * @see ACC#EVENT_HYPERLINK_START_INDEX_CHANGED + * @see ACC#EVENT_HYPERTEXT_LINK_COUNT_CHANGED + * @see ACC#EVENT_HYPERTEXT_LINK_SELECTED + * @see ACC#EVENT_LOCATION_CHANGED + * @see ACC#EVENT_NAME_CHANGED + * @see ACC#EVENT_PAGE_CHANGED + * @see ACC#EVENT_SECTION_CHANGED + * @see ACC#EVENT_SELECTION_CHANGED + * @see ACC#EVENT_STATE_CHANGED + * @see ACC#EVENT_TABLE_CAPTION_CHANGED + * @see ACC#EVENT_TABLE_CHANGED + * @see ACC#EVENT_TABLE_COLUMN_DESCRIPTION_CHANGED + * @see ACC#EVENT_TABLE_COLUMN_HEADER_CHANGED + * @see ACC#EVENT_TABLE_ROW_DESCRIPTION_CHANGED + * @see ACC#EVENT_TABLE_ROW_HEADER_CHANGED + * @see ACC#EVENT_TABLE_SUMMARY_CHANGED + * @see ACC#EVENT_TEXT_ATTRIBUTE_CHANGED + * @see ACC#EVENT_TEXT_CARET_MOVED + * @see ACC#EVENT_TEXT_CHANGED + * @see ACC#EVENT_TEXT_COLUMN_CHANGED + * @see ACC#EVENT_TEXT_SELECTION_CHANGED + * @see ACC#EVENT_VALUE_CHANGED + * * @since 3.6 */ public void sendEvent(int event, Object eventData) { 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 f9c17e81d6..6ad9d48963 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 @@ -25,6 +25,12 @@ import org.eclipse.swt.internal.carbon.OS; * String textData = "Hello World"; * </code></pre> * + * <p>Note the <code>TextTransfer</code> does not change the content of the text + * data. For a better integration with the platform, the application should convert + * the line delimiters used in the text data to the standard line delimiter used by the + * platform. + * </p> + * * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/TextTransfer.java index ac7ab05d94..e69e101ff5 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/TextTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/cocoa/org/eclipse/swt/dnd/TextTransfer.java @@ -24,6 +24,12 @@ import org.eclipse.swt.internal.cocoa.*; * String textData = "Hello World"; * </code></pre> * + * <p>Note the <code>TextTransfer</code> does not change the content of the text + * data. For a better integration with the platform, the application should convert + * the line delimiters used in the text data to the standard line delimiter used by the + * platform. + * </p> + * * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { 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 21ef001cee..2ab0e06ce8 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 @@ -23,6 +23,12 @@ package org.eclipse.swt.dnd; * String textData = "Hello World"; * </code></pre> * + * <p>Note the <code>TextTransfer</code> does not change the content of the text + * data. For a better integration with the platform, the application should convert + * the line delimiters used in the text data to the standard line delimiter used by the + * platform. + * </p> + * * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { 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 6a6dabc616..63ce761cb3 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 @@ -25,6 +25,12 @@ import org.eclipse.swt.internal.gtk.*; * String textData = "Hello World"; * </code></pre> * + * <p>Note the <code>TextTransfer</code> does not change the content of the text + * data. For a better integration with the platform, the application should convert + * the line delimiters used in the text data to the standard line delimiter used by the + * platform. + * </p> + * * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { 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 da99125db1..f61960f492 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 @@ -27,6 +27,12 @@ import org.eclipse.swt.internal.motif.XTextProperty; * String textData = "Hello World"; * </code></pre> * + * <p>Note the <code>TextTransfer</code> does not change the content of the text + * data. For a better integration with the platform, the application should convert + * the line delimiters used in the text data to the standard line delimiter used by the + * platform. + * </p> + * * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { 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 568f1e51df..056d74aad0 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 @@ -26,6 +26,12 @@ import org.eclipse.swt.internal.photon.OS; * String textData = "Hello World"; * </code></pre> * + * <p>Note the <code>TextTransfer</code> does not change the content of the text + * data. For a better integration with the platform, the application should convert + * the line delimiters used in the text data to the standard line delimiter used by the + * platform. + * </p> + * * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/wpf/org/eclipse/swt/dnd/TextTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/wpf/org/eclipse/swt/dnd/TextTransfer.java index 3dfc44cbaa..8fef1f9440 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/wpf/org/eclipse/swt/dnd/TextTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/wpf/org/eclipse/swt/dnd/TextTransfer.java @@ -25,6 +25,12 @@ import org.eclipse.swt.internal.wpf.*; * String textData = "Hello World"; * </code></pre> * + * <p>Note the <code>TextTransfer</code> does not change the content of the text + * data. For a better integration with the platform, the application should convert + * the line delimiters used in the text data to the standard line delimiter used by the + * platform. + * </p> + * * @see Transfer */ public class TextTransfer extends ByteArrayTransfer { 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 8e86a7e2c2..477401e4f2 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 @@ -321,12 +321,13 @@ public static boolean launch (String fileName) { /** * Launches the operating system executable associated with the file or * URL (http:// or https://). If the file is an executable then the - * executable is launched. If a valid working directory is specified - * it is used as working directory for the launched program. + * executable is launched. The program is launched with the specified + * working directory only when the <code>workingDir</code> exists and + * <code>fileName</code> is an executable. * Note that a <code>Display</code> must already exist to guarantee * that this method returns an appropriate result. * - * @param fileName the file or program name or URL (http:// or https://) + * @param fileName the file name or program name or URL (http:// or https://) * @param workingDir the name of the working directory or null * @return <code>true</code> if the file is launched, otherwise <code>false</code> * diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/cocoa/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/cocoa/org/eclipse/swt/program/Program.java index 7663476ee2..df4ee14df2 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT Program/cocoa/org/eclipse/swt/program/Program.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Program/cocoa/org/eclipse/swt/program/Program.java @@ -265,12 +265,13 @@ public static boolean launch (String fileName) { /** * Launches the operating system executable associated with the file or * URL (http:// or https://). If the file is an executable then the - * executable is launched. If a valid working directory is specified - * it is used as working directory for the launched program. + * executable is launched. The program is launched with the specified + * working directory only when the <code>workingDir</code> exists and + * <code>fileName</code> is an executable. * Note that a <code>Display</code> must already exist to guarantee * that this method returns an appropriate result. * - * @param fileName the file or program name or URL (http:// or https://) + * @param fileName the file name or program name or URL (http:// or https://) * @param workingDir the name of the working directory or null * @return <code>true</code> if the file is launched, otherwise <code>false</code> * diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/emulated/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/emulated/org/eclipse/swt/program/Program.java index ae9a27baac..77cf60cece 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Program/emulated/org/eclipse/swt/program/Program.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Program/emulated/org/eclipse/swt/program/Program.java @@ -95,12 +95,13 @@ public static boolean launch (String fileName) { /** * Launches the operating system executable associated with the file or * URL (http:// or https://). If the file is an executable then the - * executable is launched. If a valid working directory is specified - * it is used as working directory for the launched program. + * executable is launched. The program is launched with the specified + * working directory only when the <code>workingDir</code> exists and + * <code>fileName</code> is an executable. * Note that a <code>Display</code> must already exist to guarantee * that this method returns an appropriate result. * - * @param fileName the file or program name or URL (http:// or https://) + * @param fileName the file name or program name or URL (http:// or https://) * @param workingDir the name of the working directory or null * @return <code>true</code> if the file is launched, otherwise <code>false</code> * 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 5fbec60dc1..6f78ce277c 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 @@ -1027,23 +1027,24 @@ public static boolean launch(String fileName) { } /** -* Launches the operating system executable associated with the file or -* URL (http:// or https://). If the file is an executable then the -* executable is launched. If a valid working directory is specified -* it is used as the working directory for the launched program. -* Note that a <code>Display</code> must already exist to guarantee -* that this method returns an appropriate result. -* -* @param fileName the file or program name or URL (http:// or https://) -* @param workingDir the name of the working directory or null -* @return <code>true</code> if the file is launched, otherwise <code>false</code> -* -* @exception IllegalArgumentException <ul> -* <li>ERROR_NULL_ARGUMENT when fileName is null</li> -* </ul> -* -* @since 3.6 -*/ + * Launches the operating system executable associated with the file or + * URL (http:// or https://). If the file is an executable then the + * executable is launched. The program is launched with the specified + * working directory only when the <code>workingDir</code> exists and + * <code>fileName</code> is an executable. + * Note that a <code>Display</code> must already exist to guarantee + * that this method returns an appropriate result. + * + * @param fileName the file name or program name or URL (http:// or https://) + * @param workingDir the name of the working directory or null + * @return <code>true</code> if the file is launched, otherwise <code>false</code> + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> + * + * @since 3.6 + */ public static boolean launch (String fileName, String workingDir) { return launch(Display.getCurrent(), fileName, workingDir); } 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 a13fe75f61..58a8d97e20 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 @@ -750,24 +750,24 @@ public static boolean launch(String fileName) { } /** -* Launches the operating system executable associated with the file or -* URL (http:// or https://). If the file is an executable then the -* executable is launched. If a valid working directory is specified -* it is used as the working directory for the launched program. -* Note that a <code>Display</code> must already exist to guarantee -* that this method returns an appropriate result. -* -* @param fileName the file or program name or URL (http:// or https://) -* @param workingDir the name of the working directory or null -* @return <code>true</code> if the file is launched, otherwise <code>false</code> -* -* @exception IllegalArgumentException <ul> -* <li>ERROR_NULL_ARGUMENT when fileName is null</li> -* <li>ERROR_INVALID_ARGUMENT when workingDir is not valid</li> -* </ul> -* -* @since 3.6 -*/ + * Launches the operating system executable associated with the file or + * URL (http:// or https://). If the file is an executable then the + * executable is launched. The program is launched with the specified + * working directory only when the <code>workingDir</code> exists and + * <code>fileName</code> is an executable. + * Note that a <code>Display</code> must already exist to guarantee + * that this method returns an appropriate result. + * + * @param fileName the file name or program name or URL (http:// or https://) + * @param workingDir the name of the working directory or null + * @return <code>true</code> if the file is launched, otherwise <code>false</code> + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> + * + * @since 3.6 + */ public static boolean launch (String fileName, String workingDir) { return launch(Display.getCurrent(), fileName, workingDir); } 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 72f1eac66a..741fa4666f 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 @@ -178,18 +178,18 @@ public static boolean launch (String fileName) { /** * Launches the operating system executable associated with the file or * URL (http:// or https://). If the file is an executable then the - * executable is launched. If a valid working directory is specified - * it is used as the working directory for the launched program. + * executable is launched. The program is launched with the specified + * working directory only when the <code>workingDir</code> exists and + * <code>fileName</code> is an executable. * Note that a <code>Display</code> must already exist to guarantee * that this method returns an appropriate result. * - * @param fileName the file or program name or URL (http:// or https://) + * @param fileName the file name or program name or URL (http:// or https://) * @param workingDir the name of the working directory or null * @return <code>true</code> if the file is launched, otherwise <code>false</code> * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT when fileName is null</li> - * <li>ERROR_INVALID_ARGUMENT when workingDir is not valid</li> * </ul> * * @since 3.6 diff --git a/bundles/org.eclipse.swt/Eclipse SWT Program/wpf/org/eclipse/swt/program/Program.java b/bundles/org.eclipse.swt/Eclipse SWT Program/wpf/org/eclipse/swt/program/Program.java index c0d0c106ed..c4993e7766 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Program/wpf/org/eclipse/swt/program/Program.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Program/wpf/org/eclipse/swt/program/Program.java @@ -242,18 +242,18 @@ public static boolean launch (String fileName) { /** * Launches the operating system executable associated with the file or * URL (http:// or https://). If the file is an executable then the - * executable is launched. If a valid working directory is specified - * it is used as the working directory for the launched program. + * executable is launched. The program is launched with the specified + * working directory only when the <code>workingDir</code> exists and + * <code>fileName</code> is an executable. * Note that a <code>Display</code> must already exist to guarantee * that this method returns an appropriate result. * - * @param fileName the file or program name or URL (http:// or https://) + * @param fileName the file name or program name or URL (http:// or https://) * @param workingDir the name of the working directory or null * @return <code>true</code> if the file is launched, otherwise <code>false</code> * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT when fileName is null</li> - * <li>ERROR_INVALID_ARGUMENT when workingDir is not valid</li> * </ul> * * @since 3.6 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 147a45f282..4a2cb56ccf 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 @@ -680,7 +680,7 @@ void init(PathData data) { * <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. + * invoke any other method (except {@link #dispose()}) using the Path. * * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise */ 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 978d8279d8..9e94116ef0 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 @@ -185,7 +185,7 @@ void destroy() { * <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. + * invoke any other method (except {@link #dispose()}) using the Pattern. * * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise */ 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 5072156713..067008c5ac 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 @@ -213,7 +213,7 @@ public void invert() { * <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. + * invoke any other method (except {@link #dispose()}) using the Transform. * * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise */ 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 a8d82e0856..ca1b545dcb 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 @@ -246,7 +246,7 @@ void init( int red, int green, int blue) { * <p> * This method gets the dispose state for the color. * When a color has been disposed, it is an error to - * invoke any other method using the color. + * invoke any other method (except {@link #dispose()}) using the color. * * @return <code>true</code> when the color is disposed and <code>false</code> otherwise */ 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 e3fa79059b..3fd6125ee1 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 @@ -74,6 +74,10 @@ Cursor(Device device) { * <p> * You must dispose the cursor when it is no longer required. * </p> + * NOTE: + * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)} + * instead of using this constructor. This way you can avoid the + * overhead of disposing the Cursor resource. * * @param device the device on which to allocate the cursor * @param style the style of cursor to allocate @@ -604,7 +608,7 @@ public int hashCode () { * <p> * This method gets the dispose state for the cursor. * When a cursor has been disposed, it is an error to - * invoke any other method using the cursor. + * invoke any other method (except {@link #dispose()}) using the cursor. * * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise */ 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 c45930b1fa..5f1e41e9e6 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 @@ -413,7 +413,7 @@ int createCFString(String str) { * <p> * This method gets the dispose state for the font. * When a font has been disposed, it is an error to - * invoke any other method using the font. + * invoke any other method (except {@link #dispose()}) using the font. * * @return <code>true</code> when the font is disposed and <code>false</code> otherwise */ 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 36e4f46bae..806758f07a 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 @@ -2543,7 +2543,7 @@ public boolean isClipped() { * <p> * This method gets the dispose state for the GC. * When a GC has been disposed, it is an error to - * invoke any other method using the GC. + * invoke any other method (except {@link #dispose()}) using the GC. * * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise */ 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 8f8d57e2c8..cf0e30a926 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 @@ -925,7 +925,7 @@ public int internal_new_GC (GCData data) { * </p> * * @param hDC the platform specific GC handle - * @param data the platform specific GC data + * @param data the platform specific GC data * * @noreference This method is not intended to be referenced by clients. */ @@ -939,7 +939,7 @@ public void internal_dispose_GC (int context, GCData data) { * <p> * This method gets the dispose state for the image. * When an image has been disposed, it is an error to - * invoke any other method using the image. + * invoke any other method (except {@link #dispose()}) using the image. * * @return <code>true</code> when the image is disposed and <code>false</code> otherwise */ 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 8715722063..6f0dc4e311 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 @@ -721,7 +721,7 @@ void init(PathData data) { * <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. + * invoke any other method (except {@link #dispose()}) using the Path. * * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise */ 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 94fb2fcef7..c2d0dd368a 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 @@ -276,7 +276,7 @@ int drawPatternProc (int ref, int context) { * <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. + * invoke any other method (except {@link #dispose()}) using the Pattern. * * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise */ 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 20539077fd..6eb7585fb0 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 @@ -417,7 +417,7 @@ public boolean intersects(Rectangle rect) { * <p> * This method gets the dispose state for the region. * When a region has been disposed, it is an error to - * invoke any other method using the region. + * invoke any other method (except {@link #dispose()}) using the region. * * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java index 6b3005efb3..4167bf31e4 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java @@ -1565,6 +1565,17 @@ public int[] getSegments() { return segments; } +/** + * Returns the segments characters of the receiver. + * + * @return the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public char[] getSegmentsChars () { checkLayout(); return segmentsChars; @@ -1722,6 +1733,17 @@ public int getWidth () { return wrapWidth == 0 ? -1 : wrapWidth; } +/** +* Returns the receiver's wrap indent. +* +* @return the receiver's wrap indent +* +* @exception SWTException <ul> +* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> +* </ul> +* +* @since 3.6 +*/ public int getWrapIndent () { checkLayout(); return wrapIndent; @@ -1744,7 +1766,7 @@ static boolean isUnderlineSupported (TextStyle style) { * <p> * This method gets the dispose state for the text layout. * When a text layout has been disposed, it is an error to - * invoke any other method using the text layout. + * invoke any other method (except {@link #dispose()}) using the text layout. * </p> * * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise @@ -1885,7 +1907,7 @@ public void setFont (Font font) { } /** - * Sets the indent of the receiver. This indent it applied of the first line of + * Sets the indent of the receiver. This indent is applied to the first line of * each paragraph. * * @param indent new indent @@ -1894,6 +1916,8 @@ public void setFont (Font font) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * + * @see #setWrapIndent(int) + * * @since 3.2 */ public void setIndent (int indent) { @@ -1948,7 +1972,7 @@ public void setOrientation(int orientation) { /** * Sets the offsets of the receiver's text segments. Text segments are used to - * override the default behaviour of the bidirectional algorithm. + * override the default behavior of the bidirectional algorithm. * Bidirectional reordering can happen within a text segment but not * between two adjacent segments. * <p> @@ -1957,12 +1981,18 @@ public void setOrientation(int orientation) { * always be zero and the last one should always be equals to length of * the text. * </p> + * <p> + * When segments characters are set, the segments are the offsets where + * the characters are inserted in the text. + * <p> * * @param segments the text segments offset * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @see #setSegmentsChars(char[]) */ public void setSegments(int[] segments) { checkLayout(); @@ -1980,6 +2010,23 @@ public void setSegments(int[] segments) { this.segments = segments; } +/** + * Sets the characters to be used in the segments boundaries. The segments + * are set by calling <code>setSegments(int[])</code>. The application can + * use this API to insert Unicode Control Characters in the text to control + * the display of the text and bidi reordering. The characters are not + * accessible by any other API in <code>TextLayout</code>. + * + * @param segmentsChars the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setSegments(int[]) + * + * @since 3.6 + */ public void setSegmentsChars(char[] segmentsChars) { checkLayout(); if (this.segmentsChars == null && segmentsChars == null) return; @@ -2215,6 +2262,20 @@ public void setWidth (int width) { setLayoutControl(OS.kATSULineWidthTag, OS.Long2Fix(Math.max(0, width)), 4); } +/** + * Sets the wrap indent of the receiver. This indent is applied to all lines + * in the paragraph except the first line. + * + * @param wrapIndent new wrap indent + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setIndent(int) + * + * @since 3.6 + */ public void setWrapIndent (int wrapIndent) { checkLayout (); if (wrapIndent < 0) return; 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 c35a4aabed..0a627750d2 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 @@ -208,7 +208,7 @@ public void invert() { * <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. + * invoke any other method (except {@link #dispose()}) using the Transform. * * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise */ 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 0211c05643..cf64bd55ff 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 @@ -103,6 +103,12 @@ public Button (Composite parent, int style) { * <code>widgetSelected</code> is called when the control is selected by the user. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified * 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 a44ed95978..781853d25b 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 @@ -283,7 +283,7 @@ void reskinChildren (int flags) { * the source area to the destination and then causing the area * of the source which is not covered by the destination to * be repainted. Children that intersect the rectangle are - * optionally moved during the operation. In addition, outstanding + * optionally moved during the operation. In addition, all outstanding * paint events are flushed before the source area is copied to * ensure that the contents of the canvas are drawn correctly. * 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 c9140595d2..574b9b0ac8 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 @@ -46,7 +46,7 @@ import org.eclipse.swt.internal.carbon.Rect; * <dt><b>Styles:</b></dt> * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Selection, Verify</dd> + * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. 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 fa60b9cf74..c5d5c65487 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 @@ -268,6 +268,33 @@ void createScrolledHandle (int parentHandle) { OS.HIObjectSetAccessibilityIgnored (handle, true); } +/** + * Fills the interior of the rectangle specified by the arguments, + * with the receiver's background. + * + * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from + * the <code>gc</code> origin to the origin of the parent image background. This is useful + * to ensure proper alignment of the image background.</p> + * + * @param gc the gc where the rectangle is to be filled + * @param x the x coordinate of the rectangle to be filled + * @param y the y coordinate of the rectangle to be filled + * @param width the width of the rectangle to be filled + * @param height the height of the rectangle to be filled + * @param offsetX the image background x offset + * @param offsetY the image background y offset + * + * @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_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.6 + */ public void drawBackground (GC gc, int x, int y, int width, int height, int offsetX, int offsetY) { checkWidget (); if (gc == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -813,6 +840,64 @@ public void layout (Control [] changed) { layout (changed, SWT.NONE); } +/** + * Forces a lay out (that is, sets the size and location) of all widgets that + * are in the parent hierarchy of the changed control up to and including the + * receiver. + * <p> + * The parameter <code>flags</code> may be a combination of: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be laid out</dd> + * <dt><b>SWT.CHANGED</b></dt> + * <dd>the layout must flush its caches</dd> + * <dt><b>SWT.DEFER</b></dt> + * <dd>layout will be deferred</dd> + * </dl> + * </p> + * <p> + * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code> + * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the + * hierarchy must not rely on any information cached about the changed control or + * any of its ancestors. The layout may (potentially) optimize the + * work it is doing by assuming that none of the peers of the changed + * control have changed state since the last layout. + * If an ancestor does not have a layout, skip it. + * </p> + * <p> + * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code> + * indicates that the whole widget tree should be laid out. And the flag + * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached + * information for all controls that are laid out. + * </p> + * <p> + * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by + * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call + * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when + * appropriate (usually before the next event is handled). When this flag is set, + * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>. + * </p> + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> + * + * @param changed a control that has had a state change which requires a recalculation of its size + * @param flags the flags specifying how the layout should happen + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> + * <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</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.6 + */ public void layout (Control [] changed, int flags) { checkWidget (); if (changed != null) { 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 3582442b25..c06d8de1a1 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 @@ -36,7 +36,8 @@ import org.eclipse.swt.accessibility.Accessible; * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd> * <dt><b>Events:</b> * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter, - * MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd> + * MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move, + * Paint, Resize, Traverse</dd> * </dl> * </p><p> * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified. @@ -712,7 +713,7 @@ void destroyWidget () { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -754,7 +755,7 @@ public boolean dragDetect (Event event) { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1286,6 +1287,11 @@ int getMininumHeight () { * * @return the receiver's monitor * + * @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.0 */ public Monitor getMonitor () { @@ -4251,7 +4257,7 @@ boolean traverseMnemonic (char key) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -4289,7 +4295,7 @@ public boolean traverse (int traversal, Event event) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -4406,7 +4412,8 @@ boolean traverse (int traversal, char character, int keyCode, int keyLocation, i * traversal action. The argument should be one of the constants: * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, - * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>. + * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>, + * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>. * * @param traversal the type of traversal * @return true if the traversal succeeded 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 b92c9b377b..552e27fc96 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 @@ -91,7 +91,7 @@ import org.eclipse.swt.graphics.*; * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> - * <dd>Close, Dispose, Settings</dd> + * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd> * </dl> * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -2095,6 +2095,18 @@ public Image getSystemImage (int id) { return null; } +/** + * Returns the single instance of the system taskBar or null + * when there is no system taskBar available for the platform. + * + * @return the system taskBar or <code>null</code> + * + * @exception SWTException <ul> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public TaskBar getSystemTaskBar () { checkDevice (); return null; @@ -3820,6 +3832,8 @@ public static void setAppName (String name) { * Sets the application version to the argument. * * @param version the new app version + * + * @since 3.6 */ public static void setAppVersion (String version) { APP_VERSION = version; 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 1fcd663a9d..a74de593d8 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 @@ -674,6 +674,18 @@ void setFontStyle (Font font) { * include the mnemonic character and line delimiters. The only delimiter * the HREF attribute supports is the quotation mark ("). * </p> + * <p> + * Mnemonics are indicated by an '&' that causes the next + * character to be the mnemonic. The receiver can have a + * mnemonic in the text preceding each link. When the user presses a + * key sequence that matches the mnemonic, focus is assigned + * to the link that follows the text. Mnemonics in links and in + * the trailing text are ignored. On most platforms, + * the mnemonic appears underlined but may be emphasised in a + * platform specific manner. The mnemonic indicator character + * '&' can be escaped by doubling it in the string, causing + * a single '&' to be displayed. + * </p> * * @param string the new text * 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 427638f987..6611e9355b 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 @@ -184,7 +184,13 @@ public void addHelpListener (HelpListener listener) { * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid. * <code>widgetDefaultSelected</code> is not called. * </p> - * + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> + * * @param listener the listener which should be notified when the menu item is selected by the user * * @exception IllegalArgumentException <ul> 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 3b81bf9b20..b4eeb50836 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 @@ -370,8 +370,7 @@ public Point getSize () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -387,6 +386,19 @@ public int getThumb () { return OS.GetControlViewSize (handle); } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb relative to its parent. + * + * @return the thumb bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbBounds () { checkWidget(); int rgnHandle = OS.NewRgn (); @@ -402,6 +414,20 @@ public Rectangle getThumbBounds () { return result; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb track relative to its parent. This rectangle + * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}. + * + * @return the thumb track bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbTrackBounds () { checkWidget(); HIThemeTrackDrawInfo info = new HIThemeTrackDrawInfo(); @@ -741,10 +767,13 @@ public void setSelection (int value) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range 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 b94b1e0601..008dfe83e8 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 @@ -297,8 +297,7 @@ public int getSelection () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -459,10 +458,13 @@ public void setSelection (int value) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range 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 59a2729307..025be821e0 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 @@ -1049,11 +1049,11 @@ public void setIncrement (int value) { /** * Sets the maximum value that the receiver will allow. This new - * value will be ignored if it is not greater than the receiver's current + * value will be ignored if it is less than the receiver's current * minimum value. If the new maximum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new maximum, which must be greater than the current minimum + * @param value the new maximum, which must be greater than or equal to the current minimum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1071,11 +1071,11 @@ public void setMaximum (int value) { /** * Sets the minimum value that the receiver will allow. This new - * value will be ignored if it is not less than the receiver's + * value will be ignored if it is greater than the receiver's * current maximum value. If the new minimum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new minimum, which must be less than the current maximum + * @param value the new minimum, which must be less than or equal to the current maximum * * @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 55dca25922..e567770875 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 @@ -225,10 +225,10 @@ public Color getBackground (int index) { } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @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/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java index 6a8f4cec50..0a1f28245a 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 @@ -42,7 +42,7 @@ import org.eclipse.swt.graphics.*; * <dt><b>Styles:</b></dt> * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Verify</dd> + * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles MULTI and SINGLE may be specified, diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java index 9a8c9e5ab9..c2bd67b18e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java @@ -187,6 +187,12 @@ int actionProc (int theControl, int partCode) { * the event object detail field contains the value <code>SWT.ARROW</code>. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified when the control is selected by the user, * 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 12621663f6..9a2292bd29 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 @@ -375,10 +375,10 @@ public Color getBackground (int index) { } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1186,8 +1186,6 @@ public void setFont (int index, Font font) { * * @param color the new color (or null) * - * @since 2.0 - * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> 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 d96fa8254e..631dfb329b 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 @@ -665,6 +665,7 @@ int drawItemProc (int browser, int item, int property, int itemState, int theRec * <code>true</code> when sent the message <code>isDisposed()</code>. * Any internal connections between the widgets in the tree will * have been removed to facilitate garbage collection. + * This method does nothing if the widget is already disposed. * <p> * NOTE: This method is not called recursively on the descendants * of the receiver. This means that, widget implementers can not @@ -981,7 +982,7 @@ boolean isActive () { * <p> * This method gets the dispose state for the widget. * When a widget has been disposed, it is an error to - * invoke any other method using the widget. + * invoke any other method (except {@link #dispose()}) using the widget. * </p> * * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise @@ -1577,8 +1578,31 @@ protected void removeListener (int eventType, SWTEventListener handler) { } /** + * Marks the widget to be skinned. + * <p> + * The skin event is sent to the receiver's display when appropriate (usually before the next event + * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin + * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> + * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it + * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor + * while specifying the <code>SWT.ALL</code> flag. + * </p> + * <p> + * The parameter <code>flags</code> may be either: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be skinned</dd> + * <dt><b>SWT.NONE</b></dt> + * <dd>only the receiver should be skinned</dd> + * </dl> + * </p> + * @param flags the flags specifying how to reskin * - * @param flags + * @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.6 */ public void reskin (int flags) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java index 3b22aeaf86..175dd4843a 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Color.java @@ -246,7 +246,7 @@ void init(int red, int green, int blue) { * <p> * This method gets the dispose state for the color. * When a color has been disposed, it is an error to - * invoke any other method using the color. + * invoke any other method (except {@link #dispose()}) using the color. * * @return <code>true</code> when the color is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java index 5453a7c820..7f4ba3922d 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Cursor.java @@ -90,6 +90,10 @@ Cursor(Device device) { * <p> * You must dispose the cursor when it is no longer required. * </p> + * NOTE: + * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)} + * instead of using this constructor. This way you can avoid the + * overhead of disposing the Cursor resource. * * @param device the device on which to allocate the cursor * @param style the style of cursor to allocate @@ -426,7 +430,7 @@ public int hashCode () { * <p> * This method gets the dispose state for the cursor. * When a cursor has been disposed, it is an error to - * invoke any other method using the cursor. + * invoke any other method (except {@link #dispose()}) using the cursor. * * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java index c23e63777a..b1be7e9c16 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Font.java @@ -352,7 +352,7 @@ void init(String name, float height, int style, String nsName) { * <p> * This method gets the dispose state for the font. * When a font has been disposed, it is an error to - * invoke any other method using the font. + * invoke any other method (except {@link #dispose()}) using the font. * * @return <code>true</code> when the font is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java index 96a786d06e..602f6800a6 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/GC.java @@ -2959,7 +2959,7 @@ public boolean isClipped() { * <p> * This method gets the dispose state for the GC. * When a GC has been disposed, it is an error to - * invoke any other method using the GC. + * invoke any other method (except {@link #dispose()}) using the GC. * * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java index 1a5d6fb667..3a38788510 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java @@ -1159,7 +1159,7 @@ public int /*long*/ internal_new_GC (GCData data) { * </p> * * @param hDC the platform specific GC handle - * @param data the platform specific GC data + * @param data the platform specific GC data * * @noreference This method is not intended to be referenced by clients. */ @@ -1183,7 +1183,7 @@ public void internal_dispose_GC (int /*long*/ context, GCData data) { * <p> * This method gets the dispose state for the image. * When an image has been disposed, it is an error to - * invoke any other method using the image. + * invoke any other method (except {@link #dispose()}) using the image. * * @return <code>true</code> when the image is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java index 431a97a093..1de065c702 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Path.java @@ -708,7 +708,7 @@ void init(PathData data) { * <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. + * invoke any other method (except {@link #dispose()}) using the Path. * * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java index 1670e9ab87..4d72b20f4f 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Pattern.java @@ -195,7 +195,7 @@ void destroy() { * <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. + * invoke any other method (except {@link #dispose()}) using the Pattern. * * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java index 52be267307..68351dc271 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Region.java @@ -631,7 +631,7 @@ public boolean intersects(Rectangle rect) { * <p> * This method gets the dispose state for the region. * When a region has been disposed, it is an error to - * invoke any other method using the region. + * invoke any other method (except {@link #dispose()}) using the region. * * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/TextLayout.java index 3657f11714..ecf88c9b1e 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/TextLayout.java @@ -1341,6 +1341,17 @@ public int[] getSegments() { return segments; } +/** + * Returns the segments characters of the receiver. + * + * @return the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public char[] getSegmentsChars () { checkLayout(); return segmentsChars; @@ -1492,6 +1503,17 @@ public int getWidth () { return wrapWidth; } +/** +* Returns the receiver's wrap indent. +* +* @return the receiver's wrap indent +* +* @exception SWTException <ul> +* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> +* </ul> +* +* @since 3.6 +*/ public int getWrapIndent () { checkLayout(); return wrapIndent; @@ -1523,7 +1545,7 @@ void initClasses () { * <p> * This method gets the dispose state for the text layout. * When a text layout has been disposed, it is an error to - * invoke any other method using the text layout. + * invoke any other method (except {@link #dispose()}) using the text layout. * </p> * * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise @@ -1676,7 +1698,7 @@ public void setFont (Font font) { } /** - * Sets the indent of the receiver. This indent it applied of the first line of + * Sets the indent of the receiver. This indent is applied to the first line of * each paragraph. * * @param indent new indent @@ -1685,6 +1707,8 @@ public void setFont (Font font) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * + * @see #setWrapIndent(int) + * * @since 3.2 */ public void setIndent (int indent) { @@ -1701,6 +1725,20 @@ public void setIndent (int indent) { } } +/** + * Sets the wrap indent of the receiver. This indent is applied to all lines + * in the paragraph except the first line. + * + * @param wrapIndent new wrap indent + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setIndent(int) + * + * @since 3.6 + */ public void setWrapIndent (int wrapIndent) { checkLayout (); if (wrapIndent < 0) return; @@ -1769,7 +1807,7 @@ public void setOrientation(int orientation) { /** * Sets the offsets of the receiver's text segments. Text segments are used to - * override the default behaviour of the bidirectional algorithm. + * override the default behavior of the bidirectional algorithm. * Bidirectional reordering can happen within a text segment but not * between two adjacent segments. * <p> @@ -1778,12 +1816,18 @@ public void setOrientation(int orientation) { * always be zero and the last one should always be equals to length of * the text. * </p> + * <p> + * When segments characters are set, the segments are the offsets where + * the characters are inserted in the text. + * <p> * * @param segments the text segments offset * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @see #setSegmentsChars(char[]) */ public void setSegments(int[] segments) { checkLayout(); @@ -1807,6 +1851,23 @@ public void setSegments(int[] segments) { } } +/** + * Sets the characters to be used in the segments boundaries. The segments + * are set by calling <code>setSegments(int[])</code>. The application can + * use this API to insert Unicode Control Characters in the text to control + * the display of the text and bidi reordering. The characters are not + * accessible by any other API in <code>TextLayout</code>. + * + * @param segmentsChars the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setSegments(int[]) + * + * @since 3.6 + */ public void setSegmentsChars(char[] segmentsChars) { checkLayout(); if (this.segmentsChars == null && segmentsChars == null) return; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java index 6fdb13de11..dc6c63e9a2 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Transform.java @@ -243,7 +243,7 @@ public void invert() { * <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. + * invoke any other method (except {@link #dispose()}) using the Transform. * * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java index 7c2f8abab2..40d56b0bc2 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Button.java @@ -104,6 +104,12 @@ public Button (Composite parent, int style) { * <code>widgetSelected</code> is called when the control is selected by the user. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java index ea50a2e451..3312be1507 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Canvas.java @@ -278,7 +278,7 @@ void reskinChildren (int flags) { * the source area to the destination and then causing the area * of the source which is not covered by the destination to * be repainted. Children that intersect the rectangle are - * optionally moved during the operation. In addition, outstanding + * optionally moved during the operation. In addition, all outstanding * paint events are flushed before the source area is copied to * ensure that the contents of the canvas are drawn correctly. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java index c03cfcb60e..56f58424fa 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Combo.java @@ -41,7 +41,7 @@ import org.eclipse.swt.internal.cocoa.*; * <dt><b>Styles:</b></dt> * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Selection, Verify</dd> + * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java index 1d8527e434..3d19efb529 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Composite.java @@ -295,6 +295,33 @@ void createHandle () { } } +/** + * Fills the interior of the rectangle specified by the arguments, + * with the receiver's background. + * + * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from + * the <code>gc</code> origin to the origin of the parent image background. This is useful + * to ensure proper alignment of the image background.</p> + * + * @param gc the gc where the rectangle is to be filled + * @param x the x coordinate of the rectangle to be filled + * @param y the y coordinate of the rectangle to be filled + * @param width the width of the rectangle to be filled + * @param height the height of the rectangle to be filled + * @param offsetX the image background x offset + * @param offsetY the image background y offset + * + * @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_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.6 + */ public void drawBackground(GC gc, int x, int y, int width, int height, int offsetX, int offsetY) { checkWidget (); if (gc == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -710,6 +737,64 @@ public void layout (Control [] changed) { layout (changed, SWT.NONE); } +/** + * Forces a lay out (that is, sets the size and location) of all widgets that + * are in the parent hierarchy of the changed control up to and including the + * receiver. + * <p> + * The parameter <code>flags</code> may be a combination of: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be laid out</dd> + * <dt><b>SWT.CHANGED</b></dt> + * <dd>the layout must flush its caches</dd> + * <dt><b>SWT.DEFER</b></dt> + * <dd>layout will be deferred</dd> + * </dl> + * </p> + * <p> + * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code> + * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the + * hierarchy must not rely on any information cached about the changed control or + * any of its ancestors. The layout may (potentially) optimize the + * work it is doing by assuming that none of the peers of the changed + * control have changed state since the last layout. + * If an ancestor does not have a layout, skip it. + * </p> + * <p> + * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code> + * indicates that the whole widget tree should be laid out. And the flag + * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached + * information for all controls that are laid out. + * </p> + * <p> + * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by + * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call + * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when + * appropriate (usually before the next event is handled). When this flag is set, + * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>. + * </p> + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> + * + * @param changed a control that has had a state change which requires a recalculation of its size + * @param flags the flags specifying how the layout should happen + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> + * <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</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.6 + */ public void layout (Control [] changed, int flags) { checkWidget (); if (changed != null) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java index 4a13222355..a6f811461b 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java @@ -26,7 +26,8 @@ import org.eclipse.swt.internal.cocoa.*; * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd> * <dt><b>Events:</b> * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter, - * MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd> + * MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move, + * Paint, Resize, Traverse</dd> * </dl> * </p><p> * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified. @@ -965,7 +966,7 @@ void doCommandBySelector (int /*long*/ id, int /*long*/ sel, int /*long*/ select * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1007,7 +1008,7 @@ public boolean dragDetect (Event event) { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1559,6 +1560,11 @@ int getMininumHeight () { * * @return the receiver's monitor * + * @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.0 */ public Monitor getMonitor () { @@ -4054,7 +4060,7 @@ boolean traverseMnemonic (char key) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -4092,7 +4098,7 @@ public boolean traverse (int traversal, Event event) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -4209,7 +4215,8 @@ boolean traverse (int traversal, char character, int keyCode, int keyLocation, i * traversal action. The argument should be one of the constants: * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, - * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>. + * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>, + * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>. * * @param traversal the type of traversal * @return true if the traversal succeeded diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java index a1d4eda1c8..8daac5cad8 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Display.java @@ -78,7 +78,7 @@ import org.eclipse.swt.internal.cocoa.*; * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> - * <dd>Close, Dispose, Settings</dd> + * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd> * </dl> * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -1874,6 +1874,18 @@ public Tray getSystemTray () { return tray = new Tray (this, SWT.NONE); } +/** + * Returns the single instance of the system taskBar or null + * when there is no system taskBar available for the platform. + * + * @return the system taskBar or <code>null</code> + * + * @exception SWTException <ul> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public TaskBar getSystemTaskBar () { checkDevice (); if (taskBar != null) return taskBar; @@ -3832,6 +3844,8 @@ public static void setAppName (String name) { * Sets the application version to the argument. * * @param version the new app version + * + * @since 3.6 */ public static void setAppVersion (String version) { APP_VERSION = version; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Link.java index d702ad1739..6f46287341 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Link.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Link.java @@ -629,6 +629,18 @@ void setOrientation () { * include the mnemonic character and line delimiters. The only delimiter * the HREF attribute supports is the quotation mark ("). * </p> + * <p> + * Mnemonics are indicated by an '&' that causes the next + * character to be the mnemonic. The receiver can have a + * mnemonic in the text preceding each link. When the user presses a + * key sequence that matches the mnemonic, focus is assigned + * to the link that follows the text. Mnemonics in links and in + * the trailing text are ignored. On most platforms, + * the mnemonic appears underlined but may be emphasised in a + * platform specific manner. The mnemonic indicator character + * '&' can be escaped by doubling it in the string, causing + * a single '&' to be displayed. + * </p> * * @param string the new text * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/MenuItem.java index 2dafb6776c..4f5fbbc397 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/MenuItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/MenuItem.java @@ -184,7 +184,13 @@ public void addHelpListener (HelpListener listener) { * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid. * <code>widgetDefaultSelected</code> is not called. * </p> - * + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> + * * @param listener the listener which should be notified when the menu item is selected by the user * * @exception IllegalArgumentException <ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ScrollBar.java index f92d6fe6e8..2b287f8bb2 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ScrollBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ScrollBar.java @@ -284,8 +284,7 @@ public Point getSize () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -301,6 +300,19 @@ public int getThumb () { return thumb; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb relative to its parent. + * + * @return the thumb bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbBounds () { checkWidget(); NSRect rect = view.rectForPart(OS.NSScrollerKnob); @@ -308,6 +320,20 @@ public Rectangle getThumbBounds () { return new Rectangle((int)rect.x, (int)rect.y, (int)rect.width, (int)rect.height); } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb track relative to its parent. This rectangle + * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}. + * + * @return the thumb track bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbTrackBounds () { checkWidget(); NSRect rect = view.rectForPart(OS.NSScrollerKnobSlot); @@ -616,10 +642,13 @@ public void setSelection (int value) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Slider.java index f62d24c951..502957e5b1 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Slider.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Slider.java @@ -283,8 +283,7 @@ public int getSelection () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -475,10 +474,13 @@ void updateBar (int selection, int minimum, int maximum, int thumb) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Spinner.java index a436e58f48..cbf4d1d5b3 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Spinner.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Spinner.java @@ -791,11 +791,11 @@ public void setIncrement (int value) { /** * Sets the maximum value that the receiver will allow. This new - * value will be ignored if it is not greater than the receiver's current + * value will be ignored if it is less than the receiver's current * minimum value. If the new maximum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new maximum, which must be greater than the current minimum + * @param value the new maximum, which must be greater than or equal to the current minimum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -813,11 +813,11 @@ public void setMaximum (int value) { /** * Sets the minimum value that the receiver will allow. This new - * value will be ignored if it is not less than the receiver's + * value will be ignored if it is greater than the receiver's * current maximum value. If the new minimum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new minimum, which must be less than the current maximum + * @param value the new minimum, which must be less than or equal to the current maximum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java index 91095b8629..fd993ba6da 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TableItem.java @@ -250,10 +250,10 @@ public Color getBackground (int index) { } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskBar.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskBar.java index ad1a61a64a..9e425f5d89 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskBar.java @@ -109,6 +109,19 @@ public int getItemCount () { return itemCount; } +/** + * Returns the <code>TaskItem</code> for the given <code>Shell</code> or the <code>TaskItem</code> + * for the application if the <code>Shell</code> parameter is <code>null</code>. + * If the requested item is not supported by the platform it returns <code>null</code>. + * + * @param shell the shell for which the task item is requested, or null to request the application item + * @return the task item for the given shell or the application + * + * @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 TaskItem getItem (Shell shell) { checkWidget (); for (int i = 0; i < itemCount; i++) { @@ -128,7 +141,7 @@ public TaskItem getItem (Shell shell) { } /** - * Returns an array of <code>TaskBarItem</code>s which are the items + * Returns an array of <code>TaskItem</code>s which are the items * in the receiver. * <p> * Note: This is not the actual structure used by the receiver diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskItem.java index 128e006af4..921bb7263f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TaskItem.java @@ -16,7 +16,7 @@ import org.eclipse.swt.graphics.*; import org.eclipse.swt.internal.cocoa.*; /** - * Instances of this class represent a taskbar item. + * Instances of this class represent a task item. * * <dl> * <dt><b>Styles:</b></dt> @@ -96,16 +96,49 @@ void destroyWidget () { releaseHandle (); } +/** + * Returns the receiver's pop up menu if it has one, or null + * if it does not. + * + * @return the receiver's menu + * + * @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 Menu getMenu () { checkWidget (); return menu; } +/** + * Returns the receiver's overlay image if it has one, or null + * if it does not. + * + * @return the receiver's overlay image + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public Image getOverlayImage () { checkWidget (); return overlayImage; } +/** + * Returns the receiver's overlay text, which will be an empty + * string if it has never been set. + * + * @return the receiver's overlay text + * + * @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 String getOverlayText () { checkWidget (); return overlayText; @@ -127,11 +160,31 @@ public TaskBar getParent () { return parent; } +/** + * Returns the receiver's progress. + * + * @return the receiver's progress + * + * @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 getProgress () { checkWidget (); return progress; } +/** + * Returns the receiver's progress state. + * + * @return the receiver's progress state + * + * @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 getProgressState () { checkWidget (); return progressState; @@ -151,6 +204,37 @@ void releaseWidget () { shell = null; } +/** + * Sets the receiver's pop up menu to the argument. The way the menu is + * shown is platform specific. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return the NULL.</p> + * + * <p> + * For better cross platform support, the application code should + * set this feature on the <code>TaskItem</code> for application.<br> + * On Windows, this feature will only work on RCP applications.</p> + * + * <p> + * The menu should be fully created before this method is called. + * Dynamic changes to the menu after the method is called will not be reflected + * in the native menu.</p> + * + * @param menu the new pop up menu + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_MENU_NOT_POP_UP - the menu is not a pop up menu</li> + * <li>ERROR_INVALID_ARGUMENT - if the menu 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> + */ public void setMenu (Menu menu) { checkWidget (); if (menu != null) { @@ -162,6 +246,33 @@ public void setMenu (Menu menu) { this.menu = menu; } +/** + * Sets the receiver's overlay image, which may be null + * indicating that no image should be displayed. The bounds + * for the overlay image is determined by the platform and in + * general it should be a small image. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return the NULL.</p> + * + * <p> + * For better cross platform support, the application code should + * first try to set this feature on the <code>TaskItem</code> for the + * main shell then on the <code>TaskItem</code> for the application.</p> + * + * @param overlayImage the new overlay image (may be null) + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the overlayImage 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> + */ public void setOverlayImage (Image image) { checkWidget (); if (image != null && image.isDisposed ()) error (SWT.ERROR_INVALID_ARGUMENT); @@ -170,6 +281,32 @@ public void setOverlayImage (Image image) { updateImage (); } +/** + * Sets the receiver's overlay text. The space available to display the + * overlay text is platform dependent and in general it should be no longer + * than a few characters. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return an empty string.</p> + * + * <p> + * For better cross platform support, the application code should + * first try to set this feature on the <code>TaskItem</code> for the + * main shell then on the <code>TaskItem</code> for the application.</p> + * + * @param overlayText the new overlay text + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the overlayText 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> + */ public void setOverlayText (String string) { checkWidget (); if (string == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -178,6 +315,31 @@ public void setOverlayText (String string) { updateImage (); } +/** + * Sets the receiver's progress, the progress represents a percentage and + * should be in range from 0 to 100. The progress is only shown when the progress + * state is different than <code>SWT#DEFAULT</code>. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return zero.</p> + * + * <p> + * For better cross platform support, the application code should + * first try to set this feature on the <code>TaskItem</code> for the + * main shell then on the <code>TaskItem</code> for the application.</p> + * + * @param progress the new progress + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * #see {@link #setProgressState(int)} + */ public void setProgress (int progress) { checkWidget (); progress = Math.max (0, Math.min (progress, PROGRESS_MAX)); @@ -186,6 +348,41 @@ public void setProgress (int progress) { updateImage (); } +/** + * Sets the receiver's progress state, the state can be one of + * the following: + * <p><ul> + * <li>{@link SWT#DEFAULT}</li> + * <li>{@link SWT#NORMAL}</li> + * <li>{@link SWT#PAUSED}</li> + * <li>{@link SWT#ERROR}</li> + * <li>{@link SWT#INDETERMINATE}</li> + * </ul></p> + * + * The percentage of progress shown by the states <code>SWT#NORMAL</code>, <code>SWT#PAUSED</code>, + * <code>SWT#ERROR</code> is set with <code>setProgress()</code>. <br> + * The state <code>SWT#DEFAULT</code> indicates that no progress should be shown. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return <code>SWT#DEFAULT</code>.</p> + * + * <p> + * For better cross platform support, the application code should + * first try to set this feature on the <code>TaskItem</code> for the + * main shell then on the <code>TaskItem</code> for the application.</p> + * + * @param progressState the new progress state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * #see {@link #setProgress(int)} + */ public void setProgressState (int progressState) { checkWidget (); if (this.progressState == progressState) return; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java index 5ad98300ca..ca72a9bca5 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Text.java @@ -30,7 +30,7 @@ import org.eclipse.swt.internal.cocoa.*; * <dt><b>Styles:</b></dt> * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Verify</dd> + * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles MULTI and SINGLE may be specified, diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java index e76a5a53fc..c2698365b7 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/ToolItem.java @@ -241,6 +241,12 @@ boolean accessibilityIsIgnored(int /*long*/ id, int /*long*/ sel) { * the event object detail field contains the value <code>SWT.ARROW</code>. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified when the control is selected by the user, * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java index eaf464d5e1..7f53aea0c4 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/TreeItem.java @@ -422,10 +422,10 @@ public Color getBackground (int index) { } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1230,8 +1230,6 @@ public void setFont (int index, Font font) { * * @param color the new color (or null) * - * @since 2.0 - * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Widget.java index 9a48de1d7b..b5f2dc7b49 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Widget.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Widget.java @@ -325,8 +325,31 @@ void becomeKeyWindow (int /*long*/ id, int /*long*/ sel) { } /** + * Marks the widget to be skinned. + * <p> + * The skin event is sent to the receiver's display when appropriate (usually before the next event + * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin + * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> + * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it + * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor + * while specifying the <code>SWT.ALL</code> flag. + * </p> + * <p> + * The parameter <code>flags</code> may be either: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be skinned</dd> + * <dt><b>SWT.NONE</b></dt> + * <dd>only the receiver should be skinned</dd> + * </dl> + * </p> + * @param flags the flags specifying how to reskin * - * @param flags + * @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.6 */ public void reskin (int flags) { @@ -575,6 +598,7 @@ void destroyWidget () { * <code>true</code> when sent the message <code>isDisposed()</code>. * Any internal connections between the widgets in the tree will * have been removed to facilitate garbage collection. + * This method does nothing if the widget is already disposed. * <p> * NOTE: This method is not called recursively on the descendants * of the receiver. This means that, widget implementers can not @@ -928,7 +952,7 @@ boolean isActive () { * <p> * This method gets the dispose state for the widget. * When a widget has been disposed, it is an error to - * invoke any other method using the widget. + * invoke any other method (except {@link #dispose()}) using the widget. * </p> * * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise 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 f696a8cec8..b102d6f774 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 @@ -443,7 +443,7 @@ void init(PathData data) { * <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. + * invoke any other method (except {@link #dispose()}) using the Path. * * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise */ 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 44eb166b21..738287d944 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 @@ -172,7 +172,7 @@ void destroy() { * <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. + * invoke any other method (except {@link #dispose()}) using the Pattern. * * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise */ 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 ea89969116..79f89ac4ef 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 @@ -199,7 +199,7 @@ public void invert() { * <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. + * invoke any other method (except {@link #dispose()}) using the Transform. * * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java index 329a02df7a..56a5e0a549 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskBar.java @@ -108,13 +108,26 @@ public int getItemCount () { return itemCount; } +/** + * Returns the <code>TaskItem</code> for the given <code>Shell</code> or the <code>TaskItem</code> + * for the application if the <code>Shell</code> parameter is <code>null</code>. + * If the requested item is not supported by the platform it returns <code>null</code>. + * + * @param shell the shell for which the task item is requested, or null to request the application item + * @return the task item for the given shell or the application + * + * @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 TaskItem getItem (Shell shell) { checkWidget (); return null; } /** - * Returns an array of <code>TaskBarItem</code>s which are the items + * Returns an array of <code>TaskItem</code>s which are the items * in the receiver. * <p> * Note: This is not the actual structure used by the receiver diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java index 92fabc18d2..4c76d8805c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/taskbar/org/eclipse/swt/widgets/TaskItem.java @@ -15,7 +15,7 @@ import org.eclipse.swt.*; import org.eclipse.swt.graphics.*; /** - * Instances of this class represent a taskbar item. + * Instances of this class represent a task item. * * <dl> * <dt><b>Styles:</b></dt> @@ -84,16 +84,49 @@ void destroyWidget () { releaseHandle (); } +/** + * Returns the receiver's pop up menu if it has one, or null + * if it does not. + * + * @return the receiver's menu + * + * @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 Menu getMenu () { checkWidget (); return menu; } +/** + * Returns the receiver's overlay image if it has one, or null + * if it does not. + * + * @return the receiver's overlay image + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public Image getOverlayImage () { checkWidget(); return overlayImage; } +/** + * Returns the receiver's overlay text, which will be an empty + * string if it has never been set. + * + * @return the receiver's overlay text + * + * @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 String getOverlayText () { checkWidget(); return overlayText; @@ -115,11 +148,31 @@ public TaskBar getParent () { return parent; } +/** + * Returns the receiver's progress. + * + * @return the receiver's progress + * + * @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 getProgress () { checkWidget (); return progress; } +/** + * Returns the receiver's progress state. + * + * @return the receiver's progress state + * + * @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 getProgressState () { checkWidget (); return progressState; @@ -136,6 +189,37 @@ void releaseWidget () { overlayText = null; } +/** + * Sets the receiver's pop up menu to the argument. The way the menu is + * shown is platform specific. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return the NULL.</p> + * + * <p> + * For better cross platform support, the application code should + * set this feature on the <code>TaskItem</code> for application.<br> + * On Windows, this feature will only work on RCP applications.</p> + * + * <p> + * The menu should be fully created before this method is called. + * Dynamic changes to the menu after the method is called will not be reflected + * in the native menu.</p> + * + * @param menu the new pop up menu + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_MENU_NOT_POP_UP - the menu is not a pop up menu</li> + * <li>ERROR_INVALID_ARGUMENT - if the menu 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> + */ public void setMenu (Menu menu) { checkWidget (); if (menu != null) { @@ -148,12 +232,26 @@ public void setMenu (Menu menu) { } /** - * Sets the receiver's overlay image. + * Sets the receiver's overlay image, which may be null + * indicating that no image should be displayed. The bounds + * for the overlay image is determined by the platform and in + * general it should be a small image. * - * @param overlayImage the new overlay image + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return the NULL.</p> + * + * <p> + * For better cross platform support, the application code should + * first try to set this feature on the <code>TaskItem</code> for the + * main shell then on the <code>TaskItem</code> for the application.</p> + * + * @param overlayImage the new overlay image (may be null) * * @exception IllegalArgumentException <ul> - * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li> + * <li>ERROR_INVALID_ARGUMENT - if the overlayImage has been disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -166,18 +264,104 @@ public void setOverlayImage (Image overlayImage) { this.overlayImage = overlayImage; } +/** + * Sets the receiver's overlay text. The space available to display the + * overlay text is platform dependent and in general it should be no longer + * than a few characters. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return an empty string.</p> + * + * <p> + * For better cross platform support, the application code should + * first try to set this feature on the <code>TaskItem</code> for the + * main shell then on the <code>TaskItem</code> for the application.</p> + * + * @param overlayText the new overlay text + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the overlayText 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> + */ public void setOverlayText (String overlayText) { checkWidget (); if (overlayText == null) error (SWT.ERROR_NULL_ARGUMENT); this.overlayText = overlayText; } +/** + * Sets the receiver's progress state, the state can be one of + * the following: + * <p><ul> + * <li>{@link SWT#DEFAULT}</li> + * <li>{@link SWT#NORMAL}</li> + * <li>{@link SWT#PAUSED}</li> + * <li>{@link SWT#ERROR}</li> + * <li>{@link SWT#INDETERMINATE}</li> + * </ul></p> + * + * The percentage of progress shown by the states <code>SWT#NORMAL</code>, <code>SWT#PAUSED</code>, + * <code>SWT#ERROR</code> is set with <code>setProgress()</code>. <br> + * The state <code>SWT#DEFAULT</code> indicates that no progress should be shown. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return <code>SWT#DEFAULT</code>.</p> + * + * <p> + * For better cross platform support, the application code should + * first try to set this feature on the <code>TaskItem</code> for the + * main shell then on the <code>TaskItem</code> for the application.</p> + * + * @param progressState the new progress state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * #see {@link #setProgress(int)} + */ public void setProgressState (int progressState) { checkWidget (); if (this.progressState == progressState) return; this.progressState = progressState; } +/** + * Sets the receiver's progress, the progress represents a percentage and + * should be in range from 0 to 100. The progress is only shown when the progress + * state is different than <code>SWT#DEFAULT</code>. + * + * <p> + * This feature might not be available for the receiver on all + * platforms. The application code can check if it is supported + * by calling the respective get method. When the feature is not + * available, the get method will always return zero.</p> + * + * <p> + * For better cross platform support, the application code should + * first try to set this feature on the <code>TaskItem</code> for the + * main shell then on the <code>TaskItem</code> for the application.</p> + * + * @param progress the new progress + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * #see {@link #setProgressState(int)} + */ public void setProgress (int progress) { checkWidget (); progress = Math.max(0, Math.min(progress, PROGRESS_MAX)); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java index 06f73fc22a..a0f8fbcea6 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/emulated/textlayout/org/eclipse/swt/graphics/TextLayout.java @@ -1157,6 +1157,17 @@ public int[] getSegments() { return segments; } +/** + * Returns the segments characters of the receiver. + * + * @return the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public char[] getSegmentsChars () { checkLayout(); return segmentsChars; @@ -1261,6 +1272,17 @@ public int getWidth () { return wrapWidth; } +/** +* Returns the receiver's wrap indent. +* +* @return the receiver's wrap indent +* +* @exception SWTException <ul> +* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> +* </ul> +* +* @since 3.6 +*/ public int getWrapIndent () { checkLayout(); return wrapIndent; @@ -1272,7 +1294,7 @@ public int getWrapIndent () { * <p> * This method gets the dispose state for the text layout. * When a text layout has been disposed, it is an error to - * invoke any other method using the text layout. + * invoke any other method (except {@link #dispose()}) using the text layout. * </p> * * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise @@ -1484,7 +1506,7 @@ public void setFont (Font font) { } /** - * Sets the indent of the receiver. This indent it applied of the first line of + * Sets the indent of the receiver. This indent is applied to the first line of * each paragraph. * * @param indent new indent @@ -1493,6 +1515,8 @@ public void setFont (Font font) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * + * @see #setWrapIndent(int) + * * @since 3.2 */ public void setIndent (int indent) { @@ -1564,7 +1588,7 @@ public void setSpacing (int spacing) { /** * Sets the offsets of the receiver's text segments. Text segments are used to - * override the default behaviour of the bidirectional algorithm. + * override the default behavior of the bidirectional algorithm. * Bidirectional reordering can happen within a text segment but not * between two adjacent segments. * <p> @@ -1573,12 +1597,18 @@ public void setSpacing (int spacing) { * always be zero and the last one should always be equals to length of * the text. * </p> + * <p> + * When segments characters are set, the segments are the offsets where + * the characters are inserted in the text. + * <p> * * @param segments the text segments offset * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @see #setSegmentsChars(char[]) */ public void setSegments(int[] segments) { checkLayout(); @@ -1596,6 +1626,23 @@ public void setSegments(int[] segments) { this.segments = segments; } +/** + * Sets the characters to be used in the segments boundaries. The segments + * are set by calling <code>setSegments(int[])</code>. The application can + * use this API to insert Unicode Control Characters in the text to control + * the display of the text and bidi reordering. The characters are not + * accessible by any other API in <code>TextLayout</code>. + * + * @param segmentsChars the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setSegments(int[]) + * + * @since 3.6 + */ public void setSegmentsChars(char[] segmentsChars) { checkLayout(); if (this.segmentsChars == null && segmentsChars == null) return; @@ -1776,6 +1823,20 @@ public void setWidth (int width) { this.wrapWidth = width; } +/** + * Sets the wrap indent of the receiver. This indent is applied to all lines + * in the paragraph except the first line. + * + * @param wrapIndent new wrap indent + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setIndent(int) + * + * @since 3.6 + */ public void setWrapIndent (int wrapIndent) { checkLayout(); if (wrapIndent < 0) return; 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 fc37502654..abdf2bccaa 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 @@ -428,10 +428,10 @@ public Color getBackground (int columnIndex) { return cellBackgrounds [columnIndex]; } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @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/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/emulated/treetable/org/eclipse/swt/widgets/TreeItem.java index 6d2a6705e7..966b66986e 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 @@ -843,10 +843,10 @@ public Color getBackground (int columnIndex) { return cellBackgrounds [columnIndex]; } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2495,8 +2495,6 @@ public void setFont (int columnIndex, Font font) { * * @param color the new color (or null) * - * @since 2.0 - * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> 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 5e671bc180..7a57f02670 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 @@ -269,7 +269,7 @@ void init(int red, int green, int blue) { * <p> * This method gets the dispose state for the color. * When a color has been disposed, it is an error to - * invoke any other method using the color. + * invoke any other method (except {@link #dispose()}) using the color. * * @return <code>true</code> when the color is disposed and <code>false</code> otherwise */ 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 9f46a49441..96dfe32955 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 @@ -92,6 +92,10 @@ Cursor (Device device) { * <p> * You must dispose the cursor when it is no longer required. * </p> + * NOTE: + * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)} + * instead of using this constructor. This way you can avoid the + * overhead of disposing the Cursor resource. * * @param device the device on which to allocate the cursor * @param style the style of cursor to allocate @@ -507,7 +511,7 @@ public int hashCode() { * <p> * This method gets the dispose state for the cursor. * When a cursor has been disposed, it is an error to - * invoke any other method using the cursor. + * invoke any other method (except {@link #dispose()}) using the cursor. * * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise */ 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 97236c4406..2619dbb0d7 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 @@ -268,7 +268,7 @@ void init(String name, float height, int style, byte[] fontString) { * <p> * This method gets the dispose state for the font. * When a font has been disposed, it is an error to - * invoke any other method using the font. + * invoke any other method (except {@link #dispose()}) using the font. * * @return <code>true</code> when the font is disposed and <code>false</code> otherwise */ 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 2393461310..ac76e2c42e 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 @@ -2892,7 +2892,7 @@ public boolean isClipped() { * <p> * This method gets the dispose state for the GC. * When a GC has been disposed, it is an error to - * invoke any other method using the GC. + * invoke any other method (except {@link #dispose()}) using the GC. * * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise */ 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 9a0e5e1aa0..a2785ceb3f 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 @@ -1097,7 +1097,7 @@ public int /*long*/ internal_new_GC (GCData data) { * </p> * * @param hDC the platform specific GC handle - * @param data the platform specific GC data + * @param data the platform specific GC data * * @noreference This method is not intended to be referenced by clients. */ @@ -1111,7 +1111,7 @@ public void internal_dispose_GC (int /*long*/ gdkGC, GCData data) { * <p> * This method gets the dispose state for the image. * When an image has been disposed, it is an error to - * invoke any other method using the image. + * invoke any other method (except {@link #dispose()}) using the image. * * @return <code>true</code> when the image is disposed and <code>false</code> otherwise */ 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 0d7e5ce58f..a2b8995ec7 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 @@ -414,7 +414,7 @@ public boolean intersects(Rectangle rect) { * <p> * This method gets the dispose state for the region. * When a region has been disposed, it is an error to - * invoke any other method using the region. + * invoke any other method (except {@link #dispose()}) using the region. * * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java index c90cce286e..372b628ae6 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java @@ -1543,6 +1543,17 @@ public int[] getSegments() { return segments; } +/** + * Returns the segments characters of the receiver. + * + * @return the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public char[] getSegmentsChars () { checkLayout(); return segmentsChars; @@ -1694,6 +1705,17 @@ public int getWidth () { return wrapWidth; } +/** +* Returns the receiver's wrap indent. +* +* @return the receiver's wrap indent +* +* @exception SWTException <ul> +* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> +* </ul> +* +* @since 3.6 +*/ public int getWrapIndent () { checkLayout (); return wrapIndent; @@ -1705,7 +1727,7 @@ public int getWrapIndent () { * <p> * This method gets the dispose state for the text layout. * When a text layout has been disposed, it is an error to - * invoke any other method using the text layout. + * invoke any other method (except {@link #dispose()}) using the text layout. * </p> * * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise @@ -1832,7 +1854,7 @@ public void setFont (Font font) { } /** - * Sets the indent of the receiver. This indent it applied of the first line of + * Sets the indent of the receiver. This indent is applied to the first line of * each paragraph. * * @param indent new indent @@ -1841,6 +1863,8 @@ public void setFont (Font font) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * + * @see #setWrapIndent(int) + * * @since 3.2 */ public void setIndent (int indent) { @@ -1917,7 +1941,7 @@ public void setSpacing (int spacing) { /** * Sets the offsets of the receiver's text segments. Text segments are used to - * override the default behaviour of the bidirectional algorithm. + * override the default behavior of the bidirectional algorithm. * Bidirectional reordering can happen within a text segment but not * between two adjacent segments. * <p> @@ -1926,12 +1950,18 @@ public void setSpacing (int spacing) { * always be zero and the last one should always be equals to length of * the text. * </p> + * <p> + * When segments characters are set, the segments are the offsets where + * the characters are inserted in the text. + * <p> * * @param segments the text segments offset * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @see #setSegmentsChars(char[]) */ public void setSegments(int[] segments) { checkLayout(); @@ -1949,6 +1979,23 @@ public void setSegments(int[] segments) { this.segments = segments; } +/** + * Sets the characters to be used in the segments boundaries. The segments + * are set by calling <code>setSegments(int[])</code>. The application can + * use this API to insert Unicode Control Characters in the text to control + * the display of the text and bidi reordering. The characters are not + * accessible by any other API in <code>TextLayout</code>. + * + * @param segmentsChars the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setSegments(int[]) + * + * @since 3.6 + */ public void setSegmentsChars(char[] segmentsChars) { checkLayout(); if (this.segmentsChars == null && segmentsChars == null) return; @@ -2183,6 +2230,20 @@ void setWidth () { } } +/** + * Sets the wrap indent of the receiver. This indent is applied to all lines + * in the paragraph except the first line. + * + * @param wrapIndent new wrap indent + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setIndent(int) + * + * @since 3.6 + */ public void setWrapIndent (int wrapIndent) { checkLayout(); if (wrapIndent < 0) return; 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 decf696388..f16b2d4038 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 @@ -118,6 +118,12 @@ static int checkStyle (int style) { * <code>widgetSelected</code> is called when the control is selected by the user. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified * 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 405a09a611..3fd382caa5 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 @@ -219,7 +219,7 @@ void reskinChildren (int flags) { * the source area to the destination and then causing the area * of the source which is not covered by the destination to * be repainted. Children that intersect the rectangle are - * optionally moved during the operation. In addition, outstanding + * optionally moved during the operation. In addition, all outstanding * paint events are flushed before the source area is copied to * ensure that the contents of the canvas are drawn correctly. * 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 65220987b8..d692fc38df 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 @@ -42,7 +42,7 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Selection, Verify</dd> + * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. 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 10f99d3988..483032f3b0 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 @@ -330,6 +330,33 @@ void deregister () { if (socketHandle != 0) display.removeWidget (socketHandle); } +/** + * Fills the interior of the rectangle specified by the arguments, + * with the receiver's background. + * + * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from + * the <code>gc</code> origin to the origin of the parent image background. This is useful + * to ensure proper alignment of the image background.</p> + * + * @param gc the gc where the rectangle is to be filled + * @param x the x coordinate of the rectangle to be filled + * @param y the y coordinate of the rectangle to be filled + * @param width the width of the rectangle to be filled + * @param height the height of the rectangle to be filled + * @param offsetX the image background x offset + * @param offsetY the image background y offset + * + * @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_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.6 + */ public void drawBackground (GC gc, int x, int y, int width, int height, int offsetX, int offsetY) { checkWidget (); if (gc == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -958,6 +985,64 @@ public void layout (Control [] changed) { layout (changed, SWT.NONE); } +/** + * Forces a lay out (that is, sets the size and location) of all widgets that + * are in the parent hierarchy of the changed control up to and including the + * receiver. + * <p> + * The parameter <code>flags</code> may be a combination of: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be laid out</dd> + * <dt><b>SWT.CHANGED</b></dt> + * <dd>the layout must flush its caches</dd> + * <dt><b>SWT.DEFER</b></dt> + * <dd>layout will be deferred</dd> + * </dl> + * </p> + * <p> + * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code> + * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the + * hierarchy must not rely on any information cached about the changed control or + * any of its ancestors. The layout may (potentially) optimize the + * work it is doing by assuming that none of the peers of the changed + * control have changed state since the last layout. + * If an ancestor does not have a layout, skip it. + * </p> + * <p> + * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code> + * indicates that the whole widget tree should be laid out. And the flag + * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached + * information for all controls that are laid out. + * </p> + * <p> + * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by + * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call + * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when + * appropriate (usually before the next event is handled). When this flag is set, + * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>. + * </p> + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> + * + * @param changed a control that has had a state change which requires a recalculation of its size + * @param flags the flags specifying how the layout should happen + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> + * <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</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.6 + */ public void layout (Control [] changed, int flags) { checkWidget (); if (changed != null) { 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 c71351da74..ae09ff2f67 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 @@ -28,7 +28,8 @@ import org.eclipse.swt.internal.gtk.*; * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd> * <dt><b>Events:</b> * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter, - * MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd> + * MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move, + * Paint, Resize, Traverse</dd> * </dl> * </p><p> * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified. @@ -1964,7 +1965,7 @@ public void removeTraverseListener(TraverseListener listener) { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2006,7 +2007,7 @@ public boolean dragDetect (Event event) { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2421,6 +2422,11 @@ public Menu getMenu () { * * @return the receiver's monitor * + * @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.0 */ public Monitor getMonitor () { @@ -3039,7 +3045,7 @@ int /*long*/ imHandle () { * </p> * * @param hDC the platform specific GC handle - * @param data the platform specific GC data + * @param data the platform specific GC data * * @noreference This method is not intended to be referenced by clients. */ @@ -4327,7 +4333,8 @@ void sort (int [] items) { * traversal action. The argument should be one of the constants: * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, - * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>. + * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>, + * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>. * * @param traversal the type of traversal * @return true if the traversal succeeded @@ -4365,7 +4372,7 @@ public boolean traverse (int traversal) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -4403,7 +4410,7 @@ public boolean traverse (int traversal, Event event) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> 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 74c5fa262b..09e289f727 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 @@ -79,7 +79,7 @@ import org.eclipse.swt.graphics.*; * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> - * <dd>Close, Dispose, Settings</dd> + * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd> * </dl> * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -2305,6 +2305,18 @@ public Font getSystemFont () { return systemFont = Font.gtk_new (this, defaultFont); } +/** + * Returns the single instance of the system taskBar or null + * when there is no system taskBar available for the platform. + * + * @return the system taskBar or <code>null</code> + * + * @exception SWTException <ul> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public TaskBar getSystemTaskBar () { checkDevice (); return null; @@ -3674,6 +3686,8 @@ public static void setAppName (String name) { * Sets the application version to the argument. * * @param version the new app version + * + * @since 3.6 */ public static void setAppVersion (String version) { APP_VERSION = version; 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 efe2611a3c..6495b79f72 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 @@ -712,6 +712,18 @@ void setFontDescription (int /*long*/ font) { * include the mnemonic character and line delimiters. The only delimiter * the HREF attribute supports is the quotation mark ("). * </p> + * <p> + * Mnemonics are indicated by an '&' that causes the next + * character to be the mnemonic. The receiver can have a + * mnemonic in the text preceding each link. When the user presses a + * key sequence that matches the mnemonic, focus is assigned + * to the link that follows the text. Mnemonics in links and in + * the trailing text are ignored. On most platforms, + * the mnemonic appears underlined but may be emphasised in a + * platform specific manner. The mnemonic indicator character + * '&' can be escaped by doubling it in the string, causing + * a single '&' to be displayed. + * </p> * * @param string the new text * 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 38e6ac81c3..d98c2823ac 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 @@ -197,7 +197,13 @@ public void addHelpListener (HelpListener listener) { * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid. * <code>widgetDefaultSelected</code> is not called. * </p> - * + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> + * * @param listener the listener which should be notified when the menu item is selected by the user * * @exception IllegalArgumentException <ul> 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 560c841dfa..07580ec938 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 @@ -306,8 +306,7 @@ public Point getSize () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -325,6 +324,19 @@ public int getThumb () { return (int) adjustment.page_size; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb relative to its parent. + * + * @return the thumb bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbBounds () { checkWidget(); int slider_start = OS.GTK_RANGE_SLIDER_START (handle); @@ -354,6 +366,20 @@ public Rectangle getThumbBounds () { return rect; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb track relative to its parent. This rectangle + * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}. + * + * @return the thumb track bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbTrackBounds () { checkWidget(); int x = 0, y = 0, width, height; @@ -746,10 +772,13 @@ public void setSelection (int value) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range 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 f240cae42a..957b79229d 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 @@ -365,8 +365,7 @@ public int getSelection () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -538,10 +537,13 @@ public void setSelection (int value) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range 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 73c533f1af..c87d7cdf7b 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 @@ -912,11 +912,11 @@ public void setIncrement (int value) { /** * Sets the maximum value that the receiver will allow. This new - * value will be ignored if it is not greater than the receiver's current + * value will be ignored if it is less than the receiver's current * minimum value. If the new maximum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new maximum, which must be greater than the current minimum + * @param value the new maximum, which must be greater than or equal to the current minimum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -939,11 +939,11 @@ public void setMaximum (int value) { /** * Sets the minimum value that the receiver will allow. This new - * value will be ignored if it is not less than the receiver's + * value will be ignored if it is greater than the receiver's * current maximum value. If the new minimum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new minimum, which must be less than the current maximum + * @param value the new minimum, which must be less than or equal to the current maximum * * @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 f34843751d..3307d505eb 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 @@ -252,10 +252,10 @@ public Color getBackground () { } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @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/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java index c0a7aa320f..3b107ce1ed 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 @@ -32,7 +32,7 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Verify</dd> + * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles MULTI and SINGLE may be specified, diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java index d741c89cde..4c5c7d95e6 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolItem.java @@ -141,6 +141,12 @@ public ToolItem (ToolBar parent, int style, int index) { * the event object detail field contains the value <code>SWT.ARROW</code>. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified when the control is selected by the user, * 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 1102499b31..c40dea482d 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 @@ -479,10 +479,10 @@ public Rectangle getBounds (int index) { } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1449,8 +1449,6 @@ public void setFont (int index, Font font) { * * @param color the new color (or null) * - * @since 2.0 - * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> 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 5da5ebe8c8..48e06014dd 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 @@ -435,6 +435,7 @@ void destroyWidget () { * <code>true</code> when sent the message <code>isDisposed()</code>. * Any internal connections between the widgets in the tree will * have been removed to facilitate garbage collection. + * This method does nothing if the widget is already disposed. * <p> * NOTE: This method is not called recursively on the descendants * of the receiver. This means that, widget implementers can not @@ -949,7 +950,7 @@ boolean isActive () { * <p> * This method gets the dispose state for the widget. * When a widget has been disposed, it is an error to - * invoke any other method using the widget. + * invoke any other method (except {@link #dispose()}) using the widget. * </p> * * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise @@ -1184,8 +1185,31 @@ int /*long*/ rendererRenderProc (int /*long*/ cell, int /*long*/ window, int /*l } /** + * Marks the widget to be skinned. + * <p> + * The skin event is sent to the receiver's display when appropriate (usually before the next event + * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin + * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> + * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it + * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor + * while specifying the <code>SWT.ALL</code> flag. + * </p> + * <p> + * The parameter <code>flags</code> may be either: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be skinned</dd> + * <dt><b>SWT.NONE</b></dt> + * <dd>only the receiver should be skinned</dd> + * </dl> + * </p> + * @param flags the flags specifying how to reskin * - * @param flags + * @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.6 */ public void reskin (int flags) { 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 6f5e63f03c..73cd8bf4f5 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 @@ -316,7 +316,7 @@ void init(int red, int green, int blue) { * <p> * This method gets the dispose state for the color. * When a color has been disposed, it is an error to - * invoke any other method using the color. + * invoke any other method (except {@link #dispose()}) using the color. * * @return <code>true</code> when the color is disposed and <code>false</code> otherwise */ 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 df20a5435c..672ea191e3 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 @@ -91,6 +91,10 @@ Cursor (Device device) { * <p> * You must dispose the cursor when it is no longer required. * </p> + * NOTE: + * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)} + * instead of using this constructor. This way you can avoid the + * overhead of disposing the Cursor resource. * * @param device the device on which to allocate the cursor * @param style the style of cursor to allocate @@ -418,7 +422,7 @@ public int hashCode () { * <p> * This method gets the dispose state for the cursor. * When a cursor has been disposed, it is an error to - * invoke any other method using the cursor. + * invoke any other method (except {@link #dispose()}) using the cursor. * * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise */ 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 5e46f67d2c..a00669c096 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 @@ -512,7 +512,7 @@ void init (FontData[] fds) { * <p> * This method gets the dispose state for the font. * When a font has been disposed, it is an error to - * invoke any other method using the font. + * invoke any other method (except {@link #dispose()}) using the font. * * @return <code>true</code> when the font is disposed and <code>false</code> otherwise */ 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 c82db1989c..a49e46975d 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 @@ -3414,7 +3414,7 @@ public boolean isClipped() { * <p> * This method gets the dispose state for the GC. * When a GC has been disposed, it is an error to - * invoke any other method using the GC. + * invoke any other method (except {@link #dispose()}) using the GC. * * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise */ 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 2ec6fd8882..340d524787 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 @@ -1171,7 +1171,7 @@ public int internal_new_GC (GCData data) { * </p> * * @param hDC the platform specific GC handle - * @param data the platform specific GC data + * @param data the platform specific GC data * * @noreference This method is not intended to be referenced by clients. */ @@ -1188,7 +1188,7 @@ public void internal_dispose_GC (int gc, GCData data) { * <p> * This method gets the dispose state for the image. * When an image has been disposed, it is an error to - * invoke any other method using the image. + * invoke any other method (except {@link #dispose()}) using the image. * * @return <code>true</code> when the image is disposed and <code>false</code> otherwise */ 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 252deb9f03..acf228a010 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 @@ -387,7 +387,7 @@ public boolean intersects (Rectangle rect) { * <p> * This method gets the dispose state for the region. * When a region has been disposed, it is an error to - * invoke any other method using the region. + * invoke any other method (except {@link #dispose()}) using the region. * * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/TextLayout.java index c73b3ea2b2..2e427560e2 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/graphics/TextLayout.java @@ -1312,6 +1312,17 @@ public int[] getSegments() { return segments; } +/** + * Returns the segments characters of the receiver. + * + * @return the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public char[] getSegmentsChars () { checkLayout(); return segmentsChars; @@ -1430,6 +1441,17 @@ public int getWidth () { return wrapWidth; } +/** +* Returns the receiver's wrap indent. +* +* @return the receiver's wrap indent +* +* @exception SWTException <ul> +* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> +* </ul> +* +* @since 3.6 +*/ public int getWrapIndent () { checkLayout(); return wrapIndent; @@ -1441,7 +1463,7 @@ public int getWrapIndent () { * <p> * This method gets the dispose state for the text layout. * When a text layout has been disposed, it is an error to - * invoke any other method using the text layout. + * invoke any other method (except {@link #dispose()}) using the text layout. * </p> * * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise @@ -1659,7 +1681,7 @@ public void setFont (Font font) { } /** - * Sets the indent of the receiver. This indent it applied of the first line of + * Sets the indent of the receiver. This indent is applied to the first line of * each paragraph. * * @param indent new indent @@ -1668,6 +1690,8 @@ public void setFont (Font font) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * + * @see #setWrapIndent(int) + * * @since 3.2 */ public void setIndent (int indent) { @@ -1739,7 +1763,7 @@ public void setSpacing (int spacing) { /** * Sets the offsets of the receiver's text segments. Text segments are used to - * override the default behaviour of the bidirectional algorithm. + * override the default behavior of the bidirectional algorithm. * Bidirectional reordering can happen within a text segment but not * between two adjacent segments. * <p> @@ -1748,12 +1772,18 @@ public void setSpacing (int spacing) { * always be zero and the last one should always be equals to length of * the text. * </p> + * <p> + * When segments characters are set, the segments are the offsets where + * the characters are inserted in the text. + * <p> * * @param segments the text segments offset * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @see #setSegmentsChars(char[]) */ public void setSegments(int[] segments) { checkLayout(); @@ -1771,6 +1801,23 @@ public void setSegments(int[] segments) { this.segments = segments; } +/** + * Sets the characters to be used in the segments boundaries. The segments + * are set by calling <code>setSegments(int[])</code>. The application can + * use this API to insert Unicode Control Characters in the text to control + * the display of the text and bidi reordering. The characters are not + * accessible by any other API in <code>TextLayout</code>. + * + * @param segmentsChars the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setSegments(int[]) + * + * @since 3.6 + */ public void setSegmentsChars(char[] segmentsChars) { checkLayout(); if (this.segmentsChars == null && segmentsChars == null) return; @@ -1951,6 +1998,20 @@ public void setWidth (int width) { this.wrapWidth = width; } +/** + * Sets the wrap indent of the receiver. This indent is applied to all lines + * in the paragraph except the first line. + * + * @param wrapIndent new wrap indent + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setIndent(int) + * + * @since 3.6 + */ public void setWrapIndent (int wrapIndent) { checkLayout(); if (wrapIndent < 0) return; 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 2c10e59b0b..5522a1b451 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 @@ -175,6 +175,12 @@ void _setText (String string) { * <code>widgetSelected</code> is called when the control is selected by the user. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified * 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 2b4568a6c1..eb758937bc 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 @@ -169,7 +169,7 @@ void reskinChildren (int flags) { * the source area to the destination and then causing the area * of the source which is not covered by the destination to * be repainted. Children that intersect the rectangle are - * optionally moved during the operation. In addition, outstanding + * optionally moved during the operation. In addition, all outstanding * paint events are flushed before the source area is copied to * ensure that the contents of the canvas are drawn correctly. * 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 8ad4709e7a..2fe3d38758 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 @@ -42,7 +42,7 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Selection, Verify</dd> + * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. 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 92c32c6bd6..ad42e78fd4 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 @@ -303,6 +303,33 @@ void deregister () { void drawBackground (GC gc, int x, int y, int width, int height) { drawBackground(gc, x, y, width, height, 0, 0); } +/** + * Fills the interior of the rectangle specified by the arguments, + * with the receiver's background. + * + * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from + * the <code>gc</code> origin to the origin of the parent image background. This is useful + * to ensure proper alignment of the image background.</p> + * + * @param gc the gc where the rectangle is to be filled + * @param x the x coordinate of the rectangle to be filled + * @param y the y coordinate of the rectangle to be filled + * @param width the width of the rectangle to be filled + * @param height the height of the rectangle to be filled + * @param offsetX the image background x offset + * @param offsetY the image background y offset + * + * @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_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.6 + */ public void drawBackground (GC gc, int x, int y, int width, int height, int offsetX, int offsetY) { checkWidget (); if (gc == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -760,6 +787,64 @@ public void layout (Control [] changed) { layout (changed, SWT.NONE); } +/** + * Forces a lay out (that is, sets the size and location) of all widgets that + * are in the parent hierarchy of the changed control up to and including the + * receiver. + * <p> + * The parameter <code>flags</code> may be a combination of: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be laid out</dd> + * <dt><b>SWT.CHANGED</b></dt> + * <dd>the layout must flush its caches</dd> + * <dt><b>SWT.DEFER</b></dt> + * <dd>layout will be deferred</dd> + * </dl> + * </p> + * <p> + * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code> + * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the + * hierarchy must not rely on any information cached about the changed control or + * any of its ancestors. The layout may (potentially) optimize the + * work it is doing by assuming that none of the peers of the changed + * control have changed state since the last layout. + * If an ancestor does not have a layout, skip it. + * </p> + * <p> + * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code> + * indicates that the whole widget tree should be laid out. And the flag + * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached + * information for all controls that are laid out. + * </p> + * <p> + * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by + * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call + * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when + * appropriate (usually before the next event is handled). When this flag is set, + * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>. + * </p> + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> + * + * @param changed a control that has had a state change which requires a recalculation of its size + * @param flags the flags specifying how the layout should happen + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> + * <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</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.6 + */ public void layout (Control [] changed, int flags) { checkWidget (); if (changed != null) { 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 3b9f7e468c..7a704b3ac0 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 @@ -26,7 +26,8 @@ import org.eclipse.swt.accessibility.*; * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd> * <dt><b>Events:</b> * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter, - * MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd> + * MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move, + * Paint, Resize, Traverse</dd> * </dl> * </p><p> * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified. @@ -650,7 +651,7 @@ int defaultForeground () { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -691,7 +692,7 @@ public boolean dragDetect (Event event) { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1170,6 +1171,11 @@ int getMinimumHeight () { * * @return the receiver's monitor * + * @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.0 */ public Monitor getMonitor () { @@ -3316,7 +3322,7 @@ int traversalCode (int key, XKeyEvent xEvent) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -3353,7 +3359,7 @@ public boolean traverse (int traversal, Event event) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -3490,7 +3496,8 @@ boolean traverse (Event event) { * traversal action. The argument should be one of the constants: * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, - * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>. + * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>, + * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>. * * @param traversal the type of traversal * @return true if the traversal succeeded 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 8b6748ad44..20bf3904ce 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 @@ -79,7 +79,7 @@ import org.eclipse.swt.graphics.*; * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> - * <dd>Close, Dispose, Settings</dd> + * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd> * </dl> * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -1956,6 +1956,18 @@ public Image getSystemImage (int style) { if (imagePixmap == 0) return null; return Image.motif_new (this, SWT.ICON, imagePixmap, maskPixmap); } +/** + * Returns the single instance of the system taskBar or null + * when there is no system taskBar available for the platform. + * + * @return the system taskBar or <code>null</code> + * + * @exception SWTException <ul> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public TaskBar getSystemTaskBar () { checkDevice (); return null; @@ -2477,9 +2489,9 @@ public int internal_new_GC (GCData data) { * </p> * * @param hDC the platform specific GC handle - * @param data the platform specific GC data + * @param data the platform specific GC data * - * @noreference This method is not intended to be referenced by clients. + * @noreference This method is not intended to be referenced by clients. */ public void internal_dispose_GC (int gc, GCData data) { OS.XFreeGC(xDisplay, gc); @@ -3416,6 +3428,8 @@ public static void setAppName (String name) { * Sets the application version to the argument. * * @param version the new app version + * + * @since 3.6 */ public static void setAppVersion (String version) { APP_VERSION = version; 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 8d82436f87..3d3e43beb4 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 @@ -441,6 +441,18 @@ void setForegroundPixel (int pixel) { * include the mnemonic character and line delimiters. The only delimiter * the HREF attribute supports is the quotation mark ("). * </p> + * <p> + * Mnemonics are indicated by an '&' that causes the next + * character to be the mnemonic. The receiver can have a + * mnemonic in the text preceding each link. When the user presses a + * key sequence that matches the mnemonic, focus is assigned + * to the link that follows the text. Mnemonics in links and in + * the trailing text are ignored. On most platforms, + * the mnemonic appears underlined but may be emphasised in a + * platform specific manner. The mnemonic indicator character + * '&' can be escaped by doubling it in the string, causing + * a single '&' to be displayed. + * </p> * * @param string the new text * 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 9731e46e12..5dc8c8abf7 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 @@ -230,7 +230,13 @@ public void addHelpListener (HelpListener listener) { * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid. * <code>widgetDefaultSelected</code> is not called. * </p> - * + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> + * * @param listener the listener which should be notified when the menu item is selected by the user * * @exception IllegalArgumentException <ul> 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 1a5def919b..6415bafe0b 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 @@ -294,8 +294,7 @@ public Point getSize () { return new Point (argList [1] + borders, argList [3] + borders); } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -312,6 +311,19 @@ public int getThumb () { OS.XtGetValues (handle, argList, argList.length / 2); return argList [1]; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb relative to its parent. + * + * @return the thumb bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbBounds () { checkWidget(); int [] argList = { @@ -358,6 +370,20 @@ public Rectangle getThumbBounds () { rect.y -= root_y [0]; return rect; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb track relative to its parent. This rectangle + * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}. + * + * @return the thumb track bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbTrackBounds () { checkWidget(); int [] argList = { @@ -676,10 +702,13 @@ public void setSelection (int selection) { display.setWarnings (warnings); } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range 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 0ac37fc1cc..0255d5343d 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 @@ -258,8 +258,7 @@ public int getSelection () { return argList [1]; } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -440,10 +439,13 @@ public void setSelection (int value) { display.setWarnings (warnings); } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range 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 1a4266f5ce..11433a7914 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 @@ -697,11 +697,11 @@ public void setIncrement (int value) { } /** * Sets the maximum value that the receiver will allow. This new - * value will be ignored if it is not greater than the receiver's current + * value will be ignored if it is less than the receiver's current * minimum value. If the new maximum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new maximum, which must be greater than the current minimum + * @param value the new maximum, which must be greater than or equal to the current minimum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -720,11 +720,11 @@ public void setMaximum (int value) { } /** * Sets the minimum value that the receiver will allow. This new - * value will be ignored if it is not less than the receiver's + * value will be ignored if it is greater than the receiver's * current maximum value. If the new minimum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new minimum, which must be less than the current maximum + * @param value the new minimum, which must be less than or equal to the current maximum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> 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 bb1201790a..3e72a30b02 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 @@ -32,7 +32,7 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Verify</dd> + * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles MULTI and SINGLE may be specified, diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolItem.java index 9908c4690e..3acbc239c6 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ToolItem.java @@ -140,6 +140,12 @@ public ToolItem (ToolBar parent, int style, int index) { * the event object detail field contains the value <code>SWT.ARROW</code>. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified when the control is selected by the user, * 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 997e427c90..34256cbe9c 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 @@ -340,6 +340,7 @@ void destroyWidget () { * <code>true</code> when sent the message <code>isDisposed()</code>. * Any internal connections between the widgets in the tree will * have been removed to facilitate garbage collection. + * This method does nothing if the widget is already disposed. * <p> * NOTE: This method is not called recursively on the descendants * of the receiver. This means that, widget implementers can not @@ -550,7 +551,7 @@ boolean hooks (int eventType) { * <p> * This method gets the dispose state for the widget. * When a widget has been disposed, it is an error to - * invoke any other method using the widget. + * invoke any other method (except {@link #dispose()}) using the widget. * </p> * * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise @@ -769,8 +770,31 @@ protected void removeListener (int eventType, SWTEventListener handler) { eventTable.unhook (eventType, handler); } /** + * Marks the widget to be skinned. + * <p> + * The skin event is sent to the receiver's display when appropriate (usually before the next event + * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin + * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> + * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it + * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor + * while specifying the <code>SWT.ALL</code> flag. + * </p> + * <p> + * The parameter <code>flags</code> may be either: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be skinned</dd> + * <dt><b>SWT.NONE</b></dt> + * <dd>only the receiver should be skinned</dd> + * </dl> + * </p> + * @param flags the flags specifying how to reskin * - * @param flags + * @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.6 */ public void reskin (int flags) { 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 c7c70a3acc..5c3ea28c05 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 @@ -213,7 +213,7 @@ void init(int red, int green, int blue) { * <p> * This method gets the dispose state for the color. * When a color has been disposed, it is an error to - * invoke any other method using the color. + * invoke any other method (except {@link #dispose()}) using the color. * * @return <code>true</code> when the color is disposed and <code>false</code> otherwise */ 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 3ad36af8ea..ba1491e739 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 @@ -81,6 +81,10 @@ Cursor(Device device) { * <p> * You must dispose the cursor when it is no longer required. * </p> + * NOTE: + * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)} + * instead of using this constructor. This way you can avoid the + * overhead of disposing the Cursor resource. * * @param device the device on which to allocate the cursor * @param style the style of cursor to allocate @@ -439,7 +443,7 @@ public int hashCode () { * <p> * This method gets the dispose state for the cursor. * When a cursor has been disposed, it is an error to - * invoke any other method using the cursor. + * invoke any other method (except {@link #dispose()}) using the cursor. * * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise */ 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 e94abad930..36ad265242 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 @@ -205,7 +205,7 @@ public int hashCode () { * <p> * This method gets the dispose state for the font. * When a font has been disposed, it is an error to - * invoke any other method using the font. + * invoke any other method (except {@link #dispose()}) using the font. * * @return <code>true</code> when the font is disposed and <code>false</code> otherwise */ 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 c7444289a4..3b01e29575 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 @@ -2547,7 +2547,7 @@ public boolean isClipped() { * <p> * This method gets the dispose state for the GC. * When a GC has been disposed, it is an error to - * invoke any other method using the GC. + * invoke any other method (except {@link #dispose()}) using the GC. * * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise */ 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 92fae7681d..93bb5dca74 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 @@ -953,7 +953,7 @@ public int internal_new_GC (GCData data) { * </p> * * @param hDC the platform specific GC handle - * @param data the platform specific GC data + * @param data the platform specific GC data * * @noreference This method is not intended to be referenced by clients. */ @@ -967,7 +967,7 @@ public void internal_dispose_GC (int pmMC, GCData data) { * <p> * This method gets the dispose state for the image. * When an image has been disposed, it is an error to - * invoke any other method using the image. + * invoke any other method (except {@link #dispose()}) using the image. * * @return <code>true</code> when the image is disposed and <code>false</code> otherwise */ 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 39ac4316ff..9fb0d6d072 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 @@ -452,7 +452,7 @@ public boolean intersects (Rectangle rect) { * <p> * This method gets the dispose state for the region. * When a region has been disposed, it is an error to - * invoke any other method using the region. + * invoke any other method (except {@link #dispose()}) using the region. * * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise */ 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 291029074d..ec08b7c8d9 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 @@ -116,6 +116,12 @@ static int checkStyle (int style) { * <code>widgetSelected</code> is called when the control is selected by the user. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified * 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 44d3d8a528..eda2398f0e 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 @@ -202,7 +202,7 @@ void reskinChildren (int flags) { * the source area to the destination and then causing the area * of the source which is not covered by the destination to * be repainted. Children that intersect the rectangle are - * optionally moved during the operation. In addition, outstanding + * optionally moved during the operation. In addition, all outstanding * paint events are flushed before the source area is copied to * ensure that the contents of the canvas are drawn correctly. * 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 8fc948adb5..0999db44db 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 @@ -42,7 +42,7 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Selection, Verify</dd> + * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. 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 776c6453b5..cc5652c11a 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 @@ -285,6 +285,33 @@ void createScrolledHandle (int parentHandle) { createScrollBars (); } +/** + * Fills the interior of the rectangle specified by the arguments, + * with the receiver's background. + * + * <p>The <code>offsetX</code> and <code>offsetY</code> are used to map from + * the <code>gc</code> origin to the origin of the parent image background. This is useful + * to ensure proper alignment of the image background.</p> + * + * @param gc the gc where the rectangle is to be filled + * @param x the x coordinate of the rectangle to be filled + * @param y the y coordinate of the rectangle to be filled + * @param width the width of the rectangle to be filled + * @param height the height of the rectangle to be filled + * @param offsetX the image background x offset + * @param offsetY the image background y offset + * + * @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_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.6 + */ public void drawBackground (GC gc, int x, int y, int width, int height, int offsetX, int offsetY) { drawBackground(gc, offsetX, offsetY, width, height); } @@ -767,6 +794,64 @@ public void layout (Control [] changed) { layout (changed, SWT.NONE); } +/** + * Forces a lay out (that is, sets the size and location) of all widgets that + * are in the parent hierarchy of the changed control up to and including the + * receiver. + * <p> + * The parameter <code>flags</code> may be a combination of: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be laid out</dd> + * <dt><b>SWT.CHANGED</b></dt> + * <dd>the layout must flush its caches</dd> + * <dt><b>SWT.DEFER</b></dt> + * <dd>layout will be deferred</dd> + * </dl> + * </p> + * <p> + * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code> + * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the + * hierarchy must not rely on any information cached about the changed control or + * any of its ancestors. The layout may (potentially) optimize the + * work it is doing by assuming that none of the peers of the changed + * control have changed state since the last layout. + * If an ancestor does not have a layout, skip it. + * </p> + * <p> + * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code> + * indicates that the whole widget tree should be laid out. And the flag + * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached + * information for all controls that are laid out. + * </p> + * <p> + * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by + * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call + * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when + * appropriate (usually before the next event is handled). When this flag is set, + * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>. + * </p> + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> + * + * @param changed a control that has had a state change which requires a recalculation of its size + * @param flags the flags specifying how the layout should happen + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> + * <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</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.6 + */ public void layout (Control [] changed, int flags) { checkWidget (); if (changed != null) { 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 0dfb6bff88..2dffaa1725 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 @@ -26,7 +26,8 @@ import org.eclipse.swt.accessibility.*; * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd> * <dt><b>Events:</b> * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter, - * MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd> + * MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move, + * Paint, Resize, Traverse</dd> * </dl> * </p><p> * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified. @@ -613,7 +614,7 @@ boolean drawGripper (int x, int y, int width, int height, boolean vertical) { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -655,7 +656,7 @@ public boolean dragDetect (Event event) { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1046,6 +1047,11 @@ public Menu getMenu () { * * @return the receiver's monitor * + * @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.0 */ public Monitor getMonitor () { @@ -3158,7 +3164,7 @@ int traversalCode (int key_sym, PhKeyEvent_t ke) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -3196,7 +3202,7 @@ public boolean traverse (int traversal, Event event) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -3344,7 +3350,8 @@ boolean traverse (Event event) { * traversal action. The argument should be one of the constants: * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, - * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>. + * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>, + * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>. * * @param traversal the type of traversal * @return true if the traversal succeeded 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 fee5904f56..36adcfddbb 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 @@ -79,7 +79,7 @@ import org.eclipse.swt.graphics.*; * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> - * <dd>Close, Dispose, Settings</dd> + * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd> * </dl> * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -955,6 +955,8 @@ public static void setAppName (String name) { * Sets the application version to the argument. * * @param version the new app version + * + * @since 3.6 */ public static void setAppVersion (String version) { APP_VERSION = version; @@ -1348,6 +1350,18 @@ public Image getSystemImage (int id) { return null; } +/** + * Returns the single instance of the system taskBar or null + * when there is no system taskBar available for the platform. + * + * @return the system taskBar or <code>null</code> + * + * @exception SWTException <ul> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public TaskBar getSystemTaskBar () { checkDevice (); return null; 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 4864a59b91..70e15590d5 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 @@ -595,6 +595,18 @@ public void setFont (Font font) { * include the mnemonic character and line delimiters. The only delimiter * the HREF attribute supports is the quotation mark ("). * </p> + * <p> + * Mnemonics are indicated by an '&' that causes the next + * character to be the mnemonic. The receiver can have a + * mnemonic in the text preceding each link. When the user presses a + * key sequence that matches the mnemonic, focus is assigned + * to the link that follows the text. Mnemonics in links and in + * the trailing text are ignored. On most platforms, + * the mnemonic appears underlined but may be emphasised in a + * platform specific manner. The mnemonic indicator character + * '&' can be escaped by doubling it in the string, causing + * a single '&' to be displayed. + * </p> * * @param string the new text * 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 4553d5e9bf..ec4107da36 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 @@ -197,7 +197,13 @@ public void addHelpListener (HelpListener listener) { * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid. * <code>widgetDefaultSelected</code> is not called. * </p> - * + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> + * * @param listener the listener which should be notified when the menu item is selected by the user * * @exception IllegalArgumentException <ul> 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 42117cd7ab..5e0608d8f0 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 @@ -319,8 +319,7 @@ public Point getSize () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -338,12 +337,39 @@ public int getThumb () { return args [1]; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb relative to its parent. + * + * @return the thumb bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbBounds () { checkWidget(); //TODO implement getThumbBounds() return null; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb track relative to its parent. This rectangle + * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}. + * + * @return the thumb track bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbTrackBounds () { checkWidget(); //TODO implement getThumbTrackBounds() @@ -637,10 +663,13 @@ public void setSelection (int value) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range 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 8de4424e49..5825034e52 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 @@ -282,8 +282,7 @@ public Point getSize () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -488,10 +487,13 @@ public void setSelection (int value) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range 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 e8e5d1ad1a..217890c630 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 @@ -670,11 +670,11 @@ public void setIncrement (int value) { /** * Sets the maximum value that the receiver will allow. This new - * value will be ignored if it is not greater than the receiver's current + * value will be ignored if it is less than the receiver's current * minimum value. If the new maximum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new maximum, which must be greater than the current minimum + * @param value the new maximum, which must be greater than or equal to the current minimum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -689,11 +689,11 @@ public void setMaximum (int value) { /** * Sets the minimum value that the receiver will allow. This new - * value will be ignored if it is not less than the receiver's + * value will be ignored if it is greater than the receiver's * current maximum value. If the new minimum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new minimum, which must be less than the current maximum + * @param value the new minimum, which must be less than or equal to the current maximum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> 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 4fdf962a41..b41ca625ac 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 @@ -32,7 +32,7 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Verify</dd> + * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles MULTI and SINGLE may be specified, diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ToolItem.java index ee265148db..74ea3c3991 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ToolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ToolItem.java @@ -137,6 +137,12 @@ public ToolItem (ToolBar parent, int style, int index) { * the event object detail field contains the value <code>SWT.ARROW</code>. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified when the control is selected by the user, * 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 986994e6eb..47cd148ec9 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 @@ -422,6 +422,7 @@ void destroyWidget () { * <code>true</code> when sent the message <code>isDisposed()</code>. * Any internal connections between the widgets in the tree will * have been removed to facilitate garbage collection. + * This method does nothing if the widget is already disposed. * <p> * NOTE: This method is not called recursively on the descendants * of the receiver. This means that, widget implementers can not @@ -641,7 +642,7 @@ void hookEvents () { * <p> * This method gets the dispose state for the widget. * When a widget has been disposed, it is an error to - * invoke any other method using the widget. + * invoke any other method (except {@link #dispose()}) using the widget. * </p> * * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise @@ -916,8 +917,31 @@ protected void removeListener (int eventType, SWTEventListener handler) { } /** + * Marks the widget to be skinned. + * <p> + * The skin event is sent to the receiver's display when appropriate (usually before the next event + * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin + * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> + * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it + * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor + * while specifying the <code>SWT.ALL</code> flag. + * </p> + * <p> + * The parameter <code>flags</code> may be either: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be skinned</dd> + * <dt><b>SWT.NONE</b></dt> + * <dd>only the receiver should be skinned</dd> + * </dl> + * </p> + * @param flags the flags specifying how to reskin * - * @param flags + * @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.6 */ public void reskin (int flags) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Color.java index f2044be0b2..a1664eed8c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Color.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Color.java @@ -235,7 +235,7 @@ void init(int red, int green, int blue) { * <p> * This method gets the dispose state for the color. * When a color has been disposed, it is an error to - * invoke any other method using the color. + * invoke any other method (except {@link #dispose()}) using the color. * * @return <code>true</code> when the color is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Cursor.java index 438360f567..865d702d34 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Cursor.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Cursor.java @@ -73,6 +73,10 @@ Cursor(Device device) { * <p> * You must dispose the cursor when it is no longer required. * </p> + * NOTE: + * It is recommended to use {@link org.eclipse.swt.widgets.Display#getSystemCursor(int)} + * instead of using this constructor. This way you can avoid the + * overhead of disposing the Cursor resource. * * @param device the device on which to allocate the cursor * @param style the style of cursor to allocate @@ -426,7 +430,7 @@ public int hashCode () { * <p> * This method gets the dispose state for the cursor. * When a cursor has been disposed, it is an error to - * invoke any other method using the cursor. + * invoke any other method (except {@link #dispose()}) using the cursor. * * @return <code>true</code> when the cursor is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Font.java index 7531b4d58b..0d8afcc377 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Font.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Font.java @@ -252,7 +252,7 @@ void init (FontData fd) { * <p> * This method gets the dispose state for the font. * When a font has been disposed, it is an error to - * invoke any other method using the font. + * invoke any other method (except {@link #dispose()}) using the font. * * @return <code>true</code> when the font is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/GC.java index 07df9561fc..42114a9f44 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/GC.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/GC.java @@ -2111,7 +2111,7 @@ public boolean isClipped() { * <p> * This method gets the dispose state for the GC. * When a GC has been disposed, it is an error to - * invoke any other method using the GC. + * invoke any other method (except {@link #dispose()}) using the GC. * * @return <code>true</code> when the GC is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Image.java index 04b487a87f..adffe22d71 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Image.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Image.java @@ -1018,7 +1018,7 @@ public int internal_new_GC (GCData data) { * </p> * * @param hDC the platform specific GC handle - * @param data the platform specific GC data + * @param data the platform specific GC data * * @noreference This method is not intended to be referenced by clients. */ @@ -1049,7 +1049,7 @@ public void internal_dispose_GC (int dc, GCData data) { * <p> * This method gets the dispose state for the image. * When an image has been disposed, it is an error to - * invoke any other method using the image. + * invoke any other method (except {@link #dispose()}) using the image. * * @return <code>true</code> when the image is disposed and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Path.java index 4716a12656..660c61b9a9 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Path.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Path.java @@ -608,7 +608,7 @@ void init(PathData data) { * <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. + * invoke any other method (except {@link #dispose()}) using the Path. * * @return <code>true</code> when the Path is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Pattern.java index 6a28e5a41c..fdc45f41fb 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Pattern.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Pattern.java @@ -197,7 +197,7 @@ void destroy() { * <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. + * invoke any other method (except {@link #dispose()}) using the Pattern. * * @return <code>true</code> when the Pattern is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Region.java index 33d56243ae..ef2497bfcc 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Region.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Region.java @@ -496,7 +496,7 @@ public boolean intersects (Rectangle rect) { * <p> * This method gets the dispose state for the region. * When a region has been disposed, it is an error to - * invoke any other method using the region. + * invoke any other method (except {@link #dispose()}) using the region. * * @return <code>true</code> when the region is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/TextLayout.java index b4877cc31c..990b831407 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/TextLayout.java @@ -1244,6 +1244,17 @@ public int[] getSegments () { return segments; } +/** + * Returns the segments characters of the receiver. + * + * @return the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public char[] getSegmentsChars () { checkLayout(); return segmentsChars; @@ -1431,6 +1442,17 @@ public int getWidth () { return wrapWidth; } +/** +* Returns the receiver's wrap indent. +* +* @return the receiver's wrap indent +* +* @exception SWTException <ul> +* <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> +* </ul> +* +* @since 3.6 +*/ public int getWrapIndent () { checkLayout(); return wrapIndent; @@ -1442,7 +1464,7 @@ public int getWrapIndent () { * <p> * This method gets the dispose state for the text layout. * When a text layout has been disposed, it is an error to - * invoke any other method using the text layout. + * invoke any other method (except {@link #dispose()}) using the text layout. * </p> * * @return <code>true</code> when the text layout is disposed and <code>false</code> otherwise @@ -1560,7 +1582,7 @@ public void setFont (Font font) { } /** - * Sets the indent of the receiver. This indent it applied of the first line of + * Sets the indent of the receiver. This indent is applied to the first line of * each paragraph. * * @param indent new indent @@ -1569,6 +1591,8 @@ public void setFont (Font font) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * + * @see #setWrapIndent(int) + * * @since 3.2 */ public void setIndent (int indent) { @@ -1621,7 +1645,7 @@ public void setOrientation (int orientation) { /** * Sets the offsets of the receiver's text segments. Text segments are used to - * override the default behaviour of the bidirectional algorithm. + * override the default behavior of the bidirectional algorithm. * Bidirectional reordering can happen within a text segment but not * between two adjacent segments. * <p> @@ -1630,12 +1654,18 @@ public void setOrientation (int orientation) { * always be zero and the last one should always be equals to length of * the text. * </p> + * <p> + * When segments characters are set, the segments are the offsets where + * the characters are inserted in the text. + * <p> * * @param segments the text segments offset * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @see #setSegmentsChars(char[]) */ public void setSegments(int[] segments) { checkLayout(); @@ -1653,6 +1683,23 @@ public void setSegments(int[] segments) { this.segments = segments; } +/** + * Sets the characters to be used in the segments boundaries. The segments + * are set by calling <code>setSegments(int[])</code>. The application can + * use this API to insert Unicode Control Characters in the text to control + * the display of the text and bidi reordering. The characters are not + * accessible by any other API in <code>TextLayout</code>. + * + * @param segmentsChars the segments characters + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setSegments(int[]) + * + * @since 3.6 + */ public void setSegmentsChars(char[] segmentsChars) { checkLayout(); if (this.segmentsChars == null && segmentsChars == null) return; @@ -1854,6 +1901,20 @@ public void setWidth (int width) { this.wrapWidth = width; } +/** + * Sets the wrap indent of the receiver. This indent is applied to all lines + * in the paragraph except the first line. + * + * @param wrapIndent new wrap indent + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setIndent(int) + * + * @since 3.6 + */ public void setWrapIndent (int wrapIndent) { checkLayout(); if (wrapIndent < 0) return; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Transform.java index 2649deb7d8..820eda47bb 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Transform.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/graphics/Transform.java @@ -217,7 +217,7 @@ public void invert() { * <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. + * invoke any other method (except {@link #dispose()}) using the Transform. * * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Button.java index 99237de68e..67c04ace69 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Button.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Button.java @@ -102,6 +102,12 @@ public Button (Composite parent, int style) { * <code>widgetSelected</code> is called when the control is selected by the user. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Canvas.java index 43a26983bc..952705e958 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Canvas.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Canvas.java @@ -216,7 +216,7 @@ public void drawBackground (GC gc, int x, int y, int width, int height) { * the source area to the destination and then causing the area * of the source which is not covered by the destination to * be repainted. Children that intersect the rectangle are - * optionally moved during the operation. In addition, outstanding + * optionally moved during the operation. In addition, all outstanding * paint events are flushed before the source area is copied to * ensure that the contents of the canvas are drawn correctly. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Combo.java index 796bce5b02..2c07ac1929 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Combo.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Combo.java @@ -41,7 +41,7 @@ import org.eclipse.swt.internal.wpf.OS; * <dt><b>Styles:</b></dt> * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Selection, Verify</dd> + * <dd>DefaultSelection, Modify, Selection, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Composite.java index 5f3999e80b..cd63a46bbd 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Composite.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Composite.java @@ -752,6 +752,64 @@ public void layout (Control [] changed) { layout (changed, SWT.NONE); } +/** + * Forces a lay out (that is, sets the size and location) of all widgets that + * are in the parent hierarchy of the changed control up to and including the + * receiver. + * <p> + * The parameter <code>flags</code> may be a combination of: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be laid out</dd> + * <dt><b>SWT.CHANGED</b></dt> + * <dd>the layout must flush its caches</dd> + * <dt><b>SWT.DEFER</b></dt> + * <dd>layout will be deferred</dd> + * </dl> + * </p> + * <p> + * When the <code>changed</code> array is specified, the flags <code>SWT.ALL</code> + * and <code>SWT.CHANGED</code> have no effect. In this case, the layouts in the + * hierarchy must not rely on any information cached about the changed control or + * any of its ancestors. The layout may (potentially) optimize the + * work it is doing by assuming that none of the peers of the changed + * control have changed state since the last layout. + * If an ancestor does not have a layout, skip it. + * </p> + * <p> + * When the <code>changed</code> array is not specified, the flag <code>SWT.ALL</code> + * indicates that the whole widget tree should be laid out. And the flag + * <code>SWT.CHANGED</code> indicates that the layouts should flush any cached + * information for all controls that are laid out. + * </p> + * <p> + * The <code>SWT.DEFER</code> flag always causes the layout to be deferred by + * calling <code>Composite.setLayoutDeferred(true)</code> and scheduling a call + * to <code>Composite.setLayoutDeferred(false)</code>, which will happen when + * appropriate (usually before the next event is handled). When this flag is set, + * the application should not call <code>Composite.setLayoutDeferred(boolean)</code>. + * </p> + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> + * + * @param changed a control that has had a state change which requires a recalculation of its size + * @param flags the flags specifying how the layout should happen + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the controls in changed is null or has been disposed</li> + * <li>ERROR_INVALID_PARENT - if any control in changed is not in the widget tree of the receiver</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.6 + */ public void layout (Control [] changed, int flags) { checkWidget (); if (changed != null) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Control.java index cc30af6bfb..f84cf790ad 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Control.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Control.java @@ -28,7 +28,8 @@ import org.eclipse.swt.effects.*; * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd> * <dt><b>Events:</b> * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter, - * MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd> + * MouseExit, MouseHover, MouseUp, MouseMove, MouseWheel, MouseHorizontalWheel, MouseVerticalWheel, Move, + * Paint, Resize, Traverse</dd> * </dl> * </p><p> * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified. @@ -674,7 +675,7 @@ void destroyWidget () { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -716,7 +717,7 @@ public boolean dragDetect (Event event) { * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * <li>ERROR_NULL_ARGUMENT if the event is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1122,6 +1123,11 @@ public Menu getMenu () { * * @return the receiver's monitor * + * @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.0 */ public Monitor getMonitor () { @@ -3426,7 +3432,7 @@ boolean translateTraversal (int e) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -3464,7 +3470,7 @@ public boolean traverse (int traversal, Event event) { * this from <code>event</code> * @param event the KeyDown event * - * @return true if the traversal succeeded + * @return <code>true</code> if the traversal succeeded * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT if the event is null</li> @@ -3612,7 +3618,8 @@ boolean traverse (Event event) { * traversal action. The argument should be one of the constants: * <code>SWT.TRAVERSE_ESCAPE</code>, <code>SWT.TRAVERSE_RETURN</code>, * <code>SWT.TRAVERSE_TAB_NEXT</code>, <code>SWT.TRAVERSE_TAB_PREVIOUS</code>, - * <code>SWT.TRAVERSE_ARROW_NEXT</code> and <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>. + * <code>SWT.TRAVERSE_ARROW_NEXT</code>, <code>SWT.TRAVERSE_ARROW_PREVIOUS</code>, + * <code>SWT.TRAVERSE_PAGE_NEXT</code> and <code>SWT.TRAVERSE_PAGE_PREVIOUS</code>. * * @param traversal the type of traversal * @return true if the traversal succeeded diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Display.java index 23d1b8e855..3b70638f54 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Display.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Display.java @@ -78,7 +78,7 @@ import org.eclipse.swt.graphics.*; * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> - * <dd>Close, Dispose, Settings</dd> + * <dd>Close, Dispose, OpenDocument, Settings, Skin</dd> * </dl> * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -1643,6 +1643,18 @@ public Image getSystemImage (int id) { return null; } +/** + * Returns the single instance of the system taskBar or null + * when there is no system taskBar available for the platform. + * + * @return the system taskBar or <code>null</code> + * + * @exception SWTException <ul> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.6 + */ public TaskBar getSystemTaskBar () { checkDevice (); return null; @@ -2822,10 +2834,16 @@ public void setData (Object data) { } /** - * 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. Specifying - * <code>null</code> for the name clears it. + * Sets the application name to the argument. + * <p> + * The application name can be used in several ways, + * depending on the platform and tools being used. + * On Motif, for example, this can be used to set + * the name used for resource lookup. Accessibility + * tools may also ask for the application name. + * </p><p> + * Specifying <code>null</code> for the name clears it. + * </p> * * @param name the new app name or <code>null</code> */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Link.java index 4a6895c4c8..60aad80fc3 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Link.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Link.java @@ -376,6 +376,18 @@ void setForegroundBrush (int brush) { * include the mnemonic character and line delimiters. The only delimiter * the HREF attribute supports is the quotation mark ("). * </p> + * <p> + * Mnemonics are indicated by an '&' that causes the next + * character to be the mnemonic. The receiver can have a + * mnemonic in the text preceding each link. When the user presses a + * key sequence that matches the mnemonic, focus is assigned + * to the link that follows the text. Mnemonics in links and in + * the trailing text are ignored. On most platforms, + * the mnemonic appears underlined but may be emphasised in a + * platform specific manner. The mnemonic indicator character + * '&' can be escaped by doubling it in the string, causing + * a single '&' to be displayed. + * </p> * * @param string the new text * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/MenuItem.java index bd7a4e0320..a533ba9b62 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/MenuItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/MenuItem.java @@ -182,7 +182,13 @@ public void addHelpListener (HelpListener listener) { * When <code>widgetSelected</code> is called, the stateMask field of the event object is valid. * <code>widgetDefaultSelected</code> is not called. * </p> - * + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> + * * @param listener the listener which should be notified when the menu item is selected by the user * * @exception IllegalArgumentException <ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ScrollBar.java index c023abe452..cd9f021d24 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ScrollBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ScrollBar.java @@ -322,8 +322,7 @@ public Point getSize () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -339,6 +338,19 @@ public int getThumb () { return (int) OS.ScrollBar_ViewportSize (handle); } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb relative to its parent. + * + * @return the thumb bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbBounds () { checkWidget(); int track = OS.ScrollBar_Track(handle); @@ -355,6 +367,20 @@ public Rectangle getThumbBounds () { return rect; } +/** + * Returns a rectangle describing the size and location of the + * receiver's thumb track relative to its parent. This rectangle + * comprises the areas 2, 3, and 4 as described in {@link ScrollBar}. + * + * @return the thumb track bounds, relative to the {@link #getParent() parent} + * + * @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.6 + */ public Rectangle getThumbTrackBounds () { checkWidget(); int track = OS.ScrollBar_Track(handle); @@ -624,10 +650,13 @@ public void setSelection (int selection) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Slider.java index c806643d73..2e59ae1674 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Slider.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Slider.java @@ -255,8 +255,7 @@ public int getSelection () { } /** - * Returns the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. + * Returns the receiver's thumb value. * * @return the thumb value * @@ -429,10 +428,13 @@ public void setSelection (int value) { } /** - * Sets the size of the receiver's thumb relative to the - * difference between its maximum and minimum values. This new - * value will be ignored if it is less than one, and will be + * Sets the thumb value. The thumb value should be used to represent + * the size of the visual portion of the current range. This value is + * usually the same as the page increment value. + * <p> + * This new value will be ignored if it is less than one, and will be * clamped if it exceeds the receiver's current range. + * </p> * * @param value the new thumb value, which must be at least one and not * larger than the size of the current range diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Spinner.java index 93685904bf..e91e0ce044 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Spinner.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Spinner.java @@ -765,11 +765,11 @@ public void setIncrement (int value) { /** * Sets the maximum value that the receiver will allow. This new - * value will be ignored if it is not greater than the receiver's current + * value will be ignored if it is less than the receiver's current * minimum value. If the new maximum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new maximum, which must be greater than the current minimum + * @param value the new maximum, which must be greater than or equal to the current minimum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -785,11 +785,11 @@ public void setMaximum (int value) { /** * Sets the minimum value that the receiver will allow. This new - * value will be ignored if it is not less than the receiver's + * value will be ignored if it is greater than the receiver's * current maximum value. If the new minimum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new minimum, which must be less than the current maximum + * @param value the new minimum, which must be less than or equal to the current maximum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TableItem.java index 6e4946d3bc..15751546ad 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TableItem.java @@ -333,10 +333,10 @@ public Color getBackground (int index) { } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Text.java index b5295c1d40..322862c64f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Text.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Text.java @@ -31,7 +31,7 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>CENTER, ICON_CANCEL, ICON_SEARCH, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Verify</dd> + * <dd>DefaultSelection, Modify, Verify, OrientationChange</dd> * </dl> * <p> * Note: Only one of the styles MULTI and SINGLE may be specified, diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ToolItem.java index 5dda1d3821..203dba1a30 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ToolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/ToolItem.java @@ -136,6 +136,12 @@ public ToolItem (ToolBar parent, int style, int index) { * the event object detail field contains the value <code>SWT.ARROW</code>. * <code>widgetDefaultSelected</code> is not called. * </p> + * <p> + * When the <code>SWT.RADIO</code> style bit is set, the <code>widgetSelected</code> method is + * also called when the receiver loses selection because another item in the same radio group + * was selected by the user. During <code>widgetSelected</code> the application can use + * <code>getSelection()</code> to determine the current selected state of the receiver. + * </p> * * @param listener the listener which should be notified when the control is selected by the user, * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TreeItem.java index 24e2c25c4e..0540cc5750 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TreeItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/TreeItem.java @@ -575,10 +575,10 @@ public Color getBackground (int index) { } /** - * Returns a rectangle describing the receiver's size and location - * relative to its parent. + * Returns a rectangle describing the size and location of the receiver's + * text relative to its parent. * - * @return the receiver's bounding rectangle + * @return the bounding rectangle of the receiver's text * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1305,8 +1305,6 @@ public void setFont (int index, Font font) { * * @param color the new color (or null) * - * @since 2.0 - * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Widget.java index c016e42a06..41a636eb0a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Widget.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/wpf/org/eclipse/swt/widgets/Widget.java @@ -429,6 +429,7 @@ void destroyWidget () { * <code>true</code> when sent the message <code>isDisposed()</code>. * Any internal connections between the widgets in the tree will * have been removed to facilitate garbage collection. + * This method does nothing if the widget is already disposed. * <p> * NOTE: This method is not called recursively on the descendants * of the receiver. This means that, widget implementers can not @@ -732,7 +733,7 @@ boolean hooks (int eventType) { * <p> * This method gets the dispose state for the widget. * When a widget has been disposed, it is an error to - * invoke any other method using the widget. + * invoke any other method (except {@link #dispose()}) using the widget. * </p> * * @return <code>true</code> when the widget is disposed and <code>false</code> otherwise @@ -1008,8 +1009,31 @@ protected void removeListener (int eventType, SWTEventListener listener) { } /** + * Marks the widget to be skinned. + * <p> + * The skin event is sent to the receiver's display when appropriate (usually before the next event + * is handled). Widgets are automatically marked for skinning upon creation as well as when its skin + * id or class changes. The skin id and/or class can be changed by calling <code>Display.setData(String, Object)</code> + * with the keys SWT.SKIN_ID and/or SWT.SKIN_CLASS. Once the skin event is sent to a widget, it + * will not be sent again unless <code>reskin(int)</code> is called on the widget or on an ancestor + * while specifying the <code>SWT.ALL</code> flag. + * </p> + * <p> + * The parameter <code>flags</code> may be either: + * <dl> + * <dt><b>SWT.ALL</b></dt> + * <dd>all children in the receiver's widget tree should be skinned</dd> + * <dt><b>SWT.NONE</b></dt> + * <dd>only the receiver should be skinned</dd> + * </dl> + * </p> + * @param flags the flags specifying how to reskin * - * @param flags + * @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.6 */ public void reskin (int flags) { |