Up to date

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

GraphEdit

继承: Control < CanvasItem < Node < Object

图结构编辑器,使用 GraphNode

描述

GraphEdit 提供了用于对各种图进行创建、操作、显示的工具。它在引擎中的主要目的是驱动可视化编程系统,例如可视化着色器,但也可以在用户项目中使用。

GraphEdit 本身只是一个空容器,表示一个可以放置 GraphNode 的无限栅格。每个 GraphNode 代表图中的一个节点,是连接方案中的单个数据单元。而 GraphEdit 则有助于控制节点和节点之间的各种交互。当用户尝试连接、断开或删除一个 GraphNode 时,GraphEdit 中会发出对应的信号,但默认情况下不执行任何动作。使用此控件的程序员负责实现必要的逻辑,来确定应如何处理每个请求。

性能:强烈建议在使用 GraphEdit 时启用低处理器使用模式(见 OS.low_processor_usage_mode)。

属性

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_arrange_button

true

bool

show_grid

true

bool

show_grid_buttons

true

bool

show_menu

true

bool

show_minimap_button

true

bool

show_zoom_buttons

true

bool

show_zoom_label

false

int

snapping_distance

20

bool

snapping_enabled

true

float

zoom

1.0

float

zoom_max

2.0736

float

zoom_min

0.232568

float

zoom_step

1.2

方法

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_menu_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 )

主题属性

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

grid_toggle

Texture2D

layout

Texture2D

minimap_toggle

Texture2D

snapping_toggle

Texture2D

zoom_in

Texture2D

zoom_out

Texture2D

zoom_reset

StyleBox

menu_panel

StyleBox

panel


信号

begin_node_move ( )

GraphElement 移动开始时发出。


connection_drag_ended ( )

在连接拖动结束时发出。


connection_drag_started ( StringName from_node, int from_port, bool is_output )

在连接拖动开始时发出。


connection_from_empty ( StringName to_node, int to_port, Vector2 release_position )

当用户将连接从输入端口拖动到图形的空白区域时发出。


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

当尝试创建 from_node GraphNodefrom_portto_node GraphNodeto_port 之间的连接时发出。


connection_to_empty ( StringName from_node, int from_port, Vector2 release_position )

当用户将连接从输出端口拖动到图形的空白区域时发出。


copy_nodes_request ( )

当该 GraphEdit 捕获 ui_copy 动作(默认情况下为 Ctrl + C)时发出。一般来说,该信号指示所选的 GraphElement 应被复制。


delete_nodes_request ( StringName[] nodes )

当该 GraphEdit 捕获 ui_graph_delete 动作(默认为 Delete)时触发。

nodes 是应被移除的节点的名称的数组。这些通常包括所有选定的节点。


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

当试图移除 from_node GraphNodefrom_portto_node GraphNodeto_port 之间的连接时发出。


duplicate_nodes_request ( )

当该 GraphEdit 捕获 ui_graph_duplicate 动作(默认为 Ctrl + D)时触发。一般来说,该信号指示应被复制的所选的 GraphElement


end_node_move ( )

GraphElement 移动结束时发出。


node_deselected ( Node node )

当给定的 GraphElement 节点被取消选择时发出。


node_selected ( Node node )

当给定的 GraphElement 节点被选中时发出。


paste_nodes_request ( )

当该 GraphEdit 捕获 ui_paste 动作(默认为 Ctrl + V)时触发。一般来说,该信号指示应被粘贴的先前复制的 GraphElement


popup_request ( Vector2 position )

当请求弹出窗口时发出。在 GraphEdit 中右键点击时发生。position为该信号被发出时鼠标指针的位置。


scroll_offset_changed ( Vector2 offset )

当用户改变滚动偏移量时发出。在代码中改变滚动偏移量时,它不会被触发。


枚举

enum PanningScheme:

PanningScheme SCROLL_ZOOMS = 0

鼠标滚轮进行缩放,Ctrl + 鼠标滚轮进行视图的移动。

PanningScheme SCROLL_PANS = 1

鼠标滚轮进行视图的移动,Ctrl + 鼠标滚轮进行缩放。


属性说明

bool connection_lines_antialiased = true

  • void set_connection_lines_antialiased ( bool value )

  • bool is_connection_lines_antialiased ( )

如果为 true,节点之间的线将使用抗锯齿。


float connection_lines_curvature = 0.5

  • void set_connection_lines_curvature ( float value )

  • float get_connection_lines_curvature ( )

节点之间连线的曲率。0 得到的是直线。


float connection_lines_thickness = 2.0

  • void set_connection_lines_thickness ( float value )

  • float get_connection_lines_thickness ( )

节点之间连线的粗细。


bool minimap_enabled = true

  • void set_minimap_enabled ( bool value )

  • bool is_minimap_enabled ( )

如果为 true,小图是可见的。


float minimap_opacity = 0.65

  • void set_minimap_opacity ( float value )

  • float get_minimap_opacity ( )

小图矩形的不透明度。


Vector2 minimap_size = Vector2(240, 160)

  • void set_minimap_size ( Vector2 value )

  • Vector2 get_minimap_size ( )

小图矩形的大小。地图自身基于网格区域的大小,并被缩放以适应这个矩形。


PanningScheme panning_scheme = 0

定义使用鼠标滚轮平移的控制方案。


bool right_disconnects = false

  • void set_right_disconnects ( bool value )

  • bool is_right_disconnects_enabled ( )

如果为 true,通过拖动右端,可以断开 GraphEdit 中现有的连接。


Vector2 scroll_offset = Vector2(0, 0)

  • void set_scroll_offset ( Vector2 value )

  • Vector2 get_scroll_offset ( )

滚动偏移量。


bool show_arrange_button = true

  • void set_show_arrange_button ( bool value )

  • bool is_showing_arrange_button ( )

如果为 true,则自动排列图形节点的按钮可见。


bool show_grid = true

  • void set_show_grid ( bool value )

  • bool is_showing_grid ( )

如果为 true,则该网格可见。


bool show_grid_buttons = true

  • void set_show_grid_buttons ( bool value )

  • bool is_showing_grid_buttons ( )

如果为 true,则允许配置栅格和吸附选项的按钮可见。


bool show_menu = true

  • void set_show_menu ( bool value )

  • bool is_showing_menu ( )

如果为 true,则菜单栏可见。


bool show_minimap_button = true

  • void set_show_minimap_button ( bool value )

  • bool is_showing_minimap_button ( )

如果为 true,则切换小地图的按钮可见。


bool show_zoom_buttons = true

  • void set_show_zoom_buttons ( bool value )

  • bool is_showing_zoom_buttons ( )

如果为 true,则允许更改和重置缩放级别的按钮可见。


bool show_zoom_label = false

  • void set_show_zoom_label ( bool value )

  • bool is_showing_zoom_label ( )

如果为 true,则使带有当前缩放级别的标签可见。缩放级别以百分比显示。


int snapping_distance = 20

  • void set_snapping_distance ( int value )

  • int get_snapping_distance ( )

吸附距离,单位为像素,也决定了栅格线距离。


bool snapping_enabled = true

  • void set_snapping_enabled ( bool value )

  • bool is_snapping_enabled ( )

如果为 true,启用自动吸附。


float zoom = 1.0

  • void set_zoom ( float value )

  • float get_zoom ( )

当前缩放值。


float zoom_max = 2.0736

  • void set_zoom_max ( float value )

  • float get_zoom_max ( )

缩放上限。


float zoom_min = 0.232568

  • void set_zoom_min ( float value )

  • float get_zoom_min ( )

缩放下限。


float zoom_step = 1.2

  • void set_zoom_step ( float value )

  • float get_zoom_step ( )

每个缩放级别的步长。


方法说明

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

返回 mouse_position 是否在输入热区。

默认情况下,热区是一个 Rect2,其中心位于 in_node.GraphNode.get_input_port_position(in_port)(对于输出的情况,请改为调用 GraphNode.get_output_port_position)。热区的宽度是主题属性 port_grab_distance_horizontal 的两倍,高度是 port_grab_distance_vertical 的两倍。

下面是一个示例代码,以帮助入门:

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_input_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 ) virtual

返回 mouse_position 是否在输出热区。有关热区的更多信息,请参阅 _is_in_input_hotzone

下面是一个示例代码,以帮助入门:

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_output_port_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

当用户在有效端口上拖动连接时,该虚拟方法可用于插入额外的错误检测。

如果连接确实有效,则返回 true;如果连接不可能,则返回 false。如果连接是不可能的,则不会捕捉到该端口,因此不会发起对该端口的连接请求。

在该示例中,抑制了与同一节点的连接:

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

void add_valid_connection_type ( int from_type, int to_type )

允许两种不同端口类型之间的连接。端口类型是使用 GraphNode.set_slot 方法为每个插槽的左右端口单独定义的。

另请参阅 is_valid_connection_typeremove_valid_connection_type


void add_valid_left_disconnect_type ( int type )

如果 GraphNode 插槽的左侧端口具有指定的类型,则允许在从该端口拖动时断开节点。另请参阅 remove_valid_left_disconnect_type


void add_valid_right_disconnect_type ( int type )

如果 GraphNode 插槽的右侧端口具有指定的类型,则允许在从该端口拖动时断开节点。另请参阅 remove_valid_right_disconnect_type


void arrange_nodes ( )

重新排列布局中的选定节点,使连接之间的交叉最少,节点之间的水平和垂直间隙保持一致。


void clear_connections ( )

移除节点之间的所有连接。


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

在来源 GraphNode 节点 from_nodefrom_port 端口和目标 GraphNode 节点 to_nodeto_port 端口之间创建连接。如果已存在连接,则不会创建连接。


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

移除 from_node GraphNodefrom_portto_node GraphNodeto_port 之间的连接。如果该连接不存在,则不移除任何连接。


void force_connection_drag_end ( )

结束当前连接的创建。换句话说,如果正在拖动一个连接,可以使用该方法中止该过程,并移除鼠标光标后面的线。

这最好与 connection_drag_startedconnection_drag_ended 一起使用,以添加自定义的行为,如通过快捷方式添加节点。

注意:该方法会抑制除 connection_drag_ended 之外的任何其他连接请求信号。


PackedVector2Array get_connection_line ( Vector2 from_node, Vector2 to_node )

返回构成 from_nodeto_node 之间的连接的点。


Dictionary[] get_connection_list ( ) const

返回包含连接列表的数组。连接由以下形式的结构组成:{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }


HBoxContainer get_menu_hbox ( )

获取包含图形左上角的缩放和网格捕捉控件的 HBoxContainer。你可以使用此方法重新定位工具栏或向其添加自定义控件。

警告:这是一个必需的内部节点,删除和释放它可能会导致崩溃。如果你希望隐藏它或其任何子项,请使用它们的 CanvasItem.visible 属性。


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

如果 from_node GraphNodefrom_port 连接到 to_node GraphNodeto_port,则返回 true


bool is_valid_connection_type ( int from_type, int to_type ) const

返回是否可以在两种不同的端口类型之间建立连接。端口类型是使用 GraphNode.set_slot 方法为每个插槽的左右端口单独定义的。

另请参阅 add_valid_connection_typeremove_valid_connection_type


void remove_valid_connection_type ( int from_type, int to_type )

不允许先前由 add_valid_connection_type 允许的两种不同端口类型之间的连接。端口类型是通过 GraphNode.set_slot 方法为每个插槽的左右端口单独定义的。

另请参阅 is_valid_connection_type


void remove_valid_left_disconnect_type ( int type )

如果 GraphNode 插槽的左侧端口具有指定类型,当从该端口拖动时,则不允许断开节点的连接。使用该方法来禁用以前使用 add_valid_left_disconnect_type 允许的断开连接。


void remove_valid_right_disconnect_type ( int type )

如果 GraphNode 插槽的右侧端口具有指定类型,当从该端口拖动时,则不允许断开节点的连接。使用该方法来禁用以前使用 add_valid_right_disconnect_type 允许的断开连接。


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

使用 activity 主题属性中提供的颜色,设置 from_nodefrom_portto_nodeto_port 之间的连接的颜色。使用 amount 作为权重,在连接颜色和活动颜色之间线性插值颜色。


void set_selected ( Node node )

将指定的 node 节点设置为选中的节点。


主题属性说明

Color activity = Color(1, 1, 1, 1)

该连接活动的颜色(请参阅 set_connection_activity)。


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 grid_toggle

网格开关按钮的图标。


Texture2D layout

用于自动排列图形的布局按钮的图标。


Texture2D minimap_toggle

小地图开关按钮的图标。


Texture2D snapping_toggle

吸附开关按钮的图标。


Texture2D zoom_in

放大按钮的图标。


Texture2D zoom_out

缩小按钮的图标。


Texture2D zoom_reset

缩放重置按钮的图标。


StyleBox menu_panel

目前没有这个主题属性的描述。请帮我们贡献一个


StyleBox panel

绘制在栅格下方的背景。