Up to date

This page is up to date for Godot 4.1. If you still find outdated information, please open an issue.

GraphEdit

Inherits: Control < CanvasItem < Node < Object

An editor for graph-like structures, using GraphNodes.

Description

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 close 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 OS.low_processor_usage_mode) when using GraphEdits.

Properties

bool

arrange_nodes_button_hidden

false

bool

clip_contents

true (overrides Control)

bool

connection_lines_antialiased

true

float

connection_lines_curvature

0.5

float

connection_lines_thickness

2.0

FocusMode

focus_mode

2 (overrides Control)

bool

minimap_enabled

true

float

minimap_opacity

0.65

Vector2

minimap_size

Vector2(240, 160)

PanningScheme

panning_scheme

0

bool

right_disconnects

false

Vector2

scroll_offset

Vector2(0, 0)

bool

show_zoom_label

false

int

snap_distance

20

bool

use_snap

true

float

zoom

1.0

float

zoom_max

2.0736

float

zoom_min

0.232568

float

zoom_step

1.2

Methods

PackedVector2Array

_get_connection_line ( Vector2 from_position, Vector2 to_position ) virtual const

bool

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

bool

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

bool

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

void

add_valid_connection_type ( int from_type, int to_type )

void

add_valid_left_disconnect_type ( int type )

void

add_valid_right_disconnect_type ( int type )

void

arrange_nodes ( )

void

clear_connections ( )

Error

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

void

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

void

force_connection_drag_end ( )

PackedVector2Array

get_connection_line ( Vector2 from_node, Vector2 to_node )

Dictionary[]

get_connection_list ( ) const

HBoxContainer

get_zoom_hbox ( )

bool

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

bool

is_valid_connection_type ( int from_type, int to_type ) const

void

remove_valid_connection_type ( int from_type, int to_type )

void

remove_valid_left_disconnect_type ( int type )

void

remove_valid_right_disconnect_type ( int type )

void

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

void

set_selected ( Node node )

Theme Properties

Color

activity

Color(1, 1, 1, 1)

Color

grid_major

Color(1, 1, 1, 0.2)

Color

grid_minor

Color(1, 1, 1, 0.05)

Color

selection_fill

Color(1, 1, 1, 0.3)

Color

selection_stroke

Color(1, 1, 1, 0.8)

int

port_hotzone_inner_extent

22

int

port_hotzone_outer_extent

26

Texture2D

layout

Texture2D

minimap

Texture2D

minus

Texture2D

more

Texture2D

reset

Texture2D

snap

StyleBox

bg

Signals

begin_node_move ( )

Emitted at the beginning of a GraphNode movement.

connection_drag_ended ( )

Emitted at the end of a connection drag.

connection_drag_started ( StringName from_node, int from_port, bool is_output )

Emitted at the beginning of a connection drag.

connection_from_empty ( StringName to_node, int to_port, Vector2 release_position )

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

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

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.

connection_to_empty ( StringName from_node, int from_port, Vector2 release_position )

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

copy_nodes_request ( )

Emitted when the user presses Ctrl + C.

delete_nodes_request ( StringName[] nodes )

Emitted when a GraphNode is attempted to be removed from the GraphEdit. Provides a list of node names to be removed (all selected nodes, excluding nodes without closing button).

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

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.

duplicate_nodes_request ( )

Emitted when a GraphNode is attempted to be duplicated in the GraphEdit.

end_node_move ( )

Emitted at the end of a GraphNode movement.

node_deselected ( Node node )

There is currently no description for this signal. Please help us by contributing one!

node_selected ( Node node )

Emitted when a GraphNode is selected.

paste_nodes_request ( )

Emitted when the user presses Ctrl + V.

popup_request ( Vector2 position )

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

scroll_offset_changed ( Vector2 offset )

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

Enumerations

enum PanningScheme:

PanningScheme SCROLL_ZOOMS = 0

Mouse Wheel will zoom, Ctrl + Mouse Wheel will move the view.

PanningScheme SCROLL_PANS = 1

Mouse Wheel will move the view, Ctrl + Mouse Wheel will zoom.

Property Descriptions

bool arrange_nodes_button_hidden = false

  • void set_arrange_nodes_button_hidden ( bool value )

  • bool is_arrange_nodes_button_hidden ( )

If true, the Arrange Nodes button is hidden.

bool connection_lines_antialiased = true

  • void set_connection_lines_antialiased ( bool value )

  • bool is_connection_lines_antialiased ( )

If true, the lines between nodes will use antialiasing.

float connection_lines_curvature = 0.5

  • void set_connection_lines_curvature ( float value )

  • float get_connection_lines_curvature ( )

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

float connection_lines_thickness = 2.0

  • void set_connection_lines_thickness ( float value )

  • float get_connection_lines_thickness ( )

The thickness of the lines between the nodes.

bool minimap_enabled = true

  • void set_minimap_enabled ( bool value )

  • bool is_minimap_enabled ( )

If true, the minimap is visible.

float minimap_opacity = 0.65

  • void set_minimap_opacity ( float value )

  • float get_minimap_opacity ( )

The opacity of the minimap rectangle.

Vector2 minimap_size = Vector2(240, 160)

  • void set_minimap_size ( Vector2 value )

  • Vector2 get_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.

PanningScheme panning_scheme = 0

Defines the control scheme for panning with mouse wheel.

bool right_disconnects = false

  • void set_right_disconnects ( bool value )

  • bool is_right_disconnects_enabled ( )

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

Vector2 scroll_offset = Vector2(0, 0)

The scroll offset.

bool show_zoom_label = false

  • void set_show_zoom_label ( bool value )

  • bool is_showing_zoom_label ( )

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

int snap_distance = 20

  • void set_snap ( int value )

  • int get_snap ( )

The snapping distance in pixels.

bool use_snap = true

  • void set_use_snap ( bool value )

  • bool is_using_snap ( )

If true, enables snapping.

float zoom = 1.0

  • void set_zoom ( float value )

  • float get_zoom ( )

The current zoom value.

float zoom_max = 2.0736

  • void set_zoom_max ( float value )

  • float get_zoom_max ( )

The upper zoom limit.

float zoom_min = 0.232568

  • void set_zoom_min ( float value )

  • float get_zoom_min ( )

The lower zoom limit.

float zoom_step = 1.2

  • void set_zoom_step ( float value )

  • float get_zoom_step ( )

The step of each zoom level.

Method Descriptions

PackedVector2Array _get_connection_line ( Vector2 from_position, Vector2 to_position ) virtual const

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

bool _is_in_input_hotzone ( Object in_node, int in_port, Vector2 mouse_position ) 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_connection_input_position(in_port) (For output's case, call GraphNode.get_connection_output_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 = Vector2(get_theme_constant("port_grab_distance_horizontal"), get_theme_constant("port_grab_distance_vertical"))
    var port_pos: Vector2 = in_node.get_position() + in_node.get_connection_input_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 ) virtual

Returns whether the mouse_position is in the output hot zone. For more information on hot zones, see _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 = Vector2(get_theme_constant("port_grab_distance_horizontal"), get_theme_constant("port_grab_distance_vertical"))
    var port_pos: Vector2 = in_node.get_position() + in_node.get_connection_output_position(in_port) - port_size / 2
    var rect = Rect2(port_pos, port_size)

    return rect.has_point(mouse_position)

bool _is_node_hover_valid ( StringName from_node, int from_port, StringName to_node, int to_port ) 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