559 lines
14 KiB
Markdown
559 lines
14 KiB
Markdown
# 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`：主窗口ID
|
||
- `INVALID_WINDOW_ID = -1`：无效窗口ID
|
||
|
||
---
|
||
|
||
## 枚举
|
||
|
||
### Feature
|
||
系统功能支持检测枚举，包含多种功能如子窗口、触屏、鼠标、剪贴板、虚拟键盘等支持检测。
|
||
|
||
### MouseMode
|
||
鼠标模式枚举：可见、隐藏、捕获、限制等模式。
|
||
|
||
### ScreenOrientation
|
||
屏幕朝向枚举：横屏、竖屏及其反向，以及传感器自动模式。
|
||
|
||
### VirtualKeyboardType
|
||
虚拟键盘类型：默认、多行、数字、小数、电话、邮箱、密码、URL等。
|
||
|
||
### CursorShape
|
||
光标形状枚举：箭头、工字形、指向手形等多种光标样式。
|
||
|
||
### WindowFlags
|
||
窗口标志枚举：控制窗口的各种行为和外观属性。
|
||
|
||
### WindowMode
|
||
窗口模式枚举：窗口、最小化、最大化、全屏等模式。
|
||
|
||
### HandleType
|
||
句柄类型枚举：用于获取不同类型的原生窗口句柄。
|
||
|
||
### VSyncMode
|
||
垂直同步模式枚举：控制画面撕裂和帧率同步。
|
||
|
||
### TTSUtteranceEvent
|
||
语音朗读事件枚举：开始、结束、取消、边界等事件。
|
||
|
||
---
|
||
|
||
> **注意**：此文档已排除所有已弃用的方法。某些功能可能仅在特定平台上可用，请参考原始文档中的平台支持说明。 |