diff options
Diffstat (limited to 'bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt')
35 files changed, 839 insertions, 137 deletions
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java index 27ffa0f80c..255f728dea 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java @@ -668,6 +668,22 @@ public boolean isDisposed () { return disposed; } +/** + * Loads the font specified by a file. The font will be + * present in the list of fonts available to the application. + * + * @param path the font file path + * @return whether the font was successfully loaded + * + * @exception SWTException <ul> + * <li>ERROR_NULL_ARGUMENT - if path is null</li> + * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Font + * + * @since 3.3 + */ public boolean loadFont (String path) { checkDevice(); if (path == null) SWT.error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java index d51771c145..e833365a0a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java @@ -92,7 +92,7 @@ public final class FontData { String lang, country, variant; /** - * Constructs a new un-initialized font data. + * Constructs a new uninitialized font data. */ public FontData () { this("", 12, SWT.NORMAL); @@ -220,7 +220,7 @@ public boolean equals (Object object) { * * @return the height of this FontData * - * @see #setHeight + * @see #setHeight(int) */ public int getHeight() { return (int)(0.5f + height); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java index 071f6e60ac..9380d48bfa 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java @@ -89,8 +89,8 @@ GC() { /** * Constructs a new instance of this class which has been * configured to draw on the specified drawable. Sets the - * foreground and background color in the GC to match those - * in the drawable. + * foreground color, background color and font in the GC + * to match those in the drawable. * <p> * You must dispose the graphics context when it is no longer required. * </p> @@ -114,8 +114,8 @@ public GC(Drawable drawable) { /** * Constructs a new instance of this class which has been * configured to draw on the specified drawable. Sets the - * foreground and background color in the GC to match those - * in the drawable. + * foreground color, background color and font in the GC + * to match those in the drawable. * <p> * You must dispose the graphics context when it is no longer required. * </p> @@ -1161,7 +1161,12 @@ public void drawOval(int x, int y, int width, int height) { /** * Draws the path described by the parameter. - * + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * * @param path the path to draw * * @exception IllegalArgumentException <ul> @@ -1170,6 +1175,7 @@ public void drawOval(int x, int y, int width, int height) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * * @see Path @@ -1559,7 +1565,7 @@ public void drawText(String string, int x, int y, boolean isTransparent) { * @param string the string to be drawn * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn - * @param flags the flags specifing how to process the text + * @param flags the flags specifying how to process the text * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the string is null</li> @@ -1835,6 +1841,11 @@ public void fillOval(int x, int y, int width, int height) { /** * Fills the path described by the parameter. + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> * * @param path the path to fill * @@ -1844,6 +1855,7 @@ public void fillOval(int x, int y, int width, int height) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * * @see Path @@ -2093,6 +2105,7 @@ public int getAdvanceWidth(char ch) { * </ul> * * @see #setAdvanced + * * @since 3.1 */ public boolean getAdvanced() { @@ -2454,6 +2467,17 @@ public int getInterpolation() { return data.interpolation; } +/** + * Returns the receiver's line attributes. + * + * @return the line attributes used for drawing lines + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.3 + */ public LineAttributes getLineAttributes() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); float[] dashes = null; @@ -2486,7 +2510,7 @@ public int getLineCap() { * Returns the receiver's line dash style. The default value is * <code>null</code>. * - * @return the lin dash style used for drawing lines + * @return the line dash style used for drawing lines * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -2792,8 +2816,7 @@ boolean isIdentity(double[] matrix) { * advanced and normal graphics operations. Because the two subsystems are * different, their output may differ. Switching to advanced graphics before * any graphics operations are performed ensures that the output is consistent. - * </p> - * <p> + * </p><p> * Advanced graphics may not be installed for the operating system. In this * case, this operation does nothing. Some operating system have only one * graphics subsystem, so switching from normal to advanced graphics does @@ -2813,6 +2836,7 @@ boolean isIdentity(double[] matrix) { * @see #setBackgroundPattern * @see #setClipping(Path) * @see #setForegroundPattern + * @see #setLineAttributes * @see #setInterpolation * @see #setTextAntialias * @see #setTransform @@ -2841,13 +2865,21 @@ public void setAdvanced(boolean advanced) { /** * Sets the receiver's alpha value. - * + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> * @param alpha the alpha value * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * + * @see #getAdvanced + * @see #setAdvanced + * * @since 3.1 */ public void setAlpha(int alpha) { @@ -2863,6 +2895,11 @@ public void setAlpha(int alpha) { * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all * <em>non-text drawing</em> operations. + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> * * @param antialias the anti-aliasing setting * @@ -2872,8 +2909,11 @@ public void setAlpha(int alpha) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * + * @see #getAdvanced + * @see #setAdvanced * @see #setTextAntialias * * @since 3.1 @@ -2921,7 +2961,12 @@ public void setBackground(Color color) { /** * Sets the background pattern. The default value is <code>null</code>. - * + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * * @param pattern the new background pattern * * @exception IllegalArgumentException <ul> @@ -2929,9 +2974,12 @@ public void setBackground(Color color) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * * @see Pattern + * @see #getAdvanced + * @see #setAdvanced * * @since 3.1 */ @@ -3068,8 +3116,13 @@ public void setClipping(int x, int y, int width, int height) { /** * Sets the area of the receiver which can be changed * by drawing operations to the path specified - * by the argument. - * + * by the argument. + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * * @param path the clipping path. * * @exception IllegalArgumentException <ul> @@ -3077,9 +3130,12 @@ public void setClipping(int x, int y, int width, int height) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * * @see Path + * @see #getAdvanced + * @see #setAdvanced * * @since 3.1 */ @@ -3225,7 +3281,11 @@ public void setForeground(Color color) { /** * Sets the foreground pattern. The default value is <code>null</code>. - * + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> * @param pattern the new foreground pattern * * @exception IllegalArgumentException <ul> @@ -3233,9 +3293,12 @@ public void setForeground(Color color) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * * @see Pattern + * @see #getAdvanced + * @see #setAdvanced * * @since 3.1 */ @@ -3253,7 +3316,12 @@ public void setForegroundPattern(Pattern pattern) { * Sets the receiver's interpolation setting to the parameter, which * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, * <code>SWT.LOW</code> or <code>SWT.HIGH</code>. - * + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * * @param interpolation the new interpolation setting * * @exception IllegalArgumentException <ul> @@ -3262,8 +3330,12 @@ public void setForegroundPattern(Pattern pattern) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * + * @see #getAdvanced + * @see #setAdvanced + * * @since 3.1 */ public void setInterpolation(int interpolation) { @@ -3282,6 +3354,30 @@ public void setInterpolation(int interpolation) { data.interpolation = interpolation; } +/** + * Sets the receiver's line attributes. + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * @param attributes the line attributes + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the attributes is null</li> + * <li>ERROR_INVALID_ARGUMENT - if any of the line attributes is not valid</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> + * </ul> + * + * @see LineAttributes + * @see #getAdvanced + * @see #setAdvanced + * + * @since 3.3 + */ public void setLineAttributes(LineAttributes attributes) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (attributes == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -3585,7 +3681,12 @@ void setString(String string, int flags) { * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> * or <code>SWT.ON</code>. Note that this controls anti-aliasing only * for all <em>text drawing</em> operations. - * + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * * @param antialias the anti-aliasing setting * * @exception IllegalArgumentException <ul> @@ -3594,8 +3695,11 @@ void setString(String string, int flags) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * + * @see #getAdvanced + * @see #setAdvanced * @see #setAntialias * * @since 3.1 @@ -3624,11 +3728,16 @@ public void setTextAntialias(int antialias) { Cairo.cairo_font_options_destroy(options); } -/** +/** * Sets the transform that is currently being used by the receiver. If * the argument is <code>null</code>, the current transform is set to * the identity transform. - * + * <p> + * This operation requires the operating system's advanced + * graphics subsystem which may not be available on some + * platforms. + * </p> + * * @param transform the transform to set * * @exception IllegalArgumentException <ul> @@ -3636,9 +3745,12 @@ public void setTextAntialias(int antialias) { * </ul> * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li> * </ul> * * @see Transform + * @see #getAdvanced + * @see #setAdvanced * * @since 3.1 */ @@ -3750,7 +3862,7 @@ public Point textExtent(String string) { * </p> * * @param string the string to measure - * @param flags the flags specifing how to process the text + * @param flags the flags specifying how to process the text * @return a point containing the extent of the string * * @exception IllegalArgumentException <ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java index 50d6475927..aaa54b2cfc 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/TextLayout.java @@ -302,6 +302,33 @@ public void draw(GC gc, int x, int y, int selectionStart, int selectionEnd, Colo draw(gc, x, y, selectionStart, selectionEnd, selectionForeground, selectionBackground, 0); } +/** + * Draws the receiver's text using the specified GC at the specified + * point. + * <p> + * The parameter <code>flags</code> can include one of <code>SWT.DELIMITER_SELECTION</code> + * or <code>SWT.FULL_SELECTION</code> to specify the selection behavior on all lines except + * for the last line, and can also include <code>SWT.LAST_LINE_SELECTION</code> to extend + * the specified selection behavior to the last line. + * </p> + * @param gc the GC to draw + * @param x the x coordinate of the top left corner of the rectangular area where the text is to be drawn + * @param y the y coordinate of the top left corner of the rectangular area where the text is to be drawn + * @param selectionStart the offset where the selections starts, or -1 indicating no selection + * @param selectionEnd the offset where the selections ends, or -1 indicating no selection + * @param selectionForeground selection foreground, or NULL to use the system default color + * @param selectionBackground selection background, or NULL to use the system default color + * @param flags drawing options + * + * @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> + * + * @since 3.3 + */ public void draw(GC gc, int x, int y, int selectionStart, int selectionEnd, Color selectionForeground, Color selectionBackground, int flags) { checkLayout (); computeRuns(); @@ -662,7 +689,7 @@ public boolean getJustify () { * embedding level is usually used to determine the directionality of a * character in bidirectional text. * - * @param offset the charecter offset + * @param offset the character offset * @return the embedding level * * @exception IllegalArgumentException <ul> @@ -891,7 +918,8 @@ public Point getLocation(int offset, boolean trailing) { /** * Returns the next offset for the specified offset and movement * type. The movement is one of <code>SWT.MOVEMENT_CHAR</code>, - * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>. + * <code>SWT.MOVEMENT_CLUSTER</code>, <code>SWT.MOVEMENT_WORD</code>, + * <code>SWT.MOVEMENT_WORD_END</code> or <code>SWT.MOVEMENT_WORD_START</code>. * * @param offset the start offset * @param movement the movement type @@ -1060,7 +1088,8 @@ public int getOrientation() { /** * Returns the previous offset for the specified offset and movement * type. The movement is one of <code>SWT.MOVEMENT_CHAR</code>, - * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>. + * <code>SWT.MOVEMENT_CLUSTER</code> or <code>SWT.MOVEMENT_WORD</code>, + * <code>SWT.MOVEMENT_WORD_END</code> or <code>SWT.MOVEMENT_WORD_START</code>. * * @param offset the start offset * @param movement the movement type 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 a92c8856b1..4843505231 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 @@ -104,11 +104,11 @@ static int checkStyle (int style) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the control is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> - * <code>widgetSelected</code> is called when the control is selected. + * <code>widgetSelected</code> is called when the control is selected by the user. * <code>widgetDefaultSelected</code> is not called. * </p> * @@ -454,7 +454,7 @@ void releaseWidget () { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * @@ -628,7 +628,12 @@ void setForegroundColor (GdkColor color) { /** * Sets the receiver's image to the argument, which may be * <code>null</code> indicating that no image should be displayed. - * + * <p> + * Note that a Button can display an image and text simultaneously + * on Windows (starting with XP), GTK+ and OSX. On other platforms, + * a Button that has an image and text set into it will display the + * image or text that was set most recently. + * </p> * @param image the image to display on the receiver (may be <code>null</code>) * * @exception IllegalArgumentException <ul> @@ -711,12 +716,16 @@ public void setSelection (boolean selected) { * character to be the mnemonic. When the user presses a * key sequence that matches the mnemonic, a selection * event occurs. On most platforms, the mnemonic appears - * underlined but may be emphasised in a platform specific + * underlined but may be emphasized in a platform specific * manner. The mnemonic indicator character '&' can be * escaped by doubling it in the string, causing a single * '&' to be displayed. + * </p><p> + * Note that a Button can display an image and text simultaneously + * on Windows (starting with XP), GTK+ and OSX. On other platforms, + * a Button that has an image and text set into it will display the + * image or text that was set most recently. * </p> - * * @param string the new text * * @exception IllegalArgumentException <ul> 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 b4cd8dfe44..a2a12058a6 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java @@ -42,7 +42,7 @@ import org.eclipse.swt.events.*; * <dt><b>Styles:</b></dt> * <dd>DROP_DOWN, READ_ONLY, SIMPLE</dd> * <dt><b>Events:</b></dt> - * <dd>DefaultSelection, Modify, Selection</dd> + * <dd>DefaultSelection, Modify, Selection, Verify</dd> * </dl> * <p> * Note: Only one of the styles DROP_DOWN and SIMPLE may be specified. @@ -217,11 +217,11 @@ public void addModifyListener (ModifyListener listener) { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's selection changes, by sending + * be notified when the user changes the receiver's selection, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> - * <code>widgetSelected</code> is called when the combo's list selection changes. + * <code>widgetSelected</code> is called when the user changes the combo's list selection. * <code>widgetDefaultSelected</code> is typically called when ENTER is pressed the combo's text area. * </p> * @@ -1470,7 +1470,7 @@ public void removeModifyListener (ModifyListener listener) { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's selection changes. + * be notified when the user changes the receiver's selection. * * @param listener the listener which should no longer be notified * @@ -1619,9 +1619,7 @@ void setForegroundColor (GdkColor color) { /** * Sets the text of the item in the receiver's list at the given - * zero-relative index to the string argument. This is equivalent - * to removing the old item at the index, and then adding the new - * item at that index. + * zero-relative index to the string argument. * * @param index the index for the item * @param string the new text for the item 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 ebad55743b..6c8b41e992 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 @@ -800,7 +800,13 @@ boolean isTabGroup() { * <p> * This is equivalent to calling <code>layout(true)</code>. * </p> - * + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> + * * @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> @@ -826,7 +832,14 @@ public void layout () { * will cascade down through all child widgets in the receiver's widget * tree until a child is encountered that does not resize. Note that * a layout due to a resize will not flush any cached information - * (same as <code>layout(false)</code>).</p> + * (same as <code>layout(false)</code>). + * </p> + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> * * @param changed <code>true</code> if the layout must flush its caches, and <code>false</code> otherwise * @@ -857,7 +870,14 @@ public void layout (boolean changed) { * tree. However, if a child is resized as a result of a call to layout, the * resize event will invoke the layout of the child. Note that * a layout due to a resize will not flush any cached information - * (same as <code>layout(false)</code>).</p> + * (same as <code>layout(false)</code>). + * </p> + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> * * @param changed <code>true</code> if the layout must flush its caches, and <code>false</code> otherwise * @param all <code>true</code> if all children in the receiver's widget tree should be laid out, and <code>false</code> otherwise @@ -884,6 +904,12 @@ public void layout (boolean changed, boolean all) { * (potentially) optimize the work it is doing by assuming that none of the * peers of the changed control have changed state since the last layout. * If an ancestor does not have a layout, skip it. + * <p> + * Note: Layout is different from painting. If a child is + * moved or resized such that an area in the parent is + * exposed, then the parent will paint. If no child is + * affected, the parent will not paint. + * </p> * * @param changed a control that has had a state change which requires a recalculation of its size * 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 61484f6d95..940f51f215 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 @@ -27,9 +27,8 @@ import org.eclipse.swt.accessibility.*; * <dd>BORDER</dd> * <dd>LEFT_TO_RIGHT, RIGHT_TO_LEFT</dd> * <dt><b>Events:</b> - * <dd>FocusIn, FocusOut, Help, KeyDown, KeyUp, MouseDoubleClick, MouseDown, MouseEnter, - * MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse, - * DragDetect, MenuDetect</dd> + * <dd>DragDetect, FocusIn, FocusOut, Help, KeyDown, KeyUp, MenuDetect, MouseDoubleClick, MouseDown, MouseEnter, + * MouseExit, MouseHover, MouseUp, MouseMove, Move, Paint, Resize, Traverse</dd> * </dl> * </p><p> * Only one of LEFT_TO_RIGHT or RIGHT_TO_LEFT may be specified. @@ -1082,6 +1081,27 @@ public void addControlListener(ControlListener listener) { addListener (SWT.Move,typedListener); } +/** + * Adds the listener to the collection of listeners who will + * be notified when a drag gesture occurs, by sending it + * one of the messages defined in the <code>DragDetectListener</code> + * interface. + * + * @param listener the listener which should be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener 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> + * + * @see DragDetectListener + * @see #removeDragDetectListener + * + * @since 3.3 + */ public void addDragDetectListener (DragDetectListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -1147,7 +1167,18 @@ public void addHelpListener (HelpListener listener) { * be notified when keys are pressed and released on the system keyboard, by sending * it one of the messages defined in the <code>KeyListener</code> * interface. - * + * <p> + * When a key listener is added to a control, the control + * will take part in widget traversal. By default, all + * traversal keys (such as the tab key and so on) are + * delivered to the control. In order for a control to take + * part in traversal, it should listen for traversal events. + * Otherwise, the user can traverse into a control but not + * out. Note that native controls such as table and tree + * implement key traversal in the operating system. It is + * not necessary to add traversal listeners for these controls, + * unless you want to override the default traversal. + * </p> * @param listener the listener which should be notified * * @exception IllegalArgumentException <ul> @@ -1387,6 +1418,25 @@ public void removeControlListener (ControlListener listener) { eventTable.unhook (SWT.Resize, listener); } +/** + * Removes the listener from the collection of listeners who will + * be notified when a drag gesture occurs. + * + * @param listener the listener which should no longer be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener 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> + * + * @see DragDetectListener + * @see #addDragDetectListener + * + * @since 3.3 + */ public void removeDragDetectListener(DragDetectListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -1656,12 +1706,84 @@ public void removeTraverseListener(TraverseListener listener) { eventTable.unhook (SWT.Traverse, listener); } +/** + * Detects a drag and drop gesture. This method is used + * to detect a drag gesture when called from within a mouse + * down listener. + * + * <p>By default, a drag is detected when the gesture + * occurs anywhere within the client area of a control. + * Some controls, such as tables and trees, override this + * behavior. In addition to the operating system specific + * drag gesture, they require the mouse to be inside an + * item. Custom widget writers can use <code>setDragDetect</code> + * to disable the default detection, listen for mouse down, + * and then call <code>dragDetect()</code> from within the + * listener to conditionally detect a drag. + * </p> + * + * @param event the mouse down event + * + * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * </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 DragDetectListener + * @see #addDragDetectListener + * + * @see #getDragDetect + * @see #setDragDetect + * + * @since 3.3 + */ public boolean dragDetect (Event event) { checkWidget (); if (event == null) error (SWT.ERROR_NULL_ARGUMENT); return dragDetect (event.button, event.count, event.stateMask, event.x, event.y); } +/** + * Detects a drag and drop gesture. This method is used + * to detect a drag gesture when called from within a mouse + * down listener. + * + * <p>By default, a drag is detected when the gesture + * occurs anywhere within the client area of a control. + * Some controls, such as tables and trees, override this + * behavior. In addition to the operating system specific + * drag gesture, they require the mouse to be inside an + * item. Custom widget writers can use <code>setDragDetect</code> + * to disable the default detection, listen for mouse down, + * and then call <code>dragDetect()</code> from within the + * listener to conditionally detect a drag. + * </p> + * + * @param event the mouse down event + * + * @return <code>true</code> if the gesture occurred, and <code>false</code> otherwise. + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT when the event is null</li> + * </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 DragDetectListener + * @see #addDragDetectListener + * + * @see #getDragDetect + * @see #setDragDetect + * + * @since 3.3 + */ public boolean dragDetect (MouseEvent event) { checkWidget (); if (event == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -1880,11 +2002,38 @@ public int getBorderWidth () { return 0; } +/** + * Returns the receiver's cursor, or null if it has not been set. + * <p> + * When the mouse pointer passes over a control its appearance + * is changed to match the control's cursor. + * </p> + * </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.3 + */ public Cursor getCursor () { checkWidget (); return cursor; } +/** + * Returns <code>true</code> if the receiver is detecting + * drag gestures, and <code>false</code> otherwise. + * + * @return the receiver's drag detect 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.3 + */ public boolean getDragDetect () { checkWidget (); return (state & DRAG_DETECT) != 0; @@ -2742,12 +2891,13 @@ void register () { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #update + * @see #update() * @see PaintListener * @see SWT#Paint * @see SWT#NO_BACKGROUND * @see SWT#NO_REDRAW_RESIZE * @see SWT#NO_MERGE_PAINTS + * @see SWT#DOUBLE_BUFFERED */ public void redraw () { checkWidget(); @@ -2782,12 +2932,13 @@ void redraw (boolean all) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #update + * @see #update() * @see PaintListener * @see SWT#Paint * @see SWT#NO_BACKGROUND * @see SWT#NO_REDRAW_RESIZE * @see SWT#NO_MERGE_PAINTS + * @see SWT#DOUBLE_BUFFERED */ public void redraw (int x, int y, int width, int height, boolean all) { checkWidget(); @@ -2974,7 +3125,10 @@ void setBackground () { * Sets the receiver's background color to the color specified * by the argument, or to the default system color for the control * if the argument is null. - * + * <p> + * Note: This operation is a hint and may be overridden by the platform. + * For example, on Windows the background of a Button cannot be changed. + * </p> * @param color the new color (or null) * * @exception IllegalArgumentException <ul> @@ -3038,7 +3192,10 @@ void setBackgroundColor (GdkColor color) { * by the argument, or to the default system color for the control * if the argument is null. The background image is tiled to fill * the available space. - * + * <p> + * Note: This operation is a hint and may be overridden by the platform. + * For example, on Windows the background of a Button cannot be changed. + * </p> * @param image the new image (or null) * * @exception IllegalArgumentException <ul> @@ -3133,6 +3290,20 @@ void setCursor (int /*long*/ cursor) { } } +/** + * Sets the receiver's drag detect state. If the argument is + * <code>true</code>, the receiver will detect drag gestures, + * otherwise these gestures will be ignored. + * + * @param dragDetect the new drag detect 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.3 + */ public void setDragDetect (boolean dragDetect) { checkWidget (); if (dragDetect) { @@ -3277,7 +3448,9 @@ void setFontDescription (int /*long*/ font) { * Sets the receiver's foreground color to the color specified * by the argument, or to the default system color for the control * if the argument is null. - * + * <p> + * Note: This operation is a hint and may be overridden by the platform. + * </p> * @param color the new color (or null) * * @exception IllegalArgumentException <ul> @@ -3456,7 +3629,7 @@ boolean setRadioSelection (boolean value) { * </ul> * * @see #redraw(int, int, int, int, boolean) - * @see #update + * @see #update() */ public void setRedraw (boolean redraw) { checkWidget(); @@ -3989,13 +4162,19 @@ boolean traverseMnemonic (char key) { /** * Forces all outstanding paint requests for the widget - * to be processed before this method returns. + * to be processed before this method returns. If there + * are no outstanding paint request, this method does + * nothing. + * <p> + * Note: This method does not cause a redraw. + * </p> * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * + * @see #redraw() * @see #redraw(int, int, int, int, boolean) * @see PaintListener * @see SWT#Paint diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DateTime.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DateTime.java index 7bf38e5642..7cdd1541aa 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DateTime.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DateTime.java @@ -18,6 +18,29 @@ import org.eclipse.swt.events.*; import org.eclipse.swt.graphics.*; import org.eclipse.swt.internal.gtk.OS; +/** + * Instances of this class are selectable user interface + * objects that allow the user to enter and modify date + * or time values. + * <p> + * Note that although this class is a subclass of <code>Composite</code>, + * it does not make sense to add children to it, or set a layout on it. + * </p> + * <dl> + * <dt><b>Styles:</b></dt> + * <dd>DATE, TIME, CALENDAR, SHORT, MEDIUM, LONG</dd> + * <dt><b>Events:</b></dt> + * <dd>Selection</dd> + * </dl> + * <p> + * Note: Only one of the styles DATE, TIME, or CALENDAR may be specified, + * and only one of the styles SHORT, MEDIUM, or LONG may be specified. + * </p><p> + * IMPORTANT: This class is <em>not</em> intended to be subclassed. + * </p> + * + * @since 3.3 + */ public class DateTime extends Composite { int day, month, year, hours, minutes, seconds; @@ -41,6 +64,36 @@ public class DateTime extends Composite { static final String DEFAULT_MEDIUM_TIME_FORMAT = "HH:MM:SS AM"; static final String DEFAULT_LONG_TIME_FORMAT = "HH:MM:SS AM"; +/** + * 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 composite 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 SWT#DATE + * @see SWT#TIME + * @see SWT#CALENDAR + * @see Widget#checkSubclass + * @see Widget#getStyle + */ public DateTime (Composite parent, int style) { super (parent, checkStyle (style)); if ((this.style & SWT.CALENDAR) == 0) { @@ -109,6 +162,30 @@ static int checkStyle (int style) { return checkBits (style, SWT.MEDIUM, SWT.SHORT, SWT.LONG, 0, 0, 0); } +/** + * Adds the listener to the collection of listeners who will + * be notified when the control is selected by the user, by sending + * it one of the messages defined in the <code>SelectionListener</code> + * interface. + * <p> + * <code>widgetSelected</code> is called when the user changes the control's value. + * <code>widgetDefaultSelected</code> is not called. + * </p> + * + * @param listener the listener which should be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener 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> + * + * @see SelectionListener + * @see #removeSelectionListener + * @see SelectionEvent + */ public void addSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -250,6 +327,19 @@ void getDate() { day = d[0]; } +/** + * Returns the receiver's date, or day of the month. + * <p> + * The first day of the month is 1, and the last day depends on the month and year. + * </p> + * + * @return a positive integer beginning with 1 + * + * @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 getDay () { checkWidget (); if ((style & SWT.CALENDAR) != 0) { @@ -260,6 +350,19 @@ public int getDay () { } } +/** + * Returns the receiver's hours. + * <p> + * Hours is an integer between 0 and 23. + * </p> + * + * @return an integer between 0 and 23 + * + * @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 getHours () { checkWidget (); if ((style & SWT.CALENDAR) != 0) { @@ -269,6 +372,19 @@ public int getHours () { } } +/** + * Returns the receiver's minutes. + * <p> + * Minutes is an integer between 0 and 59. + * </p> + * + * @return an integer between 0 and 59 + * + * @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 getMinutes () { checkWidget (); if ((style & SWT.CALENDAR) != 0) { @@ -278,6 +394,19 @@ public int getMinutes () { } } +/** + * Returns the receiver's month. + * <p> + * The first month of the year is 0, and the last month is 11. + * </p> + * + * @return an integer between 0 and 11 + * + * @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 getMonth () { checkWidget (); if ((style & SWT.CALENDAR) != 0) { @@ -288,6 +417,19 @@ public int getMonth () { } } +/** + * Returns the receiver's seconds. + * <p> + * Seconds is an integer between 0 and 59. + * </p> + * + * @return an integer between 0 and 59 + * + * @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 getSeconds () { checkWidget (); if ((style & SWT.CALENDAR) != 0) { @@ -297,6 +439,19 @@ public int getSeconds () { } } +/** + * Returns the receiver's year. + * <p> + * The first year is 1752 and the last year is 9999. + * </p> + * + * @return an integer between 1752 and 9999 + * + * @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 getYear () { checkWidget (); if ((style & SWT.CALENDAR) != 0) { @@ -495,6 +650,23 @@ void releaseWidget () { //TODO: need to do anything here? } +/** + * Removes the listener from the collection of listeners who will + * be notified when the control is selected by the user. + * + * @param listener the listener which should no longer be notified + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the listener 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> + * + * @see SelectionListener + * @see #addSelectionListener + */ public void removeSelectionListener (SelectionListener listener) { checkWidget (); if (listener == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -638,6 +810,19 @@ void setTextField(int fieldName, int value, boolean commit, boolean adjust) { if (commit) setField(fieldName, value); } +/** + * Sets the receiver's date, or day of the month, to the specified day. + * <p> + * The first day of the month is 1, and the last day depends on the month and year. + * </p> + * + * @param day a positive integer beginning with 1 + * + * @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 setDay (int day) { checkWidget (); if (!isValid(Calendar.DAY_OF_MONTH, day)) return; @@ -650,6 +835,19 @@ public void setDay (int day) { } } +/** + * Sets the receiver's hours. + * <p> + * Hours is an integer between 0 and 23. + * </p> + * + * @param hours an integer between 0 and 23 + * + * @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 setHours (int hours) { checkWidget (); if (!isValid(Calendar.HOUR_OF_DAY, hours)) return; @@ -661,6 +859,19 @@ public void setHours (int hours) { } } +/** + * Sets the receiver's minutes. + * <p> + * Minutes is an integer between 0 and 59. + * </p> + * + * @param minutes an integer between 0 and 59 + * + * @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 setMinutes (int minutes) { checkWidget (); if (!isValid(Calendar.MINUTE, minutes)) return; @@ -672,6 +883,19 @@ public void setMinutes (int minutes) { } } +/** + * Sets the receiver's month. + * <p> + * The first month of the year is 0, and the last month is 11. + * </p> + * + * @param month an integer between 0 and 11 + * + * @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 setMonth (int month) { checkWidget (); if (!isValid(Calendar.MONTH, month)) return; @@ -684,6 +908,19 @@ public void setMonth (int month) { } } +/** + * Sets the receiver's seconds. + * <p> + * Seconds is an integer between 0 and 59. + * </p> + * + * @param seconds an integer between 0 and 59 + * + * @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 setSeconds (int seconds) { checkWidget (); if (!isValid(Calendar.SECOND, seconds)) return; @@ -695,6 +932,19 @@ public void setSeconds (int seconds) { } } +/** + * Sets the receiver's year. + * <p> + * The first year is 1752 and the last year is 9999. + * </p> + * + * @param year an integer between 1752 and 9999 + * + * @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 setYear (int year) { checkWidget (); //if (!isValid(Calendar.YEAR, year)) return; 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 1d7a2dd445..cfa7626fbd 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 @@ -286,7 +286,7 @@ void fixDecorations (Decorations newDecorations, Control control, Menu [] menus) * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #setDefaultButton + * @see #setDefaultButton(Button) */ public Button getDefaultButton () { checkWidget(); 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 ab263f283c..237716e172 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java @@ -79,7 +79,7 @@ import org.eclipse.swt.graphics.*; * <dt><b>Styles:</b></dt> * <dd>(none)</dd> * <dt><b>Events:</b></dt> - * <dd>Close, Dispose</dd> + * <dd>Close, Dispose, Settings</dd> * </dl> * <p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -3880,7 +3880,7 @@ int /*long*/ styleSetProc (int /*long*/ gobject, int /*long*/ arg1, int /*long*/ * @param runnable code to run on the user-interface thread or <code>null</code> * * @exception SWTException <ul> - * <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li> + * <li>ERROR_FAILED_EXEC - if an exception occurred when executing the runnable</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> * 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 2762d3fa94..48ab07f547 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 @@ -79,11 +79,11 @@ public Link (Composite parent, int style) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the control is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> - * <code>widgetSelected</code> is called when the control is selected. + * <code>widgetSelected</code> is called when the control is selected by the user. * <code>widgetDefaultSelected</code> is not called. * </p> * @@ -467,7 +467,7 @@ void releaseWidget () { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * 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 4a6f14618b..b264def3e6 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 @@ -146,7 +146,7 @@ public void add (String string, int index) { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's selection changes, by sending + * be notified when the user changes the receiver's selection, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -154,7 +154,7 @@ public void add (String string, int index) { * <code>widgetDefaultSelected</code> is typically called when an item is double-clicked. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the user changes the receiver's selection * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -878,7 +878,7 @@ public int indexOf (String string, int start) { * range are ignored. * * @param index the index of the item - * @return the visibility state of the item at the index + * @return the selection state of the item at the index * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -1058,7 +1058,7 @@ public void removeAll () { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's selection changes. + * be notified when the user changes the receiver's selection. * * @param listener the listener which should no longer be notified * @@ -1278,9 +1278,7 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize /** * Sets the text of the item in the receiver's list at the given - * zero-relative index to the string argument. This is equivalent - * to <code>remove</code>'ing the old item at the index, and then - * <code>add</code>'ing the new item at that index. + * zero-relative index to the string argument. * * @param index the index for the item * @param string the new text for the item 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 e0f995220b..f6f1c59c55 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 @@ -622,7 +622,7 @@ void hookEvents () { * @return the index of the item * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the string is null</li> + * <li>ERROR_NULL_ARGUMENT - if the item is null</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/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java index 7b2999efd1..3fe760ba7c 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 @@ -187,7 +187,7 @@ public void addHelpListener (HelpListener listener) { /** * Adds the listener to the collection of listeners who will - * be notified when the menu item is selected, by sending + * be notified when the menu item is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -195,7 +195,7 @@ public void addHelpListener (HelpListener listener) { * <code>widgetDefaultSelected</code> is not called. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the menu item is selected by the user * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -563,7 +563,7 @@ public void removeHelpListener (HelpListener listener) { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java index 48aafc07cd..d69e49d79c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java @@ -116,7 +116,7 @@ public void setMessage (String string) { * of the display. * * @return the ID of the button that was selected to dismiss the - * message box (e.g. SWT.OK, SWT.CANCEL, etc...) + * message box (e.g. SWT.OK, SWT.CANCEL, etc.) * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the dialog has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java index b117622fd2..c379605bb7 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java @@ -15,7 +15,7 @@ import org.eclipse.swt.*; import org.eclipse.swt.internal.gtk.*; /** - * Instances of the receiver represent is an unselectable + * Instances of the receiver represent an unselectable * user interface object that is used to display progress, * typically in the form of a bar. * <dl> 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 0134c1be91..d42980e145 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 @@ -76,7 +76,7 @@ public Sash (Composite parent, int style) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the control is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -85,7 +85,7 @@ public Sash (Composite parent, int style) { * <code>widgetDefaultSelected</code> is not called. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the control is selected by the user * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -394,7 +394,7 @@ void releaseWidget () { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * 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 2fe42efb04..e113dd4db9 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 @@ -71,11 +71,11 @@ public Scale (Composite parent, int style) { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's value changes, by sending + * be notified when the user changes the receiver's value, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> - * <code>widgetSelected</code> is called when the control's value changes. + * <code>widgetSelected</code> is called when the user changes the receiver's value. * <code>widgetDefaultSelected</code> is not called. * </p> * @@ -241,7 +241,7 @@ int /*long*/ gtk_value_changed (int /*long*/ adjustment) { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's value changes. + * be notified when the user changes the receiver's value. * * @param listener the listener which should no longer be notified * 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 24aa86e030..3672b01885 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 @@ -99,7 +99,7 @@ ScrollBar (Scrollable parent, int style) { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's value changes, by sending + * be notified when the user changes the receiver's value, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -115,7 +115,7 @@ ScrollBar (Scrollable parent, int style) { * <code>widgetDefaultSelected</code> is not called. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the user changes the receiver's value * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -472,7 +472,7 @@ void releaseWidget () { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's value changes. + * be notified when the user changes the receiver's value. * * @param listener the listener which should no longer be notified * 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 d4420539ed..8405e2841b 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 @@ -867,7 +867,7 @@ Shell _getShell () { } /** * Returns an array containing all shells which are - * descendents of the receiver. + * descendants of the receiver. * <p> * @return the dialog shells * @@ -1037,7 +1037,7 @@ int /*long*/ gtk_window_state_event (int /*long*/ widget, int /*long*/ event) { * @see Control#setFocus * @see Control#setVisible * @see Display#getActiveShell - * @see Decorations#setDefaultButton + * @see Decorations#setDefaultButton(Button) * @see Shell#setActive * @see Shell#forceActive */ @@ -1094,7 +1094,7 @@ public void removeShellListener (ShellListener listener) { * @see Control#setFocus * @see Control#setVisible * @see Display#getActiveShell - * @see Decorations#setDefaultButton + * @see Decorations#setDefaultButton(Button) * @see Shell#open * @see Shell#setActive */ @@ -1662,7 +1662,7 @@ public void dispose () { * @see Control#setFocus * @see Control#setVisible * @see Display#getActiveShell - * @see Decorations#setDefaultButton + * @see Decorations#setDefaultButton(Button) * @see Shell#open * @see Shell#setActive */ 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 b5b2d811ac..9f714644de 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 @@ -102,7 +102,7 @@ public Slider (Composite parent, int style) { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's value changes, by sending + * be notified when the user changes the receiver's value, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -118,7 +118,7 @@ public Slider (Composite parent, int style) { * <code>widgetDefaultSelected</code> is not called. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the user changes the receiver's value * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -371,7 +371,7 @@ public int getThumb () { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's value changes. + * be notified when the user changes the receiver's value. * * @param listener the listener which should no longer be notified * 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 9115eb2f67..eb50c854d2 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 @@ -22,11 +22,14 @@ import org.eclipse.swt.events.*; * objects that allow the user to enter and modify numeric * values. * <p> + * Note that although this class is a subclass of <code>Composite</code>, + * it does not make sense to add children to it, or set a layout on it. + * </p><p> * <dl> * <dt><b>Styles:</b></dt> * <dd>READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> - * <dd>Selection, Modify</dd> + * <dd>Selection, Modify, Verify</dd> * </dl> * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. @@ -102,7 +105,7 @@ public void addModifyListener (ModifyListener listener) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the control is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -110,7 +113,7 @@ public void addModifyListener (ModifyListener listener) { * <code>widgetDefaultSelected</code> is typically called when ENTER is pressed in a single-line text. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the control is selected by the user * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -733,7 +736,7 @@ public void removeModifyListener (ModifyListener listener) { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * 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 51ee72e4e9..5fb9aee82c 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 @@ -102,7 +102,7 @@ int /*long*/ childStyle () { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's selection changes, by sending + * be notified when the user changes the receiver's selection, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -110,7 +110,7 @@ int /*long*/ childStyle () { * <code>widgetDefaultSelected</code> is not called. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the user changes the receiver's selection * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -427,7 +427,7 @@ void hookEvents () { * @return the index of the item * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the string is null</li> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -524,7 +524,7 @@ void removeControl (Control control) { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's selection changes. + * be notified when the user changes the receiver's selection. * * @param listener the listener which should no longer be notified * 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 645942927b..539baca31b 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 @@ -286,18 +286,18 @@ protected void checkSubclass () { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's selection changes, by sending + * be notified when the user changes the receiver's selection, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> * When <code>widgetSelected</code> is called, the item field of the event object is valid. - * If the receiver has <code>SWT.CHECK</code> style set and the check selection changes, + * If the receiver has the <code>SWT.CHECK</code> style and the check selection changes, * the event object detail field contains the value <code>SWT.CHECK</code>. * <code>widgetDefaultSelected</code> is typically called when an item is double-clicked. * The item field of the event object is valid for default selection, but the detail field is not used. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the user changes the receiver's selection * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -2019,7 +2019,7 @@ void hookEvents () { * @return the index of the column * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the string is null</li> + * <li>ERROR_NULL_ARGUMENT - if the column is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2045,7 +2045,7 @@ public int indexOf (TableColumn column) { * @return the index of the item * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the string is null</li> + * <li>ERROR_NULL_ARGUMENT - if the item is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2078,7 +2078,7 @@ public int indexOf (TableItem item) { * range are ignored. * * @param index the index of the item - * @return the visibility state of the item at the index + * @return the selection state of the item at the index * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2382,7 +2382,7 @@ public void removeAll () { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's selection changes. + * be notified when the user changes the receiver's selection. * * @param listener the listener which should no longer be notified * 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 49be0567ba..e766a161dd 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 @@ -145,7 +145,7 @@ public void addControlListener(ControlListener listener) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the control is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -153,7 +153,7 @@ public void addControlListener(ControlListener listener) { * <code>widgetDefaultSelected</code> is not called. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the control is selected by the user * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -471,7 +471,7 @@ public void removeControlListener (ControlListener listener) { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * 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 1eeae3acd7..b51cf283a2 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 @@ -615,6 +615,22 @@ public String getText (int index) { return new String (Converter.mbcsToWcs (null, buffer)); } +/** + * Returns a rectangle describing the size and location + * relative to its parent of the text at a column in the + * table. An empty rectangle is returned if index exceeds + * the index of the table's last column. + * + * @param index the index that specifies the column + * @return the receiver's bounding text 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.3 + */ public Rectangle getTextBounds (int index) { checkWidget (); if (!parent.checkData (this)) error (SWT.ERROR_WIDGET_DISPOSED); 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 fe446a72ae..907d3c9d9c 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 @@ -23,12 +23,13 @@ import org.eclipse.swt.events.*; * <p> * <dl> * <dt><b>Styles:</b></dt> - * <dd>CENTER, LEFT, MULTI, PASSWORD, SINGLE, RIGHT, READ_ONLY, WRAP</dd> + * <dd>CANCEL, CENTER, LEFT, MULTI, PASSWORD, SEARCH, SINGLE, RIGHT, READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> * <dd>DefaultSelection, Modify, Verify</dd> * </dl> * <p> - * Note: Only one of the styles MULTI and SINGLE may be specified. + * Note: Only one of the styles MULTI and SINGLE may be specified, + * and only one of the styles LEFT, CENTER, and RIGHT may be specified. * </p><p> * IMPORTANT: This class is <em>not</em> intended to be subclassed. * </p> @@ -200,15 +201,17 @@ public void addModifyListener (ModifyListener listener) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the control is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> * <code>widgetSelected</code> is not called for texts. - * <code>widgetDefaultSelected</code> is typically called when ENTER is pressed in a single-line text. + * <code>widgetDefaultSelected</code> is typically called when ENTER is pressed in a single-line text, + * or when ENTER is pressed in a search text. If the receiver has the <code>SWT.SEARCH | SWT.CANCEL</code> style + * and the user cancels the search, the event object detail field contains the value <code>SWT.CANCEL</code>. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the control is selected by the user * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -749,6 +752,25 @@ public int getLineHeight () { return fontHeight (getFontDescription (), handle); } +/** + * Returns the widget message. When the widget is created + * with the style <code>SWT.SEARCH</code>, the message text + * is displayed as a hint for the user, indicating the + * purpose of the field. + * <p> + * Note: This operation is a <em>HINT</em> and is not + * supported on platforms that do not have this concept. + * </p> + * + * @return the widget message + * + * @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.3 + */ public String getMessage () { checkWidget (); return message; @@ -1474,7 +1496,7 @@ public void removeModifyListener (ModifyListener listener) { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * @@ -1635,6 +1657,28 @@ void setFontDescription (int /*long*/ font) { setTabStops (tabs); } +/** + * Sets the widget message. When the widget is created + * with the style <code>SWT.SEARCH</code>, the message text + * is displayed as a hint for the user, indicating the + * purpose of the field. + * <p> + * Note: This operation is a <em>HINT</em> and is not + * supported on platforms that do not have this concept. + * </p> + * + * @param message the new message + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the message 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.3 + */ public void setMessage (String message) { checkWidget (); if (message == null) error (SWT.ERROR_NULL_ARGUMENT); 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 fe4d483e75..53a7fd686a 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 @@ -129,7 +129,7 @@ public ToolItem (ToolBar parent, int style, int index) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the control is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -138,7 +138,7 @@ public ToolItem (ToolBar parent, int style, int index) { * <code>widgetDefaultSelected</code> is not called. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the control is selected by the user, * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -681,7 +681,7 @@ void releaseWidget () { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * @@ -768,7 +768,7 @@ public void setControl (Control control) { * Sets the receiver's disabled image to the argument, which may be * null indicating that no disabled image should be displayed. * <p> - * The disbled image is displayed when the receiver is disabled. + * The disabled image is displayed when the receiver is disabled. * </p> * * @param image the disabled image to display on the receiver (may be null) diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolTip.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolTip.java index 6e7c53fe20..79da579361 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolTip.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ToolTip.java @@ -28,6 +28,9 @@ import org.eclipse.swt.events.*; * <dd>Selection</dd> * </dl> * </p><p> + * Note: Only one of the styles ICON_ERROR, ICON_INFORMATION, + * and ICON_WARNING may be specified. + * </p><p> * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> @@ -94,11 +97,15 @@ static int checkStyle (int style) { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's value changes, by sending + * be notified when the receiver is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. + * <p> + * <code>widgetSelected</code> is called when the receiver is selected. + * <code>widgetDefaultSelected</code> is not called. + * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the receiver is selected by the user * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -533,7 +540,7 @@ void releaseWidget () { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's value changes. + * be notified when the receiver is selected by the user. * * @param listener the listener which should no longer be notified * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java index 344a046091..0205aa497b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TrayItem.java @@ -106,7 +106,7 @@ public void addMenuDetectListener (MenuDetectListener listener) { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver is selected, by sending + * be notified when the receiver is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -114,7 +114,7 @@ public void addMenuDetectListener (MenuDetectListener listener) { * <code>widgetDefaultSelected</code> is called when the receiver is double-clicked * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the receiver is selected by the user * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -365,7 +365,7 @@ public void removeMenuDetectListener (MenuDetectListener listener) { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver is selected. + * be notified when the receiver is selected by the user. * * @param listener the listener which should no longer be notified * 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 1fc23de90d..a7c93877d5 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 @@ -331,18 +331,18 @@ protected void checkSubclass () { /** * Adds the listener to the collection of listeners who will - * be notified when the receiver's selection changes, by sending + * be notified when the user changes the receiver's selection, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> * When <code>widgetSelected</code> is called, the item field of the event object is valid. - * If the receiver has <code>SWT.CHECK</code> style set and the check selection changes, + * If the receiver has the <code>SWT.CHECK</code> style and the check selection changes, * the event object detail field contains the value <code>SWT.CHECK</code>. * <code>widgetDefaultSelected</code> is typically called when an item is double-clicked. * The item field of the event object is valid for default selection, but the detail field is not used. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the user changes the receiver's selection * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -2063,7 +2063,7 @@ void hookEvents () { * @return the index of the column * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the string is null</li> + * <li>ERROR_NULL_ARGUMENT - if the column is null</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2091,8 +2091,8 @@ public int indexOf (TreeColumn column) { * @return the index of the item * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li> - * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li> + * <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> @@ -2318,7 +2318,7 @@ public void removeAll () { /** * Removes the listener from the collection of listeners who will - * be notified when the receiver's selection changes. + * be notified when the user changes the receiver's selection. * * @param listener the listener which should no longer be notified * 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 523f993fcc..4f0d5b472b 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 @@ -147,7 +147,7 @@ public void addControlListener(ControlListener listener) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the control is selected by the user, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -155,7 +155,7 @@ public void addControlListener(ControlListener listener) { * <code>widgetDefaultSelected</code> is not called. * </p> * - * @param listener the listener which should be notified + * @param listener the listener which should be notified when the control is selected by the user * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the listener is null</li> @@ -467,7 +467,7 @@ public void removeControlListener (ControlListener listener) { /** * Removes the listener from the collection of listeners who will - * be notified when the control is selected. + * be notified when the control is selected by the user. * * @param listener the listener which should no longer be notified * 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 b4001462ee..ece1fb3ef8 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 @@ -878,6 +878,21 @@ public String getText (int index) { return new String (Converter.mbcsToWcs (null, buffer)); } +/** + * Returns a rectangle describing the size and location + * relative to its parent of the text at a column in the + * tree. + * + * @param index the index that specifies the column + * @return the receiver's bounding text 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.3 + */ public Rectangle getTextBounds (int index) { checkWidget (); if (!parent.checkData (this)) error (SWT.ERROR_WIDGET_DISPOSED); @@ -950,8 +965,8 @@ public Rectangle getTextBounds (int index) { * @return the index of the item * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li> - * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li> + * <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> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java index 387b6c5717..5b616828d2 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java @@ -227,7 +227,7 @@ void _addListener (int eventType, Listener listener) { * * @see Listener * @see SWT - * @see #removeListener + * @see #removeListener(int, Listener) * @see #notifyListeners */ public void addListener (int eventType, Listener listener) { @@ -403,13 +403,13 @@ void destroyWidget () { /** * Disposes of the operating system resources associated with - * the receiver and all its descendents. After this method has - * been invoked, the receiver and all descendents will answer + * the receiver and all its descendants. After this method has + * been invoked, the receiver and all descendants will answer * <code>true</code> when sent the message <code>isDisposed()</code>. * Any internal connections between the widgets in the tree will * have been removed to facilitate garbage collection. * <p> - * NOTE: This method is not called recursively on the descendents + * NOTE: This method is not called recursively on the descendants * of the receiver. This means that, widget implementers can not * detect when a widget is being disposed of by re-implementing * this method, but should instead listen for the <code>Dispose</code> @@ -943,7 +943,7 @@ boolean mnemonicMatch (int /*long*/ mnemonicHandle, char key) { * * @see SWT * @see #addListener - * @see #removeListener + * @see #removeListener(int, Listener) */ public void notifyListeners (int eventType, Event event) { checkWidget(); |