Add ImageUtilities methods to help migrating away from "new ImageIcon" (SVG icon related)

[eirikbakke]

Background: To ensure that SVG icons are loaded and drawn at full resolution, direct use of ImageIcon constructors should be avoided in the NetBeans codebase. The ImageIcon instances returned from methods in ImageUtilities, by contrast, are instances of a special subclass of ImageIcon that support vector graphics painting.

During work to remove uses of "new ImageIcon" constructors in the codebase (including #8109), I see that a few new utility methods would be useful in ImageUtilities. This PR proposes adding the following methods to ImageUtilities:

• loadIcon(String,boolean) works like loadIconImage(String,boolean) but returns only a plain Icon (not IconImage). This would help discourage use of IconImage in the future.
• loadIcon(String) is equivalent to loadIcon(String,false)
• toImageIcon(Icon) helps cases where an existing API requires an ImageIcon to be returned, but where we only have an Icon.
• loadImage(URL) helps migrate away from uses of Toolkit.getDefaultToolkit().createImage(), which has similar problems as "new ImageIcon".

This PR also contains, in a separate commit, migration away from the Toolkit.getDefaultToolkit().createImage() method, using the new loadImage(URL) method. This makes, for instance, the "lightbulb" icons in the editor gutter show up properly with their new SVG icons:

[eirikbakke]

There is one more method I could add which might be useful, which is a mergeIcons(Icon,Icon,int,int) which works like mergeImages(Image,Image,int,int) but takes and returns Icon instances instead of Image. It could simplify some of the cases in #8109.

[eirikbakke]

I pushed a revision to the two commits in this PR. Changes since your previous review:

• Change the new loadImage(URL) to loadImage(URI). Update call sites accordingly in the second commit.
• Clean up the Javadoc in ImageUtilities to avoid repeating the explanation of resource path loading semantics (substitution of dark mode suffixes and SVG images) for every similar method. Some other Javadoc edits for grammar, consistency etc.
• Add the ImageUtilities.mergeIcons(Icon,Icon,int,int) method (like mergeImages(Image,Image,int,int) but takes and returns Icon instances instead of Image) as well, for future use.

[eirikbakke]

(Latest push was just a rebase on master.)

[mbien]

looks good to me. Please check the comment I added.

[mbien]

it might be better to fail on null since (new) code which doesn't check for null Icons before passing it to a conversion method is likely buggy and might benefit from failing early.

image2Icon will fail on null i believe, icon2Image does accept null but will log a warning + return placeholder image.

what do you think about keeping the naming pattern? -> icon2ImageIcon?

[eirikbakke]

When doing bulk refactoring in the style of #8109, it is useful if icon and toImageIcon(icon) is guaranteed not to change the current behavior. Otherwise, existing features could break e.g. if they previously relied on null values being quietly accepted.

(Often I can read the existing code and be 95% sure a null value is never passed... but getting the last 5% of certainty is very difficult. And I don't want to have to insert null checks everywhere, if I'm changing 20 call sites and each case is really not supposed to be null in the first place.)

Perhaps I will specify in the Javadoc that null is not a valid input, but log a warning if a null does occur, and still return null in that unexpected case?

what do you think about keeping the naming pattern? -> icon2ImageIcon?

Good idea, will rename.

[mbien]

this would be mergeIcons2Images2Icon (I am kidding, please don't change :))