diff options
Diffstat (limited to 'bundles/org.eclipse.swt/Eclipse SWT/carbon/org')
58 files changed, 889 insertions, 41 deletions
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java index 970a4415f8..bdd57d9709 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Color.java @@ -26,6 +26,9 @@ import org.eclipse.swt.*; * * @see RGB * @see Device#getSystemColor + * @see <a href="http://www.eclipse.org/swt/snippets/#color">Color and RGB snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: PaintExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class Color extends Resource { /** diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java index cd723c0b53..7051c5d236 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Cursor.java @@ -38,6 +38,9 @@ import org.eclipse.swt.*; * <p> * Note: Only one of the above styles may be specified. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#cursor">Cursor snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class Cursor extends Resource { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java index f1b93847d4..99e5b30386 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Device.java @@ -19,6 +19,8 @@ import org.eclipse.swt.*; * such as the Display device and the Printer device. Devices * can have a graphics context (GC) created for them, and they * can be drawn on by sending messages to the associated GC. + * + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public abstract class Device implements Drawable { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java index 01aaf53f84..26ba3831f4 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Font.java @@ -26,6 +26,9 @@ import org.eclipse.swt.*; * </p> * * @see FontData + * @see <a href="http://www.eclipse.org/swt/snippets/#font">Font snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Examples: GraphicsExample, PaintExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class Font extends Resource { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java index e1c01257a6..3b4c1db707 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontData.java @@ -36,6 +36,7 @@ import org.eclipse.swt.*; * required, and thus no <code>dispose()</code> method is provided. * * @see Font + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class FontData { /** diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java index afb64dd730..6e75e8c28d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/FontMetrics.java @@ -19,6 +19,7 @@ package org.eclipse.swt.graphics; * using the <code>getFontMetrics()</code> method. * * @see GC#getFontMetrics + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class FontMetrics { int ascent, descent, averageCharWidth, leading, height; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java index 2e6688dca6..3cc597d1b6 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GC.java @@ -42,6 +42,9 @@ import org.eclipse.swt.*; * </p> * * @see org.eclipse.swt.events.PaintEvent + * @see <a href="http://www.eclipse.org/swt/snippets/#gc">GC snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Examples: GraphicsExample, PaintExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class GC extends Resource { /** @@ -1919,7 +1922,8 @@ public boolean getAdvanced() { } /** - * Returns the receiver's alpha value. + * Returns the receiver's alpha value. The alpha value + * is between 0 (transparent) and 255 (opaque). * * @return the alpha value * @@ -2582,7 +2586,8 @@ public void setAdvanced(boolean advanced) { } /** - * Sets the receiver's alpha value. + * Sets the receiver's alpha value which must be + * between 0 (transparent) and 255 (opaque). * <p> * This operation requires the operating system's advanced * graphics subsystem which may not be available on some diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GCData.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GCData.java index edb15ce9e5..7a9e165fd2 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GCData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/GCData.java @@ -23,6 +23,7 @@ import org.eclipse.swt.internal.carbon.Rect; * within the packages provided by SWT. It is not available on all * platforms, and should never be called from application code. * </p> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class GCData { public Device device; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java index 1b9d30b9d6..986009418a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Image.java @@ -61,6 +61,9 @@ import java.io.*; * @see Color * @see ImageData * @see ImageLoader + * @see <a href="http://www.eclipse.org/swt/snippets/#image">Image snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Examples: GraphicsExample, ImageAnalyzer</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class Image extends Resource implements Drawable { @@ -180,11 +183,11 @@ public Image(Device device, int width, int height) { * provided image, with an appearance that varies depending * on the value of the flag. The possible flag values are: * <dl> - * <dt><b>IMAGE_COPY</b></dt> + * <dt><b>{@link SWT#IMAGE_COPY}</b></dt> * <dd>the result is an identical copy of srcImage</dd> - * <dt><b>IMAGE_DISABLE</b></dt> + * <dt><b>{@link SWT#IMAGE_DISABLE}</b></dt> * <dd>the result is a copy of srcImage which has a <em>disabled</em> look</dd> - * <dt><b>IMAGE_GRAY</b></dt> + * <dt><b>{@link SWT#IMAGE_GRAY}</b></dt> * <dd>the result is a copy of srcImage which has a <em>gray scale</em> look</dd> * </dl> * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java index 242b53bcbe..1d6247707c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Path.java @@ -29,6 +29,10 @@ import org.eclipse.swt.internal.cocoa.*; * This class requires the operating system's advanced graphics subsystem * which may not be available on some platforms. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#path">Path, Pattern snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: GraphicsExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> * * @since 3.1 */ @@ -77,6 +81,37 @@ public Path (Device device) { init(); } +/** + * Constructs a new Path that is a copy of <code>path</code>. If + * <code>flatness</code> is less than or equal to zero, an unflatten + * copy of the path is created. Otherwise, it specifies the maximum + * error between the path and its flatten copy. Smaller numbers give + * better approximation. + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * + * @param device the device on which to allocate the path + * @param path the path to make a copy + * @param flatness the flatness value + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device</li> + * <li>ERROR_NULL_ARGUMENT - if the path is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> + * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle for the path could not be obtained</li> + * </ul> + * + * @see #dispose() + * @since 3.4 + */ public Path (Device device, Path path, float flatness) { super(device); if (path == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -173,6 +208,31 @@ public Path (Device device, Path path, float flatness) { init(); } +/** + * Constructs a new Path with the specifed PathData. + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * + * @param device the device on which to allocate the path + * @param data the data for the path + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the device is null and there is no current device</li> + * <li>ERROR_NULL_ARGUMENT - if the data is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> + * </ul> + * @exception SWTError <ul> + * <li>ERROR_NO_HANDLES if a handle for the path could not be obtained</li> + * </ul> + * + * @see #dispose() + * @since 3.4 + */ public Path (Device device, PathData data) { this(device); if (data == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java index 2bcc0067ed..cdd684b893 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Pattern.java @@ -26,6 +26,10 @@ import org.eclipse.swt.internal.carbon.*; * which may not be available on some platforms. * </p> * + * @see <a href="http://www.eclipse.org/swt/snippets/#path">Path, Pattern snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: GraphicsExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> + * * @since 3.1 */ public class Pattern extends Resource { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java index d41bda790a..89afca6c88 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Region.java @@ -23,6 +23,9 @@ import org.eclipse.swt.*; * method to release the operating system resources managed by each instance * when those instances are no longer required. * </p> + * + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: GraphicsExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public final class Region extends Resource { /** diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java index b2dfce16a7..f04512d107 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/TextLayout.java @@ -27,7 +27,11 @@ import org.eclipse.swt.*; * when those instances are no longer required. * </p> * - * @since 3.0 + * @see <a href="http://www.eclipse.org/swt/snippets/#textlayout">TextLayout, TextStyle snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: CustomControlExample, StyledText tab</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> + * + * @since 3.0 */ public final class TextLayout extends Resource { @@ -903,13 +907,18 @@ public int getAscent () { } /** - * Returns the bounds of the receiver. + * Returns the bounds of the receiver. The width returned is either the + * width of the longest line or the width set using {@link TextLayout#setWidth(int)}. + * To obtain the text bounds of a line use {@link TextLayout#getLineBounds(int)}. * * @return the bounds of the receiver * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @see #setWidth(int) + * @see #getLineBounds(int) */ public Rectangle getBounds() { checkLayout(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java index c2c3b89dc3..1886b1016c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/graphics/Transform.java @@ -27,6 +27,9 @@ import org.eclipse.swt.internal.carbon.*; * which may not be available on some platforms. * </p> * + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: GraphicsExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> + * * @since 3.1 */ public class Transform extends Resource { @@ -165,13 +168,23 @@ public void getElements(float[] elements) { System.arraycopy(handle, 0, elements, 0, handle.length); } +/** + * Modifies the receiver such that the matrix it represents becomes the + * identity matrix. + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.4 + */ public void identity() { if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); OS.CGAffineTransformMake(1, 0, 0, 1, 0, 0, handle); } /** - * Modifies the receiver such that the matrix it represents becomes the + * Modifies the receiver such that the matrix it represents becomes * the mathematical inverse of the matrix it previously represented. * * @exception SWTException <ul> @@ -288,6 +301,19 @@ public void setElements(float m11, float m12, float m21, float m22, float dx, fl OS.CGAffineTransformMake(m11, m12, m21, m22, dx, dy, handle); } +/** + * Modifies the receiver so that it represents a transformation that is + * equivalent to its previous transformation sheared by (shearX, shearY). + * + * @param shearX the shear factor in the X direction + * @param shearY the shear factor in the Y direction + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.4 + */ public void shear(float shearX, float shearY) { if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); float[] matrix = {1, shearX, shearY, 1, 0, 0}; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java index 99d784f6ed..8fe96a547d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Button.java @@ -40,6 +40,10 @@ import org.eclipse.swt.internal.carbon.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#button">Button snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Button extends Control { String text = ""; @@ -359,6 +363,20 @@ public int getAlignment () { return SWT.LEFT; } +/** + * Returns <code>true</code> if the receiver is grayed, + * and false otherwise. When the widget does not have + * the <code>CHECK</code> style, return false. + * + * @return the grayed state of the checkbox + * + * @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.4 + */ public boolean getGrayed () { checkWidget(); if ((style & SWT.CHECK) == 0) return false; @@ -636,6 +654,20 @@ void setDefault (boolean value) { OS.SetWindowDefaultButton (window, value ? handle : 0); } +/** + * Sets the grayed state of the receiver. This state change + * only applies if the control was created with the SWT.CHECK + * style. + * + * @param grayed the new grayed state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public void setGrayed (boolean grayed) { checkWidget(); if ((style & SWT.CHECK) == 0) return; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java index 152c385ed0..28dd97431e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Canvas.java @@ -34,6 +34,9 @@ import org.eclipse.swt.graphics.*; * </p> * * @see Composite + * @see <a href="http://www.eclipse.org/swt/snippets/#canvas">Canvas snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Canvas extends Composite { Caret caret; @@ -151,7 +154,7 @@ void drawWidget (int control, int context, int damageRgn, int visibleRgn, int th * drawing in the window any other time. * </p> * - * @return the caret + * @return the caret for the receiver, may be null * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -163,6 +166,18 @@ public Caret getCaret () { return caret; } +/** + * Returns the IME. + * + * @return the IME + * + * @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.4 + */ public IME getIME () { checkWidget(); return ime; @@ -363,6 +378,21 @@ public void setFont (Font font) { super.setFont (font); } +/** + * Sets the receiver's IME. + * + * @param ime the new IME for the receiver, may be null + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the IME has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public void setIME (IME ime) { checkWidget (); if (ime != null && ime.isDisposed()) error(SWT.ERROR_INVALID_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Caret.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Caret.java index 011b6b5839..e83f8a511e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Caret.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Caret.java @@ -32,6 +32,10 @@ import org.eclipse.swt.graphics.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#caret">Caret snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Canvas tab</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Caret extends Widget { Canvas parent; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ColorDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ColorDialog.java index 698ba7ccc2..a653367f81 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ColorDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ColorDialog.java @@ -28,6 +28,9 @@ import org.eclipse.swt.graphics.RGB; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class ColorDialog extends Dialog { RGB rgb; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java index 9e60b2c4d2..e2f4ef9a16 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Combo.java @@ -55,6 +55,9 @@ import org.eclipse.swt.internal.carbon.Rect; * </p> * * @see List + * @see <a href="http://www.eclipse.org/swt/snippets/#combo">Combo snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Combo extends Composite { int menuHandle; @@ -731,6 +734,25 @@ public String [] getItems () { return result; } +/** + * Returns <code>true</code> if the receiver's list is visible, + * and <code>false</code> otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, this method + * may still indicate that it is considered visible even though + * it may not actually be showing. + * </p> + * + * @return the receiver's list's visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public boolean getListVisible () { checkWidget (); if ((style & SWT.READ_ONLY) != 0) { @@ -1661,6 +1683,24 @@ public void setItems (String [] items) { } } +/** + * Marks the receiver's list as visible if the argument is <code>true</code>, + * and marks it invisible otherwise. + * <p> + * If one of the receiver's ancestors is not visible or some + * other condition makes the receiver not visible, marking + * it visible may not actually cause it to be displayed. + * </p> + * + * @param visible the new visibility state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public void setListVisible (boolean visible) { checkWidget (); if ((style & SWT.READ_ONLY) != 0) { diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java index 7106e29733..f3386d0ee0 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Composite.java @@ -44,6 +44,8 @@ import org.eclipse.swt.graphics.*; * </p> * * @see Canvas + * @see <a href="http://www.eclipse.org/swt/snippets/#composite">Composite snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Composite extends Scrollable { Layout layout; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java index 2e52b3a9e4..471cc6cc22 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Control.java @@ -44,6 +44,10 @@ import org.eclipse.swt.accessibility.Accessible; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#control">Control snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public abstract class Control extends Widget implements Drawable { /** @@ -1135,7 +1139,9 @@ int getDrawCount (int control) { * When the mouse pointer passes over a control its appearance * is changed to match the control's cursor. * </p> - * </ul> + * + * @return the receiver's cursor or <code>null</code> + * * @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> @@ -1337,6 +1343,19 @@ Control [] getPath () { return result; } +/** + * Returns the region that defines the shape of the control, + * or null if the control has the default shape. + * + * @return the region that defines the shape of the shell (or null) + * + * @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.4 + */ public Region getRegion () { checkWidget (); return region; @@ -2383,6 +2402,23 @@ public void pack (boolean changed) { setSize (computeSize (SWT.DEFAULT, SWT.DEFAULT, changed)); } +/** + * Prints the receiver and all children. + * + * @param gc the gc where the drawing occurs + * @return <code>true</code> if the operation was successful and <code>false</code> otherwise + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the gc is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the gc has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - 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.4 + */ public boolean print (GC gc) { checkWidget (); if (gc == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -3210,7 +3246,8 @@ public void setBounds (Rectangle rect) { /** * If the argument is <code>true</code>, causes the receiver to have * all mouse events delivered to it until the method is called with - * <code>false</code> as the argument. + * <code>false</code> as the argument. Note that on some platforms, + * a mouse button must currently be down for capture to be assigned. * * @param capture <code>true</code> to capture the mouse, and <code>false</code> to release it * @@ -3649,6 +3686,23 @@ public void setRedraw (boolean redraw) { } } +/** + * Sets the shape of the control to the region specified + * by the argument. When the argument is null, the + * default shape of the control is restored. + * + * @param region the region that defines the shape of the control (or null) + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public void setRegion (Region region) { checkWidget (); if (region != null && region.isDisposed()) error (SWT.ERROR_INVALID_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DateTime.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DateTime.java index 81a696b427..9ee2b1c84b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DateTime.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DateTime.java @@ -40,6 +40,10 @@ import org.eclipse.swt.internal.carbon.Rect; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#datetime">DateTime snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> * * @since 3.3 */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java index 283f53d0da..c46c15420b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Decorations.java @@ -92,6 +92,7 @@ import org.eclipse.swt.graphics.*; * @see #getMaximized * @see Shell * @see SWT + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Decorations extends Canvas { Image image; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java index 429c3bf853..04ccefa6ac 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/DirectoryDialog.java @@ -28,6 +28,10 @@ import org.eclipse.swt.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#directorydialog">DirectoryDialog snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class DirectoryDialog extends Dialog { String message = "", filterPath = ""; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java index 39e42453b3..17be768e11 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Display.java @@ -101,6 +101,8 @@ import org.eclipse.swt.graphics.*; * @see #readAndDispatch * @see #sleep * @see Device#dispose + * @see <a href="http://www.eclipse.org/swt/snippets/#display">Display snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Display extends Device { @@ -1276,7 +1278,8 @@ public Shell getActiveShell () { } /** - * Returns a rectangle describing the receiver's size and location. + * Returns a rectangle describing the receiver's size and location. Note that + * on multi-monitor systems the origin can be negative. * * @return the bounding rectangle * @@ -3276,7 +3279,7 @@ public void removeFilter (int eventType, Listener listener) { * is one of the event constants defined in class <code>SWT</code>. * * @param eventType the type of event to listen for - * @param listener the listener which should no longer be notified when the event occurs + * @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/carbon/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java index 33b91cc243..e6989ab3e0 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FileDialog.java @@ -30,6 +30,10 @@ import org.eclipse.swt.internal.carbon.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#filedialog">FileDialog snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class FileDialog extends Dialog { String [] filterNames = new String [0]; @@ -462,8 +466,10 @@ public void setFileName (String string) { * which may be null. * <p> * The strings are platform specific. For example, on - * Windows, an extension filter string is typically of - * the form "*.extension", where "*.*" matches all files. + * some platforms, an extension filter string is typically + * of the form "*.extension", where "*.*" matches all files. + * For filters with multiple extensions, use semicolon as + * a separator, e.g. "*.jpg;*.png". * </p> * * @param extensions the file extension filter @@ -496,7 +502,7 @@ public void setFilterIndex (int index) { } /** - * Sets the the names that describe the filter extensions + * Sets the names that describe the filter extensions * which the dialog will use to filter the files it shows * to the argument, which may be null. * <p> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FontDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FontDialog.java index d5e4a67724..3544773db7 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FontDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/FontDialog.java @@ -30,6 +30,9 @@ import org.eclipse.swt.internal.carbon.RGBColor; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class FontDialog extends Dialog { FontData fontData; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Group.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Group.java index bc3e5a59df..ae9a1b8d5f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Group.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Group.java @@ -36,6 +36,9 @@ import org.eclipse.swt.internal.carbon.Rect; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Group extends Composite { String text = ""; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/IME.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/IME.java index aaa85d3888..031ddee3f9 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/IME.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/IME.java @@ -17,6 +17,26 @@ import org.eclipse.swt.internal.carbon.OS; import org.eclipse.swt.internal.carbon.TextRange; +/** + * Instances of this class represent input method editors. + * These are typically in-line pre-edit text areas that allow + * the user to compose characters from Far Eastern languages + * such as Japanese, Chinese or Korean. + * + * <dl> + * <dt><b>Styles:</b></dt> + * <dd>(none)</dd> + * <dt><b>Events:</b></dt> + * <dd>ImeComposition</dd> + * </dl> + * <p> + * IMPORTANT: This class is <em>not</em> intended to be subclassed. + * </p> + * + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> + * + * @since 3.4 + */ public class IME extends Widget { Canvas parent; int caretOffset; @@ -37,8 +57,31 @@ IME () { } /** - * - * @see SWT + * Constructs a new instance of this class given its parent + * and a style value describing its behavior and appearance. + * <p> + * The style value is either one of the style constants defined in + * class <code>SWT</code> which is applicable to instances of this + * class, or must be built by <em>bitwise OR</em>'ing together + * (that is, using the <code>int</code> "|" operator) two or more + * of those <code>SWT</code> style constants. The class description + * lists the style constants that are applicable to the class. + * Style bits are also inherited from superclasses. + * </p> + * + * @param parent a canvas control which will be the parent of the new instance (cannot be null) + * @param style the style of control to construct + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> + * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> + * </ul> + * + * @see Widget#checkSubclass + * @see Widget#getStyle */ public IME (Canvas parent, int style) { super (parent, style); @@ -54,21 +97,78 @@ void createWidget () { } } +/** + * Returns the offset of the caret from the start of the document. + * The caret is within the current composition. + * + * @return the caret offset + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public int getCaretOffset () { checkWidget (); return startOffset + caretOffset; } +/** + * Returns the commit count of the composition. This is the + * number of characters that have been composed. When the + * commit count is equal to the length of the composition + * text, then the in-line edit operation is complete. + * + * @return the commit count + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see IME#getText + */ public int getCommitCount () { checkWidget (); return commitCount; } +/** + * Returns the offset of the composition from the start of the document. + * This is the start offset of the composition within the document and + * in not changed by the input method editor itself during the in-line edit + * session. + * + * @return the offset of the composition + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public int getCompositionOffset () { checkWidget (); return startOffset; } +/** + * Returns the ranges for the style that should be applied during the + * in-line edit session. + * <p> + * The ranges array contains start and end pairs. Each pair refers to + * the corresponding style in the styles array. For example, the pair + * that starts at ranges[n] and ends at ranges[n+1] uses the style + * at styles[n/2] returned by <code>getStyles()</code>. + * </p> + * @return the ranges for the styles + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see IME#getStyles + */ public int [] getRanges () { checkWidget (); if (ranges == null) return new int [0]; @@ -79,6 +179,24 @@ public int [] getRanges () { return result; } +/** + * Returns the styles for the ranges. + * <p> + * The ranges array contains start and end pairs. Each pair refers to + * the corresponding style in the styles array. For example, the pair + * that starts at ranges[n] and ends at ranges[n+1] uses the style + * at styles[n/2]. + * </p> + * + * @return the ranges for the styles + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see IME#getRanges + */ public TextStyle [] getStyles () { checkWidget (); if (styles == null) return new TextStyle [0]; @@ -87,11 +205,40 @@ public TextStyle [] getStyles () { return result; } +/** + * Returns the composition text. + * <p> + * The text for an IME is the characters in the widget that + * are in the current composition. When the commit count is + * equal to the length of the composition text, then the + * in-line edit operation is complete. + * </p> + * + * @return the widget text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public String getText () { checkWidget (); return text; } +/** + * Returns <code>true</code> if the caret should be wide, and + * <code>false</code> otherwise. In some languages, for example + * Korean, the caret is typically widened to the width of the + * current character in the in-line edit session. + * + * @return the wide caret state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public boolean getWideCaret() { checkWidget (); return false; @@ -266,6 +413,22 @@ void releaseWidget () { ranges = null; } +/** + * Sets the offset of the composition from the start of the document. + * This is the start offset of the composition within the document and + * in not changed by the input method editor itself during the in-line edit + * session but may need to be changed by clients of the IME. For example, + * if during an in-line edit operation, a text editor inserts characters + * above the IME, then the IME must be informed that the composition + * offset has changed. + * + * @return the offset of the composition + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setCompositionOffset (int offset) { checkWidget (); if (offset < 0) return; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Label.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Label.java index 2f8778bd4b..8441943368 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Label.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Label.java @@ -22,6 +22,12 @@ import org.eclipse.swt.graphics.*; * user interface object that displays a string or image. * When SEPARATOR is specified, displays a single * vertical or horizontal line. + * <p> + * Shadow styles are hints and may not be honoured + * by the platform. To create a separator label + * with the default shadow style for the platform, + * do not specify a shadow style. + * </p> * <dl> * <dt><b>Styles:</b></dt> * <dd>SEPARATOR, HORIZONTAL, VERTICAL</dd> @@ -38,6 +44,10 @@ import org.eclipse.swt.graphics.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#label">Label snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Label extends Control { String text = ""; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java index ba61d13565..4d5432179b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Link.java @@ -33,6 +33,10 @@ import org.eclipse.swt.graphics.*; * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#link">Link snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> * * @since 3.1 */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java index b7f0d28b49..eeb6db1615 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/List.java @@ -38,6 +38,10 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#list">List snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class List extends Scrollable { String [] items; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java index 1a17feb1a6..1a735fa362 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Menu.java @@ -37,6 +37,10 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#menu">Menu snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Menu extends Widget { /** @@ -62,6 +66,11 @@ public class Menu extends Widget { * Constructs a new instance of this class given its parent, * and sets the style for the instance so that the instance * will be a popup menu on the given parent's shell. + * <p> + * After constructing a menu, it can be set into its parent + * using <code>parent.setMenu(menu)</code>. In this case, the parent may + * be any control in the same widget tree as the parent. + * </p> * * @param parent a control which will be the parent of the new instance (cannot be null) * @@ -93,6 +102,9 @@ public Menu (Control parent) { * of those <code>SWT</code> style constants. The class description * lists the style constants that are applicable to the class. * Style bits are also inherited from superclasses. + * </p><p> + * After constructing a menu or menuBar, it can be set into its parent + * using <code>parent.setMenu(menu)</code> or <code>parent.setMenuBar(menuBar)</code>. * </p> * * @param parent a decorations control which will be the parent of the new instance (cannot be null) @@ -123,6 +135,10 @@ public Menu (Decorations parent, int style) { * (which must be a <code>Menu</code>) and sets the style * for the instance so that the instance will be a drop-down * menu on the given parent's parent. + * <p> + * After constructing a drop-down menu, it can be set into its parentMenu + * using <code>parentMenu.setMenu(menu)</code>. + * </p> * * @param parentMenu a menu which will be the parent of the new instance (cannot be null) * @@ -147,6 +163,10 @@ public Menu (Menu parentMenu) { * (which must be a <code>MenuItem</code>) and sets the style * for the instance so that the instance will be a drop-down * menu on the given parent's parent menu. + * <p> + * After constructing a drop-down menu, it can be set into its parentItem + * using <code>parentItem.setMenu(menu)</code>. + * </p> * * @param parentItem a menu item which will be the parent of the new instance (cannot be null) * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java index e0171cf591..5d7492ea2b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MenuItem.java @@ -31,6 +31,8 @@ import org.eclipse.swt.internal.carbon.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class MenuItem extends Item { Menu parent, menu; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java index 89b60f641a..b7c189ebd8 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/MessageBox.java @@ -33,6 +33,9 @@ import org.eclipse.swt.internal.carbon.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample, Dialog tab</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class MessageBox extends Dialog { String message = ""; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java index 3b7c88f05a..3562de653a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ProgressBar.java @@ -32,6 +32,10 @@ import org.eclipse.swt.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#progressbar">ProgressBar snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class ProgressBar extends Control { @@ -148,6 +152,19 @@ public int getSelection () { return OS.GetControl32BitValue (handle); } +/** + * Returns the state of the receiver. The value will be one of + * <code>NORMAL</code>, <code>ERROR</code> or <code>PAUSED</code>. + * + * @return the state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public int getState () { checkWidget (); return SWT.NORMAL; @@ -222,6 +239,19 @@ public void setSelection (int value) { display.runEventLoopTimers (); } +/** + * Sets the state of the receiver. The state is be one of + * <code>NORMAL</code>, <code>ERROR</code> or <code>PAUSED</code>. + * + * @param state the new state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public void setState (int state) { checkWidget (); //NOT IMPLEMENTED diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Sash.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Sash.java index 6b19035d12..142b5ce63d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Sash.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Sash.java @@ -35,6 +35,10 @@ import org.eclipse.swt.events.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#sash">Sash snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Sash extends Control { Cursor sizeCursor; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java index c2535b75bb..d44c27547a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scale.java @@ -34,6 +34,10 @@ import org.eclipse.swt.graphics.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#scale">Scale snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Scale extends Control { int increment = 1; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java index 8102c1954f..6372792e84 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ScrollBar.java @@ -79,6 +79,8 @@ import org.eclipse.swt.graphics.*; * @see Scrollable * @see Scrollable#getHorizontalBar * @see Scrollable#getVerticalBar + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class ScrollBar extends Widget { int handle; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scrollable.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scrollable.java index cd11c0df9c..e93cc4f40e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scrollable.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Scrollable.java @@ -32,6 +32,8 @@ import org.eclipse.swt.graphics.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public abstract class Scrollable extends Control { int scrolledHandle; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java index 556c0e9a81..15c6b4e732 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Shell.java @@ -115,6 +115,9 @@ import org.eclipse.swt.graphics.*; * * @see Decorations * @see SWT + * @see <a href="http://www.eclipse.org/swt/snippets/#shell">Shell snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Shell extends Decorations { int shellHandle, windowGroup; @@ -353,6 +356,23 @@ public Shell (Shell parent, int style) { this (parent != null ? parent.display : null, parent, style, 0, false); } +/** + * Invokes platform specific functionality to allocate a new shell + * that is not embedded. + * <p> + * <b>IMPORTANT:</b> This method is <em>not</em> part of the public + * API for <code>Shell</code>. 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 called from + * application code. + * </p> + * + * @param display the display for the shell + * @param handle the handle for the shell + * @return a new shell object containing the specified display and handle + * + * @since 3.3 + */ public static Shell internal_new (Display display, int handle) { return new Shell (display, null, SWT.NO_TRIM, handle, false); } @@ -673,6 +693,19 @@ public void forceActive () { OS.SetFrontProcessWithOptions (new int [] {0, OS.kCurrentProcess}, OS.kSetFrontProcessFrontWindowOnly); } +/** + * Returns the receiver's alpha value. The alpha value + * is between 0 (transparent) and 255 (opaque). + * + * @return the alpha value + * + * @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.4 + */ public int getAlpha () { checkWidget (); float [] alpha = new float [1]; @@ -694,6 +727,20 @@ int getDrawCount (int control) { return 0; } +/** + * Returns <code>true</code> if the receiver is currently + * in fullscreen state, and false otherwise. + * <p> + * + * @return the fullscreen state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public boolean getFullScreen () { checkWidget(); return fullScreen; @@ -1394,6 +1441,23 @@ void setActiveControl (Control control) { } } +/** + * Sets the receiver's alpha value which must be + * between 0 (transparent) and 255 (opaque). + * <p> + * This operation requires the operating system's advanced + * widgets subsystem which may not be available on some + * platforms. + * </p> + * @param alpha the alpha value + * + * @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.4 + */ public void setAlpha (int alpha) { checkWidget (); alpha &= 0xFF; @@ -1436,6 +1500,29 @@ public void setEnabled (boolean enabled) { } } +/** + * Sets the full screen state of the receiver. + * If the argument is <code>true</code> causes the receiver + * to switch to the full screen state, and if the argument is + * <code>false</code> and the receiver was previously switched + * into full screen state, causes the receiver to switch back + * to either the maximmized or normal states. + * <p> + * Note: The result of intermixing calls to <code>setFullScreen(true)</code>, + * <code>setMaximized(true)</code> and <code>setMinimized(true)</code> will + * vary by platform. Typically, the behavior will match the platform user's + * expectations, but not always. This should be avoided if possible. + * </p> + * + * @param fullScreen the new fullscreen state + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public void setFullScreen (boolean fullScreen) { checkWidget (); this.fullScreen = fullScreen; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java index ac5778ae28..f03f6ba37f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Slider.java @@ -64,6 +64,9 @@ import org.eclipse.swt.graphics.*; * </p> * * @see ScrollBar + * @see <a href="http://www.eclipse.org/swt/snippets/#slider">Slider snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Slider extends Control { boolean dragging; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java index 2cf2e1135d..57c4e71806 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Spinner.java @@ -36,6 +36,10 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#spinner">Spinner snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> * * @since 3.1 */ @@ -49,13 +53,11 @@ public class Spinner extends Composite { static int GAP = 3; /** - * The maximum number of characters that can be entered - * into a text widget. - * <p> - * Note that this value is platform dependent, based upon - * the native widget implementation. - * </p> - */ + * the operating system limit for the number of characters + * that the text field in an instance of this class can hold + * + * @since 3.4 + */ public static final int LIMIT; /* @@ -526,6 +528,20 @@ int getSelectionText (boolean [] parseFail) { return -1; } +/** + * Returns a string containing a copy of the contents of the + * receiver's text field, or an empty string if there are no + * contents. + * + * @return the receiver's text + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public String getText() { int [] ptr = new int [1]; int [] actualSize = new int [1]; @@ -539,6 +555,23 @@ public String getText() { return new String (buffer); } +/** + * Returns the maximum number of characters that the receiver's + * text field is capable of holding. If this has not been changed + * by <code>setTextLimit()</code>, it will be the constant + * <code>Spinner.LIMIT</code>. + * + * @return the text limit + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see #LIMIT + * + * @since 3.4 + */ public int getTextLimit () { checkWidget(); return textLimit; @@ -995,11 +1028,11 @@ public void setMaximum (int value) { /** * Sets the minimum value that the receiver will allow. This new - * value will be ignored if it is negative or is not less than the receiver's + * value will be ignored if it is not less than the receiver's * current maximum value. If the new minimum is applied then the receiver's * selection value will be adjusted if necessary to fall within its new range. * - * @param value the new minimum, which must be nonnegative and less than the current maximum + * @param value the new minimum, which must be less than the current maximum * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1150,6 +1183,28 @@ char [] setText (String string, int start, int end, boolean notify) { return buffer; } +/** + * Sets the maximum number of characters that the receiver's + * text field is capable of holding to be the argument. + * <p> + * To reset this value to the default, use <code>setTextLimit(Spinner.LIMIT)</code>. + * Specifying a limit value larger than <code>Spinner.LIMIT</code> sets the + * receiver's limit to <code>Spinner.LIMIT</code>. + * </p> + * @param limit new text limit + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_CANNOT_BE_ZERO - if the limit is zero</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @see #LIMIT + * + * @since 3.4 + */ public void setTextLimit (int limit) { checkWidget(); if (limit == 0) error (SWT.ERROR_CANNOT_BE_ZERO); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java index 44c80084b6..3b9ebb48fb 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabFolder.java @@ -43,6 +43,10 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#tabfolder">TabFolder, TabItem snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class TabFolder extends Composite { TabItem [] items; @@ -294,6 +298,24 @@ public TabItem getItem (int index) { return items [index]; } +/** + * Returns the tab item at the given point in the receiver + * or null if no such item exists. The point is in the + * coordinate system of the receiver. + * + * @param point the point used to locate the item + * @return the tab item at the given point, or null if the point is not in a tab item + * + * @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.4 + */ public TabItem getItem(Point point) { checkWidget (); if (point == null) error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java index 0860ce23e4..a73040a53b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TabItem.java @@ -30,6 +30,9 @@ import org.eclipse.swt.internal.carbon.Rect; * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#tabfolder">TabFolder, TabItem snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class TabItem extends Item { TabFolder parent; @@ -130,6 +133,19 @@ void destroyWidget () { releaseHandle (); } +/** + * Returns a rectangle describing the receiver's size and location + * relative to its parent. + * + * @return the receiver's bounding rectangle + * + * @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.4 + */ public Rectangle getBounds() { checkWidget (); int index = parent.indexOf (this); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java index ca632044fe..5ccc55b150 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Table.java @@ -55,12 +55,13 @@ import org.eclipse.swt.graphics.*; * </pre></code> * </p><p> * Note that although this class is a subclass of <code>Composite</code>, - * it does not make sense to add <code>Control</code> children to it, - * or set a layout on it. + * it does not normally make sense to add <code>Control</code> children to + * it, or set a layout on it, unless implementing something like a cell + * editor. * </p><p> * <dl> * <dt><b>Styles:</b></dt> - * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION, HIDE_SELECTION, VIRTUAL</dd> + * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION, HIDE_SELECTION, VIRTUAL, NO_SCROLL</dd> * <dt><b>Events:</b></dt> * <dd>Selection, DefaultSelection, SetData, MeasureItem, EraseItem, PaintItem</dd> * </dl> @@ -69,6 +70,10 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#table">Table, TableItem, TableColumn snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Table extends Composite { TableItem [] items; @@ -122,6 +127,7 @@ public class Table extends Composite { * @see SWT#FULL_SELECTION * @see SWT#HIDE_SELECTION * @see SWT#VIRTUAL + * @see SWT#NO_SCROLL * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -1556,7 +1562,7 @@ public int getItemCount () { /** * Returns the height of the area which would be used to - * display <em>one</em> of the items in the receiver's. + * display <em>one</em> of the items in the receiver. * * @return the height of one item * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java index e2e94c0189..682ab30957 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableColumn.java @@ -31,6 +31,9 @@ import org.eclipse.swt.events.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#table">Table, TableItem, TableColumn snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class TableColumn extends Item { Table parent; @@ -91,7 +94,10 @@ public TableColumn (Table parent, int style) { * lists the style constants that are applicable to the class. * Style bits are also inherited from superclasses. * </p> - * + * <p> + * Note that due to a restriction on some platforms, the first column + * is always left aligned. + * </p> * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct * @param index the zero-relative index to store the receiver in its parent @@ -424,7 +430,10 @@ void resized (int newWidth) { * Controls how text and images will be displayed in the receiver. * The argument should be one of <code>LEFT</code>, <code>RIGHT</code> * or <code>CENTER</code>. - * + * <p> + * Note that due to a restriction on some platforms, the first column + * is always left aligned. + * </p> * @param alignment the new alignment * * @exception SWTException <ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java index 45fbc0a6fb..5c50fb87db 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TableItem.java @@ -29,6 +29,9 @@ import org.eclipse.swt.graphics.*; * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#table">Table, TableItem, TableColumn snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class TableItem extends Item { Table parent; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java index 7a922a6afe..8cedb95249 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Text.java @@ -30,6 +30,13 @@ import org.eclipse.swt.graphics.*; /** * Instances of this class are selectable user interface * objects that allow the user to enter and modify text. + * Text controls can be either single or multi-line. + * When a text control is created with a border, the + * operating system includes a platform specific inset + * around the contents of the control. When created + * without a border, an effort is made to remove the + * inset such that the preferred size of the control + * is the same size as the contents. * <p> * <dl> * <dt><b>Styles:</b></dt> @@ -43,6 +50,10 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#text">Text snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Text extends Scrollable { int txnObject, frameHandle; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolBar.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolBar.java index 4d6f727b8b..669acb8316 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolBar.java @@ -39,6 +39,10 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#toolbar">ToolBar, ToolItem snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class ToolBar extends Composite { int itemCount; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java index c58332d0d6..1fd6f07480 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolItem.java @@ -41,6 +41,9 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#toolbar">ToolBar, ToolItem snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class ToolItem extends Item { int handle, iconHandle, labelHandle; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolTip.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolTip.java index 9856649b36..d6ae0a7d2e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolTip.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/ToolTip.java @@ -34,6 +34,10 @@ import org.eclipse.swt.events.*; * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#tooltips">Tool Tips snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> * * @since 3.2 */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java index c5e6a913a9..c2f25a8184 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tracker.java @@ -37,6 +37,9 @@ import org.eclipse.swt.internal.carbon.Rect; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#tracker">Tracker snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Tracker extends Widget { Control parent; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TrayItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TrayItem.java index def4438b7d..ac529d86af 100755 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TrayItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TrayItem.java @@ -31,6 +31,9 @@ import org.eclipse.swt.internal.cocoa.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#tray">Tray, TrayItem snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> * * @since 3.0 */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java index 1639789150..4aabe45bfc 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Tree.java @@ -62,12 +62,13 @@ import org.eclipse.swt.graphics.*; * </pre></code> * </p><p> * Note that although this class is a subclass of <code>Composite</code>, - * it does not make sense to add <code>Control</code> children to it, - * or set a layout on it. + * it does not normally make sense to add <code>Control</code> children to + * it, or set a layout on it, unless implementing something like a cell + * editor. * </p><p> * <dl> * <dt><b>Styles:</b></dt> - * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION, VIRTUAL</dd> + * <dd>SINGLE, MULTI, CHECK, FULL_SELECTION, VIRTUAL, NO_SCROLL</dd> * <dt><b>Events:</b></dt> * <dd>Selection, DefaultSelection, Collapse, Expand, SetData, MeasureItem, EraseItem, PaintItem</dd> * </dl> @@ -76,6 +77,10 @@ import org.eclipse.swt.graphics.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#tree">Tree, TreeItem, TreeColumn snippets</a> + * @see <a href="http://www.eclipse.org/swt/examples.php">SWT Example: ControlExample</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class Tree extends Composite { TreeItem [] items; @@ -131,6 +136,9 @@ public class Tree extends Composite { * @see SWT#SINGLE * @see SWT#MULTI * @see SWT#CHECK + * @see SWT#FULL_SELECTION + * @see SWT#VIRTUAL + * @see SWT#NO_SCROLL * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -835,6 +843,23 @@ public void deselectAll () { ignoreSelect = false; } +/** + * Deselects an item in the receiver. If the item was already + * deselected, it remains deselected. + * + * @param item the item to be deselected + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public void deselect (TreeItem item) { checkWidget (); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -2806,6 +2831,23 @@ public void selectAll () { ignoreSelect = false; } +/** + * Selects an item in the receiver. If the item was already + * selected, it remains selected. + * + * @param item the item to be selected + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.4 + */ public void select (TreeItem item) { checkWidget (); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeColumn.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeColumn.java index a929935a7e..428fb8d37e 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeColumn.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeColumn.java @@ -31,6 +31,9 @@ import org.eclipse.swt.events.*; * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#tree">Tree, TreeItem, TreeColumn snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> * * @since 3.1 */ @@ -93,7 +96,10 @@ public TreeColumn (Tree parent, int style) { * lists the style constants that are applicable to the class. * Style bits are also inherited from superclasses. * </p> - * + * <p> + * Note that due to a restriction on some platforms, the first column + * is always left aligned. + * </p> * @param parent a composite control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct * @param index the zero-relative index to store the receiver in its parent @@ -437,7 +443,10 @@ void resized (int newWidth) { * Controls how text and images will be displayed in the receiver. * The argument should be one of <code>LEFT</code>, <code>RIGHT</code> * or <code>CENTER</code>. - * + * <p> + * Note that due to a restriction on some platforms, the first column + * is always left aligned. + * </p> * @param alignment the new alignment * * @exception SWTException <ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java index 128af3b2b8..910c62e074 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/TreeItem.java @@ -31,6 +31,9 @@ import org.eclipse.swt.graphics.*; * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> + * + * @see <a href="http://www.eclipse.org/swt/snippets/#tree">Tree, TreeItem, TreeColumn snippets</a> + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public class TreeItem extends Item { Tree parent; diff --git a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java index dc665aca89..c58876b4cc 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/carbon/org/eclipse/swt/widgets/Widget.java @@ -49,6 +49,7 @@ import org.eclipse.swt.events.*; * </p> * * @see #checkSubclass + * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a> */ public abstract class Widget { int style, state; @@ -160,6 +161,7 @@ int actionProc (int theControl, int partCode) { * * @see Listener * @see SWT + * @see #getListeners(int) * @see #removeListener(int, Listener) * @see #notifyListeners */ @@ -1349,6 +1351,7 @@ int mouseProc (int nextHandler, int theEvent, int userData) { * * @see SWT * @see #addListener + * @see #getListeners(int) * @see #removeListener(int, Listener) */ public void notifyListeners (int eventType, Event event) { @@ -1466,7 +1469,7 @@ void releaseWidget () { * type is one of the event constants defined in class <code>SWT</code>. * * @param eventType the type of event to listen for - * @param listener the listener which should no longer be notified when the event occurs + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1479,6 +1482,7 @@ void releaseWidget () { * @see Listener * @see SWT * @see #addListener + * @see #getListeners(int) * @see #notifyListeners */ public void removeListener (int eventType, Listener handler) { @@ -1499,7 +1503,7 @@ public void removeListener (int eventType, Listener handler) { * </p> * * @param eventType the type of event to listen for - * @param listener the listener which should no longer be notified when the event occurs + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -1523,7 +1527,7 @@ protected void removeListener (int eventType, SWTEventListener handler) { * Removes the listener from the collection of listeners who will * be notified when the widget is disposed. * - * @param listener the listener which should no longer be notified when the receiver is disposed + * @param listener the listener which should no longer be notified * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> |