14 KiB
14 KiB
DisplayServer API 参考文档
类简介
继承：Object
DisplayServer 是用于低阶窗口管理的服务器接口。所有与窗口管理相关的内容都由 DisplayServer（显示服务器）处理。
无头模式：如果使用
--headless命令行参数启动引擎，就会禁用所有渲染和窗口管理功能，此时 DisplayServer 的大多数函数都会返回虚设值。
方法列表
🔔 系统交互
void beep()
发出系统提示音。
void enable_for_stealing_focus(process_id: int)
允许指定进程获取焦点。
void force_process_and_drop_events()
强制处理并丢弃所有事件。
📋 剪贴板操作
String clipboard_get()
获取剪贴板文本内容。
Image clipboard_get_image()
获取剪贴板图像内容。
String clipboard_get_primary()
获取主剪贴板文本内容（仅限 Linux）。
bool clipboard_has()
检查剪贴板是否有内容。
bool clipboard_has_image()
检查剪贴板是否有图像。
void clipboard_set(clipboard: String)
设置剪贴板文本内容。
void clipboard_set_primary(clipboard_primary: String)
设置主剪贴板文本内容（仅限 Linux）。
🖱️ 鼠标和光标
CursorShape cursor_get_shape()
获取当前光标形状。
void cursor_set_custom_image(cursor: Resource, shape: CursorShape = 0, hotspot: Vector2 = Vector2(0, 0))
设置自定义光标图像。
void cursor_set_shape(shape: CursorShape)
设置光标形状。
BitField[MouseButtonMask] mouse_get_button_state()
获取鼠标按键状态。
MouseMode mouse_get_mode()
获取鼠标模式。
Vector2i mouse_get_position()
获取鼠标位置。
void mouse_set_mode(mouse_mode: MouseMode)
设置鼠标模式。
void warp_mouse(position: Vector2i)
将鼠标光标移动到指定位置。
💬 对话框
Error dialog_input_text(title: String, description: String, existing_text: String, callback: Callable)
显示文本输入对话框。
Error dialog_show(title: String, description: String, buttons: PackedStringArray, callback: Callable)
显示系统对话框。
Error file_dialog_show(title: String, current_directory: String, filename: String, show_hidden: bool, mode: FileDialogMode, filters: PackedStringArray, callback: Callable)
显示文件选择对话框。
Error file_dialog_with_options_show(title: String, current_directory: String, root: String, filename: String, show_hidden: bool, mode: FileDialogMode, filters: PackedStringArray, options: Array[Dictionary], callback: Callable)
显示带扩展选项的文件选择对话框。
🎨 主题和颜色
Color get_accent_color()
获取系统强调色。
Color get_base_color()
获取系统基础色。
bool is_dark_mode()
检查系统是否为深色模式。
bool is_dark_mode_supported()
检查系统是否支持深色模式。
void set_system_theme_change_callback(callable: Callable)
设置系统主题变化时的回调。
📱 显示和屏幕
Array[Rect2] get_display_cutouts()
获取显示器刘海信息。
Rect2i get_display_safe_area()
获取显示器安全区域。
int get_keyboard_focus_screen()
获取键盘焦点所在屏幕。
String get_name()
获取显示服务器名称。
int get_primary_screen()
获取主屏幕索引。
int get_screen_count()
获取屏幕数量。
int get_screen_from_rect(rect: Rect2)
根据矩形位置获取屏幕索引。
bool get_swap_cancel_ok()
获取是否交换确定取消按钮。
int get_window_at_screen_position(position: Vector2i)
获取指定屏幕位置的窗口ID。
PackedInt32Array get_window_list()
获取所有窗口ID列表。
🖥️ 屏幕操作
int screen_get_dpi(screen: int = -1)
获取屏幕DPI。
Image screen_get_image(screen: int = -1)
获取屏幕截图。
Image screen_get_image_rect(rect: Rect2i)
获取屏幕指定区域截图。
float screen_get_max_scale()
获取所有屏幕的最大缩放系数。
ScreenOrientation screen_get_orientation(screen: int = -1)
获取屏幕朝向。
Color screen_get_pixel(position: Vector2i)
获取指定位置的像素颜色。
Vector2i screen_get_position(screen: int = -1)
获取屏幕位置。
float screen_get_refresh_rate(screen: int = -1)
获取屏幕刷新率。
float screen_get_scale(screen: int = -1)
获取屏幕缩放系数。
Vector2i screen_get_size(screen: int = -1)
获取屏幕大小。
Rect2i screen_get_usable_rect(screen: int = -1)
获取屏幕可用区域。
bool screen_is_kept_on()
检查屏幕是否保持开启。
void screen_set_keep_on(enable: bool)
设置屏幕保持开启。
void screen_set_orientation(orientation: ScreenOrientation, screen: int = -1)
设置屏幕朝向。
🖼️ 图标设置
void set_icon(image: Image)
设置窗口图标。
void set_native_icon(filename: String)
使用原生格式设置窗口图标。
💾 输出管理
bool has_additional_outputs()
检查是否有额外输出设备。
void register_additional_output(object: Object)
注册额外输出设备。
void unregister_additional_output(object: Object)
取消注册额外输出设备。
⚡ 功能检测
bool has_feature(feature: Feature)
检查是否支持指定功能。
bool has_hardware_keyboard()
检查是否有硬件键盘。
bool is_touchscreen_available()
检查是否支持触屏。
bool is_window_transparency_available()
检查是否支持窗口透明。
⌨️ 键盘
int keyboard_get_current_layout()
获取当前键盘布局。
Key keyboard_get_keycode_from_physical(keycode: Key)
从物理按键获取键码。
Key keyboard_get_label_from_physical(keycode: Key)
从物理按键获取标签。
int keyboard_get_layout_count()
获取键盘布局数量。
String keyboard_get_layout_language(index: int)
获取键盘布局语言。
String keyboard_get_layout_name(index: int)
获取键盘布局名称。
void keyboard_set_current_layout(index: int)
设置当前键盘布局。
📝 输入法
Vector2i ime_get_selection()
获取输入法选中范围。
String ime_get_text()
获取输入法文本。
🎯 状态指示器
int create_status_indicator(icon: Texture2D, tooltip: String, callback: Callable)
创建状态指示器。
void delete_status_indicator(id: int)
删除状态指示器。
Rect2 status_indicator_get_rect(id: int)
获取状态指示器位置。
void status_indicator_set_callback(id: int, callback: Callable)
设置状态指示器回调。
void status_indicator_set_icon(id: int, icon: Texture2D)
设置状态指示器图标。
void status_indicator_set_menu(id: int, menu_rid: RID)
设置状态指示器菜单。
void status_indicator_set_tooltip(id: int, tooltip: String)
设置状态指示器提示文本。
📱 数位板
String tablet_get_current_driver()
获取当前数位板驱动。
int tablet_get_driver_count()
获取数位板驱动数量。
String tablet_get_driver_name(idx: int)
获取数位板驱动名称。
void tablet_set_current_driver(name: String)
设置数位板驱动。
🗣️ 文本转语音
Array[Dictionary] tts_get_voices()
获取语音列表。
PackedStringArray tts_get_voices_for_language(language: String)
获取指定语言的语音列表。
bool tts_is_paused()
检查是否暂停。
bool tts_is_speaking()
检查是否正在朗读。
void tts_pause()
暂停朗读。
void tts_resume()
恢复朗读。
void tts_set_utterance_callback(event: TTSUtteranceEvent, callable: Callable)
设置朗读事件回调。
void tts_speak(text: String, voice: String, volume: int = 50, pitch: float = 1.0, rate: float = 1.0, utterance_id: int = 0, interrupt: bool = false)
开始朗读文本。
void tts_stop()
停止朗读。
⌨️ 虚拟键盘
int virtual_keyboard_get_height()
获取虚拟键盘高度。
void virtual_keyboard_hide()
隐藏虚拟键盘。
void virtual_keyboard_show(existing_text: String, position: Rect2 = Rect2(0, 0, 0, 0), type: VirtualKeyboardType = 0, max_length: int = -1, cursor_start: int = -1, cursor_end: int = -1)
显示虚拟键盘。
🪟 窗口管理
bool window_can_draw(window_id: int = 0)
检查窗口是否可绘制。
int window_get_active_popup()
获取活动弹出窗口ID。
int window_get_attached_instance_id(window_id: int = 0)
获取窗口附加的实例ID。
int window_get_current_screen(window_id: int = 0)
获取窗口所在屏幕。
bool window_get_flag(flag: WindowFlags, window_id: int = 0)
获取窗口标志。
Vector2i window_get_max_size(window_id: int = 0)
获取窗口最大尺寸。
Vector2i window_get_min_size(window_id: int = 0)
获取窗口最小尺寸。
WindowMode window_get_mode(window_id: int = 0)
获取窗口模式。
int window_get_native_handle(handle_type: HandleType, window_id: int = 0)
获取窗口原生句柄。
Rect2i window_get_popup_safe_rect(window: int)
获取弹出窗口安全区域。
Vector2i window_get_position(window_id: int = 0)
获取窗口位置。
Vector2i window_get_position_with_decorations(window_id: int = 0)
获取窗口位置（含边框）。
Vector3i window_get_safe_title_margins(window_id: int = 0)
获取标题栏安全边距。
Vector2i window_get_size(window_id: int = 0)
获取窗口大小。
Vector2i window_get_size_with_decorations(window_id: int = 0)
获取窗口大小（含边框）。
Vector2i window_get_title_size(title: String, window_id: int = 0)
获取标题栏大小。
VSyncMode window_get_vsync_mode(window_id: int = 0)
获取垂直同步模式。
bool window_is_focused(window_id: int = 0)
检查窗口是否有焦点。
bool window_is_maximize_allowed(window_id: int = 0)
检查窗口是否可最大化。
bool window_maximize_on_title_dbl_click()
检查双击标题栏是否最大化。
bool window_minimize_on_title_dbl_click()
检查双击标题栏是否最小化。
void window_move_to_foreground(window_id: int = 0)
将窗口移到前台。
void window_request_attention(window_id: int = 0)
请求窗口注意。
void window_set_current_screen(screen: int, window_id: int = 0)
设置窗口所在屏幕。
void window_set_drop_files_callback(callback: Callable, window_id: int = 0)
设置文件拖放回调。
void window_set_exclusive(window_id: int, exclusive: bool)
设置窗口独占模式。
void window_set_flag(flag: WindowFlags, enabled: bool, window_id: int = 0)
设置窗口标志。
void window_set_ime_active(active: bool, window_id: int = 0)
设置输入法是否激活。
void window_set_ime_position(position: Vector2i, window_id: int = 0)
设置输入法位置。
void window_set_input_event_callback(callback: Callable, window_id: int = 0)
设置输入事件回调。
void window_set_input_text_callback(callback: Callable, window_id: int = 0)
设置文本输入回调。
void window_set_max_size(max_size: Vector2i, window_id: int = 0)
设置窗口最大尺寸。
void window_set_min_size(min_size: Vector2i, window_id: int = 0)
设置窗口最小尺寸。
void window_set_mode(mode: WindowMode, window_id: int = 0)
设置窗口模式。
void window_set_mouse_passthrough(region: PackedVector2Array, window_id: int = 0)
设置鼠标穿透区域。
void window_set_popup_safe_rect(window: int, rect: Rect2i)
设置弹出窗口安全区域。
void window_set_position(position: Vector2i, window_id: int = 0)
设置窗口位置。
void window_set_rect_changed_callback(callback: Callable, window_id: int = 0)
设置窗口位置大小变化回调。
void window_set_size(size: Vector2i, window_id: int = 0)
设置窗口大小。
void window_set_title(title: String, window_id: int = 0)
设置窗口标题。
void window_set_transient(window_id: int, parent_window_id: int)
设置窗口为瞬态。
void window_set_vsync_mode(vsync_mode: VSyncMode, window_id: int = 0)
设置垂直同步模式。
void window_set_window_buttons_offset(offset: Vector2i, window_id: int = 0)
设置窗口按钮偏移。
void window_set_window_event_callback(callback: Callable, window_id: int = 0)
设置窗口事件回调。
void window_start_drag(window_id: int = 0)
开始拖拽窗口。
void window_start_resize(edge: WindowResizeEdge, window_id: int = 0)
开始调整窗口大小。
📞 帮助系统
void help_set_search_callbacks(search_callback: Callable, action_callback: Callable)
设置帮助系统搜索回调。
void show_emoji_and_symbol_picker()
显示表情符号选择器。
⚙️ 事件处理
void process_events()
处理事件。
常量
SCREEN_WITH_MOUSE_FOCUS = -4：鼠标焦点所在屏幕SCREEN_WITH_KEYBOARD_FOCUS = -3：键盘焦点所在屏幕SCREEN_PRIMARY = -2：主屏幕SCREEN_OF_MAIN_WINDOW = -1：主窗口所在屏幕MAIN_WINDOW_ID = 0：主窗口IDINVALID_WINDOW_ID = -1：无效窗口ID
枚举
Feature
系统功能支持检测枚举，包含多种功能如子窗口、触屏、鼠标、剪贴板、虚拟键盘等支持检测。
MouseMode
鼠标模式枚举：可见、隐藏、捕获、限制等模式。
ScreenOrientation
屏幕朝向枚举：横屏、竖屏及其反向，以及传感器自动模式。
VirtualKeyboardType
虚拟键盘类型：默认、多行、数字、小数、电话、邮箱、密码、URL等。
CursorShape
光标形状枚举：箭头、工字形、指向手形等多种光标样式。
WindowFlags
窗口标志枚举：控制窗口的各种行为和外观属性。
WindowMode
窗口模式枚举：窗口、最小化、最大化、全屏等模式。
HandleType
句柄类型枚举：用于获取不同类型的原生窗口句柄。
VSyncMode
垂直同步模式枚举：控制画面撕裂和帧率同步。
TTSUtteranceEvent
语音朗读事件枚举：开始、结束、取消、边界等事件。
注意：此文档已排除所有已弃用的方法。某些功能可能仅在特定平台上可用，请参考原始文档中的平台支持说明。