From 3a61ca94524ca08007ac44392ff1cfa1af491094 Mon Sep 17 00:00:00 2001
From: MadeScientist <294023457@qq.com>
Date: Wed, 19 Nov 2025 19:39:02 +0800
Subject: [PATCH] Fix incorrect transform method reference in
 CanvasItem.get_screen_transform() documentation

The get_global_transform method of CanvasItem doesn't consider the canvas_transform, so when any camera is enabled, its return value may differ from get_screen_transform. Thus, we should use get_global_transform_with_canvas instead, which provides consistent results with or without cameras enabled.
---
 doc/classes/CanvasItem.xml | 2 +-
 doc/classes/Control.xml    | 8 ++++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml
index 6ddcfd5a853..1571e39da54 100644
--- a/doc/classes/CanvasItem.xml
+++ b/doc/classes/CanvasItem.xml
@@ -520,7 +520,7 @@
 			<return type="Transform2D" />
 			<description>
 				Returns the transform of this [CanvasItem] in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins.
-				Equals to [method get_global_transform] if the window is embedded (see [member Viewport.gui_embed_subwindows]).
+				Equivalent to [method get_global_transform_with_canvas] if the window is embedded (see [member Viewport.gui_embed_subwindows]).
 			</description>
 		</method>
 		<method name="get_transform" qualifiers="const">
diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml
index da2f62a9772..55111898f9a 100644
--- a/doc/classes/Control.xml
+++ b/doc/classes/Control.xml
@@ -493,10 +493,14 @@
 			<return type="Vector2" />
 			<description>
 				Returns the position of this [Control] in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins.
-				Equals to [member global_position] if the window is embedded (see [member Viewport.gui_embed_subwindows]).
+				Equivalent to [code]get_screen_transform().origin[/code] (see [method CanvasItem.get_screen_transform]).
 				[b]Example:[/b] Show a popup at the mouse position:
 				[codeblock]
-				popup_menu.position = get_screen_position() + get_local_mouse_position()
+				popup_menu.position = get_screen_position() + get_screen_transform().basis_xform(get_local_mouse_position())
+
+				# The above code is equivalent to:
+				popup_menu.position = get_screen_transform() * get_local_mouse_position()
+
 				popup_menu.reset_size()
 				popup_menu.popup()
 				[/codeblock]