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.