8264125: Specification of Taskbar::getIconImage doesn't mention that the returned image might not be equal to the Taskbar::setIconImage one. (eg on Mac OS)

Alexander Zvegintsev · Alexander Zvegintsev · commit 51a1299b68fb · 2021-06-26T15:57:45.000Z
Reviewed-by: kizune, prr
diff --git a/src/java.desktop/share/classes/java/awt/Taskbar.java b/src/java.desktop/share/classes/java/awt/Taskbar.java
@@ -323,7 +323,7 @@ public PopupMenu getMenu() {
     }
 
     /**
-     * Changes this application's icon to the provided image.
+     * Requests the system to change this application's icon to the provided {@code image}.
      *
      * @param image to change
      * @throws SecurityException if a security manager exists and it denies the
@@ -340,6 +340,10 @@ public void setIconImage(final Image image) {
     /**
      * Obtains an image of this application's icon.
      *
+     * @apiNote The returned icon image may not be equal
+     * to an image set by {@link java.awt.Taskbar#setIconImage},
+     * but should be visually similar.
+     *
      * @return an image of this application's icon
      * @throws SecurityException if a security manager exists and it denies the
      * {@code RuntimePermission("canProcessApplicationEvents")} permission.

Original file line number	Diff line number	Diff line change
`@@ -323,7 +323,7 @@ public PopupMenu getMenu() {`
`323`	`323`	`}`
`324`	`324`
`325`	`325`	`/**`
`326`		`- * Changes this application's icon to the provided image.`
	`326`	`+ * Requests the system to change this application's icon to the provided {@code image}.`
`327`	`327`	`*`
`328`	`328`	`* @param image to change`
`329`	`329`	`* @throws SecurityException if a security manager exists and it denies the`
`@@ -340,6 +340,10 @@ public void setIconImage(final Image image) {`
`340`	`340`	`/**`
`341`	`341`	`* Obtains an image of this application's icon.`
`342`	`342`	`*`
	`343`	`+ * @apiNote The returned icon image may not be equal`
	`344`	`+ * to an image set by {@link java.awt.Taskbar#setIconImage},`
	`345`	`+ * but should be visually similar.`
	`346`	`+ *`
`343`	`347`	`* @return an image of this application's icon`
`344`	`348`	`* @throws SecurityException if a security manager exists and it denies the`
`345`	`349`	`* {@code RuntimePermission("canProcessApplicationEvents")} permission.`