diff options
Diffstat (limited to 'bundles/org.eclipse.swt/Eclipse SWT/gtk/org')
35 files changed, 839 insertions, 233 deletions
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java index 06b52e7852..15f71c6bb0 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Color.java @@ -191,7 +191,7 @@ public int getRed() { /** * Returns an integer hash code for the receiver. Any two - * objects which return <code>true</code> when passed to + * objects that return <code>true</code> when passed to * <code>equals</code> must return the same value for this * method. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java index a7f20b00ed..8c74fd0d44 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Cursor.java @@ -417,7 +417,7 @@ public static Cursor gtk_new(Device device, int /*long*/ handle) { /** * Returns an integer hash code for the receiver. Any two - * objects which return <code>true</code> when passed to + * objects that return <code>true</code> when passed to * <code>equals</code> must return the same value for this * method. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java index 2cd7ac82f5..ca2baf871d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Device.java @@ -433,7 +433,7 @@ public FontData[] getFontList (String faceName, boolean scalable) { * specified in class <code>SWT</code>. Any value other * than one of the SWT color constants which is passed * in will result in the color black. This color should - * not be free'd because it was allocated by the system, + * not be freed because it was allocated by the system, * not the application. * * @param id the color constant @@ -472,7 +472,7 @@ public Color getSystemColor (int id) { * Returns a reasonable font for applications to use. * On some platforms, this will match the "default font" * or "system font" if such can be found. This font - * should not be free'd because it was allocated by the + * should not be freed because it was allocated by the * system, not the application. * <p> * Typically, applications which want the default look diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java index 0137471f4a..9b1d8b54df 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Font.java @@ -227,7 +227,7 @@ public static Font gtk_new(Device device, int /*long*/ handle) { /** * Returns an integer hash code for the receiver. Any two - * objects which return <code>true</code> when passed to + * objects that return <code>true</code> when passed to * <code>equals</code> must return the same value for this * method. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java index 76b22c812a..68798e380a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontData.java @@ -290,7 +290,7 @@ public int getStyle() { /** * Returns an integer hash code for the receiver. Any two - * objects which return <code>true</code> when passed to + * objects that return <code>true</code> when passed to * <code>equals</code> must return the same value for this * method. * @@ -392,7 +392,8 @@ public void setName(String name) { /** * Sets the style of the receiver to the argument which must * be a bitwise OR of one or more of the <code>SWT</code> - * constants NORMAL, BOLD and ITALIC. + * constants NORMAL, BOLD and ITALIC. All other style bits are + * ignored. * * @param style the new style for this <code>FontData</code> * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java index 96b962c8da..8abe3cf1c9 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/FontMetrics.java @@ -117,7 +117,7 @@ public static FontMetrics gtk_new(int ascent, int descent, int averageCharWidth, /** * Returns an integer hash code for the receiver. Any two - * objects which return <code>true</code> when passed to + * objects that return <code>true</code> when passed to * <code>equals</code> must return the same value for this * method. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java index e44ada99a8..8c10ea70c7 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/GC.java @@ -195,6 +195,24 @@ public void copyArea(Image image, int x, int y) { public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY) { copyArea(srcX, srcY, width, height, destX, destY, true); } +/** + * Copies a rectangular area of the receiver at the source + * position onto the receiver at the destination position. + * + * @param srcX the x coordinate in the receiver of the area to be copied + * @param srcY the y coordinate in the receiver of the area to be copied + * @param width the width of the area to copy + * @param height the height of the area to copy + * @param destX the x coordinate in the receiver of the area to copy to + * @param destY the y coordinate in the receiver of the area to copy to + * @param paint if <code>true</code> paint events will be generated for old and obscured areas + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void copyArea(int srcX, int srcY, int width, int height, int destX, int destY, boolean paint) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (width <= 0 || height <= 0) return; @@ -354,7 +372,7 @@ public void drawArc(int x, int y, int width, int height, int startAngle, int arc * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #drawRectangle + * @see #drawRectangle(int, int, int, int) */ public void drawFocus(int x, int y, int width, int height) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -713,8 +731,22 @@ public void drawOval(int x, int y, int width, int height) { OS.gdk_draw_arc(data.drawable, handle, 0, x, y, width, height, 0, 23040); } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Draws the path described by the parameter. + * + * @param path the path to draw + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Path + * + * @since 3.1 */ public void drawPath(Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1259,7 +1291,7 @@ public void fillArc(int x, int y, int width, int height, int startAngle, int arc * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #drawRectangle + * @see #drawRectangle(int, int, int, int) */ public void fillGradientRectangle(int x, int y, int width, int height, boolean vertical) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1372,8 +1404,22 @@ public void fillOval(int x, int y, int width, int height) { OS.gdk_gc_set_foreground(handle, color); } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Fills the path described by the parameter. + * + * @param path the path to fill + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Path + * + * @since 3.1 */ public void fillPath (Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1458,7 +1504,7 @@ public void fillPolygon(int[] pointArray) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #drawRectangle + * @see #drawRectangle(int, int, int, int) */ public void fillRectangle(int x, int y, int width, int height) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1508,7 +1554,7 @@ public void fillRectangle(int x, int y, int width, int height) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see #drawRectangle + * @see #drawRectangle(int, int, int, int) */ public void fillRectangle(Rectangle rect) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1648,13 +1694,45 @@ public int getAdvanceWidth(char ch) { return stringExtent(new String(new char[]{ch})).x; } +/** + * Returns <code>true</code> if receiver is using the operating system's + * advanced graphics subsystem. Otherwise, <code>false</code> is returned + * to indicate that normal graphics are in use. + * <p> + * Advanced graphics may not be installed for the operating system. In this + * case, <code>false</code> is always returned. Some operating system have + * only one graphics subsystem. If this subsystem supports advanced graphics, + * then <code>true</code> is always returned. If any graphics operation such + * as alpha, antialias, patterns, interpolation, paths, clipping or transformation + * has caused the receiver to switch from regular to advanced graphics mode, + * <code>true</code> is returned. If the receiver has been explicitly switched + * to advanced mode and this mode is supported, <code>true</code> is returned. + * </p> + * + * @return the advanced value + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setAdvanced + * @since 3.1 + */ public boolean getAdvanced() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); return data.cairo != 0; } /** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + * Returns the receiver's alpha value. + * + * @return the alpha value + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 */ public int getAlpha() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1663,7 +1741,20 @@ public int getAlpha() { } /** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + * Returns the receiver's anti-aliasing setting value, which will be + * one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or + * <code>SWT.ON</code>. Note that this controls anti-aliasing for all + * <em>non-text drawing</em> operations. + * + * @return the anti-aliasing setting + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #getTextAntialias + * + * @since 3.1 */ public int getAntialias() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1691,8 +1782,19 @@ public Color getBackground() { return Color.gtk_new(data.device, color); } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Returns the background pattern. The default value is + * <code>null</code>. + * + * @return the receiver's background pattern + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Pattern + * + * @since 3.1 */ public Pattern getBackgroundPattern() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1791,6 +1893,18 @@ public void getClipping(Region region) { } } +/** + * Returns the receiver's fill rule, which will be one of + * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>. + * + * @return the receiver's fill rule + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public int getFillRule() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); int /*long*/ cairo = data.cairo; @@ -1858,16 +1972,37 @@ public Color getForeground() { return Color.gtk_new(data.device, color); } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Returns the foreground pattern. The default value is + * <code>null</code>. + * + * @return the receiver's foreground pattern + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Pattern + * + * @since 3.1 */ public Pattern getForegroundPattern() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); return data.foregroundPattern; } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Returns the receiver's interpolation setting, which will be one of + * <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, + * <code>SWT.LOW</code> or <code>SWT.HIGH</code>. + * + * @return the receiver's interpolation setting + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 */ public int getInterpolation() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -1901,7 +2036,8 @@ public int getLineCap() { } /** - * Returns the receiver's line dash style. + * Returns the receiver's line dash style. The default value is + * <code>null</code>. * * @return the lin dash style used for drawing lines * @@ -2006,15 +2142,43 @@ public int getStyle () { } /** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + * Returns the receiver's text drawing anti-aliasing setting value, + * which will be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> or + * <code>SWT.ON</code>. Note that this controls anti-aliasing + * <em>only</em> for text drawing operations. + * + * @return the anti-aliasing setting + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #getAntialias + * + * @since 3.1 */ public int getTextAntialias() { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); return data.textAntialias; } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Sets the parameter to the transform that is currently being + * used by the receiver. + * + * @param transform the destination to copy the transform into + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the parameter is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Transform + * + * @since 3.1 */ public void getTransform(Transform transform) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2051,7 +2215,7 @@ public boolean getXORMode() { /** * Returns an integer hash code for the receiver. Any two - * objects which return <code>true</code> when passed to + * objects that return <code>true</code> when passed to * <code>equals</code> must return the same value for this * method. * @@ -2200,6 +2364,48 @@ boolean isIdentity(int /*long*/ matrix) { return a[0] == 1 && b[0] == 0 && c[0] == 0 && d[0] == 1 && tx[0] == 0 && ty[0] == 0; } +/** + * Sets the receiver to always use the operating system's advanced graphics + * subsystem for all graphics operations if the argument is <code>true</code>. + * If the argument is <code>false</code>, the advanced graphics subsystem is + * no longer used, advanced graphics state is cleared and the normal graphics + * subsystem is used from now on. + * <p> + * Normally, the advanced graphics subsystem is invoked automatically when + * any one of the alpha, antialias, patterns, interpolation, paths, clipping + * or transformation operations in the receiver is requested. When the receiver + * is switched into advanced mode, the advanced graphics subsystem performs both + * advanced and normal graphics operations. Because the two subsystems are + * different, their output may differ. Switching to advanced graphics before + * any graphics operations are performed ensures that the output is consistent. + * </p> + * <p> + * Advanced graphics may not be installed for the operating system. In this + * case, this operation does nothing. Some operating system have only one + * graphics subsystem, so switching from normal to advanced graphics does + * nothing. However, switching from advanced to normal graphics will always + * clear the advanced graphics state, even for operating systems that have + * only one graphics subsystem. + * </p> + * + * @param advanced the new advanced graphics state + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setAlpha + * @see #setAntialias + * @see #setBackgroundPattern + * @see #setClipping(Path) + * @see #setForegroundPattern + * @see #setInterpolation + * @see #setTextAntialias + * @see #setTransform + * @see #getAdvanced + * + * @since 3.1 + */ public void setAdvanced(boolean advanced) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); if (advanced && data.cairo != 0) return; @@ -2222,7 +2428,15 @@ public void setAdvanced(boolean advanced) { } /** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + * Sets the receiver's alpha value. + * + * @param alpha the alpha value + * + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 */ public void setAlpha(int alpha) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2232,7 +2446,24 @@ public void setAlpha(int alpha) { } /** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + * Sets the receiver's anti-aliasing value to the parameter, + * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> + * or <code>SWT.ON</code>. Note that this controls anti-aliasing for all + * <em>non-text drawing</em> operations. + * + * @param antialias the anti-aliasing setting + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>, + * <code>SWT.OFF</code> or <code>SWT.ON</code></li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setTextAntialias + * + * @since 3.1 */ public void setAntialias(int antialias) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2272,8 +2503,21 @@ public void setBackground(Color color) { data.backgroundPattern = null; } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Sets the background pattern. The default value is <code>null</code>. + * + * @param pattern the new background pattern + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Pattern + * + * @since 3.1 */ public void setBackgroundPattern(Pattern pattern) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2391,7 +2635,22 @@ public void setClipping(int x, int y, int width, int height) { } /** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + * Sets the area of the receiver which can be changed + * by drawing operations to the path specified + * by the argument. + * + * @param path the clipping path. + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the path has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Path + * + * @since 3.1 */ public void setClipping(Path path) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2409,9 +2668,11 @@ public void setClipping(Path path) { /** * Sets the area of the receiver which can be changed * by drawing operations to the rectangular area specified - * by the argument. + * by the argument. Specifying <code>null</code> for the + * rectangle reverts the receiver's clipping area to its + * original value. * - * @param rect the clipping rectangle + * @param rect the clipping rectangle or <code>null</code> * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> @@ -2428,9 +2689,11 @@ public void setClipping(Rectangle rect) { /** * Sets the area of the receiver which can be changed * by drawing operations to the region specified - * by the argument. + * by the argument. Specifying <code>null</code> for the + * region reverts the receiver's clipping area to its + * original value. * - * @param region the clipping region. + * @param region the clipping region or <code>null</code> * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the region has been disposed</li> @@ -2473,6 +2736,22 @@ public void setFont(Font font) { } } +/** + * Sets the receiver's fill rule to the parameter, which must be one of + * <code>SWT.FILL_EVEN_ODD</code> or <code>SWT.FILL_WINDING</code>. + * + * @param rule the new fill rule + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.FILL_EVEN_ODD</code> + * or <code>SWT.FILL_WINDING</code></li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 + */ public void setFillRule(int rule) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); int cairo_mode = Cairo.CAIRO_FILL_RULE_EVEN_ODD; @@ -2519,8 +2798,21 @@ public void setForeground(Color color) { data.foregroundPattern = null; } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Sets the foreground pattern. The default value is <code>null</code>. + * + * @param pattern the new foreground pattern + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Pattern + * + * @since 3.1 */ public void setForegroundPattern(Pattern pattern) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2542,8 +2834,22 @@ public void setForegroundPattern(Pattern pattern) { data.foregroundPattern = pattern; } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Sets the receiver's interpolation setting to the parameter, which + * must be one of <code>SWT.DEFAULT</code>, <code>SWT.NONE</code>, + * <code>SWT.LOW</code> or <code>SWT.HIGH</code>. + * + * @param interpolation the new interpolation setting + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the rule is not one of <code>SWT.DEFAULT</code>, + * <code>SWT.NONE</code>, <code>SWT.LOW</code> or <code>SWT.HIGH</code> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @since 3.1 */ public void setInterpolation(int interpolation) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2607,7 +2913,10 @@ public void setLineCap(int cap) { } /** - * Sets the receiver's line dash style to the argument. + * Sets the receiver's line dash style to the argument. The default + * value is <code>null</code>. If the argument is not <code>null</code>, + * the receiver's line style is set to <code>SWT.LINE_CUSTOM</code>, otherwise + * it is set to <code>SWT.LINE_SOLID</code>. * * @param dashes the dash style to be used for drawing lines * @@ -2771,6 +3080,12 @@ public void setLineStyle(int lineStyle) { * for all of the figure drawing operations (that is, * <code>drawLine</code>, <code>drawRectangle</code>, * <code>drawPolyline</code>, and so forth. + * <p> + * Note that line width of zero is used as a hint to + * indicate that the fastest possible line drawing + * algorithms should be used. This means that the + * output may be different from line width one. + * </p> * * @param lineWidth the width of a line * @@ -2840,7 +3155,24 @@ void setString(String string, int flags) { } /** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE + * Sets the receiver's text anti-aliasing value to the parameter, + * which must be one of <code>SWT.DEFAULT</code>, <code>SWT.OFF</code> + * or <code>SWT.ON</code>. Note that this controls anti-aliasing only + * for all <em>text drawing</em> operations. + * + * @param antialias the anti-aliasing setting + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the parameter is not one of <code>SWT.DEFAULT</code>, + * <code>SWT.OFF</code> or <code>SWT.ON</code></li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see #setAntialias + * + * @since 3.1 */ public void setTextAntialias(int antialias) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2855,8 +3187,23 @@ public void setTextAntialias(int antialias) { data.textAntialias = antialias; } -/** - * WARNING API STILL UNDER CONSTRUCTION AND SUBJECT TO CHANGE +/** + * Sets the transform that is currently being used by the receiver. If + * the argument is <code>null</code>, the current transform is set to + * the identity transform. + * + * @param transform the transform to set + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> + * </ul> + * + * @see Transform + * + * @since 3.1 */ public void setTransform(Transform transform) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -2923,12 +3270,19 @@ public void setTransform(Transform transform) { * and the destination, and if the argument is <code>false</code>, * puts the receiver in a drawing mode where the destination color * is replaced with the source color value. + * <p> + * Note that this mode in fundamentally unsupportable on certain + * platforms, notably Carbon (Mac OS X). Clients that want their + * code to run on all platforms need to avoid this method. + * </p> * * @param xor if <code>true</code>, then <em>xor</em> mode is used, otherwise <em>source copy</em> mode is used * * @exception SWTException <ul> * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @deprecated this functionality is not supported on some platforms */ public void setXORMode(boolean xor) { if (handle == 0) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java index 5d7d965818..775ba8b1e1 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java @@ -54,7 +54,7 @@ import java.io.*; * loading process should use the support provided in class * <code>ImageLoader</code>. * </p><p> - * Application code must explicitely invoke the <code>Image.dispose()</code> + * Application code must explicitly invoke the <code>Image.dispose()</code> * method to release the operating system resources managed by each instance * when those instances are no longer required. * </p> @@ -451,7 +451,20 @@ public Image(Device device, ImageData source, ImageData mask) { * This constructor may be used to load a resource as follows: * </p> * <pre> - * new Image(device, clazz.getResourceAsStream("file.gif")); + * static Image loadImage (Display display, Class clazz, String string) { + * InputStream stream = clazz.getResourceAsStream (string); + * if (stream == null) return null; + * Image image = null; + * try { + * image = new Image (display, stream); + * } catch (SWTException ex) { + * } finally { + * try { + * stream.close (); + * } catch (IOException ex) {} + * } + * return image; + * } * </pre> * * @param device the device on which to create the image @@ -806,7 +819,7 @@ public static Image gtk_new(Device device, int type, int /*long*/ pixmap, int /* /** * Returns an integer hash code for the receiver. Any two - * objects which return <code>true</code> when passed to + * objects that return <code>true</code> when passed to * <code>equals</code> must return the same value for this * method. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java index 26006135b8..935ee2098d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Region.java @@ -135,7 +135,6 @@ public void add(Rectangle rect) { * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> * </ul> * @exception SWTException <ul> @@ -272,7 +271,7 @@ public static Region gtk_new(Device device, int /*long*/ handle) { /** * Returns an integer hash code for the receiver. Any two - * objects which return <code>true</code> when passed to + * objects that return <code>true</code> when passed to * <code>equals</code> must return the same value for this * method. * @@ -376,7 +375,7 @@ public void intersect(Region region) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see Rectangle#intersects + * @see Rectangle#intersects(Rectangle) */ public boolean intersects (int x, int y, int width, int height) { if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED); @@ -402,7 +401,7 @@ public boolean intersects (int x, int y, int width, int height) { * <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li> * </ul> * - * @see Rectangle#intersects + * @see Rectangle#intersects(Rectangle) */ public boolean intersects(Rectangle rect) { if (rect == null) SWT.error(SWT.ERROR_NULL_ARGUMENT); @@ -494,7 +493,6 @@ public void subtract(Rectangle rect) { * @param height the height coordinate of the rectangle * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the argument is null</li> * <li>ERROR_INVALID_ARGUMENT - if the rectangle's width or height is negative</li> * </ul> * @exception SWTException <ul> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java index ab8460f110..cd10658ef7 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Button.java @@ -614,9 +614,9 @@ void setForegroundColor (GdkColor color) { /** * Sets the receiver's image to the argument, which may be - * null indicating that no image should be displayed. + * <code>null</code> indicating that no image should be displayed. * - * @param image the image to display on the receiver (may be null) + * @param image the image to display on the receiver (may be <code>null</code>) * * @exception IllegalArgumentException <ul> * <li>ERROR_INVALID_ARGUMENT - if the image has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java index b6971efa03..b15398c1f8 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Canvas.java @@ -60,7 +60,6 @@ Canvas () {} * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> - * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> * </ul> * * @see SWT diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java index 377047cfc9..144a51c470 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Combo.java @@ -662,8 +662,8 @@ public int getItemHeight () { } /** - * Returns an array of <code>String</code>s which are the items - * in the receiver's list. + * Returns a (possibly empty) array of <code>String</code>s which are + * the items in the receiver's list. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of items, so modifying the array will @@ -702,11 +702,16 @@ public int getOrientation () { } /** - * Returns a <code>Point</code> whose x coordinate is the start - * of the selection in the receiver's text field, and whose y - * coordinate is the end of the selection. The returned values - * are zero-relative. An "empty" selection as indicated by - * the the x and y coordinates having the same value. + * Returns a <code>Point</code> whose x coordinate is the + * character position representing the start of the selection + * in the receiver's text field, and whose y coordinate is the + * character position representing the end of the selection. + * An "empty" selection is indicated by the x and y coordinates + * having the same value. + * <p> + * Indexing is zero based. The range of a selection is from + * 0..N where N is the number of characters in the widget. + * </p> * * @return a point representing the selection start and end * @@ -754,7 +759,8 @@ public int getSelectionIndex () { /** * Returns a string containing a copy of the contents of the - * receiver's text field. + * receiver's text field, or an empty string if there are no + * contents. * * @return the receiver's text * @@ -808,6 +814,8 @@ public int getTextHeight () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #LIMIT */ public int getTextLimit () { checkWidget(); @@ -1338,8 +1346,8 @@ void setForegroundColor (GdkColor color) { /** * Sets the text of the item in the receiver's list at the given * zero-relative index to the string argument. This is equivalent - * to <code>remove</code>'ing the old item at the index, and then - * <code>add</code>'ing the new item at that index. + * to removing the old item at the index, and then adding the new + * item at that index. * * @param index the index for the item * @param string the new text for the item @@ -1532,7 +1540,11 @@ public void setText (String string) { /** * Sets the maximum number of characters that the receiver's * text field is capable of holding to be the argument. - * + * <p> + * To reset this value to the default, use <code>setTextLimit(Combo.LIMIT)</code>. + * Specifying a limit value larger than <code>Combo.LIMIT</code> sets the + * receiver's limit to <code>Combo.LIMIT</code>. + * </p> * @param limit new text limit * * @exception IllegalArgumentException <ul> @@ -1542,6 +1554,8 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #LIMIT */ public void setTextLimit (int limit) { checkWidget(); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java index c2b15199b4..5a13446cbc 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Composite.java @@ -20,7 +20,7 @@ import org.eclipse.swt.graphics.*; * of containing other controls. * <dl> * <dt><b>Styles:</b></dt> - * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED</dd> + * <dd>NO_BACKGROUND, NO_FOCUS, NO_MERGE_PAINTS, NO_REDRAW_RESIZE, NO_RADIO_GROUP, EMBEDDED, DOUBLE_BUFFERED</dd> * <dt><b>Events:</b></dt> * <dd>(none)</dd> * </dl> @@ -386,7 +386,7 @@ boolean forceFocus (int /*long*/ focusHandle) { } /** - * Returns an array containing the receiver's children. + * Returns a (possibly empty) array containing the receiver's children. * Children are returned in the order that they are drawn. * <p> * Note: This is not the actual structure used by the receiver @@ -474,7 +474,7 @@ public boolean getLayoutDeferred () { } /** - * Gets the last specified tabbing order for the control. + * Gets the (possibly empty) tabbing order for the control. * * @return tabList the ordered list of controls representing the tab order * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java index 68a7352af0..490a58a819 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java @@ -270,7 +270,7 @@ int /*long*/ paintWindow () { * @see #getBorderWidth * @see #getBounds * @see #getSize - * @see #pack + * @see #pack(boolean) * @see "computeTrim, getClientArea for controls that implement them" */ public Point computeSize (int wHint, int hHint) { @@ -355,7 +355,7 @@ void createWidget (int index) { * @see #getBorderWidth * @see #getBounds * @see #getSize - * @see #pack + * @see #pack(boolean) * @see "computeTrim, getClientArea for controls that implement them" */ public Point computeSize (int wHint, int hHint, boolean changed) { @@ -821,7 +821,7 @@ public void moveBelow (Control control) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #computeSize + * @see #computeSize(int, int, boolean) */ public void pack () { pack (true); @@ -846,7 +846,7 @@ public void pack () { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #computeSize + * @see #computeSize(int, int, boolean) */ public void pack (boolean changed) { setSize (computeSize (SWT.DEFAULT, SWT.DEFAULT, changed)); @@ -2846,7 +2846,8 @@ void setOrientation () { * @return <code>true</code> if the parent is changed and <code>false</code> otherwise. * * @exception IllegalArgumentException <ul> - * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> + * <li>ERROR_INVALID_ARGUMENT - if the argument has been disposed</li> + * <li>ERROR_NULL_ARGUMENT - if the parent is <code>null</code></li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -2903,7 +2904,7 @@ boolean setRadioSelection (boolean value) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #redraw + * @see #redraw(int, int, int, int, boolean) * @see #update */ public void setRedraw (boolean redraw) { @@ -3363,7 +3364,7 @@ boolean traverseMnemonic (char key) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #redraw + * @see #redraw(int, int, int, int, boolean) * @see PaintListener * @see SWT#Paint */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java index 49140c1c4b..735212c207 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Decorations.java @@ -326,9 +326,9 @@ public Image getImage () { * marked as iconified, and may also be displayed somewhere * in the trim when the instance is in normal or maximized * states. Depending where the icon is displayed, the platform - * chooses the icon with the "best" size. It is expected that - * the array will contain the same icon rendered at different - * resolutions. + * chooses the icon with the "best" attributes. It is expected + * that the array will contain the same icon rendered at different + * sizes, with different depth and transparency attributes. * * <p> * Note: This method will return an empty array if called before @@ -501,7 +501,11 @@ boolean restoreFocus () { * <em>saved default button</em>). If no default button had * previously been set, or the saved default button was * disposed, the receiver's default button will be set to - * null. + * null. + * <p> + * The default button is the button that is selected when + * the receiver is active and the user presses ENTER. + * </p> * * @param button the new default button * @@ -554,8 +558,9 @@ public void setImage (Image image) { * and may also be displayed somewhere in the trim when the * instance is in normal or maximized states. Depending where * the icon is displayed, the platform chooses the icon with - * the "best" size. It is expected that the array will contain - * the same icon rendered at different resolutions. + * the "best" attributes. It is expected that the array will + * contain the same icon rendered at different sizes, with + * different depth and transparency attributes. * * @param images the new image array * @@ -588,7 +593,7 @@ public void setImages (Image [] images) { * causes the receiver to switch back to either the minimized * or normal states. * <p> - * Note: The result of intermixing calls to<code>setMaximized(true)</code> + * Note: The result of intermixing calls to <code>setMaximized(true)</code> * and <code>setMinimized(true)</code> will vary by platform. Typically, * the behavior will match the platform user's expectations, but not * always. This should be avoided if possible. @@ -641,7 +646,7 @@ public void setMenuBar (Menu menu) { * causes the receiver to switch back to either the maximized * or normal states. * <p> - * Note: The result of intermixing calls to<code>setMaximized(true)</code> + * Note: The result of intermixing calls to <code>setMaximized(true)</code> * and <code>setMinimized(true)</code> will vary by platform. Typically, * the behavior will match the platform user's expectations, but not * always. This should be avoided if possible. @@ -669,7 +674,7 @@ void setSavedFocus (Control control) { /** * Sets the receiver's text, which is the string that the * window manager will typically display as the receiver's - * <em>title</em>, to the argument, which may not be null. + * <em>title</em>, to the argument, which must not be null. * * @param string the new text * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java index 3a2854758b..f2ba3bc167 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/DirectoryDialog.java @@ -82,6 +82,8 @@ public DirectoryDialog (Shell parent, int style) { * the directories it shows. * * @return the filter path + * + * @see #setFilterPath */ public String getFilterPath () { return filterPath; @@ -258,9 +260,15 @@ String openClassicDialog () { return answer; } /** - * Sets the path which the dialog will use to filter - * the directories it shows to the argument, which may be - * null. + * Sets the path that the dialog will use to filter + * the directories it shows to the argument, which may + * be null. If the string is null, then the operating + * system's default filter path will be used. + * <p> + * Note that the path string is platform dependent. + * For convenience, either '/' or '\' can be used + * as a path separator. + * </p> * * @param string the filter path */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java index 7b0f169d06..8c04cde11a 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Display.java @@ -407,7 +407,7 @@ static void setDevice (Device device) { * </p> * * @exception SWTException <ul> - * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if called from a thread that already created an existing display</li> * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> * </ul> * @@ -420,6 +420,11 @@ public Display () { this (null); } +/** + * Constructs a new instance of this class using the parameter. + * + * @param data the device data + */ public Display (DeviceData data) { super (data); } @@ -574,9 +579,16 @@ void addWidget (int /*long*/ handle, Widget widget) { * be invoked by the user-interface thread at the next * reasonable opportunity. The caller of this method continues * to run in parallel, and is not notified when the - * runnable has completed. + * runnable has completed. Specifying <code>null</code> as the + * runnable simply wakes the user-interface thread when run. + * <p> + * Note that at the time the runnable is invoked, widgets + * that have the receiver as their display may have been + * disposed. Therefore, it is necessary to check for this + * case inside the runnable before accessing the widget. + * </p> * - * @param runnable code to run on the user-interface thread. + * @param runnable code to run on the user-interface thread or <code>null</code> * * @exception SWTException <ul> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> @@ -911,7 +923,7 @@ synchronized void deregister () { * <p> * This method is called after <code>release</code>. * </p> - * @see #dispose + * @see Device#dispose * @see #release */ protected void destroy () { @@ -926,7 +938,9 @@ void destroyDisplay () { /** * Returns the display which the given thread is the * user-interface thread for, or null if the given thread - * is not a user-interface thread for any display. + * is not a user-interface thread for any display. Specifying + * <code>null</code> as the thread will return <code>null</code> + * for the display. * * @param thread the user-interface thread * @return the display for the given thread @@ -944,7 +958,8 @@ public static synchronized Display findDisplay (Thread thread) { /** * Causes the <code>run()</code> method of the runnable to * be invoked by the user-interface thread just before the - * receiver is disposed. + * receiver is disposed. Specifying a <code>null</code> runnable + * is ignored. * * @param runnable code to run at dispose time. * @@ -1314,7 +1329,7 @@ public Point [] getCursorSizes () { * Applications may have associated arbitrary objects with the * receiver in this fashion. If the objects stored in the * properties need to be notified when the display is disposed - * of, it is the application's responsibility provide a + * of, it is the application's responsibility to provide a * <code>disposeExec()</code> handler which does so. * </p> * @@ -1354,7 +1369,7 @@ public Object getData (String key) { * Applications may put arbitrary objects in this field. If * the object stored in the display specific data needs to * be notified when the display is disposed of, it is the - * application's responsibility provide a + * application's responsibility to provide a * <code>disposeExec()</code> handler which does so. * </p> * @@ -1518,9 +1533,8 @@ public int getDepth () { } /** - * Returns the maximum allowed depth of icons on this display. - * On some platforms, this may be different than the actual - * depth of the display. + * Returns the maximum allowed depth of icons on this display, in bits per pixel. + * On some platforms, this may be different than the actual depth of the display. * * @return the maximum icon depth * @@ -1528,6 +1542,8 @@ public int getDepth () { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * <li>ERROR_DEVICE_DISPOSED - if the receiver has been disposed</li> * </ul> + * + * @see Device#getDepth */ public int getIconDepth () { checkDevice (); @@ -1624,8 +1640,8 @@ public Monitor getPrimaryMonitor () { } /** - * Returns an array containing all shells which have not been - * disposed and have the receiver as their display. + * Returns a (possibly empty) array containing all shells which have + * not been disposed and have the receiver as their display. * * @return the receiver's shells * @@ -2593,7 +2609,7 @@ synchronized void register () { * </p> * This method is called before <code>destroy</code>. * - * @see #dispose + * @see Device#dispose * @see #destroy */ protected void release () { @@ -2884,9 +2900,10 @@ boolean runPopups () { /** * On platforms which support it, sets the application name * to be the argument. On Motif, for example, this can be used - * to set the name used for resource lookup. + * to set the name used for resource lookup. Specifying + * <code>null</code> for the name clears it. * - * @param name the new app name + * @param name the new app name or <code>null</code> */ public static void setAppName (String name) { APP_NAME = name; @@ -3192,6 +3209,12 @@ public boolean sleep () { * be invoked by the user-interface thread after the specified * number of milliseconds have elapsed. If milliseconds is less * than zero, the runnable is not executed. + * <p> + * Note that at the time the runnable is invoked, widgets + * that have the receiver as their display may have been + * disposed. Therefore, it is necessary to check for this + * case inside the runnable before accessing the widget. + * </p> * * @param milliseconds the delay before running the runnable * @param runnable code to run on the user-interface thread @@ -3320,9 +3343,16 @@ int /*long*/ shellMapProc (int /*long*/ handle, int /*long*/ arg0, int /*long*/ * Causes the <code>run()</code> method of the runnable to * be invoked by the user-interface thread at the next * reasonable opportunity. The thread which calls this method - * is suspended until the runnable completes. - * - * @param runnable code to run on the user-interface thread. + * is suspended until the runnable completes. Specifying <code>null</code> + * as the runnable simply wakes the user-interface thread. + * <p> + * Note that at the time the runnable is invoked, widgets + * that have the receiver as their display may have been + * disposed. Therefore, it is necessary to check for this + * case inside the runnable before accessing the widget. + * </p> + * + * @param runnable code to run on the user-interface thread or <code>null</code> * * @exception SWTException <ul> * <li>ERROR_FAILED_EXEC - if an exception occured when executing the runnable</li> @@ -3368,7 +3398,7 @@ public void update () { } /** - * If the receiver's user-interface thread was <code>sleep</code>'ing, + * If the receiver's user-interface thread was <code>sleep</code>ing, * causes it to be awakened and start running again. Note that this * method may be called from any thread. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java index 18c725656c..95404d5a44 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/FileDialog.java @@ -25,6 +25,8 @@ import org.eclipse.swt.internal.gtk.*; * <dd>(none)</dd> * </dl> * <p> + * Note: Only one of the styles SAVE and OPEN may be specified. + * </p><p> * IMPORTANT: This class is intended to be subclassed <em>only</em> * within the SWT implementation. * </p> @@ -233,7 +235,8 @@ String computeResultClassicDialog () { } /** * Returns the path of the first file that was - * selected in the dialog relative to the filter path + * selected in the dialog relative to the filter path, or an + * empty string if no such file has been selected. * * @return the relative path of the file */ @@ -241,8 +244,8 @@ public String getFileName () { return fileName; } /** - * Returns the paths of all files that were selected - * in the dialog relative to the filter path. + * Returns a (possibly empty) array with the paths of all files + * that were selected in the dialog relative to the filter path. * * @return the relative paths of the files */ @@ -259,18 +262,18 @@ public String [] getFilterExtensions () { return filterExtensions; } /** - * Returns the file names which the dialog will - * use to filter the files it shows. + * Returns the names that describe the filter extensions + * which the dialog will use to filter the files it shows. * - * @return the file name filter + * @return the list of filter names */ public String [] getFilterNames () { return filterNames; } /** - * Returns the directory path that the dialog will use. - * File names in this path will appear in the dialog, - * filtered according to the filter extensions. + * Returns the directory path that the dialog will use, or an empty + * string if this is not set. File names in this path will appear + * in the dialog, filtered according to the filter extensions. * * @return the directory path string * @@ -467,6 +470,11 @@ public void setFileName (String string) { * Set the file extensions which the dialog will * use to filter the files it shows to the argument, * which may be null. + * <p> + * The strings are platform specific. For example, on + * Windows, an extension filter string is typically of + * the form "*.extension", where "*.*" matches all files. + * </p> * * @param extensions the file extension filter */ @@ -474,11 +482,11 @@ public void setFilterExtensions (String [] extensions) { filterExtensions = extensions; } /** - * Sets the file names which the dialog will - * use to filter the files it shows to the argument, - * which may be null. + * Sets the the names that describe the filter extensions + * which the dialog will use to filter the files it shows + * to the argument, which may be null. * - * @param names the file name filter + * @param names the list of filter names */ public void setFilterNames (String [] names) { filterNames = names; @@ -487,7 +495,14 @@ public void setFilterNames (String [] names) { * Sets the directory path that the dialog will use * to the argument, which may be null. File names in this * path will appear in the dialog, filtered according - * to the filter extensions. + * to the filter extensions. If the string is null, + * then the operating system's default filter path + * will be used. + * <p> + * Note that the path string is platform dependent. + * For convenience, either '/' or '\' can be used + * as a path separator. + * </p> * * @param string the directory path * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java index 6c53c6bfbd..1f07d8bf5f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Link.java @@ -23,6 +23,7 @@ import org.eclipse.swt.accessibility.*; * <p> * <dl> * <dt><b>Styles:</b></dt> + * <dd>(none)</dd> * <dt><b>Events:</b></dt> * <dd>Selection</dd> * </dl> @@ -652,7 +653,7 @@ void setFontDescription (int /*long*/ font) { * is delimited by an anchor tag, <A> and </A>. Within an * anchor, a single HREF attribute is supported. When a hyperlink is * selected, the text field of the selection event contains either the - * text of hyperlink or the value of the HREF, if one was specified. + * text of the hyperlink or the value of its HREF, if one was specified. * In the rare case of identical hyperlinks within the same string, the * HREF tag can be used to distinguish between them. The string may * include the mnemonic character and line delimiters. diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java index 910f9625e5..486567d45c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/List.java @@ -19,7 +19,7 @@ import org.eclipse.swt.events.*; /** * Instances of this class represent a selectable user interface - * object that displays a list of strings and issues notificiation + * object that displays a list of strings and issues notification * when a string selected. A list may be single or multi select. * <p> * <dl> @@ -420,7 +420,7 @@ public int getItemCount () { /** * Returns the height of the area which would be used to - * display <em>one</em> of the items in the tree. + * display <em>one</em> of the items in the list. * * @return the height of one item * @@ -449,8 +449,8 @@ public int getItemHeight () { } /** - * Returns an array of <code>String</code>s which are the items - * in the receiver. + * Returns a (possibly empty) array of <code>String</code>s which + * are the items in the receiver. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of items, so modifying the array will @@ -487,8 +487,8 @@ public String [] getItems () { /** * Returns an array of <code>String</code>s that are currently - * selected in the receiver. An empty array indicates that no - * items are selected. + * selected in the receiver. The order of the items is unspecified. + * An empty array indicates that no items are selected. * <p> * Note: This is not the actual structure used by the receiver * to maintain its selection, so modifying the array will @@ -534,7 +534,7 @@ public int getSelectionCount () { * Returns the zero-relative index of the item which is currently * selected in the receiver, or -1 if no item is selected. * - * @return the index of the selected item + * @return the index of the selected item or -1 * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -554,7 +554,8 @@ public int getSelectionIndex () { /** * Returns the zero-relative indices of the items which are currently - * selected in the receiver. The array is empty if no items are selected. + * selected in the receiver. The order of the indices is unspecified. + * The array is empty if no items are selected. * <p> * Note: This is not the actual structure used by the receiver * to maintain its selection, so modifying the array will @@ -1224,7 +1225,7 @@ public void setItems (String [] items) { /** * Selects the item at the given zero-relative index in the receiver. * If the item at the index was already selected, it remains selected. - * The current selected is first cleared, then the new items are selected. + * The current selection is first cleared, then the new item is selected. * Indices that are out of range are ignored. * * @param index the index of the item to select diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java index 6d897bf8ab..626c4631d5 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Menu.java @@ -344,7 +344,7 @@ public MenuItem getDefaultItem () { /** * Returns <code>true</code> if the receiver is enabled, and - * <code>false</code> otherwise. A disabled control is typically + * <code>false</code> otherwise. A disabled menu is typically * not selectable from the user interface and draws with an * inactive or "grayed" look. * @@ -413,8 +413,8 @@ public int getItemCount () { } /** - * Returns an array of <code>MenuItem</code>s which are the items - * in the receiver. + * Returns a (possibly empty) array of <code>MenuItem</code>s which + * are the items in the receiver. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of items, so modifying the array will @@ -622,7 +622,7 @@ public int indexOf (MenuItem item) { /** * Returns <code>true</code> if the receiver is enabled and all * of the receiver's ancestors are enabled, and <code>false</code> - * otherwise. A disabled control is typically not selectable from the + * otherwise. A disabled menu is typically not selectable from the * user interface and draws with an inactive or "grayed" look. * * @return the receiver's enabled state @@ -808,7 +808,7 @@ public void setDefaultItem (MenuItem item) { /** * Enables the receiver if the argument is <code>true</code>, - * and disables it otherwise. A disabled control is typically + * and disables it otherwise. A disabled menu is typically * not selectable from the user interface and draws with an * inactive or "grayed" look. * @@ -829,11 +829,15 @@ public void setEnabled (boolean enabled) { } /** - * Sets the receiver's location to the point specified by - * the arguments which are relative to the display. + * Sets the location of the receiver, which must be a popup, + * to the point specified by the arguments which are relative + * to the display. * <p> - * Note: This is different from most widgets where the + * Note that this is different from most widgets where the * location of the widget is relative to the parent. + * </p><p> + * Note that the platform window manager ultimately has control + * over the location of popup menus. * </p> * * @param x the new x coordinate for the receiver @@ -853,11 +857,15 @@ public void setLocation (int x, int y) { } /** - * Sets the receiver's location to the point specified by - * the arguments which are relative to the display. + * Sets the location of the receiver, which must be a popup, + * to the point specified by the argument which is relative + * to the display. * <p> - * Note: This is different from most widgets where the + * Note that this is different from most widgets where the * location of the widget is relative to the parent. + * </p><p> + * Note that the platform window manager ultimately has control + * over the location of popup menus. * </p> * * @param location the new location for the receiver diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java index dd0de648d3..356e3149c4 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MenuItem.java @@ -186,7 +186,7 @@ public void addHelpListener (HelpListener listener) { /** * Adds the listener to the collection of listeners who will - * be notified when the control is selected, by sending + * be notified when the menu item is selected, by sending * it one of the messages defined in the <code>SelectionListener</code> * interface. * <p> @@ -277,11 +277,13 @@ void fixMenus (Decorations newParent) { } /** - * Return the widget accelerator. An accelerator is the bit-wise + * Returns the widget accelerator. An accelerator is the bit-wise * OR of zero or more modifier masks and a key. Examples: * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>. + * The default value is zero, indicating that the menu item does + * not have an accelerator. * - * @return the accelerator + * @return the accelerator or 0 * * </ul> * @exception SWTException <ul> @@ -318,7 +320,7 @@ int /*long*/ getAccelGroup () { /** * Returns <code>true</code> if the receiver is enabled, and - * <code>false</code> otherwise. A disabled control is typically + * <code>false</code> otherwise. A disabled menu item is typically * not selectable from the user interface and draws with an * inactive or "grayed" look. * @@ -460,7 +462,7 @@ void hookEvents () { /** * Returns <code>true</code> if the receiver is enabled and all * of the receiver's ancestors are enabled, and <code>false</code> - * otherwise. A disabled control is typically not selectable from the + * otherwise. A disabled menu item is typically not selectable from the * user interface and draws with an inactive or "grayed" look. * * @return the receiver's enabled state @@ -593,6 +595,8 @@ void selectRadio () { * OR of zero or more modifier masks and a key. Examples: * <code>SWT.MOD1 | SWT.MOD2 | 'T', SWT.MOD3 | SWT.F2</code>. * <code>SWT.CONTROL | SWT.SHIFT | 'T', SWT.ALT | SWT.F2</code>. + * The default value is zero, indicating that the menu item does + * not have an accelerator. * * @param accelerator an integer that is the bit-wise OR of masks and a key * @@ -613,7 +617,7 @@ public void setAccelerator (int accelerator) { /** * Enables the receiver if the argument is <code>true</code>, - * and disables it otherwise. A disabled control is typically + * and disables it otherwise. A disabled menu item is typically * not selectable from the user interface and draws with an * inactive or "grayed" look. * @@ -636,8 +640,9 @@ public void setEnabled (boolean enabled) { /** * Sets the image the receiver will display to the argument. * <p> - * Note: This feature is not available on all window systems (for example, Window NT), - * in which case, calling this method will silently do nothing. + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept (for example, Windows NT). + * </p> * * @param image the image to display * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java index f0396de6c2..90c4f5660b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/MessageBox.java @@ -85,9 +85,9 @@ public MessageBox (Shell parent, int style) { } /** - * Returns the dialog's message, which is a description of - * the purpose for which it was opened. This message will be - * visible on the dialog while it is open. + * Returns the dialog's message, or an empty string if it does not have one. + * The message is a description of the purpose for which the dialog was opened. + * This message will be visible in the dialog while it is open. * * @return the message */ diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java index 47f00b6def..0a460894c4 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ProgressBar.java @@ -120,7 +120,7 @@ public int getMinimum () { } /** - * Returns the single <em>selection</em> that is the receiver's position. + * Returns the single 'selection' that is the receiver's position. * * @return the selection * @@ -196,7 +196,7 @@ public void setMinimum (int value) { } /** - * Sets the single <em>selection</em> that is the receiver's + * Sets the single 'selection' that is the receiver's * position to the argument which must be greater than or equal * to zero. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java index c26b47ef8f..aa678750b2 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Scale.java @@ -213,7 +213,7 @@ public int getPageIncrement () { } /** - * Returns the <em>selection</em>, which is the receiver's position. + * Returns the 'selection', which is the receiver's position. * * @return the selection * @@ -348,9 +348,8 @@ public void setPageIncrement (int value) { } /** - * Sets the <em>selection</em>, which is the receiver's - * value, to the argument which must be greater than or equal - * to zero. + * Sets the 'selection', which is the receiver's value, + * to the argument which must be greater than or equal to zero. * * @param value the new selection (must be zero or greater) * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java index 65ca2a529c..7c31f5b3e9 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/ScrollBar.java @@ -21,7 +21,7 @@ import org.eclipse.swt.events.*; * objects that represent a range of positive, numeric values. * <p> * At any given moment, a given scroll bar will have a - * single <em>selection</em> that is considered to be its + * single 'selection' that is considered to be its * value, which is constrained to be within the range of * values the scroll bar represents (that is, between its * <em>minimum</em> and <em>maximum</em> values). @@ -102,6 +102,7 @@ ScrollBar (Scrollable parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: + * <code>SWT.NONE</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. @@ -237,7 +238,7 @@ public int getPageIncrement () { } /** - * Returns the receiver's parent, which must be scrollable. + * Returns the receiver's parent, which must be a Scrollable. * * @return the receiver's parent * @@ -252,7 +253,7 @@ public Scrollable getParent () { } /** - * Returns the single <em>selection</em> that is the receiver's value. + * Returns the single 'selection' that is the receiver's value. * * @return the selection * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java index b97a5397a2..d47f1d9aea 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Shell.java @@ -67,7 +67,7 @@ import org.eclipse.swt.events.*; * it would be upgraded to <code>APPLICATION_MODAL</code>. * <dl> * <dt><b>Styles:</b></dt> - * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE</dd> + * <dd>BORDER, CLOSE, MIN, MAX, NO_TRIM, RESIZE, TITLE, ON_TOP, TOOL</dd> * <dd>APPLICATION_MODAL, MODELESS, PRIMARY_MODAL, SYSTEM_MODAL</dd> * <dt><b>Events:</b></dt> * <dd>Activate, Close, Deactivate, Deiconify, Iconify</dd> @@ -262,7 +262,7 @@ Shell (Display display, Shell parent, int style, int /*long*/ handle) { * @param parent a shell which will be the parent of the new instance * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -296,6 +296,9 @@ public Shell (Shell parent) { * @param parent a shell which will be the parent of the new instance * @param style the style of control to construct * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li> + * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> * <li>ERROR_INVALID_SUBCLASS - if this class is not an allowed subclass</li> @@ -310,6 +313,8 @@ public Shell (Shell parent) { * @see SWT#NO_TRIM * @see SWT#SHELL_TRIM * @see SWT#DIALOG_TRIM + * @see SWT#ON_TOP + * @see SWT#TOOL * @see SWT#MODELESS * @see SWT#PRIMARY_MODAL * @see SWT#APPLICATION_MODAL @@ -1262,7 +1267,7 @@ public void setMinimized (boolean minimized) { } /** - * Sets the receiver's minimum size to the point specified by the arguments. + * Sets the receiver's minimum size to the size specified by the arguments. * If the new minimum size is larger than the current size of the receiver, * the receiver is resized to the new minimum size. * @@ -1285,7 +1290,7 @@ public void setMinimumSize (int width, int height) { } /** - * Sets the receiver's minimum size to the point specified by the argument. + * Sets the receiver's minimum size to the size specified by the argument. * If the new minimum size is larger than the current size of the receiver, * the receiver is resized to the new minimum size. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java index 83632cda91..4c4dd9a13c 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Slider.java @@ -21,7 +21,7 @@ import org.eclipse.swt.events.*; * objects that represent a range of positive, numeric values. * <p> * At any given moment, a given slider will have a - * single <em>selection</em> that is considered to be its + * single 'selection' that is considered to be its * value, which is constrained to be within the range of * values the slider represents (that is, between its * <em>minimum</em> and <em>maximum</em> values). @@ -106,7 +106,7 @@ public Slider (Composite parent, int style) { * interface. * <p> * When <code>widgetSelected</code> is called, the event object detail field contains one of the following values: - * <code>0</code> - for the end of a drag. + * <code>SWT.NONE</code> - for the end of a drag. * <code>SWT.DRAG</code>. * <code>SWT.HOME</code>. * <code>SWT.END</code>. @@ -272,7 +272,7 @@ public int getPageIncrement () { } /** - * Returns the <em>selection</em>, which is the receiver's value. + * Returns the 'selection', which is the receiver's value. * * @return the selection * @@ -444,7 +444,7 @@ public void setPageIncrement (int value) { } /** - * Sets the <em>selection</em>, which is the receiver's + * Sets the 'selection', which is the receiver's * value, to the argument which must be greater than or equal * to zero. * diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java index fe5e347096..9405d91de7 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Spinner.java @@ -24,7 +24,7 @@ import org.eclipse.swt.events.*; * <p> * <dl> * <dt><b>Styles:</b></dt> - * <dd>READ_ONLY</dd> + * <dd>READ_ONLY, WRAP</dd> * <dt><b>Events:</b></dt> * <dd>Selection, Modify</dd> * </dl> @@ -65,6 +65,7 @@ public class Spinner extends Composite { * </ul> * * @see SWT#READ_ONLY + * @see SWT#WRAP * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -446,6 +447,16 @@ public int getSelection () { return (int) adjustment.value; } +/** + * Returns the number of decimal places used by the receiver. + * + * @return the digits + * + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public int getDigits () { checkWidget (); return OS.gtk_spin_button_get_digits (handle); @@ -871,6 +882,25 @@ public void setSelection (int value) { OS.g_signal_handlers_unblock_matched (handle, OS.G_SIGNAL_MATCH_DATA, 0, 0, 0, 0, VALUE_CHANGED); } +/** + * Sets the number of decimal places used by the receiver. + * <p> + * The digit setting is used to allow for floating point values in the receiver. + * For example, to set the selection to a floating point value of 1.37 call setDigits() with + * a value of 2 and setSelection() with a value of 137. Similarly, if getDigits() has a value + * of 2 and getSelection() returns 137 this should be interpreted as 1.37. This applies to all + * numeric APIs. + * + * @param value the new digits (must be greater than or equal to zero) + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_ARGUMENT - if the value is less than zero</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + */ public void setDigits (int value) { checkWidget (); if (value < 0) error (SWT.ERROR_INVALID_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java index 62aedc5679..426d79283d 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Table.java @@ -93,6 +93,7 @@ public class Table extends Composite { * @see SWT#CHECK * @see SWT#FULL_SELECTION * @see SWT#HIDE_SELECTION + * @see SWT#VIRTUAL * @see Widget#checkSubclass * @see Widget#getStyle */ @@ -1200,8 +1201,8 @@ public int getItemHeight () { } /** - * Returns an array of <code>TableItem</code>s which are the items - * in the receiver. + * Returns a (possibly empty) array of <code>TableItem</code>s which + * are the items in the receiver. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of items, so modifying the array will @@ -1270,8 +1271,8 @@ int /*long*/ getPixbufRenderer (int /*long*/ column) { /** * Returns an array of <code>TableItem</code>s that are currently - * selected in the receiver. An empty array indicates that no - * items are selected. + * selected in the receiver. The order of the items is unspecified. + * An empty array indicates that no items are selected. * <p> * Note: This is not the actual structure used by the receiver * to maintain its selection, so modifying the array will @@ -1337,7 +1338,8 @@ public int getSelectionIndex () { /** * Returns the zero-relative indices of the items which are currently - * selected in the receiver. The array is empty if no items are selected. + * selected in the receiver. The order of the indices is unspecified. + * The array is empty if no items are selected. * <p> * Note: This is not the actual structure used by the receiver * to maintain its selection, so modifying the array will @@ -2361,7 +2363,7 @@ void setScrollWidth (int /*long*/ column, int /*long*/ iter) { /** * Selects the item at the given zero-relative index in the receiver. - * The current selected is first cleared, then the new item is selected. + * The current selection is first cleared, then the new item is selected. * * @param index the index of the item to select * @@ -2531,8 +2533,8 @@ public void setTopIndex (int index) { * @param column the column to be shown * * @exception IllegalArgumentException <ul> - * <li>ERROR_NULL_ARGUMENT - if the item is null</li> - * <li>ERROR_INVALID_ARGUMENT - if the item has been disposed</li> + * <li>ERROR_NULL_ARGUMENT - if the column is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the column has been disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java index b3b3e9f189..bcadc137be 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TableItem.java @@ -170,7 +170,6 @@ void clear () { * </ul> * * @since 2.0 - * */ public Color getBackground () { checkWidget (); @@ -346,7 +345,6 @@ public Font getFont (int index) { * </ul> * * @since 2.0 - * */ public Color getForeground () { checkWidget (); @@ -442,7 +440,8 @@ public Image getImage (int index) { /** * Returns a rectangle describing the size and location * relative to its parent of an image at a column in the - * table. + * table. An empty rectangle is returned if index exceeds + * the index of the table's last column. * * @param index the index that specifies the column * @return the receiver's bounding image rectangle @@ -613,7 +612,6 @@ void releaseWidget () { * </ul> * * @since 2.0 - * */ public void setBackground (Color color) { checkWidget (); @@ -642,7 +640,6 @@ public void setBackground (Color color) { * </ul> * * @since 3.0 - * */ public void setBackground (int index, Color color) { checkWidget (); @@ -816,7 +813,6 @@ public void setFont (int index, Font font) { * </ul> * * @since 2.0 - * */ public void setForeground (Color color){ checkWidget (); @@ -845,7 +841,6 @@ public void setForeground (Color color){ * </ul> * * @since 3.0 - * */ public void setForeground (int index, Color color){ checkWidget (); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java index 7bc11bd191..603d48652f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Text.java @@ -45,6 +45,10 @@ public class Text extends Scrollable { /** * The maximum number of characters that can be entered * into a text widget. + * <p> + * Note that this value is platform dependent, based upon + * the native widget implementation. + * </p> */ public final static int LIMIT; /** @@ -457,7 +461,7 @@ public int getBorderWidth () { } /** - * Gets the line number of the caret. + * Returns the line number of the caret. * <p> * The line number of the caret is returned. * </p> @@ -479,7 +483,8 @@ public int getCaretLineNumber () { } /** - * Gets the location the caret. + * Returns a point describing the receiver's location relative + * to its parent (or its display if its parent is null). * <p> * The location of the caret is returned. * </p> @@ -506,9 +511,9 @@ public Point getCaretLocation () { } /** - * Gets the position of the caret. + * Returns the character position of the caret. * <p> - * The character position of the caret is returned. + * Indexing is zero based. * </p> * * @return the position of the caret @@ -530,7 +535,7 @@ public int getCaretPosition () { } /** - * Gets the number of characters. + * Returns the number of characters. * * @return number of characters in the widget * @@ -549,7 +554,7 @@ public int getCharCount () { } /** - * Gets the double click enabled flag. + * Returns the double click enabled flag. * <p> * The double click flag enables or disables the * default action of the text widget when the user @@ -569,7 +574,7 @@ public boolean getDoubleClickEnabled () { } /** - * Gets the echo character. + * Returns the echo character. * <p> * The echo character is the character that is * displayed when the user enters text or the @@ -582,6 +587,8 @@ public boolean getDoubleClickEnabled () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #setEchoChar */ public char getEchoChar () { checkWidget (); @@ -594,7 +601,7 @@ public char getEchoChar () { } /** - * Gets the editable state. + * Returns the editable state. * * @return whether or not the reciever is editable * @@ -616,7 +623,7 @@ GdkColor getForegroundColor () { } /** - * Gets the number of lines. + * Returns the number of lines. * * @return the number of lines in the widget * @@ -632,7 +639,7 @@ public int getLineCount () { } /** - * Gets the line delimiter. + * Returns the line delimiter. * * @return a string that is the line delimiter * @@ -640,6 +647,8 @@ public int getLineCount () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #DELIMITER */ public String getLineDelimiter () { checkWidget (); @@ -647,7 +656,7 @@ public String getLineDelimiter () { } /** - * Gets the height of a line. + * Returns the height of a line. * * @return the height of a row of text * @@ -662,7 +671,8 @@ public int getLineHeight () { } /** - * Returns the orientation of the receiver. + * Returns the orientation of the receiver, which will be one of the + * constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>. * * @return the orientation style * @@ -679,14 +689,17 @@ public int getOrientation () { } /** - * Gets the position of the selected text. + * Returns a <code>Point</code> whose x coordinate is the + * character position representing the start of the selected + * text, and whose y coordinate is the character position + * representing the end of the selection. An "empty" selection + * is indicated by the x and y coordinates having the same value. * <p> - * Indexing is zero based. The range of - * a selection is from 0..N where N is - * the number of characters in the widget. + * Indexing is zero based. The range of a selection is from + * 0..N where N is the number of characters in the widget. * </p> - * - * @return the start and end of the selection + * + * @return a point representing the selection start and end * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> @@ -708,7 +721,7 @@ public Point getSelection () { } /** - * Gets the number of selected characters. + * Returns the number of selected characters. * * @return the number of selected characters. * @@ -724,7 +737,7 @@ public int getSelectionCount () { } /** - * Gets the selected text. + * Gets the selected text, or an empty string if there is no current selection. * * @return the selected text * @@ -740,7 +753,7 @@ public String getSelectionText () { } /** - * Gets the number of tabs. + * Returns the number of tabs. * <p> * Tab stop spacing is specified in terms of the * space (' ') character. The width of a single @@ -770,9 +783,10 @@ int getTabWidth (int tabs) { } /** - * Gets the widget text. + * Returns the widget text. * <p> - * The text for a text widget is the characters in the widget. + * The text for a text widget is the characters in the widget, or + * an empty string if this has never been set. * </p> * * @return the widget text @@ -802,7 +816,7 @@ public String getText () { } /** - * Gets a range of text. Returns an empty string if the + * Returns a range of text. Returns an empty string if the * start of the range is greater than the end. * <p> * Indexing is zero based. The range of @@ -856,6 +870,8 @@ public String getText (int start, int end) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #LIMIT */ public int getTextLimit () { checkWidget (); @@ -889,7 +905,7 @@ public int getTopIndex () { } /** - * Gets the top pixel. + * Returns the top pixel. * <p> * The top pixel is the pixel position of the line * that is currently at the top of the widget. On @@ -1141,6 +1157,9 @@ int /*long*/ imContext () { * * @param string the string * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the string is <code>null</code></li> + * </ul> * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> @@ -1342,6 +1361,9 @@ void setCursor (int /*long*/ cursor) { * The double click flag enables or disables the * default action of the text widget when the user * double clicks. + * </p><p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. * </p> * * @param doubleClick the new double click flag @@ -1365,8 +1387,9 @@ public void setDoubleClickEnabled (boolean doubleClick) { * the echo character to '\0' clears the echo * character and redraws the original text. * If for any reason the echo character is invalid, - * the default echo character for the platform - * is used. + * or if the platform does not allow modification + * of the echo character, the default echo character + * for the platform is used. * </p> * * @param echo the new echo character @@ -1419,6 +1442,9 @@ void setForegroundColor (GdkColor color) { * Sets the orientation of the receiver, which must be one * of the constants <code>SWT.LEFT_TO_RIGHT</code> or <code>SWT.RIGHT_TO_LEFT</code>. * <p> + * Note: This operation is a hint and is not supported on + * platforms that do not have this concept. + * </p> * * @param orientation new orientation style * @@ -1470,7 +1496,8 @@ public void setSelection (int start) { } /** - * Sets the selection. + * Sets the selection to the range specified + * by the given start and end indices. * <p> * Indexing is zero based. The range of * a selection is from 0..N where N is @@ -1511,7 +1538,10 @@ public void setSelection (int start, int end) { } /** - * Sets the selection. + * Sets the selection to the range specified + * by the given point, where the x coordinate + * represents the start index and the y coordinate + * represents the end index. * <p> * Indexing is zero based. The range of * a selection is from 0..N where N is @@ -1635,6 +1665,8 @@ public void setText (String string) { * creating a read-only text widget. * </p><p> * To reset this value to the default, use <code>setTextLimit(Text.LIMIT)</code>. + * Specifying a limit value larger than <code>Text.LIMIT</code> sets the + * receiver's limit to <code>Text.LIMIT</code>. * </p> * * @param limit new text limit @@ -1646,6 +1678,8 @@ public void setText (String string) { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * + * @see #LIMIT */ public void setTextLimit (int limit) { checkWidget (); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java index 1810f6844d..f3b4d6773b 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Tree.java @@ -18,7 +18,7 @@ import org.eclipse.swt.events.*; /** * Instances of this class provide a selectable user interface object - * that displays a hierarchy of items and issue notificiation when an + * that displays a hierarchy of items and issue notification when an * item in the hierarchy is selected. * <p> * The item children that may be added to instances of this class @@ -891,6 +891,23 @@ public boolean getHeaderVisible () { return OS.gtk_tree_view_get_headers_visible (handle); } +/** + * Returns the item at the given, zero-relative index in the + * receiver. Throws an exception if the index is out of range. + * + * @param index the index of the item to return + * @return the item at the given index + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public TreeItem getItem (int index) { checkWidget(); int length = OS.gtk_tree_model_iter_n_children (modelHandle, 0); @@ -1011,8 +1028,8 @@ public int getItemHeight () { } /** - * Returns the items contained in the receiver - * that are direct item children of the receiver. These + * Returns a (possibly empty) array of items contained in the + * receiver that are direct item children of the receiver. These * are the roots of the tree. * <p> * Note: This is not the actual structure used by the receiver @@ -1115,8 +1132,8 @@ int /*long*/ getPixbufRenderer (int /*long*/ column) { /** * Returns an array of <code>TreeItem</code>s that are currently - * selected in the receiver. An empty array indicates that no - * items are selected. + * selected in the receiver. The order of the items is unspecified. + * An empty array indicates that no items are selected. * <p> * Note: This is not the actual structure used by the receiver * to maintain its selection, so modifying the array will @@ -1503,6 +1520,7 @@ void hookEvents () { * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> + * * @since 3.1 */ public int indexOf (TreeColumn column) { @@ -1514,6 +1532,26 @@ public int indexOf (TreeColumn column) { return -1; } +/** + * Searches the receiver's list starting at the first item + * (index 0) until an item is found that is equal to the + * argument, and returns the index of that item. If no item + * is found, returns -1. + * + * @param item the search item + * @return the index of the item + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public int indexOf (TreeItem item) { checkWidget(); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java index 098e95d2be..a871b72714 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/TreeItem.java @@ -52,7 +52,7 @@ public class TreeItem extends Item { * Style bits are also inherited from superclasses. * </p> * - * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param parent a tree control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct * * @exception IllegalArgumentException <ul> @@ -88,7 +88,7 @@ public TreeItem (Tree parent, int style) { * Style bits are also inherited from superclasses. * </p> * - * @param parent a composite control which will be the parent of the new instance (cannot be null) + * @param parent a tree control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct * @param index the index to store the receiver in its parent * @@ -126,7 +126,7 @@ public TreeItem (Tree parent, int style, int index) { * Style bits are also inherited from superclasses. * </p> * - * @param parentItem a composite control which will be the parent of the new instance (cannot be null) + * @param parentItem a tree control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct * * @exception IllegalArgumentException <ul> @@ -162,7 +162,7 @@ public TreeItem (TreeItem parentItem, int style) { * Style bits are also inherited from superclasses. * </p> * - * @param parentItem a composite control which will be the parent of the new instance (cannot be null) + * @param parentItem a tree control which will be the parent of the new instance (cannot be null) * @param style the style of control to construct * @param index the index to store the receiver in its parent * @@ -680,6 +680,23 @@ public int getItemCount () { return OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle); } +/** + * Returns the item at the given, zero-relative index in the + * receiver. Throws an exception if the index is out of range. + * + * @param index the index of the item to return + * @return the item at the given index + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_INVALID_RANGE - if the index is not between 0 and the number of elements in the list minus 1 (inclusive)</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public TreeItem getItem (int index) { checkWidget(); int length = OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle); @@ -694,8 +711,8 @@ public TreeItem getItem (int index) { } /** - * Returns an array of <code>TreeItem</code>s which are the - * direct item children of the receiver. + * Returns a (possibly empty) array of <code>TreeItem</code>s which + * are the direct item children of the receiver. * <p> * Note: This is not the actual structure used by the receiver * to maintain its list of items, so modifying the array will @@ -797,6 +814,26 @@ public String getText (int index) { return new String (Converter.mbcsToWcs (null, buffer)); } +/** + * Searches the receiver's list starting at the first item + * (index 0) until an item is found that is equal to the + * argument, and returns the index of that item. If no item + * is found, returns -1. + * + * @param item the search item + * @return the index of the item + * + * @exception IllegalArgumentException <ul> + * <li>ERROR_NULL_ARGUMENT - if the tool item is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the tool item has been disposed</li> + * </ul> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public int indexOf (TreeItem item) { checkWidget(); if (item == null) error (SWT.ERROR_NULL_ARGUMENT); @@ -839,6 +876,16 @@ void releaseWidget () { cellFont = null; } +/** + * Removes all of the items from the receiver. + * <p> + * @exception SWTException <ul> + * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> + * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> + * </ul> + * + * @since 3.1 + */ public void removeAll () { checkWidget (); int length = OS.gtk_tree_model_iter_n_children (parent.modelHandle, handle); diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java index 8a43d58c24..b46bdb8d2f 100644 --- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java +++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Widget.java @@ -157,6 +157,7 @@ Widget () {} * * @exception IllegalArgumentException <ul> * <li>ERROR_NULL_ARGUMENT - if the parent is null</li> + * <li>ERROR_INVALID_ARGUMENT - if the parent is disposed</li> * </ul> * @exception SWTException <ul> * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the parent</li> @@ -427,7 +428,7 @@ void error (int code) { * <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li> * </ul> * - * @see #setData + * @see #setData(Object) */ public Object getData () { checkWidget(); @@ -455,7 +456,7 @@ public Object getData () { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #setData + * @see #setData(String, Object) */ public Object getData (String key) { checkWidget(); @@ -482,7 +483,6 @@ public Object getData (String key) { * * @exception SWTException <ul> * <li>ERROR_WIDGET_DISPOSED - if the receiver has been disposed</li> - * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> */ public Display getDisplay () { @@ -1148,6 +1148,8 @@ char [] sendIMKeyEvent (int type, GdkEventKey keyEvent, char [] chars) { * <li>ERROR_WIDGET_DISPOSED - when the receiver has been disposed</li> * <li>ERROR_THREAD_INVALID_ACCESS - when called from the wrong thread</li> * </ul> + * + * @see #getData() */ public void setData (Object data) { checkWidget(); @@ -1180,7 +1182,7 @@ public void setData (Object data) { * <li>ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver</li> * </ul> * - * @see #getData + * @see #getData(String) */ public void setData (String key, Object value) { checkWidget(); |