From 50ef6f8c1ef01ba205f67094d12ea9d62c47b5a1 Mon Sep 17 00:00:00 2001
From: Heiko Klare <heiko.klare@vector.com>
Date: Sat, 7 Sep 2024 11:46:55 +0200
Subject: [PATCH] Correct contracts of Control#[get|set]Location() #790

The Control#getLocation() and Control#setLocation(...) operations
currently claim to always work (i.e., yield reasonable values or
actually change the location). This specification is incorrect when
executing these methods in shells on a platform that uses the Wayland
protocol. Since there is currently no fix to make the implementation
fulfill the specification, this adds an according warning to the
specification in order to avoid that clients rely on the specification
to be fulfilled.

Contributes to
https://github.com/eclipse-platform/eclipse.platform.swt/issues/790
---
 .../org/eclipse/swt/widgets/Control.java      | 39 ++++++++++++-------
 .../gtk/org/eclipse/swt/widgets/Control.java  | 39 ++++++++++++-------
 .../org/eclipse/swt/widgets/Control.java      | 39 ++++++++++++-------
 3 files changed, 75 insertions(+), 42 deletions(-)

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 13e26aa318e..9b9150031df 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	
@@ -1726,10 +1726,15 @@ public Object getLayoutData () {
 }
 
 /**
- * Returns a point describing the receiver's location relative
- * to its parent in points (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Returns a point describing the receiver's location relative to its parent in
+ * points (or its display if its parent is null), unless the receiver is a
+ * shell. In this case, the point is usually relative to the display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not yield a
+ * value with the expected meaning on some platforms. For example, executing
+ * this operation on a shell when the environment uses the Wayland protocol, the
+ * result is <b>not</b> a coordinate relative to the display. It will not change
+ * when moving the shell.
  *
  * @return the receiver's location
  *
@@ -3974,11 +3979,14 @@ public void setLayoutData (Object layoutData) {
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Sets the receiver's location to the point specified by the arguments which
+ * are relative to the receiver's parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the point is relative to the
+ * display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not have the
+ * intended effect on some platforms. For example, executing this operation on a
+ * shell when the environment uses the Wayland protocol, nothing will happen.
  *
  * @param x the new x coordinate for the receiver
  * @param y the new y coordinate for the receiver
@@ -3994,11 +4002,14 @@ public void setLocation (int x, int y) {
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Sets the receiver's location to the point specified by the argument which
+ * is relative to the receiver's parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the point is relative to the
+ * display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not have the
+ * intended effect on some platforms. For example, executing this operation on a
+ * shell when the environment uses the Wayland protocol, nothing will happen.
  *
  * @param location the new location for the receiver
  *
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 7a87db4125b..751601c8a2d 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	
@@ -1215,10 +1215,15 @@ int setBounds (int x, int y, int width, int height, boolean move, boolean resize
 }
 
 /**
- * Returns a point describing the receiver's location relative
- * to its parent in points (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Returns a point describing the receiver's location relative to its parent in
+ * points (or its display if its parent is null), unless the receiver is a
+ * shell. In this case, the point is usually relative to the display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not yield a
+ * value with the expected meaning on some platforms. For example, executing
+ * this operation on a shell when the environment uses the Wayland protocol, the
+ * result is <b>not</b> a coordinate relative to the display. It will not change
+ * when moving the shell.
  *
  * @return the receiver's location
  *
@@ -1247,11 +1252,14 @@ Point getLocationInPixels () {
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Sets the receiver's location to the point specified by the argument which
+ * is relative to the receiver's parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the point is relative to the
+ * display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not have the
+ * intended effect on some platforms. For example, executing this operation on a
+ * shell when the environment uses the Wayland protocol, nothing will happen.
  *
  * @param location the new location for the receiver
  *
@@ -1274,11 +1282,14 @@ void setLocationInPixels (Point location) {
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Sets the receiver's location to the point specified by the arguments which
+ * are relative to the receiver's parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the point is relative to the
+ * display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not have the
+ * intended effect on some platforms. For example, executing this operation on a
+ * shell when the environment uses the Wayland protocol, nothing will happen.
  *
  * @param x the new x coordinate for the receiver
  * @param y the new y coordinate for the receiver
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 03c32a4c72d..53f74792919 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	
@@ -1350,10 +1350,15 @@ public Object getLayoutData () {
 }
 
 /**
- * Returns a point describing the receiver's location relative
- * to its parent in points (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Returns a point describing the receiver's location relative to its parent in
+ * points (or its display if its parent is null), unless the receiver is a
+ * shell. In this case, the point is usually relative to the display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not yield a
+ * value with the expected meaning on some platforms. For example, executing
+ * this operation on a shell when the environment uses the Wayland protocol, the
+ * result is <b>not</b> a coordinate relative to the display. It will not change
+ * when moving the shell.
  *
  * @return the receiver's location
  *
@@ -3486,11 +3491,14 @@ public void setLayoutData (Object layoutData) {
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Sets the receiver's location to the point specified by the arguments which
+ * are relative to the receiver's parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the point is relative to the
+ * display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not have the
+ * intended effect on some platforms. For example, executing this operation on a
+ * shell when the environment uses the Wayland protocol, nothing will happen.
  *
  * @param x the new x coordinate for the receiver
  * @param y the new y coordinate for the receiver
@@ -3514,11 +3522,14 @@ void setLocationInPixels (int x, int y) {
 }
 
 /**
- * Sets the receiver's location to the point specified by
- * the arguments which are relative to the receiver's
- * parent (or its display if its parent is null), unless
- * the receiver is a shell. In this case, the point is
- * relative to the display.
+ * Sets the receiver's location to the point specified by the argument which
+ * is relative to the receiver's parent (or its display if its parent is null),
+ * unless the receiver is a shell. In this case, the point is relative to the
+ * display.
+ * <p>
+ * <b>Warning:</b> When executing this operation on a shell, it may not have the
+ * intended effect on some platforms. For example, executing this operation on a
+ * shell when the environment uses the Wayland protocol, nothing will happen.
  *
  * @param location the new location for the receiver
  *