GraphEdit

实验性： This class may be changed or removed in future versions.

继承： Control < CanvasItem < Node < Object

图结构编辑器，使用 GraphNode。

描述

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 OS.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.

属性

方法

主题属性

信号

begin_node_move() 🔗

在 GraphElement 移动开始时发出。

connection_drag_ended() 🔗

在连接拖动结束时发出。

connection_drag_started(from_node: StringName, from_port: int, is_output: bool) 🔗

在连接拖动开始时发出。

connection_from_empty(to_node: StringName, to_port: int, release_position: Vector2) 🔗

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

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

当尝试创建 from_node GraphNode 的 from_port 和 to_node GraphNode 的 to_port 之间的连接时发出。

connection_to_empty(from_node: StringName, from_port: int, release_position: Vector2) 🔗

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

copy_nodes_request() 🔗

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

delete_nodes_request(nodes: Array[StringName]) 🔗

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

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

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

当试图移除 from_node GraphNode 的 from_port 和 to_node GraphNode 的 to_port 之间的连接时发出。

duplicate_nodes_request() 🔗

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

end_node_move() 🔗

在 GraphElement 移动结束时发出。

frame_rect_changed(frame: GraphFrame, new_rect: Vector2) 🔗

当 GraphFrame frame 大小调整为 new_rect 时发出。

graph_elements_linked_to_frame_request(elements: Array, frame: StringName) 🔗

当一个或多个 GraphElement 被放到名为 frame 的 GraphFrame 上，且它们之前未被附加到任何其他框中时发出。

elements 是要附加的 GraphElement 数组。

node_deselected(node: Node) 🔗

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

node_selected(node: Node) 🔗

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

paste_nodes_request() 🔗

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

popup_request(at_position: Vector2) 🔗

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

scroll_offset_changed(offset: Vector2) 🔗

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

枚举

enum PanningScheme: 🔗

PanningScheme SCROLL_ZOOMS = 0

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

PanningScheme SCROLL_PANS = 1

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

enum GridPattern: 🔗

GridPattern GRID_PATTERN_LINES = 0

使用实线绘制网格。

GridPattern GRID_PATTERN_DOTS = 1

使用点线绘制网格。

属性说明

bool connection_lines_antialiased = true 🔗

• void set_connection_lines_antialiased(value: bool)

• bool is_connection_lines_antialiased()

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

float connection_lines_curvature = 0.5 🔗

• void set_connection_lines_curvature(value: float)

• float get_connection_lines_curvature()

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

float connection_lines_thickness = 4.0 🔗

• void set_connection_lines_thickness(value: float)

• float get_connection_lines_thickness()

节点之间连线的粗细。

GridPattern grid_pattern = 0 🔗

• void set_grid_pattern(value: GridPattern)

• GridPattern get_grid_pattern()

绘制网格时使用的图案。

bool minimap_enabled = true 🔗

• void set_minimap_enabled(value: bool)

• bool is_minimap_enabled()

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

float minimap_opacity = 0.65 🔗

• void set_minimap_opacity(value: float)

• float get_minimap_opacity()

小图矩形的不透明度。

Vector2 minimap_size = Vector2(240, 160) 🔗

• void set_minimap_size(value: Vector2)

• Vector2 get_minimap_size()

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

PanningScheme panning_scheme = 0 🔗

• void set_panning_scheme(value: PanningScheme)

• PanningScheme get_panning_scheme()

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

bool right_disconnects = false 🔗

• void set_right_disconnects(value: bool)

• bool is_right_disconnects_enabled()

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

Vector2 scroll_offset = Vector2(0, 0) 🔗

• void set_scroll_offset(value: Vector2)

• Vector2 get_scroll_offset()

滚动偏移量。

bool show_arrange_button = true 🔗

• void set_show_arrange_button(value: bool)

• bool is_showing_arrange_button()

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

bool show_grid = true 🔗

• void set_show_grid(value: bool)

• bool is_showing_grid()

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

bool show_grid_buttons = true 🔗

• void set_show_grid_buttons(value: bool)

• bool is_showing_grid_buttons()

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

bool show_menu = true 🔗

• void set_show_menu(value: bool)

• bool is_showing_menu()

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

bool show_minimap_button = true 🔗

• void set_show_minimap_button(value: bool)

• bool is_showing_minimap_button()

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

bool show_zoom_buttons = true 🔗

• void set_show_zoom_buttons(value: bool)

• bool is_showing_zoom_buttons()

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

bool show_zoom_label = false 🔗

• void set_show_zoom_label(value: bool)

• bool is_showing_zoom_label()

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

int snapping_distance = 20 🔗

• void set_snapping_distance(value: int)

• int get_snapping_distance()

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

bool snapping_enabled = true 🔗

• void set_snapping_enabled(value: bool)

• bool is_snapping_enabled()

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

float zoom = 1.0 🔗

• void set_zoom(value: float)

• float get_zoom()

当前缩放值。

float zoom_max = 2.0736 🔗

• void set_zoom_max(value: float)

• float get_zoom_max()

缩放上限。

float zoom_min = 0.232568 🔗

• void set_zoom_min(value: float)

• float get_zoom_min()

缩放下限。

float zoom_step = 1.2 🔗

• void set_zoom_step(value: float)

• float get_zoom_step()

每个缩放级别的步长。

方法说明

PackedVector2Array _get_connection_line(from_position: Vector2, to_position: Vector2) virtual const 🔗

可以重写的虚方法，以自定义如何绘制连接。

bool _is_in_input_hotzone(in_node: Object, in_port: int, mouse_position: Vector2) 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(in_node: Object, in_port: int, mouse_position: Vector2) 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(from_node: StringName, from_port: int, to_node: StringName, to_port: int) virtual 🔗

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

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

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

GDScriptC#

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;
}

void add_valid_connection_type(from_type: int, to_type: int) 🔗

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

另请参阅 is_valid_connection_type 和 remove_valid_connection_type。

void add_valid_left_disconnect_type(type: int) 🔗

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

void add_valid_right_disconnect_type(type: int) 🔗

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

void arrange_nodes() 🔗

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

void attach_graph_element_to_frame(element: StringName, frame: StringName) 🔗

将 element GraphElement 附加到 frame GraphFrame。

void clear_connections() 🔗

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

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

在来源 GraphNode 节点 from_node 的 from_port 端口和目标 GraphNode 节点 to_node 的 to_port 端口之间创建连接。如果已存在连接，则不会创建连接。

void detach_graph_element_from_frame(element: StringName) 🔗

将 element GraphElement 从其当前附加的 GraphFrame 中分离出来。

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

移除 from_node GraphNode 的 from_port 和 to_node GraphNode 的 to_port 之间的连接。如果该连接不存在，则不移除任何连接。

void force_connection_drag_end() 🔗

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

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

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

Array[StringName] get_attached_nodes_of_frame(frame: StringName) 🔗

返回附加到给定名称的 GraphFrame 的节点名称数组。

Dictionary get_closest_connection_at_point(point: Vector2, max_distance: float = 4.0) const 🔗

返回到屏幕空间中给定点的最近连接。如果在 max_distance 像素内未找到连接，则返回空的 Dictionary。

连接由以下形式的结构组成：{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }。

例如，可以像这样实现获取在给定鼠标位置处的连接：

GDScript

var connection = get_closest_connection_at_point(mouse_event.get_position())

PackedVector2Array get_connection_line(from_node: Vector2, to_node: Vector2) const 🔗

返回构成 from_node 和 to_node 之间的连接的点。

Array[Dictionary] get_connection_list() const 🔗

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

Array[Dictionary] get_connections_intersecting_with_rect(rect: Rect2) const 🔗

返回一个 Array，其中包含与给定 Rect2 相交的连接列表。连接由以下形式的结构组成：{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }。

GraphFrame get_element_frame(element: StringName) 🔗

返回包含给定名称的 GraphElement 的 GraphFrame。

HBoxContainer get_menu_hbox() 🔗

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

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

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

如果 from_node GraphNode 的 from_port 连接到 to_node GraphNode 的 to_port，则返回 true。

bool is_valid_connection_type(from_type: int, to_type: int) const 🔗

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

另请参阅 add_valid_connection_type 和 remove_valid_connection_type。

void remove_valid_connection_type(from_type: int, to_type: int) 🔗

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

另请参阅 is_valid_connection_type。

void remove_valid_left_disconnect_type(type: int) 🔗

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

void remove_valid_right_disconnect_type(type: int) 🔗

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

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

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

void set_selected(node: Node) 🔗

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

主题属性说明

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

根据连接的活动值插入连接线的颜色（请参阅 set_connection_activity）。

Color connection_hover_tint_color = Color(0, 0, 0, 0.3) 🔗

当鼠标悬停在连接线上时与该连接线混合的颜色。

Color connection_rim_color = Color(0.1, 0.1, 0.1, 0.6) 🔗

每条连接线周围的边缘颜色，用于使相交线更容易区分。

Color connection_valid_target_tint_color = Color(1, 1, 1, 0.4) 🔗

当前拖动的连接悬停在有效目标端口上时与该连接线混合的颜色。

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 🔗

绘制在栅格下方的背景。