diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml
index 186ee1b9c4a4..12501d5430f0 100644
--- a/doc/classes/CanvasItem.xml
+++ b/doc/classes/CanvasItem.xml
@@ -413,19 +413,20 @@
- Forces the transform to update. Transform changes in physics are not instant for performance reasons. Transforms are accumulated and then set. Use this if you need an up-to-date transform when doing physics operations.
+ Forces the node's transform to update. Fails if the node is not inside the tree. See also [method get_transform].
+ [b]Note:[/b] For performance reasons, transform changes are usually accumulated and applied [i]once[/i] at the end of the frame. The update propagates through [CanvasItem] children, as well. Therefore, use this method only when you need an up-to-date transform (such as during physics operations).
- Returns the [RID] of the [World2D] canvas where this item is in.
+ Returns the [RID] of the [World2D] canvas where this item is in used by the [RenderingServer].
- Returns the canvas item RID used by [RenderingServer] for this item.
+ Returns the internal canvas item [RID] used by the [RenderingServer] for this node.
@@ -443,7 +444,7 @@
- Returns the mouse's position in the [CanvasLayer] that this [CanvasItem] is in using the coordinate system of the [CanvasLayer].
+ Returns mouse cursor's global position relative to the [CanvasLayer] that contains this node.
[b]Note:[/b] For screen-space coordinates (e.g. when using a non-embedded [Popup]), you can use [method DisplayServer.mouse_get_position].
@@ -475,32 +476,33 @@
- Returns the transform matrix of this item.
+ Returns the transform matrix of this [CanvasItem].
- Returns the viewport's boundaries as a [Rect2].
+ Returns this node's viewport boundaries as a [Rect2]. See also [method Node.get_viewport].
- Returns the transform from the coordinate system of the canvas, this item is in, to the [Viewport]s embedders coordinate system.
+ Returns the transform from the coordinate system of the canvas, this item is in, to the [Viewport]s embedders coordinate system. See also [method Node.get_viewport].
- Returns an individual bit on the rendering visibility layer.
+ Returns [code]true[/code] if the layer at the given index is set in [member visibility_layer].
- Returns the [World2D] where this item is in.
+ Returns the [World2D] this node is registered to.
+ Usually, this is the same as this node's viewport (see [method Node.get_viewport] and [method Viewport.find_world_2d]).
@@ -512,13 +514,13 @@
- Returns [code]true[/code] if local transform notifications are communicated to children.
+ Returns [code]true[/code] if the node receives [constant NOTIFICATION_LOCAL_TRANSFORM_CHANGED] whenever its local transform changes. This is enabled with [method set_notify_local_transform].
- Returns [code]true[/code] if global transform notifications are communicated to children.
+ Returns [code]true[/code] if the node receives [constant NOTIFICATION_TRANSFORM_CHANGED] whenever its global transform changes. This is enabled with [method set_notify_transform].
@@ -539,14 +541,13 @@
- Transformations issued by [param event]'s inputs are applied in local space instead of global space.
+ Returns a copy the given [param event] with its coordinates converted from global space to this [CanvasItem]'s local space. If not possible, returns the same [InputEvent] unchanged.
- Moves this node to display on top of its siblings.
- Internally, the node is moved to the bottom of parent's child list. The method has no effect on nodes without a parent.
+ Moves this node below its siblings, usually causing the node to draw on top of its siblings. Does nothing if this node does not have a parent. See also [method Node.move_child].
@@ -559,14 +560,16 @@
- If [param enable] is [code]true[/code], this node will receive [constant NOTIFICATION_LOCAL_TRANSFORM_CHANGED] when its local transform changes.
+ If [code]true[/code], the node will receive [constant NOTIFICATION_LOCAL_TRANSFORM_CHANGED] whenever its local transform changes.
+ [b]Note:[/b] Many canvas items such as [Camera2D] or [CollisionShape2D] automatically enable this in order to function correctly.
- If [param enable] is [code]true[/code], this node will receive [constant NOTIFICATION_TRANSFORM_CHANGED] when its global transform changes.
+ If [code]true[/code], the node will receive [constant NOTIFICATION_TRANSFORM_CHANGED] whenever its local or global transform changes.
+ [b]Note:[/b] Many canvas items such as [Camera2D] or [CollisionObject2D] automatically enable this in order to function correctly.
@@ -580,13 +583,14 @@
- Show the [CanvasItem] if it's currently hidden. This is equivalent to setting [member visible] to [code]true[/code]. For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead.
+ Show the [CanvasItem] if it's currently hidden. This is equivalent to setting [member visible] to [code]true[/code].
+ [b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead.
- Allows the current node to clip child nodes, essentially acting as a mask.
+ The mode in which this node clips its children, acting as a mask.
The rendering layers in which this [CanvasItem] responds to [Light2D] nodes.
@@ -599,41 +603,42 @@
The color applied to this [CanvasItem]. This property does [b]not[/b] affect child [CanvasItem]s, unlike [member modulate] which affects both the node itself and its children.
- [b]Note:[/b] Internal children (e.g. sliders in [ColorPicker] or tab bar in [TabContainer]) are also not affected by this property (see [code]include_internal[/code] parameter of [method Node.get_child] and other similar methods).
+ [b]Note:[/b] Internal children are also not affected by this property (see the [code]include_internal[/code] parameter in [method Node.add_child]). For built-in nodes this includes sliders in [ColorPicker], and the tab bar in [TabContainer].
- If [code]true[/code], the object draws behind its parent.
+ If [code]true[/code], this node draws behind its parent.
- The texture filtering mode to use on this [CanvasItem].
+ The filtering mode used to render this [CanvasItem]'s texture(s).
- The texture repeating mode to use on this [CanvasItem].
+ The repeating mode used to render this [CanvasItem]'s texture(s).
If [code]true[/code], this [CanvasItem] will [i]not[/i] inherit its transform from parent [CanvasItem]s. Its draw order will also be changed to make it draw on top of other [CanvasItem]s that do not have [member top_level] set to [code]true[/code]. The [CanvasItem] will effectively act as if it was placed as a child of a bare [Node].
- If [code]true[/code], the parent [CanvasItem]'s [member material] property is used as this one's material.
+ If [code]true[/code], the parent [CanvasItem]'s [member material] is used as this node's material.
The rendering layer in which this [CanvasItem] is rendered by [Viewport] nodes. A [Viewport] will render a [CanvasItem] if it and all its parents share a layer with the [Viewport]'s canvas cull mask.
If [code]true[/code], this [CanvasItem] is drawn. The node is only visible if all of its ancestors are visible as well (in other words, [method is_visible_in_tree] must return [code]true[/code]).
- [b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead.
+ [b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup_*()[/code] functions instead.
- If [code]true[/code], this and child [CanvasItem] nodes with a higher Y position are rendered in front of nodes with a lower Y position. If [code]false[/code], this and child [CanvasItem] nodes are rendered normally in scene tree order.
- With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree.
+ If [code]true[/code], this and child [CanvasItem] nodes with a higher Y position are rendered in front of nodes with a higher Y position. If [code]false[/code], this and child [CanvasItem] nodes are rendered normally in scene tree order.
+ With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc) render together on the same Y position as the child node 'B'. This allows you to organize the render order of a scene without changing the scene tree.
Nodes sort relative to each other only if they are on the same [member z_index].
- If [code]true[/code], the node's Z index is relative to its parent's Z index. If this node's Z index is 2 and its parent's effective Z index is 3, then this node's effective Z index will be 2 + 3 = 5.
+ If [code]true[/code], this node's final Z index is relative to its parent's Z index.
+ For example, if [member z_index] is [code]2[/code] and its parent's final Z index is [code]3[/code], then this node's final Z index will be [code]5[/code] ([code]2 + 3[/code]).
- Controls the order in which the nodes render. A node with a higher Z index will display in front of others. Must be between [constant RenderingServer.CANVAS_ITEM_Z_MIN] and [constant RenderingServer.CANVAS_ITEM_Z_MAX] (inclusive).
- [b]Note:[/b] Changing the Z index of a [Control] only affects the drawing order, not the order in which input events are handled. This can be useful to implement certain UI animations, e.g. a menu where hovered items are scaled and should overlap others.
+ The order in which this node are drawn. A node with a higher Z index will display in front of others. Must be between [constant RenderingServer.CANVAS_ITEM_Z_MIN] and [constant RenderingServer.CANVAS_ITEM_Z_MAX] (inclusive).
+ [b]Note:[/b] The Z index does [b]not[/b] affect the order in which [CanvasItem] nodes are processed or the way input events are handled. This is especially important to keep in mind for [Control] nodes.
@@ -645,7 +650,7 @@
- Emitted when becoming hidden.
+ Emitted when this node becomes hidden.
@@ -655,22 +660,26 @@
- Emitted when the visibility (hidden/visible) changes.
+ Emitted when this node's visibility changes (see [member visible] and [method is_visible_in_tree]).
+ This signal is emitted [i]after[/i] the related [constant NOTIFICATION_VISIBILITY_CHANGED] notification.
- The [CanvasItem]'s global transform has changed. This notification is only received if enabled by [method set_notify_transform].
+ Notification received when this node's global transform changes, if [method is_transform_notification_enabled] is [code]true[/code]. See also [method set_notify_transform] and [method get_transform].
+ [b]Note:[/b] Many canvas items such as [Camera2D] or [CollisionObject2D] automatically enable this in order to function correctly.
- The [CanvasItem]'s local transform has changed. This notification is only received if enabled by [method set_notify_local_transform].
+ Notification received when this node's transform changes, if [method is_local_transform_notification_enabled] is [code]true[/code]. This is not received when a parent [Node2D]'s transform changes. See also [method set_notify_local_transform].
+ [b]Note:[/b] Many canvas items such as [Camera2D] or [CollisionShape2D] automatically enable this in order to function correctly.
The [CanvasItem] is requested to draw (see [method _draw]).
- The [CanvasItem]'s visibility has changed.
+ Notification received when this node's visibility changes (see [member visible] and [method is_visible_in_tree]).
+ This notification is received [i]before[/i] the related [signal visibility_changed] signal.
The [CanvasItem] has entered the canvas.
@@ -679,7 +688,7 @@
The [CanvasItem] has exited the canvas.
- The [CanvasItem]'s active [World2D] changed.
+ Notification received when this [CanvasItem] is registered to a new [World2D] (see [method get_world_2d]).
The [CanvasItem] will inherit the filter from its parent.
@@ -713,25 +722,25 @@
The [CanvasItem] will inherit the filter from its parent.
- Texture will not repeat.
+ The texture does not repeat.
- Texture will repeat normally.
+ The texture repeats when exceeding the texture's size.
- Texture will repeat in a 2×2 tiled mode, where elements at even positions are mirrored.
+ The texture repeats when the exceeding the texture's size in a "2×2 tiled mode". Repeated textures at even positions are mirrored.
Represents the size of the [enum TextureRepeat] enum.
- Child draws over parent and is not clipped.
+ Children are drawn over this node and are not clipped.
- Parent is used for the purposes of clipping only. Child is clipped to the parent's visible area, parent is not drawn.
+ This node is used as a mask and is not drawn. Children are clipped to this node's drawn area.
- Parent is used for clipping child, but parent is also drawn underneath child as normal before clipping child to its visible area.
+ This node is used as a mask and is also drawn. Children are clipped to the parent's drawn area.
Represents the size of the [enum ClipChildrenMode] enum.