diff options
Diffstat (limited to 'doc/classes/OS.xml')
| -rw-r--r-- | doc/classes/OS.xml | 134 |
1 files changed, 69 insertions, 65 deletions
diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index f6e2f47a42..d73c85a6d9 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -4,7 +4,7 @@ Operating System functions. </brief_description> <description> - Operating System functions. OS Wraps the most common functionality to communicate with the host Operating System, such as: clipboard, video mode, date and time, timers, environment variables, execution of binaries, command line, etc. + Operating System functions. OS wraps the most common functionality to communicate with the host operating system, such as the clipboard, video driver, date and time, timers, environment variables, execution of binaries, command line, etc. </description> <tutorials> </tutorials> @@ -17,7 +17,7 @@ <argument index="1" name="title" type="String" default=""Alert!""> </argument> <description> - Displays a modal dialog box utilizing the host OS. + Displays a modal dialog box using the host OS' facilities. Execution is blocked until the dialog is closed. </description> </method> <method name="can_draw" qualifiers="const"> @@ -53,7 +53,7 @@ <argument index="0" name="msec" type="int"> </argument> <description> - Delay execution of the current thread by given milliseconds. + Delay execution of the current thread by [code]msec[/code] milliseconds. </description> </method> <method name="delay_usec" qualifiers="const"> @@ -62,7 +62,7 @@ <argument index="0" name="usec" type="int"> </argument> <description> - Delay execution of the current thread by given microseconds. + Delay execution of the current thread by [code]usec[/code] microseconds. </description> </method> <method name="dump_memory_to_file"> @@ -101,15 +101,15 @@ </argument> <description> Execute the file at the given path with the arguments passed as an array of strings. Platform path resolution will take place. The resolved file must exist and be executable. - The arguments are used in the given order and separated by a space, so [code]OS.execute('ping', ['-w', '3', 'godotengine.org'], false)[/code] will resolve to [code]ping -w 3 godotengine.org[/code] in the system's shell. + The arguments are used in the given order and separated by a space, so [code]OS.execute("ping", ["-w", "3", "godotengine.org"], false)[/code] will resolve to [code]ping -w 3 godotengine.org[/code] in the system's shell. This method has slightly different behavior based on whether the [code]blocking[/code] mode is enabled. - When [code]blocking[/code] is enabled, the Godot thread will pause its execution while waiting for the process to terminate. The shell output of the process will be written to the [code]output[/code] array as a single string. When the process terminates, the Godot thread will resume execution. - When [code]blocking[/code] is disabled, the Godot thread will continue while the new process runs. It is not possible to retrieve the shell output in non-blocking mode, so [code]output[/code] will be empty. - The return value also depends on the blocking mode. When blocking, the method will return -2 (no process ID information is available in blocking mode). When non-blocking, the method returns a process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). If the process forking (non-blocking) or opening (blocking) fails, the method will return -1. + If [code]blocking[/code] is [code]true[/code], the Godot thread will pause its execution while waiting for the process to terminate. The shell output of the process will be written to the [code]output[/code] array as a single string. When the process terminates, the Godot thread will resume execution. + If [code]blocking[/code] is [code]false[/code], the Godot thread will continue while the new process runs. It is not possible to retrieve the shell output in non-blocking mode, so [code]output[/code] will be empty. + The return value also depends on the blocking mode. When blocking, the method will return -2 (no process ID information is available in blocking mode). When non-blocking, the method returns a process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). If the process forking (non-blocking) or opening (blocking) fails, the method will return [code]-1[/code]. Example of blocking mode and retrieving the shell output: [codeblock] var output = [] - OS.execute('ls', ['-l', '/tmp'], true, output) + OS.execute("ls", ["-l", "/tmp"], true, output) [/codeblock] Example of non-blocking mode, running another instance of the project and storing its process ID: [codeblock] @@ -117,7 +117,7 @@ [/codeblock] If you wish to access a shell built-in or perform a composite command, a platform-specific shell can be invoked. For example: [codeblock] - OS.execute('CMD.exe', ['/C', 'cd %TEMP% && dir'], true, output) + OS.execute("CMD.exe", ["/C", "cd %TEMP% && dir"], true, output) [/codeblock] </description> </method> @@ -127,7 +127,7 @@ <argument index="0" name="string" type="String"> </argument> <description> - Returns the scancode of the given string (e.g. "Escape") + Returns the scancode of the given string (e.g. "Escape"). </description> </method> <method name="get_audio_driver_count" qualifiers="const"> @@ -172,7 +172,7 @@ <argument index="0" name="utc" type="bool" default="false"> </argument> <description> - Returns current date as a dictionary of keys: year, month, day, weekday, dst (daylight savings time). + Returns current date as a dictionary of keys: [code]year[/code], [code]month[/code], [code]day[/code], [code]weekday[/code], [code]dst[/code] (Daylight Savings Time). </description> </method> <method name="get_datetime" qualifiers="const"> @@ -181,7 +181,7 @@ <argument index="0" name="utc" type="bool" default="false"> </argument> <description> - Returns current datetime as a dictionary of keys: year, month, day, weekday, dst (daylight savings time), hour, minute, second. + Returns current datetime as a dictionary of keys: [code]year[/code], [code]month[/code], [code]day[/code], [code]weekday[/code], [code]dst[/code] (Daylight Savings Time), [code]hour[/code], [code]minute[/code], [code]second[/code]. </description> </method> <method name="get_datetime_from_unix_time" qualifiers="const"> @@ -190,8 +190,8 @@ <argument index="0" name="unix_time_val" type="int"> </argument> <description> - Get a dictionary of time values when given epoch time. - Dictionary Time values will be a union of values from [method get_time] and [method get_date] dictionaries (with the exception of dst = day light standard time, as it cannot be determined from epoch). + Gets a dictionary of time values corresponding to the given UNIX epoch time (in seconds). + The returned Dictionary's values will be the same as [method get_datetime], with the exception of Daylight Savings Time as it cannot be determined from the epoch. </description> </method> <method name="get_dynamic_memory_usage" qualifiers="const"> @@ -221,7 +221,7 @@ <return type="Vector2"> </return> <description> - Returns IME cursor position (currently edited portion of the string) relative to the characters in the composition string. + Returns the IME cursor position (the currently-edited portion of the string) relative to the characters in the composition string. [constant MainLoop.NOTIFICATION_OS_IME_UPDATE] is sent to the application to notify it of changes to the IME cursor position. </description> </method> @@ -229,7 +229,7 @@ <return type="String"> </return> <description> - Returns IME intermediate composition string. + Returns the IME intermediate composition string. [constant MainLoop.NOTIFICATION_OS_IME_UPDATE] is sent to the application to notify it of changes to the IME composition string. </description> </method> @@ -238,7 +238,7 @@ </return> <description> Returns the current latin keyboard variant as a String. - Possible return values are: "QWERTY", "AZERTY", "QZERTY", "DVORAK", "NEO", "COLEMAK" or "ERROR". + Possible return values are: [code]"QWERTY"[/code], [code]"AZERTY"[/code], [code]"QZERTY"[/code], [code]"DVORAK"[/code], [code]"NEO"[/code], [code]"COLEMAK"[/code] or [code]"ERROR"[/code]. </description> </method> <method name="get_locale" qualifiers="const"> @@ -259,7 +259,7 @@ <return type="String"> </return> <description> - Returns the name of the host OS. Possible values are: "Android", "Haiku", "iOS", "HTML5", "OSX", "Server", "Windows", "UWP", "X11". + Returns the name of the host OS. Possible values are: [code]"Android"[/code], [code]"Haiku"[/code], [code]"iOS"[/code], [code]"HTML5"[/code], [code]"OSX"[/code], [code]"Server"[/code], [code]"Windows"[/code], [code]"UWP"[/code], [code]"X11"[/code]. </description> </method> <method name="get_power_percent_left"> @@ -273,7 +273,7 @@ <return type="int"> </return> <description> - Returns the time in seconds before the device runs out of battery. + Returns an estimate of the time left in seconds before the device runs out of battery. </description> </method> <method name="get_power_state"> @@ -287,14 +287,14 @@ <return type="int"> </return> <description> - Returns the game process ID + Returns the project's process ID. </description> </method> <method name="get_processor_count" qualifiers="const"> <return type="int"> </return> <description> - Returns the number of cores available in the host machine. + Returns the number of threads available on the host machine. </description> </method> <method name="get_real_window_size" qualifiers="const"> @@ -310,7 +310,7 @@ <argument index="0" name="code" type="int"> </argument> <description> - Returns the given scancode as a string (e.g. Return values: "Escape", "Shift+Escape"). + Returns the given scancode as a string (e.g. Return values: [code]"Escape"[/code], [code]"Shift+Escape"[/code]). </description> </method> <method name="get_screen_count" qualifiers="const"> @@ -327,13 +327,15 @@ </argument> <description> Returns the dots per inch density of the specified screen. - 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 + On Android devices, the actual screen densities are grouped into six generalized densities: + [codeblock] + ldpi - 120 dpi + mdpi - 160 dpi + hdpi - 240 dpi + xhdpi - 320 dpi + xxhdpi - 480 dpi + xxxhdpi - 640 dpi + [/codeblock] </description> </method> <method name="get_screen_position" qualifiers="const"> @@ -358,13 +360,14 @@ <return type="int"> </return> <description> + Returns the amount of time in milliseconds it took for the boot logo to appear. </description> </method> <method name="get_static_memory_peak_usage" qualifiers="const"> <return type="int"> </return> <description> - Returns the max amount of static memory used (only works in debug). + Returns the maximum amount of static memory used (only works in debug). </description> </method> <method name="get_static_memory_usage" qualifiers="const"> @@ -432,14 +435,14 @@ </return> <description> Returns a string that is unique to the device. - Returns empty string on HTML5 and UWP which are not supported yet. + [b]Note:[/b] Returns an empty string on HTML5 and UWP, as this method isn't implemented on those platforms yet. </description> </method> <method name="get_unix_time" qualifiers="const"> <return type="int"> </return> <description> - Returns the current unix epoch timestamp. + Returns the current UNIX epoch timestamp. </description> </method> <method name="get_unix_time_from_datetime" qualifiers="const"> @@ -448,9 +451,9 @@ <argument index="0" name="datetime" type="Dictionary"> </argument> <description> - Get an epoch time value from a dictionary of time values. - [code]datetime[/code] must be populated with the following keys: year, month, day, hour, minute, second. - You can pass the output from [method get_datetime_from_unix_time] directly into this function. Daylight savings time (dst), if present, is ignored. + Gets an epoch time value from a dictionary of time values. + [code]datetime[/code] must be populated with the following keys: [code]year[/code], [code]month[/code], [code]day[/code], [code]hour[/code], [code]minute[/code], [code]second[/code]. + You can pass the output from [method get_datetime_from_unix_time] directly into this function. Daylight Savings Time ([code]dst[/code]), if present, is ignored. </description> </method> <method name="get_user_data_dir" qualifiers="const"> @@ -484,13 +487,14 @@ <return type="int"> </return> <description> - Returns the on-screen keyboard's height in pixels. Returns 0 if there is no keyboard or it is currently hidden. + Returns the on-screen keyboard's height in pixels. Returns 0 if there is no keyboard or if it is currently hidden. </description> </method> <method name="get_window_safe_area" qualifiers="const"> <return type="Rect2"> </return> <description> + Returns unobscured area of the window where interactive controls should be rendered. </description> </method> <method name="has_environment" qualifiers="const"> @@ -509,7 +513,7 @@ </argument> <description> Returns [code]true[/code] if the feature for the given feature tag is supported in the currently running instance, depending on platform, build etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the [url=https://docs.godotengine.org/en/latest/getting_started/workflow/export/feature_tags.html]Feature Tags[/url] documentation for more details. - Note that tag names are case-sensitive. + [b]Note:[/b] Tag names are case-sensitive. </description> </method> <method name="has_touchscreen_ui_hint" qualifiers="const"> @@ -546,7 +550,7 @@ <return type="bool"> </return> <description> - Returns [code]true[/code] if the "Okay" button should appear on the left and "Cancel" on the right. + Returns [code]true[/code] if the [b]OK[/b] button should appear on the left and [b]Cancel[/b] on the right. </description> </method> <method name="is_scancode_unicode" qualifiers="const"> @@ -555,14 +559,14 @@ <argument index="0" name="code" type="int"> </argument> <description> - Returns [code]true[/code] if the input code has a unicode character. + Returns [code]true[/code] if the input scancode corresponds to a Unicode character. </description> </method> <method name="is_stdout_verbose" qualifiers="const"> <return type="bool"> </return> <description> - Returns [code]true[/code] if the engine was executed with -v (verbose stdout). + Returns [code]true[/code] if the engine was executed with [code]-v[/code] (verbose stdout). </description> </method> <method name="is_userfs_persistent" qualifiers="const"> @@ -586,7 +590,7 @@ </argument> <description> Kill (terminate) the process identified by the given process ID ([code]pid[/code]), e.g. the one returned by [method execute] in non-blocking mode. - Note that this method can also be used to kill processes that were not spawned by the game. + [b]Note:[/b] This method can also be used to kill processes that were not spawned by the game. </description> </method> <method name="move_window_to_foreground"> @@ -623,7 +627,7 @@ </argument> <description> Plays native video from the specified path, at the given volume and with audio and subtitle tracks. - Note: This method is only implemented on Android and iOS, and the current Android implementation does not support the [code]volume[/code], [code]audio_track[/code] and [code]subtitle_track[/code] options. + [b]Note:[/b] This method is only implemented on Android and iOS, and the current Android implementation does not support the [code]volume[/code], [code]audio_track[/code] and [code]subtitle_track[/code] options. </description> </method> <method name="native_video_stop"> @@ -652,7 +656,7 @@ <argument index="0" name="tofile" type="String" default=""""> </argument> <description> - Shows all resources in the game. Optionally the list can be written to a file. + Shows all resources in the game. Optionally, the list can be written to a file by specifying a file path in [code]tofile[/code]. </description> </method> <method name="print_all_textures_by_size"> @@ -735,7 +739,7 @@ <description> Sets the game's icon using a multi-size platform-specific icon file ([code]*.ico[/code] on Windows and [code]*.icns[/code] on macOS). Appropriate size sub-icons are used for window caption, taskbar/dock and window selection dialog. - Note: This method is only implemented on macOS and Windows. + [b]Note:[/b] This method is only implemented on macOS and Windows. </description> </method> <method name="set_thread_name"> @@ -791,63 +795,63 @@ <argument index="0" name="existing_text" type="String" default=""""> </argument> <description> - Shows the virtual keyboard if the platform has one. The [i]existing_text[/i] parameter is useful for implementing your own LineEdit, as it tells the virtual keyboard what text has already been typed (the virtual keyboard uses it for auto-correct and predictions). + Shows the virtual keyboard if the platform has one. The [code]existing_text[/code] parameter is useful for implementing your own LineEdit, as it tells the virtual keyboard what text has already been typed (the virtual keyboard uses it for auto-correct and predictions). </description> </method> </methods> <members> - <member name="clipboard" type="String" setter="set_clipboard" getter="get_clipboard"> + <member name="clipboard" type="String" setter="set_clipboard" getter="get_clipboard" default=""""> The clipboard from the host OS. Might be unavailable on some platforms. </member> - <member name="current_screen" type="int" setter="set_current_screen" getter="get_current_screen"> + <member name="current_screen" type="int" setter="set_current_screen" getter="get_current_screen" default="0"> The current screen index (starting from 0). </member> - <member name="exit_code" type="int" setter="set_exit_code" getter="get_exit_code"> + <member name="exit_code" type="int" setter="set_exit_code" getter="get_exit_code" default="0"> The exit code passed to the OS when the main loop exits. </member> - <member name="keep_screen_on" type="bool" setter="set_keep_screen_on" getter="is_keep_screen_on"> + <member name="keep_screen_on" type="bool" setter="set_keep_screen_on" getter="is_keep_screen_on" default="true"> If [code]true[/code], the engine tries to keep the screen on while the game is running. Useful on mobile. </member> - <member name="low_processor_usage_mode" type="bool" setter="set_low_processor_usage_mode" getter="is_in_low_processor_usage_mode"> + <member name="low_processor_usage_mode" type="bool" setter="set_low_processor_usage_mode" getter="is_in_low_processor_usage_mode" default="false"> If [code]true[/code], the engine optimizes for low processor usage by only refreshing the screen if needed. Can improve battery consumption on mobile. </member> - <member name="max_window_size" type="Vector2" setter="set_max_window_size" getter="get_max_window_size"> + <member name="max_window_size" type="Vector2" setter="set_max_window_size" getter="get_max_window_size" default="Vector2( 0, 0 )"> The maximum size of the window (without counting window manager decorations). Does not affect fullscreen mode. Set to [code](0, 0)[/code] to reset to the system default value. </member> - <member name="min_window_size" type="Vector2" setter="set_min_window_size" getter="get_min_window_size"> + <member name="min_window_size" type="Vector2" setter="set_min_window_size" getter="get_min_window_size" default="Vector2( 0, 0 )"> The minimum size of the window (without counting window manager decorations). Does not affect fullscreen mode. Set to [code](0, 0)[/code] to reset to the system default value. </member> - <member name="screen_orientation" type="int" setter="set_screen_orientation" getter="get_screen_orientation" enum="_OS.ScreenOrientation"> + <member name="screen_orientation" type="int" setter="set_screen_orientation" getter="get_screen_orientation" enum="_OS.ScreenOrientation" default="0"> The current screen orientation. </member> - <member name="vsync_enabled" type="bool" setter="set_use_vsync" getter="is_vsync_enabled"> + <member name="vsync_enabled" type="bool" setter="set_use_vsync" getter="is_vsync_enabled" default="true"> If [code]true[/code], vertical synchronization (Vsync) is enabled. </member> - <member name="window_borderless" type="bool" setter="set_borderless_window" getter="get_borderless_window"> + <member name="window_borderless" type="bool" setter="set_borderless_window" getter="get_borderless_window" default="false"> If [code]true[/code], removes the window frame. - Note: Setting [code]window_borderless[/code] to [code]false[/code] disables per-pixel transparency. + [b]Note:[/b] Setting [code]window_borderless[/code] to [code]false[/code] disables per-pixel transparency. </member> - <member name="window_fullscreen" type="bool" setter="set_window_fullscreen" getter="is_window_fullscreen"> + <member name="window_fullscreen" type="bool" setter="set_window_fullscreen" getter="is_window_fullscreen" default="false"> If [code]true[/code], the window is fullscreen. </member> - <member name="window_maximized" type="bool" setter="set_window_maximized" getter="is_window_maximized"> + <member name="window_maximized" type="bool" setter="set_window_maximized" getter="is_window_maximized" default="false"> If [code]true[/code], the window is maximized. </member> - <member name="window_minimized" type="bool" setter="set_window_minimized" getter="is_window_minimized"> + <member name="window_minimized" type="bool" setter="set_window_minimized" getter="is_window_minimized" default="false"> If [code]true[/code], the window is minimized. </member> - <member name="window_per_pixel_transparency_enabled" type="bool" setter="set_window_per_pixel_transparency_enabled" getter="get_window_per_pixel_transparency_enabled"> + <member name="window_per_pixel_transparency_enabled" type="bool" setter="set_window_per_pixel_transparency_enabled" getter="get_window_per_pixel_transparency_enabled" default="false"> If [code]true[/code], the window background is transparent and window frame is removed. Use [code]get_tree().get_root().set_transparent_background(true)[/code] to disable main viewport background rendering. - Note: This property has no effect if "Project > Project Settings > Display > Window > Per-pixel transparency > Allowed" setting is disabled. + [b]Note:[/b] This property has no effect if [b]Project > Project Settings > Display > Window > Per-pixel transparency > Allowed[/b] setting is disabled. </member> - <member name="window_position" type="Vector2" setter="set_window_position" getter="get_window_position"> + <member name="window_position" type="Vector2" setter="set_window_position" getter="get_window_position" default="Vector2( 0, 0 )"> The window position relative to the screen, the origin is the top left corner, +Y axis goes to the bottom and +X axis goes to the right. </member> - <member name="window_resizable" type="bool" setter="set_window_resizable" getter="is_window_resizable"> + <member name="window_resizable" type="bool" setter="set_window_resizable" getter="is_window_resizable" default="true"> If [code]true[/code], the window is resizable by the user. </member> - <member name="window_size" type="Vector2" setter="set_window_size" getter="get_window_size"> + <member name="window_size" type="Vector2" setter="set_window_size" getter="get_window_size" default="Vector2( 0, 0 )"> The size of the window (without counting window manager decorations). </member> </members> |