diff options
Diffstat (limited to 'bundles')
97 files changed, 1429 insertions, 870 deletions
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 599affd90c..9b6138c573 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 @@ -60,7 +60,7 @@ public class Accessible { /** * Adds the listener to the collection of listeners who will - * be notifed when an accessible client asks for certain strings, + * be notified when an accessible client asks for certain strings, * such as name, description, help, or keyboard shortcut. The * listener is notified by sending it one of the messages defined * in the <code>AccessibleListener</code> interface. @@ -84,7 +84,7 @@ public class Accessible { /** * Removes the listener from the collection of listeners who will - * be notifed when an accessible client asks for certain strings, + * be notified when an accessible client asks for certain strings, * such as name, description, help, or keyboard shortcut. * * @param listener the listener that should no longer be notified when the receiver @@ -106,7 +106,7 @@ public class Accessible { /** * Adds the listener to the collection of listeners who will - * be notifed when an accessible client asks for custom control + * be notified when an accessible client asks for custom control * specific information. The listener is notified by sending it * one of the messages defined in the <code>AccessibleControlListener</code> * interface. @@ -130,7 +130,7 @@ public class Accessible { /** * Removes the listener from the collection of listeners who will - * be notifed when an accessible client asks for custom control + * be notified when an accessible client asks for custom control * specific information. * * @param listener the listener that should no longer be notified when the receiver @@ -152,7 +152,7 @@ public class Accessible { /** * Adds the listener to the collection of listeners who will - * be notifed when an accessible client asks for custom text control + * be notified when an accessible client asks for custom text control * specific information. The listener is notified by sending it * one of the messages defined in the <code>AccessibleTextListener</code> * interface. @@ -178,7 +178,7 @@ public class Accessible { /** * Removes the listener from the collection of listeners who will - * be notifed when an accessible client asks for custom text control + * be notified when an accessible client asks for custom text control * specific information. * * @param listener the listener that should no longer be notified when the receiver 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 5f64fabdee..3bbae11237 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 @@ -57,7 +57,7 @@ public class Accessible { /** * Adds the listener to the collection of listeners who will - * be notifed when an accessible client asks for certain strings, + * be notified when an accessible client asks for certain strings, * such as name, description, help, or keyboard shortcut. The * listener is notified by sending it one of the messages defined * in the <code>AccessibleListener</code> interface. @@ -84,7 +84,7 @@ public class Accessible { /** * Adds the listener to the collection of listeners who will - * be notifed when an accessible client asks for custom control + * be notified when an accessible client asks for custom control * specific information. The listener is notified by sending it * one of the messages defined in the <code>AccessibleControlListener</code> * interface. @@ -111,7 +111,7 @@ public class Accessible { /** * Adds the listener to the collection of listeners who will - * be notifed when an accessible client asks for custom text control + * be notified when an accessible client asks for custom text control * specific information. The listener is notified by sending it * one of the messages defined in the <code>AccessibleTextListener</code> * interface. @@ -210,7 +210,7 @@ public class Accessible { } /** * Removes the listener from the collection of listeners who will - * be notifed when an accessible client asks for custom control + * be notified when an accessible client asks for custom control * specific information. * * @param listener the listener that should no longer be notified when the receiver @@ -235,7 +235,7 @@ public class Accessible { /** * Removes the listener from the collection of listeners who will - * be notifed when an accessible client asks for certain strings, + * be notified when an accessible client asks for certain strings, * such as name, description, help, or keyboard shortcut. * * @param listener the listener that should no longer be notified when the receiver @@ -260,7 +260,7 @@ public class Accessible { /** * Removes the listener from the collection of listeners who will - * be notifed when an accessible client asks for custom text control + * be notified when an accessible client asks for custom text control * specific information. * * @param listener the listener that should no longer be notified when the receiver diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java index 3291f5e408..dd0884bc52 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/carbon/org/eclipse/swt/browser/Browser.java @@ -326,10 +326,14 @@ static int eventProc(int webview, int selector, int arg0, int arg1, int arg2, in } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the window hosting the receiver should be closed. * <p> + * This notification occurs when a javascript command such as + * <code>window.close</code> gets executed by a <code>Browser</code>. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -352,10 +356,15 @@ public void addCloseWindowListener(CloseWindowListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the current location is changed or about to be changed. * <p> + * This notification typically occurs when the application navigates + * to a new location with {@link #setUrl(String)} or when the user + * activates a hyperlink. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -378,10 +387,14 @@ public void addLocationListener(LocationListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when a new window needs to be created. * <p> + * This notification occurs when a javascript command such as + * <code>window.open</code> gets executed by a <code>Browser</code>. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -404,10 +417,11 @@ public void addOpenWindowListener(OpenWindowListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when a progress is made during the loading of the current + * URL or when the loading of the current URL has been completed. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -430,10 +444,14 @@ public void addProgressListener(ProgressListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the status text is changed. * <p> + * The status text is typically displayed in the status bar of + * a browser application. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -456,10 +474,11 @@ public void addStatusTextListener(StatusTextListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when the title of the current document is available + * or has changed. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -482,10 +501,11 @@ public void addTitleListener(TitleListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when a window hosting the receiver needs to be displayed + * or hidden. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -535,6 +555,28 @@ protected void checkSubclass () { } } +/** + * Execute the specified script. + * + * <p> + * Execute a script containing javascript commands in the context of the current document. + * + * @param script the script with javascript commands + * + * @return <code>true</code> if the operation was successful and <code>false</code> otherwise + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the script is null</li> + * </ul> + * + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li> + * <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li> + * </ul> + * + * WARNING 3.1 API STILL UNDER CONSTRUCTION + * @since 3.1 + */ public boolean execute(String script) { checkWidget(); if (script == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -676,9 +718,10 @@ public void refresh() { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the window hosting the receiver should be closed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -714,9 +757,10 @@ public void removeCloseWindowListener(CloseWindowListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the current location is changed or about to be changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -752,9 +796,10 @@ public void removeLocationListener(LocationListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a new window needs to be created. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -790,9 +835,11 @@ public void removeOpenWindowListener(OpenWindowListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a progress is made during the loading of the current + * URL or when the loading of the current URL has been completed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -828,9 +875,10 @@ public void removeProgressListener(ProgressListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the status text is changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -866,9 +914,11 @@ public void removeStatusTextListener(StatusTextListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the title of the current document is available + * or has changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -904,9 +954,11 @@ public void removeTitleListener(TitleListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a window hosting the receiver needs to be displayed + * or hidden. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -944,6 +996,11 @@ public void removeVisibilityWindowListener(VisibilityWindowListener listener) { /** * Renders HTML. * + * <p> + * The html parameter is Unicode encoded since it is a java <code>String</code>. + * As a result, the HTML meta tag charset should not be set. The charset is implied + * by the <code>String</code> itself. + * * @param html the HTML content to be rendered * * @return true if the operation was successful and false otherwise. diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java index 6beaf478d7..cfddb2ea03 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/motif/org/eclipse/swt/browser/Browser.java @@ -345,10 +345,14 @@ public Browser(Composite parent, int style) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the window hosting the receiver should be closed. * <p> + * This notification occurs when a javascript command such as + * <code>window.close</code> gets executed by a <code>Browser</code>. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -371,10 +375,15 @@ public void addCloseWindowListener(CloseWindowListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the current location is changed or about to be changed. * <p> + * This notification typically occurs when the application navigates + * to a new location with {@link #setUrl(String)} or when the user + * activates a hyperlink. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -397,10 +406,14 @@ public void addLocationListener(LocationListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when a new window needs to be created. * <p> + * This notification occurs when a javascript command such as + * <code>window.open</code> gets executed by a <code>Browser</code>. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -423,10 +436,11 @@ public void addOpenWindowListener(OpenWindowListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when a progress is made during the loading of the current + * URL or when the loading of the current URL has been completed. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -449,10 +463,14 @@ public void addProgressListener(ProgressListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the status text is changed. * <p> + * The status text is typically displayed in the status bar of + * a browser application. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -475,10 +493,11 @@ public void addStatusTextListener(StatusTextListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when the title of the current document is available + * or has changed. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -501,10 +520,11 @@ public void addTitleListener(TitleListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when a window hosting the receiver needs to be displayed + * or hidden. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -717,6 +737,28 @@ void disposeCOMInterfaces() { } } +/** + * Execute the specified script. + * + * <p> + * Execute a script containing javascript commands in the context of the current document. + * + * @param script the script with javascript commands + * + * @return <code>true</code> if the operation was successful and <code>false</code> otherwise + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the script is null</li> + * </ul> + * + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li> + * <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li> + * </ul> + * + * WARNING 3.1 API STILL UNDER CONSTRUCTION + * @since 3.1 + */ public boolean execute(String script) { checkWidget(); if (script == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -1032,9 +1074,10 @@ public void refresh() { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the window hosting the receiver should be closed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1070,9 +1113,10 @@ public void removeCloseWindowListener(CloseWindowListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the current location is changed or about to be changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1108,9 +1152,10 @@ public void removeLocationListener(LocationListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a new window needs to be created. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1146,9 +1191,11 @@ public void removeOpenWindowListener(OpenWindowListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a progress is made during the loading of the current + * URL or when the loading of the current URL has been completed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1184,9 +1231,10 @@ public void removeProgressListener(ProgressListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the status text is changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1222,9 +1270,11 @@ public void removeStatusTextListener(StatusTextListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the title of the current document is available + * or has changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1260,9 +1310,11 @@ public void removeTitleListener(TitleListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a window hosting the receiver needs to be displayed + * or hidden. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1300,6 +1352,11 @@ public void removeVisibilityWindowListener(VisibilityWindowListener listener) { /** * Renders HTML. * + * <p> + * The html parameter is Unicode encoded since it is a java <code>String</code>. + * As a result, the HTML meta tag charset should not be set. The charset is implied + * by the <code>String</code> itself. + * * @param html the HTML content to be rendered * * @return true if the operation was successful and false otherwise. diff --git a/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java b/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java index 6588b203a5..8fdba821d7 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Browser/photon/org/eclipse/swt/browser/Browser.java @@ -176,10 +176,14 @@ static int webProc(int handle, int data, int info) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the window hosting the receiver should be closed. * <p> + * This notification occurs when a javascript command such as + * <code>window.close</code> gets executed by a <code>Browser</code>. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -202,10 +206,15 @@ public void addCloseWindowListener(CloseWindowListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the current location is changed or about to be changed. * <p> + * This notification typically occurs when the application navigates + * to a new location with {@link #setUrl(String)} or when the user + * activates a hyperlink. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -228,10 +237,14 @@ public void addLocationListener(LocationListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when a new window needs to be created. * <p> + * This notification occurs when a javascript command such as + * <code>window.open</code> gets executed by a <code>Browser</code>. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -254,10 +267,11 @@ public void addOpenWindowListener(OpenWindowListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when a progress is made during the loading of the current + * URL or when the loading of the current URL has been completed. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -280,10 +294,14 @@ public void addProgressListener(ProgressListener listener) { } /** - * Adds the listener to receive events. + * Adds the listener to the collection of listeners who will be + * notified when the status text is changed. * <p> + * The status text is typically displayed in the status bar of + * a browser application. + * </p> * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -306,10 +324,11 @@ public void addStatusTextListener(StatusTextListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when the title of the current document is available + * or has changed. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -332,10 +351,11 @@ public void addTitleListener(TitleListener listener) { } /** - * Adds the listener to receive events. - * <p> + * Adds the listener to the collection of listeners who will be + * notified when a window hosting the receiver needs to be displayed + * or hidden. * - * @param listener the listener + * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -407,6 +427,28 @@ protected void checkSubclass() { } } +/** + * Execute the specified script. + * + * <p> + * Execute a script containing javascript commands in the context of the current document. + * + * @param script the script with javascript commands + * + * @return <code>true</code> if the operation was successful and <code>false</code> otherwise + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the script is null</li> + * </ul> + * + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li> + * <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li> + * </ul> + * + * WARNING 3.1 API STILL UNDER CONSTRUCTION + * @since 3.1 + */ public boolean execute(String script) { checkWidget(); if (script == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -766,9 +808,10 @@ public void refresh() { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the window hosting the receiver should be closed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -804,9 +847,10 @@ public void removeCloseWindowListener(CloseWindowListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the current location is changed or about to be changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -842,9 +886,10 @@ public void removeLocationListener(LocationListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a new window needs to be created. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -880,9 +925,11 @@ public void removeOpenWindowListener(OpenWindowListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a progress is made during the loading of the current + * URL or when the loading of the current URL has been completed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -918,9 +965,10 @@ public void removeProgressListener(ProgressListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the status text is changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -956,9 +1004,11 @@ public void removeStatusTextListener(StatusTextListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when the title of the current document is available + * or has changed. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -994,9 +1044,11 @@ public void removeTitleListener(TitleListener listener) { } /** - * Removes the listener. + * Removes the listener from the collection of listeners who will + * be notified when a window hosting the receiver needs to be displayed + * or hidden. * - * @param listener the listener + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1034,6 +1086,11 @@ public void removeVisibilityWindowListener(VisibilityWindowListener listener) { /** * Renders HTML. * + * <p> + * The html parameter is Unicode encoded since it is a java <code>String</code>. + * As a result, the HTML meta tag charset should not be set. The charset is implied + * by the <code>String</code> itself. + * * @param html the HTML content to be rendered * * @return true if the operation was successful and false otherwise. diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DragSource.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DragSource.java index e96c5ea2fa..5e2ccf12e7 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DragSource.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/DragSource.java @@ -58,9 +58,9 @@ import org.eclipse.swt.internal.carbon.Point; * // This example will allow the text to be copied or moved to the drop target * int operations = DND.DROP_MOVE | DND.DROP_COPY; * - * DragSource source = new DragSource (label, operations); + * DragSource source = new DragSource(label, operations); * source.setTransfer(types); - * source.addDragListener (new DragSourceListener() { + * source.addDragListener(new DragSourceListener() { * public void dragStart(DragSourceEvent e) { * // Only start the drag if there is actually text in the * // label - this text will be what is dropped on the target. @@ -68,7 +68,7 @@ import org.eclipse.swt.internal.carbon.Point; * event.doit = false; * } * }; - * public void dragSetData (DragSourceEvent event) { + * public void dragSetData(DragSourceEvent event) { * // A drop has been performed, so provide the data of the * // requested type. * // (Checking the type of the requested data is only diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/HTMLTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/HTMLTransfer.java index 1062a6fea9..e9251ccffd 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/HTMLTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/HTMLTransfer.java @@ -22,7 +22,7 @@ import org.eclipse.swt.internal.carbon.OS; * below:</p> * * <code><pre> - * String htmlData = "<b>Hello World</b>"; + * String htmlData = "<p>This is a paragraph of text.</p>"; * </code></pre> */ public class HTMLTransfer extends ByteArrayTransfer { @@ -43,7 +43,7 @@ public static HTMLTransfer getInstance () { } /** - * This implementation of <code>javaToNative</code> converts HTML text + * This implementation of <code>javaToNative</code> converts HTML-formatted text * represented by a java <code>String</code> to a platform specific representation. * For additional information see <code>Transfer#javaToNative</code>. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TransferData.java index be9d79bce6..41395ee9c9 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TransferData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/carbon/org/eclipse/swt/dnd/TransferData.java @@ -61,7 +61,6 @@ public class TransferData { * within the packages provided by SWT. It is not available on all * platforms and should never be accessed from application code. * </p> - * * <p>The value of result is 1 if the conversion was successful. * The value of result is 0 if the conversion failed.</p> */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Clipboard.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Clipboard.java index ebd7aa52b5..821c0f1c4c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Clipboard.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/Clipboard.java @@ -136,10 +136,12 @@ public void dispose () { } /** - * Retrieve the data of the specified type currently available on the system clipboard. Refer to the - * specific subclass of <code>Tramsfer</code> to determine the type of object returned. + * Retrieve the data of the specified type currently available on the system + * clipboard. Refer to the specific subclass of <code>Transfer</code> to + * determine the type of object returned. * - * <p>The following snippet shows text and RTF text being retrieved from the clipboard:</p> + * <p>The following snippet shows text and RTF text being retrieved from the + * clipboard:</p> * * <code><pre> * Clipboard clipboard = new Clipboard(display); @@ -152,10 +154,7 @@ public void dispose () { * clipboard.dispose(); * </code></pre> * - * @see Transfer - * * @param transfer the transfer agent for the type of data being requested - * * @return the data obtained from the clipboard or null if no data of this type is available * * @exception SWTException <ul> @@ -165,6 +164,8 @@ public void dispose () { * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if transfer is null</li> * </ul> + * + * @see Transfer */ public Object getContents(Transfer transfer) { checkWidget(); @@ -191,31 +192,36 @@ public boolean isDisposed () { } /** - * Place data of the specified type on the system clipboard. More than one type of - * data can be placed on the system clipboard at the same time. Setting the data - * clears any previous data of the same type from the system clipboard and also - * clears data of any other type currently on the system clipboard. + * Place data of the specified type on the system clipboard. More than one type + * of data can be placed on the system clipboard at the same time. Setting the + * data clears any previous data from the system clipboard, regardless of type. * * <p>NOTE: On some platforms, the data is immediately copied to the system - * clipboard but on other platforms it is provided upon request. As a result, if the - * application modifes the data object it has set on the clipboard, that modification - * may or may not be available when the data is subsequently requested.</p> + * clipboard but on other platforms it is provided upon request. As a result, + * if the application modifes the data object it has set on the clipboard, that + * modification may or may not be available when the data is subsequently + * requested.</p> * - * <p>The following snippet shows text and RTF text being set on the clipboard:</p> + * <p>The following snippet shows text and RTF text being set on the copy/paste + * clipboard: + * </p> * * <code><pre> * Clipboard clipboard = new Clipboard(display); - * String textData = "Hello World"; - * String rtfData = "{\\rtf1\\b\\i Hello World}"; - * TextTransfer textTransfer = TextTransfer.getInstance(); - * RTFTransfer rtfTransfer = RTFTransfer.getInstance(); - * clipboard.setContents(new Object[]{textData, rtfData}, new Transfer[]{textTransfer, rtfTransfer}); - * clipboard.dispose(); + * String textData = "Hello World"; + * String rtfData = "{\\rtf1\\b\\i Hello World}"; + * TextTransfer textTransfer = TextTransfer.getInstance(); + * RTFTransfer rtfTransfer = RTFTransfer.getInstance(); + * Transfer[] transfers = new Transfer[]{textTransfer, rtfTransfer}; + * Object[] data = new Object[]{textData, rtfData}; + * clipboard.setContents(data, transfers); + * clipboard.dispose(); * </code></pre> * * @param data the data to be set in the clipboard - * @param dataTypes the transfer agents that will convert the data to its platform - * specific format; each entry in the data array must have a corresponding dataType + * @param dataTypes the transfer agents that will convert the data to its + * platform specific format; each entry in the data array must have a + * corresponding dataType * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if data is null or datatypes is null @@ -247,10 +253,10 @@ public void setContents(Object[] data, Transfer[] dataTypes) { } /** - * Returns an array of the data types currently available on the system clipboard. Use - * with Transfer.isSupportedType. + * Returns an array of the data types currently available on the system + * clipboard. Use with Transfer.isSupportedType. * - * @return array of TransferData + * @return array of data types currently available on teh system clipboard * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/HTMLTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/HTMLTransfer.java index c1c1cf94f8..f106b5ec2d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/HTMLTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/HTMLTransfer.java @@ -20,7 +20,7 @@ package org.eclipse.swt.dnd; * below:</p> * * <code><pre> - * String htmlData = "<b>Hello World</b>"; + * String htmlData = "<p>This is a paragraph of text.</p>"; * </code></pre> */ public class HTMLTransfer extends ByteArrayTransfer { @@ -42,7 +42,7 @@ public static HTMLTransfer getInstance () { return _instance; } /** - * This implementation of <code>javaToNative</code> converts HTML text + * This implementation of <code>javaToNative</code> converts HTML-formatted text * represented by a java <code>String</code> to a platform specific representation. * For additional information see <code>Transfer#javaToNative</code>. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TransferData.java index 551760eadc..90f673c5a1 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TransferData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/emulated/org/eclipse/swt/dnd/TransferData.java @@ -47,7 +47,12 @@ public class TransferData { * The result field contains the result of converting a * java data type into a platform specific value. * (Warning: This field is platform dependent) - * + * <p> + * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT + * public API. It is marked public only so that it can be shared + * within the packages provided by SWT. It is not available on all + * platforms and should never be accessed from application code. + * </p> * <p>The value of result is 1 if the conversion was successful. * The value of result is 0 if the conversion failed.</p> */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/FileTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/FileTransfer.java index cdc0db6e86..4e7d6fd757 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/FileTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/FileTransfer.java @@ -13,7 +13,7 @@ package org.eclipse.swt.dnd; import org.eclipse.swt.internal.gtk.*; /** - * The class <code>er</code> provides a platform specific mechanism + * The class <code>FileTransfer</code> provides a platform specific mechanism * for converting a list of files represented as a java <code>String[]</code> to a * platform specific representation of the data and vice versa. * Each <code>String</code> in the array contains the absolute path for a single diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/HTMLTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/HTMLTransfer.java index 6acd4146c8..953e5eed73 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/HTMLTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/HTMLTransfer.java @@ -22,7 +22,7 @@ import org.eclipse.swt.internal.gtk.*; * below:</p> * * <code><pre> - * String htmlData = "<b>Hello World</b>"; + * String htmlData = "<p>This is a paragraph of text.</p>"; * </code></pre> */ public class HTMLTransfer extends ByteArrayTransfer { @@ -45,7 +45,7 @@ public static HTMLTransfer getInstance () { } /** - * This implementation of <code>javaToNative</code> converts HTML text + * This implementation of <code>javaToNative</code> converts HTML-formatted text * represented by a java <code>String</code> to a platform specific representation. * For additional information see <code>Transfer#javaToNative</code>. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TransferData.java index b397cc7a03..86ad69572e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TransferData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/gtk/org/eclipse/swt/dnd/TransferData.java @@ -88,7 +88,6 @@ public class TransferData { * within the packages provided by SWT. It is not available on all * platforms and should never be accessed from application code. * </p> - * * <p>The value of result is 1 if the conversion was successful. * The value of result is 0 if the conversion failed.</p> */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/HTMLTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/HTMLTransfer.java index 35068c4804..48db94cedb 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/HTMLTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/HTMLTransfer.java @@ -22,7 +22,7 @@ import org.eclipse.swt.internal.motif.*; * below:</p> * * <code><pre> - * String htmlData = "<b>Hello World</b>"; + * String htmlData = "<p>This is a paragraph of text.</p>"; * </code></pre> */ public class HTMLTransfer extends ByteArrayTransfer { @@ -45,7 +45,7 @@ public static HTMLTransfer getInstance () { } /** - * This implementation of <code>javaToNative</code> converts HTML text + * This implementation of <code>javaToNative</code> converts HTML-formatted text * represented by a java <code>String</code> to a platform specific representation. * For additional information see <code>Transfer#javaToNative</code>. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TransferData.java index 293db24763..37ceb039c8 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TransferData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/motif/org/eclipse/swt/dnd/TransferData.java @@ -88,7 +88,6 @@ public class TransferData { * within the packages provided by SWT. It is not available on all * platforms and should never be accessed from application code. * </p> - * * <p>The value of result is 1 if the conversion was successful. * The value of result is 0 if the conversion failed.</p> */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/HTMLTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/HTMLTransfer.java index bb7eb44b73..e77b833909 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/HTMLTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/HTMLTransfer.java @@ -18,10 +18,12 @@ import org.eclipse.swt.internal.photon.OS; * for converting text in HTML format represented as a java <code>String</code> * to a platform specific representation of the data and vice versa. See * <code>Transfer</code> for additional information. + * + * <p>An example of a java <code>String</code> containing HTML text is shown * below:</p> * * <code><pre> - * String htmlData = "<b>Hello World</b>"; + * String htmlData = "<p>This is a paragraph of text.</p>"; * </code></pre> */ public class HTMLTransfer extends ByteArrayTransfer { @@ -41,7 +43,7 @@ public static HTMLTransfer getInstance () { return _instance; } /** - * This implementation of <code>javaToNative</code> converts HTML text + * This implementation of <code>javaToNative</code> converts HTML-formatted text * represented by a java <code>String</code> to a platform specific representation. * For additional information see <code>Transfer#javaToNative</code>. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TransferData.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TransferData.java index 0c496a187f..97869a10f5 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TransferData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/photon/org/eclipse/swt/dnd/TransferData.java @@ -73,7 +73,6 @@ public class TransferData { * within the packages provided by SWT. It is not available on all * platforms and should never be accessed from application code. * </p> - * * <p>The value of result is 1 if the conversion was successful. * The value of result is 0 if the conversion failed.</p> */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/win32/org/eclipse/swt/dnd/HTMLTransfer.java b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/win32/org/eclipse/swt/dnd/HTMLTransfer.java index 6ca81cfa89..7450b1b547 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/win32/org/eclipse/swt/dnd/HTMLTransfer.java +++ b/bundles/org.eclipse.swt/Eclipse SWT Drag and Drop/win32/org/eclipse/swt/dnd/HTMLTransfer.java @@ -37,7 +37,7 @@ private HTMLTransfer() {} /** * Returns the singleton instance of the HTMLTransfer class. * - * @return the singleton instance of `the HTMLTransfer class + * @return the singleton instance of the HTMLTransfer class */ public static HTMLTransfer getInstance () { return _instance; 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 2ebf6a8d11..d68eea5d3d 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 @@ -131,8 +131,8 @@ public static Program [] getPrograms () { * @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> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> */ public static boolean launch (String fileName) { if (fileName == null) SWT.error (SWT.ERROR_NULL_ARGUMENT); @@ -197,8 +197,8 @@ static String[] parseCommand(String cmd) { * @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> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> */ public boolean execute (String fileName) { if (fileName == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); 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 46f0f035a0..09149ae602 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 @@ -797,8 +797,8 @@ static Program[] getPrograms(Display display) { * @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> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> */ public static boolean launch(String fileName) { return launch(Display.getCurrent(), fileName); @@ -854,8 +854,8 @@ public boolean equals(Object other) { * @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> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> */ public boolean execute(String fileName) { if (fileName == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); 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 89364d72a5..d5c46ee796 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 @@ -830,8 +830,8 @@ static Program[] getPrograms(Display display) { * @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> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> */ public static boolean launch(String fileName) { return launch(Display.getCurrent(), fileName); @@ -887,8 +887,8 @@ public boolean equals(Object other) { * @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> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> */ public boolean execute(String fileName) { if (fileName == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); 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 55dc8622a5..7d1bd91310 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 @@ -166,8 +166,8 @@ public static Program [] getPrograms () { * @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> + * <li>ERROR_NULL_ARGUMENT when fileName is null</li> + * </ul> */ public static boolean launch (String fileName) { if (fileName == null) SWT.error (SWT.ERROR_NULL_ARGUMENT); @@ -274,7 +274,7 @@ static String [][] loadAssociationTable () { * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT when fileName is null</li> - * </ul> + * </ul> */ public boolean execute (String fileName) { if (fileName == null) SWT.error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java index da95d873d2..99145ac815 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 @@ -462,7 +462,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 0053a6aa57..229cb084ab 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 @@ -45,8 +45,7 @@ import org.eclipse.swt.events.*; * <dd>DefaultSelection, Modify, Selection</dd> * </dl> * <p> - * Note: Only one of the styles DROP_DOWN and SIMPLE - * may be specified. + * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> @@ -122,9 +121,6 @@ public Combo (Composite parent, int style) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String,int) */ @@ -154,9 +150,6 @@ public void add (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String) */ @@ -615,9 +608,6 @@ GdkColor getForegroundColor () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String getItem (int index) { checkWidget(); @@ -636,9 +626,6 @@ public String getItem (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget(); @@ -655,9 +642,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemHeight () { checkWidget(); @@ -679,9 +663,6 @@ public int getItemHeight () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String [] getItems () { checkWidget(); @@ -796,9 +777,6 @@ String getText (int start, int stop) { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getTextHeight () { checkWidget(); @@ -827,6 +805,10 @@ public int getTextLimit () { /** * Gets the number of items that are visible in the drop * down portion of the receiver's list. + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @return the number of items that are visible * @@ -1056,9 +1038,6 @@ void releaseHandle () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -1099,9 +1078,6 @@ public void remove (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -1147,9 +1123,6 @@ public void remove (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (String string) { checkWidget(); @@ -1160,7 +1133,8 @@ public void remove (String string) { } /** - * Removes all of the items from the receiver's list. + * Removes all of the items from the receiver's list and clear the + * contents of receiver's text field. * <p> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1229,7 +1203,7 @@ public void removeSelectionListener (SelectionListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is verified. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1333,10 +1307,6 @@ void setForegroundColor (GdkColor color) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li> - * <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li> - * </ul> */ public void setItem (int index, String string) { checkWidget(); @@ -1368,9 +1338,6 @@ public void setItem (int index, String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItems (String [] items) { checkWidget(); @@ -1540,6 +1507,10 @@ public void setTextLimit (int limit) { /** * Sets the number of items that are visible in the drop * down portion of the receiver's list. + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @param count the new number of items to be visible * 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 e1bf1243b4..f76133fb8c 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 @@ -373,6 +373,7 @@ boolean forceFocus (int /*long*/ focusHandle) { /** * Returns an array containing the receiver's children. + * Children are returned in the order that they are drawn. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of children, so modifying the array will @@ -380,6 +381,9 @@ boolean forceFocus (int /*long*/ focusHandle) { * </p> * * @return an array of children + * + * @see Control#moveAbove + * @see Control#moveBelow * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -995,7 +999,7 @@ public void setLayout (Layout layout) { * </ul> * * @see #layout(boolean) - * @see #layout(Control) + * @see #layout(Control[]) * * @since 3.1 */ 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 691c136810..23ac1c78d9 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 @@ -753,7 +753,8 @@ public void setSize (int width, int height) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #moveBelow + * @see Control#moveBelow + * @see Composite#getChildren */ public void moveAbove (Control control) { checkWidget(); @@ -781,7 +782,8 @@ public void moveAbove (Control control) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #moveAbove + * @see Control#moveAbove + * @see Composite#getChildren */ public void moveBelow (Control control) { checkWidget(); @@ -1189,7 +1191,7 @@ public void addTraverseListener (TraverseListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1213,7 +1215,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control gains or loses focus. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1237,7 +1239,7 @@ public void removeFocusListener(FocusListener listener) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1260,7 +1262,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when keys are pressed and released on the system keyboard. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1284,7 +1286,7 @@ public void removeKeyListener(KeyListener listener) { * Removes the listener from the collection of listeners who will * be notified when mouse buttons are pressed and released. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1309,7 +1311,7 @@ public void removeMouseListener (MouseListener listener) { * Removes the listener from the collection of listeners who will * be notified when the mouse moves. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1333,7 +1335,7 @@ public void removeMouseMoveListener(MouseMoveListener listener) { * Removes the listener from the collection of listeners who will * be notified when the mouse passes or hovers over controls. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1359,7 +1361,7 @@ public void removeMouseTrackListener(MouseTrackListener listener) { * Removes the listener from the collection of listeners who will * be notified when the receiver needs to be painted. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1383,7 +1385,7 @@ public void removePaintListener(PaintListener listener) { * Removes the listener from the collection of listeners who will * be notified when traversal events occur. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -2197,9 +2199,10 @@ boolean isTabItem () { /** * Returns <code>true</code> if the receiver is enabled and all - * of the receiver's ancestors are enabled, and <code>false</code> - * otherwise. A disabled control is typically not selectable from the - * user interface and draws with an inactive or "grayed" look. + * ancestors up to and including the receiver's nearest ancestor + * shell are enabled. Otherwise, <code>false</code> is returned. + * A disabled control is typically not selectable from the user + * interface and draws with an inactive or "grayed" look. * * @return the receiver's enabled state * @@ -2240,8 +2243,8 @@ public boolean isFocusControl () { /** * Returns <code>true</code> if the receiver is visible and all - * of the receiver's ancestors are visible and <code>false</code> - * otherwise. + * ancestors up to and including the receiver's nearest ancestor + * shell are visible. Otherwise, <code>false</code> is returned. * * @return the receiver's visibility state * @@ -2852,7 +2855,8 @@ boolean setRadioSelection (boolean value) { * can occur in the receiver until the flag is set to true. * Graphics operations that occurred while the flag was * <code>false</code> are lost. When the flag is set to <code>true</code>, - * the entire widget is marked as needing to be redrawn. + * the entire widget is marked as needing to be redrawn. Nested calls + * to this method are stacked. * <p> * Note: This operation is a hint and may not be supported on some * platforms or for some widgets. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java index dc00d55f9c..25975db0bf 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java @@ -566,7 +566,7 @@ public void setImage (Image image) { * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the array of images is null</li> - * <li>ERROR_INVALID_ARGUMENT - if one of the images has been disposed</li> + * <li>ERROR_INVALID_ARGUMENT - if one of the images is null or has been disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java index 5e04c80033..b47655265c 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 @@ -422,9 +422,19 @@ public Display (DeviceData data) { /** * Adds the listener to the collection of listeners who will * be notifed when an event of the given type occurs anywhere - * in this display. When the event does occur, the listener is + * in a widget. When the event does occur, the listener is * notified by sending it the <code>handleEvent()</code> message. - * + * <p> + * Setting the type of an event to <code>SWT.None</code> from + * within the <code>handleEvent()</code> method can be used to + * change the event type and stop subsequent Java listeners + * from running. Because event filters run before other listeners, + * event filters can both block other listeners and set arbitrary + * fields within an event. For this reason, event filters are both + * powerful and dangerous. They should generally be avoided for + * performance, debugging and code maintenance reasons. + * </p> + * * @param eventType the type of event to listen for * @param listener the listener which should be notified when the event occurs * @@ -943,6 +953,10 @@ int /*long*/ eventProc (int /*long*/ event, int /*long*/ data) { * the instance of the <code>Widget</code> subclass which * represents it in the currently running application, if * such exists, or null if no matching widget can be found. + * <p> + * <b>IMPORTANT:</b> This method should not be called from + * application code. The arguments are platform-specific. + * </p> * * @param handle the handle for the widget * @return the SWT widget that the handle represents @@ -957,6 +971,28 @@ public Widget findWidget (int /*long*/ handle) { return getWidget (handle); } +/** + * Given the operating system handle for a widget, + * and widget-specific id, returns the instance of + * the <code>Widget</code> subclass which represents + * the handle/id pair in the currently running application, + * if such exists, or null if no matching widget can be found. + * <p> + * <b>IMPORTANT:</b> This method should not be called from + * application code. The arguments are platform-specific. + * </p> + * + * @param handle the handle for the widget + * @param id the id for the subwidget (usually an item) + * @return the SWT widget that the handle/id pair represents + * + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public Widget findWidget (int /*long*/ handle, int id) { return null; } @@ -1180,8 +1216,8 @@ public Point [] getCursorSizes () { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #setData(String, Object) + * @see #disposeExec(Runnable) */ public Object getData (String key) { checkDevice (); @@ -1216,8 +1252,8 @@ public Object getData (String key) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #setData(Object) + * @see #disposeExec(Runnable) */ public Object getData () { checkDevice (); @@ -1843,9 +1879,10 @@ public Font getSystemFont () { } /** - * Returns the single instance of the system tray. + * Returns the single instance of the system tray or null + * when there is no system tray available for the platform. * - * @return the receiver's user-interface thread + * @return the system tray or <code>null</code> * * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> @@ -1995,12 +2032,12 @@ public void internal_dispose_GC (int /*long*/ gdkGC, GCData data) { * @param data the platform specific GC data * @return the platform specific GC handle * - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li> + * </ul> */ public int /*long*/ internal_new_GC (GCData data) { if (isDisposed()) SWT.error(SWT.ERROR_DEVICE_DISPOSED); @@ -2052,7 +2089,7 @@ boolean isValidThread () { * @return point with mapped coordinates * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> * <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> * </ul> * @exception SWTException <ul> @@ -2272,7 +2309,12 @@ int /*long*/ mouseHoverProc (int /*long*/ handle) { * and mouse events. The intent is to enable automated UI * testing by simulating the input from the user. Most * SWT applications should never need to call this method. - * + * <p> + * Note that this operation can fail when the operating system + * fails to generate the event for any reason. For example, + * this can happen when there is no such key or mouse button + * or when the system event queue is full. + * </p> * <p> * <b>Event Types:</b> * <p>KeyDown, KeyUp @@ -2415,6 +2457,7 @@ void putGdkEvents () { * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li> * </ul> * * @see #sleep @@ -2608,7 +2651,7 @@ void releaseDisplay () { /** * Removes the listener from the collection of listeners who will * be notifed when an event of the given type occurs anywhere in - * this display. + * a widget. * * @param eventType the type of event to listen for * @param listener the listener which should no longer be notified when the event occurs @@ -2842,8 +2885,8 @@ public void setCursorLocation (Point point) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #getData(String) + * @see #disposeExec(Runnable) */ public void setData (String key, Object value) { checkDevice (); @@ -2921,8 +2964,8 @@ public void setData (String key, Object value) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #getData - * @see #disposeExec + * @see #getData() + * @see #disposeExec(Runnable) */ public void setData (Object data) { checkDevice (); @@ -2949,6 +2992,7 @@ int setDirectionProc (int widget, int direction) { * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li> * </ul> */ public void setSynchronizer (Synchronizer synchronizer) { @@ -3232,7 +3276,7 @@ static int untranslateKey (int key) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see Control#update + * @see Control#update() */ public void update () { checkDevice (); 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 615417ca5a..207b435663 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 @@ -16,6 +16,20 @@ import org.eclipse.swt.graphics.*; import org.eclipse.swt.events.*; /** + * Instances of this class represent a selectable + * user interface object that displays a text with + * links. + * <p> + * <dl> + * <dt><b>Styles:</b></dt> + * <dt><b>Events:</b></dt> + * <dd>Selection</dd> + * </dl> + * <p> + * IMPORTANT: This class is <em>not</em> intended to be subclassed. + * </p> + * + * @since 3.1 */ public class Link extends Control { String text; @@ -567,6 +581,15 @@ void setFontDescription (int /*long*/ font) { /** * Sets the receiver's text. * <p> + * The string can contain both regular text and hyperlinks. A hyperlink + * is delimited by an anchor tag, <A> and </A>. Within an + * anchor, a single HREF attribute is supported. When a hyperlink is + * selected, the text field of the selection event contains either the + * text of hyperlink or the value of the HREF, if one was specified. + * In the rare case of identical hyperlinks within the same string, the + * HREF tag can be used to distinguish between them. The string may + * include the mnemonic character and line delimiters. + * </p> * * @param string the new text * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java index 97f7767736..4d409a2e11 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java @@ -84,9 +84,6 @@ public List (Composite parent, int style) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String,int) */ @@ -121,9 +118,6 @@ public void add (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String) */ @@ -386,9 +380,6 @@ GdkColor getForegroundColor () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String getItem (int index) { checkWidget(); @@ -417,9 +408,6 @@ public String getItem (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget(); @@ -436,9 +424,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemHeight () { checkWidget(); @@ -474,10 +459,6 @@ public int getItemHeight () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li> - * </ul> */ public String [] getItems () { checkWidget(); @@ -515,10 +496,6 @@ public String [] getItems () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure while getting the selection</li> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * </ul> */ public String [] getSelection () { checkWidget(); @@ -539,9 +516,6 @@ public String [] getSelection () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getSelectionCount () { checkWidget(); @@ -562,9 +536,6 @@ public int getSelectionCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li> - * </ul> */ public int getSelectionIndex () { checkWidget(); @@ -591,9 +562,6 @@ public int getSelectionIndex () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li> - * </ul> */ public int [] getSelectionIndices () { checkWidget(); @@ -771,10 +739,6 @@ public int indexOf (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * </ul> */ public int indexOf (String string, int start) { checkWidget(); @@ -838,9 +802,6 @@ void releaseWidget () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -871,9 +832,6 @@ public void remove (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -908,9 +866,6 @@ public void remove (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (String string) { checkWidget(); @@ -934,9 +889,6 @@ public void remove (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int [] indices) { checkWidget(); @@ -1216,10 +1168,6 @@ void setForegroundColor (GdkColor color) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li> - * <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li> - * </ul> */ public void setItem (int index, String string) { checkWidget(); @@ -1247,9 +1195,6 @@ public void setItem (int index, String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItems (String [] items) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java index 8b30a8e73f..6d897bf8ab 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java @@ -721,7 +721,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the menu events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -754,7 +754,7 @@ void removeAccelerators (int /*long*/ accelGroup) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 4f9279722c..29089d6325 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 @@ -510,7 +510,7 @@ void removeAccelerators (int /*long*/ accelGroup) { * Removes the listener from the collection of listeners who will * be notified when the arm events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -534,7 +534,7 @@ public void removeArmListener (ArmListener listener) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -558,7 +558,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Sash.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Sash.java index 6be9f079e1..1bd9693324 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Sash.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Sash.java @@ -22,7 +22,7 @@ import org.eclipse.swt.events.*; * the parent control. * <dl> * <dt><b>Styles:</b></dt> - * <dd>HORIZONTAL, VERTICAL</dd> + * <dd>HORIZONTAL, VERTICAL, SMOOTH</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -390,7 +390,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java index 7fd19d857a..c26b47ef8f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java @@ -213,7 +213,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the <em>selection</em>, which is the receiver's position. * * @return the selection * @@ -348,8 +348,8 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal + * Sets the <em>selection</em>, which is the receiver's + * value, to the argument which must be greater than or equal * to zero. * * @param value the new selection (must be zero or greater) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java index 11ae2aa765..b53daad0ad 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 @@ -101,7 +101,6 @@ ScrollBar (Scrollable parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java index 148989475e..c6acc4856d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java @@ -650,6 +650,21 @@ public Point getLocation () { return new Point (x [0], y [0]); } +/** + * Returns a point describing the minimum receiver's size. The + * x coordinate of the result is the minimum width of the receiver. + * The y coordinate of the result is the minimum height of the + * receiver. + * + * @return the receiver's size + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public Point getMinimumSize () { checkWidget (); int width = Math.max (1, minWidth + trimWidth ()); @@ -916,11 +931,11 @@ public void removeShellListener (ShellListener listener) { } /** - * Moves the receiver to the top of the drawing order for - * the display on which it was created (so that all other - * shells on that display, which are not the receiver's - * children will be drawn behind it) and asks the window - * manager to make the shell active. + * If the receiver is visible, moves it to the top of the + * drawing order for the display on which it was created + * (so that all other shells on that display, which are not + * the receiver's children will be drawn behind it) and asks + * the window manager to make the shell active * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1192,6 +1207,21 @@ public void setMinimized (boolean minimized) { } } +/** + * Sets the receiver's minimum size to the point specified by the arguments. + * If the new minimum size is larger than the current size of the receiver, + * the receiver is resized to the new minimum size. + * + * @param width the new minimum width for the receiver + * @param height the new minimum height for the receiver + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public void setMinimumSize (int width, int height) { checkWidget (); GdkGeometry geometry = new GdkGeometry (); @@ -1200,6 +1230,23 @@ public void setMinimumSize (int width, int height) { OS.gtk_window_set_geometry_hints (shellHandle, 0, geometry, OS.GDK_HINT_MIN_SIZE); } +/** + * Sets the receiver's minimum size to the point specified by the argument. + * If the new minimum size is larger than the current size of the receiver, + * the receiver is resized to the new minimum size. + * + * @param size the new minimum size for the receiver + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public void setMinimumSize (Point size) { checkWidget (); if (size == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -1417,11 +1464,11 @@ public void dispose () { } /** - * Moves the receiver to the top of the drawing order for - * the display on which it was created (so that all other - * shells on that display, which are not the receiver's - * children will be drawn behind it) and forces the window - * manager to make the shell active. + * If the receiver is visible, moves it to the top of the + * drawing order for the display on which it was created + * (so that all other shells on that display, which are not + * the receiver's children will be drawn behind it) and forces + * the window manager to make the shell active. * * @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/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java index ae536f769d..b6d89f6b9a 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 @@ -272,7 +272,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's value. + * Returns the <em>selection</em>, which is the receiver's value. * * @return the selection * @@ -435,8 +435,8 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal + * Sets the <em>selection</em>, which is the receiver's + * value, to the argument which must be greater than or equal * to zero. * * @param value the new selection (must be zero or greater) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java index 91ba8c4b88..3c069d49fd 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 @@ -19,7 +19,8 @@ import org.eclipse.swt.events.*; /** * Instances of this class are selectable user interface - * objects that allow the user to enter and modify number + * objects that allow the user to enter and modify numeric + * values. * <p> * <dl> * <dt><b>Styles:</b></dt> @@ -30,6 +31,8 @@ import org.eclipse.swt.events.*; * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @since 3.1 */ public class Spinner extends Composite { static final int INNER_BORDER = 2; @@ -370,9 +373,8 @@ public int getMinimum () { } /** - * Returns the amount that the receiver's value will be - * modified by when the page increment/decrement areas - * are selected. + * Returns the amount that the receiver's position will be + * modified by when the page up/down keys are pressed. * * @return the page increment * @@ -390,7 +392,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the <em>selection</em>, which is the receiver's position. * * @return the selection * @@ -590,7 +592,7 @@ public void removeModifyListener (ModifyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -658,11 +660,10 @@ void setForegroundColor (GdkColor color) { /** * Sets the amount that the receiver's value will be - * modified by when the up/down (or right/left) arrows - * are pressed to the argument, which must be at least - * one. + * modified by when the up/down arrows are pressed to + * the argument, which must be at least one. * - * @param increment the new increment (must be greater than zero) + * @param value the new increment (must be greater than zero) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -724,12 +725,11 @@ public void setMinimum (int value) { } /** - * Sets the amount that the receiver's value will be - * modified by when the page increment/decrement areas - * are selected to the argument, which must be at least - * one. + * Sets the amount that the receiver's position will be + * modified by when the page up/down keys are pressed + * to the argument, which must be at least one. * - * @param pageIncrement the page increment (must be greater than zero) + * @param value the page increment (must be greater than zero) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -745,9 +745,10 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal - * to zero. + * Sets the <em>selection</em>, which is the receiver's + * position, to the argument. If the argument is not within + * the range specified by minimum and maximum, it will be + * adjusted to fall within this range. * * @param value the new selection (must be zero or greater) * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java index bf1b2645bc..d4c79242b8 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TabFolder.java @@ -627,6 +627,9 @@ void setSelection (int index, boolean notify) { * * @param items the array of items * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the items array 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> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java index 578d4cdb37..666a8c2e7c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java @@ -20,7 +20,7 @@ import org.eclipse.swt.events.*; /** * Instances of this class implement a selectable user interface * object that displays a list of images and strings and issue - * notificiation when selected. + * notification when selected. * <p> * The item children that may be added to instances of this class * must be of type <code>TableItem</code>. @@ -218,7 +218,7 @@ public Point computeSize (int wHint, int hHint, boolean changed) { /** * Clears the item at the given zero-relative index in the receiver. - * The text, icon and other attribues of the item are set to the default + * The text, icon and other attributes of the item are set to the default * value. If the table was created with the SWT.VIRTUAL style, these * attributes are requested again as needed. * @@ -265,7 +265,7 @@ public void clear (int index) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -303,7 +303,7 @@ public void clear (int start, int end) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -334,7 +334,7 @@ public void clear (int [] indices) { * </ul> * * @see SWT#VIRTUAL - * @see SWT.SetData + * @see SWT#SetData * * @since 3.0 */ @@ -865,7 +865,7 @@ public TableColumn getColumn (int index) { * Returns the number of columns contained in the receiver. * If no <code>TableColumn</code>s were created by the programmer, * this value is zero, despite the fact that visually, one column - * of items is may be visible. This occurs when the programmer uses + * of items may be visible. This occurs when the programmer uses * the table like a list, adding items but never creating a column. * * @return the number of columns @@ -874,9 +874,6 @@ public TableColumn getColumn (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getColumnCount () { checkWidget(); @@ -902,7 +899,7 @@ int /*long*/[] getColumnTypes (int columnCount) { return types; } - /** +/** * Returns an array of zero-relative integers that map * the creation order of the receiver's items to the * order in which they are currently being displayed. @@ -923,6 +920,11 @@ int /*long*/[] getColumnTypes (int columnCount) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * + * @see Table#setColumnOrder(int[]) + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move + * * @since 3.1 */ public int [] getColumnOrder () { @@ -1734,9 +1736,6 @@ void releaseWidget () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -1775,9 +1774,6 @@ public void remove (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -1817,9 +1813,6 @@ public void remove (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int [] indices) { checkWidget(); @@ -2134,7 +2127,7 @@ boolean setCellData(int /*long*/ tree_model, int /*long*/ iter) { * in terms of the zero-relative ordering of when the items * were added. * - * @param itemOrder the new order to display the items + * @param order the new order to display the items * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2144,7 +2137,12 @@ boolean setCellData(int /*long*/ tree_model, int /*long*/ iter) { * <li>ERROR_NULL_ARGUMENT - if the item order is null</li> * <li>ERROR_INVALID_ARGUMENT - if the item order is not the same length as the number of items</li> * </ul> - * + * + * @see Table#getColumnOrder() + * @see TableColumn#getMoveable() + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move + * * @since 3.1 */ public void setColumnOrder (int [] order) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java index 156b9d5c39..2557c5c56c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableColumn.java @@ -231,6 +231,8 @@ public int getAlignment () { * * @see Table#getColumnOrder() * @see Table#setColumnOrder(int[]) + * @see TableColumn#setMoveable(boolean) + * @see SWT#Move * * @since 3.1 */ @@ -400,7 +402,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -425,7 +427,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -492,8 +494,10 @@ public void setImage (Image image) { /** * Sets the resizable attribute. A column that is - * not resizable cannot be dragged by the user but - * may be resized by the programmer. + * resizable can be resized by the user dragging the + * edge of the header. A column that is not resizable + * cannot be dragged by the user but may be resized + * by the programmer. * * @param resizable the resize attribute * @@ -523,6 +527,8 @@ public void setResizable (boolean resizable) { * * @see Table#setColumnOrder(int[]) * @see Table#getColumnOrder() + * @see TableColumn#getMoveable() + * @see SWT#Move * * @since 3.1 */ 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 2170b57342..79ad3f5dce 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 @@ -540,9 +540,6 @@ public String getText () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_TEXT - if the column at index does not exist</li> - * </ul> */ public String getText (int index) { checkWidget (); @@ -913,7 +910,7 @@ public void setImage (Image image) { } /** - * Sets the image for multiple columns in the Table. + * Sets the image for multiple columns in the table. * * @param images the array of new images * @@ -944,6 +941,8 @@ public void setImage (Image [] images) { * <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> + * + * @deprecated this functionality is not supported on most platforms */ public void setImageIndent (int indent) { checkWidget (); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java index a8b0ec7627..d1bd0ea31f 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 @@ -1212,7 +1212,7 @@ public void removeModifyListener (ModifyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1237,7 +1237,7 @@ public void removeSelectionListener(SelectionListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is verified. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 75dc108e4a..2f2768a6b9 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 @@ -637,7 +637,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -936,7 +936,7 @@ public void setToolTipText (String string) { } /** - * Sets the width of the receiver. + * Sets the width of the receiver, for <code>SEPARATOR</code> ToolItems. * * @param width the new width * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java index f394df210b..12af331fe2 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tracker.java @@ -730,7 +730,7 @@ public boolean open () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -755,7 +755,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when keys are pressed and released on the system keyboard. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java index 095176d07c..d00c1ebcd8 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java @@ -30,7 +30,7 @@ import org.eclipse.swt.events.*; * </p><p> * <dl> * <dt><b>Styles:</b></dt> - * <dd>SINGLE, MULTI, CHECK</dd> + * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION</dd> * <dt><b>Events:</b></dt> * <dd>Selection, DefaultSelection, Collapse, Expand</dd> * </dl> @@ -677,10 +677,10 @@ GdkColor getBackgroundColor () { /** * Returns the column at the given, zero-relative index in the * receiver. Throws an exception if the index is out of range. - * If no <code>TableColumn</code>s were created by the programmer, + * If no <code>TreeColumn</code>s were created by the programmer, * this method will throw <code>ERROR_INVALID_RANGE</code> despite - * the fact that a single column of data may be visible in the table. - * This occurs when the programmer uses the table like a list, adding + * the fact that a single column of data may be visible in the tree. + * This occurs when the programmer uses the tree like a list, adding * items but never creating a column. * * @param index the index of the column to return @@ -693,7 +693,7 @@ GdkColor getBackgroundColor () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public TreeColumn getColumn (int index) { @@ -704,10 +704,10 @@ public TreeColumn getColumn (int index) { /** * Returns the number of columns contained in the receiver. - * If no <code>TableColumn</code>s were created by the programmer, + * If no <code>TreeColumn</code>s were created by the programmer, * this value is zero, despite the fact that visually, one column - * of items is may be visible. This occurs when the programmer uses - * the table like a list, adding items but never creating a column. + * of items may be visible. This occurs when the programmer uses + * the tree like a list, adding items but never creating a column. * * @return the number of columns * @@ -715,10 +715,7 @@ public TreeColumn getColumn (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> - * + * * @since 3.1 */ public int getColumnCount () { @@ -747,11 +744,11 @@ int /*long*/[] getColumnTypes (int columnCount) { } /** - * Returns an array of <code>TableColumn</code>s which are the - * columns in the receiver. If no <code>TableColumn</code>s were + * Returns an array of <code>TreeColumn</code>s which are the + * columns in the receiver. If no <code>TreeColumn</code>s were * created by the programmer, the array is empty, despite the fact * that visually, one column of items may be visible. This occurs - * when the programmer uses the table like a list, adding items but + * when the programmer uses the tree like a list, adding items but * never creating a column. * <p> * Note: This is not the actual structure used by the receiver @@ -765,7 +762,7 @@ int /*long*/[] getColumnTypes (int columnCount) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public TreeColumn [] getColumns () { @@ -804,7 +801,7 @@ GdkColor getForegroundColor () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public int getGridLineWidth () { @@ -822,7 +819,7 @@ public int getGridLineWidth () { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @since 3.1 + * @since 3.1 */ public int getHeaderHeight () { checkWidget (); @@ -853,7 +850,7 @@ public int getHeaderHeight () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public boolean getHeaderVisible () { @@ -1027,7 +1024,7 @@ TreeItem [] getItems (int /*long*/ parent) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public boolean getLinesVisible() { @@ -1734,8 +1731,8 @@ void setForegroundColor (GdkColor color) { * <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> - * - * @since3.1 + * + * @since 3.1 */ public void setHeaderVisible (boolean show) { checkWidget (); @@ -1757,7 +1754,7 @@ public void setHeaderVisible (boolean show) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public void setLinesVisible (boolean show) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeColumn.java index 3e5591cad1..907718e239 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeColumn.java @@ -18,7 +18,7 @@ import org.eclipse.swt.graphics.*; import org.eclipse.swt.events.*; /** - * Instances of this class represent a column in a table widget. + * Instances of this class represent a column in a tree widget. * <dl> * <dt><b>Styles:</b></dt> * <dd>LEFT, RIGHT, CENTER</dd> @@ -30,6 +30,8 @@ import org.eclipse.swt.events.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @since 3.1 */ public class TreeColumn extends Item { int /*long*/ labelHandle, imageHandle, buttonHandle; @@ -39,7 +41,7 @@ public class TreeColumn extends Item { /** * Constructs a new instance of this class given its parent - * (which must be a <code>Table</code>) and a style value + * (which must be a <code>Tree</code>) and a style value * describing its behavior and appearance. The item is added * to the end of the items maintained by its parent. * <p> @@ -77,7 +79,7 @@ public TreeColumn (Tree parent, int style) { /** * Constructs a new instance of this class given its parent - * (which must be a <code>Table</code>), a style value + * (which must be a <code>Tree</code>), a style value * describing its behavior and appearance, and the index * at which to place it in the items maintained by its parent. * <p> @@ -216,7 +218,7 @@ public int getAlignment () { } /** - * Returns the receiver's parent, which must be a <code>Table</code>. + * Returns the receiver's parent, which must be a <code>Tree</code>. * * @return the receiver's parent * @@ -376,7 +378,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -401,7 +403,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 6a42bfa392..e1e604b6c8 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 @@ -198,7 +198,7 @@ protected void checkSubclass () { * Returns the receiver's background color. * * @return the background color - * + * * @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> @@ -247,7 +247,7 @@ public Color getBackground (int index) { /** * Returns a rectangle describing the receiver's size and location - * relative to its parent at a column in the table. + * relative to its parent at a column in the tree. * * @param index the index that specifies the column * @return the receiver's bounding column rectangle @@ -256,7 +256,7 @@ public Color getBackground (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public Rectangle getBounds (int index) { @@ -395,9 +395,10 @@ public Rectangle getBounds () { /** * Returns <code>true</code> if the receiver is checked, * and false otherwise. When the parent does not have - * the <code>CHECK</code> style, return false. + * the <code>CHECK style, return false. + * <p> * - * @return the checked state of the checkbox + * @return the checked state * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -530,10 +531,10 @@ public Color getForeground (int index) { /** * Returns <code>true</code> if the receiver is grayed, * and false otherwise. When the parent does not have - * the <code>CHECK</code> style, return false. + * the <code>CHECK style, return false. * <p> * - * @return the grayed state of the checkbox + * @return the grayed state * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -566,8 +567,8 @@ public Image getImage () { * <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> - * - * @since3.1 + * + * @since 3.1 */ public Image getImage (int index) { checkWidget (); @@ -589,7 +590,7 @@ public Image getImage (int index) { /** * Returns a rectangle describing the size and location * relative to its parent of an image at a column in the - * tree. + * table. * * @param index the index that specifies the column * @return the receiver's bounding image rectangle @@ -598,7 +599,7 @@ public Image getImage (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public Rectangle getImageBounds (int index) { @@ -764,10 +765,7 @@ public String getText () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_TEXT - if the column at index does not exist</li> - * </ul> - * + * * @since 3.1 */ public String getText (int index) { @@ -808,7 +806,7 @@ void releaseWidget () { * if the argument is null. * * @param color the new color (or null) - * + * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> @@ -1023,6 +1021,8 @@ 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> @@ -1127,7 +1127,7 @@ public void setGrayed (boolean grayed) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public void setImage (int index, Image image) { @@ -1158,7 +1158,7 @@ public void setImage (Image image) { } /** - * Sets the image for multiple columns in the Tree. + * Sets the image for multiple columns in the tree. * * @param images the array of new images * @@ -1170,7 +1170,7 @@ public void setImage (Image image) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public void setImage (Image [] images) { @@ -1194,7 +1194,7 @@ public void setImage (Image [] images) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * + * * @since 3.1 */ public void setText (int index, String string) { @@ -1216,7 +1216,7 @@ public void setText (String string) { } /** - * Sets the text for multiple columns in the table. + * Sets the text for multiple columns in the tree. * * @param strings the array of new strings * @@ -1227,8 +1227,8 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * - * @since3.1 + * + * @since 3.1 */ public void setText (String [] strings) { checkWidget (); 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 d9ef42029f..a08559851e 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 @@ -189,8 +189,7 @@ public Cursor (Device device, int style) { * <li>ERROR_NULL_ARGUMENT - if the source is null</li> * <li>ERROR_NULL_ARGUMENT - if the mask is null and the source does not have a mask</li> * <li>ERROR_INVALID_ARGUMENT - if the source and the mask are not the same - * size, or either is not of depth one, or if the hotspot is outside - * the bounds of the image</li> + * size, or if the hotspot is outside the bounds of the image</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li> 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 4529847792..42a47c5496 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 @@ -363,12 +363,12 @@ public void drawFocus (int x, int y, int width, int height) { * <li>ERROR_NULL_ARGUMENT - if the image is null</li> * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li> * <li>ERROR_INVALID_ARGUMENT - if the given coordinates are outside the bounds of the image</li> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> + * </ul> */ public void drawImage(Image image, int x, int y) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -402,12 +402,12 @@ public void drawImage(Image image, int x, int y) { * <li>ERROR_INVALID_ARGUMENT - if any of the width or height arguments are negative. * <li>ERROR_INVALID_ARGUMENT - if the source rectangle is not contained within the bounds of the source image</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> + * </ul> */ public void drawImage(Image image, int srcX, int srcY, int srcWidth, int srcHeight, int destX, int destY, int destWidth, int destHeight) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -796,6 +796,9 @@ public void drawOval(int x, int y, int width, int height) { } OS.XDrawArc(data.display, data.drawable, handle, x, y, width, height, 0, 23040); } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void drawPath(Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path.handle == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT); @@ -995,14 +998,16 @@ public void drawRectangle (Rectangle rect) { * right edges of the rectangle are at <code>x</code> and <code>x + width</code>. * The top and bottom edges are at <code>y</code> and <code>y + height</code>. * The <em>roundness</em> of the corners is specified by the - * <code>arcWidth</code> and <code>arcHeight</code> arguments. + * <code>arcWidth</code> and <code>arcHeight</code> arguments, which + * are respectively the width and height of the ellipse used to draw + * the corners. * * @param x the x coordinate of the rectangle to be drawn * @param y the y coordinate of the rectangle to be drawn * @param width the width of the rectangle to be drawn * @param height the height of the rectangle to be drawn - * @param arcWidth the horizontal diameter of the arc at the four corners - * @param arcHeight the vertical diameter of the arc at the four corners + * @param arcWidth the width of the arc + * @param arcHeight the height of the arc * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1546,6 +1551,9 @@ public void fillOval (int x, int y, int width, int height) { OS.XFillArc (display, data.drawable, handle, x, y, width, height, 0, 23040); OS.XSetForeground (display, handle, values.foreground); } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void fillPath (Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path.handle == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT); @@ -1679,8 +1687,8 @@ public void fillRectangle (Rectangle rect) { * @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 arcWidth the horizontal diameter of the arc at the four corners - * @param arcHeight the vertical diameter of the arc at the four corners + * @param arcWidth the width of the arc + * @param arcHeight the height of the arc * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1922,6 +1930,9 @@ public int getAdvanceWidth(char ch) { OS.XmFontListFreeFontContext(context); return 0; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public int getAlpha() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); initCairo(); @@ -2147,6 +2158,7 @@ public Rectangle getClipping() { * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the region is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the region is disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -2454,6 +2466,19 @@ public Color getForeground() { return Color.motif_new(data.device, xColor); } +/** + * Returns the receiver's line cap style, which will be one + * of the constants <code>SWT.CAP_FLAT</code>, <code>SWT.CAP_ROUND</code>, + * or <code>SWT.CAP_SQUARE</code>. + * + * @return the cap style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int getLineCap() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); XGCValues values = new XGCValues(); @@ -2466,6 +2491,17 @@ public int getLineCap() { } return cap; } +/** + * Returns the receiver's line dash style. + * + * @return the lin dash style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int[] getLineDash() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); byte[] dash_list = data.dashes; @@ -2476,6 +2512,19 @@ public int[] getLineDash() { } return dashes; } +/** + * Returns the receiver's line join style, which will be one + * of the constants <code>SWT.JOIN_MITER</code>, <code>SWT.JOIN_ROUND</code>, + * or <code>SWT.JOIN_BEVEL</code>. + * + * @return the join style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int getLineJoin() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); XGCValues values = new XGCValues(); @@ -2544,6 +2593,9 @@ public int getStyle () { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); return data.style; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void getTransform(Transform transform) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (transform == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -2691,6 +2743,9 @@ boolean isIdentity(int /*long*/ matrix) { Cairo.cairo_matrix_get_affine(matrix, a, b, c, d, tx, ty); return a[0] == 1 && b[0] == 0 && c[0] == 0 && d[0] == 1 && tx[0] == 0 && ty[0] == 0; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setAlpha(int alpha) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); initCairo(); @@ -2846,6 +2901,9 @@ public void setClipping (int x, int y, int width, int height) { setClipping(clipRgn); OS.XDestroyRegion(clipRgn); } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setClipping(Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path != null && path.isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2883,10 +2941,10 @@ public void setClipping (Rectangle rect) { * by the argument. * * @param region the clipping region. - * - * * @exception IllegalArgumentException <ul> + * + * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li> - * </ul> + * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> @@ -2966,6 +3024,22 @@ public void setForeground (Color color) { Cairo.cairo_set_rgb_color(cairo, (xColor.red & 0xFFFF) / (float)0xFFFF, (xColor.green & 0xFFFF) / (float)0xFFFF, (xColor.blue & 0xFFFF) / (float)0xFFFF); } } +/** + * Sets the receiver's line cap style to the argument, which must be one + * of the constants <code>SWT.CAP_FLAT</code>, <code>SWT.CAP_ROUND</code>, + * or <code>SWT.CAP_SQUARE</code>. + * + * @param cap the cap style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineCap(int cap) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); int cap_style = 0, cairo_style = 0; @@ -2995,6 +3069,20 @@ public void setLineCap(int cap) { Cairo.cairo_set_line_cap(cairo, cairo_style); } } +/** + * Sets the receiver's line dash style to the argument. + * + * @param dashes the dash style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the values in the array is less than or equal 0</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineDash(int[] dashes) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); int xDisplay = data.display; @@ -3029,6 +3117,22 @@ public void setLineDash(int[] dashes) { } } } +/** + * Sets the receiver's line join style to the argument, which must be one + * of the constants <code>SWT.JOIN_MITER</code>, <code>SWT.JOIN_ROUND</code>, + * or <code>SWT.JOIN_BEVEL</code>. + * + * @param join the join style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineJoin(int join) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); int join_style = 0, cairo_style = 0; @@ -3066,6 +3170,9 @@ public void setLineJoin(int join) { * * @param lineStyle the style to be used for drawing lines * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> @@ -3181,6 +3288,9 @@ void setText(String string, int flags) { data.textWidth = data.textHeight = -1; data.drawFlags = flags; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setTransform(Transform transform) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (transform == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); 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 3e90e524ce..2744c57bc3 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 @@ -520,12 +520,12 @@ public Image(Device device, Rectangle bounds) { * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * <li>ERROR_NULL_ARGUMENT - if the image data is null</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the ImageData is not supported</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> + * </ul> */ public Image(Device device, ImageData image) { if (device == null) device = Device.getDevice(); @@ -536,10 +536,8 @@ public Image(Device device, ImageData image) { /** * Constructs an instance of this class, whose type is * <code>SWT.ICON</code>, from the two given <code>ImageData</code> - * objects. The two images must be the same size, and the mask image - * must have a color depth of 1. Pixel transparency in either image - * will be ignored. If either image is an icon to begin with, an - * exception is thrown. + * objects. The two images must be the same size. Pixel transparency + * in either image will be ignored. * <p> * The mask image should contain white wherever the icon is to be visible, * and black wherever the icon is to be transparent. In addition, @@ -554,9 +552,7 @@ public Image(Device device, ImageData image) { * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * <li>ERROR_NULL_ARGUMENT - if either the source or mask is null </li> - * <li>ERROR_INVALID_ARGUMENT - if source and mask are different sizes or - * if the mask is not monochrome, or if either the source or mask - * is already an icon</li> + * <li>ERROR_INVALID_ARGUMENT - if source and mask are different sizes</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> @@ -581,7 +577,8 @@ public Image(Device device, ImageData source, ImageData mask) { * Constructs an instance of this class by loading its representation * from the specified input stream. Throws an error if an error * occurs while loading the image, or if the result is an image - * of an unsupported type. + * of an unsupported type. Application code is still responsible + * for closing the input stream. * <p> * This constructor is provided for convenience when loading a single * image only. If the stream contains multiple images, only the first @@ -605,7 +602,8 @@ public Image(Device device, ImageData source, ImageData mask) { * <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li> * <li>ERROR_IO - if an IO error occurs while reading data</li> * <li>ERROR_UNSUPPORTED_DEPTH - if the InputStream describes an image with an unsupported depth</li> - * </ul> + * <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li> + * * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> * </ul> @@ -637,6 +635,7 @@ public Image(Device device, InputStream stream) { * <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li> * <li>ERROR_IO - if an IO error occurs while reading data</li> * <li>ERROR_UNSUPPORTED_DEPTH - if the image file has an unsupported depth</li> + * <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> 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 ebe8d69f0f..be128407fb 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 @@ -60,12 +60,12 @@ public Region () { * * @param device the device on which to allocate the region * -* @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li> - * </ul> * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li> + * </ul> * * @see #dispose * @@ -133,9 +133,13 @@ public void add (Rectangle rect) { * Adds the given rectangle to the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to merge with the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> * </ul> * @exception SWTException <ul> @@ -297,7 +301,10 @@ public void intersect (Rectangle rect) { * Intersects the given rectangle to the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to intersect with the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> @@ -468,9 +475,13 @@ public void subtract (Rectangle rect) { * Subtracts the given rectangle from the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to subtract from the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> * </ul> * @exception SWTException <ul> @@ -536,7 +547,7 @@ public void translate (int x, int y) { * Translate all of the polygons the receiver maintains to describe * its area by the specified point. * - * @param point the point to translate + * @param pt the point to translate * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> 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 5074ce7d33..258c320eac 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 @@ -276,6 +276,9 @@ public void dispose () { * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the gc is null</li> + * </ul> */ public void draw (GC gc, int x, int y) { draw(gc, x, y, -1, -1, null, null); @@ -296,6 +299,9 @@ public void draw (GC gc, int x, int y) { * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the gc is null</li> + * </ul> */ public void draw(GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground) { checkLayout(); @@ -869,6 +875,7 @@ public int getNextOffset (int offset, int movement) { * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the trailing length is less than <code>1</code></li> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1262,7 +1269,7 @@ public void setAlignment (int alignment) { * </ul> * * @see #setDescent(int) - * @see #getLineMetrics() + * @see #getLineMetrics(int) */ public void setAscent (int ascent) { checkLayout(); @@ -1288,7 +1295,7 @@ public void setAscent (int ascent) { * </ul> * * @see #setAscent(int) - * @see #getLineMetrics() + * @see #getLineMetrics(int) */ public void setDescent (int descent) { checkLayout(); 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 04a18b36dd..18e05cae56 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 @@ -469,7 +469,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 9418671e9a..b9524a545c 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 @@ -45,8 +45,7 @@ import org.eclipse.swt.events.*; * <dd>DefaultSelection, Modify, Selection</dd> * </dl> * <p> - * Note: Only one of the styles DROP_DOWN and SIMPLE - * may be specified. + * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> @@ -117,9 +116,6 @@ public Combo (Composite parent, int style) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String,int) */ @@ -153,9 +149,6 @@ public void add (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String) */ @@ -501,9 +494,6 @@ public void deselectAll () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String getItem (int index) { checkWidget(); @@ -542,9 +532,6 @@ public String getItem (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget(); @@ -562,9 +549,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemHeight () { checkWidget(); @@ -591,9 +575,6 @@ public int getItemHeight () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String [] getItems () { checkWidget(); @@ -729,9 +710,6 @@ public String getText () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getTextHeight () { checkWidget(); @@ -788,6 +766,10 @@ public int getTextLimit () { /** * Gets the number of items that are visible in the drop * down portion of the receiver's list. + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @return the number of items that are visible * @@ -935,9 +917,6 @@ public void paste () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -974,9 +953,6 @@ public void remove (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -1016,9 +992,6 @@ void register () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (String string) { checkWidget(); @@ -1038,7 +1011,8 @@ public void remove (String string) { } } /** - * Removes all of the items from the receiver's list. + * Removes all of the items from the receiver's list and clear the + * contents of receiver's text field. * <p> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1109,7 +1083,7 @@ public void removeSelectionListener (SelectionListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is verified. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1250,10 +1224,6 @@ void setForegroundPixel (int pixel) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li> - * <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li> - * </ul> */ public void setItem (int index, String string) { checkWidget(); @@ -1285,9 +1255,6 @@ public void setItem (int index, String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItems (String [] items) { checkWidget(); @@ -1476,6 +1443,10 @@ public void setTextLimit (int limit) { /** * Sets the number of items that are visible in the drop * down portion of the receiver's list. + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @param count the new number of items to be visible * 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 22cebaebaf..b3830dc41e 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 @@ -345,6 +345,7 @@ boolean fowardKeyEvent (int event) { } /** * Returns an array containing the receiver's children. + * Children are returned in the order that they are drawn. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of children, so modifying the array will @@ -352,6 +353,9 @@ boolean fowardKeyEvent (int event) { * </p> * * @return an array of children + * + * @see Control#moveAbove + * @see Control#moveBelow * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -982,7 +986,7 @@ public void setLayout (Layout layout) { * </ul> * * @see #layout(boolean) - * @see #layout(Control) + * @see #layout(Control[]) * * @since 3.1 */ 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 cf961bbf27..ec2294a475 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 @@ -1146,9 +1146,10 @@ public void internal_dispose_GC (int xGC, GCData data) { } /** * Returns <code>true</code> if the receiver is enabled and all - * of the receiver's ancestors are enabled, and <code>false</code> - * otherwise. A disabled control is typically not selectable from the - * user interface and draws with an inactive or "grayed" look. + * ancestors up to and including the receiver's nearest ancestor + * shell are enabled. Otherwise, <code>false</code> is returned. + * A disabled control is typically not selectable from the user + * interface and draws with an inactive or "grayed" look. * * @return the receiver's enabled state * @@ -1238,8 +1239,8 @@ boolean isTabItem () { } /** * Returns <code>true</code> if the receiver is visible and all - * of the receiver's ancestors are visible and <code>false</code> - * otherwise. + * ancestors up to and including the receiver's nearest ancestor + * shell are visible. Otherwise, <code>false</code> is returned. * * @return the receiver's visibility state * @@ -1291,7 +1292,8 @@ boolean mnemonicMatch (char key) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #moveBelow + * @see Control#moveBelow + * @see Composite#getChildren */ public void moveAbove (Control control) { checkWidget(); @@ -1318,7 +1320,8 @@ public void moveAbove (Control control) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #moveAbove + * @see Control#moveAbove + * @see Composite#getChildren */ public void moveBelow (Control control) { checkWidget(); @@ -1496,7 +1499,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1520,7 +1523,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control gains or loses focus. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1544,7 +1547,7 @@ public void removeFocusListener(FocusListener listener) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1567,7 +1570,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when keys are pressed and released on the system keyboard. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1591,7 +1594,7 @@ public void removeKeyListener(KeyListener listener) { * Removes the listener from the collection of listeners who will * be notified when mouse buttons are pressed and released. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1616,7 +1619,7 @@ public void removeMouseListener(MouseListener listener) { * Removes the listener from the collection of listeners who will * be notified when the mouse moves. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1639,7 +1642,7 @@ public void removeMouseMoveListener(MouseMoveListener listener) { * Removes the listener from the collection of listeners who will * be notified when the mouse passes or hovers over controls. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1664,7 +1667,7 @@ public void removeMouseTrackListener(MouseTrackListener listener) { * Removes the listener from the collection of listeners who will * be notified when the receiver needs to be painted. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1686,7 +1689,7 @@ public void removePaintListener(PaintListener listener) { * Removes the listener from the collection of listeners who will * be notified when traversal events occur. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -2258,7 +2261,8 @@ boolean setRadioSelection (boolean value) { * can occur in the receiver until the flag is set to true. * Graphics operations that occurred while the flag was * <code>false</code> are lost. When the flag is set to <code>true</code>, - * the entire widget is marked as needing to be redrawn. + * the entire widget is marked as needing to be redrawn. Nested calls + * to this method are stacked. * <p> * Note: This operation is a hint and may not be supported on some * platforms or for some widgets. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java index bd26cea07a..87442923ab 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Decorations.java @@ -274,6 +274,33 @@ public Image getImage () { checkWidget(); return image; } +/** + * Returns the receiver's images if they had previously been + * set using <code>setImages()</code>. Images are typically + * displayed by the window manager when the instance is + * marked as iconified, and may also be displayed somewhere + * in the trim when the instance is in normal or maximized + * states. Depending where the icon is displayed, the platform + * chooses the icon with the "best" size. It is expected that + * the array will contain the same icon rendered at different + * resolutions. + * + * <p> + * Note: This method will return an empty array if called before + * <code>setImages()</code> is called. It does not provide + * access to a window manager provided, "default" image + * even if one exists. + * </p> + * + * @return the images + * + * @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 Image [] getImages () { checkWidget (); if (images == null) return new Image [0]; @@ -495,7 +522,7 @@ public void setImage (Image image) { * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the array of images is null</li> - * <li>ERROR_INVALID_ARGUMENT - if one of the images has been disposed</li> + * <li>ERROR_INVALID_ARGUMENT - if one of the images is null or has been disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Display.java index 19d70263e4..56e9261ed7 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 @@ -455,9 +455,19 @@ void addWidget (int handle, Widget widget) { /** * Adds the listener to the collection of listeners who will * be notifed when an event of the given type occurs anywhere - * in this display. When the event does occur, the listener is + * in a widget. When the event does occur, the listener is * notified by sending it the <code>handleEvent()</code> message. - * + * <p> + * Setting the type of an event to <code>SWT.None</code> from + * within the <code>handleEvent()</code> method can be used to + * change the event type and stop subsequent Java listeners + * from running. Because event filters run before other listeners, + * event filters can both block other listeners and set arbitrary + * fields within an event. For this reason, event filters are both + * powerful and dangerous. They should generally be avoided for + * performance, debugging and code maintenance reasons. + * </p> + * * @param eventType the type of event to listen for * @param listener the listener which should be notified when the event occurs * @@ -955,6 +965,10 @@ boolean filterEvent (int event) { * the instance of the <code>Widget</code> subclass which * represents it in the currently running application, if * such exists, or null if no matching widget can be found. + * <p> + * <b>IMPORTANT:</b> This method should not be called from + * application code. The arguments are platform-specific. + * </p> * * @param handle the handle for the widget * @return the SWT widget that the handle represents @@ -968,6 +982,28 @@ public Widget findWidget (int handle) { checkDevice (); return getWidget (handle); } +/** + * Given the operating system handle for a widget, + * and widget-specific id, returns the instance of + * the <code>Widget</code> subclass which represents + * the handle/id pair in the currently running application, + * if such exists, or null if no matching widget can be found. + * <p> + * <b>IMPORTANT:</b> This method should not be called from + * application code. The arguments are platform-specific. + * </p> + * + * @param handle the handle for the widget + * @param id the id for the subwidget (usually an item) + * @return the SWT widget that the handle/id pair represents + * + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public Widget findWidget (int handle, int id) { return null; } @@ -1248,8 +1284,8 @@ public static synchronized Display getDefault () { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #setData(String, Object) + * @see #disposeExec(Runnable) */ public Object getData (String key) { checkDevice (); @@ -1283,8 +1319,8 @@ public Object getData (String key) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #setData(Object) + * @see #disposeExec(Runnable) */ public Object getData () { checkDevice (); @@ -1781,9 +1817,10 @@ public Image getSystemImage (int style) { return Image.motif_new (this, SWT.ICON, imagePixmap, maskPixmap); } /** - * Returns the single instance of the system tray. + * Returns the single instance of the system tray or null + * when there is no system tray available for the platform. * - * @return the receiver's user-interface thread + * @return the system tray or <code>null</code> * * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> @@ -2252,12 +2289,12 @@ void initializeWidgetTable () { * @param data the platform specific GC data * @return the platform specific GC handle * - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li> + * </ul> */ public int internal_new_GC (GCData data) { if (isDisposed()) SWT.error(SWT.ERROR_DEVICE_DISPOSED); @@ -2330,7 +2367,7 @@ static boolean isValidClass (Class clazz) { * @return point with mapped coordinates * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> * <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> * </ul> * @exception SWTException <ul> @@ -2511,7 +2548,12 @@ int mouseHoverProc (int handle, int id) { * and mouse events. The intent is to enable automated UI * testing by simulating the input from the user. Most * SWT applications should never need to call this method. - * + * <p> + * Note that this operation can fail when the operating system + * fails to generate the event for any reason. For example, + * this can happen when there is no such key or mouse button + * or when the system event queue is full. + * </p> * <p> * <b>Event Types:</b> * <p>KeyDown, KeyUp @@ -2635,6 +2677,7 @@ void postEvent (Event event) { * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li> * </ul> * * @see #sleep @@ -2883,7 +2926,7 @@ Widget removeWidget (int handle) { /** * Removes the listener from the collection of listeners who will * be notifed when an event of the given type occurs anywhere in - * this display. + * a widget. * * @param eventType the type of event to listen for * @param listener the listener which should no longer be notified when the event occurs @@ -3094,8 +3137,8 @@ void setCurrentCaret (Caret caret) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #getData(String) + * @see #disposeExec(Runnable) */ public void setData (String key, Object value) { checkDevice (); @@ -3164,8 +3207,8 @@ public void setData (String key, Object value) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #getData - * @see #disposeExec + * @see #getData() + * @see #disposeExec(Runnable) */ public void setData (Object data) { checkDevice (); @@ -3183,6 +3226,7 @@ public void setData (Object data) { * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li> * </ul> */ public void setSynchronizer (Synchronizer synchronizer) { @@ -3448,7 +3492,7 @@ static int untranslateKey (int key) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see Control#update + * @see Control#update() */ public void update () { checkDevice (); 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 1380553a61..169ba05810 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 @@ -16,6 +16,20 @@ import org.eclipse.swt.graphics.*; import org.eclipse.swt.events.*; /** + * Instances of this class represent a selectable + * user interface object that displays a text with + * links. + * <p> + * <dl> + * <dt><b>Styles:</b></dt> + * <dt><b>Events:</b></dt> + * <dd>Selection</dd> + * </dl> + * <p> + * IMPORTANT: This class is <em>not</em> intended to be subclassed. + * </p> + * + * @since 3.1 */ public class Link extends Control { String text; @@ -391,6 +405,15 @@ void setForegroundPixel (int pixel) { /** * Sets the receiver's text. * <p> + * The string can contain both regular text and hyperlinks. A hyperlink + * is delimited by an anchor tag, <A> and </A>. Within an + * anchor, a single HREF attribute is supported. When a hyperlink is + * selected, the text field of the selection event contains either the + * text of hyperlink or the value of the HREF, if one was specified. + * In the rare case of identical hyperlinks within the same string, the + * HREF tag can be used to distinguish between them. The string may + * include the mnemonic character and line delimiters. + * </p> * * @param string the new text * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java index a6cc903ea8..c9534e33a0 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/List.java @@ -87,9 +87,6 @@ public List (Composite parent, int style) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String,int) */ @@ -122,9 +119,6 @@ public void add (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String) */ @@ -424,9 +418,6 @@ public int getFocusIndex () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String getItem (int index) { checkWidget(); @@ -465,9 +456,6 @@ public String getItem (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget(); @@ -485,9 +473,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemHeight () { checkWidget(); @@ -516,10 +501,6 @@ public int getItemHeight () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li> - * </ul> */ public String [] getItems () { checkWidget(); @@ -566,10 +547,6 @@ public String [] getItems () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure while getting the selection</li> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * </ul> */ public String [] getSelection () { checkWidget(); @@ -610,9 +587,6 @@ public String [] getSelection () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getSelectionCount () { checkWidget(); @@ -630,9 +604,6 @@ public int getSelectionCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li> - * </ul> */ public int getSelectionIndex () { checkWidget(); @@ -661,9 +632,6 @@ public int getSelectionIndex () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li> - * </ul> */ public int [] getSelectionIndices () { checkWidget(); @@ -748,10 +716,6 @@ public int indexOf (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * </ul> */ public int indexOf (String string, int start) { checkWidget(); @@ -809,9 +773,6 @@ void overrideTranslations () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -844,9 +805,6 @@ public void remove (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -874,9 +832,6 @@ public void remove (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (String string) { checkWidget(); @@ -903,9 +858,6 @@ public void remove (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int [] indices) { checkWidget(); @@ -1271,10 +1223,6 @@ public void setFont (Font font) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li> - * <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li> - * </ul> */ public void setItem (int index, String string) { checkWidget(); @@ -1306,9 +1254,6 @@ public void setItem (int index, String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItems (String [] items) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java index 81c1d0c331..48cc247152 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Menu.java @@ -633,7 +633,7 @@ void removeAccelerators () { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -656,7 +656,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when the menu events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 e9fe65207c..a2ba19f5bc 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 @@ -535,7 +535,7 @@ void removeAccelerators () { * Removes the listener from the collection of listeners who will * be notified when the arm events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -558,7 +558,7 @@ public void removeArmListener (ArmListener listener) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -581,7 +581,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Sash.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Sash.java index 85306094a8..7d7e771063 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Sash.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Sash.java @@ -22,7 +22,7 @@ import org.eclipse.swt.events.*; * the parent control. * <dl> * <dt><b>Styles:</b></dt> - * <dd>HORIZONTAL, VERTICAL</dd> + * <dd>HORIZONTAL, VERTICAL, SMOOTH</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -188,7 +188,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java index a82806d039..a84776d6be 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Scale.java @@ -203,7 +203,7 @@ public int getPageIncrement () { return argList [1]; } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the <em>selection</em>, which is the receiver's position. * * @return the selection * @@ -347,8 +347,8 @@ public void setPageIncrement (int pageIncrement) { display.setWarnings (warnings); } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal + * Sets the <em>selection</em>, which is the receiver's + * value, to the argument which must be greater than or equal * to zero. * * @param value the new selection (must be zero or greater) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/ScrollBar.java index 76dfe87ac8..ac15c88d14 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 @@ -96,7 +96,6 @@ ScrollBar (Scrollable parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java index ea7a668233..0a503726b2 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Shell.java @@ -735,11 +735,11 @@ void enableWidget (boolean enabled) { enableHandle (enabled, shellHandle); } /** - * Moves the receiver to the top of the drawing order for - * the display on which it was created (so that all other - * shells on that display, which are not the receiver's - * children will be drawn behind it) and forces the window - * manager to make the shell active. + * If the receiver is visible, moves it to the top of the + * drawing order for the display on which it was created + * (so that all other shells on that display, which are not + * the receiver's children will be drawn behind it) and forces + * the window manager to make the shell active. * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -882,6 +882,21 @@ public boolean getMaximized () { } return super.getMaximized (); } +/** + * Returns a point describing the minimum receiver's size. The + * x coordinate of the result is the minimum width of the receiver. + * The y coordinate of the result is the minimum height of the + * receiver. + * + * @return the receiver's size + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public Point getMinimumSize () { checkWidget (); int [] argList = {OS.XmNminWidth, 0, OS.XmNminHeight, 0}; @@ -1119,11 +1134,11 @@ public void removeShellListener(ShellListener listener) { } /** - * Moves the receiver to the top of the drawing order for - * the display on which it was created (so that all other - * shells on that display, which are not the receiver's - * children will be drawn behind it) and asks the window - * manager to make the shell active. + * If the receiver is visible, moves it to the top of the + * drawing order for the display on which it was created + * (so that all other shells on that display, which are not + * the receiver's children will be drawn behind it) and asks + * the window manager to make the shell active * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1369,6 +1384,21 @@ public void setMinimized (boolean minimized) { } } } +/** + * Sets the receiver's minimum size to the point specified by the arguments. + * If the new minimum size is larger than the current size of the receiver, + * the receiver is resized to the new minimum size. + * + * @param width the new minimum width for the receiver + * @param height the new minimum height for the receiver + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public void setMinimumSize (int width, int height) { checkWidget (); int [] argList = { @@ -1377,6 +1407,23 @@ public void setMinimumSize (int width, int height) { }; OS.XtSetValues (shellHandle, argList, argList.length / 2); } +/** + * Sets the receiver's minimum size to the point specified by the argument. + * If the new minimum size is larger than the current size of the receiver, + * the receiver is resized to the new minimum size. + * + * @param size the new minimum size for the receiver + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public void setMinimumSize (Point size) { checkWidget (); if (size == null) error (SWT.ERROR_NULL_ARGUMENT); 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 01e27cf775..7da69fafb0 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 @@ -238,7 +238,7 @@ public int getPageIncrement () { return argList [1]; } /** - * Returns the single <em>selection</em> that is the receiver's value. + * Returns the <em>selection</em>, which is the receiver's value. * * @return the selection * @@ -416,8 +416,8 @@ public void setPageIncrement (int value) { OS.XtSetValues (handle, argList, argList.length / 2); } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal + * Sets the <em>selection</em>, which is the receiver's + * value, to the argument which must be greater than or equal * to zero. * * @param value the new selection (must be zero or greater) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Spinner.java index a2f59cd651..a7d3f15411 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 @@ -19,7 +19,8 @@ import org.eclipse.swt.events.*; /** * Instances of this class are selectable user interface - * objects that allow the user to enter and modify number + * objects that allow the user to enter and modify numeric + * values. * <p> * <dl> * <dt><b>Styles:</b></dt> @@ -30,6 +31,8 @@ import org.eclipse.swt.events.*; * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @since 3.1 */ public class Spinner extends Composite { @@ -344,9 +347,8 @@ public int getMinimum () { return argList [1]; } /** - * Returns the amount that the receiver's value will be - * modified by when the page increment/decrement areas - * are selected. + * Returns the amount that the receiver's position will be + * modified by when the page up/down keys are pressed. * * @return the page increment * @@ -360,7 +362,7 @@ public int getPageIncrement () { return 1; } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the <em>selection</em>, which is the receiver's position. * * @return the selection * @@ -447,7 +449,7 @@ public void removeModifyListener (ModifyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -532,11 +534,10 @@ void setForegroundPixel (int pixel) { } /** * Sets the amount that the receiver's value will be - * modified by when the up/down (or right/left) arrows - * are pressed to the argument, which must be at least - * one. + * modified by when the up/down arrows are pressed to + * the argument, which must be at least one. * - * @param increment the new increment (must be greater than zero) + * @param value the new increment (must be greater than zero) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -598,12 +599,11 @@ public void setMinimum (int value) { OS.XtSetValues (handle, argList2, argList2.length / 2); } /** - * Sets the amount that the receiver's value will be - * modified by when the page increment/decrement areas - * are selected to the argument, which must be at least - * one. + * Sets the amount that the receiver's position will be + * modified by when the page up/down keys are pressed + * to the argument, which must be at least one. * - * @param pageIncrement the page increment (must be greater than zero) + * @param value the page increment (must be greater than zero) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -615,9 +615,10 @@ public void setPageIncrement (int value) { if (value < 1) return; } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal - * to zero. + * Sets the <em>selection</em>, which is the receiver's + * position, to the argument. If the argument is not within + * the range specified by minimum and maximum, it will be + * adjusted to fall within this range. * * @param value the new selection (must be zero or greater) * 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 5c425c5994..f35df0a7ff 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 @@ -988,7 +988,7 @@ public void removeModifyListener (ModifyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1012,7 +1012,7 @@ public void removeSelectionListener(SelectionListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is verified. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 c852bd6565..1c32f1acae 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 @@ -524,7 +524,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -803,7 +803,7 @@ void setVisible (boolean visible) { OS.XtSetMappedWhenManaged (handle, visible); } /** - * Sets the width of the receiver. + * Sets the width of the receiver, for <code>SEPARATOR</code> ToolItems. * * @param width the new width * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Tracker.java index 3b2dbc73a0..ad244a8a37 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Tracker.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/motif/org/eclipse/swt/widgets/Tracker.java @@ -479,7 +479,7 @@ public boolean open () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -503,7 +503,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when keys are pressed and released on the system keyboard. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 28833ab824..889b491e6c 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 @@ -172,8 +172,7 @@ public Cursor(Device device, int style) { * <li>ERROR_NULL_ARGUMENT - if the source is null</li> * <li>ERROR_NULL_ARGUMENT - if the mask is null and the source does not have a mask</li> * <li>ERROR_INVALID_ARGUMENT - if the source and the mask are not the same - * size, or either is not of depth one, or if the hotspot is outside - * the bounds of the image</li> + * size, or if the hotspot is outside the bounds of the image</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES - if a handle could not be obtained for cursor creation</li> 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 8a4722b810..091a685284 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 @@ -544,12 +544,12 @@ public void drawFocus (int x, int y, int width, int height) { * <li>ERROR_NULL_ARGUMENT - if the image is null</li> * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li> * <li>ERROR_INVALID_ARGUMENT - if the given coordinates are outside the bounds of the image</li> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> + * </ul> */ public void drawImage(Image image, int x, int y) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -583,12 +583,12 @@ public void drawImage(Image image, int x, int y) { * <li>ERROR_INVALID_ARGUMENT - if any of the width or height arguments are negative. * <li>ERROR_INVALID_ARGUMENT - if the source rectangle is not contained within the bounds of the source image</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES - if no handles are available to perform the operation</li> + * </ul> */ public void drawImage(Image image, int srcX, int srcY, int srcWidth, int srcHeight, int destX, int destY, int destWidth, int destHeight) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -993,6 +993,9 @@ public void drawOval (int x, int y, int width, int height) { } } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void drawPath(Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path.handle == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT); @@ -1158,14 +1161,16 @@ public void drawRectangle (Rectangle rect) { * right edges of the rectangle are at <code>x</code> and <code>x + width</code>. * The top and bottom edges are at <code>y</code> and <code>y + height</code>. * The <em>roundness</em> of the corners is specified by the - * <code>arcWidth</code> and <code>arcHeight</code> arguments. + * <code>arcWidth</code> and <code>arcHeight</code> arguments, which + * are respectively the width and height of the ellipse used to draw + * the corners. * * @param x the x coordinate of the rectangle to be drawn * @param y the y coordinate of the rectangle to be drawn * @param width the width of the rectangle to be drawn * @param height the height of the rectangle to be drawn - * @param arcWidth the horizontal diameter of the arc at the four corners - * @param arcHeight the vertical diameter of the arc at the four corners + * @param arcWidth the width of the arc + * @param arcHeight the height of the arc * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1668,6 +1673,9 @@ public void fillOval (int x, int y, int width, int height) { } } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void fillPath (Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path.handle == 0) SWT.error(SWT.ERROR_INVALID_ARGUMENT); @@ -1769,8 +1777,8 @@ public void fillRectangle (Rectangle rect) { * @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 arcWidth the horizontal diameter of the arc at the four corners - * @param arcHeight the vertical diameter of the arc at the four corners + * @param arcWidth the width of the arc + * @param arcHeight the height of the arc * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -1828,6 +1836,9 @@ public int getAdvanceWidth(char ch) { return getCharWidth(ch); } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public int getAlpha() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); return 0xFF; @@ -1932,6 +1943,7 @@ public Rectangle getClipping() { * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the region is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the region is disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -2025,11 +2037,35 @@ public Color getForeground() { return Color.photon_new(data.device, data.foreground); } +/** + * Returns the receiver's line cap style, which will be one + * of the constants <code>SWT.CAP_FLAT</code>, <code>SWT.CAP_ROUND</code>, + * or <code>SWT.CAP_SQUARE</code>. + * + * @return the cap style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int getLineCap() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); return data.lineCap; } +/** + * Returns the receiver's line dash style. + * + * @return the lin dash style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int[] getLineDash() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); byte[] dashList = data.dashes; @@ -2041,6 +2077,19 @@ public int[] getLineDash() { return dashes; } +/** + * Returns the receiver's line join style, which will be one + * of the constants <code>SWT.JOIN_MITER</code>, <code>SWT.JOIN_ROUND</code>, + * or <code>SWT.JOIN_BEVEL</code>. + * + * @return the join style used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int getLineJoin() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); return data.lineJoin; @@ -2103,6 +2152,9 @@ public int getStyle () { return data.style; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void getTransform(Transform transform) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (transform == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -2213,6 +2265,9 @@ public boolean isDisposed() { return handle == 0; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setAlpha(int alpha) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); } @@ -2280,6 +2335,9 @@ public void setClipping (int x, int y, int width, int height) { dirtyBits |= DIRTY_CLIPPING; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setClipping(Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (path != null && path.isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2315,8 +2373,8 @@ public void setClipping (Rectangle rect) { * by the argument. * * @param region the clipping region. - * - * * @exception IllegalArgumentException <ul> + * + * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li> * </ul> * @exception SWTException <ul> @@ -2402,6 +2460,22 @@ public void setForeground (Color color) { dirtyBits |= DIRTY_FOREGROUND; } +/** + * Sets the receiver's line cap style to the argument, which must be one + * of the constants <code>SWT.CAP_FLAT</code>, <code>SWT.CAP_ROUND</code>, + * or <code>SWT.CAP_SQUARE</code>. + * + * @param cap the cap style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineCap(int cap) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); switch (cap) { @@ -2416,6 +2490,20 @@ public void setLineCap(int cap) { dirtyBits |= DIRTY_LINECAP; } +/** + * Sets the receiver's line dash style to the argument. + * + * @param dashes the dash style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if any of the values in the array is less than or equal 0</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineDash(int[] dashes) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (dashes != null && dashes.length != 0) { @@ -2432,6 +2520,22 @@ public void setLineDash(int[] dashes) { dirtyBits |= DIRTY_LINESTYLE; } +/** + * Sets the receiver's line join style to the argument, which must be one + * of the constants <code>SWT.JOIN_MITER</code>, <code>SWT.JOIN_ROUND</code>, + * or <code>SWT.JOIN_BEVEL</code>. + * + * @param join the join style to be used for drawing lines + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setLineJoin(int join) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); switch (join) { @@ -2454,6 +2558,9 @@ public void setLineJoin(int join) { * * @param lineStyle the style to be used for drawing lines * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the style is not valid</li> + * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> @@ -2661,6 +2768,9 @@ int getClipping(int widget, int topWidget, boolean clipChildren, boolean clipSib return widget_tile; } +/** + * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + */ public void setTransform(Transform transform) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (transform == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); 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 dbd5723749..9aed8f3641 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 @@ -342,12 +342,12 @@ public Image(Device device, Rectangle bounds) { * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * <li>ERROR_NULL_ARGUMENT - if the image data is null</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_UNSUPPORTED_DEPTH - if the depth of the ImageData is not supported</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> + * </ul> */ public Image(Device device, ImageData data) { if (device == null) device = Device.getDevice(); @@ -359,10 +359,8 @@ public Image(Device device, ImageData data) { /** * Constructs an instance of this class, whose type is * <code>SWT.ICON</code>, from the two given <code>ImageData</code> - * objects. The two images must be the same size, and the mask image - * must have a color depth of 1. Pixel transparency in either image - * will be ignored. If either image is an icon to begin with, an - * exception is thrown. + * objects. The two images must be the same size. Pixel transparency + * in either image will be ignored. * <p> * The mask image should contain white wherever the icon is to be visible, * and black wherever the icon is to be transparent. In addition, @@ -377,9 +375,7 @@ public Image(Device device, ImageData data) { * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * <li>ERROR_NULL_ARGUMENT - if either the source or mask is null </li> - * <li>ERROR_INVALID_ARGUMENT - if source and mask are different sizes or - * if the mask is not monochrome, or if either the source or mask - * is already an icon</li> + * <li>ERROR_INVALID_ARGUMENT - if source and mask are different sizes</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> @@ -405,7 +401,8 @@ public Image(Device device, ImageData source, ImageData mask) { * Constructs an instance of this class by loading its representation * from the specified input stream. Throws an error if an error * occurs while loading the image, or if the result is an image - * of an unsupported type. + * of an unsupported type. Application code is still responsible + * for closing the input stream. * <p> * This constructor is provided for convenience when loading a single * image only. If the stream contains multiple images, only the first @@ -429,7 +426,8 @@ public Image(Device device, ImageData source, ImageData mask) { * <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li> * <li>ERROR_IO - if an IO error occurs while reading data</li> * <li>ERROR_UNSUPPORTED_DEPTH - if the InputStream describes an image with an unsupported depth</li> - * </ul> + * <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li> + * * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> * </ul> @@ -462,6 +460,7 @@ public Image (Device device, InputStream stream) { * <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li> * <li>ERROR_IO - if an IO error occurs while reading data</li> * <li>ERROR_UNSUPPORTED_DEPTH - if the image file has an unsupported depth</li> + * <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li> * </ul> * @exception SWTError <ul> * <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li> 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 5e667ae9fb..b565603454 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 @@ -63,12 +63,12 @@ public Region () { * * @param device the device on which to allocate the region * -* @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li> - * </ul> * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for region creation</li> + * </ul> * * @see #dispose * @@ -133,9 +133,13 @@ public void add (Rectangle rect) { * Adds the given rectangle to the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to merge with the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> * </ul> * @exception SWTException <ul> @@ -337,7 +341,10 @@ public void intersect (Rectangle rect) { * Intersects the given rectangle to the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to intersect with the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> @@ -532,9 +539,13 @@ public void subtract (Rectangle rect) { * Subtracts the given rectangle from the collection of polygons * the receiver maintains to describe its area. * - * @param rect the rectangle to subtract from the receiver + * @param x the x coordinate of the rectangle + * @param y the y coordinate of the rectangle + * @param width the width coordinate of the rectangle + * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> * </ul> * @exception SWTException <ul> @@ -612,7 +623,7 @@ public void translate (int x, int y) { * Translate all of the polygons the receiver maintains to describe * its area by the specified point. * - * @param point the point to translate + * @param pt the point to translate * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> 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 dc065837fa..50ec6429b5 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 @@ -388,7 +388,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 c2ed1d1afb..a41cfbab1b 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 @@ -45,8 +45,7 @@ import org.eclipse.swt.events.*; * <dd>DefaultSelection, Modify, Selection</dd> * </dl> * <p> - * Note: Only one of the styles DROP_DOWN and SIMPLE - * may be specified. + * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> @@ -276,9 +275,6 @@ public void deselectAll () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String,int) */ @@ -312,9 +308,6 @@ public void add (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String) */ @@ -539,9 +532,6 @@ int focusHandle () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String getItem (int index) { checkWidget(); @@ -571,9 +561,6 @@ public String getItem (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget(); @@ -592,9 +579,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemHeight () { checkWidget(); @@ -617,9 +601,6 @@ public int getItemHeight () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String [] getItems () { checkWidget(); @@ -754,9 +735,6 @@ public String getText () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getTextHeight () { checkWidget(); @@ -794,6 +772,10 @@ public int getTextLimit () { /** * Gets the number of items that are visible in the drop * down portion of the receiver's list. + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @return the number of items that are visible * @@ -953,9 +935,6 @@ void register () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -986,9 +965,6 @@ public void remove (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -1017,9 +993,6 @@ public void remove (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (String string) { checkWidget(); @@ -1029,7 +1002,8 @@ public void remove (String string) { } /** - * Removes all of the items from the receiver's list. + * Removes all of the items from the receiver's list and clear the + * contents of receiver's text field. * <p> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1096,7 +1070,7 @@ public void removeSelectionListener (SelectionListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is verified. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1159,10 +1133,6 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li> - * <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li> - * </ul> */ public void setItem (int index, String string) { checkWidget(); @@ -1192,9 +1162,6 @@ public void setItem (int index, String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItems (String [] items) { checkWidget(); @@ -1331,6 +1298,10 @@ int traversalCode (int key_sym, PhKeyEvent_t ke) { /** * Sets the number of items that are visible in the drop * down portion of the receiver's list. + * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @param count the new number of items to be visible * 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 f09f8e5aed..06d06c4839 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 @@ -438,6 +438,7 @@ int getClipping(int widget, int topWidget, boolean clipChildren, boolean clipSib /** * Returns an array containing the receiver's children. + * Children are returned in the order that they are drawn. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of children, so modifying the array will @@ -445,6 +446,9 @@ int getClipping(int widget, int topWidget, boolean clipChildren, boolean clipSib * </p> * * @return an array of children + * + * @see Control#moveAbove + * @see Control#moveBelow * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -969,7 +973,7 @@ public void setLayout (Layout layout) { * </ul> * * @see #layout(boolean) - * @see #layout(Control) + * @see #layout(Control[]) * * @since 3.1 */ 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 63e0ddd8db..dc4aeec2db 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 @@ -1008,9 +1008,10 @@ public void internal_dispose_GC (int phGC, GCData data) { /** * Returns <code>true</code> if the receiver is enabled and all - * of the receiver's ancestors are enabled, and <code>false</code> - * otherwise. A disabled control is typically not selectable from the - * user interface and draws with an inactive or "grayed" look. + * ancestors up to and including the receiver's nearest ancestor + * shell are enabled. Otherwise, <code>false</code> is returned. + * A disabled control is typically not selectable from the user + * interface and draws with an inactive or "grayed" look. * * @return the receiver's enabled state * @@ -1117,8 +1118,8 @@ boolean isTabItem () { /** * Returns <code>true</code> if the receiver is visible and all - * of the receiver's ancestors are visible and <code>false</code> - * otherwise. + * ancestors up to and including the receiver's nearest ancestor + * shell are visible. Otherwise, <code>false</code> is returned. * * @return the receiver's visibility state * @@ -1159,7 +1160,8 @@ Decorations menuShell () { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #moveBelow + * @see Control#moveBelow + * @see Composite#getChildren */ public void moveAbove (Control control) { checkWidget(); @@ -1192,7 +1194,8 @@ public void moveAbove (Control control) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #moveAbove + * @see Control#moveAbove + * @see Composite#getChildren */ public void moveBelow (Control control) { checkWidget(); @@ -1672,7 +1675,7 @@ public void redraw (int x, int y, int width, int height, boolean allChildren) { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1697,7 +1700,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control gains or loses focus. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1722,7 +1725,7 @@ public void removeFocusListener(FocusListener listener) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1746,7 +1749,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when keys are pressed and released on the system keyboard. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1771,7 +1774,7 @@ public void removeKeyListener(KeyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the mouse passes or hovers over controls. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1797,7 +1800,7 @@ public void removeMouseTrackListener(MouseTrackListener listener) { * Removes the listener from the collection of listeners who will * be notified when mouse buttons are pressed and released. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1823,7 +1826,7 @@ public void removeMouseListener (MouseListener listener) { * Removes the listener from the collection of listeners who will * be notified when the mouse moves. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1847,7 +1850,7 @@ public void removeMouseMoveListener(MouseMoveListener listener) { * Removes the listener from the collection of listeners who will * be notified when the receiver needs to be painted. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1871,7 +1874,7 @@ public void removePaintListener(PaintListener listener) { * Removes the listener from the collection of listeners who will * be notified when traversal events occur. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -2308,9 +2311,9 @@ public void setMenu (Menu menu) { * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_THREAD_INVALID_ACCESS when called from the wrong thread</li> - * <li>ERROR_WIDGET_DISPOSED when the widget has been disposed</li> + * @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 boolean setParent (Composite parent) { @@ -2362,7 +2365,8 @@ boolean setRadioSelection (boolean value) { * can occur in the receiver until the flag is set to true. * Graphics operations that occurred while the flag was * <code>false</code> are lost. When the flag is set to <code>true</code>, - * the entire widget is marked as needing to be redrawn. + * the entire widget is marked as needing to be redrawn. Nested calls + * to this method are stacked. * <p> * Note: This operation is a hint and may not be supported on some * platforms or for some widgets. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java index 9bd33d16be..d651c4cc41 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Decorations.java @@ -490,7 +490,7 @@ public void setImage (Image image) { * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the array of images is null</li> - * <li>ERROR_INVALID_ARGUMENT - if one of the images has been disposed</li> + * <li>ERROR_INVALID_ARGUMENT - if one of the images is null or has been disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Display.java index 144aa3d001..4ce1e4c0b6 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 @@ -333,9 +333,19 @@ public Display (DeviceData data) { /** * Adds the listener to the collection of listeners who will * be notifed when an event of the given type occurs anywhere - * in this display. When the event does occur, the listener is + * in a widget. When the event does occur, the listener is * notified by sending it the <code>handleEvent()</code> message. - * + * <p> + * Setting the type of an event to <code>SWT.None</code> from + * within the <code>handleEvent()</code> method can be used to + * change the event type and stop subsequent Java listeners + * from running. Because event filters run before other listeners, + * event filters can both block other listeners and set arbitrary + * fields within an event. For this reason, event filters are both + * powerful and dangerous. They should generally be avoided for + * performance, debugging and code maintenance reasons. + * </p> + * * @param eventType the type of event to listen for * @param listener the listener which should be notified when the event occurs * @@ -630,6 +640,10 @@ boolean filters (int eventType) { * the instance of the <code>Widget</code> subclass which * represents it in the currently running application, if * such exists, or null if no matching widget can be found. + * <p> + * <b>IMPORTANT:</b> This method should not be called from + * application code. The arguments are platform-specific. + * </p> * * @param handle the handle for the widget * @return the SWT widget that the handle represents @@ -644,6 +658,28 @@ public Widget findWidget (int handle) { return WidgetTable.get (handle); } +/** + * Given the operating system handle for a widget, + * and widget-specific id, returns the instance of + * the <code>Widget</code> subclass which represents + * the handle/id pair in the currently running application, + * if such exists, or null if no matching widget can be found. + * <p> + * <b>IMPORTANT:</b> This method should not be called from + * application code. The arguments are platform-specific. + * </p> + * + * @param handle the handle for the widget + * @param id the id for the subwidget (usually an item) + * @return the SWT widget that the handle/id pair represents + * + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public Widget findWidget (int handle, int id) { return null; } @@ -1183,9 +1219,10 @@ public Image getSystemImage (int id) { } /** - * Returns the single instance of the system tray. + * Returns the single instance of the system tray or null + * when there is no system tray available for the platform. * - * @return the receiver's user-interface thread + * @return the system tray or <code>null</code> * * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> @@ -1498,12 +1535,12 @@ int inputProc (int data, int rcvid, int message, int size) { * @param data the platform specific GC data * @return the platform specific GC handle * - * @exception SWTError <ul> - * <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li> - * </ul> * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle could not be obtained for gc creation</li> + * </ul> */ public int internal_new_GC (GCData data) { if (isDisposed()) SWT.error(SWT.ERROR_DEVICE_DISPOSED); @@ -1562,8 +1599,8 @@ boolean isValidThread () { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #setData(String, Object) + * @see #disposeExec(Runnable) */ public Object getData (String key) { checkDevice (); @@ -1595,8 +1632,8 @@ public Object getData (String key) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #setData(Object) + * @see #disposeExec(Runnable) */ public Object getData () { checkDevice (); @@ -1634,7 +1671,7 @@ static boolean isValidClass (Class clazz) { * @return point with mapped coordinates * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the rectangle is null</li> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> * <li>ERROR_INVALID_ARGUMENT - if the Control from or the Control to have been disposed</li> * </ul> * @exception SWTException <ul> @@ -1813,7 +1850,12 @@ public Rectangle map (Control from, Control to, int x, int y, int width, int hei * and mouse events. The intent is to enable automated UI * testing by simulating the input from the user. Most * SWT applications should never need to call this method. - * + * <p> + * Note that this operation can fail when the operating system + * fails to generate the event for any reason. For example, + * this can happen when there is no such key or mouse button + * or when the system event queue is full. + * </p> * <p> * <b>Event Types:</b> * <p>KeyDown, KeyUp @@ -1901,6 +1943,7 @@ void postEvent (Event event) { * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li> * </ul> * * @see #sleep @@ -2049,7 +2092,7 @@ void releaseDisplay () { /** * Removes the listener from the collection of listeners who will * be notifed when an event of the given type occurs anywhere in - * this display. + * a widget. * * @param eventType the type of event to listen for * @param listener the listener which should no longer be notified when the event occurs @@ -2218,8 +2261,8 @@ public void setCursorLocation (Point point) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #setData - * @see #disposeExec + * @see #getData(String) + * @see #disposeExec(Runnable) */ public void setData (String key, Object value) { checkDevice (); @@ -2289,8 +2332,8 @@ public void setData (String key, Object value) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #getData - * @see #disposeExec + * @see #getData() + * @see #disposeExec(Runnable) */ public void setData (Object data) { checkDevice (); @@ -2309,6 +2352,7 @@ public void setData (Object data) { * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred while running an inter-thread message</li> * </ul> */ public void setSynchronizer (Synchronizer synchronizer) { @@ -2470,7 +2514,7 @@ static int untranslateKey (int key) { * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see Control#update + * @see Control#update() */ public void update() { checkDevice (); 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 109ecc8c93..9708123c03 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 @@ -562,6 +562,15 @@ public void setFont (Font font) { /** * Sets the receiver's text. * <p> + * The string can contain both regular text and hyperlinks. A hyperlink + * is delimited by an anchor tag, <A> and </A>. Within an + * anchor, a single HREF attribute is supported. When a hyperlink is + * selected, the text field of the selection event contains either the + * text of hyperlink or the value of the HREF, if one was specified. + * In the rare case of identical hyperlinks within the same string, the + * HREF tag can be used to distinguish between them. The string may + * include the mnemonic character and line delimiters. + * </p> * * @param string the new text * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java index 78540c816b..75783b3b1c 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/List.java @@ -85,9 +85,6 @@ static int checkStyle (int style) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String,int) */ @@ -153,9 +150,6 @@ public void addSelectionListener(SelectionListener listener) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> * * @see #add(String) */ @@ -382,9 +376,6 @@ public int getFocusIndex () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure</li> - * </ul> */ public String getItem (int index) { checkWidget(); @@ -414,9 +405,6 @@ public String getItem (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemCount () { checkWidget(); @@ -435,9 +423,6 @@ public int getItemCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM_HEIGHT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getItemHeight () { checkWidget(); @@ -474,10 +459,6 @@ public int getItemHeight () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li> - * </ul> */ public String [] getItems () { checkWidget(); @@ -515,10 +496,6 @@ public String [] getItems () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure while getting the selection</li> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * </ul> */ public String [] getSelection () { checkWidget(); @@ -539,9 +516,6 @@ public String [] getSelection () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure</li> - * </ul> */ public int getSelectionCount () { checkWidget(); @@ -560,9 +534,6 @@ public int getSelectionCount () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li> - * </ul> */ public int getSelectionIndex () { checkWidget(); @@ -591,9 +562,6 @@ public int getSelectionIndex () { * <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> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_SELECTION - if the operation fails because of an operating system failure</li> - * </ul> */ public int [] getSelectionIndices () { checkWidget(); @@ -681,10 +649,6 @@ public int indexOf (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_CANNOT_GET_COUNT - if the operation fails because of an operating system failure while getting the item count</li> - * <li>ERROR_CANNOT_GET_ITEM - if the operation fails because of an operating system failure while getting an item</li> - * </ul> */ public int indexOf (String string, int start) { checkWidget(); @@ -765,9 +729,6 @@ int Pt_CB_SELECTION (int widget, int info) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int index) { checkWidget(); @@ -793,9 +754,6 @@ public void remove (int index) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (String string) { checkWidget(); @@ -818,9 +776,6 @@ public void remove (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int [] indices) { checkWidget(); @@ -862,9 +817,6 @@ public void remove (int [] indices) { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the operation fails because of an operating system failure</li> - * </ul> */ public void remove (int start, int end) { checkWidget(); @@ -1062,10 +1014,6 @@ public void selectAll () { * <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> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_REMOVED - if the remove operation fails because of an operating system failure</li> - * <li>ERROR_ITEM_NOT_ADDED - if the add operation fails because of an operating system failure</li> - * </ul> */ public void setItem (int index, String string) { checkWidget(); @@ -1095,9 +1043,6 @@ public void setItem (int index, String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> - * @exception SWTError <ul> - * <li>ERROR_ITEM_NOT_ADDED - if the operation fails because of an operating system failure</li> - * </ul> */ public void setItems (String [] items) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java index 7f37d0003a..bc439c37db 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Menu.java @@ -620,7 +620,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -644,7 +644,7 @@ public void removeHelpListener (HelpListener listener) { * Removes the listener from the collection of listeners who will * be notified when the menu events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 b9e5e297b3..dc44683e89 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 @@ -477,7 +477,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the arm events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -501,7 +501,7 @@ public void removeArmListener (ArmListener listener) { * Removes the listener from the collection of listeners who will * be notified when the help events are generated for the control. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -539,7 +539,7 @@ void removeAccelerator () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Sash.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Sash.java index e6d1e886d6..1212882b27 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Sash.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Sash.java @@ -22,7 +22,7 @@ import org.eclipse.swt.events.*; * the parent control. * <dl> * <dt><b>Styles:</b></dt> - * <dd>HORIZONTAL, VERTICAL</dd> + * <dd>HORIZONTAL, VERTICAL, SMOOTH</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -313,7 +313,7 @@ void processMouse (int info) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java index f97b6e2d7b..95559709d1 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Scale.java @@ -221,7 +221,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the <em>selection</em>, which is the receiver's position. * * @return the selection * @@ -347,8 +347,8 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal + * Sets the <em>selection</em>, which is the receiver's + * value, to the argument which must be greater than or equal * to zero. * * @param value the new selection (must be zero or greater) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/ScrollBar.java index 53e01e861d..606d8e3cbc 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 @@ -107,7 +107,6 @@ static int checkStyle (int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java index 46e65ee682..c378a700e8 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Shell.java @@ -499,11 +499,11 @@ void deregister () { } /** - * Moves the receiver to the top of the drawing order for - * the display on which it was created (so that all other - * shells on that display, which are not the receiver's - * children will be drawn behind it) and forces the window - * manager to make the shell active. + * If the receiver is visible, moves it to the top of the + * drawing order for the display on which it was created + * (so that all other shells on that display, which are not + * the receiver's children will be drawn behind it) and forces + * the window manager to make the shell active. * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -591,6 +591,21 @@ public boolean getMinimized () { return (args [1] & OS.Ph_WM_STATE_ISICONIFIED) != 0; } +/** + * Returns a point describing the minimum receiver's size. The + * x coordinate of the result is the minimum width of the receiver. + * The y coordinate of the result is the minimum height of the + * receiver. + * + * @return the receiver's size + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public Point getMinimumSize () { checkWidget(); int [] args = {OS.Pt_ARG_WINDOW_RENDER_FLAGS, 0, 0}; @@ -859,11 +874,11 @@ public void removeShellListener (ShellListener listener) { } /** - * Moves the receiver to the top of the drawing order for - * the display on which it was created (so that all other - * shells on that display, which are not the receiver's - * children will be drawn behind it) and asks the window - * manager to make the shell active. + * If the receiver is visible, moves it to the top of the + * drawing order for the display on which it was created + * (so that all other shells on that display, which are not + * the receiver's children will be drawn behind it) and asks + * the window manager to make the shell active * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1105,6 +1120,21 @@ public void setRegion (Region region) { this.region = region; } +/** + * Sets the receiver's minimum size to the point specified by the arguments. + * If the new minimum size is larger than the current size of the receiver, + * the receiver is resized to the new minimum size. + * + * @param width the new minimum width for the receiver + * @param height the new minimum height for the receiver + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public void setMinimumSize (int width, int height) { checkWidget(); int [] args = {OS.Pt_ARG_WINDOW_RENDER_FLAGS, 0, 0}; @@ -1122,6 +1152,23 @@ public void setMinimumSize (int width, int height) { OS.PtSetResources (shellHandle, args.length / 3, args); } +/** + * Sets the receiver's minimum size to the point specified by the argument. + * If the new minimum size is larger than the current size of the receiver, + * the receiver is resized to the new minimum size. + * + * @param size the new minimum size for the receiver + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the point is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public void setMinimumSize (Point size) { checkWidget(); if (size == null) error (SWT.ERROR_NULL_ARGUMENT); 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 54cc4c0072..4f4755fa54 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 @@ -254,7 +254,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's value. + * Returns the <em>selection</em>, which is the receiver's value. * * @return the selection * @@ -467,8 +467,8 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal + * Sets the <em>selection</em>, which is the receiver's + * value, to the argument which must be greater than or equal * to zero. * * @param value the new selection (must be zero or greater) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Spinner.java index 0f70bdb51b..34784efa1c 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 @@ -17,7 +17,8 @@ import org.eclipse.swt.*; /** * Instances of this class are selectable user interface - * objects that allow the user to enter and modify number + * objects that allow the user to enter and modify numeric + * values. * <p> * <dl> * <dt><b>Styles:</b></dt> @@ -28,6 +29,8 @@ import org.eclipse.swt.*; * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @since 3.1 */ public class Spinner extends Composite { @@ -56,7 +59,6 @@ public class Spinner extends Composite { * </ul> * * @see SWT#READ_ONLY - * @see SWT#WRAP * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -370,9 +372,8 @@ public int getMinimum () { } /** - * Returns the amount that the receiver's value will be - * modified by when the page increment/decrement areas - * are selected. + * Returns the amount that the receiver's position will be + * modified by when the page up/down keys are pressed. * * @return the page increment * @@ -387,7 +388,7 @@ public int getPageIncrement () { } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the <em>selection</em>, which is the receiver's position. * * @return the selection * @@ -497,7 +498,7 @@ public void removeModifyListener (ModifyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -544,11 +545,10 @@ void removeVerifyListener (VerifyListener listener) { /** * Sets the amount that the receiver's value will be - * modified by when the up/down (or right/left) arrows - * are pressed to the argument, which must be at least - * one. + * modified by when the up/down arrows are pressed to + * the argument, which must be at least one. * - * @param increment the new increment (must be greater than zero) + * @param value the new increment (must be greater than zero) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -600,12 +600,11 @@ public void setMinimum (int value) { } /** - * Sets the amount that the receiver's value will be - * modified by when the page increment/decrement areas - * are selected to the argument, which must be at least - * one. + * Sets the amount that the receiver's position will be + * modified by when the page up/down keys are pressed + * to the argument, which must be at least one. * - * @param pageIncrement the page increment (must be greater than zero) + * @param value the page increment (must be greater than zero) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -618,9 +617,10 @@ public void setPageIncrement (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's - * value to the argument which must be greater than or equal - * to zero. + * Sets the <em>selection</em>, which is the receiver's + * position, to the argument. If the argument is not within + * the range specified by minimum and maximum, it will be + * adjusted to fall within this range. * * @param value the new selection (must be zero or greater) * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabFolder.java index 59d431d733..885d9b79d0 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/TabFolder.java @@ -638,6 +638,9 @@ void setSelection (int index, boolean notify) { * * @param items the array of items * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the items array 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> 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 19db64be83..eae743d769 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 @@ -1080,7 +1080,7 @@ public void removeModifyListener (ModifyListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1105,7 +1105,7 @@ public void removeSelectionListener (SelectionListener listener) { * Removes the listener from the collection of listeners who will * be notified when the control is verified. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> 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 77708a0395..7580c0c7fb 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 @@ -580,7 +580,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is selected. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -931,7 +931,7 @@ public void setToolTipText (String string) { } /** - * Sets the width of the receiver. + * Sets the width of the receiver, for <code>SEPARATOR</code> ToolItems. * * @param width the new width * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Tracker.java index 2fe3c24335..a2725102be 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Tracker.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/photon/org/eclipse/swt/widgets/Tracker.java @@ -785,7 +785,7 @@ void releaseWidget () { * Removes the listener from the collection of listeners who will * be notified when the control is moved or resized. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -810,7 +810,7 @@ public void removeControlListener (ControlListener listener) { * Removes the listener from the collection of listeners who will * be notified when keys are pressed and released on the system keyboard. * - * @param listener the listener which should be notified + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> |