Class GraphEdit

An editor for graph-like structures, using GraphNodes.

Inheritance: Control

CanvasItem

Node

Object

GraphEdit

Remarks

GraphEdit provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects.

GraphEdit by itself is only an empty container, representing an infinite grid where GraphNodes can be placed. Each GraphNode represents a node in the graph, a single unit of data in the connected scheme. GraphEdit, in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or delete a GraphNode, a signal is emitted in the GraphEdit, but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled.

Performance: It is greatly advised to enable low-processor usage mode (see low_processor_usage_mode) when using GraphEdits.

Note: Keep in mind that Node.get_children will also return the connection layer node named _connection_layer due to technical limitations. This behavior may change in future releases.

Properties

connection_lines_antialiased

If true, the lines between nodes will use antialiasing.

var connection_lines_antialiased : bool = true

Property Value

bool

Remarks

void set_connection_lines_antialiased(bool value)
bool is_connection_lines_antialiased

connection_lines_curvature

The curvature of the lines between the nodes. 0 results in straight lines.

var connection_lines_curvature : float = 0.5

Property Value

float

Remarks

void set_connection_lines_curvature(float value)
float get_connection_lines_curvature

connection_lines_thickness

The thickness of the lines between the nodes.

var connection_lines_thickness : float = 4.0

Property Value

float

Remarks

void set_connection_lines_thickness(float value)
float get_connection_lines_thickness

connections

The connections between GraphNodes.

A connection is represented as a Dictionary in the form of:

{
    from_node: StringName,
    from_port: int,
    to_node: StringName,
    to_port: int,
    keep_alive: bool

}

Connections with keep_alive set to false may be deleted automatically if invalid during a redraw.

var connections : Dictionary[] = []

Property Value

Dictionary[]

Remarks

void set_connections(Dictionary[] value)
Dictionary[] get_connection_list

grid_pattern

The pattern used for drawing the grid.

var grid_pattern : int = 0

Property Value

int

Remarks

void set_grid_pattern(int value)
int get_grid_pattern

minimap_enabled

If true, the minimap is visible.

var minimap_enabled : bool = true

Property Value

bool

Remarks

void set_minimap_enabled(bool value)
bool is_minimap_enabled

minimap_opacity

The opacity of the minimap rectangle.

var minimap_opacity : float = 0.65

Property Value

float

Remarks

void set_minimap_opacity(float value)
float get_minimap_opacity

minimap_size

The size of the minimap rectangle. The map itself is based on the size of the grid area and is scaled to fit this rectangle.

var minimap_size : Vector2 = Vector2(240, 160)

Property Value

Vector2

Remarks

void set_minimap_size(Vector2 value)
Vector2 get_minimap_size

panning_scheme

Defines the control scheme for panning with mouse wheel.

var panning_scheme : int = 0

Property Value

int

Remarks

void set_panning_scheme(int value)
int get_panning_scheme

right_disconnects

If true, enables disconnection of existing connections in the GraphEdit by dragging the right end.

var right_disconnects : bool = false

Property Value

bool

Remarks

void set_right_disconnects(bool value)
bool is_right_disconnects_enabled

scroll_offset

The scroll offset.

var scroll_offset : Vector2 = Vector2(0, 0)

Property Value

Vector2

Remarks

void set_scroll_offset(Vector2 value)
Vector2 get_scroll_offset

show_arrange_button

If true, the button to automatically arrange graph nodes is visible.

var show_arrange_button : bool = true

Property Value

bool

Remarks

void set_show_arrange_button(bool value)
bool is_showing_arrange_button

show_grid

If true, the grid is visible.

var show_grid : bool = true

Property Value

bool

Remarks

void set_show_grid(bool value)
bool is_showing_grid

show_grid_buttons

If true, buttons that allow to configure grid and snapping options are visible.

var show_grid_buttons : bool = true

Property Value

bool

Remarks

void set_show_grid_buttons(bool value)
bool is_showing_grid_buttons

show_menu

If true, the menu toolbar is visible.

var show_menu : bool = true

Property Value

bool

Remarks

void set_show_menu(bool value)
bool is_showing_menu

show_minimap_button

If true, the button to toggle the minimap is visible.

var show_minimap_button : bool = true

Property Value

bool

Remarks

void set_show_minimap_button(bool value)
bool is_showing_minimap_button

show_zoom_buttons

If true, buttons that allow to change and reset the zoom level are visible.

var show_zoom_buttons : bool = true

Property Value

bool

Remarks

void set_show_zoom_buttons(bool value)
bool is_showing_zoom_buttons

show_zoom_label

If true, the label with the current zoom level is visible. The zoom level is displayed in percents.

var show_zoom_label : bool = false

Property Value

bool

Remarks

void set_show_zoom_label(bool value)
bool is_showing_zoom_label

snapping_distance

The snapping distance in pixels, also determines the grid line distance.

var snapping_distance : int = 20

Property Value

int

Remarks

void set_snapping_distance(int value)
int get_snapping_distance

snapping_enabled

If true, enables snapping.

var snapping_enabled : bool = true

Property Value

bool

Remarks

void set_snapping_enabled(bool value)
bool is_snapping_enabled

zoom

The current zoom value.

var zoom : float = 1.0

Property Value

float

Remarks

void set_zoom(float value)
float get_zoom

zoom_max

The upper zoom limit.

var zoom_max : float = 2.0736

Property Value

float

Remarks

void set_zoom_max(float value)
float get_zoom_max

zoom_min

The lower zoom limit.

var zoom_min : float = 0.232568

Property Value

float

Remarks

void set_zoom_min(float value)
float get_zoom_min

zoom_step

The step of each zoom level.

var zoom_step : float = 1.2

Property Value

float

Remarks

void set_zoom_step(float value)
float get_zoom_step

activity

Theme Property

Color the connection line is interpolated to based on the activity value of a connection (see GraphEdit.set_connection_activity).

 = ``Color(1, 1, 1, 1)``

Property Value

Color

connection_hover_tint_color

Theme Property

Color which is blended with the connection line when the mouse is hovering over it.

 = ``Color(0, 0, 0, 0.3)``

Property Value

Color

connection_rim_color

Theme Property

Color of the rim around each connection line used for making intersecting lines more distinguishable.

 = ``Color(0.1, 0.1, 0.1, 0.6)``

Property Value

Color

connection_valid_target_tint_color

Theme Property

Color which is blended with the connection line when the currently dragged connection is hovering over a valid target port.

 = ``Color(1, 1, 1, 0.4)``

Property Value

Color

grid_major

Theme Property

Color of major grid lines/dots.

 = ``Color(1, 1, 1, 0.2)``

Property Value

Color

grid_minor

Theme Property

Color of minor grid lines/dots.

 = ``Color(1, 1, 1, 0.05)``

Property Value

Color

selection_fill

Theme Property

The fill color of the selection rectangle.

 = ``Color(1, 1, 1, 0.3)``

Property Value

Color

selection_stroke

Theme Property

The outline color of the selection rectangle.

 = ``Color(1, 1, 1, 0.8)``

Property Value

Color

connection_hover_thickness

Theme Property

Widen the line of the connection when the mouse is hovering over it by a percentage factor. A value of 0 disables the highlight. A value of 100 doubles the line width.

 = ``0``

Property Value

int

port_hotzone_inner_extent

Theme Property

The horizontal range within which a port can be grabbed (inner side).

 = ``22``

Property Value

int

port_hotzone_outer_extent

Theme Property

The horizontal range within which a port can be grabbed (outer side).

 = ``26``

Property Value

int

grid_toggle

Theme Property

The icon for the grid toggle button.

Texture2D grid_toggle

Property Value

Texture2D

layout

Theme Property

The icon for the layout button for auto-arranging the graph.

Texture2D layout

Property Value

Texture2D

minimap_toggle

Theme Property

The icon for the minimap toggle button.

Texture2D minimap_toggle

Property Value

Texture2D

snapping_toggle

Theme Property

The icon for the snapping toggle button.

Texture2D snapping_toggle

Property Value

Texture2D

zoom_in

Theme Property

The icon for the zoom in button.

Texture2D zoom_in

Property Value

Texture2D

zoom_out

Theme Property

The icon for the zoom out button.

Texture2D zoom_out

Property Value

Texture2D

zoom_reset

Theme Property

The icon for the zoom reset button.

Texture2D zoom_reset

Property Value

Texture2D

menu_panel

Theme Property

StyleBox menu_panel

Property Value

StyleBox

panel

Theme Property

The background drawn under the grid.

StyleBox panel

Property Value

StyleBox

Methods

_get_connection_line(Vector2, Vector2)

Qualifiers: virtualconst

Virtual method which can be overridden to customize how connections are drawn.

PackedVector2Array _get_connection_line(Vector2 from_position, Vector2 to_position)

Parameters

from_position Vector2
to_position Vector2

_is_in_input_hotzone(Object, int, Vector2)

Qualifiers: virtual

Returns whether the mouse_position is in the input hot zone.

By default, a hot zone is a Rect2 positioned such that its center is at in_node.GraphNode.get_input_port_position(in_port) (For output's case, call GraphNode.get_output_port_position instead). The hot zone's width is twice the Theme Property port_grab_distance_horizontal, and its height is twice the port_grab_distance_vertical.

Below is a sample code to help get started:

func _is_in_input_hotzone(in_node, in_port, mouse_position):
    var port_size = Vector2(get_theme_constant("port_grab_distance_horizontal"), get_theme_constant("port_grab_distance_vertical"))
    var port_pos = in_node.get_position() + in_node.get_input_port_position(in_port) - port_size / 2
    var rect = Rect2(port_pos, port_size)

    return rect.has_point(mouse_position)

bool _is_in_input_hotzone(Object in_node, int in_port, Vector2 mouse_position)

Parameters

in_node Object
in_port int
mouse_position Vector2

_is_in_output_hotzone(Object, int, Vector2)

Qualifiers: virtual

Returns whether the mouse_position is in the output hot zone. For more information on hot zones, see GraphEdit._is_in_input_hotzone.

Below is a sample code to help get started:

func _is_in_output_hotzone(in_node, in_port, mouse_position):
    var port_size = Vector2(get_theme_constant("port_grab_distance_horizontal"), get_theme_constant("port_grab_distance_vertical"))
    var port_pos = in_node.get_position() + in_node.get_output_port_position(in_port) - port_size / 2
    var rect = Rect2(port_pos, port_size)

    return rect.has_point(mouse_position)

bool _is_in_output_hotzone(Object in_node, int in_port, Vector2 mouse_position)

Parameters

in_node Object
in_port int
mouse_position Vector2

_is_node_hover_valid(StringName, int, StringName, int)

Qualifiers: virtual

This virtual method can be used to insert additional error detection while the user is dragging a connection over a valid port.

Return true if the connection is indeed valid or return false if the connection is impossible. If the connection is impossible, no snapping to the port and thus no connection request to that port will happen.

In this example a connection to same node is suppressed:

gdscript
C#

func _is_node_hover_valid(from, from_port, to, to_port):
    return from != to

public override bool _IsNodeHoverValid(StringName fromNode, int fromPort, StringName toNode, int toPort)
{
    return fromNode != toNode;

}

bool _is_node_hover_valid(StringName from_node, int from_port, StringName to_node, int to_port)

Parameters

from_node StringName
from_port int
to_node StringName
to_port int

add_valid_connection_type(int, int)

Allows the connection between two different port types. The port type is defined individually for the left and the right port of each slot with the GraphNode.set_slot method.

See also GraphEdit.is_valid_connection_type and GraphEdit.remove_valid_connection_type.

void add_valid_connection_type(int from_type, int to_type)

Parameters

from_type int
to_type int

add_valid_left_disconnect_type(int)

Allows to disconnect nodes when dragging from the left port of the GraphNode's slot if it has the specified type. See also GraphEdit.remove_valid_left_disconnect_type.

void add_valid_left_disconnect_type(int type)

Parameters

type int

add_valid_right_disconnect_type(int)

Allows to disconnect nodes when dragging from the right port of the GraphNode's slot if it has the specified type. See also GraphEdit.remove_valid_right_disconnect_type.

void add_valid_right_disconnect_type(int type)

Parameters

type int

arrange_nodes

Rearranges selected nodes in a layout with minimum crossings between connections and uniform horizontal and vertical gap between nodes.

void arrange_nodes

attach_graph_element_to_frame(StringName, StringName)

Attaches the element GraphElement to the frame GraphFrame.

void attach_graph_element_to_frame(StringName element, StringName frame)

Parameters

element StringName
frame StringName

clear_connections

Removes all connections between nodes.

void clear_connections

connect_node(StringName, int, StringName, int, bool)

Create a connection between the from_port of the from_node GraphNode and the to_port of the to_node GraphNode. If the connection already exists, no connection is created.

Connections with keep_alive set to false may be deleted automatically if invalid during a redraw.

int connect_node(StringName from_node, int from_port, StringName to_node, int to_port, bool keep_alive)

Parameters

from_node StringName
from_port int
to_node StringName
to_port int
keep_alive bool

detach_graph_element_from_frame(StringName)

Detaches the element GraphElement from the GraphFrame it is currently attached to.

void detach_graph_element_from_frame(StringName element)

Parameters

element StringName

disconnect_node(StringName, int, StringName, int)

Removes the connection between the from_port of the from_node GraphNode and the to_port of the to_node GraphNode. If the connection does not exist, no connection is removed.

void disconnect_node(StringName from_node, int from_port, StringName to_node, int to_port)

Parameters

from_node StringName
from_port int
to_node StringName
to_port int

force_connection_drag_end

Ends the creation of the current connection. In other words, if you are dragging a connection you can use this method to abort the process and remove the line that followed your cursor.

This is best used together with GraphEdit.connection_drag_started and connection_drag_ended to add custom behavior like node addition through shortcuts.

Note: This method suppresses any other connection request signals apart from connection_drag_ended.

void force_connection_drag_end

get_attached_nodes_of_frame(StringName)

Returns an array of node names that are attached to the GraphFrame with the given name.

StringName[] get_attached_nodes_of_frame(StringName frame)

Parameters

frame StringName

get_closest_connection_at_point(Vector2, float)

Qualifiers: const

Returns the closest connection to the given point in screen space. If no connection is found within max_distance pixels, an empty Dictionary is returned.

A connection is represented as a Dictionary in the form of:

{
    from_node: StringName,
    from_port: int,
    to_node: StringName,
    to_port: int,
    keep_alive: bool

}

For example, getting a connection at a given mouse position can be achieved like this:

gdscript

var connection = get_closest_connection_at_point(mouse_event.get_position())

Dictionary get_closest_connection_at_point(Vector2 point, float max_distance)

Parameters

point Vector2
max_distance float

get_connection_count(StringName, int)

Returns the number of connections from from_port of from_node.

int get_connection_count(StringName from_node, int from_port)

Parameters

from_node StringName
from_port int

get_connection_line(Vector2, Vector2)

Qualifiers: const

Returns the points which would make up a connection between from_node and to_node.

PackedVector2Array get_connection_line(Vector2 from_node, Vector2 to_node)

Parameters

from_node Vector2
to_node Vector2

get_connections_intersecting_with_rect(Rect2)

Qualifiers: const

Returns an Array containing the list of connections that intersect with the given Rect2.

A connection is represented as a Dictionary in the form of:

{
    from_node: StringName,
    from_port: int,
    to_node: StringName,
    to_port: int,
    keep_alive: bool

}

Dictionary[] get_connections_intersecting_with_rect(Rect2 rect)

Parameters

rect Rect2

get_element_frame(StringName)

Returns the GraphFrame that contains the GraphElement with the given name.

GraphFrame get_element_frame(StringName element)

Parameters

element StringName

get_menu_hbox

Gets the HBoxContainer that contains the zooming and grid snap controls in the top left of the graph. You can use this method to reposition the toolbar or to add your own custom controls to it.

Warning: This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their visible property.

HBoxContainer get_menu_hbox

is_node_connected(StringName, int, StringName, int)

Returns true if the from_port of the from_node GraphNode is connected to the to_port of the to_node GraphNode.

bool is_node_connected(StringName from_node, int from_port, StringName to_node, int to_port)

Parameters

from_node StringName
from_port int
to_node StringName
to_port int

is_valid_connection_type(int, int)

Qualifiers: const

Returns whether it's possible to make a connection between two different port types. The port type is defined individually for the left and the right port of each slot with the GraphNode.set_slot method.

See also GraphEdit.add_valid_connection_type and GraphEdit.remove_valid_connection_type.

bool is_valid_connection_type(int from_type, int to_type)

Parameters

from_type int
to_type int

remove_valid_connection_type(int, int)

Disallows the connection between two different port types previously allowed by GraphEdit.add_valid_connection_type. The port type is defined individually for the left and the right port of each slot with the GraphNode.set_slot method.

See also GraphEdit.is_valid_connection_type.

void remove_valid_connection_type(int from_type, int to_type)

Parameters

from_type int
to_type int

remove_valid_left_disconnect_type(int)

Disallows to disconnect nodes when dragging from the left port of the GraphNode's slot if it has the specified type. Use this to disable disconnection previously allowed with GraphEdit.add_valid_left_disconnect_type.

void remove_valid_left_disconnect_type(int type)

Parameters

type int

remove_valid_right_disconnect_type(int)

Disallows to disconnect nodes when dragging from the right port of the GraphNode's slot if it has the specified type. Use this to disable disconnection previously allowed with GraphEdit.add_valid_right_disconnect_type.

void remove_valid_right_disconnect_type(int type)

Parameters

type int

set_connection_activity(StringName, int, StringName, int, float)

Sets the coloration of the connection between from_node's from_port and to_node's to_port with the color provided in the activity theme property. The color is linearly interpolated between the connection color and the activity color using amount as weight.

void set_connection_activity(StringName from_node, int from_port, StringName to_node, int to_port, float amount)

Parameters

from_node StringName
from_port int
to_node StringName
to_port int
amount float

set_selected(Node)

Sets the specified node as the one selected.

void set_selected(Node node)

Parameters

node Node

Events

begin_node_move

Emitted at the beginning of a GraphElement's movement.

signal begin_node_move

connection_drag_ended

Emitted at the end of a connection drag.

signal connection_drag_ended

connection_drag_started(StringName, int, bool)

Emitted at the beginning of a connection drag.

signal connection_drag_started(StringName from_node, int from_port, bool is_output)

Parameters

from_node StringName
from_port int
is_output bool

connection_from_empty(StringName, int, Vector2)

Emitted when user drags a connection from an input port into the empty space of the graph.

signal connection_from_empty(StringName to_node, int to_port, Vector2 release_position)

Parameters

to_node StringName
to_port int
release_position Vector2

connection_request(StringName, int, StringName, int)

Emitted to the GraphEdit when the connection between the from_port of the from_node GraphNode and the to_port of the to_node GraphNode is attempted to be created.

signal connection_request(StringName from_node, int from_port, StringName to_node, int to_port)

Parameters

from_node StringName
from_port int
to_node StringName
to_port int

connection_to_empty(StringName, int, Vector2)

Emitted when user drags a connection from an output port into the empty space of the graph.

signal connection_to_empty(StringName from_node, int from_port, Vector2 release_position)

Parameters

from_node StringName
from_port int
release_position Vector2

copy_nodes_request

Emitted when this GraphEdit captures a ui_copy action (Ctrl + C by default). In general, this signal indicates that the selected GraphElements should be copied.

signal copy_nodes_request

cut_nodes_request

Emitted when this GraphEdit captures a ui_cut action (Ctrl + X by default). In general, this signal indicates that the selected GraphElements should be cut.

signal cut_nodes_request

delete_nodes_request(StringName[])

Emitted when this GraphEdit captures a ui_graph_delete action (Delete by default).

nodes is an array of node names that should be removed. These usually include all selected nodes.

signal delete_nodes_request(StringName[] nodes)

Parameters

nodes StringName[]

disconnection_request(StringName, int, StringName, int)

Emitted to the GraphEdit when the connection between from_port of from_node GraphNode and to_port of to_node GraphNode is attempted to be removed.

signal disconnection_request(StringName from_node, int from_port, StringName to_node, int to_port)

Parameters

from_node StringName
from_port int
to_node StringName
to_port int

duplicate_nodes_request

Emitted when this GraphEdit captures a ui_graph_duplicate action (Ctrl + D by default). In general, this signal indicates that the selected GraphElements should be duplicated.

signal duplicate_nodes_request

end_node_move

Emitted at the end of a GraphElement's movement.

signal end_node_move

frame_rect_changed(GraphFrame, Rect2)

Emitted when the GraphFrame frame is resized to new_rect.

signal frame_rect_changed(GraphFrame frame, Rect2 new_rect)

Parameters

frame GraphFrame
new_rect Rect2

graph_elements_linked_to_frame_request(Array, StringName)

Emitted when one or more GraphElements are dropped onto the GraphFrame named frame, when they were not previously attached to any other one.

elements is an array of GraphElements to be attached.

signal graph_elements_linked_to_frame_request(Array elements, StringName frame)

Parameters

elements Array
frame StringName

node_deselected(Node)

Emitted when the given GraphElement node is deselected.

signal node_deselected(Node node)

Parameters

node Node

node_selected(Node)

Emitted when the given GraphElement node is selected.

signal node_selected(Node node)

Parameters

node Node

paste_nodes_request

Emitted when this GraphEdit captures a ui_paste action (Ctrl + V by default). In general, this signal indicates that previously copied GraphElements should be pasted.

signal paste_nodes_request

popup_request(Vector2)

Emitted when a popup is requested. Happens on right-clicking in the GraphEdit. at_position is the position of the mouse pointer when the signal is sent.

signal popup_request(Vector2 at_position)

Parameters

at_position Vector2

scroll_offset_changed(Vector2)

Emitted when the scroll offset is changed by the user. It will not be emitted when changed in code.

signal scroll_offset_changed(Vector2 offset)

Parameters

offset Vector2

Table of Contents

Class GraphEdit

Remarks

Properties

connection_lines_antialiased

Property Value

Remarks

connection_lines_curvature

Property Value

Remarks

connection_lines_thickness

Property Value

Remarks

connections

Property Value

Remarks

grid_pattern

Property Value

Remarks

minimap_enabled

Property Value

Remarks

minimap_opacity

Property Value

Remarks

minimap_size

Property Value

Remarks

panning_scheme

Property Value

Remarks

right_disconnects

Property Value

Remarks

scroll_offset

Property Value

Remarks

show_arrange_button

Property Value

Remarks

show_grid

Property Value

Remarks

show_grid_buttons

Property Value

Remarks

show_menu

Property Value

Remarks

show_minimap_button

Property Value

Remarks

show_zoom_buttons

Property Value

Remarks

show_zoom_label

Property Value

Remarks

snapping_distance

Property Value

Remarks

snapping_enabled

Property Value

Remarks

zoom

Property Value

Remarks

zoom_max

Property Value

Remarks

zoom_min

Property Value

Remarks

zoom_step

Property Value

Remarks

activity

Property Value

connection_hover_tint_color

Property Value