From 9c448604254db0309f404f5d875cae2193a48710 Mon Sep 17 00:00:00 2001 From: DerryAlex Date: Sun, 11 Aug 2024 10:06:01 +0800 Subject: [PATCH 1/4] Fetch GLib/Gio win32 specific GIR file --- dl-win32.sh | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/dl-win32.sh b/dl-win32.sh index 794df992..28dc7e2c 100755 --- a/dl-win32.sh +++ b/dl-win32.sh @@ -4,3 +4,11 @@ GTK_VERSION=$(wget -qO- "https://packages.msys2.org/api/search?query=gtk4" | jq wget -qO- "https://mirror.msys2.org/mingw/ucrt64/mingw-w64-ucrt-x86_64-gtk4-$GTK_VERSION-any.pkg.tar.zst" | \ zstdcat - | tar xO "ucrt64/share/gir-1.0/GdkWin32-4.0.gir" > GdkWin32-4.0.gir + +# -x ucrt64/share/gir-1.0/GLibWin32-2.0.gir -x ucrt64/share/gir-1.0/GioWin32-2.0.gir +GLIB_VERSION=$(wget -qO- "https://packages.msys2.org/api/search?query=glib2" | jq -r ".results.exact.version") + +wget -qO- "https://mirror.msys2.org/mingw/ucrt64/mingw-w64-ucrt-x86_64-glib2-$GLIB_VERSION-any.pkg.tar.zst" | \ + zstdcat - | tar -x "ucrt64/share/gir-1.0/GLibWin32-2.0.gir" -x "ucrt64/share/gir-1.0/GioWin32-2.0.gir" +mv ucrt64/share/gir-1.0/*.gir . +rm -r ucrt64 From e90ece41acbd7cb28911ce95269876cf3679a3ef Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Mon, 9 Sep 2024 05:07:18 +0000 Subject: [PATCH 2/4] Bump peter-evans/create-pull-request from 6 to 7 Bumps [peter-evans/create-pull-request](https://github.com/peter-evans/create-pull-request) from 6 to 7. - [Release notes](https://github.com/peter-evans/create-pull-request/releases) - [Commits](https://github.com/peter-evans/create-pull-request/compare/v6...v7) --- updated-dependencies: - dependency-name: peter-evans/create-pull-request dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] --- .github/workflows/regenerate_scheduled.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/regenerate_scheduled.yml b/.github/workflows/regenerate_scheduled.yml index 3b72bfe7..41ab3dd8 100644 --- a/.github/workflows/regenerate_scheduled.yml +++ b/.github/workflows/regenerate_scheduled.yml @@ -30,7 +30,7 @@ jobs: echo ::set-output name=pr_body::"This PR was auto-generated on $(date +%Y-%m-%d). Please review and manually edit before merging." - name: Create PR id: cpr - uses: peter-evans/create-pull-request@v6 + uses: peter-evans/create-pull-request@v7 with: commit-message: Update GIR files title: ${{ steps.changes.outputs.pr_title }} From 426f37ae4067f24f9ba3498d0efb6b17adb8fd08 Mon Sep 17 00:00:00 2001 From: bilelmoussaoui <7660997+bilelmoussaoui@users.noreply.github.com> Date: Fri, 18 Oct 2024 17:22:41 +0000 Subject: [PATCH 3/4] Update GIR files --- Atk-1.0.gir | 8 +- GLib-2.0.gir | 1700 ++++++++++++++++++++++----------- GLibUnix-2.0.gir | 126 +++ GLibWin32-2.0.gir | 136 +++ GModule-2.0.gir | 24 + GObject-2.0.gir | 24 + Gdk-3.0.gir | 2 +- Gdk-4.0.gir | 1020 +++++++++++++++++++- Gio-2.0.gir | 2328 ++++++++++++++++++++++++++------------------- GioUnix-2.0.gir | 382 +++++--- GioWin32-2.0.gir | 393 ++++++++ Gsk-4.0.gir | 21 +- Gtk-3.0.gir | 4 +- Gtk-4.0.gir | 237 ++++- Pango-1.0.gir | 12 +- 15 files changed, 4678 insertions(+), 1739 deletions(-) create mode 100644 GLibWin32-2.0.gir create mode 100644 GioWin32-2.0.gir diff --git a/Atk-1.0.gir b/Atk-1.0.gir index a96c4281..88333fe3 100644 --- a/Atk-1.0.gir +++ b/Atk-1.0.gir @@ -553,7 +553,7 @@ A string name/value pair representing a generic attribute. - + Like atk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -4727,7 +4727,7 @@ application compile time, rather than from the library linked against at application run time. - + Like atk_get_minor_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -7682,7 +7682,7 @@ in ATK. Other roles may be added at runtime, so an AtkRole >= An object used to indicate how much of a task has been completed - + An object the user can manipulate to tell the application to do something @@ -8018,6 +8018,8 @@ actual change is. (Since: 2.36) not a valid role, used for finding end of the enumeration + + Get the #AtkRole type corresponding to a rolew name. diff --git a/GLib-2.0.gir b/GLib-2.0.gir index ca087972..23408d4f 100644 --- a/GLib-2.0.gir +++ b/GLib-2.0.gir @@ -3206,7 +3206,7 @@ thread. - + A simple refcounted data type representing an immutable sequence of zero or more bytes from an unspecified origin. @@ -3234,7 +3234,10 @@ a mutable #GByteArray, use the g_byte_array_free_to_bytes() function. Creates a new #GBytes from @data. -@data is copied. If @size is 0, @data may be %NULL. +@data is copied. If @size is 0, @data may be %NULL. + +As an optimization, g_bytes_new() may avoid an extra allocation by copying +the data within the resulting bytes structure if sufficiently small (since GLib 2.84). a new #GBytes @@ -3553,8 +3556,9 @@ the same byte data. As an optimization, the byte data is transferred to the array without copying if this was the last reference to bytes and bytes was created with -g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all -other cases the data is copied. +g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes() and the +buffer was larger than the size #GBytes may internalize within its allocation. +In all other cases the data is copied. Do not use it if @bytes contains more than %G_MAXUINT bytes. #GByteArray stores the length of its data in #guint, which @@ -3578,8 +3582,9 @@ contents. As an optimization, the byte data is returned without copying if this was the last reference to bytes and bytes was created with g_bytes_new(), -g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the -data is copied. +g_bytes_new_take() or g_byte_array_free_to_bytes() and the buffer was larger +than the size #GBytes may internalize within its allocation. In all other +cases the data is copied. a pointer to the same byte data, which should be freed with g_free() @@ -4102,8 +4107,8 @@ date to include new hashing algorithm types. Prototype of a #GChildWatchSource callback, called when a child process has exited. -To interpret @wait_status, see the documentation -for g_spawn_check_wait_status(). In particular, +To interpret @wait_status, see the documentation for +[func@GLib.spawn_check_wait_status]. In particular, on Unix platforms, note that it is usually not equal to the integer passed to `exit()` or returned from `main()`. @@ -4120,16 +4125,16 @@ to the integer passed to `exit()` or returned from `main()`. - user data passed to g_child_watch_add() + user data passed to [func@GLib.child_watch_add] - Specifies the type of function passed to g_clear_handle_id(). -The implementation is expected to free the resource identified -by @handle_id; for instance, if @handle_id is a #GSource ID, -g_source_remove() can be used. + Specifies the type of function passed to [func@GLib.clear_handle_id] The +implementation is expected to free the resource identified by @handle_id; +for instance, if @handle_id is a [struct@GLib.Source] ID, +[func@GLib.Source.remove] can be used. @@ -5124,6 +5129,12 @@ in the macro, so you shouldn't use double quotes. + + + + + + @@ -5304,6 +5315,12 @@ in the macro, so you shouldn't use double quotes. + + + + + + @@ -5484,6 +5501,12 @@ in the macro, so you shouldn't use double quotes. + + + + + + @@ -5664,6 +5687,12 @@ in the macro, so you shouldn't use double quotes. + + + + + + The directory separator character. This is '/' on UNIX machines and '\' under Windows. @@ -6521,7 +6550,7 @@ For example, don't expect that using g_date_strftime() would make the \%F provided by the C99 strftime() work on Windows where the C library only complies to C89. - number of characters written to the buffer, or 0 the buffer was too small + number of characters written to the buffer, or `0` if the buffer was too small @@ -6786,7 +6815,7 @@ when you are done with it. Creates a #GDateTime corresponding to the given [ISO 8601 formatted string](https://en.wikipedia.org/wiki/ISO_8601) -@text. ISO 8601 strings of the form <date><sep><time><tz> are supported, with +@text. ISO 8601 strings of the form `<date><sep><time><tz>` are supported, with some extensions from [RFC 3339](https://tools.ietf.org/html/rfc3339) as mentioned below. @@ -6794,11 +6823,11 @@ Note that as #GDateTime "is oblivious to leap seconds", leap seconds information in an ISO-8601 string will be ignored, so a `23:59:60` time would be parsed as `23:59:59`. -<sep> is the separator and can be either 'T', 't' or ' '. The latter two +`<sep>` is the separator and can be either 'T', 't' or ' '. The latter two separators are an extension from [RFC 3339](https://tools.ietf.org/html/rfc3339#section-5.6). -<date> is in the form: +`<date>` is in the form: - `YYYY-MM-DD` - Year/month/day, e.g. 2016-08-24. - `YYYYMMDD` - Same as above without dividers. @@ -6808,12 +6837,12 @@ separators are an extension from e.g. 2016-W34-3. - `YYYYWwwD` - Same as above without dividers. -<time> is in the form: +`<time>` is in the form: - `hh:mm:ss(.sss)` - Hours, minutes, seconds (subseconds), e.g. 22:10:42.123. - `hhmmss(.sss)` - Same as above without dividers. -<tz> is an optional timezone suffix of the form: +`<tz>` is an optional timezone suffix of the form: - `Z` - UTC. - `+hh:mm` or `-hh:mm` - Offset from UTC in hours and minutes, e.g. +12:00. @@ -9218,13 +9247,18 @@ it is active and it has not been destroyed. Specifies the type of the function passed to -g_hash_table_foreach_remove(). It is called with each key/value -pair, together with the @user_data parameter passed to -g_hash_table_foreach_remove(). It should return %TRUE if the -key/value pair should be removed from the #GHashTable. +[func@GLib.HashTable.find], [func@GLib.HashTable.foreach_remove], and +[func@GLib.HashTable.foreach_steal]. + +The function is called with each key/value pair, together with +the @user_data parameter passed to the calling function. + +The function should return true if the key/value pair should be +selected, meaning it has been found or it should be removed from the +[struct@GLib.HashTable], depending on the calling function. - %TRUE if the key/value pair should be removed from the - #GHashTable + true if the key/value pair should be selected, and + false otherwise @@ -9237,7 +9271,7 @@ key/value pair should be removed from the #GHashTable. - user data passed to g_hash_table_remove() + user data passed to the calling function @@ -10046,8 +10080,9 @@ You can pass %NULL for @lookup_key, provided the hash and equal functions of @hash_table are %NULL-safe. The dictionary implementation optimizes for having all values identical to -their keys, for example by using g_hash_table_add(). When stealing both the -key and the value from such a dictionary, the value will be %NULL. +their keys, for example by using g_hash_table_add(). Before 2.82, when +stealing both the key and the value from such a dictionary, the value was +%NULL. Since 2.82, the returned value and key will be the same. %TRUE if the key was found in the #GHashTable @@ -11472,7 +11507,8 @@ the internal values of these flags. This returns the string that #GIOChannel uses to determine where in the file a line break occurs. A value of %NULL -indicates autodetection. +indicates autodetection. Since 2.84, the return value is always +nul-terminated. The line termination string. This value is owned by GLib and must not be freed. @@ -15227,7 +15263,7 @@ linked against at application run time. The minimum value which can be held in a #gint8. - + The minor version number of the GLib library. Like #gtk_minor_version, but from the headers used at @@ -15281,14 +15317,14 @@ variable, which could be before any statement in the case The `GMainContext` struct is an opaque data type representing a set of sources to be handled in a main loop. - Creates a new #GMainContext structure. + Creates a new [struct@GLib.MainContext] structure. the new #GMainContext - Creates a new #GMainContext structure. + Creates a new [struct@GLib.MainContext] structure. the new #GMainContext @@ -15306,12 +15342,13 @@ type representing a set of sources to be handled in a main loop. If some other thread is the owner of the context, returns %FALSE immediately. Ownership is properly recursive: the owner can require ownership again -and will release ownership when g_main_context_release() -is called as many times as g_main_context_acquire(). +and will release ownership when [method@GLib.MainContext.release] +is called as many times as [method@GLib.MainContext.acquire]. You must be the owner of a context before you -can call g_main_context_prepare(), g_main_context_query(), -g_main_context_check(), g_main_context_dispatch(), g_main_context_release(). +can call [method@GLib.MainContext.prepare], [method@GLib.MainContext.query], +[method@GLib.MainContext.check], [method@GLib.MainContext.dispatch], +[method@GLib.MainContext.release]. Since 2.76 @context can be %NULL to use the global-default main context. @@ -15331,7 +15368,7 @@ main context. Adds a file descriptor to the set of file descriptors polled for this context. This will very seldom be used directly. Instead -a typical event source will use g_source_add_unix_fd() instead. +a typical event source will use `g_source_add_unix_fd` instead. @@ -15348,8 +15385,8 @@ a typical event source will use g_source_add_unix_fd() instead. the priority for this file descriptor which should be - the same as the priority used for g_source_attach() to ensure that the - file descriptor is polled whenever the results may be needed. + the same as the priority used for [method@GLib.Source.attach] to ensure + that the file descriptor is polled whenever the results may be needed. @@ -15357,11 +15394,11 @@ a typical event source will use g_source_add_unix_fd() instead. Passes the results of polling back to the main loop. You should be careful to pass @fds and its length @n_fds as received from -g_main_context_query(), as this functions relies on assumptions +[method@GLib.MainContext.query], as this functions relies on assumptions on how @fds is filled. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. +[method@GLib.MainContext.acquire] before you may call this function. Since 2.76 @context can be %NULL to use the global-default main context. @@ -15381,13 +15418,13 @@ main context. array of #GPollFD's that was passed to - the last call to g_main_context_query() + the last call to [method@GLib.MainContext.query] - return value of g_main_context_query() + return value of [method@GLib.MainContext.query] @@ -15396,7 +15433,7 @@ main context. Dispatches all pending sources. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. +[method@GLib.MainContext.acquire] before you may call this function. Since 2.76 @context can be %NULL to use the global-default main context. @@ -15426,7 +15463,7 @@ the first one found will be returned. - the @source_funcs passed to g_source_new(). + the @source_funcs passed to [ctor@GLib.Source.new]. @@ -15443,7 +15480,7 @@ It is a programmer error to attempt to look up a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the @@ -15459,7 +15496,7 @@ wrong source. - the source ID, as returned by g_source_get_id(). + the source ID, as returned by [method@GLib.Source.get_id]. @@ -15485,7 +15522,7 @@ one found will be returned. - Gets the poll function set by g_main_context_set_poll_func(). + Gets the poll function set by [method@GLib.MainContext.set_poll_func]. the poll function @@ -15503,19 +15540,19 @@ one found will be returned. invocation of @function. If @context is %NULL then the global-default main context — as -returned by g_main_context_default() — is used. +returned by [func@GLib.MainContext.default] — is used. If @context is owned by the current thread, @function is called directly. Otherwise, if @context is the thread-default main context -of the current thread and g_main_context_acquire() succeeds, then -@function is called and g_main_context_release() is called +of the current thread and [method@GLib.MainContext.acquire] succeeds, then +@function is called and [method@GLib.MainContext.release] is called afterwards. In any other case, an idle source is created to call @function and that source is attached to @context (presumably to be run in another -thread). The idle source is attached with %G_PRIORITY_DEFAULT +thread). The idle source is attached with [const@GLib.PRIORITY_DEFAULT] priority. If you want a different priority, use -g_main_context_invoke_full(). +[method@GLib.MainContext.invoke_full]. Note that, as with normal idle functions, @function should probably return %FALSE. If it returns %TRUE, it will be continuously run in a @@ -15543,7 +15580,7 @@ loop (and may prevent this call from returning). Invokes a function in such a way that @context is owned during the invocation of @function. -This function is the same as g_main_context_invoke() except that it +This function is the same as [method@GLib.MainContext.invoke] except that it lets you specify the priority in case @function ends up being scheduled as an idle and also lets you give a #GDestroyNotify for @data. @@ -15578,7 +15615,7 @@ thread or with any particular context acquired. Determines whether this thread holds the (recursive) -ownership of this #GMainContext. This is useful to +ownership of this [struct@GLib.MainContext]. This is useful to know before waiting on another thread that may be blocking to get ownership of @context. @@ -15604,7 +15641,7 @@ events sources will be dispatched (if any), that are ready at this given moment without further waiting. Note that even when @may_block is %TRUE, it is still possible for -g_main_context_iteration() to return %FALSE, since the wait may +[method@GLib.MainContext.iteration] to return %FALSE, since the wait may be interrupted for other reasons than an event source becoming ready. %TRUE if events were dispatched. @@ -15652,10 +15689,10 @@ it was on the top of the stack). Prepares to poll sources within a main loop. The resulting information -for polling is determined by calling g_main_context_query (). +for polling is determined by calling [method@GLib.MainContext.query]. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. +[method@GLib.MainContext.acquire] before you may call this function. %TRUE if some source is ready to be dispatched prior to polling. @@ -15681,32 +15718,33 @@ current thread. This will cause certain asynchronous operations started in this thread to run under @context and deliver their results to its main loop, rather than running under the global default main context in the main thread. Note that calling this function -changes the context returned by g_main_context_get_thread_default(), -not the one returned by g_main_context_default(), so it does not affect -the context used by functions like g_idle_add(). +changes the context returned by [func@GLib.MainContext.get_thread_default], +not the one returned by [func@GLib.MainContext.default], so it does not +affect the context used by functions like [func@GLib.idle_add]. Normally you would call this function shortly after creating a new -thread, passing it a #GMainContext which will be run by a -#GMainLoop in that thread, to set a new default context for all +thread, passing it a [struct@GLib.MainContext] which will be run by a +[struct@GLib.MainLoop] in that thread, to set a new default context for all async operations in that thread. In this case you may not need to -ever call g_main_context_pop_thread_default(), assuming you want the -new #GMainContext to be the default for the whole lifecycle of the -thread. +ever call [method@GLib.MainContext.pop_thread_default], assuming you want +the new [struct@GLib.MainContext] to be the default for the whole lifecycle +of the thread. If you don't have control over how the new thread was created (e.g. in the new thread isn't newly created, or if the thread life cycle is managed by a #GThreadPool), it is always suggested to wrap -the logic that needs to use the new #GMainContext inside a -g_main_context_push_thread_default() / g_main_context_pop_thread_default() -pair, otherwise threads that are re-used will end up never explicitly -releasing the #GMainContext reference they hold. +the logic that needs to use the new [struct@GLib.MainContext] inside a +[method@GLib.MainContext.push_thread_default] / +[method@GLib.MainContext.pop_thread_default] pair, otherwise threads that +are re-used will end up never explicitly releasing the +[struct@GLib.MainContext] reference they hold. In some cases you may want to schedule a single operation in a non-default context, or temporarily use a non-default context in the main thread. In that case, you can wrap the call to the asynchronous operation inside a -g_main_context_push_thread_default() / -g_main_context_pop_thread_default() pair, but it is up to you to +[method@GLib.MainContext.push_thread_default] / +[method@GLib.MainContext.pop_thread_default] pair, but it is up to you to ensure that no other asynchronous operations accidentally get started while the non-default context is active. @@ -15724,14 +15762,63 @@ see g_file_supports_thread_contexts(). + + Push @main_context as the new thread-default main context for the current +thread, using [method@GLib.MainContext.push_thread_default], and return a +new [alias@GLib.MainContextPusher]. Pop with g_main_context_pusher_free(). +Using [method@GLib.MainContext.pop_thread_default] on @main_context while a +[alias@GLib.MainContextPusher] exists for it can lead to undefined behaviour. + +Using two [alias@GLib.MainContextPusher]s in the same scope is not allowed, +as it leads to an undefined pop order. + +This is intended to be used with g_autoptr(). Note that g_autoptr() +is only available when using GCC or clang, so the following example +will only work with those compilers: +|[ +typedef struct +{ + ... + GMainContext *context; + ... +} MyObject; + +static void +my_object_do_stuff (MyObject *self) +{ + g_autoptr(GMainContextPusher) pusher = g_main_context_pusher_new (self->context); + + // Code with main context as the thread default here + + if (cond) + // No need to pop + return; + + // Optionally early pop + g_clear_pointer (&pusher, g_main_context_pusher_free); + + // Code with main context no longer the thread default here +} +]| + + a #GMainContextPusher + + + + + a main context to push + + + + Determines information necessary to poll this main loop. You should be careful to pass the resulting @fds array and its length @n_fds -as is when calling g_main_context_check(), as this function relies +as is when calling [method@GLib.MainContext.check], as this function relies on assumptions made when the array is filled. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. +[method@GLib.MainContext.acquire] before you may call this function. the number of records actually stored in @fds, or, if more than @n_fds records need to be stored, the number @@ -15766,7 +15853,7 @@ g_main_context_acquire() before you may call this function. - Increases the reference count on a #GMainContext object by one. + Increases the reference count on a [struct@GLib.MainContext] object by one. the @context that was passed in (since 2.6) @@ -15780,12 +15867,12 @@ g_main_context_acquire() before you may call this function. Releases ownership of a context previously acquired by this thread -with g_main_context_acquire(). If the context was acquired multiple -times, the ownership will be released only when g_main_context_release() +with [method@GLib.MainContext.acquire]. If the context was acquired multiple +times, the ownership will be released only when [method@GLib.MainContext.release] is called as many times as it was acquired. You must have successfully acquired the context with -g_main_context_acquire() before you may call this function. +[method@GLib.MainContext.acquire] before you may call this function. @@ -15810,7 +15897,8 @@ polled for a particular context. - a #GPollFD descriptor previously added with g_main_context_add_poll() + a #GPollFD descriptor previously added with + [method@GLib.MainContext.add_poll] @@ -15839,7 +15927,8 @@ loop with an external event loop. - Decreases the reference count on a #GMainContext object by one. If + Decreases the reference count on a [struct@GLib.MainContext] object by one. +If the result is zero, free the context and free all associated memory. @@ -15853,11 +15942,12 @@ the result is zero, free the context and free all associated memory. Tries to become the owner of the specified context, -as with g_main_context_acquire(). But if another thread +as with [method@GLib.MainContext.acquire]. But if another thread is the owner, atomically drop @mutex and wait on @cond until that owner releases ownership or until @cond is signaled, then try again (once) to become the owner. - Use g_main_context_is_owner() and separate locking instead. + Use [method@GLib.MainContext.is_owner] and separate + locking instead. %TRUE if the operation succeeded, and this thread is now the owner of @context. @@ -15880,14 +15970,14 @@ try again (once) to become the owner. - If @context is currently blocking in g_main_context_iteration() + If @context is currently blocking in [method@GLib.MainContext.iteration] waiting for a source to become ready, cause it to stop blocking and return. Otherwise, cause the next invocation of -g_main_context_iteration() to return without blocking. +[method@GLib.MainContext.iteration] to return without blocking. -This API is useful for low-level control over #GMainContext; for +This API is useful for low-level control over [struct@GLib.MainContext]; for example, integrating it with main loop implementations such as -#GMainLoop. +[struct@GLib.MainLoop]. Another related use for this function is when implementing a main loop with a termination condition, computed from multiple threads: @@ -15923,7 +16013,7 @@ Then in a thread: Returns the global-default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the "main" main loop. See also -g_main_context_get_thread_default(). +[func@GLib.MainContext.get_thread_default]. the global-default main context. @@ -15933,37 +16023,54 @@ g_main_context_get_thread_default(). Gets the thread-default #GMainContext for this thread. Asynchronous operations that want to be able to be run in contexts other than the default one should call this method or -g_main_context_ref_thread_default() to get a #GMainContext to add -their #GSources to. (Note that even in single-threaded -programs applications may sometimes want to temporarily push a -non-default context, so it is not safe to assume that this will -always return %NULL if you are running in the default thread.) +[func@GLib.MainContext.ref_thread_default] to get a +[struct@GLib.MainContext] to add their [struct@GLib.Source]s to. (Note that +even in single-threaded programs applications may sometimes want to +temporarily push a non-default context, so it is not safe to assume that +this will always return %NULL if you are running in the default thread.) If you need to hold a reference on the context, use -g_main_context_ref_thread_default() instead. +[func@GLib.MainContext.ref_thread_default] instead. the thread-default #GMainContext, or %NULL if the thread-default context is the global-default main context. + + Pop @pusher’s main context as the thread default main context. +See g_main_context_pusher_new() for details. + +This will pop the [struct@GLib.MainContext] as the current thread-default +main context, but will not call [method@GLib.MainContext.unref] on it. + + + + + + a #GMainContextPusher + + + + - Gets the thread-default #GMainContext for this thread, as with -g_main_context_get_thread_default(), but also adds a reference to -it with g_main_context_ref(). In addition, unlike -g_main_context_get_thread_default(), if the thread-default context -is the global-default context, this will return that #GMainContext -(with a ref added to it) rather than returning %NULL. + Gets the thread-default [struct@GLib.MainContext] for this thread, as with +[func@GLib.MainContext.get_thread_default], but also adds a reference to +it with [method@GLib.MainContext.ref]. In addition, unlike +[func@GLib.MainContext.get_thread_default], if the thread-default context +is the global-default context, this will return that +[struct@GLib.MainContext] (with a ref added to it) rather than returning +%NULL. the thread-default #GMainContext. Unref - with g_main_context_unref() when you are done with it. + with [method@GLib.MainContext.unref] when you are done with it. - Flags to pass to g_main_context_new_with_flags() which affect the behaviour -of a #GMainContext. + Flags to pass to [ctor@GLib.MainContext.new_with_flags] which affect the +behaviour of a [struct@GLib.MainContext]. Default behaviour. @@ -15978,7 +16085,7 @@ other event loops. The `GMainLoop` struct is an opaque data type representing the main event loop of a GLib or GTK application. - Creates a new #GMainLoop structure. + Creates a new [struct@GLib.MainLoop] structure. a new #GMainLoop. @@ -15991,16 +16098,16 @@ representing the main event loop of a GLib or GTK application. set to %TRUE to indicate that the loop is running. This -is not very important since calling g_main_loop_run() will set this to -%TRUE anyway. +is not very important since calling [method@GLib.MainLoop.run] will set this +to %TRUE anyway. - Returns the #GMainContext of @loop. + Returns the [struct@GLib.MainContext] of @loop. - the #GMainContext of @loop + the [struct@GLib.MainContext] of @loop @@ -16011,7 +16118,8 @@ is not very important since calling g_main_loop_run() will set this to - Checks to see if the main loop is currently being run via g_main_loop_run(). + Checks to see if the main loop is currently being run via +[method@GLib.MainLoop.run]. %TRUE if the mainloop is currently being run. @@ -16024,11 +16132,11 @@ is not very important since calling g_main_loop_run() will set this to - Stops a #GMainLoop from running. Any calls to g_main_loop_run() -for the loop will return. + Stops a [struct@GLib.MainLoop] from running. Any calls to +[method@GLib.MainLoop.run] for the loop will return. Note that sources that have already been dispatched when -g_main_loop_quit() is called will still be executed. +[method@GLib.MainLoop.quit] is called will still be executed. @@ -16040,7 +16148,7 @@ g_main_loop_quit() is called will still be executed. - Increases the reference count on a #GMainLoop object by one. + Increases the reference count on a [struct@GLib.MainLoop] object by one. @loop @@ -16053,7 +16161,7 @@ g_main_loop_quit() is called will still be executed. - Runs a main loop until g_main_loop_quit() is called on the loop. + Runs a main loop until [method@GLib.MainLoop.quit] is called on the loop. If this is called for the thread of the loop's #GMainContext, it will process events from the loop, otherwise it will simply wait. @@ -16068,7 +16176,7 @@ simply wait. - Decreases the reference count on a #GMainLoop object by one. If + Decreases the reference count on a [struct@GLib.MainLoop] object by one. If the result is zero, free the loop and free all associated memory. @@ -16184,7 +16292,7 @@ Note that the contents may not be zero-terminated, even if the #GMappedFile is backed by a text file. If the file is empty then %NULL is returned. - + the contents of @file, or %NULL. @@ -16938,7 +17046,7 @@ so you cannot call this function after freeing the string. Retrieves the text matching the capturing parentheses named @name. If @name is a valid sub pattern name but it didn't match anything -(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") +(e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`) then an empty string is returned. The string is fetched from the string passed to the match function, @@ -16963,7 +17071,7 @@ so you cannot call this function after freeing the string. Retrieves the position in bytes of the capturing parentheses named @name. If @name is a valid sub pattern name but it didn't match anything -(e.g. sub pattern "X", matching "b" against "(?P<X>a)?b") +(e.g. sub pattern `"X"`, matching `"b"` against `"(?P<X>a)?b"`) then @start_pos and @end_pos are set to -1 and %TRUE is returned. %TRUE if the position was fetched, %FALSE otherwise. @@ -19313,6 +19421,41 @@ and all memory allocated by the @group is released. + + Yields a new preprocessor pasted identifier +@identifier1identifier2 from its expanded +arguments @identifier1 and @identifier2. For example, +the following code: +|[<!-- language="C" --> +#define GET(traveller,method) G_PASTE(traveller_get_, method) (traveller) +const gchar *name = GET (traveller, name); +const gchar *quest = GET (traveller, quest); +GdkColor *favourite = GET (traveller, favourite_colour); +]| + +is transformed by the preprocessor into: +|[<!-- language="C" --> +const gchar *name = traveller_get_name (traveller); +const gchar *quest = traveller_get_quest (traveller); +GdkColor *favourite = traveller_get_favourite_colour (traveller); +]| + + + an identifier + + + an identifier + + + + + + + + + + + Specifies one of the possible types of byte order (currently unused). See %G_BYTE_ORDER. @@ -19344,7 +19487,7 @@ when printing the @fd member of a #GPollFD. Use this for default priority event sources. In GLib this priority is used when adding timeout functions -with g_timeout_add(). In GDK this priority is used for events +with [func@GLib.timeout_add]. In GDK this priority is used for events from the X server. @@ -19352,7 +19495,7 @@ from the X server. Use this for default priority idle functions. In GLib this priority is used when adding idle functions with -g_idle_add(). +[func@GLib.idle_add]. @@ -22965,15 +23108,15 @@ freeing or modifying @string then the behaviour is undefined. Using the standard algorithm for regular expression matching only the longest match in the @string is retrieved, it is not possible to obtain all the available matches. For instance matching -"<a> <b> <c>" against the pattern "<.*>" -you get "<a> <b> <c>". +`"<a> <b> <c>"` against the pattern `"<.*>"` +you get `"<a> <b> <c>"`. This function uses a different algorithm (called DFA, i.e. deterministic finite automaton), so it can retrieve all the possible matches, all starting at the same point in the string. For instance matching -"<a> <b> <c>" against the pattern "<.*>;" -you would obtain three matches: "<a> <b> <c>", -"<a> <b>" and "<a>". +`"<a> <b> <c>"` against the pattern `"<.*>"` +you would obtain three matches: `"<a> <b> <c>"`, +`"<a> <b>"` and `"<a>"`. The number of matched strings is retrieved using g_match_info_get_match_count(). To obtain the matched strings and @@ -23135,13 +23278,13 @@ print_uppercase_words (const gchar *string) Replaces all occurrences of the pattern in @regex with the -replacement text. Backreferences of the form '\number' or -'\g<number>' in the replacement text are interpolated by the -number-th captured subexpression of the match, '\g<name>' refers -to the captured subexpression with the given name. '\0' refers -to the complete match, but '\0' followed by a number is the octal -representation of a character. To include a literal '\' in the -replacement, write '\\\\'. +replacement text. Backreferences of the form `\number` or +`\g<number>` in the replacement text are interpolated by the +number-th captured subexpression of the match, `\g<name>` refers +to the captured subexpression with the given name. `\0` refers +to the complete match, but `\0` followed by a number is the octal +representation of a character. To include a literal `\` in the +replacement, write `\\\\`. There are also escapes that changes the case of the following text: @@ -25080,20 +25223,21 @@ used is a stable sort. - Use this macro as the return value of a #GSourceFunc to leave -the #GSource in the main loop. + Use this macro as the return value of a [callback@GLib.SourceFunc] to leave +the [struct@GLib.Source] in the main loop. - Cast a function pointer to a #GSourceFunc, suppressing warnings from GCC 8 -onwards with `-Wextra` or `-Wcast-function-type` enabled about the function -types being incompatible. + Cast a function pointer to a [callback@GLib.SourceFunc], suppressing +warnings from GCC 8 onwards with `-Wextra` or `-Wcast-function-type` enabled +about the function types being incompatible. For example, the correct type of callback for a source created by -g_child_watch_source_new() is #GChildWatchFunc, which accepts more arguments -than #GSourceFunc. Casting the function with `(GSourceFunc)` to call -g_source_set_callback() will trigger a warning, even though it will be cast -back to the correct type before it is called by the source. +[func@GLib.child_watch_source_new] is #GChildWatchFunc, which accepts more +arguments than [callback@GLib.SourceFunc]. Casting the function with +`(GSourceFunc)` to call [method@GLib.Source.set_callback] will trigger a +warning, even though it will be cast back to the correct type before it is +called by the source. a function pointer. @@ -25101,14 +25245,51 @@ back to the correct type before it is called by the source. - Use this macro as the return value of a #GSourceFunc to remove -the #GSource from the main loop. + Use this macro as the return value of a [callback@GLib.SourceFunc] to remove +the [struct@GLib.Source] from the main loop. The square root of two. + + The G_STATIC_ASSERT() macro lets the programmer check +a condition at compile time, the condition needs to +be compile time computable. The macro can be used in +any place where a typedef is valid. + +A typedef is generally allowed in exactly the same places that +a variable declaration is allowed. For this reason, you should +not use G_STATIC_ASSERT() in the middle of blocks of code. + +The macro should only be used once per source code line. + + + a constant expression + + + + + The G_STATIC_ASSERT_EXPR() macro lets the programmer check +a condition at compile time. The condition needs to be +compile time computable. + +Unlike G_STATIC_ASSERT(), this macro evaluates to an expression +and, as such, can be used in the middle of other expressions. +Its value should be ignored. This can be accomplished by placing +it as the first argument of a comma expression. + +|[<!-- language="C" --> +#define ADD_ONE_TO_INT(x) \ + (G_STATIC_ASSERT_EXPR(sizeof (x) == sizeof (int)), ((x) + 1)) +]| + + + a constant expression + + + Accepts a macro or a string and converts it into a string after preprocessor argument expansion. For example, the following code: @@ -26800,13 +26981,13 @@ representing an event source. - Creates a new #GSource structure. The size is specified to -allow creating structures derived from #GSource that contain + Creates a new [struct@GLib.Source] structure. The size is specified to +allow creating structures derived from [struct@GLib.Source] that contain additional data. The size passed in must be at least `sizeof (GSource)`. The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be +and must be added to one with [method@GLib.Source.attach] before it will be executed. the newly-created #GSource. @@ -26819,15 +27000,15 @@ executed. - size of the #GSource structure to create. + size of the [struct@GLib.Source] structure to create. Adds @child_source to @source as a "polled" source; when @source is -added to a #GMainContext, @child_source will be automatically added -with the same priority, when @child_source is triggered, it will +added to a [struct@GLib.MainContext], @child_source will be automatically +added with the same priority, when @child_source is triggered, it will cause @source to dispatch (in addition to calling its own callback), and when @source is destroyed, it will destroy @child_source as well. (@source will also still be dispatched if @@ -26840,8 +27021,9 @@ callback that does nothing (except return %TRUE if appropriate). @source will hold a reference on @child_source while @child_source is attached to it. -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. +This API is only intended to be used by implementations of +[struct@GLib.Source]. Do not call this API on a [struct@GLib.Source] that +you did not create. @@ -26858,17 +27040,17 @@ Do not call this API on a #GSource that you did not create. Adds a file descriptor to the set of file descriptors polled for -this source. This is usually combined with g_source_new() to add an +this source. This is usually combined with [ctor@GLib.Source.new] to add an event source. The event source's check function will typically test the @revents field in the #GPollFD struct and return %TRUE if events need to be processed. -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. +This API is only intended to be used by implementations of [struct@GLib.Source]. +Do not call this API on a [struct@GLib.Source] that you did not create. Using this API forces the linear scanning of event sources on each main loop iteration. Newly-written event sources should try to use -g_source_add_unix_fd() instead of this API. +`g_source_add_unix_fd` instead of this API. @@ -26888,8 +27070,8 @@ g_source_add_unix_fd() instead of this API. Monitors @fd for the IO events in @events. The tag returned by this function can be used to remove or modify the -monitoring of the fd using g_source_remove_unix_fd() or -g_source_modify_unix_fd(). +monitoring of the fd using [method@GLib.Source.remove_unix_fd] or +[method@GLib.Source.modify_unix_fd]. It is not necessary to remove the fd before destroying the source; it will be cleaned up automatically. @@ -26918,8 +27100,8 @@ As the name suggests, this function is not available on Windows. - Adds a #GSource to a @context so that it will be executed within -that context. Remove it by calling g_source_destroy(). + Adds a [struct@GLib.Source] to a @context so that it will be executed within +that context. Remove it by calling [method@GLib.Source.destroy]. This function is safe to call from any thread, regardless of which thread the @context is running in. @@ -26941,20 +27123,21 @@ the @context is running in. - Removes a source from its #GMainContext, if any, and mark it as + Removes a source from its [struct@GLib.MainContext], if any, and mark it as destroyed. The source cannot be subsequently added to another context. It is safe to call this on sources which have already been removed from their context. -This does not unref the #GSource: if you still hold a reference, use -g_source_unref() to drop it. +This does not unref the [struct@GLib.Source]: if you still hold a reference, +use [method@GLib.Source.unref] to drop it. This function is safe to call from any thread, regardless of which thread -the #GMainContext is running in. +the [struct@GLib.MainContext] is running in. -If the source is currently attached to a #GMainContext, destroying it -will effectively unset the callback similar to calling g_source_set_callback(). -This can mean, that the data's #GDestroyNotify gets called right away. +If the source is currently attached to a [struct@GLib.MainContext], +destroying it will effectively unset the callback similar to calling +[method@GLib.Source.set_callback]. This can mean, that the data's +#GDestroyNotify gets called right away. @@ -26967,7 +27150,7 @@ This can mean, that the data's #GDestroyNotify gets called right away. Checks whether a source is allowed to be called recursively. -see g_source_set_can_recurse(). +see [method@GLib.Source.set_can_recurse]. whether recursion is allowed. @@ -26980,14 +27163,14 @@ see g_source_set_can_recurse(). - Gets the #GMainContext with which the source is associated. + Gets the [struct@GLib.MainContext] with which the source is associated. You can call this on a source that has been destroyed, provided -that the #GMainContext it was attached to still exists (in which -case it will return that #GMainContext). In particular, you can +that the [struct@GLib.MainContext] it was attached to still exists (in which +case it will return that [struct@GLib.MainContext]). In particular, you can always call this function on the source returned from -g_main_current_source(). But calling this function on a source -whose #GMainContext has been destroyed is an error. +[func@GLib.main_current_source]. But calling this function on a source +whose [struct@GLib.MainContext] has been destroyed is an error. the #GMainContext with which the source is associated, or %NULL if the context has not @@ -27003,8 +27186,8 @@ whose #GMainContext has been destroyed is an error. This function ignores @source and is otherwise the same as -g_get_current_time(). - use g_source_get_time() instead +[func@GLib.get_current_time]. + use [method@GLib.Source.get_time] instead @@ -27022,13 +27205,14 @@ g_get_current_time(). Returns the numeric ID for a particular source. The ID of a source is a positive integer which is unique within a particular main loop -context. The reverse -mapping from ID to source is done by g_main_context_find_source_by_id(). +context. The reverse mapping from ID to source is done by +[method@GLib.MainContext.find_source_by_id]. You can only call this function while the source is associated to a -#GMainContext instance; calling this function before g_source_attach() -or after g_source_destroy() yields undefined behavior. The ID returned -is unique within the #GMainContext instance passed to g_source_attach(). +[struct@GLib.MainContext] instance; calling this function before +[method@GLib.Source.attach] or after [method@GLib.Source.destroy] yields +undefined behavior. The ID returned is unique within the +[struct@GLib.MainContext] instance passed to [method@GLib.Source.attach]. the ID (greater than 0) for the source @@ -27042,7 +27226,7 @@ is unique within the #GMainContext instance passed to g_source_attach(). Gets a name for the source, used in debugging and profiling. The -name may be #NULL if it has never been set with g_source_set_name(). +name may be #NULL if it has never been set with [method@GLib.Source.set_name]. the name of the source @@ -27069,7 +27253,7 @@ name may be #NULL if it has never been set with g_source_set_name(). Gets the "ready time" of @source, as set by -g_source_set_ready_time(). +[method@GLib.Source.set_ready_time]. Any time before or equal to the current monotonic time (including 0) is an indication that the source will fire immediately. @@ -27086,12 +27270,12 @@ is an indication that the source will fire immediately. Gets the time to be used when checking this source. The advantage of -calling this function over calling g_get_monotonic_time() directly is +calling this function over calling [func@GLib.get_monotonic_time] directly is that when checking multiple sources, GLib can cache a single value instead of having to repeatedly get the system monotonic time. The time here is the system monotonic time, if available, or some -other reasonable alternative otherwise. See g_get_monotonic_time(). +other reasonable alternative otherwise. See [func@GLib.get_monotonic_time]. the monotonic time in microseconds @@ -27178,10 +27362,10 @@ idle_callback (gpointer data) ]| Calls to this function from a thread other than the one acquired by the -#GMainContext the #GSource is attached to are typically redundant, as the -source could be destroyed immediately after this function returns. However, -once a source is destroyed it cannot be un-destroyed, so this function can be -used for opportunistic checks from any thread. +[struct@GLib.MainContext] the #GSource is attached to are typically +redundant, as the source could be destroyed immediately after this function +returns. However, once a source is destroyed it cannot be un-destroyed, so +this function can be used for opportunistic checks from any thread. %TRUE if the source has been destroyed @@ -27196,10 +27380,10 @@ used for opportunistic checks from any thread. Updates the event mask to watch for the fd identified by @tag. -@tag is the tag returned from g_source_add_unix_fd(). +@tag is the tag returned from [method@GLib.Source.add_unix_fd]. If you want to remove a fd, don't set its event mask to zero. -Instead, call g_source_remove_unix_fd(). +Instead, call [method@GLib.Source.remove_unix_fd]. This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create. @@ -27214,7 +27398,7 @@ As the name suggests, this function is not available on Windows. - the tag from g_source_add_unix_fd() + the tag from [method@GLib.Source.add_unix_fd] @@ -27244,7 +27428,7 @@ As the name suggests, this function is not available on Windows. - the tag from g_source_add_unix_fd() + the tag from [method@GLib.Source.add_unix_fd] @@ -27277,7 +27461,7 @@ Do not call this API on a #GSource that you did not create. a #GSource previously passed to - g_source_add_child_source(). + [method@GLib.Source.add_child_source]. @@ -27286,8 +27470,8 @@ Do not call this API on a #GSource that you did not create. Removes a file descriptor from the set of file descriptors polled for this source. -This API is only intended to be used by implementations of #GSource. -Do not call this API on a #GSource that you did not create. +This API is only intended to be used by implementations of [struct@GLib.Source]. +Do not call this API on a [struct@GLib.Source] that you did not create. @@ -27297,13 +27481,13 @@ Do not call this API on a #GSource that you did not create. - a #GPollFD structure previously passed to g_source_add_poll(). + a #GPollFD structure previously passed to [method@GLib.Source.add_poll]. - Reverses the effect of a previous call to g_source_add_unix_fd(). + Reverses the effect of a previous call to [method@GLib.Source.add_unix_fd]. You only need to call this if you want to remove an fd from being watched while keeping the same source around. In the normal case you @@ -27322,7 +27506,7 @@ As the name suggests, this function is not available on Windows. - the tag from g_source_add_unix_fd() + the tag from [method@GLib.Source.add_unix_fd] @@ -27333,20 +27517,21 @@ called from the source's dispatch function. The exact type of @func depends on the type of source; ie. you should not count on @func being called with @data as its first -parameter. Cast @func with G_SOURCE_FUNC() to avoid warnings about +parameter. Cast @func with [func@GLib.SOURCE_FUNC] to avoid warnings about incompatible function types. See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle memory management of @data. Typically, you won't use this function. Instead use functions specific -to the type of source you are using, such as g_idle_add() or g_timeout_add(). +to the type of source you are using, such as [func@GLib.idle_add] or +[func@GLib.timeout_add]. It is safe to call this function multiple times on a source which has already been attached to a context. The changes will take effect for the next time the source is dispatched after this call returns. -Note that g_source_destroy() for a currently attached source has the effect +Note that [method@GLib.Source.destroy] for a currently attached source has the effect of also unsetting the callback. @@ -27373,7 +27558,7 @@ of also unsetting the callback. Sets the callback function storing the data as a refcounted callback "object". This is used internally. Note that calling -g_source_set_callback_indirect() assumes +[method@GLib.Source.set_callback_indirect] assumes an initial reference count on @callback_data, and thus @callback_funcs->unref will eventually be called once more than @callback_funcs->ref. @@ -27424,8 +27609,9 @@ source is blocked until the dispatch function returns. the reference count of @source reaches 0 but before any of the state of the source is freed, especially before the finalize function is called. -This means that at this point @source is still a valid #GSource and it is -allow for the reference count to increase again until @dispose returns. +This means that at this point @source is still a valid [struct@GLib.Source] +and it is allow for the reference count to increase again until @dispose +returns. The dispose function can be used to clear any "weak" references to the @source in other data structures in a thread-safe way where it is possible @@ -27481,11 +27667,11 @@ one could change the name in the "check" function of a #GSourceFuncs to include details like the event type in the source name. Use caution if changing the name while another thread may be -accessing it with g_source_get_name(); that function does not copy +accessing it with [method@GLib.Source.get_name]; that function does not copy the value, and changing the value will free it while the other thread may be attempting to use it. -Also see g_source_set_static_name(). +Also see [method@GLib.Source.set_static_name]. @@ -27542,7 +27728,7 @@ for both sources is reached during the same main context iteration, then the order of dispatch is undefined. It is a no-op to call this function on a #GSource which has already been -destroyed with g_source_destroy(). +destroyed with [method@GLib.Source.destroy]. This API is only intended to be used by implementations of #GSource. Do not call this API on a #GSource that you did not create. @@ -27562,7 +27748,7 @@ Do not call this API on a #GSource that you did not create. - A variant of g_source_set_name() that does not + A variant of [method@GLib.Source.set_name] that does not duplicate the @name, and can only be used with string literals. @@ -27595,20 +27781,21 @@ memory will be destroyed. Removes the source with the given ID from the default main context. You must -use g_source_destroy() for sources added to a non-default main context. +use [method@GLib.Source.destroy] for sources added to a non-default main context. -The ID of a #GSource is given by g_source_get_id(), or will be -returned by the functions g_source_attach(), g_idle_add(), -g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), -g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and -g_io_add_watch_full(). +The ID of a #GSource is given by [method@GLib.Source.get_id], or will be +returned by the functions [method@GLib.Source.attach], [func@GLib.idle_add], +[func@GLib.idle_add_full], [func@GLib.timeout_add], +[func@GLib.timeout_add_full], [func@GLib.child_watch_add], +[func@GLib.child_watch_add_full], [func@GLib.io_add_watch], and +[func@GLib.io_add_watch_full]. It is a programmer error to attempt to remove a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the @@ -27634,7 +27821,7 @@ same source functions and user data, only one will be destroyed. - The @source_funcs passed to g_source_new() + The @source_funcs passed to [ctor@GLib.Source.new] @@ -27662,7 +27849,7 @@ data, only one will be destroyed. Sets the name of a source using its ID. This is a convenience utility to set source names from the return -value of g_idle_add(), g_timeout_add(), etc. +value of [func@GLib.idle_add], [func@GLib.timeout_add], etc. It is a programmer error to attempt to set the name of a non-existent source. @@ -27670,7 +27857,7 @@ source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the @@ -27744,8 +27931,8 @@ functions for managing callback objects. - Dispose function for @source. See g_source_set_dispose_function() for -details. + Dispose function for @source. See [method@GLib.Source.set_dispose_function] +for details. @@ -27764,15 +27951,17 @@ which cannot be used here for dependency reasons. - Specifies the type of function passed to g_timeout_add(), -g_timeout_add_full(), g_idle_add(), and g_idle_add_full(). + Specifies the type of function passed to [func@GLib.timeout_add], +[func@GLib.timeout_add_full], [func@GLib.idle_add], and +[func@GLib.idle_add_full]. -When calling g_source_set_callback(), you may need to cast a function of a -different type to this type. Use G_SOURCE_FUNC() to avoid warnings about -incompatible function types. +When calling [method@GLib.Source.set_callback], you may need to cast a +function of a different type to this type. Use [func@GLib.SOURCE_FUNC] to +avoid warnings about incompatible function types. - %FALSE if the source should be removed. %G_SOURCE_CONTINUE and -%G_SOURCE_REMOVE are more memorable names for the return value. + %FALSE if the source should be removed. +[const@GLib.SOURCE_CONTINUE] and [const@GLib.SOURCE_REMOVE] are more +memorable names for the return value. @@ -27832,18 +28021,20 @@ required condition has been met, and returns %TRUE if so. %TRUE in either its @prepare or its @check function, or if a ready time has been reached. The @dispatch function receives a callback function and user data. The callback function may be %NULL if the source was never - connected to a callback using g_source_set_callback(). The @dispatch - function should call the callback function with @user_data and whatever - additional parameters are needed for this type of event source. The - return value of the @dispatch function should be %G_SOURCE_REMOVE if the - source should be removed or %G_SOURCE_CONTINUE to keep it. + connected to a callback using [method@GLib.Source.set_callback]. The + @dispatch function should call the callback function with @user_data and + whatever additional parameters are needed for this type of event source. + The return value of the @dispatch function should be + [const@GLib.SOURCE_REMOVE] if the source should be removed or + [const@GLib.SOURCE_CONTINUE] to keep it. Called when the source is finalized. At this point, the source will have been destroyed, had its callback cleared, and have been removed - from its #GMainContext, but it will still have its final reference count, - so methods can be called on it from within this function. + from its [struct@GLib.MainContext], but it will still have its final + reference count, so methods can be called on it from within this + function. @@ -27957,7 +28148,7 @@ function always returns `FALSE` with a timeout of `-1`. A source function that is only called once before being removed from the main context automatically. -See: g_idle_add_once(), g_timeout_add_once() +See: [func@GLib.idle_add_once], [func@GLib.timeout_add_once] @@ -30584,15 +30775,17 @@ but nothing happens except for the first call. Since version 2.32, GLib does not support custom thread implementations anymore and the @vtable parameter is ignored and you should pass %NULL. -<note><para>g_thread_init() must not be called directly or indirectly -in a callback from GLib. Also no mutexes may be currently locked while -calling g_thread_init().</para></note> - -<note><para>To use g_thread_init() in your program, you have to link -with the libraries that the command <command>pkg-config --libs -gthread-2.0</command> outputs. This is not the case for all the -other thread-related functions of GLib. Those can be used without -having to link with the thread libraries.</para></note> +::: note + g_thread_init() must not be called directly or indirectly in a + callback from GLib. Also no mutexes may be currently locked + while calling g_thread_init(). + +::: note + To use g_thread_init() in your program, you have to link with + the libraries that the command `pkg-config --libs gthread-2.0` + outputs. This is not the case for all the other thread-related + functions of GLib. Those can be used without having to link + with the thread libraries. This function is no longer necessary. The GLib threading system is automatically initialized at the start of your program. @@ -32306,16 +32499,38 @@ stopped. Specifies the type of traversal performed by g_tree_traverse(), -g_node_traverse() and g_node_find(). The different orders are -illustrated here: +g_node_traverse() and g_node_find(). + +The different orders are illustrated here: + - In order: A, B, C, D, E, F, G, H, I - ![](Sorted_binary_tree_inorder.svg) + <picture> + <source srcset="Sorted_binary_tree_inorder-dark.svg" + media="(prefers-color-scheme: dark)"> + <img src="Sorted_binary_tree_inorder.svg" + alt="Sorted binary tree, in-order traversal"> + </picture> - Pre order: F, B, A, D, C, E, G, I, H - ![](Sorted_binary_tree_preorder.svg) + <picture> + <source srcset="Sorted_binary_tree_preorder-dark.svg" + media="(prefers-color-scheme: dark)"> + <img src="Sorted_binary_tree_preorder.svg" + alt="Sorted binary tree, pre-order traversal"> + </picture> - Post order: A, C, E, D, B, H, I, G, F - ![](Sorted_binary_tree_postorder.svg) + <picture> + <source srcset="Sorted_binary_tree_postorder-dark.svg" + media="(prefers-color-scheme: dark)"> + <img src="Sorted_binary_tree_postorder.svg" + alt="Sorted binary tree, post-order traversal"> + </picture> - Level order: F, B, G, A, D, I, C, E, H - ![](Sorted_binary_tree_breadth-first_traversal.svg) + <picture> + <source srcset="Sorted_binary_tree_breadth-first_traversal-dark.svg" + media="(prefers-color-scheme: dark)"> + <img src="Sorted_binary_tree_breadth-first_traversal.svg" + alt="Sorted binary tree, breadth-first level order traversal"> + </picture> vists a node's left child first, then the node itself, then its right child. This is the one to use if you @@ -33983,6 +34198,132 @@ on compilers that support that feature. + + Close both ends of the pipe, unless they have already been closed or +stolen. Any errors are ignored: use g_unix_pipe_close() or g_clear_fd() +if error-handling is required. + +This function is async-signal safe if @error is %NULL and each member +of @fds are either negative or a valid open file descriptor. +As a result, it is safe to call this function or use `g_auto(GUnixPipe)` +(on compilers that support it) in a signal handler or a +#GSpawnChildSetupFunc, as long as those conditions are ensured to be true. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + +This function preserves the value of `errno`. + + + + + + a #GUnixPipe + + + + + + Close one of the ends of the pipe and set the relevant member of @fds +to `-1` before returning, equivalent to g_clear_fd(). + +Like g_close(), if closing the file descriptor fails, the error is +stored in both %errno and @error. If this function succeeds, +%errno is undefined. + +This function is async-signal safe if @error is %NULL and the relevant +member of @fds is either negative or a valid open file descriptor. +This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc +under those conditions. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + +To close both file descriptors and ignore any errors, use +g_unix_pipe_clear() instead. + + %TRUE on success + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + + + Return one of the ends of the pipe. It remains owned by @self. + +This function is async-signal safe (see [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a +signal handler or a #GSpawnChildSetupFunc. + +This function preserves the value of `errno`. + + a non-negative file descriptor owned by @self, which must not + be closed by the caller, or a negative number if the corresponding + end of the pipe was already closed or stolen + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + + + Open a pipe. This is the same as g_unix_open_pipe(), but uses the +#GUnixPipe data structure. + + %TRUE on success + + + + + A pair of file descriptors + + + + Flags to pass to g_unix_open_pipe(), typically `O_CLOEXEC` + + + + + + Return one of the ends of the pipe. It becomes owned by the caller, +and the file descriptor in the data structure is set to `-1`, +similar to g_steal_fd(). + +This function is async-signal safe (see [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a +signal handler or a #GSpawnChildSetupFunc. + +This function preserves the value of `errno`. + + a non-negative file descriptor, which becomes owned by the + caller and must be closed by the caller if required, or a negative + number if the corresponding end of the pipe was already closed or stolen + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + Mnemonic constants for the ends of a Unix pipe. @@ -35546,7 +35887,7 @@ functions, then using functions that were deprecated in version using functions deprecated in later releases will not). - + `GVariant` is a variant datatype; it can contain one or more values along with information about the type of the values. @@ -38097,7 +38438,7 @@ any other call. In most cases it is easier to place a #GVariantBuilder directly on the stack of the calling function and initialise it with -g_variant_builder_init(). +g_variant_builder_init_static(). a #GVariantBuilder @@ -38128,7 +38469,7 @@ make_pointless_dictionary (void) GVariantBuilder builder; int i; - g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); + g_variant_builder_init_static (&builder, G_VARIANT_TYPE_ARRAY); for (i = 0; i < 16; i++) { gchar buf[3]; @@ -38178,7 +38519,7 @@ make_pointless_dictionary (void) GVariantBuilder builder; int i; - g_variant_builder_init (&builder, G_VARIANT_TYPE_ARRAY); + g_variant_builder_init_static (&builder, G_VARIANT_TYPE_ARRAY); g_variant_builder_add_parsed (&builder, "{'width', <%i>}", 600); g_variant_builder_add_parsed (&builder, "{'title', <%s>}", "foo"); g_variant_builder_add_parsed (&builder, "{'transparency', <0.5>}"); @@ -38308,6 +38649,10 @@ construct. It can be an indefinite type such as Maybe, array, tuple, dictionary entry and variant-typed values may be constructed. +If using a static type such as one of the `G_VARIANT_TYPE_*` constants +or a `G_VARIANT_TYPE ("(ii)")` macro, it is more performant to use +g_variant_builder_init_static() rather than g_variant_builder_init(). + After the builder is initialised, values are added using g_variant_builder_add_value() or g_variant_builder_add(). @@ -38343,6 +38688,27 @@ this function. + + Initialises a #GVariantBuilder structure. + +This function works exactly like g_variant_builder_init() but does +not make a copy of @type. Therefore, @type must remain valid for the +lifetime of @builder. This is always true of type constants like +`G_VARIANT_TYPE_*` or `G_VARIANT_TYPE ("(ii)")`. + + + + + + a #GVariantBuilder + + + + a container type + + + + Opens a subcontainer inside the given @builder. When done adding items to the subcontainer, g_variant_builder_close() must be called. @type @@ -43394,24 +43760,25 @@ not supported. Sets a function to be called when the child indicated by @pid -exits, at a default priority, %G_PRIORITY_DEFAULT. +exits, at a default priority, [const@GLib.PRIORITY_DEFAULT]. -If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() -you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to -the spawn function for the child watching to work. +If you obtain @pid from [func@GLib.spawn_async] or +[func@GLib.spawn_async_with_pipes] you will need to pass +%G_SPAWN_DO_NOT_REAP_CHILD as flag to the spawn function for the child +watching to work. Note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the +(see [func@GLib.spawn_close_pid]) @pid must not be closed while the source is still active. Typically, you will want to call -g_spawn_close_pid() in the callback function for the source. +[func@GLib.spawn_close_pid] in the callback function for the source. GLib supports only a single callback per process id. On POSIX platforms, the same restrictions mentioned for -g_child_watch_source_new() apply to this function. +[func@GLib.child_watch_source_new] apply to this function. This internally creates a main loop source using -g_child_watch_source_new() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you +[func@GLib.child_watch_source_new] and attaches it to the main loop context +using [method@GLib.Source.attach]. You can do these steps manually if you need greater control. the ID (greater than 0) of the event source. @@ -43438,26 +43805,27 @@ need greater control. Sets a function to be called when the child indicated by @pid exits, at the priority @priority. -If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() -you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to -the spawn function for the child watching to work. +If you obtain @pid from [func@GLib.spawn_async] or +[func@GLib.spawn_async_with_pipes] you will need to pass +%G_SPAWN_DO_NOT_REAP_CHILD as flag to the spawn function for the child +watching to work. -In many programs, you will want to call g_spawn_check_wait_status() +In many programs, you will want to call [func@GLib.spawn_check_wait_status] in the callback to determine whether or not the child exited successfully. Also, note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the source -is still active. Typically, you should invoke g_spawn_close_pid() +(see [func@GLib.spawn_close_pid]) @pid must not be closed while the source +is still active. Typically, you should invoke [func@GLib.spawn_close_pid] in the callback function for the source. GLib supports only a single callback per process id. On POSIX platforms, the same restrictions mentioned for -g_child_watch_source_new() apply to this function. +[func@GLib.child_watch_source_new] apply to this function. This internally creates a main loop source using -g_child_watch_source_new() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you +[func@GLib.child_watch_source_new] and attaches it to the main loop context +using [method@GLib.Source.attach]. You can do these steps manually if you need greater control. the ID (greater than 0) of the event source. @@ -43466,7 +43834,8 @@ need greater control. the priority of the idle source. Typically this will be in the - range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. + range between [const@GLib.PRIORITY_DEFAULT_IDLE] and + [const@GLib.PRIORITY_HIGH_IDLE]. @@ -43491,17 +43860,17 @@ Windows a handle for a process (which doesn't have to be a child). Creates a new child_watch source. -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. +The source will not initially be associated with any +[struct@GLib.MainContext] and must be added to one with +[method@GLib.Source.attach] before it will be executed. Note that child watch sources can only be used in conjunction with `g_spawn...` when the %G_SPAWN_DO_NOT_REAP_CHILD flag is used. Note that on platforms where #GPid must be explicitly closed -(see g_spawn_close_pid()) @pid must not be closed while the +(see [func@GLib.spawn_close_pid]) @pid must not be closed while the source is still active. Typically, you will want to call -g_spawn_close_pid() in the callback function for the source. +[func@GLib.spawn_close_pid] in the callback function for the source. On POSIX platforms, the following restrictions apply to this API due to limitations in POSIX process interfaces: @@ -43516,8 +43885,8 @@ due to limitations in POSIX process interfaces: * the application must not ignore `SIGCHLD` * Before 2.78, the application could not send a signal (`kill()`) to the watched @pid in a race free manner. Since 2.78, you can do that while the - associated #GMainContext is acquired. -* Before 2.78, even after destroying the #GSource, you could not + associated [struct@GLib.MainContext] is acquired. +* Before 2.78, even after destroying the [struct@GLib.Source], you could not be sure that @pid wasn't already reaped. Hence, it was also not safe to `kill()` or `waitpid()` on the process ID after the child watch source was gone. Destroying the source before it fired made it @@ -43599,13 +43968,77 @@ calls g_error_free() on *@err and sets *@err to %NULL. + + If @fd_ptr points to a file descriptor, close it and return +whether closing it was successful, like g_close(). +If @fd_ptr points to a negative number, return %TRUE without closing +anything. +In both cases, set @fd_ptr to `-1` before returning. + +Like g_close(), if closing the file descriptor fails, the error is +stored in both %errno and @error. If this function succeeds, +%errno is undefined. + +On POSIX platforms, this function is async-signal safe +if @error is %NULL and @fd_ptr points to either a negative number or a +valid open file descriptor. +This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc +under those conditions. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + +It is a programming error for @fd_ptr to point to a non-negative +number that is not a valid file descriptor. + +A typical use of this function is to clean up a file descriptor at +the end of its scope, whether it has been set successfully or not: + +|[ +gboolean +operate_on_fd (GError **error) +{ + gboolean ret = FALSE; + int fd = -1; + + fd = open_a_fd (error); + + if (fd < 0) + goto out; + + if (!do_something (fd, error)) + goto out; + + if (!g_clear_fd (&fd, error)) + goto out; + + ret = TRUE; + +out: + // OK to call even if fd was never opened or was already closed + g_clear_fd (&fd, NULL); + return ret; +} +]| + +This function is also useful in conjunction with #g_autofd. + + %TRUE on success + + + + + a pointer to a file descriptor + + + + Clears a numeric handler, such as a #GSource ID. @tag_ptr must be a valid pointer to the variable holding the handler. If the ID is zero then this function does nothing. -Otherwise, clear_func() is called with the ID as a parameter, and the tag is +Otherwise, @clear_func is called with the ID as a parameter, and the tag is set to zero. A macro is also included that allows this function to be used without @@ -44945,7 +45378,7 @@ For example, don't expect that using g_date_strftime() would make the \%F provided by the C99 strftime() work on Windows where the C library only complies to C89. - number of characters written to the buffer, or 0 the buffer was too small + number of characters written to the buffer, or `0` if the buffer was too small @@ -46457,9 +46890,9 @@ the current directory is the target of a symbolic link. Equivalent to the UNIX gettimeofday() function, but portable. -You may find g_get_real_time() to be more convenient. - #GTimeVal is not year-2038-safe. Use g_get_real_time() - instead. +You may find [func@GLib.get_real_time] to be more convenient. + #GTimeVal is not year-2038-safe. Use + [func@GLib.get_real_time] instead. @@ -46728,12 +47161,12 @@ returned. Queries the system wall-clock time. -This call is functionally equivalent to g_get_current_time() except +This call is functionally equivalent to [func@GLib.get_current_time] except that the return value is often more convenient than dealing with a #GTimeVal. You should only use this call if you are actually interested in the real -wall-clock time. g_get_monotonic_time() is probably more useful for +wall-clock time. [func@GLib.get_monotonic_time] is probably more useful for measuring intervals. the number of microseconds since January 1, 1970 UTC. @@ -47604,8 +48037,9 @@ You can pass %NULL for @lookup_key, provided the hash and equal functions of @hash_table are %NULL-safe. The dictionary implementation optimizes for having all values identical to -their keys, for example by using g_hash_table_add(). When stealing both the -key and the value from such a dictionary, the value will be %NULL. +their keys, for example by using g_hash_table_add(). Before 2.82, when +stealing both the key and the value from such a dictionary, the value was +%NULL. Since 2.82, the returned value and key will be the same. %TRUE if the key was found in the #GHashTable @@ -47972,18 +48406,18 @@ more convenient than the raw iconv wrappers. Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the -default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function +default idle priority, [const@GLib.PRIORITY_DEFAULT_IDLE]. If the function returns %FALSE it is automatically removed from the list of event sources and will not be called again. See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. -This internally creates a main loop source using g_idle_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. +This internally creates a main loop source using [func@GLib.idle_source_new] +and attaches it to the global [struct@GLib.MainContext] using +[method@GLib.Source.attach], so the callback will be invoked in whichever +thread is running that main context. You can do these steps manually if you +need greater control or to use a custom main context. the ID (greater than 0) of the event source. @@ -48003,17 +48437,17 @@ use a custom main context. Adds a function to be called whenever there are no higher priority events pending. -If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically +If the function returns [const@GLib.SOURCE_REMOVE] or %FALSE it is automatically removed from the list of event sources and will not be called again. See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. -This internally creates a main loop source using g_idle_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. +This internally creates a main loop source using [func@GLib.idle_source_new] +and attaches it to the global [struct@GLib.MainContext] using +[method@GLib.Source.attach], so the callback will be invoked in whichever +thread is running that main context. You can do these steps manually if you +need greater control or to use a custom main context. the ID (greater than 0) of the event source. @@ -48021,7 +48455,8 @@ use a custom main context. the priority of the idle source. Typically this will be in the - range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. + range between [const@GLib.PRIORITY_DEFAULT_IDLE] and + [const@GLib.PRIORITY_HIGH_IDLE]. @@ -48041,12 +48476,12 @@ use a custom main context. Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the -default idle priority, %G_PRIORITY_DEFAULT_IDLE. +default idle priority, [const@GLib.PRIORITY_DEFAULT_IDLE]. The function will only be called once and then the source will be automatically removed from the main context. -This function otherwise behaves like g_idle_add(). +This function otherwise behaves like [func@GLib.idle_add]. the ID (greater than 0) of the event source @@ -48078,11 +48513,12 @@ This function otherwise behaves like g_idle_add(). Creates a new idle source. -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. Note that the default priority for idle sources is -%G_PRIORITY_DEFAULT_IDLE, as compared to other sources which -have a default priority of %G_PRIORITY_DEFAULT. +The source will not initially be associated with any +[struct@GLib.MainContext] and must be added to one with +[method@GLib.Source.attach] before it will be executed. Note that the +default priority for idle sources is [const@GLib.PRIORITY_DEFAULT_IDLE], as +compared to other sources which have a default priority of +[const@GLib.PRIORITY_DEFAULT]. the newly-created idle source @@ -49497,7 +49933,7 @@ See your C library manual for more details about lstat(). Returns the global-default main context. This is the main context used for main loop functions when a main loop is not explicitly specified, and corresponds to the "main" main loop. See also -g_main_context_get_thread_default(). +[func@GLib.MainContext.get_thread_default]. the global-default main context. @@ -49507,14 +49943,14 @@ g_main_context_get_thread_default(). Gets the thread-default #GMainContext for this thread. Asynchronous operations that want to be able to be run in contexts other than the default one should call this method or -g_main_context_ref_thread_default() to get a #GMainContext to add -their #GSources to. (Note that even in single-threaded -programs applications may sometimes want to temporarily push a -non-default context, so it is not safe to assume that this will -always return %NULL if you are running in the default thread.) +[func@GLib.MainContext.ref_thread_default] to get a +[struct@GLib.MainContext] to add their [struct@GLib.Source]s to. (Note that +even in single-threaded programs applications may sometimes want to +temporarily push a non-default context, so it is not safe to assume that +this will always return %NULL if you are running in the default thread.) If you need to hold a reference on the context, use -g_main_context_ref_thread_default() instead. +[func@GLib.MainContext.ref_thread_default] instead. the thread-default #GMainContext, or %NULL if the thread-default context is the global-default main context. @@ -49522,15 +49958,16 @@ g_main_context_ref_thread_default() instead. - Gets the thread-default #GMainContext for this thread, as with -g_main_context_get_thread_default(), but also adds a reference to -it with g_main_context_ref(). In addition, unlike -g_main_context_get_thread_default(), if the thread-default context -is the global-default context, this will return that #GMainContext -(with a ref added to it) rather than returning %NULL. + Gets the thread-default [struct@GLib.MainContext] for this thread, as with +[func@GLib.MainContext.get_thread_default], but also adds a reference to +it with [method@GLib.MainContext.ref]. In addition, unlike +[func@GLib.MainContext.get_thread_default], if the thread-default context +is the global-default context, this will return that +[struct@GLib.MainContext] (with a ref added to it) rather than returning +%NULL. the thread-default #GMainContext. Unref - with g_main_context_unref() when you are done with it. + with [method@GLib.MainContext.unref] when you are done with it. @@ -49543,11 +49980,11 @@ is the global-default context, this will return that #GMainContext Returns the depth of the stack of calls to -g_main_context_dispatch() on any #GMainContext in the current thread. +[method@GLib.MainContext.dispatch] on any #GMainContext in the current thread. That is, when called from the toplevel, it gives 0. When -called from within a callback from g_main_context_iteration() -(or g_main_loop_run(), etc.) it returns 1. When called from within -a callback to a recursive call to g_main_context_iteration(), +called from within a callback from [method@GLib.MainContext.iteration] +(or [method@GLib.MainLoop.run], etc.) it returns 1. When called from within +a callback to a recursive call to [method@GLib.MainContext.iteration], it returns 2. And so forth. This function is useful in a situation like the following: @@ -49588,7 +50025,7 @@ thing from a library, it gets more difficult, since you no longer control the main loop. You might think you can simply use an idle function to make the call to free_allocated_memory(), but that doesn't work, since the idle function could be called from a -recursive callback. This can be fixed by using g_main_depth() +recursive callback. This can be fixed by using [func@GLib.main_depth] |[<!-- language="C" --> gpointer @@ -49623,12 +50060,12 @@ free_allocated_memory (void) } ]| -There is a temptation to use g_main_depth() to solve +There is a temptation to use [func@GLib.main_depth] to solve problems with reentrancy. For instance, while waiting for data to be received from the network in response to a menu item, the menu item might be selected again. It might seem that one could make the menu item's callback return immediately -and do nothing if g_main_depth() returns a value greater than 1. +and do nothing if [func@GLib.main_depth] returns a value greater than 1. However, this should be avoided since the user then sees selecting the menu item do nothing. Furthermore, you'll find yourself adding these checks all over your code, since there are doubtless many, @@ -52143,6 +52580,28 @@ g_ref_count_init() to be used again. + + Compares two ref-counted strings for byte-by-byte equality. + +It can be passed to [func@GLib.HashTable.new] as the key equality function, +and behaves exactly the same as [func@GLib.str_equal] (or `strcmp()`), but +can return slightly faster as it can check the string lengths before checking +all the bytes. + + `TRUE` if the strings are equal, otherwise `FALSE` + + + + + a reference counted string + + + + a reference counted string + + + + Retrieves the length of @str. @@ -53001,6 +53460,45 @@ Before GLib 2.76, this was `NULL`. + + Updates a pointer to a string to a copy of @new_str and returns whether the +string was changed. + +If @new_str matches the previous string, this function is a no-op. If +@new_str is different, a copy of it will be assigned to @str_pointer and +the previous string pointed to by @str_pointer will be freed with +[func@GLib.free]. + +@str_pointer must not be `NULL`, but can point to a `NULL` value. + +One convenient usage of this function is in implementing property settings: +```C +void +foo_set_bar (Foo *foo, + const char *new_bar) +{ + g_return_if_fail (IS_FOO (foo)); + + if (g_set_str (&foo->bar, new_bar)) + g_object_notify (foo, "bar"); +} +``` + + true if the value of @str_pointer changed, false otherwise + + + + + a pointer to either + a string or `NULL` + + + + a string to assign to @str_pointer + + + + Sets an environment variable. On UNIX, both the variable's name and value can be arbitrary byte strings, except that the variable's name @@ -53520,7 +54018,7 @@ the Single Unix Specification. - + This is just like the standard C [`qsort()`](man:qsort(3)) function, but the comparison routine accepts a user data argument (like [`qsort_r()`](man:qsort_r(3))). @@ -53556,20 +54054,21 @@ Unlike `qsort()`, this is guaranteed to be a stable sort. Removes the source with the given ID from the default main context. You must -use g_source_destroy() for sources added to a non-default main context. +use [method@GLib.Source.destroy] for sources added to a non-default main context. -The ID of a #GSource is given by g_source_get_id(), or will be -returned by the functions g_source_attach(), g_idle_add(), -g_idle_add_full(), g_timeout_add(), g_timeout_add_full(), -g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and -g_io_add_watch_full(). +The ID of a #GSource is given by [method@GLib.Source.get_id], or will be +returned by the functions [method@GLib.Source.attach], [func@GLib.idle_add], +[func@GLib.idle_add_full], [func@GLib.timeout_add], +[func@GLib.timeout_add_full], [func@GLib.child_watch_add], +[func@GLib.child_watch_add_full], [func@GLib.io_add_watch], and +[func@GLib.io_add_watch_full]. It is a programmer error to attempt to remove a non-existent source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the @@ -53595,7 +54094,7 @@ same source functions and user data, only one will be destroyed. - The @source_funcs passed to g_source_new() + The @source_funcs passed to [ctor@GLib.Source.new] @@ -53623,7 +54122,7 @@ data, only one will be destroyed. Sets the name of a source using its ID. This is a convenience utility to set source names from the return -value of g_idle_add(), g_timeout_add(), etc. +value of [func@GLib.idle_add], [func@GLib.timeout_add], etc. It is a programmer error to attempt to set the name of a non-existent source. @@ -53631,7 +54130,7 @@ source. More specifically: source IDs can be reissued after a source has been destroyed and therefore it is never valid to use this function with a source ID which may have already been removed. An example is when -scheduling an idle to run in another thread with g_idle_add(): the +scheduling an idle to run in another thread with [func@GLib.idle_add]: the idle may already have run and been removed by the time this function is called on its (now invalid) source ID. This source ID may have been reissued, leading to the operation being performed against the @@ -54482,7 +54981,69 @@ See your C library manual for more details about stat(). - + + Sets @fd_ptr to `-1`, returning the value that was there before. + +Conceptually, this transfers the ownership of the file descriptor +from the referenced variable to the caller of the function (i.e. +‘steals’ the reference). This is very similar to [func@GLib.steal_pointer], +but for file descriptors. + +On POSIX platforms, this function is async-signal safe +(see [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a +signal handler or a #GSpawnChildSetupFunc. + +This function preserves the value of `errno`. + + the value that @fd_ptr previously had + + + + + A pointer to a file descriptor + + + + + + Sets @handle_pointer to `0`, returning the value that was there before. + +Conceptually, this transfers the ownership of the handle ID from the +referenced variable to the ‘caller’ of the macro (ie: ‘steals’ the +handle ID). + +This can be very useful to make ownership transfer explicit, or to prevent +a handle from being released multiple times. For example: + +```c +void +maybe_unsubscribe_signal (ContextStruct *data) +{ + if (some_complex_logic (data)) + { + g_dbus_connection_signal_unsubscribe (data->connection, + g_steal_handle_id (&data->subscription_id)); + // now data->subscription_id isn’t a dangling handle + } +} +``` + +While [func@GLib.clear_handle_id] can be used in many of the same situations +as `g_steal_handle_id()`, this is one situation where it cannot be used, as +there is no way to pass the `GDBusConnection` to a +[type@GLib.ClearHandleFunc]. + + + + + + a pointer to a handle ID + + + + + Sets @pp to %NULL, returning the value that was there before. Conceptually, this transfers the ownership of the pointer from the @@ -54531,12 +55092,16 @@ get_object (GObject **obj_out) In the above example, the object will be automatically freed in the early error case and also in the case that %NULL was given for @obj_out. + + + - + a pointer to a pointer + - + Copies a nul-terminated string into the destination buffer, including the trailing nul byte, and returns a pointer to the trailing nul byte @@ -57207,15 +57772,17 @@ but nothing happens except for the first call. Since version 2.32, GLib does not support custom thread implementations anymore and the @vtable parameter is ignored and you should pass %NULL. -<note><para>g_thread_init() must not be called directly or indirectly -in a callback from GLib. Also no mutexes may be currently locked while -calling g_thread_init().</para></note> - -<note><para>To use g_thread_init() in your program, you have to link -with the libraries that the command <command>pkg-config --libs -gthread-2.0</command> outputs. This is not the case for all the -other thread-related functions of GLib. Those can be used without -having to link with the thread libraries.</para></note> +::: note + g_thread_init() must not be called directly or indirectly in a + callback from GLib. Also no mutexes may be currently locked + while calling g_thread_init(). + +::: note + To use g_thread_init() in your program, you have to link with + the libraries that the command `pkg-config --libs gthread-2.0` + outputs. This is not the case for all the other thread-related + functions of GLib. Those can be used without having to link + with the thread libraries. This function is no longer necessary. The GLib threading system is automatically initialized at the start of your program. @@ -57382,12 +57949,12 @@ g_date_time_unref (dt); Sets a function to be called at regular intervals, with the default -priority, %G_PRIORITY_DEFAULT. +priority, [const@GLib.PRIORITY_DEFAULT]. -The given @function is called repeatedly until it returns %G_SOURCE_REMOVE -or %FALSE, at which point the timeout is automatically destroyed and the -function will not be called again. The first call to the function will be -at the end of the first @interval. +The given @function is called repeatedly until it returns +[const@GLib.SOURCE_REMOVE] or %FALSE, at which point the timeout is +automatically destroyed and the function will not be called again. The first +call to the function will be at the end of the first @interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. @@ -57400,19 +57967,20 @@ on how to handle the return value and memory management of @data. If you want to have a timer in the "seconds" range and do not care about the exact time of the first call of the timer, use the -g_timeout_add_seconds() function; this function allows for more +[func@GLib.timeout_add_seconds] function; this function allows for more optimizations and more efficient system power usage. -This internally creates a main loop source using g_timeout_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. +This internally creates a main loop source using +[func@GLib.timeout_source_new] and attaches it to the global +[struct@GLib.MainContext] using [method@GLib.Source.attach], so the callback +will be invoked in whichever thread is running that main context. You can do +these steps manually if you need greater control or to use a custom main +context. It is safe to call this function from any thread. The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). +time. See [func@GLib.get_monotonic_time]. the ID (greater than 0) of the event source. @@ -57450,14 +58018,15 @@ timeout is recalculated based on the current time and the given interval See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. -This internally creates a main loop source using g_timeout_source_new() -and attaches it to the global #GMainContext using g_source_attach(), so -the callback will be invoked in whichever thread is running that main -context. You can do these steps manually if you need greater control or to -use a custom main context. +This internally creates a main loop source using +[func@GLib.timeout_source_new] and attaches it to the global +[struct@GLib.MainContext] using [method@GLib.Source.attach], so the callback +will be invoked in whichever thread is running that main context. You can do +these steps manually if you need greater control or to use a custom main +context. The interval given is in terms of monotonic time, not wall clock time. -See g_get_monotonic_time(). +See [func@GLib.get_monotonic_time]. the ID (greater than 0) of the event source. @@ -57465,7 +58034,8 @@ See g_get_monotonic_time(). the priority of the timeout source. Typically this will be in - the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. + the range between [const@GLib.PRIORITY_DEFAULT] and + [const@GLib.PRIORITY_HIGH]. @@ -57489,12 +58059,12 @@ See g_get_monotonic_time(). Sets a function to be called after @interval milliseconds have elapsed, -with the default priority, %G_PRIORITY_DEFAULT. +with the default priority, [const@GLib.PRIORITY_DEFAULT]. The given @function is called once and then the source will be automatically removed from the main context. -This function otherwise behaves like g_timeout_add(). +This function otherwise behaves like [func@GLib.timeout_add]. the ID (greater than 0) of the event source @@ -57517,28 +58087,28 @@ This function otherwise behaves like g_timeout_add(). Sets a function to be called at regular intervals with the default -priority, %G_PRIORITY_DEFAULT. +priority, [const@GLib.PRIORITY_DEFAULT]. -The function is called repeatedly until it returns %G_SOURCE_REMOVE +The function is called repeatedly until it returns [const@GLib.SOURCE_REMOVE] or %FALSE, at which point the timeout is automatically destroyed and the function will not be called again. This internally creates a main loop source using -g_timeout_source_new_seconds() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you need -greater control. Also see g_timeout_add_seconds_full(). +[func@GLib.timeout_source_new_seconds] and attaches it to the main loop context +using [method@GLib.Source.attach]. You can do these steps manually if you need +greater control. Also see [func@GLib.timeout_add_seconds_full]. It is safe to call this function from any thread. Note that the first call of the timer may not be precise for timeouts of one second. If you need finer precision and have such a timeout, -you may want to use g_timeout_add() instead. +you may want to use [func@GLib.timeout_add] instead. See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). +time. See [func@GLib.get_monotonic_time]. the ID (greater than 0) of the event source. @@ -57561,17 +58131,17 @@ time. See g_get_monotonic_time(). Sets a function to be called at regular intervals, with @priority. -The function is called repeatedly until it returns %G_SOURCE_REMOVE +The function is called repeatedly until it returns [const@GLib.SOURCE_REMOVE] or %FALSE, at which point the timeout is automatically destroyed and the function will not be called again. -Unlike g_timeout_add(), this function operates at whole second granularity. -The initial starting point of the timer is determined by the implementation -and the implementation is expected to group multiple timers together so that -they fire all at the same time. To allow this grouping, the @interval to the -first timer is rounded and can deviate up to one second from the specified -interval. Subsequent timer iterations will generally run at the specified -interval. +Unlike [func@GLib.timeout_add], this function operates at whole second +granularity. The initial starting point of the timer is determined by the +implementation and the implementation is expected to group multiple timers +together so that they fire all at the same time. To allow this grouping, the +@interval to the first timer is rounded and can deviate up to one second +from the specified interval. Subsequent timer iterations will generally run +at the specified interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. @@ -57581,23 +58151,24 @@ timeout is recalculated based on the current time and the given @interval See [mainloop memory management](main-loop.html#memory-management-of-sources) for details on how to handle the return value and memory management of @data. -If you want timing more precise than whole seconds, use g_timeout_add() -instead. +If you want timing more precise than whole seconds, use +[func@GLib.timeout_add] instead. The grouping of timers to fire at the same time results in a more power and CPU efficient behavior so if your timer is in multiples of seconds and you don't require the first timer exactly one second from now, the -use of g_timeout_add_seconds() is preferred over g_timeout_add(). +use of [func@GLib.timeout_add_seconds] is preferred over +[func@GLib.timeout_add]. This internally creates a main loop source using -g_timeout_source_new_seconds() and attaches it to the main loop context -using g_source_attach(). You can do these steps manually if you need -greater control. +[func@GLib.timeout_source_new_seconds] and attaches it to the main loop +context using [method@GLib.Source.attach]. You can do these steps manually +if you need greater control. It is safe to call this function from any thread. The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). +time. See [func@GLib.get_monotonic_time]. the ID (greater than 0) of the event source. @@ -57605,7 +58176,8 @@ time. See g_get_monotonic_time(). the priority of the timeout source. Typically this will be in - the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. + the range between [const@GLib.PRIORITY_DEFAULT] and + [const@GLib.PRIORITY_HIGH]. @@ -57627,7 +58199,8 @@ time. See g_get_monotonic_time(). - This function behaves like g_timeout_add_once() but with a range in seconds. + This function behaves like [func@GLib.timeout_add_once] but with a range in +seconds. the ID (greater than 0) of the event source @@ -57650,12 +58223,12 @@ time. See g_get_monotonic_time(). Creates a new timeout source. -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be +The source will not initially be associated with any [struct@GLib.MainContext] +and must be added to one with [method@GLib.Source.attach] before it will be executed. The interval given is in terms of monotonic time, not wall clock -time. See g_get_monotonic_time(). +time. See [func@GLib.get_monotonic_time]. the newly-created timeout source @@ -57670,15 +58243,15 @@ time. See g_get_monotonic_time(). Creates a new timeout source. -The source will not initially be associated with any #GMainContext -and must be added to one with g_source_attach() before it will be -executed. +The source will not initially be associated with any +[struct@GLib.MainContext] and must be added to one with +[method@GLib.Source.attach] before it will be executed. The scheduling granularity/accuracy of this timeout source will be in seconds. The interval given is in terms of monotonic time, not wall clock time. -See g_get_monotonic_time(). +See [func@GLib.get_monotonic_time]. the newly-created timeout source @@ -57914,12 +58487,12 @@ The function returns %NULL if an overflow occurs. - Convert a string from UCS-4 to UTF-16. A 0 character will be -added to the result after the converted text. + Convert a string from UCS-4 to UTF-16. + +A nul character (U+0000) will be added to the result after the converted text. a pointer to a newly allocated UTF-16 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + This value must be freed with [func@GLib.free]. @@ -57931,31 +58504,33 @@ added to the result after the converted text. the maximum length (number of characters) of @str to use. - If @len < 0, then the string is nul-terminated. + If @len is negative, then the string is nul-terminated. location to store number of - bytes read, or %NULL. If an error occurs then the index of the invalid - input is stored here. + bytes read, or `NULL`. If an error occurs then the index of the invalid + input is stored here. location to store number - of #gunichar2 written, or %NULL. The value stored here does not include - the trailing 0. + of `gunichar2` written, or `NULL`. The value stored here does not include + the trailing nul. Convert a string from a 32-bit fixed width representation as UCS-4. -to UTF-8. The result will be terminated with a 0 byte. +to UTF-8. + +The result will be terminated with a nul byte. a pointer to a newly allocated UTF-8 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. In that case, @items_read - will be set to the position of the first invalid input character. + This value must be freed with [func@GLib.free]. If an error occurs, + @items_read will be set to the position of the first invalid input + character. @@ -57967,18 +58542,18 @@ to UTF-8. The result will be terminated with a 0 byte. the maximum length (number of characters) of @str to use. - If @len < 0, then the string is nul-terminated. + If @len is negative, then the string is nul-terminated. location to store number of - characters read, or %NULL. + characters read, or `NULL`. location to store number - of bytes written or %NULL. The value here stored does not include the - trailing 0 byte. + of bytes written or `NULL`. The value here stored does not include the + trailing nul byte. @@ -58562,8 +59137,8 @@ terminals support zero-width rendering of zero-width marks. output buffer, must have at - least 6 bytes of space. If %NULL, the length will be computed and - returned and nothing will be written to @outbuf. + least 6 bytes of space. If `NULL`, the length will be computed and + returned and nothing will be written to @outbuf. @@ -58627,11 +59202,12 @@ terminals support zero-width rendering of zero-width marks. - Checks whether @ch is a valid Unicode character. Some possible -integer values of @ch will not be valid. 0 is considered a valid -character, though it's normally a string terminator. + Checks whether @ch is a valid Unicode character. + +Some possible integer values of @ch will not be valid. U+0000 is considered a +valid character, though it’s normally a string terminator. - %TRUE if @ch is a valid Unicode character + `TRUE` if @ch is a valid Unicode character @@ -59833,12 +60409,12 @@ length of the sleep. - Convert a string from UTF-16 to UCS-4. The result will be -nul-terminated. + Convert a string from UTF-16 to UCS-4. + +The result will be nul-terminated. a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + This value must be freed with [func@GLib.free]. @@ -59850,42 +60426,42 @@ nul-terminated. the maximum length (number of #gunichar2) of @str to use. - If @len < 0, then the string is nul-terminated. + If @len is negative, then the string is nul-terminated. - location to store number of - words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. + location to store number of words read, or + `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will be + returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. location to store number - of characters written, or %NULL. The value stored here does not include - the trailing 0 character. + of characters written, or `NULL`. The value stored here does not include + the trailing nul character. - Convert a string from UTF-16 to UTF-8. The result will be -terminated with a 0 byte. + Convert a string from UTF-16 to UTF-8. + +The result will be terminated with a nul byte. Note that the input is expected to be already in native endianness, an initial byte-order-mark character is not handled specially. -g_convert() can be used to convert a byte buffer of UTF-16 data of +[func@GLib.convert] can be used to convert a byte buffer of UTF-16 data of ambiguous endianness. Further note that this function does not validate the result -string; it may e.g. include embedded NUL characters. The only +string; it may (for example) include embedded nul characters. The only validation done by this function is to ensure that the input can -be correctly interpreted as UTF-16, i.e. it doesn't contain +be correctly interpreted as UTF-16, i.e. it doesn’t contain unpaired surrogates or partial character sequences. a pointer to a newly allocated UTF-8 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + This value must be freed with [func@GLib.free]. @@ -59897,21 +60473,21 @@ unpaired surrogates or partial character sequences. the maximum length (number of #gunichar2) of @str to use. - If @len < 0, then the string is nul-terminated. + If @len is negative, then the string is nul-terminated. - location to store number of - words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. - It’s guaranteed to be non-negative. + location to store number of words read, or + `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will + be returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. + It’s guaranteed to be non-negative. location to store number - of bytes written, or %NULL. The value stored here does not include the - trailing 0 byte. It’s guaranteed to be non-negative. + of bytes written, or `NULL`. The value stored here does not include the + trailing nul byte. It’s guaranteed to be non-negative. @@ -59980,11 +60556,16 @@ The results of comparing the collation keys of two strings with strcmp() will always be the same as comparing the two original keys with g_utf8_collate(). -Note that this function depends on the [current locale][setlocale]. +Note that this function depends on the [current locale][setlocale]. + +Note that the returned string is not guaranteed to be in any +encoding, especially UTF-8. The returned value is meant to be +used only for comparisons. - a newly allocated string. This string should - be freed with g_free() when you are done with it. - + a newly allocated string. + The contents of the string are only meant to be used when sorting. + This string should be freed with g_free() when you are done with it. + @@ -60008,11 +60589,16 @@ insignificant, thus producing the ordering "event.c" "eventgenerator.c" would like to treat numbers intelligently so that "file1" "file10" "file5" is sorted as "file1" "file5" "file10". -Note that this function depends on the [current locale][setlocale]. +Note that this function depends on the [current locale][setlocale]. + +Note that the returned string is not guaranteed to be in any +encoding, especially UTF-8. The returned value is meant to be +used only for comparisons. - a newly allocated string. This string should - be freed with g_free() when you are done with it. - + a newly allocated string. + The contents of the string are only meant to be used when sorting. + This string should be freed with g_free() when you are done with it. + @@ -60032,12 +60618,12 @@ Note that this function depends on the [current locale][setlocale]. is made to see if the character found is actually valid other than it starts with an appropriate byte. -If @end is %NULL, the return value will never be %NULL: if the end of the +If @end is `NULL`, the return value will never be `NULL`: if the end of the string is reached, a pointer to the terminating nul byte is returned. If -@end is non-%NULL, the return value will be %NULL if the end of the string +@end is non-`NULL`, the return value will be `NULL` if the end of the string is reached. - a pointer to the found character or %NULL if @end is + a pointer to the found character or `NULL` if @end is set and is reached @@ -60048,21 +60634,21 @@ is reached. a pointer to the byte following the end of the string, - or %NULL to indicate that the string is nul-terminated + or `NULL` to indicate that the string is nul-terminated Given a position @p with a UTF-8 encoded string @str, find the start -of the previous UTF-8 character starting before @p. Returns %NULL if no +of the previous UTF-8 character starting before @p. Returns `NULL` if no UTF-8 characters are present in @str before @p. @p does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. - a pointer to the found character or %NULL. + a pointer to the found character @@ -60081,7 +60667,7 @@ it starts with an appropriate byte. If @p does not point to a valid UTF-8 encoded character, results are undefined. If you are not sure that the bytes are complete -valid Unicode characters, you should use g_utf8_get_char_validated() +valid Unicode characters, you should use [func@GLib.utf8_get_char_validated] instead. the resulting character @@ -60096,19 +60682,20 @@ instead. Convert a sequence of bytes encoded as UTF-8 to a Unicode character. + This function checks for incomplete characters, for invalid characters such as characters that are out of the range of Unicode, and for overlong encodings of valid characters. -Note that g_utf8_get_char_validated() returns (gunichar)-2 if +Note that [func@GLib.utf8_get_char_validated] returns `(gunichar)-2` if @max_len is positive and any of the bytes in the first UTF-8 character sequence are nul. the resulting character. If @p points to a partial - sequence at the end of a string that could begin a valid - character (or if @max_len is zero), returns (gunichar)-2; - otherwise, if @p does not point to a valid UTF-8 encoded - Unicode character, returns (gunichar)-1. + sequence at the end of a string that could begin a valid + character (or if @max_len is zero), returns `(gunichar)-2`; + otherwise, if @p does not point to a valid UTF-8 encoded + Unicode character, returns `(gunichar)-1`. @@ -60117,7 +60704,7 @@ sequence are nul. - the maximum number of bytes to read, or -1 if @p is nul-terminated + the maximum number of bytes to read, or `-1` if @p is nul-terminated @@ -60142,8 +60729,8 @@ readable as-is. - the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. + the maximum length of @str to use, in bytes. If @len is negative, + then the string is nul-terminated. @@ -60222,9 +60809,9 @@ step backwards. It is usually worth stepping backwards from the end instead of forwards if @offset is in the last fourth of the string, since moving forward is about 3 times faster than moving backward. -Note that this function doesn't abort when reaching the end of @str. +Note that this function doesn’t abort when reaching the end of @str. Therefore you should be sure that @offset is within string boundaries -before calling that function. Call g_utf8_strlen() when unsure. +before calling that function. Call [func@GLib.utf8_strlen] when unsure. This limitation exists as this function is called frequently during text rendering and therefore has to be as fast as possible. @@ -60269,7 +60856,8 @@ a negative offset in this case. @p does not have to be at the beginning of a UTF-8 character. No check is made to see if the character found is actually valid other than it starts with an appropriate byte. If @p might be the first -character of the string, you must use g_utf8_find_prev_char() instead. +character of the string, you must use [func@GLib.utf8_find_prev_char] +instead. a pointer to the found character @@ -60284,11 +60872,12 @@ character of the string, you must use g_utf8_find_prev_char() instead. Finds the leftmost occurrence of the given Unicode character in a UTF-8 encoded string, while limiting the search to @len bytes. -If @len is -1, allow unbounded search. + +If @len is `-1`, allow unbounded search. - %NULL if the string does not contain the character, - otherwise, a pointer to the start of the leftmost occurrence - of the character in the string. + `NULL` if the string does not contain + the character, otherwise, a pointer to the start of the leftmost occurrence + of the character in the string. @@ -60329,7 +60918,7 @@ characters in the string changing. Computes the length of the string in characters, not including -the terminating nul character. If the @max'th byte falls in the +the terminating nul character. If the @max’th byte falls in the middle of a character, the last (partial) character is not counted. the length of the string in characters @@ -60342,19 +60931,21 @@ middle of a character, the last (partial) character is not counted. the maximum number of bytes to examine. If @max - is less than 0, then the string is assumed to be - nul-terminated. If @max is 0, @p will not be examined and - may be %NULL. If @max is greater than 0, up to @max - bytes are examined + is less than 0, then the string is assumed to be + nul-terminated. If @max is 0, @p will not be examined and + may be `NULL`. If @max is greater than 0, up to @max + bytes are examined - Like the standard C strncpy() function, but copies a given number -of characters instead of a given number of bytes. The @src string -must be valid UTF-8 encoded text. (Use g_utf8_validate() on all -text before trying to use UTF-8 utility functions with it.) + Like the standard C [`strncpy()`](man:strncpy) function, but copies a given +number of characters instead of a given number of bytes. + +The @src string must be valid UTF-8 encoded text. (Use +[func@GLib.utf8_validate] on all text before trying to use UTF-8 utility +functions with it.) Note you must ensure @dest is at least 4 * @n + 1 to fit the largest possible UTF-8 characters @@ -60380,11 +60971,12 @@ largest possible UTF-8 characters Find the rightmost occurrence of the given Unicode character in a UTF-8 encoded string, while limiting the search to @len bytes. -If @len is -1, allow unbounded search. + +If @len is `-1`, allow unbounded search. - %NULL if the string does not contain the character, - otherwise, a pointer to the start of the rightmost occurrence - of the character in the string. + `NULL` if the string does not contain + the character, otherwise, a pointer to the start of the rightmost + occurrence of the character in the string. @@ -60403,9 +60995,10 @@ If @len is -1, allow unbounded search. - Reverses a UTF-8 string. @str must be valid UTF-8 encoded text. -(Use g_utf8_validate() on all text before trying to use UTF-8 -utility functions with it.) + Reverses a UTF-8 string. + +@str must be valid UTF-8 encoded text. (Use [func@GLib.utf8_validate] on all +text before trying to use UTF-8 utility functions with it.) This function is intended for programmatic uses of reversed strings. It pays no attention to decomposed characters, combining marks, byte @@ -60413,8 +61006,8 @@ order marks, directional indicators (LRM, LRO, etc) and similar characters which might need special handling when reversing a string for display purposes. -Note that unlike g_strreverse(), this function returns -newly-allocated memory, which should be freed with g_free() when +Note that unlike [func@GLib.strreverse], this function returns +newly-allocated memory, which should be freed with [func@GLib.free] when no longer needed. a newly-allocated string which is the reverse of @str @@ -60426,8 +61019,8 @@ no longer needed. - the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. + the maximum length of @str to use, in bytes. If @len is negative, + then the string is nul-terminated. @@ -60462,7 +61055,7 @@ Since GLib 2.72, `-1` can be passed to @end_pos to indicate the end of the string. a newly allocated copy of the requested - substring. Free with g_free() when no longer needed. + substring. Free with [func@GLib.free] when no longer needed. @@ -60482,13 +61075,13 @@ end of the string. - Convert a string from UTF-8 to a 32-bit fixed width -representation as UCS-4. A trailing 0 character will be added to the -string after the converted text. + Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4. + +A trailing nul character (U+0000) will be added to the string after the +converted text. a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + This value must be freed with [func@GLib.free]. @@ -60497,23 +61090,23 @@ string after the converted text. - the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. + the maximum length of @str to use, in bytes. If @len is negative, + then the string is nul-terminated. location to store number of - bytes read, or %NULL. - If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be - returned in case @str contains a trailing partial - character. If an error occurs then the index of the - invalid input is stored here. + bytes read, or `NULL`. + If `NULL`, then %G_CONVERT_ERROR_PARTIAL_INPUT will be + returned in case @str contains a trailing partial + character. If an error occurs then the index of the + invalid input is stored here. location to store number - of characters written or %NULL. The value here stored does not include - the trailing 0 character. + of characters written or `NULL`. The value here stored does not include + the trailing nul character. @@ -60521,12 +61114,13 @@ string after the converted text. Convert a string from UTF-8 to a 32-bit fixed width representation as UCS-4, assuming valid UTF-8 input. -This function is roughly twice as fast as g_utf8_to_ucs4() -but does no error checking on the input. A trailing 0 character + +This function is roughly twice as fast as [func@GLib.utf8_to_ucs4] +but does no error checking on the input. A trailing nul character (U+0000) will be added to the string after the converted text. a pointer to a newly allocated UCS-4 string. - This value must be freed with g_free(). + This value must be freed with [func@GLib.free]. @@ -60535,24 +61129,24 @@ will be added to the string after the converted text. - the maximum length of @str to use, in bytes. If @len < 0, - then the string is nul-terminated. + the maximum length of @str to use, in bytes. If @len is negative, + then the string is nul-terminated. location to store the - number of characters in the result, or %NULL. + number of characters in the result, or `NULL`. - Convert a string from UTF-8 to UTF-16. A 0 character will be -added to the result after the converted text. + Convert a string from UTF-8 to UTF-16. + +A nul character (U+0000) will be added to the result after the converted text. a pointer to a newly allocated UTF-16 string. - This value must be freed with g_free(). If an error occurs, - %NULL will be returned and @error set. + This value must be freed with [func@GLib.free]. @@ -60562,20 +61156,20 @@ added to the result after the converted text. the maximum length (number of bytes) of @str to use. - If @len < 0, then the string is nul-terminated. + If @len is negative, then the string is nul-terminated. - location to store number of - bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will - be returned in case @str contains a trailing partial character. If - an error occurs then the index of the invalid input is stored here. + location to store number of bytes read, or + `NULL`. If `NULL`, then [error@GLib.ConvertError.PARTIAL_INPUT] will + be returned in case @str contains a trailing partial character. If + an error occurs then the index of the invalid input is stored here. location to store number - of #gunichar2 written, or %NULL. The value stored here does not include - the trailing 0. + of `gunichar2` written, or `NULL`. The value stored here does not include + the trailing nul. @@ -60602,23 +61196,25 @@ If @truncate_length is `0`, an empty string is returned. - Validates UTF-8 encoded text. @str is the text to validate; -if @str is nul-terminated, then @max_len can be -1, otherwise -@max_len should be the number of bytes to validate. -If @end is non-%NULL, then the end of the valid range -will be stored there (i.e. the start of the first invalid -character if some bytes were invalid, or the end of the text -being validated otherwise). - -Note that g_utf8_validate() returns %FALSE if @max_len is -positive and any of the @max_len bytes are nul. - -Returns %TRUE if all of @str was valid. Many GLib and GTK + Validates UTF-8 encoded text. + +@str is the text to validate; if @str is nul-terminated, then @max_len can be +`-1`, otherwise @max_len should be the number of bytes to validate. + +If @end is non-`NULL`, then the end of the valid range will be stored there. +This is the first byte of the first invalid character if some bytes were +invalid, or the end of the text being validated otherwise — either the +trailing nul byte, or the first byte beyond @max_len (if it’s positive). + +Note that `g_utf8_validate()` returns `FALSE` if @max_len is positive and +any of the @max_len bytes are nul. + +Returns `TRUE` if all of @str was valid. Many GLib and GTK routines require valid UTF-8 as input; so data read from a file -or the network should be checked with g_utf8_validate() before +or the network should be checked with `g_utf8_validate()` before doing anything else with it. - %TRUE if the text was valid UTF-8 + `TRUE` if the text was valid UTF-8 @@ -60629,7 +61225,7 @@ doing anything else with it. - max bytes to validate, or -1 to go until NUL + max bytes to validate, or `-1` to go until nul @@ -60641,10 +61237,10 @@ doing anything else with it. Validates UTF-8 encoded text. -As with g_utf8_validate(), but @max_len must be set, and hence this function -will always return %FALSE if any of the bytes of @str are nul. +As with [func@GLib.utf8_validate], but @max_len must be set, and hence this +function will always return `FALSE` if any of the bytes of @str are nul. - %TRUE if the text was valid UTF-8 + `TRUE` if the text was valid UTF-8 diff --git a/GLibUnix-2.0.gir b/GLibUnix-2.0.gir index 8c05c1a7..fe29ab69 100644 --- a/GLibUnix-2.0.gir +++ b/GLibUnix-2.0.gir @@ -42,6 +42,132 @@ on compilers that support that feature. + + Close both ends of the pipe, unless they have already been closed or +stolen. Any errors are ignored: use g_unix_pipe_close() or g_clear_fd() +if error-handling is required. + +This function is async-signal safe if @error is %NULL and each member +of @fds are either negative or a valid open file descriptor. +As a result, it is safe to call this function or use `g_auto(GUnixPipe)` +(on compilers that support it) in a signal handler or a +#GSpawnChildSetupFunc, as long as those conditions are ensured to be true. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + +This function preserves the value of `errno`. + + + + + + a #GUnixPipe + + + + + + Close one of the ends of the pipe and set the relevant member of @fds +to `-1` before returning, equivalent to g_clear_fd(). + +Like g_close(), if closing the file descriptor fails, the error is +stored in both %errno and @error. If this function succeeds, +%errno is undefined. + +This function is async-signal safe if @error is %NULL and the relevant +member of @fds is either negative or a valid open file descriptor. +This makes it safe to call from a signal handler or a #GSpawnChildSetupFunc +under those conditions. +See [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7)) for more details. + +To close both file descriptors and ignore any errors, use +g_unix_pipe_clear() instead. + + %TRUE on success + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + + + Return one of the ends of the pipe. It remains owned by @self. + +This function is async-signal safe (see [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a +signal handler or a #GSpawnChildSetupFunc. + +This function preserves the value of `errno`. + + a non-negative file descriptor owned by @self, which must not + be closed by the caller, or a negative number if the corresponding + end of the pipe was already closed or stolen + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + + + Open a pipe. This is the same as g_unix_open_pipe(), but uses the +#GUnixPipe data structure. + + %TRUE on success + + + + + A pair of file descriptors + + + + Flags to pass to g_unix_open_pipe(), typically `O_CLOEXEC` + + + + + + Return one of the ends of the pipe. It becomes owned by the caller, +and the file descriptor in the data structure is set to `-1`, +similar to g_steal_fd(). + +This function is async-signal safe (see [`signal(7)`](man:signal(7)) and +[`signal-safety(7)`](man:signal-safety(7))), making it safe to call from a +signal handler or a #GSpawnChildSetupFunc. + +This function preserves the value of `errno`. + + a non-negative file descriptor, which becomes owned by the + caller and must be closed by the caller if required, or a negative + number if the corresponding end of the pipe was already closed or stolen + + + + + A pair of file descriptors + + + + One of the ends of the pipe + + + + Mnemonic constants for the ends of a Unix pipe. diff --git a/GLibWin32-2.0.gir b/GLibWin32-2.0.gir new file mode 100644 index 00000000..4340aa76 --- /dev/null +++ b/GLibWin32-2.0.gir @@ -0,0 +1,136 @@ + + + + + + + + + + + Type of Windows edition to check for at run-time. + + The running system can be a workstation or a server edition of + Windows. The type of the running system is therefore not checked. + + + The running system is a workstation edition of Windows, + such as Windows 7 Professional. + + + The running system is a server edition of Windows, such as + Windows Server 2008 R2. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/GModule-2.0.gir b/GModule-2.0.gir index b22db6c2..b1f99af6 100644 --- a/GModule-2.0.gir +++ b/GModule-2.0.gir @@ -181,6 +181,12 @@ and/or use gtk-doc annotations. --> + + + + + + @@ -361,6 +367,12 @@ and/or use gtk-doc annotations. --> + + + + + + @@ -535,6 +547,12 @@ and/or use gtk-doc annotations. --> + + + + + + @@ -709,6 +727,12 @@ and/or use gtk-doc annotations. --> + + + + + + diff --git a/GObject-2.0.gir b/GObject-2.0.gir index f610610a..1f78378d 100644 --- a/GObject-2.0.gir +++ b/GObject-2.0.gir @@ -4553,6 +4553,12 @@ See also: G_ADD_PRIVATE() + + + + + + @@ -4733,6 +4739,12 @@ See also: G_ADD_PRIVATE() + + + + + + @@ -4907,6 +4919,12 @@ See also: G_ADD_PRIVATE() + + + + + + @@ -5081,6 +5099,12 @@ See also: G_ADD_PRIVATE() + + + + + + diff --git a/Gdk-3.0.gir b/Gdk-3.0.gir index ddad1b36..82824fab 100644 --- a/Gdk-3.0.gir +++ b/Gdk-3.0.gir @@ -14773,7 +14773,7 @@ See gdk_keymap_get_caps_lock_state(). - + diff --git a/Gdk-4.0.gir b/Gdk-4.0.gir index 95019357..4549d294 100644 --- a/Gdk-4.0.gir +++ b/Gdk-4.0.gir @@ -397,6 +397,228 @@ The returned context is guaranteed to be valid until + + The `GdkCicpParams` struct contains the parameters that define +a colorstate according to the ITU-T H.273 +[specification](https://www.itu.int/rec/T-REC-H.273/en). + +See the documentation of individual properties for supported values. + +The 'unspecified' value (2) is not treated in any special way, and +must be replaced by a different value before creating a color state. + +`GdkCicpParams` can be used as a builder object to construct a color +state from Cicp data with [method@Gdk.CicpParams.build_color_state]. +The function will return an error if the given parameters are not +supported. + +You can obtain a `GdkCicpParams` object from a color state with +[method@Gdk.ColorState.create_cicp_params]. This can be used to +create a variant of a color state, by changing just one of the cicp +parameters, or just to obtain information about the color state. + + Creates a new `GdkCicpParams` object. + +The initial values of the properties are the values for "undefined" +and need to be set before a color state object can be built. + + a new `GdkCicpParams` + + + + + Creates a new `GdkColorState` object for the cicp parameters in @self. + +Note that this may fail if the cicp parameters in @self are not +supported by GTK. In that case, `NULL` is returned, and @error is set +with an error message that can be presented to the user. + + A newly allocated `GdkColorState` + + + + + a `GdkCicpParams` + + + + + + Returns the value of the color-primaries property +of @self. + + the color-primaries value + + + + + a `GdkCicpParams` + + + + + + Gets the matrix-coefficients property of @self. + + the matrix-coefficients value + + + + + a `GdkCicpParams` + + + + + + Gets the range property of @self. + + the range value + + + + + a `GdkCicpParams` + + + + + + Gets the transfer-function property of @self. + + the transfer-function value + + + + + a `GdkCicpParams` + + + + + + Sets the color-primaries property of @self. + + + + + + a `GdkCicpParams` + + + + the new color primaries value + + + + + + @self a `GdkCicpParams` +Sets the matrix-coefficients property of @self. + + + + + + + + + the new matrix-coefficients value + + + + + + Sets the range property of @self + + + + + + a `GdkCipParams` + + + + the range value + + + + + + Sets the transfer-function property of @self. + + + + + + a `GdkCicpParams` + + + + the new transfer-function value + + + + + + The color primaries to use. + +Supported values: + +- 1: BT.709 / sRGB +- 2: unspecified +- 5: PAL +- 6,7: BT.601 / NTSC +- 9: BT.2020 +- 12: Display P3 + + + + The matrix coefficients (for YUV to RGB conversion). + +Supported values: + +- 0: RGB +- 2: unspecified + + + + Whether the data is using the full range of values. + +The range of the data. + + + + The transfer function to use. + +Supported values: + +- 1,6,14,15: BT.709, BT.601, BT.2020 +- 2: unspecified +- 4: gamma 2.2 +- 5: gamma 2.8 +- 8: linear +- 13: sRGB +- 16: BT.2100 PQ +- 18: BT.2100 HLG + + + + + + The values of this enumeration describe whether image data uses +the full range of 8-bit values. + +In digital broadcasting, it is common to reserve the lowest and +highest values. Typically the allowed values for the narrow range +are 16-235 for Y and 16-240 for u,v (when dealing with YUV data). + + The values use the range of 16-235 (for Y) and 16-240 for u and v. + + + The values use the full range. + + The `GdkClipboard` object represents data shared between applications or inside an application. @@ -898,6 +1120,153 @@ provided otherwise. + + A `GdkColorState` object provides the information to interpret +colors and pixels in a variety of ways. + +They are also known as +[*color spaces*](https://en.wikipedia.org/wiki/Color_space). + +Crucially, GTK knows how to convert colors from one color +state to another. + +`GdkColorState` objects are immutable and therefore threadsafe. + + Create a [class@Gdk.CicpParams] representing the colorstate. + +It is not guaranteed that every `GdkColorState` can be +represented with Cicp parameters. If that is the case, +this function returns `NULL`. + + A new [class@Gdk.CicpParams] + + + + + a `GdkColorState` + + + + + + Compares two `GdkColorStates` for equality. + +Note that this function is not guaranteed to be perfect and two objects +describing the same color state may compare not equal. However, different +color states will never compare equal. + + %TRUE if the two color states compare equal + + + + + a `GdkColorState` + + + + another `GdkColorStatee` + + + + + + Increase the reference count of @self. + + the object that was passed in + + + + + a `GdkColorState` + + + + + + Decrease the reference count of @self. + +Unless @self is static, it will be freed +when the reference count reaches zero. + + + + + + a `GdkColorState` + + + + + + + + + + + + + + + + Returns the color state object representing the linear rec2100 color space. + +This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and a linear +transfer function. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/8/0/1. + +See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-linear) +for details about this colorstate. + + the color state object for linearized rec2100 + + + + + Returns the color state object representing the rec2100-pq color space. + +This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and the transfer +function defined by SMPTE ST 2084 and BT.2100-2. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/16/0/1. + +See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-pq) +for details about this colorstate. + + the color state object for rec2100-pq + + + + + Returns the color state object representing the sRGB color space. + +This color state uses the primaries defined by BT.709-6 and the transfer function +defined by IEC 61966-2-1. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/13/0/1. + +See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB) +for details about this colorstate. + + the color state object for sRGB + + + + + Returns the color state object representing the linearized sRGB color space. + +This color state uses the primaries defined by BT.709-6 and a linear transfer function. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/8/0/1. + +See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB-linear) +for details about this colorstate. + + the color state object for linearized sRGB + + + + The type of a function that can be registered with gdk_content_register_deserializer(). @@ -4547,6 +4916,19 @@ possibly with changing properties in between. + + Gets the color state previously set via gdk_dmabuf_texture_builder_set_color_state(). + + the color state + + + + + a `GdkDmabufTextureBuilder` + + + + Returns the display that this texture builder is associated with. @@ -4723,6 +5105,26 @@ The format is specified as a fourcc code. + + Sets the color state for the texture. + +By default, the colorstate is `NULL`. In that case, GTK will choose the +correct colorstate based on the format. +If you don't know what colorstates are, this is probably the right thing. + + + + + + a `GdkDmabufTextureBuilder` + + + + a `GdkColorState` or `NULL` to unset the colorstate. + + + + Sets the display that this texture builder is associated with. @@ -4954,6 +5356,10 @@ The width must be set before calling [method@Gdk.GLTextureBuilder.build]. + + The color state of the texture. + + The display that this texture will be used on. @@ -5403,7 +5809,7 @@ It provides shared functionality between those contexts. You will always interact with one of those subclasses. A `GdkDrawContext` is always associated with a single toplevel surface. - + Indicates that you are beginning the process of redrawing @region on the @context's surface. @@ -5428,6 +5834,8 @@ When using GTK, the widget system automatically places calls to gdk_draw_context_begin_frame() and gdk_draw_context_end_frame() via the use of [GskRenderer](../gsk4/class.Renderer.html)s, so application code does not need to call these functions explicitly. + Drawing directly to the surface is no longer recommended. + Use `GskRenderNode` and `GskRenderer`. @@ -5443,7 +5851,7 @@ does not need to call these functions explicitly. - + Ends a drawing operation started with gdk_draw_context_begin_frame(). This makes the drawing available on screen. @@ -5452,6 +5860,8 @@ See [method@Gdk.DrawContext.begin_frame] for more details about drawing. When using a [class@Gdk.GLContext], this function may call `glFlush()` implicitly before returning; it is not recommended to call `glFlush()` explicitly before calling this function. + Drawing directly to the surface is no longer recommended. + Use `GskRenderNode` and `GskRenderer`. @@ -5475,7 +5885,7 @@ explicitly before calling this function. - + Retrieves the region that is currently being repainted. After a call to [method@Gdk.DrawContext.begin_frame] this function will @@ -5484,6 +5894,8 @@ surface that the @context determined needs to be repainted. If @context is not in between calls to [method@Gdk.DrawContext.begin_frame] and [method@Gdk.DrawContext.end_frame], %NULL will be returned. + Drawing directly to the surface is no longer recommended. + Use `GskRenderNode` and `GskRenderer`. a Cairo region @@ -5508,12 +5920,14 @@ and [method@Gdk.DrawContext.end_frame], %NULL will be returned. - + Returns %TRUE if @context is in the process of drawing to its surface. This is the case between calls to [method@Gdk.DrawContext.begin_frame] and [method@Gdk.DrawContext.end_frame]. In this situation, drawing commands may be effecting the contents of the @context's surface. + Drawing directly to the surface is no longer recommended. + Use `GskRenderNode` and `GskRenderer`. %TRUE if the context is between [method@Gdk.DrawContext.begin_frame] and [method@Gdk.DrawContext.end_frame] calls. @@ -6214,9 +6628,13 @@ returns %GDK_CURRENT_TIME. according to platform conventions. The right mouse button typically triggers context menus. +On macOS, Control+left mouse button also triggers. This function should always be used instead of simply checking for -event->button == %GDK_BUTTON_SECONDARY. + +```c +event->button == GDK_BUTTON_SECONDARY +``` %TRUE if the event should trigger a context menu. @@ -7551,6 +7969,19 @@ possibly with changing properties in between. + + Gets the color state previously set via gdk_gl_texture_builder_set_color_state(). + + the color state + + + + + a `GdkGLTextureBuilder` + + + + Gets the context previously set via gdk_gl_texture_builder_set_context() or %NULL if none was set. @@ -7674,6 +8105,25 @@ possibly with changing properties in between. + + Sets the color state for the texture. + +By default, the sRGB colorstate is used. If you don't know what +colorstates are, this is probably the right thing. + + + + + + a `GdkGLTextureBuilder` + + + + a `GdkColorState` + + + + Sets the context to be used for the texture. This is the context that owns the texture. @@ -7688,7 +8138,7 @@ The context must be set before calling [method@Gdk.GLTextureBuilder.build]. - The context the texture beongs to or %NULL to unset + The context the texture belongs to or %NULL to unset @@ -7864,6 +8314,10 @@ The width must be set before calling [method@Gdk.GLTextureBuilder.build]. + + The color state of the texture. + + The context owning the texture. @@ -13353,6 +13807,21 @@ If this is set, GTK will wait on it before using the texture. + + + + + + + + + + + + + + + @@ -13401,6 +13870,9 @@ If this is set, GTK will wait on it before using the texture. + + + @@ -13491,6 +13963,9 @@ If this is set, GTK will wait on it before using the texture. + + + @@ -13527,6 +14002,9 @@ If this is set, GTK will wait on it before using the texture. + + + @@ -13809,6 +14287,12 @@ If this is set, GTK will wait on it before using the texture. + + + + + + @@ -14538,6 +15022,9 @@ If this is set, GTK will wait on it before using the texture. + + + @@ -15381,28 +15868,365 @@ in the given format. - - - Flags to indicate the state of modifier keys and mouse buttons -in events. + + `GdkMemoryTextureBuilder` is a builder used to construct [class@Gdk.Texture] objects +from system memory provided via [struct@GLib.Bytes]. -Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose, -Apple, CapsLock or ShiftLock. +The operation is quite simple: Create a texture builder, set all the necessary +properties - keep in mind that the properties [property@Gdk.MemoryTextureBuilder:bytes], +[property@Gdk.MemoryTextureBuilder:stride], [property@Gdk.MemoryTextureBuilder:width], +and [property@Gdk.MemoryTextureBuilder:height] are mandatory - and then call +[method@Gdk.MemoryTextureBuilder.build] to create the new texture. -Note that GDK may add internal values to events which include values outside -of this enumeration. Your code should preserve and ignore them. You can use -%GDK_MODIFIER_MASK to remove all private values. - - No modifier. - - - the Shift key. - - - a Lock key (depending on the modifier mapping of the - X server this may either be CapsLock or ShiftLock). - - +`GdkMemoryTextureBuilder` can be used for quick one-shot construction of +textures as well as kept around and reused to construct multiple textures. + + Creates a new texture builder. + + the new `GdkTextureBuilder` + + + + + Builds a new `GdkTexture` with the values set up in the builder. + +Note that it is a programming error to call this function if any mandatory +property has not been set. + +It is possible to call this function multiple times to create multiple textures, +possibly with changing properties in between. + + a newly built `GdkTexture` + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the bytes previously set via gdk_memory_texture_builder_set_bytes() +or %NULL if none was set. + + The bytes + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the colorstate previously set via gdk_memory_texture_builder_set_color_state(). + + The colorstate + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the format previously set via gdk_memory_texture_builder_set_format(). + + The format + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the height previously set via gdk_memory_texture_builder_set_height() +or 0 if the height wasn't set. + + The height + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the stride previously set via gdk_memory_texture_builder_set_stride(). + + the stride + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the region previously set via gdk_memory_texture_builder_set_update_region() +or %NULL if none was set. + + The update region + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the texture previously set via gdk_memory_texture_builder_set_update_texture() +or %NULL if none was set. + + The update texture + + + + + a `GdkMemoryTextureBuilder` + + + + + + Gets the width previously set via gdk_memory_texture_builder_set_width() +or 0 if the width wasn't set. + + The width + + + + + a `GdkMemoryTextureBuilder` + + + + + + Sets the data to be shown but the texture. + +The bytes must be set before calling [method@Gdk.MemoryTextureBuilder.build]. + + + + + + a `GdkMemoryTextureBuilder` + + + + The bytes the texture shows or %NULL to unset + + + + + + Sets the colorstate describing the data. + +By default, the sRGB colorstate is used. If you don't know +what colorstates are, this is probably the right thing. + + + + + + a `GdkMemoryTextureBuilder` + + + + The colorstate describing the data + + + + + + Sets the format of the bytes. + +The default is `GDK_MEMORY_R8G8B8A8_PREMULTIPLIED`. + + + + + + a `GdkMemoryTextureBuilder` + + + + The texture's format + + + + + + Sets the height of the texture. + +The height must be set before calling [method@Gdk.MemoryTextureBuilder.build]. + + + + + + a `GdkMemoryTextureBuilder` + + + + The texture's height or 0 to unset + + + + + + Sets the rowstride of the bytes used. + +The rowstride must be set before calling [method@Gdk.MemoryTextureBuilder.build]. + + + + + + a `GdkMemoryTextureBuilder` + + + + the stride or 0 to unset + + + + + + Sets the region to be updated by this texture. + +Together with [property@Gdk.MemoryTextureBuilder:update-texture], +this describes an update of a previous texture. + +When rendering animations of large textures, it is possible that +consecutive textures are only updating contents in parts of the texture. +It is then possible to describe this update via these two properties, +so that GTK can avoid rerendering parts that did not change. + +An example would be a screen recording where only the mouse pointer moves. + + + + + + a `GdkMemoryTextureBuilder` + + + + the region to update + + + + + + Sets the texture to be updated by this texture. + +See [method@Gdk.MemoryTextureBuilder.set_update_region] for an explanation. + + + + + + a `GdkMemoryTextureBuilder` + + + + the texture to update + + + + + + Sets the width of the texture. + +The width must be set before calling [method@Gdk.MemoryTextureBuilder.build]. + + + + + + a `GdkMemoryTextureBuilder` + + + + The texture's width or 0 to unset + + + + + + The bytes holding the data. + + + + The colorstate describing the data. + + + + The format of the data. + + + + The height of the texture. + + + + The rowstride of the texture. + +The rowstride is the number of bytes between the first pixel +in a row of image data, and the first pixel in the next row. + + + + The update region for [property@Gdk.MemoryTextureBuilder:update-texture]. + + + + The texture [property@Gdk.MemoryTextureBuilder:update-region] is an update for. + + + + The width of the texture. + + + + + + + Flags to indicate the state of modifier keys and mouse buttons +in events. + +Typical modifier keys are Shift, Control, Meta, Super, Hyper, Alt, Compose, +Apple, CapsLock or ShiftLock. + +Note that GDK may add internal values to events which include values outside +of this enumeration. Your code should preserve and ignore them. You can use +%GDK_MODIFIER_MASK to remove all private values. + + No modifier. + + + the Shift key. + + + a Lock key (depending on the modifier mapping of the + X server this may either be CapsLock or ShiftLock). + + the Control key. @@ -18074,7 +18898,7 @@ a particular backend supports input regions. - + Marks a region of the `GdkSurface` as opaque. For optimisation purposes, compositing window managers may @@ -18090,6 +18914,8 @@ GTK will update this property automatically if the @surface background is opaque, as we know where the opaque regions are. If your surface background is not opaque, please update this property in your [GtkWidgetClass.css_changed](../gtk4/vfunc.Widget.css_changed.html) handler. + GDK can figure out the opaque parts of a window itself + by inspecting the contents that are drawn. @@ -18288,7 +19114,18 @@ instance; you can only make a copy of it, via [method@Gdk.Texture.download]. `GdkTexture` is an immutable object: That means you cannot change anything about it other than increasing the reference count via -[method@GObject.Object.ref], and consequently, it is a thread-safe object. +[method@GObject.Object.ref], and consequently, it is a threadsafe object. + +GDK provides a number of threadsafe texture loading functions: +[ctor@Gdk.Texture.new_from_resource], +[ctor@Gdk.Texture.new_from_bytes], +[ctor@Gdk.Texture.new_from_file], +[ctor@Gdk.Texture.new_from_filename], +[ctor@Gdk.Texture.new_for_pixbuf]. Note that these are meant for loading +icons and resources that are shipped with the toolkit or application. It +is recommended that you use a dedicated image loading framework such as +[glycin](https://lib.rs/crates/glycin), if you need to load untrusted image +data. @@ -18444,6 +19281,19 @@ For more flexible download capabilities, see + + Returns the color state associated with the texture. + + the color state of the `GdkTexture` + + + + + a `GdkTexture` + + + + Gets the memory format most closely associated with the data of the texture. @@ -18583,6 +19433,10 @@ use [method@Gdk.Texture.save_to_png_bytes]. + + The color state of the texture. + + The height of the texture, in pixels. @@ -18605,7 +19459,10 @@ settings. Create a `GdkTexture` for the existing format and then download it in a different format. - Creates a new texture downloader for @texture. + Creates a new texture downloader for @texture. + +By default, the downloader will convert the data to +the default memory format, and to the sRGB color state. A new texture downloader @@ -18690,6 +19547,19 @@ once allocation succeeded. + + Gets the color state that the data will be downloaded in. + + The color state of the download + + + + + a texture downloader + + + + Gets the format that the data will be downloaded in. @@ -18716,6 +19586,25 @@ once allocation succeeded. + + Sets the color state the downloader will convert the data to. + +By default, the sRGB colorstate returned by [func@ColorState.get_srgb] +is used. + + + + + + a texture downloader + + + + the color state to use + + + + Sets the format the downloader will download. @@ -19682,8 +20571,8 @@ being set. whether the left edge is resizable - - the surface is not visible to the user + + The surface is not visible to the user. @@ -20020,6 +20909,75 @@ so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y. + + + + + + + + + + + + Returns the color state object representing the linear rec2100 color space. + +This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and a linear +transfer function. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/8/0/1. + +See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-linear) +for details about this colorstate. + + the color state object for linearized rec2100 + + + + + Returns the color state object representing the rec2100-pq color space. + +This color state uses the primaries defined by BT.2020-2 and BT.2100-0 and the transfer +function defined by SMPTE ST 2084 and BT.2100-2. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 9/16/0/1. + +See e.g. [the CSS HDR Module](https://drafts.csswg.org/css-color-hdr/#valdef-color-rec2100-pq) +for details about this colorstate. + + the color state object for rec2100-pq + + + + + Returns the color state object representing the sRGB color space. + +This color state uses the primaries defined by BT.709-6 and the transfer function +defined by IEC 61966-2-1. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/13/0/1. + +See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB) +for details about this colorstate. + + the color state object for sRGB + + + + + Returns the color state object representing the linearized sRGB color space. + +This color state uses the primaries defined by BT.709-6 and a linear transfer function. + +It is equivalent to the [Cicp](class.CicpParams.html) tuple 1/8/0/1. + +See e.g. [the CSS Color Module](https://www.w3.org/TR/css-color-4/#predefined-sRGB-linear) +for details about this colorstate. + + the color state object for linearized sRGB + + + Read content from the given input stream and deserialize it, asynchronously. diff --git a/Gio-2.0.gir b/Gio-2.0.gir index 9fc38c13..13628253 100644 --- a/Gio-2.0.gir +++ b/Gio-2.0.gir @@ -8,13 +8,13 @@ and/or use gtk-doc annotations. --> - - + + + + + + - - - - @@ -646,27 +646,26 @@ action is stateless. This is immutable. This struct defines a single action. It is for use with -g_action_map_add_action_entries(). +[method@Gio.ActionMap.add_action_entries]. The order of the items in the structure are intended to reflect frequency of use. It is permissible to use an incomplete initialiser -in order to leave some of the later values as %NULL. All values +in order to leave some of the later values as `NULL`. All values after @name are optional. Additional optional fields may be added in the future. -See g_action_map_add_action_entries() for an example. +See [method@Gio.ActionMap.add_action_entries] for an example. the name of the action - the callback to connect to the "activate" signal of the - action. Since GLib 2.40, this can be %NULL for stateful - actions, in which case the default handler is used. For - boolean-stated actions with no parameter, this is a - toggle. For other state types (and parameter type equal - to the state type) this will be a function that - just calls @change_state (which you should provide). + the callback to connect to the "activate" signal of the action. + Since GLib 2.40, this can be `NULL` for stateful actions, in which case + the default handler is used. For boolean-stated actions with no + parameter, this is a toggle. For other state types (and parameter type + equal to the state type) this will be a function that just calls + @change_state (which you should provide). @@ -686,22 +685,21 @@ See g_action_map_add_action_entries() for an example. the type of the parameter that must be passed to the - activate function for this action, given as a single - GVariant type string (or %NULL for no parameter) + activate function for this action, given as a single GVariant type string + (or `NULL` for no parameter) the initial state for this action, given in - [GVariant text format](gvariant-text-format.html). The state is parsed - with no extra type information, so type tags must be added to - the string if they are necessary. Stateless actions should - give %NULL here. + [GVariant text format](gvariant-text-format.html). The state is parsed + with no extra type information, so type tags must be added to the string + if they are necessary. Stateless actions should give `NULL` here. - the callback to connect to the "change-state" signal - of the action. All stateful actions should provide a - handler here; stateless actions should not. + the callback to connect to the "change-state" signal of the + action. All stateful actions should provide a handler here; stateless + actions should not. @@ -2077,7 +2075,7 @@ implementations that operate by containing a number of named One useful application of this interface is to map the names of actions from various action groups to unique, prefixed names (e.g. by prepending "app." or "win."). -This is the motivation for the 'Map' part of the interface +This is the motivation for the ‘Map’ part of the interface name. Adds an action to the @action_map. @@ -2091,11 +2089,11 @@ The action map takes its own reference on @action. - a #GActionMap + an action map - a #GAction + a [iface@Gio.Action] @@ -2103,14 +2101,14 @@ The action map takes its own reference on @action. Looks up the action with the name @action_name in @action_map. -If no such action exists, returns %NULL. +If no such action exists, returns `NULL`. - a #GAction, or %NULL + a [iface@Gio.Action] - a #GActionMap + an action map @@ -2128,7 +2126,7 @@ If no action of this name is in the map then nothing happens. - a #GActionMap + an action map @@ -2149,22 +2147,22 @@ The action map takes its own reference on @action. - a #GActionMap + an action map - a #GAction + a [iface@Gio.Action] - A convenience function for creating multiple #GSimpleAction instances -and adding them to a #GActionMap. + A convenience function for creating multiple [class@Gio.SimpleAction] +instances and adding them to a [iface@Gio.ActionMap]. -Each action is constructed as per one #GActionEntry. +Each action is constructed as per one [struct@Gio.ActionEntry]. -|[<!-- language="C" --> +```c static void activate_quit (GSimpleAction *simple, GVariant *parameter, @@ -2195,24 +2193,24 @@ create_action_group (void) return G_ACTION_GROUP (group); } -]| +``` - a #GActionMap + an action map a pointer to - the first item in an array of #GActionEntry structs + the first item in an array of [struct@Gio.ActionEntry] structs - the length of @entries, or -1 if @entries is %NULL-terminated + the length of @entries, or -1 if @entries is `NULL`-terminated @@ -2224,14 +2222,14 @@ create_action_group (void) Looks up the action with the name @action_name in @action_map. -If no such action exists, returns %NULL. +If no such action exists, returns `NULL`. - a #GAction, or %NULL + a [iface@Gio.Action] - a #GActionMap + an action map @@ -2249,7 +2247,7 @@ If no action of this name is in the map then nothing happens. - a #GActionMap + an action map @@ -2259,11 +2257,11 @@ If no action of this name is in the map then nothing happens. - Remove actions from a #GActionMap. This is meant as the reverse of -g_action_map_add_action_entries(). + Remove actions from a [iface@Gio.ActionMap]. This is meant as the reverse of +[method@Gio.ActionMap.add_action_entries]. -|[<!-- language="C" --> +```c static const GActionEntry entries[] = { { "quit", activate_quit }, { "print-string", activate_print_string, "s" } @@ -2280,44 +2278,45 @@ remove_actions (GActionMap *map) { g_action_map_remove_action_entries (map, entries, G_N_ELEMENTS (entries)); } -]| +``` - The #GActionMap + The [iface@Gio.ActionMap] a pointer to - the first item in an array of #GActionEntry structs + the first item in an array of [struct@Gio.ActionEntry] structs - the length of @entries, or -1 if @entries is %NULL-terminated + the length of @entries, or -1 if @entries is `NULL`-terminated - The virtual function table for #GActionMap. + The virtual function table for [iface@Gio.ActionMap]. - the virtual function pointer for g_action_map_lookup_action() + the virtual function pointer for + [method@Gio.ActionMap.lookup_action] - a #GAction, or %NULL + a [iface@Gio.Action] - a #GActionMap + an action map @@ -2328,32 +2327,34 @@ remove_actions (GActionMap *map) - the virtual function pointer for g_action_map_add_action() + the virtual function pointer for + [method@Gio.ActionMap.add_action] - a #GActionMap + an action map - a #GAction + a [iface@Gio.Action] - the virtual function pointer for g_action_map_remove_action() + the virtual function pointer for + [method@Gio.ActionMap.remove_action] - a #GActionMap + an action map @@ -2374,15 +2375,19 @@ applications installed on the system. As of GLib 2.20, URIs will always be converted to POSIX paths (using [method@Gio.File.get_path]) when using [method@Gio.AppInfo.launch] even if the application requested an URI and not a POSIX path. For example -for a desktop-file based application with Exec key `totem -%U` and a single URI, `sftp://foo/file.avi`, then -`/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will -only work if a set of suitable GIO extensions (such as GVfs 2.26 -compiled with FUSE support), is available and operational; if this -is not the case, the URI will be passed unmodified to the application. -Some URIs, such as `mailto:`, of course cannot be mapped to a POSIX -path (in GVfs there's no FUSE mount for it); such URIs will be -passed unmodified to the application. +for a desktop-file based application with the following Exec key: + +``` +Exec=totem %U +``` + +and a single URI, `sftp://foo/file.avi`, then +`/home/user/.gvfs/sftp on foo/file.avi` will be passed. This will only work +if a set of suitable GIO extensions (such as GVfs 2.26 compiled with FUSE +support), is available and operational; if this is not the case, the URI +will be passed unmodified to the application. Some URIs, such as `mailto:`, +of course cannot be mapped to a POSIX path (in GVfs there’s no FUSE mount +for it); such URIs will be passed unmodified to the application. Specifically for GVfs 2.26 and later, the POSIX URI will be mapped back to the GIO URI in the [iface@Gio.File] constructors (since GVfs @@ -2412,33 +2417,35 @@ g_object_unref (file); This code will work when both `cdda://sr0/Track 1.wav` and `/home/user/.gvfs/cdda on sr0/Track 1.wav` is passed to the -application. It should be noted that it's generally not safe +application. It should be noted that it’s generally not safe for applications to rely on the format of a particular URIs. Different launcher applications (e.g. file managers) may have different ideas of what a given URI means. - Creates a new #GAppInfo from the given information. + Creates a new [iface@Gio.AppInfo] from the given information. -Note that for @commandline, the quoting rules of the Exec key of the +Note that for @commandline, the quoting rules of the `Exec` key of the [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) are applied. For example, if the @commandline contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from -being swallowed by Exec key unquoting. See the specification for exact quoting rules. +being swallowed by `Exec` key unquoting. See +[the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) +for exact quoting rules. - new #GAppInfo for given command. + new [iface@Gio.AppInfo] for given command. - the commandline to use + the command line to use - the application name, or %NULL to use @commandline + the application name, or `NULL` to use @commandline - flags that can specify details of the created #GAppInfo + flags that can specify details of the created [iface@Gio.AppInfo] @@ -2448,76 +2455,84 @@ being swallowed by Exec key unquoting. See the specification for exact quoting r on this system. For desktop files, this includes applications that have -`NoDisplay=true` set or are excluded from display by means -of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). -The returned list does not include applications which have -the `Hidden` key set. +[`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) +set or are excluded from display by means of +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). +See [method@Gio.AppInfo.should_show]. + +The returned list does not include applications which have the +[`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) +set. - a newly allocated #GList of references to #GAppInfos. + a newly allocated + list of references to [iface@Gio.AppInfo]s. - Gets a list of all #GAppInfos for a given content type, -including the recommended and fallback #GAppInfos. See -g_app_info_get_recommended_for_type() and -g_app_info_get_fallback_for_type(). + Gets a list of all [iface@Gio.AppInfo]s for a given content type, +including the recommended and fallback [iface@Gio.AppInfo]s. See +[func@Gio.AppInfo.get_recommended_for_type] and +[func@Gio.AppInfo.get_fallback_for_type]. - #GList of #GAppInfos - for given @content_type or %NULL on error. + list of + [iface@Gio.AppInfo]s for given @content_type. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - Gets the default #GAppInfo for a given content type. + Gets the default [iface@Gio.AppInfo] for a given content type. - #GAppInfo for given @content_type or - %NULL on error. + [iface@Gio.AppInfo] for given + @content_type or `NULL` on error. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - if %TRUE, the #GAppInfo is expected to - support URIs + if `TRUE`, the [iface@Gio.AppInfo] is expected to + support URIs - Asynchronously gets the default #GAppInfo for a given content type. + Asynchronously gets the default [iface@Gio.AppInfo] for a given content +type. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - if %TRUE, the #GAppInfo is expected to - support URIs + if `TRUE`, the [iface@Gio.AppInfo] is expected to + support URIs - optional #GCancellable object, %NULL to ignore + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -2527,30 +2542,31 @@ g_app_info_get_fallback_for_type(). - Finishes a default #GAppInfo lookup started by -g_app_info_get_default_for_type_async(). + Finishes a default [iface@Gio.AppInfo] lookup started by +[func@Gio.AppInfo.get_default_for_type_async]. -If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. +If no #[iface@Gio.AppInfo] is found, then @error will be set to +[error@Gio.IOErrorEnum.NOT_FOUND]. - #GAppInfo for given @content_type or - %NULL on error. + [iface@Gio.AppInfo] for given @content_type or + `NULL` on error. - a #GAsyncResult + the async result - Gets the default application for handling URIs with -the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". + Gets the default application for handling URIs with the given URI scheme. + +A URI scheme is the initial part of the URI, up to but not including the `:`. +For example, `http`, `ftp` or `sip`. - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. @@ -2563,8 +2579,8 @@ of the URI, up to but not including the ':', e.g. "http", Asynchronously gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". +of the URI, up to but not including the `:`, e.g. `http`, +`ftp` or `sip`. @@ -2574,11 +2590,12 @@ of the URI, up to but not including the ':', e.g. "http", - optional #GCancellable object, %NULL to ignore + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -2588,72 +2605,73 @@ of the URI, up to but not including the ':', e.g. "http", - Finishes a default #GAppInfo lookup started by -g_app_info_get_default_for_uri_scheme_async(). + Finishes a default [iface@Gio.AppInfo] lookup started by +[func@Gio.AppInfo.get_default_for_uri_scheme_async]. -If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. +If no [iface@Gio.AppInfo] is found, then @error will be set to +[error@Gio.IOErrorEnum.NOT_FOUND]. - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given @uri_scheme or + `NULL` on error. - a #GAsyncResult + the async result - Gets a list of fallback #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type -by MIME type subclassing and not directly. + Gets a list of fallback [iface@Gio.AppInfo]s for a given content type, i.e. +those applications which claim to support the given content type by MIME +type subclassing and not directly. - #GList of #GAppInfos - for given @content_type or %NULL on error. + list of [iface@Gio.AppInfo]s + for given @content_type or `NULL` on error. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - Gets a list of recommended #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type exactly, -and not by MIME type subclassing. + Gets a list of recommended [iface@Gio.AppInfo]s for a given content type, +i.e. those applications which claim to support the given content type +exactly, and not by MIME type subclassing. + Note that the first application of the list is the last used one, i.e. -the last one for which g_app_info_set_as_last_used_for_type() has been -called. +the last one for which [method@Gio.AppInfo.set_as_last_used_for_type] has +been called. - #GList of #GAppInfos - for given @content_type or %NULL on error. + list of + [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - Utility function that launches the default application -registered to handle the specified uri. Synchronous I/O -is done on the uri to detect the type of the file if -required. + Utility function that launches the default application registered to handle +the specified uri. Synchronous I/O is done on the uri to detect the type of +the file if required. -The D-Bus–activated applications don't have to be started if your application +The D-Bus–activated applications don’t have to be started if your application terminates too soon after this function. To prevent this, use -g_app_info_launch_default_for_uri_async() instead. +[func@Gio.AppInfo.launch_default_for_uri_async] instead. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. @@ -2662,18 +2680,17 @@ g_app_info_launch_default_for_uri_async() instead. - an optional #GAppLaunchContext + optional launch context - Async version of g_app_info_launch_default_for_uri(). + Async version of [func@Gio.AppInfo.launch_default_for_uri]. -This version is useful if you are interested in receiving -error information in the case where the application is -sandboxed and the portal may present an application chooser -dialog to the user. +This version is useful if you are interested in receiving error information +in the case where the application is sandboxed and the portal may present an +application chooser dialog to the user. This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested @@ -2687,15 +2704,16 @@ in receiving error information from their activation. - an optional #GAppLaunchContext + optional launch context - a #GCancellable + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -2707,22 +2725,22 @@ in receiving error information from their activation. Finishes an asynchronous launch-default-for-uri operation. - %TRUE if the launch was successful, %FALSE if @error is set + `TRUE` if the launch was successful, `FALSE` if @error is set - a #GAsyncResult + the async result Removes all changes to the type associations done by -g_app_info_set_as_default_for_type(), -g_app_info_set_as_default_for_extension(), -g_app_info_add_supports_type() or -g_app_info_remove_supports_type(). +[method@Gio.AppInfo.set_as_default_for_type], +[method@Gio.AppInfo.set_as_default_for_extension], +[method@Gio.AppInfo.add_supports_type] or +[method@Gio.AppInfo.remove_supports_type]. @@ -2737,12 +2755,12 @@ g_app_info_remove_supports_type(). Adds a content type to the application information to indicate the application is capable of opening files with the given content type. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -2752,15 +2770,15 @@ application is capable of opening files with the given content type. - Obtains the information whether the #GAppInfo can be deleted. -See g_app_info_delete(). + Obtains the information whether the [iface@Gio.AppInfo] can be deleted. +See [method@Gio.AppInfo.delete]. - %TRUE if @appinfo can be deleted + `TRUE` if @appinfo can be deleted - a #GAppInfo + the app info @@ -2768,64 +2786,64 @@ See g_app_info_delete(). Checks if a supported content type can be removed from an application. - %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. + `TRUE` if it is possible to remove supported content types from a + given @appinfo, `FALSE` if not. - a #GAppInfo. + the app info - Tries to delete a #GAppInfo. + Tries to delete a [iface@Gio.AppInfo]. On some platforms, there may be a difference between user-defined -#GAppInfos which can be deleted, and system-wide ones which cannot. -See g_app_info_can_delete(). +[iface@Gio.AppInfo]s which can be deleted, and system-wide ones which cannot. +See [method@Gio.AppInfo.can_delete]. - %TRUE if @appinfo has been deleted + `TRUE` if @appinfo has been deleted - a #GAppInfo + the app info - Creates a duplicate of a #GAppInfo. + Creates a duplicate of a [iface@Gio.AppInfo]. a duplicate of @appinfo. - a #GAppInfo. + the app info - Checks if two #GAppInfos are equal. + Checks if two [iface@Gio.AppInfo]s are equal. -Note that the check *may not* compare each individual -field, and only does an identity check. In case detecting changes in the -contents is needed, program code must additionally compare relevant fields. +Note that the check *may not* compare each individual field, and only does +an identity check. In case detecting changes in the contents is needed, +program code must additionally compare relevant fields. - %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + `TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. - the first #GAppInfo. + the first [iface@Gio.AppInfo]. - the second #GAppInfo. + the second [iface@Gio.AppInfo]. @@ -2834,13 +2852,13 @@ contents is needed, program code must additionally compare relevant fields.Gets the commandline with which the application will be started. - a string containing the @appinfo's commandline, - or %NULL if this information is not available + a string containing the @appinfo’s + commandline, or `NULL` if this information is not available - a #GAppInfo + the app info @@ -2849,12 +2867,12 @@ started. Gets a human-readable description of an installed application. a string containing a description of the -application @appinfo, or %NULL if none. +application @appinfo, or `NULL` if none. - a #GAppInfo. + the app info @@ -2869,25 +2887,25 @@ no display name is available. - a #GAppInfo. + the app info - Gets the executable's name for the installed application. + Gets the executable’s name for the installed application. This is intended to be used for debugging or labelling what program is going -to be run. To launch the executable, use g_app_info_launch() and related +to be run. To launch the executable, use [method@Gio.AppInfo.launch] and related functions, rather than spawning the return value from this function. - a string containing the @appinfo's application + a string containing the @appinfo’s application binaries name - a #GAppInfo + the app info @@ -2895,32 +2913,31 @@ binaries name Gets the icon for the application. - the default #GIcon for @appinfo or %NULL -if there is no default icon. + the default [iface@Gio.Icon] for + @appinfo or `NULL` if there is no default icon. - a #GAppInfo. + the app info - Gets the ID of an application. An id is a string that -identifies the application. The exact format of the id is -platform dependent. For instance, on Unix this is the -desktop file id from the xdg menu specification. + Gets the ID of an application. An id is a string that identifies the +application. The exact format of the id is platform dependent. For instance, +on Unix this is the desktop file id from the xdg menu specification. -Note that the returned ID may be %NULL, depending on how -the @appinfo has been constructed. +Note that the returned ID may be `NULL`, depending on how the @appinfo has +been constructed. - a string containing the application's ID. + a string containing the application’s ID. - a #GAppInfo. + the app info @@ -2933,7 +2950,7 @@ the @appinfo has been constructed. - a #GAppInfo. + the app info @@ -2941,20 +2958,21 @@ the @appinfo has been constructed. Retrieves the list of content types that @app_info claims to support. If this information is not provided by the environment, this function -will return %NULL. +will return `NULL`. + This function does not take in consideration associations added with -g_app_info_add_supports_type(), but only those exported directly by +[method@Gio.AppInfo.add_supports_type], but only those exported directly by the application. - a list of content types. + a list of content types. - a #GAppInfo that can handle files + an app info that can handle files @@ -2965,7 +2983,7 @@ as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. -To launch the application without arguments pass a %NULL @files list. +To launch the application without arguments pass a `NULL` @files list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is @@ -2974,11 +2992,11 @@ no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using -g_app_info_launch_uris() instead. +[method@Gio.AppInfo.launch_uris] instead. The launched application inherits the environment of the launching -process, but it can be modified with g_app_launch_context_setenv() -and g_app_launch_context_unsetenv(). +process, but it can be modified with [method@Gio.AppLaunchContext.setenv] +and [method@Gio.AppLaunchContext.unsetenv]. On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` environment variable with the path of the launched desktop file and @@ -2988,22 +3006,22 @@ should it be inherited by further processes. The `DISPLAY`, `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment variables are also set, based on information provided in @context. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GList of #GFile objects + a list of [iface@Gio.File] objects - a #GAppLaunchContext or %NULL + the launch context @@ -3016,63 +3034,64 @@ On error, @error will be set accordingly. If the application only supports one URI per invocation as part of their command-line, multiple instances of the application will be spawned. -To launch the application without arguments pass a %NULL @uris list. +To launch the application without arguments pass a `NULL` @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GList containing URIs to launch. + a list of URIs to launch. - a #GAppLaunchContext or %NULL + the launch context - Async version of g_app_info_launch_uris(). + Async version of [method@Gio.AppInfo.launch_uris]. The @callback is invoked immediately after the application launch, but it waits for activation in case of D-Bus–activated applications and also provides extended error information for sandboxed applications, see notes for -g_app_info_launch_default_for_uri_async(). +[func@Gio.AppInfo.launch_default_for_uri_async]. - a #GAppInfo + the app info - a #GList containing URIs to launch. + a list of URIs to launch. - a #GAppLaunchContext or %NULL + the launch context - a #GCancellable + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -3082,18 +3101,18 @@ g_app_info_launch_default_for_uri_async(). - Finishes a g_app_info_launch_uris_async() operation. + Finishes a [method@Gio.AppInfo.launch_uris_async] operation. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GAsyncResult + the async result @@ -3101,12 +3120,12 @@ g_app_info_launch_default_for_uri_async(). Removes a supported type from an application, if possible. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3118,17 +3137,17 @@ g_app_info_launch_default_for_uri_async(). Sets the application as the default handler for the given file extension. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info - a string containing the file extension - (without the dot). + a string containing the file extension (without + the dot). @@ -3136,12 +3155,12 @@ g_app_info_launch_default_for_uri_async(). Sets the application as the default handler for a given type. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3151,17 +3170,17 @@ g_app_info_launch_default_for_uri_async(). - Sets the application as the last used application for a given type. -This will make the application appear as first in the list returned -by g_app_info_get_recommended_for_type(), regardless of the default + Sets the application as the last used application for a given type. This +will make the application appear as first in the list returned by +[func@Gio.AppInfo.get_recommended_for_type], regardless of the default application for that content type. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3174,12 +3193,12 @@ application for that content type. Checks if the application info should be shown in menus that list available applications. - %TRUE if the @appinfo should be shown, %FALSE otherwise. + `TRUE` if the @appinfo should be shown, `FALSE` otherwise. - a #GAppInfo. + the app info @@ -3187,12 +3206,12 @@ list available applications. Checks if the application accepts files as arguments. - %TRUE if the @appinfo supports files. + `TRUE` if the @appinfo supports files. - a #GAppInfo. + the app info @@ -3200,12 +3219,12 @@ list available applications. Checks if the application supports reading files and directories from URIs. - %TRUE if the @appinfo supports URIs. + `TRUE` if the @appinfo supports URIs. - a #GAppInfo. + the app info @@ -3214,12 +3233,12 @@ list available applications. Adds a content type to the application information to indicate the application is capable of opening files with the given content type. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3229,15 +3248,15 @@ application is capable of opening files with the given content type. - Obtains the information whether the #GAppInfo can be deleted. -See g_app_info_delete(). + Obtains the information whether the [iface@Gio.AppInfo] can be deleted. +See [method@Gio.AppInfo.delete]. - %TRUE if @appinfo can be deleted + `TRUE` if @appinfo can be deleted - a #GAppInfo + the app info @@ -3245,64 +3264,64 @@ See g_app_info_delete(). Checks if a supported content type can be removed from an application. - %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. + `TRUE` if it is possible to remove supported content types from a + given @appinfo, `FALSE` if not. - a #GAppInfo. + the app info - Tries to delete a #GAppInfo. + Tries to delete a [iface@Gio.AppInfo]. On some platforms, there may be a difference between user-defined -#GAppInfos which can be deleted, and system-wide ones which cannot. -See g_app_info_can_delete(). +[iface@Gio.AppInfo]s which can be deleted, and system-wide ones which cannot. +See [method@Gio.AppInfo.can_delete]. - %TRUE if @appinfo has been deleted + `TRUE` if @appinfo has been deleted - a #GAppInfo + the app info - Creates a duplicate of a #GAppInfo. + Creates a duplicate of a [iface@Gio.AppInfo]. a duplicate of @appinfo. - a #GAppInfo. + the app info - Checks if two #GAppInfos are equal. + Checks if two [iface@Gio.AppInfo]s are equal. -Note that the check *may not* compare each individual -field, and only does an identity check. In case detecting changes in the -contents is needed, program code must additionally compare relevant fields. +Note that the check *may not* compare each individual field, and only does +an identity check. In case detecting changes in the contents is needed, +program code must additionally compare relevant fields. - %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + `TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. - the first #GAppInfo. + the first [iface@Gio.AppInfo]. - the second #GAppInfo. + the second [iface@Gio.AppInfo]. @@ -3311,13 +3330,13 @@ contents is needed, program code must additionally compare relevant fields.Gets the commandline with which the application will be started. - a string containing the @appinfo's commandline, - or %NULL if this information is not available + a string containing the @appinfo’s + commandline, or `NULL` if this information is not available - a #GAppInfo + the app info @@ -3326,12 +3345,12 @@ started. Gets a human-readable description of an installed application. a string containing a description of the -application @appinfo, or %NULL if none. +application @appinfo, or `NULL` if none. - a #GAppInfo. + the app info @@ -3346,25 +3365,25 @@ no display name is available. - a #GAppInfo. + the app info - Gets the executable's name for the installed application. + Gets the executable’s name for the installed application. This is intended to be used for debugging or labelling what program is going -to be run. To launch the executable, use g_app_info_launch() and related +to be run. To launch the executable, use [method@Gio.AppInfo.launch] and related functions, rather than spawning the return value from this function. - a string containing the @appinfo's application + a string containing the @appinfo’s application binaries name - a #GAppInfo + the app info @@ -3372,32 +3391,31 @@ binaries name Gets the icon for the application. - the default #GIcon for @appinfo or %NULL -if there is no default icon. + the default [iface@Gio.Icon] for + @appinfo or `NULL` if there is no default icon. - a #GAppInfo. + the app info - Gets the ID of an application. An id is a string that -identifies the application. The exact format of the id is -platform dependent. For instance, on Unix this is the -desktop file id from the xdg menu specification. + Gets the ID of an application. An id is a string that identifies the +application. The exact format of the id is platform dependent. For instance, +on Unix this is the desktop file id from the xdg menu specification. -Note that the returned ID may be %NULL, depending on how -the @appinfo has been constructed. +Note that the returned ID may be `NULL`, depending on how the @appinfo has +been constructed. - a string containing the application's ID. + a string containing the application’s ID. - a #GAppInfo. + the app info @@ -3410,7 +3428,7 @@ the @appinfo has been constructed. - a #GAppInfo. + the app info @@ -3418,20 +3436,21 @@ the @appinfo has been constructed. Retrieves the list of content types that @app_info claims to support. If this information is not provided by the environment, this function -will return %NULL. +will return `NULL`. + This function does not take in consideration associations added with -g_app_info_add_supports_type(), but only those exported directly by +[method@Gio.AppInfo.add_supports_type], but only those exported directly by the application. - a list of content types. + a list of content types. - a #GAppInfo that can handle files + an app info that can handle files @@ -3442,7 +3461,7 @@ as arguments, using the optional @context to get information about the details of the launcher (like what screen it is on). On error, @error will be set accordingly. -To launch the application without arguments pass a %NULL @files list. +To launch the application without arguments pass a `NULL` @files list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is @@ -3451,11 +3470,11 @@ no way to detect this. Some URIs can be changed when passed through a GFile (for instance unsupported URIs with strange formats like mailto:), so if you have a textual URI you want to pass in as argument, consider using -g_app_info_launch_uris() instead. +[method@Gio.AppInfo.launch_uris] instead. The launched application inherits the environment of the launching -process, but it can be modified with g_app_launch_context_setenv() -and g_app_launch_context_unsetenv(). +process, but it can be modified with [method@Gio.AppLaunchContext.setenv] +and [method@Gio.AppLaunchContext.unsetenv]. On UNIX, this function sets the `GIO_LAUNCHED_DESKTOP_FILE` environment variable with the path of the launched desktop file and @@ -3465,22 +3484,22 @@ should it be inherited by further processes. The `DISPLAY`, `XDG_ACTIVATION_TOKEN` and `DESKTOP_STARTUP_ID` environment variables are also set, based on information provided in @context. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GList of #GFile objects + a list of [iface@Gio.File] objects - a #GAppLaunchContext or %NULL + the launch context @@ -3493,63 +3512,64 @@ On error, @error will be set accordingly. If the application only supports one URI per invocation as part of their command-line, multiple instances of the application will be spawned. -To launch the application without arguments pass a %NULL @uris list. +To launch the application without arguments pass a `NULL` @uris list. Note that even if the launch is successful the application launched can fail to start if it runs into problems during startup. There is no way to detect this. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GList containing URIs to launch. + a list of URIs to launch. - a #GAppLaunchContext or %NULL + the launch context - Async version of g_app_info_launch_uris(). + Async version of [method@Gio.AppInfo.launch_uris]. The @callback is invoked immediately after the application launch, but it waits for activation in case of D-Bus–activated applications and also provides extended error information for sandboxed applications, see notes for -g_app_info_launch_default_for_uri_async(). +[func@Gio.AppInfo.launch_default_for_uri_async]. - a #GAppInfo + the app info - a #GList containing URIs to launch. + a list of URIs to launch. - a #GAppLaunchContext or %NULL + the launch context - a #GCancellable + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -3559,18 +3579,18 @@ g_app_info_launch_default_for_uri_async(). - Finishes a g_app_info_launch_uris_async() operation. + Finishes a [method@Gio.AppInfo.launch_uris_async] operation. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GAsyncResult + the async result @@ -3578,12 +3598,12 @@ g_app_info_launch_default_for_uri_async(). Removes a supported type from an application, if possible. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3595,17 +3615,17 @@ g_app_info_launch_default_for_uri_async(). Sets the application as the default handler for the given file extension. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info - a string containing the file extension - (without the dot). + a string containing the file extension (without + the dot). @@ -3613,12 +3633,12 @@ g_app_info_launch_default_for_uri_async(). Sets the application as the default handler for a given type. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3628,17 +3648,17 @@ g_app_info_launch_default_for_uri_async(). - Sets the application as the last used application for a given type. -This will make the application appear as first in the list returned -by g_app_info_get_recommended_for_type(), regardless of the default + Sets the application as the last used application for a given type. This +will make the application appear as first in the list returned by +[func@Gio.AppInfo.get_recommended_for_type], regardless of the default application for that content type. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3651,12 +3671,12 @@ application for that content type. Checks if the application info should be shown in menus that list available applications. - %TRUE if the @appinfo should be shown, %FALSE otherwise. + `TRUE` if the @appinfo should be shown, `FALSE` otherwise. - a #GAppInfo. + the app info @@ -3664,12 +3684,12 @@ list available applications. Checks if the application accepts files as arguments. - %TRUE if the @appinfo supports files. + `TRUE` if the @appinfo supports files. - a #GAppInfo. + the app info @@ -3677,12 +3697,12 @@ list available applications. Checks if the application supports reading files and directories from URIs. - %TRUE if the @appinfo supports URIs. + `TRUE` if the @appinfo supports URIs. - a #GAppInfo. + the app info @@ -3710,7 +3730,7 @@ list available applications. - Copies a #GAppInfo. + Copies a [iface@Gio.AppInfo]. a duplicate of @appinfo. @@ -3718,48 +3738,48 @@ list available applications. - a #GAppInfo. + the app info - Checks two #GAppInfos for equality. + Checks two [iface@Gio.AppInfo]s for equality. - %TRUE if @appinfo1 is equal to @appinfo2. %FALSE otherwise. + `TRUE` if @appinfo1 is equal to @appinfo2. `FALSE` otherwise. - the first #GAppInfo. + the first [iface@Gio.AppInfo]. - the second #GAppInfo. + the second [iface@Gio.AppInfo]. - Gets a string identifier for a #GAppInfo. + Gets a string identifier for a [iface@Gio.AppInfo]. - a string containing the application's ID. + a string containing the application’s ID. - a #GAppInfo. + the app info - Gets the name of the application for a #GAppInfo. + Gets the name of the application for a [iface@Gio.AppInfo]. the name of the application for @appinfo. @@ -3767,110 +3787,113 @@ list available applications. - a #GAppInfo. + the app info - Gets a short description for the application described by the #GAppInfo. + Gets a short description for the application described by + the [iface@Gio.AppInfo]. a string containing a description of the -application @appinfo, or %NULL if none. +application @appinfo, or `NULL` if none. - a #GAppInfo. + the app info - Gets the executable name for the #GAppInfo. + Gets the executable name for the [iface@Gio.AppInfo]. - a string containing the @appinfo's application + a string containing the @appinfo’s application binaries name - a #GAppInfo + the app info - Gets the #GIcon for the #GAppInfo. + Gets the [iface@Gio.Icon] for the [iface@Gio.AppInfo]. - the default #GIcon for @appinfo or %NULL -if there is no default icon. + the default [iface@Gio.Icon] for + @appinfo or `NULL` if there is no default icon. - a #GAppInfo. + the app info - Launches an application specified by the #GAppInfo. + Launches an application specified by the [iface@Gio.AppInfo]. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GList of #GFile objects + a list of [iface@Gio.File] objects - a #GAppLaunchContext or %NULL + the launch context - Indicates whether the application specified supports launching URIs. + Indicates whether the application specified supports + launching URIs. - %TRUE if the @appinfo supports URIs. + `TRUE` if the @appinfo supports URIs. - a #GAppInfo. + the app info - Indicates whether the application specified accepts filename arguments. + Indicates whether the application specified accepts + filename arguments. - %TRUE if the @appinfo supports files. + `TRUE` if the @appinfo supports files. - a #GAppInfo. + the app info @@ -3880,53 +3903,55 @@ if there is no default icon. Launches an application with a list of URIs. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GList containing URIs to launch. + a list of URIs to launch. - a #GAppLaunchContext or %NULL + the launch context - Returns whether an application should be shown (e.g. when getting a list of installed applications). -[FreeDesktop.Org Startup Notification Specification](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). + Returns whether an application should be shown (e.g. when + getting a list of installed applications). + [FreeDesktop.Org Startup Notification Specification](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). - %TRUE if the @appinfo should be shown, %FALSE otherwise. + `TRUE` if the @appinfo should be shown, `FALSE` otherwise. - a #GAppInfo. + the app info - Sets an application as default for a given content type. + Sets an application as default for a given content + type. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3937,35 +3962,37 @@ if there is no default icon. - Sets an application as default for a given file extension. + Sets an application as default for a given + file extension. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info - a string containing the file extension - (without the dot). + a string containing the file extension (without + the dot). - Adds to the #GAppInfo information about supported file types. + Adds to the [iface@Gio.AppInfo] information about + supported file types. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -3976,31 +4003,33 @@ if there is no default icon. - Checks for support for removing supported file types from a #GAppInfo. + Checks for support for removing supported file + types from a [iface@Gio.AppInfo]. - %TRUE if it is possible to remove supported - content types from a given @appinfo, %FALSE if not. + `TRUE` if it is possible to remove supported content types from a + given @appinfo, `FALSE` if not. - a #GAppInfo. + the app info - Removes a supported application type from a #GAppInfo. + Removes a supported application type from a + [iface@Gio.AppInfo]. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -4011,53 +4040,55 @@ if there is no default icon. - Checks if a #GAppInfo can be deleted. Since 2.20 + Checks if a [iface@Gio.AppInfo] can be deleted. (Since 2.20) - %TRUE if @appinfo can be deleted + `TRUE` if @appinfo can be deleted - a #GAppInfo + the app info - Deletes a #GAppInfo. Since 2.20 + Deletes a [iface@Gio.AppInfo]. (Since 2.20) - %TRUE if @appinfo has been deleted + `TRUE` if @appinfo has been deleted - a #GAppInfo + the app info - Gets the commandline for the #GAppInfo. Since 2.20 + Gets the commandline for the [iface@Gio.AppInfo]. + (Since 2.20) - a string containing the @appinfo's commandline, - or %NULL if this information is not available + a string containing the @appinfo’s + commandline, or `NULL` if this information is not available - a #GAppInfo + the app info - Gets the display name for the #GAppInfo. Since 2.24 + Gets the display name for the [iface@Gio.AppInfo]. + (Since 2.24) the display name of the application for @appinfo, or the name if @@ -4066,22 +4097,23 @@ no display name is available. - a #GAppInfo. + the app info - Sets the application as the last used. See g_app_info_set_as_last_used_for_type(). + Sets the application as the last used. See + [method@Gio.AppInfo.set_as_last_used_for_type]. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. - a #GAppInfo. + the app info @@ -4092,50 +4124,53 @@ no display name is available. - Retrieves the list of content types that @app_info claims to support. + Retrieves the list of content types that @app_info + claims to support. - a list of content types. + a list of content types. - a #GAppInfo that can handle files + an app info that can handle files - Asynchronously launches an application with a list of URIs. (Since: 2.60) + Asynchronously launches an application with a list of + URIs. (Since: 2.60) - a #GAppInfo + the app info - a #GList containing URIs to launch. + a list of URIs to launch. - a #GAppLaunchContext or %NULL + the launch context - a #GCancellable + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -4146,19 +4181,20 @@ no display name is available. - Finishes an operation started with @launch_uris_async. (Since: 2.60) + Finishes an operation started with @launch_uris_async. + (Since: 2.60) - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GAppInfo + the app info - a #GAsyncResult + the async result @@ -4209,7 +4245,7 @@ on every change is pointless and expensive. Gets the #GAppInfoMonitor for the current thread-default main context. -The #GAppInfoMonitor will emit a "changed" signal in the +The #GAppInfoMonitor will emit a “changed” signal in the thread-default main context whenever the list of installed applications (as reported by g_app_info_get_all()) may have changed. @@ -4238,9 +4274,10 @@ handle for instance startup notification and launching the new application on the same screen as the launching window. Creates a new application launch context. This is not normally used, -instead you instantiate a subclass of this, such as #GdkAppLaunchContext. +instead you instantiate a subclass of this, such as +[`GdkAppLaunchContext`](https://docs.gtk.org/gdk4/class.AppLaunchContext.html). - a #GAppLaunchContext. + a launch context. @@ -4254,15 +4291,15 @@ application, by setting the `DISPLAY` environment variable. - a #GAppLaunchContext + the launch context - a #GAppInfo + the app info - a #GList of #GFile objects + a list of [iface@Gio.File] objects @@ -4282,23 +4319,25 @@ Activation tokens are defined in the [XDG Activation Protocol](https://wayland.a and startup notification IDs are defined in the [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). -Support for the XDG Activation Protocol was added in GLib 2.76. +Support for the XDG Activation Protocol was added in GLib 2.76. +Since GLib 2.82 @info and @files can be `NULL`. If that’s not supported by the backend, +the returned token will be `NULL`. - a startup notification ID for the application, or %NULL if - not supported. + a startup notification ID for the application, or `NULL` if + not supported. - a #GAppLaunchContext + the launch context - - a #GAppInfo + + the app info - - a #GList of #GFile objects + + a list of [iface@Gio.File] objects @@ -4307,17 +4346,19 @@ Support for the XDG Activation Protocol was added in GLib 2.76. Called when an application has failed to launch, so that it can cancel -the application startup notification started in g_app_launch_context_get_startup_notify_id(). +the application startup notification started in +[method@Gio.AppLaunchContext.get_startup_notify_id]. - a #GAppLaunchContext. + the launch context - the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). + the startup notification id that was returned by + [method@Gio.AppLaunchContext.get_startup_notify_id]. @@ -4364,15 +4405,15 @@ application, by setting the `DISPLAY` environment variable. - a #GAppLaunchContext + the launch context - a #GAppInfo + the app info - a #GList of #GFile objects + a list of [iface@Gio.File] objects @@ -4382,18 +4423,18 @@ application, by setting the `DISPLAY` environment variable. Gets the complete environment variable list to be passed to the child process when @context is used to launch an application. -This is a %NULL-terminated array of strings, where each string has +This is a `NULL`-terminated array of strings, where each string has the form `KEY=VALUE`. - the child's environment + the child’s environment - a #GAppLaunchContext + the launch context @@ -4411,23 +4452,25 @@ Activation tokens are defined in the [XDG Activation Protocol](https://wayland.a and startup notification IDs are defined in the [freedesktop.org Startup Notification Protocol](http://standards.freedesktop.org/startup-notification-spec/startup-notification-latest.txt). -Support for the XDG Activation Protocol was added in GLib 2.76. +Support for the XDG Activation Protocol was added in GLib 2.76. +Since GLib 2.82 @info and @files can be `NULL`. If that’s not supported by the backend, +the returned token will be `NULL`. - a startup notification ID for the application, or %NULL if - not supported. + a startup notification ID for the application, or `NULL` if + not supported. - a #GAppLaunchContext + the launch context - - a #GAppInfo + + the app info - - a #GList of #GFile objects + + a list of [iface@Gio.File] objects @@ -4436,30 +4479,32 @@ Support for the XDG Activation Protocol was added in GLib 2.76. Called when an application has failed to launch, so that it can cancel -the application startup notification started in g_app_launch_context_get_startup_notify_id(). +the application startup notification started in +[method@Gio.AppLaunchContext.get_startup_notify_id]. - a #GAppLaunchContext. + the launch context - the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). + the startup notification id that was returned by + [method@Gio.AppLaunchContext.get_startup_notify_id]. - Arranges for @variable to be set to @value in the child's -environment when @context is used to launch an application. + Arranges for @variable to be set to @value in the child’s environment when +@context is used to launch an application. - a #GAppLaunchContext + the launch context @@ -4473,14 +4518,14 @@ environment when @context is used to launch an application. - Arranges for @variable to be unset in the child's environment -when @context is used to launch an application. + Arranges for @variable to be unset in the child’s environment when @context +is used to launch an application. - a #GAppLaunchContext + the launch context @@ -4496,9 +4541,9 @@ when @context is used to launch an application. - The #GAppLaunchContext::launch-failed signal is emitted when a #GAppInfo launch -fails. The startup notification id is provided, so that the launcher -can cancel the startup notification. + The [signal@Gio.AppLaunchContext::launch-failed] signal is emitted when a +[iface@Gio.AppInfo] launch fails. The startup notification id is provided, +so that the launcher can cancel the startup notification. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple @@ -4514,11 +4559,11 @@ times, one for each spawned instance. - The #GAppLaunchContext::launch-started signal is emitted when a #GAppInfo is -about to be launched. If non-null the @platform_data is an -GVariant dictionary mapping strings to variants (ie `a{sv}`), which -contains additional, platform-specific data about this launch. On -UNIX, at least the `startup-notification-id` keys will be + The [signal@Gio.AppLaunchContext::launch-started] signal is emitted when a +[iface@Gio.AppInfo] is about to be launched. If non-null the +@platform_data is an GVariant dictionary mapping strings to variants +(ie `a{sv}`), which contains additional, platform-specific data about this +launch. On UNIX, at least the `startup-notification-id` keys will be present. The value of the `startup-notification-id` key (type `s`) is a startup @@ -4526,8 +4571,9 @@ notification ID corresponding to the format from the [startup-notification specification](https://specifications.freedesktop.org/startup-notification-spec/startup-notification-0.1.txt). It allows tracking the progress of the launchee through startup. -It is guaranteed that this signal is followed by either a #GAppLaunchContext::launched or -#GAppLaunchContext::launch-failed signal. +It is guaranteed that this signal is followed by either a +[signal@Gio.AppLaunchContext::launched] or +[signal@Gio.AppLaunchContext::launch-failed] signal. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple @@ -4537,7 +4583,7 @@ times, one for each spawned instance. - the #GAppInfo that is about to be launched + the [iface@Gio.AppInfo] that is about to be launched @@ -4547,8 +4593,8 @@ times, one for each spawned instance. - The #GAppLaunchContext::launched signal is emitted when a #GAppInfo is successfully -launched. + The [signal@Gio.AppLaunchContext::launched] signal is emitted when a +[iface@Gio.AppInfo] is successfully launched. Because a launch operation may involve spawning multiple instances of the target application, you should expect this signal to be emitted multiple @@ -4559,20 +4605,21 @@ strings to variants (ie `a{sv}`), which contains additional, platform-specific data about this launch. On UNIX, at least the `pid` and `startup-notification-id` keys will be present. -Since 2.72 the `pid` may be 0 if the process id wasn't known (for +Since 2.72 the `pid` may be 0 if the process id wasn’t known (for example if the process was launched via D-Bus). The `pid` may not be set at all in subsequent releases. On Windows, `pid` is guaranteed to be valid only for the duration of the -#GAppLaunchContext::launched signal emission; after the signal is emitted, -GLib will call g_spawn_close_pid(). If you need to keep the #GPid after the -signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. +[signal@Gio.AppLaunchContext::launched] signal emission; after the signal +is emitted, GLib will call [func@GLib.spawn_close_pid]. If you need to +keep the [alias@GLib.Pid] after the signal has been emitted, then you can +duplicate `pid` using `DuplicateHandle()`. - the #GAppInfo that was just launched + the [iface@Gio.AppInfo] that was just launched @@ -4594,15 +4641,15 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - a #GAppLaunchContext + the launch context - a #GAppInfo + the app info - a #GList of #GFile objects + a list of [iface@Gio.File] objects @@ -4613,21 +4660,21 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - a startup notification ID for the application, or %NULL if - not supported. + a startup notification ID for the application, or `NULL` if + not supported. - a #GAppLaunchContext + the launch context - - a #GAppInfo + + the app info - - a #GList of #GFile objects + + a list of [iface@Gio.File] objects @@ -4642,11 +4689,12 @@ signal has been emitted, then you can duplicate `pid` using `DuplicateHandle()`. - a #GAppLaunchContext. + the launch context - the startup notification id that was returned by g_app_launch_context_get_startup_notify_id(). + the startup notification id that was returned by + [method@Gio.AppLaunchContext.get_startup_notify_id]. @@ -5865,11 +5913,11 @@ replaced with @notification and shown again as if it was a new notification. This works even for notifications sent from a previous execution of the application, as long as @id is the same string. -@id may be %NULL, but it is impossible to replace or withdraw +@id may be `NULL`, but it is impossible to replace or withdraw notifications without an id. If @notification is no longer relevant, it can be withdrawn with -g_application_withdraw_notification(). +[method@Gio.Application.withdraw_notification]. It is an error to call this function if @application has no application ID. @@ -8286,7 +8334,7 @@ to enable subclasses to chain up correctly. - Buffered input stream implements #GFilterInputStream and provides + Buffered input stream implements [class@Gio.FilterInputStream] and provides for buffered reads. By default, `GBufferedInputStream`'s buffer size is set at 4 kilobytes. @@ -8301,29 +8349,29 @@ buffered input stream's buffer, use [method@Gio.BufferedInputStream.set_buffer_s Note that the buffer's size cannot be reduced below the size of the data within the buffer. - Creates a new #GInputStream from the given @base_stream, with + Creates a new [class@Gio.InputStream] from the given @base_stream, with a buffer set to the default size (4 kilobytes). - a #GInputStream for the given @base_stream. + a [class@Gio.InputStream] for the given @base_stream. - a #GInputStream + a [class@Gio.InputStream] - Creates a new #GBufferedInputStream from the given @base_stream, + Creates a new [class@Gio.BufferedInputStream] from the given @base_stream, with a buffer set to @size. - a #GInputStream. + a [class@Gio.InputStream]. - a #GInputStream + a [class@Gio.InputStream] @@ -8337,7 +8385,8 @@ with a buffer set to @size. Will block during this read. If @count is zero, returns zero and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. +larger than `G_MAXSSIZE` will cause a +[error@Gio.IOErrorEnum.INVALID_ARGUMENT] error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it @@ -8347,24 +8396,24 @@ can happen e.g. near the end of a file. Zero is returned on end of file If @count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. -If @cancellable is not %NULL, then the operation can be cancelled by +If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the +was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. +If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. -On error -1 is returned and @error is set accordingly. +On error `-1` is returned and @error is set accordingly. For the asynchronous, non-blocking, version of this function, see -g_buffered_input_stream_fill_async(). +[method@Gio.BufferedInputStream.fill_async]. the number of bytes read into @stream's buffer, up to @count, - or -1 on error. + or `-1` on error. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8372,7 +8421,7 @@ g_buffered_input_stream_fill_async(). - optional #GCancellable object, %NULL to ignore + optional [class@Gio.Cancellable] object, `NULL` to ignore @@ -8380,16 +8429,16 @@ g_buffered_input_stream_fill_async(). Reads data into @stream's buffer asynchronously, up to @count size. @io_priority can be used to prioritize reads. For the synchronous -version of this function, see g_buffered_input_stream_fill(). +version of this function, see [method@Gio.BufferedInputStream.fill]. -If @count is -1 then the attempted read size is equal to the number +If @count is `-1` then the attempted read size is equal to the number of bytes that are required to fill the buffer. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8401,11 +8450,11 @@ of bytes that are required to fill the buffer. - optional #GCancellable object + optional [class@Gio.Cancellable] object - a #GAsyncReadyCallback + a [callback@Gio.AsyncReadyCallback] @@ -8422,11 +8471,11 @@ of bytes that are required to fill the buffer. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] - a #GAsyncResult + a [iface@Gio.AsyncResult] @@ -8436,7 +8485,8 @@ of bytes that are required to fill the buffer. Will block during this read. If @count is zero, returns zero and does nothing. A value of @count -larger than %G_MAXSSIZE will cause a %G_IO_ERROR_INVALID_ARGUMENT error. +larger than `G_MAXSSIZE` will cause a +[error@Gio.IOErrorEnum.INVALID_ARGUMENT] error. On success, the number of bytes read into the buffer is returned. It is not an error if this is not the same as the requested size, as it @@ -8446,24 +8496,24 @@ can happen e.g. near the end of a file. Zero is returned on end of file If @count is -1 then the attempted read size is equal to the number of bytes that are required to fill the buffer. -If @cancellable is not %NULL, then the operation can be cancelled by +If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the +was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. +If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. -On error -1 is returned and @error is set accordingly. +On error `-1` is returned and @error is set accordingly. For the asynchronous, non-blocking, version of this function, see -g_buffered_input_stream_fill_async(). +[method@Gio.BufferedInputStream.fill_async]. the number of bytes read into @stream's buffer, up to @count, - or -1 on error. + or `-1` on error. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8471,7 +8521,7 @@ g_buffered_input_stream_fill_async(). - optional #GCancellable object, %NULL to ignore + optional [class@Gio.Cancellable] object, `NULL` to ignore @@ -8479,16 +8529,16 @@ g_buffered_input_stream_fill_async(). Reads data into @stream's buffer asynchronously, up to @count size. @io_priority can be used to prioritize reads. For the synchronous -version of this function, see g_buffered_input_stream_fill(). +version of this function, see [method@Gio.BufferedInputStream.fill]. -If @count is -1 then the attempted read size is equal to the number +If @count is `-1` then the attempted read size is equal to the number of bytes that are required to fill the buffer. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8500,11 +8550,11 @@ of bytes that are required to fill the buffer. - optional #GCancellable object + optional [class@Gio.Cancellable] object - a #GAsyncReadyCallback + a [callback@Gio.AsyncReadyCallback] @@ -8521,11 +8571,11 @@ of bytes that are required to fill the buffer. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] - a #GAsyncResult + a [iface@Gio.AsyncResult] @@ -8538,7 +8588,7 @@ of bytes that are required to fill the buffer. - #GBufferedInputStream + [class@Gio.BufferedInputStream] @@ -8551,7 +8601,7 @@ of bytes that are required to fill the buffer. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8560,12 +8610,12 @@ of bytes that are required to fill the buffer. Peeks in the buffer, copying data of size @count into @buffer, offset @offset bytes. - a #gsize of the number of bytes peeked, or -1 on error. + a #gsize of the number of bytes peeked, or `-1` on error. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8598,7 +8648,7 @@ the stream or filling the buffer. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8612,26 +8662,26 @@ the stream or filling the buffer. during this read. On success, the byte read from the stream is returned. On end of stream --1 is returned but it's not an exceptional error and @error is not set. +`-1` is returned but it's not an exceptional error and @error is not set. -If @cancellable is not %NULL, then the operation can be cancelled by +If @cancellable is not `NULL`, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation -was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. If an -operation was partially finished when the operation was cancelled the +was cancelled, the error [error@Gio.IOErrorEnum.CANCELLED] will be returned. +If an operation was partially finished when the operation was cancelled the partial result will be returned, without an error. -On error -1 is returned and @error is set accordingly. +On error `-1` is returned and @error is set accordingly. - the byte read from the @stream, or -1 on end of stream or error. + the byte read from the @stream, or `-1` on end of stream or error. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] - optional #GCancellable object, %NULL to ignore + optional [class@Gio.Cancellable] object, `NULL` to ignore @@ -8645,7 +8695,7 @@ smaller than its current contents. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8673,12 +8723,12 @@ smaller than its current contents. the number of bytes read into @stream's buffer, up to @count, - or -1 on error. + or `-1` on error. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8686,7 +8736,7 @@ smaller than its current contents. - optional #GCancellable object, %NULL to ignore + optional [class@Gio.Cancellable] object, `NULL` to ignore @@ -8699,7 +8749,7 @@ smaller than its current contents. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] @@ -8711,11 +8761,11 @@ smaller than its current contents. - optional #GCancellable object + optional [class@Gio.Cancellable] object - a #GAsyncReadyCallback + a [callback@Gio.AsyncReadyCallback] @@ -8733,11 +8783,11 @@ smaller than its current contents. - a #GBufferedInputStream + a [class@Gio.BufferedInputStream] - a #GAsyncResult + a [iface@Gio.AsyncResult] @@ -8798,12 +8848,12 @@ Note that the buffer's size cannot be reduced below the size of the data within Creates a new buffered output stream for a base stream. - a #GOutputStream for the given @base_stream. + a [class@Gio.OutputStream] for the given @base_stream. - a #GOutputStream. + a [class@Gio.OutputStream]. @@ -8811,12 +8861,12 @@ Note that the buffer's size cannot be reduced below the size of the data within Creates a new buffered output stream with a given buffer size. - a #GOutputStream with an internal buffer set to @size. + a [class@Gio.OutputStream] with an internal buffer set to @size. - a #GOutputStream. + a [class@Gio.OutputStream]. @@ -8828,13 +8878,13 @@ Note that the buffer's size cannot be reduced below the size of the data within Checks if the buffer automatically grows as data is added. - %TRUE if the @stream's buffer automatically grows, -%FALSE otherwise. + `TRUE` if the @stream's buffer automatically grows, +`FALSE` otherwise. - a #GBufferedOutputStream. + a [class@Gio.BufferedOutputStream]. @@ -8847,7 +8897,7 @@ Note that the buffer's size cannot be reduced below the size of the data within - a #GBufferedOutputStream. + a [class@Gio.BufferedOutputStream]. @@ -8862,7 +8912,7 @@ the data to the underlying stream. - a #GBufferedOutputStream. + a [class@Gio.BufferedOutputStream]. @@ -8878,7 +8928,7 @@ the data to the underlying stream. - a #GBufferedOutputStream. + a [class@Gio.BufferedOutputStream]. @@ -9287,9 +9337,11 @@ the application returns to the main loop. signal. Also handles the race condition that may happen if the cancellable is cancelled right before connecting. -@callback is called at most once, either directly at the -time of the connect if @cancellable is already cancelled, -or when @cancellable is cancelled in some thread. +@callback is called exactly once each time @cancellable is cancelled, +either directly at the time of the connect if @cancellable is already +cancelled, or when @cancellable is cancelled in some thread. +In case the cancellable is reset via [method@Gio.Cancellable.reset] +then the callback can be called again if the @cancellable is cancelled. @data_destroy_func will be called when the handler is disconnected, or immediately if the cancellable is already @@ -12030,7 +12082,7 @@ If this constraint is violated, the export will fail and 0 will be returned (with @error set accordingly). You can unexport the action group using -g_dbus_connection_unexport_action_group() with the return value of +[method@Gio.DBusConnection.unexport_action_group] with the return value of this function. The thread default main context is taken at the time of this call. @@ -12047,7 +12099,7 @@ context. - a #GDBusConnection + the D-Bus connection @@ -12055,7 +12107,7 @@ context. - a #GActionGroup + an action group @@ -12898,21 +12950,21 @@ created with this flag or if the method has already been called. Reverses the effect of a previous call to -g_dbus_connection_export_action_group(). +[method@Gio.DBusConnection.export_action_group]. -It is an error to call this function with an ID that wasn't returned -from g_dbus_connection_export_action_group() or to call it with the -same ID more than once. +It is an error to call this function with an ID that wasn’t returned from +[method@Gio.DBusConnection.export_action_group] or to call it with the same +ID more than once. - a #GDBusConnection + the D-Bus connection - the ID from g_dbus_connection_export_action_group() + the ID from [method@Gio.DBusConnection.export_action_group] @@ -16159,7 +16211,7 @@ This method will take ownership of @invocation. See Parses @xml_data and returns a #GDBusNodeInfo representing the data. The introspection XML must contain exactly one top-level -<node> element. +`<node>` element. Note that this routine is using a [GMarkup][glib-Simple-XML-Subset-Parser.description]-based @@ -19876,6 +19928,12 @@ See [Extending GIO][extending-gio]. + + + + + + @@ -20056,6 +20114,12 @@ See [Extending GIO][extending-gio]. + + + + + + @@ -20230,6 +20294,12 @@ See [Extending GIO][extending-gio]. + + + + + + @@ -20404,6 +20474,12 @@ See [Extending GIO][extending-gio]. + + + + + + @@ -22608,33 +22684,33 @@ GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file or the `GioUnix-2.0` GIR namespace when using it. - Creates a new #GDesktopAppInfo based on a desktop file id. + Creates a new [class@Gio.DesktopAppInfo] based on a desktop file ID. -A desktop file id is the basename of the desktop file, including the -.desktop extension. GIO is looking for a desktop file with this name +A desktop file ID is the basename of the desktop file, including the +`.desktop` extension. GIO is looking for a desktop file with this name in the `applications` subdirectories of the XDG data directories (i.e. the directories specified in the `XDG_DATA_HOME` and `XDG_DATA_DIRS` environment variables). GIO also supports the prefix-to-subdirectory mapping that is described in the [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) -(i.e. a desktop id of kde-foo.desktop will match +(i.e. a desktop ID of `kde-foo.desktop` will match `/usr/share/applications/kde/foo.desktop`). - a new #GDesktopAppInfo, or %NULL if no desktop - file with that id exists. + a new [class@Gio.DesktopAppInfo], or `NULL` if no + desktop file with that ID exists. - the desktop file id + the desktop file ID - Creates a new #GDesktopAppInfo. + Creates a new [class@Gio.DesktopAppInfo]. - a new #GDesktopAppInfo or %NULL on error. + a new [class@Gio.DesktopAppInfo] or `NULL` on error. @@ -22646,14 +22722,14 @@ prefix-to-subdirectory mapping that is described in the - Creates a new #GDesktopAppInfo. + Creates a new [class@Gio.DesktopAppInfo]. - a new #GDesktopAppInfo or %NULL on error. + a new [class@Gio.DesktopAppInfo] or `NULL` on error. - an opened #GKeyFile + an opened [type@GLib.KeyFile] @@ -22662,10 +22738,10 @@ prefix-to-subdirectory mapping that is described in the Gets all applications that implement @interface. An application implements an interface if that interface is listed in -the Implements= line of the desktop file of the application. +the `Implements` line of the desktop file of the application. - a list of #GDesktopAppInfo -objects. + a list of + [class@Gio.DesktopAppInfo] objects. @@ -22688,15 +22764,15 @@ The algorithm for determining matches is undefined and may change at any time. None of the search results are subjected to the normal validation -checks performed by g_desktop_app_info_new() (for example, checking that +checks performed by [ctor@Gio.DesktopAppInfo.new] (for example, checking that the executable referenced by a result exists), and so it is possible for -g_desktop_app_info_new() to return %NULL when passed an app ID returned by -this function. It is expected that calling code will do this when -subsequently creating a #GDesktopAppInfo for each result. +[ctor@Gio.DesktopAppInfo.new] to return `NULL` when passed an app ID returned +by this function. It is expected that calling code will do this when +subsequently creating a [class@Gio.DesktopAppInfo] for each result. a - list of strvs. Free each item with g_strfreev() and free the outer - list with g_free(). + list of strvs. Free each item with [func@GLib.strfreev] and free the outer + list with [func@GLib.free]. @@ -22712,14 +22788,16 @@ subsequently creating a #GDesktopAppInfo for each result. Sets the name of the desktop that the application is running in. -This is used by g_app_info_should_show() and -g_desktop_app_info_get_show_in() to evaluate the -`OnlyShowIn` and `NotShowIn` -desktop entry fields. + +This is used by [method@Gio.AppInfo.should_show] and +[method@Gio.DesktopAppInfo.get_show_in] to evaluate the +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) +keys. Should be called only once; subsequent calls are ignored. do not use this API. Since 2.42 the value of the -`XDG_CURRENT_DESKTOP` environment variable will be used. + `XDG_CURRENT_DESKTOP` environment variable will be used. @@ -22731,10 +22809,11 @@ Should be called only once; subsequent calls are ignored. - Gets the user-visible display name of the "additional application -action" specified by @action_name. + Gets the user-visible display name of the +[‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) +specified by @action_name. -This corresponds to the "Name" key within the keyfile group for the +This corresponds to the `Name` key within the keyfile group for the action. the locale-specific action name @@ -22742,12 +22821,12 @@ action. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] the name of the action as from - g_desktop_app_info_list_actions() + [method@Gio.DesktopAppInfo.list_actions] @@ -22755,15 +22834,14 @@ action. Looks up a boolean value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. +The @key is looked up in the `Desktop Entry` group. - the boolean value, or %FALSE if the key - is not found + the boolean value, or `FALSE` if the key is not found - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22775,29 +22853,31 @@ The @key is looked up in the "Desktop Entry" group. Gets the categories from the desktop file. - The unparsed Categories key from the desktop file; - i.e. no attempt is made to split it by ';' or validate it. + The unparsed + [`Categories` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-categories) + from the desktop file; + i.e. no attempt is made to split it by `;` or validate it. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] When @info was created from a known filename, return it. In some -situations such as the #GDesktopAppInfo returned from -g_desktop_app_info_new_from_keyfile(), this function will return %NULL. +situations such as a [class@Gio.DesktopAppInfo] returned from +[ctor@Gio.DesktopAppInfo.new_from_keyfile], this function will return `NULL`. The full path to the file for @info, - or %NULL if not known. + or `NULL` if not known. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22805,26 +22885,28 @@ g_desktop_app_info_new_from_keyfile(), this function will return %NULL. Gets the generic name from the desktop file. - The value of the GenericName key + The value of the + [`GenericName` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-genericname) - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] - A desktop file is hidden if the Hidden key in it is -set to True. + A desktop file is hidden if the +[`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) +in it is set to `True`. - %TRUE if hidden, %FALSE otherwise. + `TRUE` if hidden, `FALSE` otherwise. - a #GDesktopAppInfo. + a [class@Gio.DesktopAppInfo]. @@ -22832,14 +22914,15 @@ set to True. Gets the keywords from the desktop file. - The value of the Keywords key + The value of the + [`Keywords` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-keywords) - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22848,15 +22931,15 @@ set to True. Looks up a localized string value in the keyfile backing @info translated to the current locale. -The @key is looked up in the "Desktop Entry" group. +The @key is looked up in the `Desktop Entry` group. - a newly allocated string, or %NULL if the key - is not found + a newly allocated string, or `NULL` if the key is not + found - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22866,16 +22949,17 @@ The @key is looked up in the "Desktop Entry" group. - Gets the value of the NoDisplay key, which helps determine if the -application info should be shown in menus. See -%G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show(). + Gets the value of the +[`NoDisplay` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) + which helps determine if the application info should be shown in menus. See +`G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and [method@Gio.AppInfo.should_show]. - The value of the NoDisplay key + The value of the `NoDisplay` key - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22883,24 +22967,25 @@ application info should be shown in menus. See Checks if the application info should be shown in menus that list available applications for a specific name of the desktop, based on the -`OnlyShowIn` and `NotShowIn` keys. +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) +keys. -@desktop_env should typically be given as %NULL, in which case the +@desktop_env should typically be given as `NULL`, in which case the `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want to override the default mechanism then you may specify @desktop_env, but this is not recommended. -Note that g_app_info_should_show() for @info will include this check (with -%NULL for @desktop_env) as well as additional checks. +Note that [method@Gio.AppInfo.should_show] for @info will include this check +(with `NULL` for @desktop_env) as well as additional checks. - %TRUE if the @info should be shown in @desktop_env according to the -`OnlyShowIn` and `NotShowIn` keys, %FALSE -otherwise. + `TRUE` if the @info should be shown in @desktop_env according to the +`OnlyShowIn` and `NotShowIn` keys, `FALSE` otherwise. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22910,17 +22995,17 @@ otherwise. - Retrieves the StartupWMClass field from @info. This represents the -WM_CLASS property of the main window of the application, if launched + Retrieves the `StartupWMClass` field from @info. This represents the +`WM_CLASS` property of the main window of the application, if launched through @info. - the startup WM class, or %NULL if none is set -in the desktop file. + the startup WM class, or `NULL` if none + is set in the desktop file. - a #GDesktopAppInfo that supports startup notify + a [class@Gio.DesktopAppInfo] that supports startup notify @@ -22928,15 +23013,15 @@ in the desktop file. Looks up a string value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. +The @key is looked up in the `Desktop Entry` group. - a newly allocated string, or %NULL if the key - is not found + a newly allocated string, or `NULL` if the key is not + found - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22948,18 +23033,18 @@ The @key is looked up in the "Desktop Entry" group. Looks up a string list value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. +The @key is looked up in the `Desktop Entry` group. - a %NULL-terminated string array or %NULL if the specified - key cannot be found. The array should be freed with g_strfreev(). + a `NULL`-terminated string array or `NULL` if the specified + key cannot be found. The array should be freed with [func@GLib.strfreev]. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22967,21 +23052,22 @@ The @key is looked up in the "Desktop Entry" group. - return location for the number of returned strings, or %NULL + return location for the number of returned + strings, or `NULL` - Returns whether @key exists in the "Desktop Entry" group + Returns whether @key exists in the `Desktop Entry` group of the keyfile backing @info. - %TRUE if the @key exists + `TRUE` if the @key exists - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -22994,60 +23080,62 @@ of the keyfile backing @info. Activates the named application action. You may only call this function on action names that were -returned from g_desktop_app_info_list_actions(). +returned from [method@Gio.DesktopAppInfo.list_actions]. Note that if the main entry of the desktop file indicates that the application supports startup notification, and @launch_context is -non-%NULL, then startup notification will be used when activating the +non-`NULL`, then startup notification will be used when activating the action (and as such, invocation of the action on the receiving side must signal the end of startup notification when it is completed). This is the expected behaviour of applications declaring additional -actions, as per the desktop file specification. +actions, as per the +[desktop file specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html). -As with g_app_info_launch() there is no way to detect failures that +As with [method@Gio.AppInfo.launch] there is no way to detect failures that occur while using this function. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] the name of the action as from - g_desktop_app_info_list_actions() + [method@Gio.DesktopAppInfo.list_actions] - a #GAppLaunchContext + a [class@Gio.AppLaunchContext] - This function performs the equivalent of g_app_info_launch_uris(), + This function performs the equivalent of [method@Gio.AppInfo.launch_uris], but is intended primarily for operating system components that launch applications. Ordinary applications should use -g_app_info_launch_uris(). +[method@Gio.AppInfo.launch_uris]. If the application is launched via GSpawn, then @spawn_flags, @user_setup -and @user_setup_data are used for the call to g_spawn_async(). +and @user_setup_data are used for the call to [func@GLib.spawn_async]. Additionally, @pid_callback (with @pid_callback_data) will be called to -inform about the PID of the created process. See g_spawn_async_with_pipes() -for information on certain parameter conditions that can enable an -optimized posix_spawn() codepath to be used. +inform about the PID of the created process. See +[func@GLib.spawn_async_with_pipes] for information on certain parameter +conditions that can enable an optimized [`posix_spawn()`](man:posix_spawn(3)) +code path to be used. -If application launching occurs via some other mechanism (eg: D-Bus +If application launching occurs via some other mechanism (for example, D-Bus activation) then @spawn_flags, @user_setup, @user_setup_data, @pid_callback and @pid_callback_data are ignored. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -23057,16 +23145,16 @@ activation) then @spawn_flags, @user_setup, @user_setup_data, - a #GAppLaunchContext + a [class@Gio.AppLaunchContext] - #GSpawnFlags, used for each process + [flags@GLib.SpawnFlags], used for each process - a #GSpawnChildSetupFunc, used once - for each process. + a [callback@GLib.SpawnChildSetupFunc], + used once for each process. @@ -23084,19 +23172,19 @@ activation) then @spawn_flags, @user_setup, @user_setup_data, - Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows + Equivalent to [method@Gio.DesktopAppInfo.launch_uris_as_manager] but allows you to pass in file descriptors for the stdin, stdout and stderr streams of the launched process. If application launching occurs via some non-spawn mechanism (e.g. D-Bus activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -23106,16 +23194,16 @@ activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - a #GAppLaunchContext + a [class@Gio.AppLaunchContext] - #GSpawnFlags, used for each process + [flags@GLib.SpawnFlags], used for each process - a #GSpawnChildSetupFunc, used once - for each process. + a + [callback@GLib.SpawnChildSetupFunc], used once for each process. @@ -23131,40 +23219,42 @@ activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - file descriptor to use for child's stdin, or -1 + file descriptor to use for child’s stdin, or `-1` - file descriptor to use for child's stdout, or -1 + file descriptor to use for child’s stdout, or `-1` - file descriptor to use for child's stderr, or -1 + file descriptor to use for child’s stderr, or `-1` - Returns the list of "additional application actions" supported on the -desktop file, as per the desktop file specification. + Returns the list of +[‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) +supported on the desktop file, as per the desktop file specification. As per the specification, this is the list of actions that are -explicitly listed in the "Actions" key of the [Desktop Entry] group. +explicitly listed in the `Actions` key of the `Desktop Entry` group. - a list of strings, always non-%NULL + a + list of strings, always non-`NULL` - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] - The origin filename of this #GDesktopAppInfo + The origin filename of this [class@Gio.DesktopAppInfo] @@ -23176,27 +23266,28 @@ explicitly listed in the "Actions" key of the [Desktop Entry] group. #GDesktopAppInfoLookup is an opaque data structure and can only be accessed using the following functions. - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. Gets the default application for launching applications -using this URI scheme for a particular #GDesktopAppInfoLookup +using this URI scheme for a particular [iface@Gio.DesktopAppInfoLookup] implementation. -The #GDesktopAppInfoLookup interface and this function is used -to implement g_app_info_get_default_for_uri_scheme() backends +The [iface@Gio.DesktopAppInfoLookup] interface and this function is used +to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends in a GIO module. There is no reason for applications to use it -directly. Applications should use g_app_info_get_default_for_uri_scheme(). - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. +directly. Applications should use +[func@Gio.AppInfo.get_default_for_uri_scheme]. + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. - a #GDesktopAppInfoLookup + a [iface@Gio.DesktopAppInfoLookup] @@ -23207,23 +23298,24 @@ directly. Applications should use g_app_info_get_default_for_uri_scheme(). Gets the default application for launching applications -using this URI scheme for a particular #GDesktopAppInfoLookup +using this URI scheme for a particular [iface@Gio.DesktopAppInfoLookup] implementation. -The #GDesktopAppInfoLookup interface and this function is used -to implement g_app_info_get_default_for_uri_scheme() backends +The [iface@Gio.DesktopAppInfoLookup] interface and this function is used +to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends in a GIO module. There is no reason for applications to use it -directly. Applications should use g_app_info_get_default_for_uri_scheme(). - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. +directly. Applications should use +[func@Gio.AppInfo.get_default_for_uri_scheme]. + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. - a #GDesktopAppInfoLookup + a [iface@Gio.DesktopAppInfoLookup] @@ -23244,13 +23336,13 @@ handlers with URI schemes. g_desktop_app_info_lookup_get_default_for_uri_scheme(). - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. - a #GDesktopAppInfoLookup + a [iface@Gio.DesktopAppInfoLookup] @@ -23286,7 +23378,7 @@ for each, providing the process ID. `GDrive` represents a piece of hardware connected to the machine. It’s generally only created for removable hardware or hardware with -removable media. +removable media. For example, an optical disc drive, or a USB flash drive. `GDrive` is a container class for [iface@Gio.Volume] objects that stem from the same piece of media. As such, `GDrive` abstracts a drive with @@ -25064,8 +25156,8 @@ been pressed. The start/stop methods will - unlock/lock the disk (for example using the ATA <quote>SECURITY - UNLOCK DEVICE</quote> command) + unlock/lock the disk (for example using the ATA `SECURITY UNLOCK + DEVICE` command) @@ -30255,6 +30347,49 @@ of @prefix. + + Utility function to check if a particular file exists. + +The fallback implementation of this API is using [method@Gio.File.query_info] +and therefore may do blocking I/O. To asynchronously query the existence +of a file, use [method@Gio.File.query_info_async]. + +Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) +and then execute something based on the outcome of that, because the +file might have been created or removed in between the operations. The +general approach to handling that is to not check, but just do the +operation and handle the errors as they come. + +As an example of race-free checking, take the case of reading a file, +and if it doesn't exist, creating it. There are two racy versions: read +it, and on error create it; and: check if it exists, if not create it. +These can both result in two processes creating the file (with perhaps +a partially written file as the result). The correct approach is to +always try to create the file with g_file_create() which will either +atomically create the file or fail with a %G_IO_ERROR_EXISTS error. + +However, in many cases an existence check is useful in a user interface, +for instance to make a menu item sensitive/insensitive, so that you don't +have to fool users that something is possible and then just show an error +dialog. If you do this, you should make sure to also handle the errors +that can happen due to races when you execute the operation. + + %TRUE if the file exists (and can be detected without error), + %FALSE otherwise (or if cancelled). + + + + + input #GFile + + + + optional #GCancellable object, + %NULL to ignore + + + + Similar to g_file_query_info(), but obtains information about the filesystem the @file is on, rather than the file itself. @@ -31276,10 +31411,13 @@ with g_file_stop_mountable(). Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. -Not all file systems support trashing, so this call can return the +Trashing is disabled for system mounts by default (see +g_unix_mount_is_system_internal()), so this call can return the %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix -mount option can be used to disable g_file_trash() support for certain +mount option can be used to disable g_file_trash() support for particular mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. +Since 2.82, the `x-gvfs-trash` unix mount option can be used to enable +g_file_trash() support for particular system mounts. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -34074,8 +34212,11 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. - Utility function to check if a particular file exists. This is -implemented using g_file_query_info() and as such does blocking I/O. + Utility function to check if a particular file exists. + +The fallback implementation of this API is using [method@Gio.File.query_info] +and therefore may do blocking I/O. To asynchronously query the existence +of a file, use [method@Gio.File.query_info_async]. Note that in many cases it is [racy to first check for file existence](https://en.wikipedia.org/wiki/Time_of_check_to_time_of_use) and then execute something based on the outcome of that, because the @@ -35590,10 +35731,13 @@ If this returns %FALSE, you cannot perform asynchronous operations on Sends @file to the "Trashcan", if possible. This is similar to deleting it, but the user can recover it before emptying the trashcan. -Not all file systems support trashing, so this call can return the +Trashing is disabled for system mounts by default (see +g_unix_mount_is_system_internal()), so this call can return the %G_IO_ERROR_NOT_SUPPORTED error. Since GLib 2.66, the `x-gvfs-notrash` unix -mount option can be used to disable g_file_trash() support for certain +mount option can be used to disable g_file_trash() support for particular mounts, the %G_IO_ERROR_NOT_SUPPORTED error will be returned in that case. +Since 2.82, the `x-gvfs-trash` unix mount option can be used to enable +g_file_trash() support for particular system mounts. If @cancellable is not %NULL, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation @@ -40291,6 +40435,27 @@ otherwise. + + Queries whether a file exists. Since 2.84 + + + %TRUE if the file exists (and can be detected without error), + %FALSE otherwise (or if cancelled). + + + + + input #GFile + + + + optional #GCancellable object, + %NULL to ignore + + + + + Stores information about a file system object referenced by a [iface@Gio.File]. @@ -43280,12 +43445,12 @@ and byte order flipping. Gets the base stream for the filter stream. - a #GOutputStream. + a [class@Gio.OutputStream]. - a #GFilterOutputStream. + a [class@Gio.FilterOutputStream]. @@ -43294,12 +43459,12 @@ and byte order flipping. Returns whether the base stream will be closed when @stream is closed. - %TRUE if the base stream will be closed. + `TRUE` if the base stream will be closed. - a #GFilterOutputStream. + a [class@Gio.FilterOutputStream]. @@ -43311,11 +43476,11 @@ closed. - a #GFilterOutputStream. + a [class@Gio.FilterOutputStream]. - %TRUE to close the base stream. + `TRUE` to close the base stream. @@ -47627,7 +47792,7 @@ override one you must override all. - a buffer to read data into (which should be at least count bytes long). + a buffer to read data into (which should be at least count bytes long). @@ -47963,7 +48128,7 @@ On error -1 is returned and @error is set accordingly. - a buffer to read data into (which should be at least count bytes long). + a buffer to read data into (which should be at least count bytes long). @@ -48009,7 +48174,7 @@ write your own loop around g_input_stream_read(). - a buffer to read data into (which should be at least count bytes long). + a buffer to read data into (which should be at least count bytes long). @@ -48032,9 +48197,9 @@ write your own loop around g_input_stream_read(). Request an asynchronous read of @count bytes from the stream into the buffer starting at @buffer. -This is the asynchronous equivalent of g_input_stream_read_all(). +This is the asynchronous equivalent of [method@InputStream.read_all]. -Call g_input_stream_read_all_finish() to collect the result. +Call [method@InputStream.read_all_finish] to collect the result. Any outstanding I/O request with higher priority (lower numerical value) will be executed before an outstanding request with lower @@ -48049,7 +48214,7 @@ priority. Default priority is %G_PRIORITY_DEFAULT. - a buffer to read data into (which should be at least count bytes long) + a buffer to read data into (which should be at least count bytes long) @@ -48079,7 +48244,7 @@ priority. Default priority is %G_PRIORITY_DEFAULT. Finishes an asynchronous stream read operation started with -g_input_stream_read_all_async(). +[method@InputStream.read_all_async]. As a special exception to the normal conventions for functions that use #GError, if this function returns %FALSE (and sets @error) then @@ -48140,7 +48305,7 @@ override one you must override all. - a buffer to read data into (which should be at least count bytes long). + a buffer to read data into (which should be at least count bytes long). @@ -48501,7 +48666,7 @@ However, if you override one, you must override all. - a buffer to read data into (which should be at least count bytes long). + a buffer to read data into (which should be at least count bytes long). @@ -51578,6 +51743,8 @@ As an example, consider the visible portions of this menu: ![](menu-example.png) +While this kind of deeply nested menu is no longer considered good UI +practice, it serves as a good example of the concepts in `GMenuModel`. There are 8 ‘menus’ visible in the screenshot: one menubar, two submenus and 5 sections: @@ -52280,14 +52447,15 @@ reported. The signal is emitted after the modification. - The `GMount` interface represents user-visible mounts. Note, when -[porting from GnomeVFS](migrating-gnome-vfs.html), `GMount` is the moral -equivalent of `GnomeVFSVolume`. + The `GMount` interface represents a user-visible mount, such as a mounted +file system. `GMount` is a ‘mounted’ filesystem that you can access. Mounted is in quotes because it’s not the same as a UNIX mount, it might be a GVFS -mount, but you can still access the files on it if you use GIO. Might or -might not be related to a volume object. +mount, but you can still access the files on it if you use GIO. + +A `GMount` might be associated with a [iface@Gio.Volume] (such as a USB flash +drive) which hosts it. Unmounting a `GMount` instance is an asynchronous operation. For more information about asynchronous operations, see [iface@Gio.AsyncResult] @@ -52300,7 +52468,10 @@ callback should then call [method@Gio.Mount.unmount_with_operation_finish] with the `GMount` and the [iface@Gio.AsyncResult] data to see if the operation was completed successfully. If an `error` is present when [method@Gio.Mount.unmount_with_operation_finish] is called, then it will be -filled with any error information. +filled with any error information. + +Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), `GMount` is the +moral equivalent of `GnomeVFSVolume`. Checks if @mount can be ejected. @@ -60744,7 +60915,7 @@ resolver that returns %TRUE for this method.) Looks into the system proxy configuration to determine what proxy, if any, to use to connect to @uri. The returned proxy URIs are of the form `<protocol>://[user[:password]@]host[:port]` or -`direct://`, where <protocol> could be http, rtsp, socks +`direct://`, where `<protocol>` could be http, rtsp, socks or other proxying protocol. If you don't know what network protocol is being used on the @@ -60850,7 +61021,7 @@ resolver that returns %TRUE for this method.) Looks into the system proxy configuration to determine what proxy, if any, to use to connect to @uri. The returned proxy URIs are of the form `<protocol>://[user[:password]@]host[:port]` or -`direct://`, where <protocol> could be http, rtsp, socks +`direct://`, where `<protocol>` could be http, rtsp, socks or other proxying protocol. If you don't know what network protocol is being used on the @@ -63055,12 +63226,13 @@ before the `=`. The path after the slash should ideally be absolute, but this is not strictly required. It is possible to overlay the location of a single resource with an individual file. - Creates a GResource from a reference to the binary resource bundle. + Creates a [struct@Gio.Resource] from a reference to the binary resource bundle. + This will keep a reference to @data while the resource lives, so the data should not be modified or freed. If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). +to register it with [func@Gio.resources_register]. Note: @data must be backed by memory that is at least pointer aligned. Otherwise this function will internally create a copy of the memory since @@ -63068,26 +63240,28 @@ GLib 2.56, or in older versions fail and exit the process. If @data is empty or corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. - a new #GResource, or %NULL on error + a new [struct@Gio.Resource], or `NULL` on error - A #GBytes + A [struct@GLib.Bytes] Registers the resource with the process-global set of resources. + Once a resource is registered the files in it can be accessed -with the global resource lookup functions like g_resources_lookup_data(). +with the global resource lookup functions like +[func@Gio.resources_lookup_data]. - A #GResource + A [struct@Gio.Resource] @@ -63099,17 +63273,18 @@ with the global resource lookup functions like g_resources_lookup_data(). - A #GResource + A [struct@Gio.Resource] Returns all the names of children at the specified @path in the resource. -The return result is a %NULL terminated list of strings which should -be released with g_strfreev(). -If @path is invalid or does not exist in the #GResource, +The return result is a `NULL` terminated list of strings which should +be released with [func@GLib.strfreev]. + +If @path is invalid or does not exist in the [struct@Gio.Resource], %G_RESOURCE_ERROR_NOT_FOUND will be returned. @lookup_flags controls the behaviour of the lookup. @@ -63121,15 +63296,15 @@ If @path is invalid or does not exist in the #GResource, - A #GResource + A [struct@Gio.Resource] - A pathname inside the resource + A path name inside the resource - A #GResourceLookupFlags + A [flags@Gio.ResourceLookupFlags] @@ -63138,138 +63313,166 @@ If @path is invalid or does not exist in the #GResource, Looks for a file at the specified @path in the resource and if found returns information about it. -@lookup_flags controls the behaviour of the lookup. +@lookup_flags controls the behaviour of the lookup. + +The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was +not found in @resource. - %TRUE if the file was found. %FALSE if there were errors + `TRUE` if the file was found, `FALSE` if there were errors - A #GResource + A [struct@Gio.Resource] - A pathname inside the resource + A path name inside the resource - A #GResourceLookupFlags + A [flags@Gio.ResourceLookupFlags] a location to place the length of the contents of the file, - or %NULL if the length is not needed + or `NULL` if the length is not needed a location to place the flags about the file, - or %NULL if the length is not needed + or `NULL` if the length is not needed + + Returns whether the specified @path in the resource +has children. + + %TRUE if @path has children + + + + + A #GResource + + + + A pathname inside the resource + + + + Looks for a file at the specified @path in the resource and -returns a #GBytes that lets you directly access the data in +returns a [struct@GLib.Bytes] that lets you directly access the data in memory. The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte -is not included in the size of the GBytes. +is not included in the size of the [struct@GLib.Bytes]. For uncompressed resource files this is a pointer directly into -the resource bundle, which is typically in some readonly data section -in the program binary. For compressed files we allocate memory on -the heap and automatically uncompress the data. +the resource bundle, which is typically in some read-only data section +in the program binary. For compressed files, memory is allocated on +the heap and the data is automatically uncompressed. -@lookup_flags controls the behaviour of the lookup. +@lookup_flags controls the behaviour of the lookup. + +This can return error %G_RESOURCE_ERROR_NOT_FOUND if @path was not found in +@resource, or %G_RESOURCE_ERROR_INTERNAL if decompression of a compressed +resource failed. - #GBytes or %NULL on error. - Free the returned object with g_bytes_unref() + [struct@GLib.Bytes] or `NULL` on error - A #GResource + A [struct@Gio.Resource] - A pathname inside the resource + A path name inside the resource - A #GResourceLookupFlags + A [flags@Gio.ResourceLookupFlags] Looks for a file at the specified @path in the resource and -returns a #GInputStream that lets you read the data. +returns a [class@Gio.InputStream] that lets you read the data. -@lookup_flags controls the behaviour of the lookup. +@lookup_flags controls the behaviour of the lookup. + +The only error this can return is %G_RESOURCE_ERROR_NOT_FOUND, if @path was +not found in @resource. - #GInputStream or %NULL on error. - Free the returned object with g_object_unref() + [class@Gio.InputStream] or `NULL` on error - A #GResource + A [struct@Gio.Resource] - A pathname inside the resource + A path name inside the resource - A #GResourceLookupFlags + A [flags@Gio.ResourceLookupFlags] - Atomically increments the reference count of @resource by one. This -function is MT-safe and may be called from any thread. + Atomically increments the reference count of @resource by one. + +This function is threadsafe and may be called from any thread. - The passed in #GResource + The passed in [struct@Gio.Resource] - A #GResource + A [struct@Gio.Resource] - Atomically decrements the reference count of @resource by one. If the -reference count drops to 0, all memory allocated by the resource is -released. This function is MT-safe and may be called from any + Atomically decrements the reference count of @resource by one. + +If the reference count drops to 0, all memory allocated by the resource is +released. This function is threadsafe and may be called from any thread. - A #GResource + A [struct@Gio.Resource] - Loads a binary resource bundle and creates a #GResource representation of it, allowing -you to query it for data. + Loads a binary resource bundle and creates a [struct@Gio.Resource] +representation of it, allowing you to query it for data. If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). +to register it with [func@Gio.resources_register]. If @filename is empty or the data in it is corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or -there is an error in reading it, an error from g_mapped_file_new() will be -returned. +there is an error in reading it, an error from [ctor@GLib.MappedFile.new] +will be returned. - a new #GResource, or %NULL on error + a new [struct@Gio.Resource], or `NULL` on error @@ -63290,9 +63493,9 @@ from a #GResource routine. unknown error - Gets the #GResource Error Quark. + Gets the [struct@Gio.Resource] Error Quark. - a #GQuark + a [type@GLib.Quark] @@ -64191,6 +64394,70 @@ they can be specified as `<child>` elements in the parent schema, e.g.: ## Build system integration +### Meson + +GSettings is natively supported by Meson's [GNOME module](https://mesonbuild.com/Gnome-module.html). + +You can install the schemas as any other data file: + +``` +install_data( + 'org.foo.MyApp.gschema.xml', + install_dir: get_option('datadir') / 'glib-2.0/schemas', +) +``` + +You can use `gnome.post_install()` function to compile the schemas on +installation: + +``` +gnome = import('gnome') +gnome.post_install( + glib_compile_schemas: true, +) +``` + +If an enumerated type defined in a C header file is to be used in a GSettings +schema, it can either be defined manually using an `<enum>` element in the +schema XML, or it can be extracted automatically from the C header. This +approach is preferred, as it ensures the two representations are always +synchronised. To do so, you will need to use the `gnome.mkenums()` function +with the following templates: + +``` +schemas_enums = gnome.mkenums('org.foo.MyApp.enums.xml', + comments: '<!-- @comment@ -->', + fhead: '<schemalist>', + vhead: ' <@type@ id="org.foo.MyApp.@EnumName@">', + vprod: ' <value nick="@valuenick@" value="@valuenum@"/>', + vtail: ' </@type@>', + ftail: '</schemalist>', + sources: enum_sources, + install_header: true, + install_dir: get_option('datadir') / 'glib-2.0/schemas', +) +``` + +It is recommended to validate your schemas as part of the test suite for +your application: + +``` +test('validate-schema', + find_program('glib-compile-schemas'), + args: ['--strict', '--dry-run', meson.current_source_dir()], +) +``` + +If your application allows running uninstalled, you should also use the +`gnome.compile_schemas()` function to compile the schemas in the current +build directory: + +``` +gnome.compile_schemas() +``` + +### Autotools + GSettings comes with autotools integration to simplify compiling and installing schemas. To add GSettings support to an application, add the following to your `configure.ac`: @@ -64207,25 +64474,6 @@ EXTRA_DIST = $(gsettings_SCHEMAS) @GSETTINGS_RULES@ ``` -No changes are needed to the build system to mark a schema XML file for -translation. Assuming it sets the `gettext-domain` attribute, a schema may -be marked for translation by adding it to `POTFILES.in`, assuming gettext -0.19 is in use (the preferred method for translation): -``` -data/org.foo.MyApp.gschema.xml -``` - -Alternatively, if intltool 0.50.1 is in use: -``` -[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml -``` - -GSettings will use gettext to look up translations for the `<summary>` and -`<description>` elements, and also any `<default>` elements which have a -`l10n` attribute set. Translations must not be included in the `.gschema.xml` -file by the build system, for example by using intltool XML rules with a -`.gschema.xml.in` template. - If an enumerated type defined in a C header file is to be used in a GSettings schema, it can either be defined manually using an `<enum>` element in the schema XML, or it can be extracted automatically from the C header. This @@ -64241,7 +64489,29 @@ which are specified in `gsettings_ENUM_FILES`. This will generate a `org.foo.MyApp.enums.xml` file containing the extracted enums, which will be automatically included in the schema compilation, install and uninstall rules. It should not be committed to version control or included in -`EXTRA_DIST`. +`EXTRA_DIST`. + +## Localization + +No changes are needed to the build system to mark a schema XML file for +translation. Assuming it sets the `gettext-domain` attribute, a schema may +be marked for translation by adding it to `POTFILES.in`, assuming gettext +0.19 or newer is in use (the preferred method for translation): +``` +data/org.foo.MyApp.gschema.xml +``` + +Alternatively, if intltool 0.50.1 is in use: +``` +[type: gettext/gsettings]data/org.foo.MyApp.gschema.xml +``` + +GSettings will use gettext to look up translations for the `<summary>` and +`<description>` elements, and also any `<default>` elements which have a +`l10n` attribute set. + +Translations **must not** be included in the `.gschema.xml` file by the build +system, for example by using a rule to generate the XML file from a template. Creates a new #GSettings object with the schema specified by @schema_id. @@ -69165,7 +69435,7 @@ g_socket_set_multicast_ttl() for more details. getsockopt(). (If you need to fetch a non-integer-valued option, you will need to call getsockopt() directly.) -The [<gio/gnetworking.h>][gio-gnetworking.h] +The [`<gio/gnetworking.h>`](networking.html) header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional @@ -70331,7 +70601,7 @@ the local network. setsockopt(). (If you need to set a non-integer-valued option, you will need to call setsockopt() directly.) -The [<gio/gnetworking.h>][gio-gnetworking.h] +The [`<gio/gnetworking.h>`](networking.html) header pulls in system headers that will define most of the standard/portable socket options. For unusual socket protocols or platform-dependent options, you may need to include additional @@ -73877,7 +74147,7 @@ RFC 2782. - #GStaticResource is an opaque data structure and can only be accessed + `GStaticResource` is an opaque data structure and can only be accessed using the following functions. @@ -73895,51 +74165,53 @@ using the following functions. - Finalized a GResource initialized by g_static_resource_init(). + Finalizes a [struct@Gio.Resource] initialized by +[method@Gio.StaticResource.init]. This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] +[`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. - pointer to a static #GStaticResource + pointer to a static [struct@Gio.StaticResource] - Gets the GResource that was registered by a call to g_static_resource_init(). + Gets the [struct@Gio.Resource] that was registered by a call to +[method@Gio.StaticResource.init]. This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] +[`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. - a #GResource + a [struct@Gio.Resource] - pointer to a static #GStaticResource + pointer to a static [struct@Gio.StaticResource] - Initializes a GResource from static data using a -GStaticResource. + Initializes a [struct@Gio.Resource] from static data using a +[struct@Gio.StaticResource]. This is normally used by code generated by -[glib-compile-resources][glib-compile-resources] +[`glib-compile-resources`](glib-compile-resources.html) and is not typically used by other code. - pointer to a static #GStaticResource + pointer to a static [struct@Gio.StaticResource] @@ -83713,7 +83985,7 @@ when the stream is closed. - Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>). + Defines a Unix mount entry (e.g. `/media/cdrom`). This corresponds roughly to a mtab entry. @@ -83783,7 +84055,7 @@ the monitor. - Defines a Unix mount point (e.g. <filename>/dev</filename>). + Defines a Unix mount point (e.g. `/dev`). This corresponds roughly to a fstab entry. Compares two unix mount points. @@ -85145,8 +85417,11 @@ created for @uri, or %NULL to continue with the default implementation. The `GVolume` interface represents user-visible objects that can be -mounted. Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), -`GVolume` is the moral equivalent of `GnomeVFSDrive`. +mounted. For example, a file system partition on a USB flash drive, or an +optical disc inserted into a disc drive. + +If a `GVolume` is currently mounted, the corresponding [iface@Gio.Mount] can +be retrieved using [method@Gio.Volume.get_mount]. Mounting a `GVolume` instance is an asynchronous operation. For more information about asynchronous operations, see [iface@Gio.AsyncResult] and @@ -85168,6 +85443,9 @@ successfully. If a [type@GLib.Error] is present when [method@Gio.Volume.mount_finish] is called, then it will be filled with any error information. +Note, when [porting from GnomeVFS](migrating-gnome-vfs.html), +`GVolume` is the moral equivalent of `GnomeVFSDrive`. + ## Volume Identifiers It is sometimes necessary to directly access the underlying @@ -87564,28 +87842,30 @@ this function. - Creates a new #GAppInfo from the given information. + Creates a new [iface@Gio.AppInfo] from the given information. -Note that for @commandline, the quoting rules of the Exec key of the +Note that for @commandline, the quoting rules of the `Exec` key of the [freedesktop.org Desktop Entry Specification](http://freedesktop.org/Standards/desktop-entry-spec) are applied. For example, if the @commandline contains percent-encoded URIs, the percent-character must be doubled in order to prevent it from -being swallowed by Exec key unquoting. See the specification for exact quoting rules. +being swallowed by `Exec` key unquoting. See +[the specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s07.html) +for exact quoting rules. - new #GAppInfo for given command. + new [iface@Gio.AppInfo] for given command. - the commandline to use + the command line to use - the application name, or %NULL to use @commandline + the application name, or `NULL` to use @commandline - flags that can specify details of the created #GAppInfo + flags that can specify details of the created [iface@Gio.AppInfo] @@ -87595,76 +87875,84 @@ being swallowed by Exec key unquoting. See the specification for exact quoting r on this system. For desktop files, this includes applications that have -`NoDisplay=true` set or are excluded from display by means -of `OnlyShowIn` or `NotShowIn`. See g_app_info_should_show(). -The returned list does not include applications which have -the `Hidden` key set. +[`NoDisplay=true`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) +set or are excluded from display by means of +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +or [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin). +See [method@Gio.AppInfo.should_show]. + +The returned list does not include applications which have the +[`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) +set. - a newly allocated #GList of references to #GAppInfos. + a newly allocated + list of references to [iface@Gio.AppInfo]s. - Gets a list of all #GAppInfos for a given content type, -including the recommended and fallback #GAppInfos. See -g_app_info_get_recommended_for_type() and -g_app_info_get_fallback_for_type(). + Gets a list of all [iface@Gio.AppInfo]s for a given content type, +including the recommended and fallback [iface@Gio.AppInfo]s. See +[func@Gio.AppInfo.get_recommended_for_type] and +[func@Gio.AppInfo.get_fallback_for_type]. - #GList of #GAppInfos - for given @content_type or %NULL on error. + list of + [iface@Gio.AppInfo]s for given @content_type. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - Gets the default #GAppInfo for a given content type. + Gets the default [iface@Gio.AppInfo] for a given content type. - #GAppInfo for given @content_type or - %NULL on error. + [iface@Gio.AppInfo] for given + @content_type or `NULL` on error. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - if %TRUE, the #GAppInfo is expected to - support URIs + if `TRUE`, the [iface@Gio.AppInfo] is expected to + support URIs - Asynchronously gets the default #GAppInfo for a given content type. + Asynchronously gets the default [iface@Gio.AppInfo] for a given content +type. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - if %TRUE, the #GAppInfo is expected to - support URIs + if `TRUE`, the [iface@Gio.AppInfo] is expected to + support URIs - optional #GCancellable object, %NULL to ignore + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -87674,30 +87962,31 @@ g_app_info_get_fallback_for_type(). - Finishes a default #GAppInfo lookup started by -g_app_info_get_default_for_type_async(). + Finishes a default [iface@Gio.AppInfo] lookup started by +[func@Gio.AppInfo.get_default_for_type_async]. -If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. +If no #[iface@Gio.AppInfo] is found, then @error will be set to +[error@Gio.IOErrorEnum.NOT_FOUND]. - #GAppInfo for given @content_type or - %NULL on error. + [iface@Gio.AppInfo] for given @content_type or + `NULL` on error. - a #GAsyncResult + the async result - Gets the default application for handling URIs with -the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". + Gets the default application for handling URIs with the given URI scheme. + +A URI scheme is the initial part of the URI, up to but not including the `:`. +For example, `http`, `ftp` or `sip`. - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. @@ -87710,8 +87999,8 @@ of the URI, up to but not including the ':', e.g. "http", Asynchronously gets the default application for handling URIs with the given URI scheme. A URI scheme is the initial part -of the URI, up to but not including the ':', e.g. "http", -"ftp" or "sip". +of the URI, up to but not including the `:`, e.g. `http`, +`ftp` or `sip`. @@ -87721,11 +88010,12 @@ of the URI, up to but not including the ':', e.g. "http", - optional #GCancellable object, %NULL to ignore + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -87735,72 +88025,73 @@ of the URI, up to but not including the ':', e.g. "http", - Finishes a default #GAppInfo lookup started by -g_app_info_get_default_for_uri_scheme_async(). + Finishes a default [iface@Gio.AppInfo] lookup started by +[func@Gio.AppInfo.get_default_for_uri_scheme_async]. -If no #GAppInfo is found, then @error will be set to %G_IO_ERROR_NOT_FOUND. +If no [iface@Gio.AppInfo] is found, then @error will be set to +[error@Gio.IOErrorEnum.NOT_FOUND]. - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given @uri_scheme or + `NULL` on error. - a #GAsyncResult + the async result - Gets a list of fallback #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type -by MIME type subclassing and not directly. + Gets a list of fallback [iface@Gio.AppInfo]s for a given content type, i.e. +those applications which claim to support the given content type by MIME +type subclassing and not directly. - #GList of #GAppInfos - for given @content_type or %NULL on error. + list of [iface@Gio.AppInfo]s + for given @content_type or `NULL` on error. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - Gets a list of recommended #GAppInfos for a given content type, i.e. -those applications which claim to support the given content type exactly, -and not by MIME type subclassing. + Gets a list of recommended [iface@Gio.AppInfo]s for a given content type, +i.e. those applications which claim to support the given content type +exactly, and not by MIME type subclassing. + Note that the first application of the list is the last used one, i.e. -the last one for which g_app_info_set_as_last_used_for_type() has been -called. +the last one for which [method@Gio.AppInfo.set_as_last_used_for_type] has +been called. - #GList of #GAppInfos - for given @content_type or %NULL on error. + list of + [iface@Gio.AppInfo]s for given @content_type or `NULL` on error. - the content type to find a #GAppInfo for + the content type to find a [iface@Gio.AppInfo] for - Utility function that launches the default application -registered to handle the specified uri. Synchronous I/O -is done on the uri to detect the type of the file if -required. + Utility function that launches the default application registered to handle +the specified uri. Synchronous I/O is done on the uri to detect the type of +the file if required. -The D-Bus–activated applications don't have to be started if your application +The D-Bus–activated applications don’t have to be started if your application terminates too soon after this function. To prevent this, use -g_app_info_launch_default_for_uri_async() instead. +[func@Gio.AppInfo.launch_default_for_uri_async] instead. - %TRUE on success, %FALSE on error. + `TRUE` on success, `FALSE` on error. @@ -87809,18 +88100,17 @@ g_app_info_launch_default_for_uri_async() instead. - an optional #GAppLaunchContext + optional launch context - Async version of g_app_info_launch_default_for_uri(). + Async version of [func@Gio.AppInfo.launch_default_for_uri]. -This version is useful if you are interested in receiving -error information in the case where the application is -sandboxed and the portal may present an application chooser -dialog to the user. +This version is useful if you are interested in receiving error information +in the case where the application is sandboxed and the portal may present an +application chooser dialog to the user. This is also useful if you want to be sure that the D-Bus–activated applications are really started before termination and if you are interested @@ -87834,15 +88124,16 @@ in receiving error information from their activation. - an optional #GAppLaunchContext + optional launch context - a #GCancellable + a [class@Gio.Cancellable] - a #GAsyncReadyCallback to call when the request is done + a [type@Gio.AsyncReadyCallback] to call + when the request is done @@ -87854,22 +88145,22 @@ in receiving error information from their activation. Finishes an asynchronous launch-default-for-uri operation. - %TRUE if the launch was successful, %FALSE if @error is set + `TRUE` if the launch was successful, `FALSE` if @error is set - a #GAsyncResult + the async result Removes all changes to the type associations done by -g_app_info_set_as_default_for_type(), -g_app_info_set_as_default_for_extension(), -g_app_info_add_supports_type() or -g_app_info_remove_supports_type(). +[method@Gio.AppInfo.set_as_default_for_type], +[method@Gio.AppInfo.set_as_default_for_extension], +[method@Gio.AppInfo.add_supports_type] or +[method@Gio.AppInfo.remove_supports_type]. @@ -90297,25 +90588,25 @@ the specified protocol. - Gets the #GResource Error Quark. + Gets the [struct@Gio.Resource] Error Quark. - a #GQuark + a [type@GLib.Quark] - Loads a binary resource bundle and creates a #GResource representation of it, allowing -you to query it for data. + Loads a binary resource bundle and creates a [struct@Gio.Resource] +representation of it, allowing you to query it for data. If you want to use this resource in the global resource namespace you need -to register it with g_resources_register(). +to register it with [func@Gio.resources_register]. If @filename is empty or the data in it is corrupt, %G_RESOURCE_ERROR_INTERNAL will be returned. If @filename doesn’t exist, or -there is an error in reading it, an error from g_mapped_file_new() will be -returned. +there is an error in reading it, an error from [ctor@GLib.MappedFile.new] +will be returned. - a new #GResource, or %NULL on error + a new [struct@Gio.Resource], or `NULL` on error @@ -90328,8 +90619,9 @@ returned. Returns all the names of children at the specified @path in the set of globally registered resources. -The return result is a %NULL terminated list of strings which should -be released with g_strfreev(). + +The return result is a `NULL` terminated list of strings which should +be released with [func@GLib.strfreev]. @lookup_flags controls the behaviour of the lookup. @@ -90340,11 +90632,11 @@ be released with g_strfreev(). - A pathname inside the resource + A path name inside the resource - A #GResourceLookupFlags + A [flags@Gio.ResourceLookupFlags] @@ -90355,93 +90647,107 @@ globally registered resources and if found returns information about it. @lookup_flags controls the behaviour of the lookup. - %TRUE if the file was found. %FALSE if there were errors + `TRUE` if the file was found, `FALSE` if there were errors - A pathname inside the resource + A path name inside the resource - A #GResourceLookupFlags + A [flags@Gio.ResourceLookupFlags] a location to place the length of the contents of the file, - or %NULL if the length is not needed + or `NULL` if the length is not needed - a location to place the #GResourceFlags about the file, - or %NULL if the flags are not needed + a location to place the [flags@Gio.ResourceFlags] about the file, + or `NULL` if the flags are not needed + + Returns whether the specified @path in the set of +globally registered resources has children. + + %TRUE if @patch has children + + + + + A pathname + + + + Looks for a file at the specified @path in the set of -globally registered resources and returns a #GBytes that +globally registered resources and returns a [struct@GLib.Bytes] that lets you directly access the data in memory. The data is always followed by a zero byte, so you can safely use the data as a C string. However, that byte -is not included in the size of the GBytes. +is not included in the size of the [struct@GLib.Bytes]. For uncompressed resource files this is a pointer directly into -the resource bundle, which is typically in some readonly data section +the resource bundle, which is typically in some read-only data section in the program binary. For compressed files we allocate memory on the heap and automatically uncompress the data. @lookup_flags controls the behaviour of the lookup. - #GBytes or %NULL on error. - Free the returned object with g_bytes_unref() + [struct@GLib.Bytes] or `NULL` on error - A pathname inside the resource + A path name inside the resource - A #GResourceLookupFlags + A [flags@Gio.ResourceLookupFlags] Looks for a file at the specified @path in the set of -globally registered resources and returns a #GInputStream +globally registered resources and returns a [class@Gio.InputStream] that lets you read the data. @lookup_flags controls the behaviour of the lookup. - #GInputStream or %NULL on error. - Free the returned object with g_object_unref() + [class@Gio.InputStream] or `NULL` on error - A pathname inside the resource + A path name inside the resource - A #GResourceLookupFlags + A [flags@Gio.ResourceLookupFlags] Registers the resource with the process-global set of resources. + Once a resource is registered the files in it can be accessed -with the global resource lookup functions like g_resources_lookup_data(). +with the global resource lookup functions like +[func@Gio.resources_lookup_data]. - A #GResource + A [struct@Gio.Resource] @@ -90453,7 +90759,7 @@ with the global resource lookup functions like g_resources_lookup_data(). - A #GResource + A [struct@Gio.Resource] @@ -91049,6 +91355,41 @@ g_unix_mount_points_changed_since(). + + Gets an array of [struct@Gio.UnixMountPoint]s containing the Unix mount +points listed in @table_path. + +This is a generalized version of g_unix_mount_points_get(), mainly intended +for internal testing use. Note that g_unix_mount_points_get() may parse +multiple hierarchical table files, so this function is not a direct superset +of its functionality. + +If there is an error reading or parsing the file, `NULL` will be returned +and both out parameters will be set to `0`. + + mount + points, or `NULL` if there was an error loading them + + + + + + + path to the mount points table file (for example `/etc/fstab`) + + + + return location for the + modification time of @table_path + + + + return location for the + number of mount points returned + + + + Checks if the unix mounts have changed since a given unix time. @@ -91081,5 +91422,40 @@ with g_unix_mounts_changed_since(). + + Gets an array of [struct@Gio.UnixMountEntry]s containing the Unix mounts +listed in @table_path. + +This is a generalized version of g_unix_mounts_get(), mainly intended for +internal testing use. Note that g_unix_mounts_get() may parse multiple +hierarchical table files, so this function is not a direct superset of its +functionality. + +If there is an error reading or parsing the file, `NULL` will be returned +and both out parameters will be set to `0`. + + mount + entries, or `NULL` if there was an error loading them + + + + + + + path to the mounts table file (for example `/proc/self/mountinfo`) + + + + return location for the + modification time of @table_path + + + + return location for the + number of mount entries returned + + + + diff --git a/GioUnix-2.0.gir b/GioUnix-2.0.gir index 4dc128bb..f77c615f 100644 --- a/GioUnix-2.0.gir +++ b/GioUnix-2.0.gir @@ -8,13 +8,13 @@ and/or use gtk-doc annotations. --> - - + + + + + + - - - - @@ -62,33 +62,33 @@ GIO interfaces, thus you have to use the `gio-unix-2.0.pc` pkg-config file or the `GioUnix-2.0` GIR namespace when using it. - Creates a new #GDesktopAppInfo based on a desktop file id. + Creates a new [class@Gio.DesktopAppInfo] based on a desktop file ID. -A desktop file id is the basename of the desktop file, including the -.desktop extension. GIO is looking for a desktop file with this name +A desktop file ID is the basename of the desktop file, including the +`.desktop` extension. GIO is looking for a desktop file with this name in the `applications` subdirectories of the XDG data directories (i.e. the directories specified in the `XDG_DATA_HOME` and `XDG_DATA_DIRS` environment variables). GIO also supports the prefix-to-subdirectory mapping that is described in the [Menu Spec](http://standards.freedesktop.org/menu-spec/latest/) -(i.e. a desktop id of kde-foo.desktop will match +(i.e. a desktop ID of `kde-foo.desktop` will match `/usr/share/applications/kde/foo.desktop`). - a new #GDesktopAppInfo, or %NULL if no desktop - file with that id exists. + a new [class@Gio.DesktopAppInfo], or `NULL` if no + desktop file with that ID exists. - the desktop file id + the desktop file ID - Creates a new #GDesktopAppInfo. + Creates a new [class@Gio.DesktopAppInfo]. - a new #GDesktopAppInfo or %NULL on error. + a new [class@Gio.DesktopAppInfo] or `NULL` on error. @@ -100,23 +100,24 @@ prefix-to-subdirectory mapping that is described in the - Creates a new #GDesktopAppInfo. + Creates a new [class@Gio.DesktopAppInfo]. - a new #GDesktopAppInfo or %NULL on error. + a new [class@Gio.DesktopAppInfo] or `NULL` on error. - an opened #GKeyFile + an opened [type@GLib.KeyFile] - Gets the user-visible display name of the "additional application -action" specified by @action_name. + Gets the user-visible display name of the +[‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) +specified by @action_name. -This corresponds to the "Name" key within the keyfile group for the +This corresponds to the `Name` key within the keyfile group for the action. the locale-specific action name @@ -124,12 +125,12 @@ action. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] the name of the action as from - g_desktop_app_info_list_actions() + [method@Gio.DesktopAppInfo.list_actions] @@ -137,15 +138,14 @@ action. Looks up a boolean value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. +The @key is looked up in the `Desktop Entry` group. - the boolean value, or %FALSE if the key - is not found + the boolean value, or `FALSE` if the key is not found - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -157,29 +157,31 @@ The @key is looked up in the "Desktop Entry" group. Gets the categories from the desktop file. - The unparsed Categories key from the desktop file; - i.e. no attempt is made to split it by ';' or validate it. + The unparsed + [`Categories` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-categories) + from the desktop file; + i.e. no attempt is made to split it by `;` or validate it. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] When @info was created from a known filename, return it. In some -situations such as the #GDesktopAppInfo returned from -g_desktop_app_info_new_from_keyfile(), this function will return %NULL. +situations such as a [class@Gio.DesktopAppInfo] returned from +[ctor@Gio.DesktopAppInfo.new_from_keyfile], this function will return `NULL`. The full path to the file for @info, - or %NULL if not known. + or `NULL` if not known. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -187,12 +189,13 @@ g_desktop_app_info_new_from_keyfile(), this function will return %NULL. Gets the generic name from the desktop file. - The value of the GenericName key + The value of the + [`GenericName` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-genericname) - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -201,10 +204,10 @@ g_desktop_app_info_new_from_keyfile(), this function will return %NULL. Gets all applications that implement @interface. An application implements an interface if that interface is listed in -the Implements= line of the desktop file of the application. +the `Implements` line of the desktop file of the application. - a list of #GDesktopAppInfo -objects. + a list of + [class@Gio.DesktopAppInfo] objects. @@ -217,15 +220,16 @@ objects. - A desktop file is hidden if the Hidden key in it is -set to True. + A desktop file is hidden if the +[`Hidden` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-hidden) +in it is set to `True`. - %TRUE if hidden, %FALSE otherwise. + `TRUE` if hidden, `FALSE` otherwise. - a #GDesktopAppInfo. + a [class@Gio.DesktopAppInfo]. @@ -233,14 +237,15 @@ set to True. Gets the keywords from the desktop file. - The value of the Keywords key + The value of the + [`Keywords` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-keywords) - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -249,15 +254,15 @@ set to True. Looks up a localized string value in the keyfile backing @info translated to the current locale. -The @key is looked up in the "Desktop Entry" group. +The @key is looked up in the `Desktop Entry` group. - a newly allocated string, or %NULL if the key - is not found + a newly allocated string, or `NULL` if the key is not + found - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -267,16 +272,17 @@ The @key is looked up in the "Desktop Entry" group. - Gets the value of the NoDisplay key, which helps determine if the -application info should be shown in menus. See -%G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY and g_app_info_should_show(). + Gets the value of the +[`NoDisplay` key](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-nodisplay) + which helps determine if the application info should be shown in menus. See +`G_KEY_FILE_DESKTOP_KEY_NO_DISPLAY` and [method@Gio.AppInfo.should_show]. - The value of the NoDisplay key + The value of the `NoDisplay` key - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -284,24 +290,25 @@ application info should be shown in menus. See Checks if the application info should be shown in menus that list available applications for a specific name of the desktop, based on the -`OnlyShowIn` and `NotShowIn` keys. +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) +keys. -@desktop_env should typically be given as %NULL, in which case the +@desktop_env should typically be given as `NULL`, in which case the `XDG_CURRENT_DESKTOP` environment variable is consulted. If you want to override the default mechanism then you may specify @desktop_env, but this is not recommended. -Note that g_app_info_should_show() for @info will include this check (with -%NULL for @desktop_env) as well as additional checks. +Note that [method@Gio.AppInfo.should_show] for @info will include this check +(with `NULL` for @desktop_env) as well as additional checks. - %TRUE if the @info should be shown in @desktop_env according to the -`OnlyShowIn` and `NotShowIn` keys, %FALSE -otherwise. + `TRUE` if the @info should be shown in @desktop_env according to the +`OnlyShowIn` and `NotShowIn` keys, `FALSE` otherwise. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -311,17 +318,17 @@ otherwise. - Retrieves the StartupWMClass field from @info. This represents the -WM_CLASS property of the main window of the application, if launched + Retrieves the `StartupWMClass` field from @info. This represents the +`WM_CLASS` property of the main window of the application, if launched through @info. - the startup WM class, or %NULL if none is set -in the desktop file. + the startup WM class, or `NULL` if none + is set in the desktop file. - a #GDesktopAppInfo that supports startup notify + a [class@Gio.DesktopAppInfo] that supports startup notify @@ -329,15 +336,15 @@ in the desktop file. Looks up a string value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. +The @key is looked up in the `Desktop Entry` group. - a newly allocated string, or %NULL if the key - is not found + a newly allocated string, or `NULL` if the key is not + found - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -349,18 +356,18 @@ The @key is looked up in the "Desktop Entry" group. Looks up a string list value in the keyfile backing @info. -The @key is looked up in the "Desktop Entry" group. +The @key is looked up in the `Desktop Entry` group. - a %NULL-terminated string array or %NULL if the specified - key cannot be found. The array should be freed with g_strfreev(). + a `NULL`-terminated string array or `NULL` if the specified + key cannot be found. The array should be freed with [func@GLib.strfreev]. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -368,21 +375,22 @@ The @key is looked up in the "Desktop Entry" group. - return location for the number of returned strings, or %NULL + return location for the number of returned + strings, or `NULL` - Returns whether @key exists in the "Desktop Entry" group + Returns whether @key exists in the `Desktop Entry` group of the keyfile backing @info. - %TRUE if the @key exists + `TRUE` if the @key exists - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -395,60 +403,62 @@ of the keyfile backing @info. Activates the named application action. You may only call this function on action names that were -returned from g_desktop_app_info_list_actions(). +returned from [method@Gio.DesktopAppInfo.list_actions]. Note that if the main entry of the desktop file indicates that the application supports startup notification, and @launch_context is -non-%NULL, then startup notification will be used when activating the +non-`NULL`, then startup notification will be used when activating the action (and as such, invocation of the action on the receiving side must signal the end of startup notification when it is completed). This is the expected behaviour of applications declaring additional -actions, as per the desktop file specification. +actions, as per the +[desktop file specification](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html). -As with g_app_info_launch() there is no way to detect failures that +As with [method@Gio.AppInfo.launch] there is no way to detect failures that occur while using this function. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] the name of the action as from - g_desktop_app_info_list_actions() + [method@Gio.DesktopAppInfo.list_actions] - a #GAppLaunchContext + a [class@Gio.AppLaunchContext] - This function performs the equivalent of g_app_info_launch_uris(), + This function performs the equivalent of [method@Gio.AppInfo.launch_uris], but is intended primarily for operating system components that launch applications. Ordinary applications should use -g_app_info_launch_uris(). +[method@Gio.AppInfo.launch_uris]. If the application is launched via GSpawn, then @spawn_flags, @user_setup -and @user_setup_data are used for the call to g_spawn_async(). +and @user_setup_data are used for the call to [func@GLib.spawn_async]. Additionally, @pid_callback (with @pid_callback_data) will be called to -inform about the PID of the created process. See g_spawn_async_with_pipes() -for information on certain parameter conditions that can enable an -optimized posix_spawn() codepath to be used. +inform about the PID of the created process. See +[func@GLib.spawn_async_with_pipes] for information on certain parameter +conditions that can enable an optimized [`posix_spawn()`](man:posix_spawn(3)) +code path to be used. -If application launching occurs via some other mechanism (eg: D-Bus +If application launching occurs via some other mechanism (for example, D-Bus activation) then @spawn_flags, @user_setup, @user_setup_data, @pid_callback and @pid_callback_data are ignored. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -458,16 +468,16 @@ activation) then @spawn_flags, @user_setup, @user_setup_data, - a #GAppLaunchContext + a [class@Gio.AppLaunchContext] - #GSpawnFlags, used for each process + [flags@GLib.SpawnFlags], used for each process - a #GSpawnChildSetupFunc, used once - for each process. + a [callback@GLib.SpawnChildSetupFunc], + used once for each process. @@ -485,19 +495,19 @@ activation) then @spawn_flags, @user_setup, @user_setup_data, - Equivalent to g_desktop_app_info_launch_uris_as_manager() but allows + Equivalent to [method@Gio.DesktopAppInfo.launch_uris_as_manager] but allows you to pass in file descriptors for the stdin, stdout and stderr streams of the launched process. If application launching occurs via some non-spawn mechanism (e.g. D-Bus activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - %TRUE on successful launch, %FALSE otherwise. + `TRUE` on successful launch, `FALSE` otherwise. - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -507,16 +517,16 @@ activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - a #GAppLaunchContext + a [class@Gio.AppLaunchContext] - #GSpawnFlags, used for each process + [flags@GLib.SpawnFlags], used for each process - a #GSpawnChildSetupFunc, used once - for each process. + a + [callback@GLib.SpawnChildSetupFunc], used once for each process. @@ -532,34 +542,36 @@ activation) then @stdin_fd, @stdout_fd and @stderr_fd are ignored. - file descriptor to use for child's stdin, or -1 + file descriptor to use for child’s stdin, or `-1` - file descriptor to use for child's stdout, or -1 + file descriptor to use for child’s stdout, or `-1` - file descriptor to use for child's stderr, or -1 + file descriptor to use for child’s stderr, or `-1` - Returns the list of "additional application actions" supported on the -desktop file, as per the desktop file specification. + Returns the list of +[‘additional application actions’](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s11.html) +supported on the desktop file, as per the desktop file specification. As per the specification, this is the list of actions that are -explicitly listed in the "Actions" key of the [Desktop Entry] group. +explicitly listed in the `Actions` key of the `Desktop Entry` group. - a list of strings, always non-%NULL + a + list of strings, always non-`NULL` - a #GDesktopAppInfo + a [class@Gio.DesktopAppInfo] @@ -575,15 +587,15 @@ The algorithm for determining matches is undefined and may change at any time. None of the search results are subjected to the normal validation -checks performed by g_desktop_app_info_new() (for example, checking that +checks performed by [ctor@Gio.DesktopAppInfo.new] (for example, checking that the executable referenced by a result exists), and so it is possible for -g_desktop_app_info_new() to return %NULL when passed an app ID returned by -this function. It is expected that calling code will do this when -subsequently creating a #GDesktopAppInfo for each result. +[ctor@Gio.DesktopAppInfo.new] to return `NULL` when passed an app ID returned +by this function. It is expected that calling code will do this when +subsequently creating a [class@Gio.DesktopAppInfo] for each result. a - list of strvs. Free each item with g_strfreev() and free the outer - list with g_free(). + list of strvs. Free each item with [func@GLib.strfreev] and free the outer + list with [func@GLib.free]. @@ -599,14 +611,16 @@ subsequently creating a #GDesktopAppInfo for each result. Sets the name of the desktop that the application is running in. -This is used by g_app_info_should_show() and -g_desktop_app_info_get_show_in() to evaluate the -`OnlyShowIn` and `NotShowIn` -desktop entry fields. + +This is used by [method@Gio.AppInfo.should_show] and +[method@Gio.DesktopAppInfo.get_show_in] to evaluate the +[`OnlyShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-onlyshowin) +and [`NotShowIn`](https://specifications.freedesktop.org/desktop-entry-spec/latest/ar01s06.html#key-notshowin) +keys. Should be called only once; subsequent calls are ignored. do not use this API. Since 2.42 the value of the -`XDG_CURRENT_DESKTOP` environment variable will be used. + `XDG_CURRENT_DESKTOP` environment variable will be used. @@ -618,7 +632,7 @@ Should be called only once; subsequent calls are ignored. - The origin filename of this #GDesktopAppInfo + The origin filename of this [class@Gio.DesktopAppInfo] @@ -630,27 +644,28 @@ Should be called only once; subsequent calls are ignored. #GDesktopAppInfoLookup is an opaque data structure and can only be accessed using the following functions. - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. Gets the default application for launching applications -using this URI scheme for a particular #GDesktopAppInfoLookup +using this URI scheme for a particular [iface@Gio.DesktopAppInfoLookup] implementation. -The #GDesktopAppInfoLookup interface and this function is used -to implement g_app_info_get_default_for_uri_scheme() backends +The [iface@Gio.DesktopAppInfoLookup] interface and this function is used +to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends in a GIO module. There is no reason for applications to use it -directly. Applications should use g_app_info_get_default_for_uri_scheme(). - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. +directly. Applications should use +[func@Gio.AppInfo.get_default_for_uri_scheme]. + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. - a #GDesktopAppInfoLookup + a [iface@Gio.DesktopAppInfoLookup] @@ -1156,7 +1171,7 @@ when the stream is closed. - Defines a Unix mount entry (e.g. <filename>/media/cdrom</filename>). + Defines a Unix mount entry (e.g. `/media/cdrom`). This corresponds roughly to a mtab entry. @@ -1226,7 +1241,7 @@ the monitor. - Defines a Unix mount point (e.g. <filename>/dev</filename>). + Defines a Unix mount point (e.g. `/dev`). This corresponds roughly to a fstab entry. Gets a #GUnixMountPoint for a given mount path. If @time_read is set, it @@ -1592,23 +1607,24 @@ when the stream is closed. Gets the default application for launching applications -using this URI scheme for a particular #GDesktopAppInfoLookup +using this URI scheme for a particular [iface@Gio.DesktopAppInfoLookup] implementation. -The #GDesktopAppInfoLookup interface and this function is used -to implement g_app_info_get_default_for_uri_scheme() backends +The [iface@Gio.DesktopAppInfoLookup] interface and this function is used +to implement [func@Gio.AppInfo.get_default_for_uri_scheme] backends in a GIO module. There is no reason for applications to use it -directly. Applications should use g_app_info_get_default_for_uri_scheme(). - The #GDesktopAppInfoLookup interface is deprecated and - unused by GIO. +directly. Applications should use +[func@Gio.AppInfo.get_default_for_uri_scheme]. + The [iface@Gio.DesktopAppInfoLookup] interface is + deprecated and unused by GIO. - #GAppInfo for given @uri_scheme or - %NULL on error. + [iface@Gio.AppInfo] for given + @uri_scheme or `NULL` on error. - a #GDesktopAppInfoLookup + a [iface@Gio.DesktopAppInfoLookup] @@ -2194,6 +2210,41 @@ g_unix_mount_points_changed_since(). + + Gets an array of [struct@Gio.UnixMountPoint]s containing the Unix mount +points listed in @table_path. + +This is a generalized version of g_unix_mount_points_get(), mainly intended +for internal testing use. Note that g_unix_mount_points_get() may parse +multiple hierarchical table files, so this function is not a direct superset +of its functionality. + +If there is an error reading or parsing the file, `NULL` will be returned +and both out parameters will be set to `0`. + + mount + points, or `NULL` if there was an error loading them + + + + + + + path to the mount points table file (for example `/etc/fstab`) + + + + return location for the + modification time of @table_path + + + + return location for the + number of mount points returned + + + + Checks if the unix mounts have changed since a given unix time. @@ -2226,5 +2277,40 @@ with g_unix_mounts_changed_since(). + + Gets an array of [struct@Gio.UnixMountEntry]s containing the Unix mounts +listed in @table_path. + +This is a generalized version of g_unix_mounts_get(), mainly intended for +internal testing use. Note that g_unix_mounts_get() may parse multiple +hierarchical table files, so this function is not a direct superset of its +functionality. + +If there is an error reading or parsing the file, `NULL` will be returned +and both out parameters will be set to `0`. + + mount + entries, or `NULL` if there was an error loading them + + + + + + + path to the mounts table file (for example `/proc/self/mountinfo`) + + + + return location for the + modification time of @table_path + + + + return location for the + number of mount entries returned + + + + diff --git a/GioWin32-2.0.gir b/GioWin32-2.0.gir new file mode 100644 index 00000000..96a86c47 --- /dev/null +++ b/GioWin32-2.0.gir @@ -0,0 +1,393 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + `GWin32InputStream` implements [class@Gio.InputStream] for reading from a +Windows file handle. + +Note that `<gio/gwin32inputstream.h>` belongs to the Windows-specific GIO +interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file +when using it. + + Creates a new #GWin32InputStream for the given @handle. + +If @close_handle is %TRUE, the handle will be closed +when the stream is closed. + +Note that "handle" here means a Win32 HANDLE, not a "file descriptor" +as used in the Windows C libraries. + + a new #GWin32InputStream + + + + + a Win32 file handle + + + + %TRUE to close the handle when done + + + + + + Returns whether the handle of @stream will be +closed when the stream is closed. + + %TRUE if the handle is closed when done + + + + + a #GWin32InputStream + + + + + + Return the Windows file handle that the stream reads from. + + The file handle of @stream + + + + + a #GWin32InputStream + + + + + + Sets whether the handle of @stream shall be closed +when the stream is closed. + + + + + + a #GWin32InputStream + + + + %TRUE to close the handle when done + + + + + + Whether to close the file handle when the stream is closed. + + + + The handle that the stream reads from. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + `GWin32OutputStream` implements [class@Gio.OutputStream] for writing to a +Windows file handle. + +Note that `<gio/gwin32outputstream.h>` belongs to the Windows-specific GIO +interfaces, thus you have to use the `gio-windows-2.0.pc` pkg-config file +when using it. + + Creates a new #GWin32OutputStream for the given @handle. + +If @close_handle, is %TRUE, the handle will be closed when the +output stream is destroyed. + + a new #GOutputStream + + + + + a Win32 file handle + + + + %TRUE to close the handle when done + + + + + + Returns whether the handle of @stream will be closed when the +stream is closed. + + %TRUE if the handle is closed when done + + + + + a #GWin32OutputStream + + + + + + Return the Windows handle that the stream writes to. + + The handle descriptor of @stream + + + + + a #GWin32OutputStream + + + + + + Sets whether the handle of @stream shall be closed when the stream +is closed. + + + + + + a #GWin32OutputStream + + + + %TRUE to close the handle when done + + + + + + Whether to close the file handle when the stream is closed. + + + + The file handle that the stream writes to. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + If @registry_key is %NULL then the default path +`HKEY_CURRENT_USER\Software\GSettings` is used. + + a registry-backed #GSettingsBackend + + + + + the path to the registry key where + settings are stored, or %NULL. + + + + + + diff --git a/Gsk-4.0.gir b/Gsk-4.0.gir index f5146097..a6d2ba7e 100644 --- a/Gsk-4.0.gir +++ b/Gsk-4.0.gir @@ -521,7 +521,10 @@ the area given by @bounds. - Retrieves the color of the given @node. + Retrieves the color of the given @node. + +The value returned by this function will not be correct +if the render node was created for a non-sRGB color. the color of the node @@ -1859,7 +1862,10 @@ into the box given by @outline. - Retrieves the color of the inset shadow. + Retrieves the color of the inset shadow. + +The value returned by this function will not be correct +if the render node was created for a non-sRGB color. the color of the shadow @@ -2267,7 +2273,10 @@ around the box given by @outline. - Retrieves the color of the outset shadow. + Retrieves the color of the outset shadow. + +The value returned by this function will not be correct +if the render node was created for a non-sRGB color. a color @@ -4436,6 +4445,7 @@ The rectangle will be fully contained in the bounds of the node. + return location for the opaque rect @@ -6098,7 +6108,10 @@ color glyphs. - Retrieves the color used by the text @node. + Retrieves the color used by the text @node. + +The value returned by this function will not be correct +if the render node was created for a non-sRGB color. the text color diff --git a/Gtk-3.0.gir b/Gtk-3.0.gir index 63589280..7b024b6f 100644 --- a/Gtk-3.0.gir +++ b/Gtk-3.0.gir @@ -9160,7 +9160,7 @@ container that has been allocated. - + Like gtk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -63513,7 +63513,7 @@ against at application run time. - + Like gtk_get_micro_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. diff --git a/Gtk-4.0.gir b/Gtk-4.0.gir index c104f937..71f6614f 100644 --- a/Gtk-4.0.gir +++ b/Gtk-4.0.gir @@ -2221,8 +2221,8 @@ integers or strings. provide additional information related to the object. Value type: reference - Identifies the element that provides - an error message for an object. Value type: reference + Identifies the element (or elements) that + provide an error message for an object. Value type: reference Identifies the next element (or elements) @@ -4586,7 +4586,7 @@ Note that in horizontal context `GTK_ALIGN_START` and `GTK_ALIGN_END` are interpreted relative to text direction. Baseline support is optional for containers and widgets, and is only available -for vertical alignment. `GTK_ALIGN_BASELINE_CENTER and `GTK_ALIGN_BASELINE_FILL` +for vertical alignment. `GTK_ALIGN_BASELINE_CENTER` and `GTK_ALIGN_BASELINE_FILL` are treated similar to `GTK_ALIGN_CENTER` and `GTK_ALIGN_FILL`, except that it positions the widget to line up the baselines, where that is supported. @@ -7288,7 +7288,7 @@ See gtk_assistant_commit() for details. add its own buttons through gtk_assistant_add_action_widget(). - + Like [func@get_binary_age], but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -9893,7 +9893,8 @@ property types: - colors (in a format understood by [method@Gdk.RGBA.parse]) - `GVariant` (can be specified in the format understood by [func@GLib.Variant.parse]) -- pixbufs (can be specified as a filename of an image file to load) +- pixbufs (can be specified as an object id, a resource path or a filename of an image file to load relative to the Builder file or the CWD if [method@Gtk.Builder.add_from_string] was used) +- GFile (like pixbufs, can be specified as an object id, a URI or a filename of a file to load relative to the Builder file or the CWD if [method@Gtk.Builder.add_from_string] was used) Objects can be referred to by their name and by default refer to objects declared in the local XML fragment and objects exposed via @@ -19834,7 +19835,7 @@ track of the group changes and state is discouraged. # CSS nodes ``` -checkbutton[.text-button] +checkbutton[.text-button][.grouped] ├── check ╰── [label] ``` @@ -21850,7 +21851,7 @@ If @self is unbound, %GTK_INVALID_LIST_POSITION is returned. Checks if the item is displayed as selected. -The selected state is maintained by the liste widget and its model +The selected state is maintained by the list widget and its model and cannot be set otherwise. %TRUE if the item is selected. @@ -51761,7 +51762,8 @@ of the icon size set by [method@Gtk.Image.set_from_icon_name]. - + + A path to the file to display. @@ -51794,7 +51796,8 @@ If set to a value != -1, this property overrides the `GTK_IMAGE_ICON_NAME`. - + + A path to a resource file to display. @@ -56050,6 +56053,19 @@ between rows. + + Returns the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. + + the tab behavior + + + + + a `GtkListBox` + + + + Insert the @child into the @box at @position. @@ -56438,6 +56454,22 @@ Note that using a sort function is incompatible with using a model + + Sets the behavior of the <kbd>Tab</kbd> and <kbd>Shift</kbd>+<kbd>Tab</kbd> keys. + + + + + + a `GtkListBox` + + + + the tab behavior + + + + Unselect all children of @box, if the selection mode allows it. @@ -56483,6 +56515,10 @@ click, or require a double-click. Whether to show separators between rows. + + Behavior of the <kbd>Tab</kbd> key + + Emitted when the cursor row is activated. @@ -57212,7 +57248,7 @@ Do not confuse this function with [method@Gtk.ListItem.get_selected]. Checks if the item is displayed as selected. -The selected state is maintained by the liste widget and its model +The selected state is maintained by the list widget and its model and cannot be set otherwise. %TRUE if the item is selected. @@ -58774,13 +58810,13 @@ This macro is longer used by GTK. - + Like [func@get_micro_version], but from the headers used at application compile time, rather than from the library linked against at application run time. - + Like [func@get_minor_version], but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -67129,7 +67165,7 @@ tweak its behavior. ## GtkPopover as menu replacement -`GtkPopover` is often used to replace menus. The best was to do this +`GtkPopover` is often used to replace menus. The best way to do this is to use the [class@Gtk.PopoverMenu] subclass which supports being populated from a `GMenuModel` with [ctor@Gtk.PopoverMenu.new_from_model]. @@ -82206,7 +82242,7 @@ gtk_selection_model_unselect_item() is supported. Note that setting [property@Gtk.SingleSelection:autoselect] will cause unselecting to not work, so it practically makes no sense -to set both at the same time the same time. +to set both at the same time. @@ -82247,7 +82283,8 @@ If the list does not have an item at @position or value of the [property@Gtk.SingleSelection:autoselect] property: If it is set, no change will occur and the old item will stay selected. If it is unset, the selection will be unset and no item -will be selected. +will be selected. This also applies if [property@Gtk.SingleSelection:can-unselect] +is set to %FALSE. @@ -86950,6 +86987,25 @@ The @string will be copied. See + + Gets the position of the @string in @self. + +If @self does not contain @string item, `G_MAXUINT` is returned. + + the position of the string + + + + + a `GtkStringList` + + + + the string to find + + + + Gets the string that is at @position in @self. @@ -89749,6 +89805,47 @@ to be in order. + + Adds a [callback@Gtk.TextBufferCommitNotify] to be called when a change +is to be made to the [type@Gtk.TextBuffer]. + +Functions are explicitly forbidden from making changes to the +[type@Gtk.TextBuffer] from this callback. It is intended for tracking +changes to the buffer only. + +It may be advantageous to use [callback@Gtk.TextBufferCommitNotify] over +connecting to the [signal@Gtk.TextBuffer::insert-text] or +[signal@Gtk.TextBuffer::delete-range] signals to avoid ordering issues with +other signal handlers which may further modify the [type@Gtk.TextBuffer]. + + a handler id which may be used to remove the commit notify + callback using [method@Gtk.TextBuffer.remove_commit_notify]. + + + + + a [type@Gtk.TextBuffer] + + + + which notifications should be dispatched to @callback + + + + a + [callback@Gtk.TextBufferCommitNotify] to call for commit notifications + + + + closure data for @commit_notify + + + + a callback to free @user_data when @commit_notify is removed + + + + Adds the mark at position @where. @@ -91263,6 +91360,27 @@ code sections that add tags. + + Removes the `GtkTextBufferCommitNotify` handler previously registered +with [method@Gtk.TextBuffer.add_commit_notify]. + +This may result in the `user_data_destroy` being called that was passed when registering +the commit notify functions. + + + + + + a `GtkTextBuffer` + + + + the notify handler identifier returned from + [method@Gtk.TextBuffer.add_commit_notify]. + + + + Removes a `GdkClipboard` added with [method@Gtk.TextBuffer.add_selection_clipboard] @@ -92095,6 +92213,85 @@ been grouped together. + + A notification callback used by [method@Gtk.TextBuffer.add_commit_notify]. + +You may not modify the [class@Gtk.TextBuffer] from a +[callback@Gtk.TextBufferCommitNotify] callback and that is enforced +by the [class@Gtk.TextBuffer] API. + +[callback@Gtk.TextBufferCommitNotify] may be used to be notified about +changes to the underlying buffer right before-or-after the changes are +committed to the underlying B-Tree. This is useful if you want to observe +changes to the buffer without other signal handlers potentially modifying +state on the way to the default signal handler. + +When @flags is `GTK_TEXT_BUFFER_NOTIFY_BEFORE_INSERT`, `position` is set to +the offset in characters from the start of the buffer where the insertion +will occur. `length` is set to the number of characters to be inserted. You +may not yet retrieve the text until it has been inserted. You may access the +text from `GTK_TEXT_BUFFER_NOTIFY_AFTER_INSERT` using +[method@Gtk.TextBuffer.get_slice]. + +When @flags is `GTK_TEXT_BUFFER_NOTIFY_AFTER_INSERT`, `position` is set to +offset in characters where the insertion occurred and `length` is set +to the number of characters inserted. + +When @flags is `GTK_TEXT_BUFFER_NOTIFY_BEFORE_DELETE`, `position` is set to +offset in characters where the deletion will occur and `length` is set +to the number of characters that will be removed. You may still retrieve +the text from this handler using `position` and `length`. + +When @flags is `GTK_TEXT_BUFFER_NOTIFY_AFTER_DELETE`, `length` is set to +zero to denote that the delete-range has already been committed to the +underlying B-Tree. You may no longer retrieve the text that has been +deleted from the [class@Gtk.TextBuffer]. + + + + + + the text buffer being notified + + + + the type of commit notification + + + + the position of the text operation + + + + the length of the text operation in characters + + + + user data passed to the callback + + + + + + Values for [callback@Gtk.TextBufferCommitNotify] to denote the +point of the notification. + + Be notified before text + is inserted into the underlying buffer. + + + Be notified after text + has been inserted into the underlying buffer. + + + Be notified before text + is deleted from the underlying buffer. + + + Be notified after text + has been deleted from the underlying buffer. + + The predicate function used by gtk_text_iter_forward_find_char() and @@ -115064,7 +115261,15 @@ called on them. Opens or closes the [interactive debugger](running.html#interactive-debugging). The debugger offers access to the widget hierarchy of the application -and to useful debugging tools. +and to useful debugging tools. + +This function allows applications that already use +<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>I</kbd> +(or <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>) +for their own key shortcuts to add a different shortcut to open the Inspector. + +If you are not overriding the default key shortcuts for the Inspector, +you should not use this function. diff --git a/Pango-1.0.gir b/Pango-1.0.gir index 886b95fb..5519dcee 100644 --- a/Pango-1.0.gir +++ b/Pango-1.0.gir @@ -3803,7 +3803,7 @@ The unset fields will get back to their default values. The string must have the form - "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", + "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS]", where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list @@ -3811,7 +3811,7 @@ of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size. VARIATIONS is a comma-separated list of font variation -specifications of the form "\@axis=value" (the = sign is optional). +specifications of the form @‍axis=value (the = sign is optional). The following words are understood as styles: "Normal", "Roman", "Oblique", "Italic". @@ -3842,7 +3842,7 @@ size in the resulting font description will be set to 0. A typical example: - "Cantarell Italic Light 15 \@wght=200" + "Cantarell Italic Light 15 @‍wght=200" a new `PangoFontDescription`. @@ -13235,7 +13235,7 @@ and @next_paragraph_start are filled with the length of @text The string must have the form - "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", + "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS]", where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list @@ -13243,7 +13243,7 @@ of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size. VARIATIONS is a comma-separated list of font variation -specifications of the form "\@axis=value" (the = sign is optional). +specifications of the form @‍axis=value (the = sign is optional). The following words are understood as styles: "Normal", "Roman", "Oblique", "Italic". @@ -13274,7 +13274,7 @@ size in the resulting font description will be set to 0. A typical example: - "Cantarell Italic Light 15 \@wght=200" + "Cantarell Italic Light 15 @‍wght=200" a new `PangoFontDescription`. From 0706a5b8ec168a4988e2869a0b23dbb5229a5329 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Sebastian=20Dr=C3=B6ge?= Date: Tue, 22 Oct 2024 13:02:56 +0300 Subject: [PATCH 4/4] Update branch from master to main --- .github/workflows/CI.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 14d3dd91..c6ab6e38 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -14,17 +14,17 @@ jobs: - uses: actions/checkout@v4 with: repository: gtk-rs/gir - ref: master + ref: main path: gir - uses: actions/checkout@v4 with: repository: gtk-rs/gtk4-rs - ref: master + ref: main path: gtk4-rs - uses: actions/checkout@v4 with: repository: gtk-rs/gtk3-rs - ref: master + ref: main path: gtk3-rs - working-directory: gir run: cargo build --release