Replace Image creating methods accepting Strings as file-system paths

Use File instead of the more modern java.nio.file.Path to avoid
confusion with the Path class that already exists in the
'o.e.swt.graphics' package.

Author: HannesWell

bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/Image.java

@@ -713,7 +713,7 @@ public Image(Device device, InputStream stream) {
  * </p>
  *
  * @param device the device on which to create the image
- * @param filename the name of the file to load the image from
+ * @param file the name of the file to load the image from
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -730,21 +730,60 @@ public Image(Device device, InputStream stream) {
  * </ul>
  *
  * @see #dispose()
+ * @since 3.129
  */
-public Image(Device device, String filename) {
+public Image(Device device, File file) {
 	super(device);
 	NSAutoreleasePool pool = null;
 	if (!NSThread.isMainThread()) pool = (NSAutoreleasePool) new NSAutoreleasePool().alloc().init();
 	try {
-		if (filename == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
-		initNative(filename);
-		if (this.handle == null) init(new ImageData(filename));
+		if (file == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
+		initNative(file.toString());
+		if (this.handle == null) init(new ImageData(file));
 		init();
 	} finally {
 		if (pool != null) pool.release();
 	}
 }
 
+/**
+ * Constructs an instance of this class by loading its representation
+ * from the file with the specified name. Throws an error if an error
+ * occurs while loading the image, or if the result is an image
+ * of an unsupported type.
+ * <p>
+ * This constructor is provided for convenience when loading
+ * a single image only. If the specified file contains
+ * multiple images, only the first one will be used.
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
+ *
+ * @param device the device on which to create the image
+ * @param filename the name of the file to load the image from
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_IO - if an IO error occurs while reading from the file</li>
+ *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the image file describes an image with an unsupported depth</li>
+ *    <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
+ * </ul>
+ *
+ * @see #dispose()
+ * @deprecated Instead use {@link #Image(Device, File)}
+ */
+@Deprecated(since = "2025-03")
+public Image(Device device, String filename) {
+	this(device, new File(filename));
+}
+
 /**
  * Constructs an instance of this class by loading its representation
  * from the file retrieved from the ImageFileNameProvider. Throws an
@@ -880,7 +919,7 @@ public Image(Device device, ImageGcDrawer imageGcDrawer, int width, int height)
 	if (!NSThread.isMainThread()) pool = (NSAutoreleasePool) new NSAutoreleasePool().alloc().init();
 	try {
 		init (data);
-		init ();		
+		init ();
 	} finally {
 		if (pool != null) pool.release();
 	}

bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/graphics/ImageLoader.java

@@ -161,7 +161,7 @@ public ImageData[] load(InputStream stream) {
  * an error occurs while loading the images, or if the images are
  * not of a supported type. Returns the loaded image data array.
  *
- * @param filename the name of the file to load the images from
+ * @param file the name of the file to load the images from
  * @return an array of <code>ImageData</code> objects loaded from the specified file
  *
  * @exception IllegalArgumentException <ul>
@@ -172,17 +172,42 @@ public ImageData[] load(InputStream stream) {
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data</li>
  *    <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li>
  * </ul>
+ * @since 3.129
  */
-public ImageData[] load(String filename) {
-	if (filename == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
-	try (InputStream stream = new FileInputStream(filename)) {
+public ImageData[] load(File file) {
+	if (file == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
+	try (InputStream stream = new FileInputStream(file)) {
 		return load(stream);
 	} catch (IOException e) {
 		SWT.error(SWT.ERROR_IO, e);
 	}
 	return null;
 }
 
+/**
+ * Loads an array of <code>ImageData</code> objects from the
+ * file with the specified name. Throws an error if either
+ * an error occurs while loading the images, or if the images are
+ * not of a supported type. Returns the loaded image data array.
+ *
+ * @param filename the name of the file to load the images from
+ * @return an array of <code>ImageData</code> objects loaded from the specified file
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_IO - if an IO error occurs while reading the file</li>
+ *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data</li>
+ *    <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li>
+ * </ul>
+ * @deprecated Instead use {@link #load(File)}
+ */
+@Deprecated(since = "2025-03")
+public ImageData[] load(String filename) {
+	return load(new File(filename));
+}
+
 /**
  * Saves the image data in this ImageLoader to the specified stream.
  * The format parameter can have one of the following values:
@@ -236,7 +261,7 @@ public void save(OutputStream stream, int format) {
  * <dd>PNG file format</dd>
  * </dl>
  *
- * @param filename the name of the file to write the images to
+ * @param file the name of the file to write the images to
  * @param format the format to write the images in
  *
  * @exception IllegalArgumentException <ul>
@@ -247,16 +272,53 @@ public void save(OutputStream stream, int format) {
  *    <li>ERROR_INVALID_IMAGE - if the image data contains invalid data</li>
  *    <li>ERROR_UNSUPPORTED_FORMAT - if the image data cannot be saved to the requested format</li>
  * </ul>
+ * @since 3.129
  */
-public void save(String filename, int format) {
-	if (filename == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
-	try (OutputStream stream = new FileOutputStream(filename)) {
+public void save(File file, int format) {
+	if (file == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
+	try (OutputStream stream = new FileOutputStream(file)) {
 		save(stream, format);
 	} catch (IOException e) {
 		SWT.error(SWT.ERROR_IO, e);
 	}
 }
 
+/**
+ * Saves the image data in this ImageLoader to a file with the specified name.
+ * The format parameter can have one of the following values:
+ * <dl>
+ * <dt><code>IMAGE_BMP</code></dt>
+ * <dd>Windows BMP file format, no compression</dd>
+ * <dt><code>IMAGE_BMP_RLE</code></dt>
+ * <dd>Windows BMP file format, RLE compression if appropriate</dd>
+ * <dt><code>IMAGE_GIF</code></dt>
+ * <dd>GIF file format</dd>
+ * <dt><code>IMAGE_ICO</code></dt>
+ * <dd>Windows ICO file format</dd>
+ * <dt><code>IMAGE_JPEG</code></dt>
+ * <dd>JPEG file format</dd>
+ * <dt><code>IMAGE_PNG</code></dt>
+ * <dd>PNG file format</dd>
+ * </dl>
+ *
+ * @param filename the name of the file to write the images to
+ * @param format the format to write the images in
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_IO - if an IO error occurs while writing to the file</li>
+ *    <li>ERROR_INVALID_IMAGE - if the image data contains invalid data</li>
+ *    <li>ERROR_UNSUPPORTED_FORMAT - if the image data cannot be saved to the requested format</li>
+ * </ul>
+ * @deprecated Instead use {@link #save(File, int)}
+ */
+@Deprecated(since = "2025-03")
+public void save(String filename, int format) {
+	save(new File(filename), format);
+}
+
 /**
  * Adds the listener to the collection of listeners who will be
  * notified when image data is either partially or completely loaded.

bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/graphics/ImageData.java

@@ -365,7 +365,7 @@ public ImageData(InputStream stream) {
  * <code>ImageLoader.load()</code>.
  * </p>
  *
- * @param filename the name of the file to load the image from (must not be null)
+ * @param file the name of the file to load the image from (must not be null)
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
@@ -375,9 +375,10 @@ public ImageData(InputStream stream) {
  *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data</li>
  *    <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li>
  * </ul>
+ * @since 3.129
  */
-public ImageData(String filename) {
-	ImageData[] data = ImageDataLoader.load(filename);
+public ImageData(File file) {
+	ImageData[] data = ImageDataLoader.load(file);
 	if (data.length < 1) SWT.error(SWT.ERROR_INVALID_IMAGE);
 	ImageData i = data[0];
 	setAllFields(
@@ -400,6 +401,35 @@ public ImageData(String filename) {
 		i.delayTime);
 }
 
+/**
+ * Constructs an <code>ImageData</code> loaded from a file with the
+ * specified name. Throws an error if an error occurs loading the
+ * image, or if the image has an unsupported type.
+ * <p>
+ * This constructor is provided for convenience when loading a single
+ * image only. If the file contains multiple images, only the first
+ * one will be loaded. To load multiple images, use
+ * <code>ImageLoader.load()</code>.
+ * </p>
+ *
+ * @param filename the name of the file to load the image from (must not be null)
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_IO - if an IO error occurs while reading from the file</li>
+ *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data</li>
+ *    <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li>
+ * </ul>
+ * @since 3.129
+ * @deprecated Instead use {@link #ImageData(File)}
+ */
+@Deprecated(since = "2025-03")
+public ImageData(String filename) {
+	this(new File(filename));
+}
+
 /**
  * Prevents uninitialized instances from being created outside the package.
  */

bundles/org.eclipse.swt/Eclipse SWT/common/org/eclipse/swt/graphics/ImageDataLoader.java

@@ -25,8 +25,8 @@ public static ImageData[] load(InputStream stream) {
 		return new ImageLoader().load(stream);
 	}
 
-	public static ImageData[] load(String filename) {
-		return new ImageLoader().load(filename);
+	public static ImageData[] load(File file) {
+		return new ImageLoader().load(file);
 	}
 
 }

bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/graphics/Image.java

@@ -551,7 +551,7 @@ public Image(Device device, InputStream stream) {
  * </p>
  *
  * @param device the device on which to create the image
- * @param filename the name of the file to load the image from
+ * @param file the name of the file to load the image from
  *
  * @exception IllegalArgumentException <ul>
  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
@@ -568,18 +568,57 @@ public Image(Device device, InputStream stream) {
  * </ul>
  *
  * @see #dispose()
+ * @since 3.129
  */
-public Image(Device device, String filename) {
+public Image(Device device, File file) {
 	super(device);
-	if (filename == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
+	if (file == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
 
-	ImageData data = new ImageData(filename);
+	ImageData data = new ImageData(file);
 	currentDeviceZoom = DPIUtil.getDeviceZoom();
 	data = DPIUtil.autoScaleUp (device, data);
 	init(data);
 	init();
 }
 
+/**
+ * Constructs an instance of this class by loading its representation
+ * from the file with the specified name. Throws an error if an error
+ * occurs while loading the image, or if the result is an image
+ * of an unsupported type.
+ * <p>
+ * This constructor is provided for convenience when loading
+ * a single image only. If the specified file contains
+ * multiple images, only the first one will be used.
+ * <p>
+ * You must dispose the image when it is no longer required.
+ * </p>
+ *
+ * @param device the device on which to create the image
+ * @param filename the name of the file to load the image from
+ *
+ * @exception IllegalArgumentException <ul>
+ *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
+ *    <li>ERROR_NULL_ARGUMENT - if the file name is null</li>
+ * </ul>
+ * @exception SWTException <ul>
+ *    <li>ERROR_IO - if an IO error occurs while reading from the file</li>
+ *    <li>ERROR_INVALID_IMAGE - if the image file contains invalid data </li>
+ *    <li>ERROR_UNSUPPORTED_DEPTH - if the image file describes an image with an unsupported depth</li>
+ *    <li>ERROR_UNSUPPORTED_FORMAT - if the image file contains an unrecognized format</li>
+ * </ul>
+ * @exception SWTError <ul>
+ *    <li>ERROR_NO_HANDLES if a handle could not be obtained for image creation</li>
+ * </ul>
+ *
+ * @see #dispose()
+ * @deprecated Instead use {@link #Image(Device, File)}
+ */
+@Deprecated(since = "2025-03")
+public Image(Device device, String filename) {
+	this(device, new File(filename));
+}
+
 /**
  * Constructs an instance of this class by loading its representation
  * from the file retrieved from the ImageFileNameProvider. Throws an