From 0cf5703a8e4fa07dd4e905ceb046b6d21f728ebf Mon Sep 17 00:00:00 2001
From: "Klare, Heiko" <Heiko.Klare@vector.com>
Date: Sat, 13 Jun 2026 15:50:47 +0200
Subject: [PATCH] Enhance Javadoc for non-dynamic Image constructors

Images may be requested at different zooms, depending on the context and
which they are used. Most types of images are able to generate image
data for different zooms from their data source, such as an
ImageDataProvider or ImageGcDrawer. The Image constructors accepting
width and height or a Rectangle reflecting width and heights are usually
used together with a GC that drawn on them. This usually produces proper
image data for one zoom only.

This change enhances the Javadoc of those constructors to emphasize that
they should only be used if none of the other constructors, in
particular the one accepting an ImageGcDrawer, are applicable. For this,
a statement about limitations for Windows ME and older are removed.
---
 .../cocoa/org/eclipse/swt/graphics/Image.java | 43 ++++++++++++++-----
 .../gtk/org/eclipse/swt/graphics/Image.java   | 43 ++++++++++++++-----
 .../win32/org/eclipse/swt/graphics/Image.java | 43 ++++++++++++++-----
 3 files changed, 99 insertions(+), 30 deletions(-)

diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
index 779b593ee2e..dbf1b852f5c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java	
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java	
@@ -279,16 +279,27 @@ void init(NSImageRep nativeRep, NSBitmapImageRep rep) {
  * by creating a GC and using any of its drawing operations,
  * as shown in the following example:
  * <pre>
- *    Image i = new Image(device, width, height);
+ *    Image i = new Image(device, imageWidth, imageHeight);
  *    GC gc = new GC(i);
- *    gc.drawRectangle(0, 0, 50, 50);
+ *    gc.drawRectangle(0, 0, imageWidth, imageHeight);
  *    gc.dispose();
  * </pre>
  * <p>
- * Note: Some platforms may have a limitation on the size
+ * <b>Note:</b> It is recommended to use
+ * {@link #Image(Device, ImageGcDrawer, int, int)} instead.
+ * With that constructor, image data for different zoom levels
+ * can be created on demand, whereas with this constructor
+ * the image data is only created once and may appear blurry
+ * when scaled to other zoom levels. The preceding example
+ * can be rewritten using the recommended constructor as follows:
+ * </p>
+ * <pre>
+ *    Image i = new Image(device, (gc, width, height) -> gc.drawRectangle(0, 0, width, height), imageWidth, imageHeight);
+ * </pre>
+ * <p>
+ * Some platforms may have a limitation on the size
  * of image that can be created (size depends on width, height,
- * and depth). For example, Windows 95, 98, and ME do not allow
- * images larger than 16M.
+ * and depth).
  * </p>
  * <p>
  * You must dispose the image when it is no longer required.
@@ -306,6 +317,7 @@ void init(NSImageRep nativeRep, NSBitmapImageRep rep) {
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
  *
+ * @see #Image(Device, ImageGcDrawer, int, int)
  * @see #dispose()
  */
 public Image(Device device, int width, int height) {
@@ -503,14 +515,25 @@ private void createRepFromSourceAndApplyFlag(NSBitmapImageRep srcRep, int srcWid
  * <pre>
  *    Image i = new Image(device, boundsRectangle);
  *    GC gc = new GC(i);
- *    gc.drawRectangle(0, 0, 50, 50);
+ *    gc.drawRectangle(0, 0, boundsRectangle.width, boundsRectangle.height);
  *    gc.dispose();
  * </pre>
  * <p>
- * Note: Some platforms may have a limitation on the size
+ * <b>Note:</b> It is recommended to use
+ * {@link #Image(Device, ImageGcDrawer, int, int)} instead.
+ * With that constructor, image data for different zoom levels
+ * can be created on demand, whereas with this constructor
+ * the image data is only created once and may appear blurry
+ * when scaled to other zoom levels. The preceding example
+ * can be rewritten using the recommended constructor as follows:
+ * </p>
+ * <pre>
+ *    Image i = new Image(device, (gc, width, height) -> gc.drawRectangle(0, 0, width, height), boundsRectangle.width, boundsRectangle.height);
+ * </pre>
+ * <p>
+ * Some platforms may have a limitation on the size
  * of image that can be created (size depends on width, height,
- * and depth). For example, Windows 95, 98, and ME do not allow
- * images larger than 16M.
+ * and depth).
  * </p>
  * <p>
  * You must dispose the image when it is no longer required.
@@ -530,7 +553,7 @@ private void createRepFromSourceAndApplyFlag(NSBitmapImageRep srcRep, int srcWid
  *
  * @see #dispose()
  *
- * @deprecated use {@link Image#Image(Device, int, int)} instead
+ * @deprecated use {@link #Image(Device, ImageGcDrawer, int, int)} or {@link #Image(Device, int, int)} instead
  */
 @Deprecated(since = "2025-06", forRemoval = true)
 public Image(Device device, Rectangle bounds) {
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 cbd3348943f..4c8593108c6 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	
@@ -184,16 +184,27 @@ public final class Image extends Resource implements Drawable {
  * by creating a GC and using any of its drawing operations,
  * as shown in the following example:
  * <pre>
- *    Image i = new Image(device, width, height);
+ *    Image i = new Image(device, imageWidth, imageHeight);
  *    GC gc = new GC(i);
- *    gc.drawRectangle(0, 0, 50, 50);
+ *    gc.drawRectangle(0, 0, imageWidth, imageHeight);
  *    gc.dispose();
  * </pre>
  * <p>
- * Note: Some platforms may have a limitation on the size
+ * <b>Note:</b> It is recommended to use
+ * {@link #Image(Device, ImageGcDrawer, int, int)} instead.
+ * With that constructor, image data for different zoom levels
+ * can be created on demand, whereas with this constructor
+ * the image data is only created once and may appear blurry
+ * when scaled to other zoom levels. The preceding example
+ * can be rewritten using the recommended constructor as follows:
+ * </p>
+ * <pre>
+ *    Image i = new Image(device, (gc, width, height) -> gc.drawRectangle(0, 0, width, height), imageWidth, imageHeight);
+ * </pre>
+ * <p>
+ * Some platforms may have a limitation on the size
  * of image that can be created (size depends on width, height,
- * and depth). For example, Windows 95, 98, and ME do not allow
- * images larger than 16M.
+ * and depth).
  * </p>
  * <p>
  * You must dispose the image when it is no longer required.
@@ -211,6 +222,7 @@ public final class Image extends Resource implements Drawable {
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
  *
+ * @see #Image(Device, ImageGcDrawer, int, int)
  * @see #dispose()
  */
 public Image(Device device, int width, int height) {
@@ -379,14 +391,25 @@ public Image(Device device, Image srcImage, int flag) {
  * <pre>
  *    Image i = new Image(device, boundsRectangle);
  *    GC gc = new GC(i);
- *    gc.drawRectangle(0, 0, 50, 50);
+ *    gc.drawRectangle(0, 0, boundsRectangle.width, boundsRectangle.height);
  *    gc.dispose();
  * </pre>
  * <p>
- * Note: Some platforms may have a limitation on the size
+ * <b>Note:</b> It is recommended to use
+ * {@link #Image(Device, ImageGcDrawer, int, int)} instead.
+ * With that constructor, image data for different zoom levels
+ * can be created on demand, whereas with this constructor
+ * the image data is only created once and may appear blurry
+ * when scaled to other zoom levels. The preceding example
+ * can be rewritten using the recommended constructor as follows:
+ * </p>
+ * <pre>
+ *    Image i = new Image(device, (gc, width, height) -> gc.drawRectangle(0, 0, width, height), boundsRectangle.width, boundsRectangle.height);
+ * </pre>
+ * <p>
+ * Some platforms may have a limitation on the size
  * of image that can be created (size depends on width, height,
- * and depth). For example, Windows 95, 98, and ME do not allow
- * images larger than 16M.
+ * and depth).
  * </p>
  * <p>
  * You must dispose the image when it is no longer required.
@@ -406,7 +429,7 @@ public Image(Device device, Image srcImage, int flag) {
  *
  * @see #dispose()
  *
- * @deprecated use {@link Image#Image(Device, int, int)} instead
+ * @deprecated use {@link #Image(Device, ImageGcDrawer, int, int)} or {@link #Image(Device, int, int)} instead
  */
 @Deprecated(since = "2025-06", forRemoval = true)
 public Image(Device device, Rectangle bounds) {
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/Image.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/Image.java
index fe0c3a3f310..12a78ed8464 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/Image.java	
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/Image.java	
@@ -275,16 +275,27 @@ private Image (Device device, int type, long handle, int nativeZoom) {
  * by creating a GC and using any of its drawing operations,
  * as shown in the following example:
  * <pre>
- *    Image i = new Image(device, width, height);
+ *    Image i = new Image(device, imageWidth, imageHeight);
  *    GC gc = new GC(i);
- *    gc.drawRectangle(0, 0, 50, 50);
+ *    gc.drawRectangle(0, 0, imageWidth, imageHeight);
  *    gc.dispose();
  * </pre>
  * <p>
- * Note: Some platforms may have a limitation on the size
+ * <b>Note:</b> It is recommended to use
+ * {@link #Image(Device, ImageGcDrawer, int, int)} instead.
+ * With that constructor, image data for different zoom levels
+ * can be created on demand, whereas with this constructor
+ * the image data is only created once and may appear blurry
+ * when scaled to other zoom levels. The preceding example
+ * can be rewritten using the recommended constructor as follows:
+ * </p>
+ * <pre>
+ *    Image i = new Image(device, (gc, width, height) -> gc.drawRectangle(0, 0, width, height), imageWidth, imageHeight);
+ * </pre>
+ * <p>
+ * Some platforms may have a limitation on the size
  * of image that can be created (size depends on width, height,
- * and depth). For example, Windows 95, 98, and ME do not allow
- * images larger than 16M.
+ * and depth).
  * </p>
  * <p>
  * You must dispose the image when it is no longer required.
@@ -302,6 +313,7 @@ private Image (Device device, int type, long handle, int nativeZoom) {
  *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
  * </ul>
  *
+ * @see #Image(Device, ImageGcDrawer, int, int)
  * @see #dispose()
  */
 public Image(Device device, int width, int height) {
@@ -437,14 +449,25 @@ public Image(Device device, Image srcImage, int flag) {
  * <pre>
  *    Image i = new Image(device, boundsRectangle);
  *    GC gc = new GC(i);
- *    gc.drawRectangle(0, 0, 50, 50);
+ *    gc.drawRectangle(0, 0, boundsRectangle.width, boundsRectangle.height);
  *    gc.dispose();
  * </pre>
  * <p>
- * Note: Some platforms may have a limitation on the size
+ * <b>Note:</b> It is recommended to use
+ * {@link #Image(Device, ImageGcDrawer, int, int)} instead.
+ * With that constructor, image data for different zoom levels
+ * can be created on demand, whereas with this constructor
+ * the image data is only created once and may appear blurry
+ * when scaled to other zoom levels. The preceding example
+ * can be rewritten using the recommended constructor as follows:
+ * </p>
+ * <pre>
+ *    Image i = new Image(device, (gc, width, height) -> gc.drawRectangle(0, 0, width, height), boundsRectangle.width, boundsRectangle.height);
+ * </pre>
+ * <p>
+ * Some platforms may have a limitation on the size
  * of image that can be created (size depends on width, height,
- * and depth). For example, Windows 95, 98, and ME do not allow
- * images larger than 16M.
+ * and depth).
  * </p>
  * <p>
  * You must dispose the image when it is no longer required.
@@ -464,7 +487,7 @@ public Image(Device device, Image srcImage, int flag) {
  *
  * @see #dispose()
  *
- * @deprecated use {@link Image#Image(Device, int, int)} instead
+ * @deprecated use {@link #Image(Device, ImageGcDrawer, int, int)} or {@link #Image(Device, int, int)} instead
  */
 @Deprecated(since = "2025-06", forRemoval = true)
 public Image(Device device, Rectangle bounds) {