Class CanvasItem

Abstract base class for everything in 2D space.

Inheritance

Node

Object

CanvasItem

Derived

Control

Node2D

Remarks

Abstract base class for everything in 2D space. Canvas items are laid out in a tree; children inherit and extend their parent's transform. CanvasItem is extended by Control for GUI-related nodes, and by Node2D for 2D game objects.

Any CanvasItem can draw. For this, queue_redraw is called by the engine, then NOTIFICATION_DRAW will be received on idle time to request a redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the CanvasItem are provided (see draw_* functions). However, they can only be used inside _draw, its corresponding Object._notification or methods connected to the draw signal.

Canvas items are drawn in tree order on their canvas layer. By default, children are on top of their parents, so a root CanvasItem will be drawn behind everything. This behavior can be changed on a per-item basis.

A CanvasItem can be hidden, which will also hide its children. By adjusting various other properties of a CanvasItem, you can also modulate its color (via modulate or self_modulate), change its Z-index, blend mode, and more.

Note that properties like transform, modulation, and visibility are only propagated to direct CanvasItem child nodes. If there is a non-CanvasItem node in between, like Node or AnimationPlayer, the CanvasItem nodes below will have an independent position and modulate chain. See also top_level.

See Also

Viewport and canvas transforms

Custom drawing in 2D

Audio Spectrum Visualizer Demo

Fields

NOTIFICATION_TRANSFORM_CHANGED

The CanvasItem's global transform has changed. This notification is only received if enabled by CanvasItem.set_notify_transform.

const NOTIFICATION_TRANSFORM_CHANGED = 2000

NOTIFICATION_LOCAL_TRANSFORM_CHANGED

The CanvasItem's local transform has changed. This notification is only received if enabled by CanvasItem.set_notify_local_transform.

const NOTIFICATION_LOCAL_TRANSFORM_CHANGED = 35

NOTIFICATION_DRAW

The CanvasItem is requested to draw (see _draw).

const NOTIFICATION_DRAW = 30

NOTIFICATION_VISIBILITY_CHANGED

The CanvasItem's visibility has changed.

const NOTIFICATION_VISIBILITY_CHANGED = 31

NOTIFICATION_ENTER_CANVAS

The CanvasItem has entered the canvas.

const NOTIFICATION_ENTER_CANVAS = 32

NOTIFICATION_EXIT_CANVAS

The CanvasItem has exited the canvas.

const NOTIFICATION_EXIT_CANVAS = 33

NOTIFICATION_WORLD_2D_CHANGED

The CanvasItem's active World2D changed.

const NOTIFICATION_WORLD_2D_CHANGED = 36

Properties

clip_children

Allows the current node to clip child nodes, essentially acting as a mask.

Note: Clipping nodes cannot be nested or placed within CanvasGroups. If an ancestor of this node clips its children or is a CanvasGroup, then this node's clip mode should be set to CanvasItem.CLIP_CHILDREN_DISABLED to avoid unexpected behavior.

var clip_children : int = 0

Property Value

int

Remarks

• void set_clip_children_mode(int value)
• int get_clip_children_mode

light_mask

The rendering layers in which this CanvasItem responds to Light2D nodes.

var light_mask : int = 1

Property Value

int

Remarks

• void set_light_mask(int value)
• int get_light_mask

material

The material applied to this CanvasItem.

var material : Material

Property Value

Material

Remarks

• void set_material(Material value)
• Material get_material

modulate

The color applied to this CanvasItem. This property does affect child CanvasItems, unlike self_modulate which only affects the node itself.

var modulate : Color = Color(1, 1, 1, 1)

Property Value

Color

Remarks

• void set_modulate(Color value)
• Color get_modulate

self_modulate

The color applied to this CanvasItem. This property does not affect child CanvasItems, unlike modulate which affects both the node itself and its children.

Note: Internal children (e.g. sliders in ColorPicker or tab bar in TabContainer) are also not affected by this property (see include_internal parameter of Node.get_child and other similar methods).

var self_modulate : Color = Color(1, 1, 1, 1)

Property Value

Color

Remarks

• void set_self_modulate(Color value)
• Color get_self_modulate

show_behind_parent

If true, the object draws behind its parent.

var show_behind_parent : bool = false

Property Value

bool

Remarks

• void set_draw_behind_parent(bool value)
• bool is_draw_behind_parent_enabled

texture_filter

The texture filtering mode to use on this CanvasItem.

var texture_filter : int = 0

Property Value

int

Remarks

• void set_texture_filter(int value)
• int get_texture_filter

texture_repeat

The texture repeating mode to use on this CanvasItem.

var texture_repeat : int = 0

Property Value

int

Remarks

• void set_texture_repeat(int value)
• int get_texture_repeat

top_level

If true, this CanvasItem will not inherit its transform from parent CanvasItems. Its draw order will also be changed to make it draw on top of other CanvasItems that do not have top_level set to true. The CanvasItem will effectively act as if it was placed as a child of a bare Node.

var top_level : bool = false

Property Value

bool

Remarks

• void set_as_top_level(bool value)
• bool is_set_as_top_level

use_parent_material

If true, the parent CanvasItem's material property is used as this one's material.

var use_parent_material : bool = false

Property Value

bool

Remarks

• void set_use_parent_material(bool value)
• bool get_use_parent_material

visibility_layer

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.

var visibility_layer : int = 1

Property Value

int

Remarks

• void set_visibility_layer(int value)
• int get_visibility_layer

visible

If true, this CanvasItem may be drawn. Whether this CanvasItem is actually drawn depends on the visibility of all of its CanvasItem ancestors. In other words: this CanvasItem will be drawn when is_visible_in_tree returns true and all CanvasItem ancestors share at least one visibility_layer with this CanvasItem.

Note: For controls that inherit Popup, the correct way to make them visible is to call one of the multiple popup*() functions instead.

var visible : bool = true

Property Value

bool

Remarks

• void set_visible(bool value)
• bool is_visible

y_sort_enabled

If true, this and child CanvasItem nodes with a higher Y position are rendered in front of nodes with a lower Y position. If false, 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 z_index.

var y_sort_enabled : bool = false

Property Value

bool

Remarks

• void set_y_sort_enabled(bool value)
• bool is_y_sort_enabled

z_as_relative

If true, 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.

var z_as_relative : bool = true

Property Value

bool

Remarks

• void set_z_as_relative(bool value)
• bool is_z_relative

z_index

Controls the order in which the nodes render. A node with a higher Z index will display in front of others. Must be between CANVAS_ITEM_Z_MIN and CANVAS_ITEM_Z_MAX (inclusive).

Note: 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.

var z_index : int = 0

Property Value

int

Remarks

• void set_z_index(int value)
• int get_z_index

Methods

_draw

Qualifiers: virtual

Called when CanvasItem has been requested to redraw (after queue_redraw is called, either manually or by the engine).

Corresponds to the NOTIFICATION_DRAW notification in Object._notification.

void _draw

draw_animation_slice(float, float, float, float)

Subsequent drawing commands will be ignored unless they fall within the specified animation slice. This is a faster way to implement animations that loop on background rather than redrawing constantly.

void draw_animation_slice(float animation_length, float slice_begin, float slice_end, float offset)

Parameters

animation_length float

slice_begin float

slice_end float

offset float

draw_arc(Vector2, float, float, float, int, Color, float, bool)

Draws an unfilled arc between the given angles with a uniform color and width and optional antialiasing (supported only for positive width). The larger the value of point_count, the smoother the curve. See also CanvasItem.draw_circle.

If width is negative, it will be ignored and the arc will be drawn using RenderingServer.PRIMITIVE_LINE_STRIP. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

The arc is drawn from start_angle towards the value of end_angle so in clockwise direction if start_angle < end_angle and counter-clockwise otherwise. Passing the same angles but in reversed order will produce the same arc. If absolute difference of start_angle and end_angle is greater than TAU radians, then a full circle arc is drawn (i.e. arc will not overlap itself).

void draw_arc(Vector2 center, float radius, float start_angle, float end_angle, int point_count, Color color, float width, bool antialiased)

Parameters

center Vector2

radius float

start_angle float

end_angle float

point_count int

color Color

width float

antialiased bool

draw_char(Font, Vector2, String, int, Color)

Qualifiers: const

Draws a string first character using a custom font.

void draw_char(Font font, Vector2 pos, String char, int font_size, Color modulate)

Parameters

font Font

pos Vector2

char String

font_size int

modulate Color

draw_char_outline(Font, Vector2, String, int, int, Color)

Qualifiers: const

Draws a string first character outline using a custom font.

void draw_char_outline(Font font, Vector2 pos, String char, int font_size, int size, Color modulate)

Parameters

font Font

pos Vector2

char String

font_size int

size int

modulate Color

draw_circle(Vector2, float, Color, bool, float, bool)

Draws a circle. See also CanvasItem.draw_arc, CanvasItem.draw_polyline, and CanvasItem.draw_polygon.

If filled is true, the circle will be filled with the color specified. If filled is false, the circle will be drawn as a stroke with the color and width specified.

If width is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

If antialiased is true, half transparent "feathers" will be attached to the boundary, making outlines smooth.

Note: width is only effective if filled is false.

void draw_circle(Vector2 position, float radius, Color color, bool filled, float width, bool antialiased)

Parameters

position Vector2

radius float

color Color

filled bool

width float

antialiased bool

draw_colored_polygon(PackedVector2Array, Color, PackedVector2Array, Texture2D)

Draws a colored polygon of any number of points, convex or concave. Unlike CanvasItem.draw_polygon, a single color must be specified for the whole polygon.

Note: If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with Geometry2D.triangulate_polygon and using CanvasItem.draw_mesh, CanvasItem.draw_multimesh, or RenderingServer.canvas_item_add_triangle_array.

void draw_colored_polygon(PackedVector2Array points, Color color, PackedVector2Array uvs, Texture2D texture)

Parameters

points PackedVector2Array

color Color

uvs PackedVector2Array

texture Texture2D

draw_dashed_line(Vector2, Vector2, Color, float, float, bool, bool)

Draws a dashed line from a 2D point to another, with a given color and width. See also CanvasItem.draw_line, CanvasItem.draw_multiline, and CanvasItem.draw_polyline.

If width is negative, then a two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the line parts will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

dash is the length of each dash in pixels, with the gap between each dash being the same length. If aligned is true, the length of the first and last dashes may be shortened or lengthened to allow the line to begin and end at the precise points defined by from and to. Both ends are always symmetrical when aligned is true. If aligned is false, all dashes will have the same length, but the line may appear incomplete at the end due to the dash length not dividing evenly into the line length. Only full dashes are drawn when aligned is false.

If antialiased is true, half transparent "feathers" will be attached to the boundary, making outlines smooth.

Note: antialiased is only effective if width is greater than 0.0.

void draw_dashed_line(Vector2 from, Vector2 to, Color color, float width, float dash, bool aligned, bool antialiased)

Parameters

from Vector2

to Vector2

color Color

width float

dash float

aligned bool

antialiased bool

draw_end_animation

After submitting all animations slices via CanvasItem.draw_animation_slice, this function can be used to revert drawing to its default state (all subsequent drawing commands will be visible). If you don't care about this particular use case, usage of this function after submitting the slices is not required.

void draw_end_animation

draw_lcd_texture_rect_region(Texture2D, Rect2, Rect2, Color)

Draws a textured rectangle region of the font texture with LCD subpixel anti-aliasing at a given position, optionally modulated by a color.

Texture is drawn using the following blend operation, blend mode of the CanvasItemMaterial is ignored:

dst.r = texture.r * modulate.r * modulate.a + dst.r * (1.0 - texture.r * modulate.a);
dst.g = texture.g * modulate.g * modulate.a + dst.g * (1.0 - texture.g * modulate.a);
dst.b = texture.b * modulate.b * modulate.a + dst.b * (1.0 - texture.b * modulate.a);
dst.a = modulate.a + dst.a * (1.0 - modulate.a);

void draw_lcd_texture_rect_region(Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate)

Parameters

texture Texture2D

rect Rect2

src_rect Rect2

modulate Color

draw_line(Vector2, Vector2, Color, float, bool)

Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. See also CanvasItem.draw_dashed_line, CanvasItem.draw_multiline, and CanvasItem.draw_polyline.

If width is negative, then a two-point primitive will be drawn instead of a four-point one. This means that when the CanvasItem is scaled, the line will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

void draw_line(Vector2 from, Vector2 to, Color color, float width, bool antialiased)

Parameters

from Vector2

to Vector2

color Color

width float

antialiased bool

draw_mesh(Mesh, Texture2D, Transform2D, Color)

Draws a Mesh in 2D, using the provided texture. See MeshInstance2D for related documentation.

void draw_mesh(Mesh mesh, Texture2D texture, Transform2D transform, Color modulate)

Parameters

mesh Mesh

texture Texture2D

transform Transform2D

modulate Color

draw_msdf_texture_rect_region(Texture2D, Rect2, Rect2, Color, float, float, float)

Draws a textured rectangle region of the multi-channel signed distance field texture at a given position, optionally modulated by a color. See multichannel_signed_distance_field for more information and caveats about MSDF font rendering.

If outline is positive, each alpha channel value of pixel in region is set to maximum value of true distance in the outline radius.

Value of the pixel_range should the same that was used during distance field texture generation.

void draw_msdf_texture_rect_region(Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate, float outline, float pixel_range, float scale)

Parameters

texture Texture2D

rect Rect2

src_rect Rect2

modulate Color

outline float

pixel_range float

scale float

draw_multiline(PackedVector2Array, Color, float, bool)

Draws multiple disconnected lines with a uniform width and color. Each line is defined by two consecutive points from points array, i.e. i-th segment consists of points[2 * i], points[2 * i + 1] endpoints. When drawing large amounts of lines, this is faster than using individual CanvasItem.draw_line calls. To draw interconnected lines, use CanvasItem.draw_polyline instead.

If width is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

Note: antialiased is only effective if width is greater than 0.0.

void draw_multiline(PackedVector2Array points, Color color, float width, bool antialiased)

Parameters

points PackedVector2Array

color Color

width float

antialiased bool

draw_multiline_colors(PackedVector2Array, PackedColorArray, float, bool)

Draws multiple disconnected lines with a uniform width and segment-by-segment coloring. Each segment is defined by two consecutive points from points array and a corresponding color from colors array, i.e. i-th segment consists of points[2 * i], points[2 * i + 1] endpoints and has colors[i] color. When drawing large amounts of lines, this is faster than using individual CanvasItem.draw_line calls. To draw interconnected lines, use CanvasItem.draw_polyline_colors instead.

If width is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

Note: antialiased is only effective if width is greater than 0.0.

void draw_multiline_colors(PackedVector2Array points, PackedColorArray colors, float width, bool antialiased)

Parameters

points PackedVector2Array

colors PackedColorArray

width float

antialiased bool

draw_multiline_string(Font, Vector2, String, int, float, int, int, Color, int, int, int, int)

Qualifiers: const

Breaks text into lines and draws it using the specified font at the pos (top-left corner). The text will have its color multiplied by modulate. If width is greater than or equal to 0, the text will be clipped if it exceeds the specified width.

void draw_multiline_string(Font font, Vector2 pos, String text, int alignment, float width, int font_size, int max_lines, Color modulate, int brk_flags, int justification_flags, int direction, int orientation)

Parameters

font Font

pos Vector2

text String

alignment int

width float

font_size int

max_lines int

modulate Color

brk_flags int

justification_flags int

direction int

orientation int

draw_multiline_string_outline(Font, Vector2, String, int, float, int, int, int, Color, int, int, int, int)

Qualifiers: const

Breaks text to the lines and draws text outline using the specified font at the pos (top-left corner). The text will have its color multiplied by modulate. If width is greater than or equal to 0, the text will be clipped if it exceeds the specified width.

void draw_multiline_string_outline(Font font, Vector2 pos, String text, int alignment, float width, int font_size, int max_lines, int size, Color modulate, int brk_flags, int justification_flags, int direction, int orientation)

Parameters

font Font

pos Vector2

text String

alignment int

width float

font_size int

max_lines int

size int

modulate Color

brk_flags int

justification_flags int

direction int

orientation int

draw_multimesh(MultiMesh, Texture2D)

Draws a MultiMesh in 2D with the provided texture. See MultiMeshInstance2D for related documentation.

void draw_multimesh(MultiMesh multimesh, Texture2D texture)

Parameters

multimesh MultiMesh

texture Texture2D

draw_polygon(PackedVector2Array, PackedColorArray, PackedVector2Array, Texture2D)

Draws a solid polygon of any number of points, convex or concave. Unlike CanvasItem.draw_colored_polygon, each point's color can be changed individually. See also CanvasItem.draw_polyline and CanvasItem.draw_polyline_colors. If you need more flexibility (such as being able to use bones), use RenderingServer.canvas_item_add_triangle_array instead.

Note: If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with Geometry2D.triangulate_polygon and using CanvasItem.draw_mesh, CanvasItem.draw_multimesh, or RenderingServer.canvas_item_add_triangle_array.

void draw_polygon(PackedVector2Array points, PackedColorArray colors, PackedVector2Array uvs, Texture2D texture)

Parameters

points PackedVector2Array

colors PackedColorArray

uvs PackedVector2Array

texture Texture2D

draw_polyline(PackedVector2Array, Color, float, bool)

Draws interconnected line segments with a uniform color and width and optional antialiasing (supported only for positive width). When drawing large amounts of lines, this is faster than using individual CanvasItem.draw_line calls. To draw disconnected lines, use CanvasItem.draw_multiline instead. See also CanvasItem.draw_polygon.

If width is negative, it will be ignored and the polyline will be drawn using RenderingServer.PRIMITIVE_LINE_STRIP. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

void draw_polyline(PackedVector2Array points, Color color, float width, bool antialiased)

Parameters

points PackedVector2Array

color Color

width float

antialiased bool

draw_polyline_colors(PackedVector2Array, PackedColorArray, float, bool)

Draws interconnected line segments with a uniform width, point-by-point coloring, and optional antialiasing (supported only for positive width). Colors assigned to line points match by index between points and colors, i.e. each line segment is filled with a gradient between the colors of the endpoints. When drawing large amounts of lines, this is faster than using individual CanvasItem.draw_line calls. To draw disconnected lines, use CanvasItem.draw_multiline_colors instead. See also CanvasItem.draw_polygon.

If width is negative, it will be ignored and the polyline will be drawn using RenderingServer.PRIMITIVE_LINE_STRIP. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

void draw_polyline_colors(PackedVector2Array points, PackedColorArray colors, float width, bool antialiased)

Parameters

points PackedVector2Array

colors PackedColorArray

width float

antialiased bool

draw_primitive(PackedVector2Array, PackedColorArray, PackedVector2Array, Texture2D)

Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for a triangle, and 4 points for a quad. If 0 points or more than 4 points are specified, nothing will be drawn and an error message will be printed. See also CanvasItem.draw_line, CanvasItem.draw_polyline, CanvasItem.draw_polygon, and CanvasItem.draw_rect.

void draw_primitive(PackedVector2Array points, PackedColorArray colors, PackedVector2Array uvs, Texture2D texture)

Parameters

points PackedVector2Array

colors PackedColorArray

uvs PackedVector2Array

texture Texture2D

draw_rect(Rect2, Color, bool, float, bool)

Draws a rectangle. If filled is true, the rectangle will be filled with the color specified. If filled is false, the rectangle will be drawn as a stroke with the color and width specified. See also CanvasItem.draw_texture_rect.

If width is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive width like 1.0.

If antialiased is true, half transparent "feathers" will be attached to the boundary, making outlines smooth.

Note: width is only effective if filled is false.

Note: Unfilled rectangles drawn with a negative width may not display perfectly. For example, corners may be missing or brighter due to overlapping lines (for a translucent color).

void draw_rect(Rect2 rect, Color color, bool filled, float width, bool antialiased)

Parameters

rect Rect2

color Color

filled bool

width float

antialiased bool

draw_set_transform(Vector2, float, Vector2)

Sets a custom transform for drawing via components. Anything drawn afterwards will be transformed by this.

Note: oversampling does not take scale into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling gui/theme/default_font_multichannel_signed_distance_field (applies to the default project font only), or enabling Multichannel Signed Distance Field in the import options of a DynamicFont for custom fonts. On system fonts, multichannel_signed_distance_field can be enabled in the inspector.

void draw_set_transform(Vector2 position, float rotation, Vector2 scale)

Parameters

position Vector2

rotation float

scale Vector2

draw_set_transform_matrix(Transform2D)

Sets a custom transform for drawing via matrix. Anything drawn afterwards will be transformed by this.

void draw_set_transform_matrix(Transform2D xform)

Parameters

xform Transform2D

draw_string(Font, Vector2, String, int, float, int, Color, int, int, int)

Qualifiers: const

Draws text using the specified font at the pos (bottom-left corner using the baseline of the font). The text will have its color multiplied by modulate. If width is greater than or equal to 0, the text will be clipped if it exceeds the specified width.

Example: Draw "Hello world", using the project's default font:

• gdscript
• C#

# If using this method in a script that redraws constantly, move the
# `default_font` declaration to a member variable assigned in `_ready()`
# so the Control is only created once.
var default_font = ThemeDB.fallback_font
var default_font_size = ThemeDB.fallback_font_size
draw_string(default_font, Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, default_font_size)

See also Font.draw_string.

void draw_string(Font font, Vector2 pos, String text, int alignment, float width, int font_size, Color modulate, int justification_flags, int direction, int orientation)

Parameters

font Font

pos Vector2

text String

alignment int

width float

font_size int

modulate Color

justification_flags int

direction int

orientation int

draw_string_outline(Font, Vector2, String, int, float, int, int, Color, int, int, int)

Qualifiers: const

Draws text outline using the specified font at the pos (bottom-left corner using the baseline of the font). The text will have its color multiplied by modulate. If width is greater than or equal to 0, the text will be clipped if it exceeds the specified width.

void draw_string_outline(Font font, Vector2 pos, String text, int alignment, float width, int font_size, int size, Color modulate, int justification_flags, int direction, int orientation)

Parameters

font Font

pos Vector2

text String

alignment int

width float

font_size int

size int

modulate Color

justification_flags int

direction int

orientation int

draw_style_box(StyleBox, Rect2)

Draws a styled rectangle.

void draw_style_box(StyleBox style_box, Rect2 rect)

Parameters

style_box StyleBox

rect Rect2

draw_texture(Texture2D, Vector2, Color)

Draws a texture at a given position.

void draw_texture(Texture2D texture, Vector2 position, Color modulate)

Parameters

texture Texture2D

position Vector2

modulate Color

draw_texture_rect(Texture2D, Rect2, bool, Color, bool)

Draws a textured rectangle at a given position, optionally modulated by a color. If transpose is true, the texture will have its X and Y coordinates swapped. See also CanvasItem.draw_rect and CanvasItem.draw_texture_rect_region.

void draw_texture_rect(Texture2D texture, Rect2 rect, bool tile, Color modulate, bool transpose)

Parameters

texture Texture2D

rect Rect2

tile bool

modulate Color

transpose bool

draw_texture_rect_region(Texture2D, Rect2, Rect2, Color, bool, bool)

Draws a textured rectangle from a texture's region (specified by src_rect) at a given position, optionally modulated by a color. If transpose is true, the texture will have its X and Y coordinates swapped. See also CanvasItem.draw_texture_rect.

void draw_texture_rect_region(Texture2D texture, Rect2 rect, Rect2 src_rect, Color modulate, bool transpose, bool clip_uv)

Parameters

texture Texture2D

rect Rect2

src_rect Rect2

modulate Color

transpose bool

clip_uv bool

force_update_transform

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.

void force_update_transform

get_canvas

Qualifiers: const

Returns the RID of the World2D canvas where this item is in.

RID get_canvas

get_canvas_item

Qualifiers: const

Returns the canvas item RID used by RenderingServer for this item.

RID get_canvas_item

get_canvas_layer_node

Qualifiers: const

Returns the CanvasLayer that contains this node, or null if the node is not in any CanvasLayer.

CanvasLayer get_canvas_layer_node

get_canvas_transform

Qualifiers: const

Returns the transform from the coordinate system of the canvas, this item is in, to the Viewports coordinate system.

Transform2D get_canvas_transform

get_global_mouse_position

Qualifiers: const

Returns the mouse's position in the CanvasLayer that this CanvasItem is in using the coordinate system of the CanvasLayer.

Note: For screen-space coordinates (e.g. when using a non-embedded Popup), you can use mouse_get_position.

Vector2 get_global_mouse_position

get_global_transform

Qualifiers: const

Returns the global transform matrix of this item, i.e. the combined transform up to the topmost CanvasItem node. The topmost item is a CanvasItem that either has no parent, has non-CanvasItem parent or it has top_level enabled.

Transform2D get_global_transform

get_global_transform_with_canvas

Qualifiers: const

Returns the transform from the local coordinate system of this CanvasItem to the Viewports coordinate system.

Transform2D get_global_transform_with_canvas

get_instance_shader_parameter(StringName)

Qualifiers: const

Get the value of a shader parameter as set on this instance.

Variant get_instance_shader_parameter(StringName name)

Parameters

name StringName

get_local_mouse_position

Qualifiers: const

Returns the mouse's position in this CanvasItem using the local coordinate system of this CanvasItem.

Vector2 get_local_mouse_position

get_screen_transform

Qualifiers: const

Returns the transform of this CanvasItem in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins.

Equals to get_global_transform if the window is embedded (see gui_embed_subwindows).

Transform2D get_screen_transform

get_transform

Qualifiers: const

Returns the transform matrix of this item.

Transform2D get_transform

get_viewport_rect

Qualifiers: const

Returns the viewport's boundaries as a Rect2.

Rect2 get_viewport_rect

get_viewport_transform

Qualifiers: const

Returns the transform from the coordinate system of the canvas, this item is in, to the Viewports embedders coordinate system.

Transform2D get_viewport_transform

get_visibility_layer_bit(int)

Qualifiers: const

Returns an individual bit on the rendering visibility layer.

bool get_visibility_layer_bit(int layer)

Parameters

layer int

get_world_2d

Qualifiers: const

Returns the World2D where this item is in.

World2D get_world_2d

hide

Hide the CanvasItem if it's currently visible. This is equivalent to setting visible to false.

void hide

is_local_transform_notification_enabled

Qualifiers: const

Returns true if local transform notifications are communicated to children.

bool is_local_transform_notification_enabled

is_transform_notification_enabled

Qualifiers: const

Returns true if global transform notifications are communicated to children.

bool is_transform_notification_enabled

is_visible_in_tree

Qualifiers: const

Returns true if the node is present in the SceneTree, its visible property is true and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see _draw).

Visibility is checked only in parent nodes that inherit from CanvasItem, CanvasLayer, and Window. If the parent is of any other type (such as Node, AnimationPlayer, or Node3D), it is assumed to be visible.

Note: This method does not take visibility_layer into account, so even if this method returns true, the node might end up not being rendered.

bool is_visible_in_tree

make_canvas_position_local(Vector2)

Qualifiers: const

Transforms viewport_point from the viewport's coordinates to this node's local coordinates.

For the opposite operation, use get_global_transform_with_canvas.

var viewport_point = get_global_transform_with_canvas() * local_point

Vector2 make_canvas_position_local(Vector2 viewport_point)

Parameters

viewport_point Vector2

make_input_local(InputEvent)

Qualifiers: const

Transformations issued by event's inputs are applied in local space instead of global space.

InputEvent make_input_local(InputEvent event)

Parameters

event InputEvent

move_to_front

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.

void move_to_front

queue_redraw

Queues the CanvasItem to redraw. During idle time, if CanvasItem is visible, NOTIFICATION_DRAW is sent and _draw is called. This only occurs once per frame, even if this method has been called multiple times.

void queue_redraw

set_instance_shader_parameter(StringName, Variant)

Set the value of a shader uniform for this instance only (per-instance uniform). See also ShaderMaterial.set_shader_parameter to assign a uniform on all instances using the same ShaderMaterial.

Note: For a shader uniform to be assignable on a per-instance basis, it must be defined with instance uniform ... rather than uniform ... in the shader code.

Note: name is case-sensitive and must match the name of the uniform in the code exactly (not the capitalized name in the inspector).

void set_instance_shader_parameter(StringName name, Variant value)

Parameters

name StringName

value Variant

set_notify_local_transform(bool)

If enable is true, this node will receive NOTIFICATION_LOCAL_TRANSFORM_CHANGED when its local transform changes.

void set_notify_local_transform(bool enable)

Parameters

enable bool

set_notify_transform(bool)

If enable is true, this node will receive NOTIFICATION_TRANSFORM_CHANGED when its global transform changes.

void set_notify_transform(bool enable)

Parameters

enable bool

set_visibility_layer_bit(int, bool)

Set/clear individual bits on the rendering visibility layer. This simplifies editing this CanvasItem's visibility layer.

void set_visibility_layer_bit(int layer, bool enabled)

Parameters

layer int

enabled bool

show

Show the CanvasItem if it's currently hidden. This is equivalent to setting visible to true. For controls that inherit Popup, the correct way to make them visible is to call one of the multiple popup*() functions instead.

void show

Events

draw

Emitted when the CanvasItem must redraw, after the related NOTIFICATION_DRAW notification, and before _draw is called.

Note: Deferred connections do not allow drawing through the draw_* methods.

signal draw

hidden

Emitted when the CanvasItem is hidden, i.e. it's no longer visible in the tree (see is_visible_in_tree).

signal hidden

item_rect_changed

Emitted when the CanvasItem's boundaries (position or size) change, or when an action took place that may have affected these boundaries (e.g. changing texture).

signal item_rect_changed

visibility_changed

Emitted when the CanvasItem's visibility changes, either because its own visible property changed or because its visibility in the tree changed (see is_visible_in_tree).

signal visibility_changed