Replace and deprecate Image creating methods accepting Strings as file-system paths

[HannesWell]

Using Strings to represent file-system paths is usually a bad idea since using String as type lacks context (String is almost like a primitive) and requires that callers handle OS-specific file-separators properly.

This PR proposes to provide alternatives for existing Image creating methods that accept Strings to represent file-system paths and to deprecate the existing methods, but not for removal since they probably have a huge user-base.

The type File is used 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.

There are multiple callers left that have to be adapted but I want to reach consensus about the new API first.

[github-actions]

Test Results

   496 files   -  6     496 suites   - 6   10m 29s ⏱️ + 1m 46s
 4 278 tests  - 56   4 264 ✅  - 56   10 💤  - 4  1 ❌ +1   3 🔥 + 3 
16 501 runs   - 74  16 381 ✅  - 85  104 💤  - 5  4 ❌ +4  12 🔥 +12 

For more details on these failures and errors, see this check.

Results for commit f66a204. ± Comparison against base commit 0071da4.

This pull request removes 56 tests.

org.eclipse.swt.graphics.ImageWin32Tests ‑ testImageDataForDifferentFractionalZoomsShouldBeDifferent
org.eclipse.swt.graphics.ImageWin32Tests ‑ testImageShouldHaveDimesionAsPerZoomLevel
org.eclipse.swt.tests.gtk.Test_GtkConverter ‑ test_HeuristicASCII_dollarSign
org.eclipse.swt.tests.gtk.Test_GtkConverter ‑ test_HeuristicASCII_emptyString
org.eclipse.swt.tests.gtk.Test_GtkConverter ‑ test_HeuristicASCII_letterA
org.eclipse.swt.tests.gtk.Test_GtkConverter ‑ test_HeuristicASCII_letters
org.eclipse.swt.tests.gtk.Test_GtkConverter ‑ test_HeuristicUTF16LE_null
org.eclipse.swt.tests.gtk.Test_GtkConverter ‑ test_HeuristicUTF16_AsciiLetters
org.eclipse.swt.tests.gtk.Test_GtkConverter ‑ test_HeuristicUTF16_Asciiletter
org.eclipse.swt.tests.gtk.Test_GtkConverter ‑ test_HeuristicUTF16_LotsOfLetters
…

♻️ This comment has been updated with latest results.

[HannesWell]

There are multiple callers left that have to be adapted but I want to reach consensus about the new API first.

Furthermore with this the existing ImageFileNameProvider should be deprecated too and replaced with a ImageFileProvider returning a File too.

But with all the ongoing effort on improving high-DPI support I wonder if this should be part of a greater API rework? Not that I'm aware of one, but I would like to make sure that there aren't concurrent, maybe even conflicting efforts.
@HeikoKlare could you help here?

[laeubi]

The type File is used 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.

I think this is a bad choice, as Path is not really "modern" but much more flexible and while each File can be converted into a Path the reverse is not true. Also o.e.swt.graphics.Path usage is quite rare in SWT application and actually this is for what namespaces where made in java.

So adding any new API should also use new/modern/better types and it would allow to use alternative sources beside local files.

[HeikoKlare]

Yes, we plan to rework the Image class because of the HiDPI improvements. And actually, the proposed change is conflicting to what we need to do for that.

The reason is that we currently have a bunch of constructors that create "static" images. That means, these images are created once for a specific zoom value and can then only be rescaled to other zoom values via scaling the raster graphics (leading to blurry results). We are working on replacing all these "static" image initializations with "dynamic" ones, i.e., those that are able to create/render an image for whatever zoom is required (like already possible with ImageFileNameProvider/ImageDataProvider). That is the reason why we, for example, created a new constructor taking an "image drawer" that is capable of rendering an on-demand image in whatever zoom value is required as a replacement for just creating an image with fixed width/height and drawing into it: #1734

This is necessary as with the enhanced HiDPI support on Windows it must be possible to always retrieve an image according to the zoom of the monitor the containing shell is currently placed on. If you are interested, you find an analysis of static/dynamic image construction in our backlog: vi-eclipse/Eclipse-Platform#171 (comment)

I can have a further look at this PR and the neccessity of it to find a solution that is conforming with the enhanced HiDPI support. I just have to leave now for the rest of the day, so I at least wanted to give you the above comment to make you aware of that "conflict".

[HeikoKlare]

So having now taken another look at the proposal, I am not yet completely sure about the reason for these changes. I agree that the existing APIs are outdated and need to be reworked, but is there a specific trigger for doing it now and in this way? In particular, do we need a replacement for the deprecated constructor at all? We would actually propose to deprecate the Image constructor accepting a string (referring to a local file) without adding a new one as a replacement for it. Instead, the deprecation notice should give advise how to create an image in a "dynamic" way, i.e., with the ability to rescale according to requested zoom (if possible) based on the existing providers.

Taking a look at current usages of new Image(device, filename) in the Eclipse platform, I only see two that are not in tests or examples, which are inside FileImageDescriptor and URLImageDescriptor. I would try to replace those two usages with ImageFileNameProviders (or maybe some replacement of that based on File/Path instead of String) and then completely get rid of this constructor. I have not taken a look at other consumers like JDT to see whether there may be more usages of that method, but I did not find that many blurry-scaled images with the new monitor-specific scaling mode on Windows, but all images created with that constructor would become blurry when changing monitor scaling.

[HannesWell]

The type File is used 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.

I think this is a bad choice, as Path is not really "modern" but much more flexible and while each File can be converted into a Path the reverse is not true. Also o.e.swt.graphics.Path usage is quite rare in SWT application and actually this is for what namespaces where made in java.

Ok, if it's not widely used I'll change it to Path. Personally I cannot remember to have used SWT's path, but I'm also not developing that many UIs.

So having now taken another look at the proposal, I am not yet completely sure about the reason for these changes. I agree that the existing APIs are outdated and need to be reworked, but is there a specific trigger for doing it now and in this way?

Yes, the specific trigger is #1638 (comment)
With the current state of the PR we would add new constructors that use Strings for file-system paths and I would like to avoid that.

In particular, do we need a replacement for the deprecated constructor at all? We would actually propose to deprecate the Image constructor accepting a string (referring to a local file) without adding a new one as a replacement for it. Instead, the deprecation notice should give advise how to create an image in a "dynamic" way, i.e., with the ability to rescale according to requested zoom (if possible) based on the existing providers.

Not having a simple constructor that allows to directly create an image from a file would make the creation of images less simple, but 'forcing' users to use the more capable constructors is probably better on the long run.

On the other hand not all images are icons. Maybe one just wants to display an image image because that person has implemented a simple image-viewer. Of course one can always use zoom -> Path.of("myImage.png") instead of just Path.of("myImage.png").

Taking a look at current usages of new Image(device, filename) in the Eclipse platform, I only see two that are not in tests or examples, which are inside FileImageDescriptor and URLImageDescriptor. I would try to replace those two usages with ImageFileNameProviders (or maybe some replacement of that based on File/Path instead of String) and then completely get rid of this constructor. I have not taken a look at other consumers like JDT to see whether there may be more usages of that method, but I did not find that many blurry-scaled images with the new monitor-specific scaling mode on Windows, but all images created with that constructor would become blurry when changing monitor scaling.

Using ImageFileNameProvider respectively a new ImageFileProvider or maybe better ImagePathProvider sounds like an interesting idea. I'll check how that can be integrated with #1638, but in general this sounds suitable.

In general I think it's good we are talking about it. :)

[HeikoKlare]

On the other hand not all images are icons. Maybe one just wants to display an image image because that person has implemented a simple image-viewer. Of course one can always use zoom -> Path.of("myImage.png") instead of just Path.of("myImage.png").

I see, valid point. From a design perspective, it would of course make sense to separate these two use cases and distinguish between "dynamic" and "static" images already by type. But for the sake of API compatibility, that's of course not that easy. So probably we will need to provide separate constructors that clearly state what they are supposed to be used for, i.e., those being used for scalable graphics like icons need to be "provider-based" while plain images may be created directly via a file.

Yes, the specific trigger is #1638 (comment)
With the current state of the PR we would add new constructors that use Strings for file-system paths and I would like to avoid that.

Just to get this correctly: the PR does currently only require new ImageData constructors, but not necessary Image constructors, does it? So wouldn't it be possible to only extend ImageData and wrap the conversion String -> File inside the existing Image constructor? I am just asking for the sake of understanding, not that I propose to make this the final solution :-)