# 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

语音朗读事件枚举：开始、结束、取消、边界等事件。

  

---

  

> **注意**：此文档已排除所有已弃用的方法。某些功能可能仅在特定平台上可用，请参考原始文档中的平台支持说明。