Skip to content

Enhance Javadoc for non-dynamic Image constructors #3383

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
HeikoKlare merged 1 commit into from
Jun 17, 2026
+99 −30
Merged

Enhance Javadoc for non-dynamic Image constructors #3383

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 33 additions & 10 deletions bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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) {
Expand Down Expand Up @@ -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.
Expand All @@ -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) {
Expand Down
43 changes: 33 additions & 10 deletions bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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) {
Expand Down Expand Up @@ -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.
Expand All @@ -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) {
Expand Down
43 changes: 33 additions & 10 deletions bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/graphics/Image.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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) {
Expand Down Expand Up @@ -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.
Expand All @@ -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) {
Expand Down
Loading