DisplayServer¶
Inherits: Object
Methods¶
Enumerations¶
enum Feature:
FEATURE_GLOBAL_MENU = 0
FEATURE_SUBWINDOWS = 1
FEATURE_TOUCHSCREEN = 2
FEATURE_MOUSE = 3
FEATURE_MOUSE_WARP = 4
FEATURE_CLIPBOARD = 5
FEATURE_VIRTUAL_KEYBOARD = 6
FEATURE_CURSOR_SHAPE = 7
FEATURE_CUSTOM_CURSOR_SHAPE = 8
FEATURE_NATIVE_DIALOG = 9
FEATURE_IME = 10
FEATURE_WINDOW_TRANSPARENCY = 11
FEATURE_HIDPI = 12
FEATURE_ICON = 13
FEATURE_NATIVE_ICON = 14
FEATURE_ORIENTATION = 15
FEATURE_SWAP_BUFFERS = 16
FEATURE_CLIPBOARD_PRIMARY = 18
MOUSE_MODE_VISIBLE = 0 --- Makes the mouse cursor visible if it is hidden.
MOUSE_MODE_HIDDEN = 1 --- Makes the mouse cursor hidden if it is visible.
MOUSE_MODE_CAPTURED = 2 --- Captures the mouse. The mouse will be hidden and its position locked at the center of the screen.
Note: If you want to process the mouse's movement in this mode, you need to use InputEventMouseMotion.relative.
MOUSE_MODE_CONFINED = 3 --- Confines the mouse cursor to the game window, and make it visible.
MOUSE_MODE_CONFINED_HIDDEN = 4 --- Confines the mouse cursor to the game window, and make it hidden.
enum ScreenOrientation:
SCREEN_LANDSCAPE = 0
SCREEN_PORTRAIT = 1
SCREEN_REVERSE_LANDSCAPE = 2
SCREEN_REVERSE_PORTRAIT = 3
SCREEN_SENSOR_LANDSCAPE = 4
SCREEN_SENSOR_PORTRAIT = 5
SCREEN_SENSOR = 6
enum CursorShape:
CURSOR_ARROW = 0
CURSOR_IBEAM = 1
CURSOR_POINTING_HAND = 2
CURSOR_CROSS = 3
CURSOR_WAIT = 4
CURSOR_BUSY = 5
CURSOR_DRAG = 6
CURSOR_CAN_DROP = 7
CURSOR_FORBIDDEN = 8
CURSOR_VSIZE = 9
CURSOR_HSIZE = 10
CURSOR_BDIAGSIZE = 11
CURSOR_FDIAGSIZE = 12
CURSOR_MOVE = 13
CURSOR_VSPLIT = 14
CURSOR_HSPLIT = 15
CURSOR_HELP = 16
CURSOR_MAX = 17
enum WindowMode:
WINDOW_MODE_WINDOWED = 0
WINDOW_MODE_MINIMIZED = 1
WINDOW_MODE_MAXIMIZED = 2
WINDOW_MODE_FULLSCREEN = 3 --- Fullscreen window mode. Note that this is not exclusive fullscreen. On Windows and Linux, a borderless window is used to emulate fullscreen. On macOS, a new desktop is used to display the running project.
Regardless of the platform, enabling fullscreen will change the window size to match the monitor's size. Therefore, make sure your project supports multiple resolutions when enabling fullscreen mode.
WINDOW_MODE_EXCLUSIVE_FULLSCREEN = 4 --- Exclusive fullscreen window mode. This mode is implemented on Windows only. On other platforms, it is equivalent to WINDOW_MODE_FULLSCREEN.
Only one window in exclusive fullscreen mode can be visible on a given screen at a time. If multiple windows are in exclusive fullscreen mode for the same screen, the last one being set to this mode takes precedence.
Regardless of the platform, enabling fullscreen will change the window size to match the monitor's size. Therefore, make sure your project supports multiple resolutions when enabling fullscreen mode.
enum WindowFlags:
WINDOW_FLAG_RESIZE_DISABLED = 0 --- Window can't be resizing by dragging its resize grip. It's still possible to resize the window using window_set_size. This flag is ignored for full screen windows.
WINDOW_FLAG_BORDERLESS = 1 --- Window do not have native title bar and other decorations. This flag is ignored for full-screen windows.
WINDOW_FLAG_ALWAYS_ON_TOP = 2 --- Window is floating above other regular windows. This flag is ignored for full-screen windows.
WINDOW_FLAG_TRANSPARENT = 3 --- Window is will be destroyed with its transient parent and displayed on top of non-exclusive full-screen parent window. Transient windows can't enter full-screen mode.
WINDOW_FLAG_NO_FOCUS = 4 --- Window can't be focused. No-focus window will ignore all input, except mouse clicks.
WINDOW_FLAG_POPUP = 5 --- Window is part of menu or OptionButton dropdown. This flag can't be changed when window is visible. An active popup window will exclusivly receive all input, without stealing focus from its parent. Popup windows are automatically closed when uses click outside it, or when an application is switched. Popup window must have WINDOW_FLAG_TRANSPARENT set.
WINDOW_FLAG_MAX = 6
enum WindowEvent:
WINDOW_EVENT_MOUSE_ENTER = 0
WINDOW_EVENT_MOUSE_EXIT = 1
WINDOW_EVENT_FOCUS_IN = 2
WINDOW_EVENT_FOCUS_OUT = 3
WINDOW_EVENT_CLOSE_REQUEST = 4
WINDOW_EVENT_GO_BACK_REQUEST = 5
WINDOW_EVENT_DPI_CHANGE = 6
enum VSyncMode:
VSYNC_DISABLED = 0 --- No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible).
VSYNC_ENABLED = 1 --- Default vertical synchronization mode, the image is displayed only on vertical blanking intervals (no tearing is visible).
VSYNC_ADAPTIVE = 2 --- Behaves like VSYNC_DISABLED when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible), otherwise vertical synchronization is enabled to avoid tearing.
VSYNC_MAILBOX = 3 --- Displays the most recent image in the queue on vertical blanking intervals, while rendering to the other images (no tearing is visible).
Although not guaranteed, the images can be rendered as fast as possible, which may reduce input lag.
enum HandleType:
DISPLAY_HANDLE = 0 --- Display handle:
Linux:
X11::Display*
for the display.WINDOW_HANDLE = 1 --- Window handle:
Windows:
HWND
for the window.Linux:
X11::Window*
for the window.MacOS:
NSWindow*
for the window.iOS:
UIViewController*
for the view controller.Android:
jObject
for the activity.WINDOW_VIEW = 2 --- Window view:
MacOS:
NSView*
for the window main view.iOS:
UIView*
for the window main view.
Constants¶
SCREEN_OF_MAIN_WINDOW = -1
MAIN_WINDOW_ID = 0
INVALID_WINDOW_ID = -1
Method Descriptions¶
String clipboard_get ( ) const
Returns the user's clipboard as a string if possible.
String clipboard_get_primary ( ) const
Returns the user's primary clipboard as a string if possible.
Note: This method is only implemented on Linux.
bool clipboard_has ( ) const
Returns true
if there is content on the user's clipboard.
void clipboard_set ( String clipboard )
Sets the user's clipboard content to the given string.
void clipboard_set_primary ( String clipboard_primary )
Sets the user's primary clipboard content to the given string.
Note: This method is only implemented on Linux.
int create_sub_window ( WindowMode mode, VSyncMode vsync_mode, int flags, Rect2i rect=Rect2i(0, 0, 0, 0) )
CursorShape cursor_get_shape ( ) const
void cursor_set_custom_image ( Resource cursor, CursorShape shape=0, Vector2 hotspot=Vector2(0, 0) )
void cursor_set_shape ( CursorShape shape )
void delete_sub_window ( int window_id )
Error dialog_input_text ( String title, String description, String existing_text, Callable callback )
Error dialog_show ( String title, String description, PackedStringArray buttons, Callable callback )
void enable_for_stealing_focus ( int process_id )
void force_process_and_drop_events ( )
String get_name ( ) const
int get_screen_count ( ) const
bool get_swap_cancel_ok ( )
PackedInt32Array get_window_list ( ) const
Vector2i ime_get_selection ( ) const
String ime_get_text ( ) const
int keyboard_get_current_layout ( ) const
Returns active keyboard layout index.
Note: This method is implemented on Linux, macOS and Windows.
Converts a physical (US QWERTY) keycode
to one in the active keyboard layout.
Note: This method is implemented on Linux, macOS and Windows.
int keyboard_get_layout_count ( ) const
Returns the number of keyboard layouts.
Note: This method is implemented on Linux, macOS and Windows.
Returns the ISO-639/BCP-47 language code of the keyboard layout at position index
.
Note: This method is implemented on Linux, macOS and Windows.
Returns the localized name of the keyboard layout at position index
.
Note: This method is implemented on Linux, macOS and Windows.
void keyboard_set_current_layout ( int index )
Sets active keyboard layout.
Note: This method is implemented on Linux, macOS and Windows.
MouseButton mouse_get_button_state ( ) const
MouseMode mouse_get_mode ( ) const
Vector2i mouse_get_position ( ) const
Returns the mouse cursor's current position.
void mouse_set_mode ( MouseMode mouse_mode )
void mouse_warp_to_position ( Vector2i position )
Sets the mouse cursor position to the given position
.
void process_events ( )
Returns the dots per inch density of the specified screen. If screen
is \ SCREEN_OF_MAIN_WINDOW
(the default value), a screen with the main window will be used.
Note: On macOS, returned value is inaccurate if fractional display scaling mode is used.
Note: On Android devices, the actual screen densities are grouped into six generalized densities:
ldpi - 120 dpi
mdpi - 160 dpi
hdpi - 240 dpi
xhdpi - 320 dpi
xxhdpi - 480 dpi
xxxhdpi - 640 dpi
Note: This method is implemented on Android, Linux, macOS and Windows. Returns 72
on unsupported platforms.
float screen_get_max_scale ( ) const
Returns the greatest scale factor of all screens.
Note: On macOS returned value is 2.0
if there is at least one hiDPI (Retina) screen in the system, and 1.0
in all other cases.
Note: This method is implemented on macOS.
ScreenOrientation screen_get_orientation ( int screen=-1 ) const
Returns the current refresh rate of the specified screen. If screen
is SCREEN_OF_MAIN_WINDOW (the default value), a screen with the main window will be used.
Note: Returns -1.0
if the DisplayServer fails to find the refresh rate for the specified screen. On HTML5, screen_get_refresh_rate will always return -1.0
as there is no way to retrieve the refresh rate on that platform.
To fallback to a default refresh rate if the method fails, try:
var refresh_rate = DisplayServer.screen_get_refresh_rate()
if refresh_rate < 0:
refresh_rate = 60.0
Returns the scale factor of the specified screen by index.
Note: On macOS returned value is 2.0
for hiDPI (Retina) screen, and 1.0
for all other cases.
Note: This method is implemented on macOS.
bool screen_is_kept_on ( ) const
void screen_set_keep_on ( bool enable )
void screen_set_orientation ( ScreenOrientation orientation, int screen=-1 )
void set_icon ( Image image )
void set_native_icon ( String filename )
String tablet_get_current_driver ( ) const
Returns current active tablet driver name.
Note: This method is implemented on Windows.
int tablet_get_driver_count ( ) const
Returns the total number of available tablet drivers.
Note: This method is implemented on Windows.
Returns the tablet driver name for the given index.
Note: This method is implemented on Windows.
void tablet_set_current_driver ( String name )
Set active tablet driver name.
Note: This method is implemented on Windows.
int virtual_keyboard_get_height ( ) const
Returns the on-screen keyboard's height in pixels. Returns 0 if there is no keyboard or if it is currently hidden.
void virtual_keyboard_hide ( )
Hides the virtual keyboard if it is shown, does nothing otherwise.
void virtual_keyboard_show ( String existing_text, Rect2 position=Rect2(0, 0, 0, 0), bool multiline=false, int max_length=-1, int cursor_start=-1, int cursor_end=-1 )
Shows the virtual keyboard if the platform has one.
existing_text
parameter is useful for implementing your own LineEdit or TextEdit, as it tells the virtual keyboard what text has already been typed (the virtual keyboard uses it for auto-correct and predictions).
position
parameter is the screen space Rect2 of the edited text.
multiline
parameter needs to be set to true
to be able to enter multiple lines of text, as in TextEdit.
max_length
limits the number of characters that can be entered if different from -1
.
cursor_start
can optionally define the current text cursor position if cursor_end
is not set.
cursor_start
and cursor_end
can optionally define the current text selection.
Note: This method is implemented on Android, iOS and UWP.
int window_get_active_popup ( ) const
Returns ID of the active popup window, or INVALID_WINDOW_ID if there is none.
bool window_get_flag ( WindowFlags flag, int window_id=0 ) const
Returns the current value of the given window's flag
.
WindowMode window_get_mode ( int window_id=0 ) const
Returns the mode of the given window.
int window_get_native_handle ( HandleType handle_type, int window_id=0 ) const
Returns internal structure pointers for use in plugins.
Note: This method is implemented on Android, Linux, macOS and Windows.
Returns the bounding box of control, or menu item that was used to open the popup window, in the screen coordinate system.
Returns the position of the given window to on the screen.
Returns the VSync mode of the given window.
void window_move_to_foreground ( int window_id=0 )
void window_request_attention ( int window_id=0 )
If set to true
, this window will always stay on top of its parent window, parent window will ignore input while this window is opened.
Note: On macOS, exclusive windows are confined to the same space (virtual desktop or screen) as the parent window.
Note: This method is implemented on macOS and Windows.
void window_set_flag ( WindowFlags flag, bool enabled, int window_id=0 )
Enables or disables the given window's given flag
. See WindowFlags for possible values and their behavior.
Sets the minimum size for the given window to min_size
(in pixels).
Note: By default, the main window has a minimum size of Vector2i(64, 64)
. This prevents issues that can arise when the window is resized to a near-zero size.
void window_set_mode ( WindowMode mode, int window_id=0 )
Sets window mode for the given window to mode
. See WindowMode for possible values and how each mode behaves.
Note: Setting the window to fullscreen forcibly sets the borderless flag to true
, so make sure to set it back to false
when not wanted.
void window_set_mouse_passthrough ( PackedVector2Array region, int window_id=0 )
Sets a polygonal region of the window which accepts mouse events. Mouse events outside the region will be passed through.
Passing an empty array will disable passthrough support (all mouse events will be intercepted by the window, which is the default behavior).
# Set region, using Path2D node.
DisplayServer.window_set_mouse_passthrough($Path2D.curve.get_baked_points())
# Set region, using Polygon2D node.
DisplayServer.window_set_mouse_passthrough($Polygon2D.polygon)
# Reset region to default.
DisplayServer.window_set_mouse_passthrough([])
// Set region, using Path2D node.
DisplayServer.WindowSetMousePassthrough(GetNode<Path2D>("Path2D").Curve.GetBakedPoints());
// Set region, using Polygon2D node.
DisplayServer.WindowSetMousePassthrough(GetNode<Polygon2D>("Polygon2D").Polygon);
// Reset region to default.
DisplayServer.WindowSetMousePassthrough(new Vector2[] {});
Note: On Windows, the portion of a window that lies outside the region is not drawn, while on Linux and macOS it is.
Note: This method is implemented on Linux, macOS and Windows.
Sets the bounding box of control, or menu item that was used to open the popup window, in the screen coordinate system. Clicking this area will not auto-close this popup.
Sets the position of the given window to position
.
Sets the size of the given window to size
.
Sets the title of the given window to title
.
Sets the VSync mode of the given window.
See VSyncMode for possible values and how they affect the behavior of your application.
Depending on the platform and used renderer, the engine will fall back to VSYNC_ENABLED, if the desired mode is not supported.