From 7093603c1d0ab5bd476febffa7cbee91cb5f5349 Mon Sep 17 00:00:00 2001
From: "Kellner, Niklas" <mail@niklaskellner.de>
Date: Wed, 9 Jul 2025 13:06:01 +0200
Subject: [PATCH] [GTK] Background images behavior differs from Windows and Mac

Document the intended behavior

Contributes to:
https://github.com/eclipse-platform/eclipse.platform.swt/issues/2290
---
 .../Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java  | 6 ++++++
 .../Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java    | 6 ++++++
 .../Eclipse SWT/win32/org/eclipse/swt/widgets/Control.java  | 6 ++++++
 3 files changed, 18 insertions(+)

diff --git a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java
index 9b9150031df..1bd2ff7879c 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java	
+++ b/bundles/org.eclipse.swt/Eclipse SWT/cocoa/org/eclipse/swt/widgets/Control.java	
@@ -3547,6 +3547,9 @@ void setBackground () {
  * <p>
  * Note: This operation is a hint and may be overridden by the platform.
  * </p>
+ * <p>
+ * Note: The background color can be overridden by setting a background image.
+ * </p>
  * @param color the new color (or null)
  *
  * @exception IllegalArgumentException <ul>
@@ -3587,6 +3590,9 @@ private void _setBackground (Color color) {
  * Note: This operation is a hint and may be overridden by the platform.
  * For example, on Windows the background of a Button cannot be changed.
  * </p>
+ * <p>
+ * Note: Setting a background image overrides a set background color.
+ * </p>
  * @param image the new image (or null)
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java
index a229c31beae..2b25c96fb69 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java	
+++ b/bundles/org.eclipse.swt/Eclipse SWT/gtk/org/eclipse/swt/widgets/Control.java	
@@ -5176,6 +5176,9 @@ void setBackground () {
  * <p>
  * Note: This operation is a hint and may be overridden by the platform.
  * </p>
+ * <p>
+ * Note: The background color can be overridden by setting a background image.
+ * </p>
  * @param color the new color (or null)
  *
  * @exception IllegalArgumentException <ul>
@@ -5281,6 +5284,9 @@ void setBackgroundGdkRGBA (long handle, GdkRGBA rgba) {
  * Note: This operation is a hint and may be overridden by the platform.
  * For example, on Windows the background of a Button cannot be changed.
  * </p>
+ * <p>
+ * Note: Setting a background image overrides a set background color.
+ * </p>
  * @param image the new image (or null)
  *
  * @exception IllegalArgumentException <ul>
diff --git a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Control.java b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Control.java
index e32faf76eef..09378668556 100644
--- a/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Control.java	
+++ b/bundles/org.eclipse.swt/Eclipse SWT/win32/org/eclipse/swt/widgets/Control.java	
@@ -3072,6 +3072,9 @@ void setBackground () {
  * <p>
  * Note: This operation is a hint and may be overridden by the platform.
  * </p>
+ * <p>
+ * Note: The background color can be overridden by setting a background image.
+ * </p>
  * @param color the new color (or null)
  *
  * @exception IllegalArgumentException <ul>
@@ -3114,6 +3117,9 @@ private void _setBackground (Color color) {
  * Note: This operation is a hint and may be overridden by the platform.
  * For example, on Windows the background of a Button cannot be changed.
  * </p>
+ * <p>
+ * Note: Setting a background image overrides a set background color.
+ * </p>
  * @param image the new image (or null)
  *
  * @exception IllegalArgumentException <ul>