diff --git a/GLib-2.0.gir b/GLib-2.0.gir index 38105f1b..dc79f3ef 100644 --- a/GLib-2.0.gir +++ b/GLib-2.0.gir @@ -160,13 +160,24 @@ alignment. - + + Evaluates to a truth value if the absolute difference between @a and @b is +smaller than @epsilon, and to a false value otherwise. + +For example, +- `G_APPROX_VALUE (5, 6, 2)` evaluates to true +- `G_APPROX_VALUE (3.14, 3.15, 0.001)` evaluates to false +- `G_APPROX_VALUE (n, 0.f, FLT_EPSILON)` evaluates to true if `n` is within + the single precision floating point epsilon from zero + a numeric value + a numeric value + a numeric value that expresses the tolerance between @a and @b @@ -1498,6 +1509,8 @@ the queue is destroyed after the final unref. + Specifies one of the possible types of byte order. +See %G_BYTE_ORDER. @@ -3621,19 +3634,60 @@ Used for specifying valid identifier characters in #GScannerConfig. - + + Macro to check if the current compiler supports a specified @version +of the C++ standard. Such value must be numeric and can be provided both +in the short form for the well-known versions (e.g. `11`, `17`...) or in +the complete form otherwise (e.g. `201103L`, `201703L`, `205503L`...). + +When a C compiler is used, the macro is defined and returns always %FALSE. + +This value is compared against %G_CXX_STD_VERSION. + +|[<!-- language="C" --> +#if G_CXX_STD_CHECK_VERSION(20) +#endif +]| + +See also: %G_C_STD_CHECK_VERSION + The C++ version to be checked for compatibility - + + Macro to check if the current compiler supports a specified @version +of the C standard. Such value must be numeric and can be provided both +in the short form for the well-known versions (e.g. `90`, `99`...) or in +the complete form otherwise (e.g. `199000L`, `199901L`, `205503L`...). + +When a C++ compiler is used, the macro is defined and returns always %FALSE. + +This value is compared against %G_C_STD_VERSION. + +|[<!-- language="C" --> +#if G_C_STD_CHECK_VERSION(17) +#endif +]| + +See also: %G_CXX_STD_CHECK_VERSION + The C version to be checked for compatibility - + + The C standard version the code is compiling against, it's normally +defined with the same value of `__STDC_VERSION__` for C standard +compatible compilers, while it uses the lowest standard version +in pure MSVC, given that in such compiler the definition depends on +a compilation flag. + +This is granted to be undefined when compiling with a C++ compiler. + +See also: %G_C_STD_CHECK_VERSION and %G_CXX_STD_VERSION @@ -4767,29 +4821,86 @@ flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. functions when debugging. It prints the current monotonic time and the code location using %G_STRLOC. - + + Defines the appropriate cleanup function for a pointer type. + +The function will not be called if the variable to be cleaned up +contains %NULL. + +This will typically be the `_free()` or `_unref()` function for the given +type. + +With this definition, it will be possible to use g_autoptr() with +@TypeName. + +|[ +G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref) +]| + +This macro should be used unconditionally; it is a no-op on compilers +where cleanup is not supported. + a type name to define a g_autoptr() cleanup function for + the cleanup function - + + Defines the appropriate cleanup function for a type. + +This will typically be the `_clear()` function for the given type. + +With this definition, it will be possible to use g_auto() with +@TypeName. + +|[ +G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear) +]| + +This macro should be used unconditionally; it is a no-op on compilers +where cleanup is not supported. + a type name to define a g_auto() cleanup function for + the clear function - + + Defines the appropriate cleanup function for a type. + +With this definition, it will be possible to use g_auto() with +@TypeName. + +This function will be rarely used. It is used with pointer-based +typedefs and non-pointer types where the value of the variable +represents a resource that must be freed. Two examples are #GStrv +and file descriptors. + +@none specifies the "none" value for the type in question. It is +probably something like %NULL or `-1`. If the variable is found to +contain this value then the free function will not be called. + +|[ +G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL) +]| + +This macro should be used unconditionally; it is a no-op on compilers +where cleanup is not supported. + a type name to define a g_auto() cleanup function for + the free function + the "none" value for the type @@ -5554,9 +5665,13 @@ in the macro, so you shouldn't use double quotes. + The directory separator character. +This is '/' on UNIX machines and '\' under Windows. + The directory separator as a string. +This is "/" on UNIX machines and "\" under Windows. @@ -8067,7 +8182,12 @@ modified, and might thus be a read-only literal string. + The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, +mantissa and exponent of IEEE floats and doubles. These unions are defined +as appropriate for a given platform. IEEE floats and doubles are supported +(used for storage) by at least Intel, PPC and Sparc. + the double value @@ -8107,6 +8227,7 @@ object. + The base of natural logarithms. @@ -8652,7 +8773,12 @@ performance. + The #GFloatIEEE754 and #GDoubleIEEE754 unions are used to access the sign, +mantissa and exponent of IEEE floats and doubles. These unions are defined +as appropriate for a given platform. IEEE floats and doubles are supported +(used for storage) by at least Intel, PPC and Sparc. + the double value @@ -8802,11 +8928,21 @@ See the [GNU C documentation](https://gcc.gnu.org/onlinedocs/gcc/Common-Function - + + Expands to a check for a compiler with __GNUC__ defined and a version +greater than or equal to the major and minor numbers provided. For example, +the following would only match on compilers such as GCC 4.8 or newer. + +|[<!-- language="C" --> +#if G_GNUC_CHECK_VERSION(4, 8) +#endif +]| + major version to check against + minor version to check against @@ -8992,6 +9128,7 @@ for details. + Defined to 1 if gcc-style visibility handling is supported. @@ -11046,9 +11183,11 @@ more convenient than the raw iconv wrappers. + The bias by which exponents in double-precision floats are offset. + The bias by which exponents in single-precision floats are offset. @@ -12214,9 +12353,13 @@ in a generic way. Resource temporarily unavailable. - + + Checks whether a character is a directory +separator. It returns %TRUE for '/' on UNIX +machines and for '\' or '/' under Windows. + a character @@ -13860,19 +14003,31 @@ reaches zero, frees the key file and all its allocated memory. written back. - + + Hints the compiler that the expression is likely to evaluate to +a true value. The compiler may use this information for optimizations. + +|[<!-- language="C" --> +if (G_LIKELY (random () != 1)) + g_print ("not one"); +]| + the expression + Specifies one of the possible types of byte order. +See %G_BYTE_ORDER. + The natural logarithm of 10. + The natural logarithm of 2. @@ -13942,6 +14097,7 @@ module. + Multiplying the base 2 exponent by this number yields the base 10 exponent. @@ -17442,8 +17598,13 @@ in structures and initialised with g_mutex_init(). + Determines the number of elements in an array. The array must be +declared so the compiler knows its size at compile-time; this +macro will not work on an array allocated on the heap, only static +arrays or arrays on the stack. + the array @@ -19153,9 +19314,12 @@ and all memory allocated by the @group is released. + Specifies one of the possible types of byte order +(currently unused). See %G_BYTE_ORDER. + The value of pi (ratio of circle's circumference to its diameter). @@ -19164,9 +19328,11 @@ when printing a #GPid. + Pi divided by 2. + Pi divided by 4. @@ -19617,15 +19783,15 @@ This function can be passed to g_hash_table_new() as the - A `GPatternSpec` struct is the 'compiled' form of a glob-style pattern. + A `GPatternSpec` struct is the ‘compiled’ form of a glob-style pattern. The [func@GLib.pattern_match_simple] and [method@GLib.PatternSpec.match] functions -match a string against a pattern containing '*' and '?' wildcards with similar -semantics as the standard `glob()` function: '*' matches an arbitrary, -possibly empty, string, '?' matches an arbitrary character. +match a string against a pattern containing `*` and `?` wildcards with similar +semantics as the standard `glob()` function: `*` matches an arbitrary, +possibly empty, string, `?` matches an arbitrary character. -Note that in contrast to `glob()`, the '/' character can be matched by -the wildcards, there are no '[...]' character ranges and '*' and '?' +Note that in contrast to [`glob()`](man:glob(3)), the `/` character can be +matched by the wildcards, there are no `[…]` character ranges and `*` and `?` can not be escaped to include them literally in a pattern. When multiple strings must be matched against the same pattern, it is better @@ -19634,9 +19800,9 @@ to compile the pattern to a [struct@GLib.PatternSpec] using instead of [func@GLib.pattern_match_simple]. This avoids the overhead of repeated pattern compilation. - Compiles a pattern to a #GPatternSpec. + Compiles a pattern to a [type@GLib.PatternSpec]. - a newly-allocated #GPatternSpec + a newly-allocated [type@GLib.PatternSpec] @@ -19647,7 +19813,7 @@ pattern compilation. - Copies @pspec in a new #GPatternSpec. + Copies @pspec in a new [type@GLib.PatternSpec]. a copy of @pspec. @@ -19678,7 +19844,7 @@ match the same set of strings. - Frees the memory allocated for the #GPatternSpec. + Frees the memory allocated for the [type@GLib.PatternSpec]. @@ -19690,23 +19856,25 @@ match the same set of strings. - Matches a string against a compiled pattern. Passing the correct + Matches a string against a compiled pattern. + +Passing the correct length of the string given is mandatory. The reversed string can be -omitted by passing %NULL, this is more efficient if the reversed +omitted by passing `NULL`, this is more efficient if the reversed version of the string to be matched is not at hand, as -g_pattern_match() will only construct it if the compiled pattern +[method@GLib.PatternSpec.match] will only construct it if the compiled pattern requires reverse matches. Note that, if the user code will (possibly) match a string against a multitude of patterns containing wildcards, chances are high that -some patterns will require a reversed string. In this case, it's +some patterns will require a reversed string. In this case, it’s more efficient to provide the reversed string to avoid multiple -constructions thereof in the various calls to g_pattern_match(). +constructions thereof in the various calls to [method@GLib.PatternSpec.match]. Note also that the reverse of a UTF-8 encoded string can in general -not be obtained by g_strreverse(). This works only if the string +not be obtained by [func@GLib.strreverse]. This works only if the string does not contain any multibyte characters. GLib offers the -g_utf8_strreverse() function to reverse UTF-8 encoded strings. +[func@GLib.utf8_strreverse] function to reverse UTF-8 encoded strings. %TRUE if @string matches @pspec @@ -19717,8 +19885,8 @@ g_utf8_strreverse() function to reverse UTF-8 encoded strings. - the length of @string (in bytes, i.e. strlen(), - not g_utf8_strlen()) + the length of @string (in bytes, i.e. `strlen()`, + not [func@GLib.utf8_strlen]) @@ -19726,15 +19894,17 @@ g_utf8_strreverse() function to reverse UTF-8 encoded strings. - the reverse of @string or %NULL + the reverse of @string - Matches a string against a compiled pattern. If the string is to be + Matches a string against a compiled pattern. + +If the string is to be matched against more than one pattern, consider using -g_pattern_match() instead while supplying the reversed string. +[method@GLib.PatternSpec.match] instead while supplying the reversed string. %TRUE if @string matches @pspec @@ -24101,9 +24271,13 @@ currently the number of fields must be 2. + The search path separator character. +This is ':' on UNIX machines and ';' under Windows. + The search path separator as a string. +This is ":" on UNIX machines and ";" under Windows. @@ -24932,11 +25106,26 @@ the #GSource from the main loop. + The square root of two. + Accepts a macro or a string and converts it into a string after +preprocessor argument expansion. For example, the following code: + +|[<!-- language="C" --> +#define AGE 27 +const gchar *greeting = G_STRINGIFY (AGE) " today!"; +]| + +is transformed by the preprocessor into (code equivalent to): + +|[<!-- language="C" --> +const gchar *greeting = "27 today!"; +]| + a macro or a string @@ -24947,28 +25136,43 @@ the #GSource from the main loop. + Returns a member of a structure at a given offset, using the given type. + the type of the struct field + a pointer to a struct + the offset of the field from the start of the struct, + in bytes + Returns an untyped pointer to a given offset of a struct. + a pointer to a struct + the offset from the start of the struct, in bytes + Returns the offset, in bytes, of a member of a struct. + +Consider using standard C `offsetof()`, available since at least C89 +and C++98, in new code (but note that `offsetof()` returns a `size_t` +rather than a `long`). + a structure type, e.g. #GtkWidget + a field in the structure, e.g. @window @@ -27132,7 +27336,7 @@ should not count on @func being called with @data as its first parameter. Cast @func with G_SOURCE_FUNC() to avoid warnings about incompatible function types. -See [memory management of sources][mainloop-memory-management] for details +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 @@ -32847,9 +33051,17 @@ decomposition of a single Unicode character. This is as defined by Unicode 6.1. - + + Hints the compiler that the expression is unlikely to evaluate to +a true value. The compiler may use this information for optimizations. + +|[<!-- language="C" --> +if (G_UNLIKELY (random () == 1)) + g_print ("a random one"); +]| + the expression @@ -39725,10 +39937,19 @@ function passed to g_atexit(). + On Windows, this macro defines a DllMain() function that stores +the actual DLL name that the code being compiled will be included in. + +On non-Windows platforms, expands to nothing. + empty or "static" + the name of the (pointer to the) char array where + the DLL name will be stored. If this is used, you must also + include `windows.h`. If you need a more complex DLL entry + point function, you cannot use this @@ -43358,9 +43579,31 @@ pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. This will mask any warnings about incompatible function types or calling conventions, so you must ensure that your @destroy function is -compatible with being called as `GDestroyNotify` using the standard calling -convention for the platform that GLib was compiled for; otherwise the program -will experience undefined behaviour. +compatible with being called as [callback@GLib.DestroyNotify] using the +standard calling convention for the platform that GLib was compiled for; +otherwise the program will experience undefined behaviour. + +Examples of this kind of undefined behaviour include using many Windows Win32 +APIs, as well as many if not all OpenGL and Vulkan calls on 32-bit Windows, +which typically use the `__stdcall` calling convention rather than the +`__cdecl` calling convention. + +The affected functions can be used by wrapping them in a +[callback@GLib.DestroyNotify] that is declared with the standard calling +convention: + +```c +// Wrapper needed to avoid mismatched calling conventions on Windows +static void +destroy_sync (void *sync) +{ + glDeleteSync (sync); +} + +// … + +g_clear_pointer (&sync, destroy_sync); +``` @@ -43371,7 +43614,7 @@ will experience undefined behaviour. - a function to which a gpointer can be passed, to destroy *@pp + a function to which a gpointer can be passed, to destroy `*pp` @@ -47570,14 +47813,18 @@ the canonical presentation form will be entirely ASCII. + Converts a 32-bit integer value from host to network byte order. + a 32-bit integer value in host byte order + Converts a 16-bit integer value from host to network byte order. + a 16-bit integer value in host byte order @@ -47652,7 +47899,7 @@ default idle priority, %G_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 [memory management of sources][mainloop-memory-management] for details +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() @@ -47682,7 +47929,7 @@ events pending. If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically removed from the list of event sources and will not be called again. -See [memory management of sources][mainloop-memory-management] for details +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() @@ -50118,14 +50365,18 @@ vulnerability. + Converts a 32-bit integer value from network to host byte order. + a 32-bit integer value in network byte order + Converts a 16-bit integer value from network to host byte order. + a 16-bit integer value in network byte order @@ -50594,24 +50845,26 @@ is not an absolute path it returns %NULL. - Matches a string against a compiled pattern. Passing the correct + Matches a string against a compiled pattern. + +Passing the correct length of the string given is mandatory. The reversed string can be -omitted by passing %NULL, this is more efficient if the reversed +omitted by passing `NULL`, this is more efficient if the reversed version of the string to be matched is not at hand, as -g_pattern_match() will only construct it if the compiled pattern +`g_pattern_match()` will only construct it if the compiled pattern requires reverse matches. Note that, if the user code will (possibly) match a string against a multitude of patterns containing wildcards, chances are high that -some patterns will require a reversed string. In this case, it's +some patterns will require a reversed string. In this case, it’s more efficient to provide the reversed string to avoid multiple -constructions thereof in the various calls to g_pattern_match(). +constructions thereof in the various calls to `g_pattern_match()`. Note also that the reverse of a UTF-8 encoded string can in general -not be obtained by g_strreverse(). This works only if the string +not be obtained by [func@GLib.strreverse]. This works only if the string does not contain any multibyte characters. GLib offers the -g_utf8_strreverse() function to reverse UTF-8 encoded strings. - Use g_pattern_spec_match() instead +[func@GLib.utf8_strreverse] function to reverse UTF-8 encoded strings. + Use [method@GLib.PatternSpec.match] instead %TRUE if @string matches @pspec @@ -50622,8 +50875,8 @@ g_utf8_strreverse() function to reverse UTF-8 encoded strings. - the length of @string (in bytes, i.e. strlen(), - not g_utf8_strlen()) + the length of @string (in bytes, i.e. `strlen()`, + not [func@GLib.utf8_strlen]) @@ -50631,16 +50884,18 @@ g_utf8_strreverse() function to reverse UTF-8 encoded strings. - the reverse of @string or %NULL + the reverse of @string - Matches a string against a pattern given as a string. If this -function is to be called in a loop, it's more efficient to compile -the pattern once with g_pattern_spec_new() and call -g_pattern_match_string() repeatedly. + Matches a string against a pattern given as a string. + +If this +function is to be called in a loop, it’s more efficient to compile +the pattern once with [ctor@GLib.PatternSpec.new] and call +[method@GLib.PatternSpec.match_string] repeatedly. %TRUE if @string matches @pspec @@ -50657,10 +50912,12 @@ g_pattern_match_string() repeatedly. - Matches a string against a compiled pattern. If the string is to be + Matches a string against a compiled pattern. + +If the string is to be matched against more than one pattern, consider using -g_pattern_match() instead while supplying the reversed string. - Use g_pattern_spec_match_string() instead +[method@GLib.PatternSpec.match] instead while supplying the reversed string. + Use [method@GLib.PatternSpec.match_string] instead %TRUE if @string matches @pspec @@ -52811,23 +53068,41 @@ preserve things literally. - + + Performs a checked addition of @a and @b, storing the result in +@dest. + +If the operation is successful, %TRUE is returned. If the operation +overflows then the state of @dest is undefined and %FALSE is +returned. + a pointer to the #gsize destination + the #gsize left operand + the #gsize right operand - + + Performs a checked multiplication of @a and @b, storing the result in +@dest. + +If the operation is successful, %TRUE is returned. If the operation +overflows then the state of @dest is undefined and %FALSE is +returned. + a pointer to the #gsize destination + the #gsize left operand + the #gsize right operand @@ -54502,9 +54777,20 @@ Comparing two %NULL pointers returns 0. - Replaces all escaped characters with their one byte equivalent. - -This function does the reverse conversion of [func@GLib.strescape]. + Makes a copy of a string replacing C string-style escape +sequences with their one byte equivalent: + +- `\b` → [U+0008 Backspace](https://en.wikipedia.org/wiki/Backspace) +- `\f` → [U+000C Form Feed](https://en.wikipedia.org/wiki/Form_feed) +- `\n` → [U+000A Line Feed](https://en.wikipedia.org/wiki/Newline) +- `\r` → [U+000D Carriage Return](https://en.wikipedia.org/wiki/Carriage_return) +- `\t` → [U+0009 Horizontal Tabulation](https://en.wikipedia.org/wiki/Tab_character) +- `\v` → [U+000B Vertical Tabulation](https://en.wikipedia.org/wiki/Vertical_Tab) +- `\` followed by one to three octal digits → the numeric value (mod 255) +- `\` followed by any other character → the character as is. + For example, `\\` will turn into a backslash (`\`) and `\"` into a double quote (`"`). + +[func@GLib.strescape] does the reverse conversion. a newly-allocated copy of @source with all escaped character compressed @@ -54716,11 +55002,22 @@ g_strerror (saved_errno); - Escapes the special characters '\b', '\f', '\n', '\r', '\t', '\v', '\' -and '"' in the string @source by inserting a '\' before -them. Additionally all characters in the range 0x01-0x1F (everything + It replaces the following special characters in the string @source +with their corresponding C escape sequence: + + Symbol | Escape +---|--- + [U+0008 Backspace](https://en.wikipedia.org/wiki/Backspace) | `\b` + [U+000C Form Feed](https://en.wikipedia.org/wiki/Form_feed) | `\f` + [U+000A Line Feed](https://en.wikipedia.org/wiki/Newline) | `\n` + [U+000D Carriage Return](https://en.wikipedia.org/wiki/Carriage_return) | `\r` + [U+0009 Horizontal Tabulation](https://en.wikipedia.org/wiki/Tab_character) | `\t` + [U+000B Vertical Tabulation](https://en.wikipedia.org/wiki/Vertical_Tab) | `\v` + +It also inserts a backslash (`\`) before any backslash or a double quote (`"`). +Additionally all characters in the range 0x01-0x1F (everything below SPACE) and in the range 0x7F-0xFF (all non-ASCII chars) are -replaced with a '\' followed by their octal representation. +replaced with a backslash followed by their octal representation. Characters supplied in @exceptions are not escaped. [func@GLib.strcompress] does the reverse conversion. @@ -56984,7 +57281,7 @@ After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays). -See [memory management of sources][mainloop-memory-management] for details +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 to have a timer in the "seconds" range and do not care @@ -57036,7 +57333,7 @@ After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given interval (it does not try to 'catch up' time lost in delays). -See [memory management of sources][mainloop-memory-management] for details +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() @@ -57123,7 +57420,7 @@ 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. -See [memory management of sources][mainloop-memory-management] for details +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 @@ -57167,7 +57464,7 @@ event sources. Thus they should not be relied on for precise timing. After each call to the timeout function, the time of the next timeout is recalculated based on the current time and the given @interval -See [memory management of sources][mainloop-memory-management] for details +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() @@ -57572,43 +57869,79 @@ to UTF-8. The result will be terminated with a 0 byte. - + + Performs a checked addition of @a and @b, storing the result in +@dest. + +If the operation is successful, %TRUE is returned. If the operation +overflows then the state of @dest is undefined and %FALSE is +returned. + a pointer to the #guint64 destination + the #guint64 left operand + the #guint64 right operand - + + Performs a checked multiplication of @a and @b, storing the result in +@dest. + +If the operation is successful, %TRUE is returned. If the operation +overflows then the state of @dest is undefined and %FALSE is +returned. + a pointer to the #guint64 destination + the #guint64 left operand + the #guint64 right operand - + + Performs a checked addition of @a and @b, storing the result in +@dest. + +If the operation is successful, %TRUE is returned. If the operation +overflows then the state of @dest is undefined and %FALSE is +returned. + a pointer to the #guint destination + the #guint left operand + the #guint right operand - + + Performs a checked multiplication of @a and @b, storing the result in +@dest. + +If the operation is successful, %TRUE is returned. If the operation +overflows then the state of @dest is undefined and %FALSE is +returned. + a pointer to the #guint destination + the #guint left operand + the #guint right operand diff --git a/GObject-2.0.gir b/GObject-2.0.gir index 5a192749..ae30e87f 100644 --- a/GObject-2.0.gir +++ b/GObject-2.0.gir @@ -7778,7 +7778,7 @@ g_signal_connect (text_view->buffer, "notify::paste-target-list", ]| It is important to note that you must use -[canonical parameter names][canonical-parameter-names] as +[canonical parameter names][class@GObject.ParamSpec#parameter-names] as detail strings for the notify signal. @@ -8656,9 +8656,9 @@ efficient, and is the ‘canonical form’. Using `_` is discouraged.< Creates a new #GParamSpec instance. -See [canonical parameter names][canonical-parameter-names] for details of -the rules for @name. Names which violate these rules lead to undefined -behaviour. +See [canonical parameter names][class@GObject.ParamSpec#parameter-names] +for details of the rules for @name. Names which violate these rules lead +to undefined behaviour. Beyond the name, #GParamSpecs have two more descriptive strings, the @nick and @blurb, which may be used as a localized label and description. @@ -8699,8 +8699,8 @@ surrounding code and supporting libraries. dynamically-generated properties which need to be validated at run-time before actually trying to create them. -See [canonical parameter names][canonical-parameter-names] for details of -the rules for valid names. +See [canonical parameter names][class@GObject.ParamSpec#parameter-names] +for details of the rules for valid names. %TRUE if @name is a valid property name, %FALSE otherwise. @@ -17780,9 +17780,8 @@ of building the arguments. Validate a signal name. This can be useful for dynamically-generated signals which need to be validated at run-time before actually trying to create them. -See [canonical parameter names][canonical-parameter-names] for details of -the rules for valid names. The rules for signal names are the same as those -for property names. +See [func@GObject.signal_new] for details of the rules for valid names. +The rules for signal names are the same as those for property names. %TRUE if @name is a valid signal name, %FALSE otherwise. diff --git a/Gdk-4.0.gir b/Gdk-4.0.gir index 2f4e355a..9f8c38a3 100644 --- a/Gdk-4.0.gir +++ b/Gdk-4.0.gir @@ -487,9 +487,6 @@ even on a local clipboard. In this case the clipboard is empty. Asynchronously requests an input stream to read the @clipboard's contents from. -When the operation is finished @callback will be called. You must then -call [method@Gdk.Clipboard.read_finish] to get the result of the operation. - The clipboard will choose the most suitable mime type from the given list to fulfill the request, preferring the ones listed first. @@ -551,9 +548,6 @@ See [method@Gdk.Clipboard.read_async]. Asynchronously request the @clipboard contents converted to a string. -When the operation is finished @callback will be called. You must then -call [method@Gdk.Clipboard.read_text_finish] to get the result. - This is a simple wrapper around [method@Gdk.Clipboard.read_value_async]. Use that function or [method@Gdk.Clipboard.read_async] directly if you need more control over the operation. @@ -601,9 +595,6 @@ See [method@Gdk.Clipboard.read_text_async]. Asynchronously request the @clipboard contents converted to a `GdkPixbuf`. -When the operation is finished @callback will be called. You must then -call [method@Gdk.Clipboard.read_texture_finish] to get the result. - This is a simple wrapper around [method@Gdk.Clipboard.read_value_async]. Use that function or [method@Gdk.Clipboard.read_async] directly if you need more control over the operation. @@ -652,9 +643,6 @@ See [method@Gdk.Clipboard.read_texture_async]. Asynchronously request the @clipboard contents converted to the given @type. -When the operation is finished @callback will be called. You must then call -[method@Gdk.Clipboard.read_value_finish] to get the resulting `GValue`. - For local clipboard contents that are available in the given `GType`, the value will be copied directly. Otherwise, GDK will try to use [func@content_deserialize_async] to convert the clipboard's data. @@ -839,8 +827,6 @@ transfer the contents and then request that format from @provider. If the clipboard is not local, this function does nothing but report success. -The @callback must call [method@Gdk.Clipboard.store_finish]. - The purpose of this call is to preserve clipboard contents beyond the lifetime of an application, so this function is typically called on exit. Depending on the platform, the functionality may not be available @@ -1805,10 +1791,6 @@ This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].< Asynchronously writes the contents of @provider to @stream in the given @mime_type. -When the operation is finished @callback will be called. You must then call -[method@Gdk.ContentProvider.write_mime_type_finish] to get the result -of the operation. - The given mime type does not need to be listed in the formats returned by [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is not supported, `G_IO_ERROR_NOT_SUPPORTED` will be reported. @@ -1941,10 +1923,6 @@ This can be assumed to be a subset of [method@Gdk.ContentProvider.ref_formats].< Asynchronously writes the contents of @provider to @stream in the given @mime_type. -When the operation is finished @callback will be called. You must then call -[method@Gdk.ContentProvider.write_mime_type_finish] to get the result -of the operation. - The given mime type does not need to be listed in the formats returned by [method@Gdk.ContentProvider.ref_formats]. However, if the given `GType` is not supported, `G_IO_ERROR_NOT_SUPPORTED` will be reported. @@ -5848,10 +5826,6 @@ See [method@Gdk.Drop.read_async]. Asynchronously request the drag operation's contents converted to the given @type. -When the operation is finished @callback will be called. You must -then call [method@Gdk.Drop.read_value_finish] to get the resulting -`GValue`. - For local drag-and-drop operations that are available in the given `GType`, the value will be copied directly. Otherwise, GDK will try to use [func@Gdk.content_deserialize_async] to convert the data. @@ -20248,10 +20222,7 @@ so that the origin of @pixbuf is @pixbuf_x, @pixbuf_y. Read content from the given input stream and deserialize it, asynchronously. The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers -indicate a higher priority. - -When the operation is finished, @callback will be called. You must then -call [func@Gdk.content_deserialize_finish] to get the result of the operation. +indicate a higher priority. @@ -20385,10 +20356,7 @@ is returned. Serialize content and write it to the given output stream, asynchronously. The default I/O priority is %G_PRIORITY_DEFAULT (i.e. 0), and lower numbers -indicate a higher priority. - -When the operation is finished, @callback will be called. You must then -call [func@Gdk.content_serialize_finish] to get the result of the operation. +indicate a higher priority. diff --git a/GdkPixbuf-2.0.gir b/GdkPixbuf-2.0.gir index ca41e6ca..a3926b18 100644 --- a/GdkPixbuf-2.0.gir +++ b/GdkPixbuf-2.0.gir @@ -316,7 +316,7 @@ interpolation is just as fast and results in higher quality. "0.8.2" for example. - + Micro version of gdk-pixbuf library, that is the "2" in "0.8.2" for example. @@ -344,7 +344,7 @@ interpolation is just as fast and results in higher quality. - + Contains the full version of GdkPixbuf as a string. This is the version being compiled against; contrast with diff --git a/Gtk-4.0.gir b/Gtk-4.0.gir index 62b0d7ef..c84d7424 100644 --- a/Gtk-4.0.gir +++ b/Gtk-4.0.gir @@ -4301,8 +4301,7 @@ covered by the [signal@Gtk.Adjustment::value-changed] signal. are needed to present a message to the user. The message is shown with the [method@Gtk.AlertDialog.choose] -function. This API follows the GIO async pattern, and the result can -be obtained by calling [method@Gtk.AlertDialog.choose_finish]. +function. If you don't need to wait for a button to be clicked, you can use [method@Gtk.AlertDialog.show]. @@ -4329,10 +4328,6 @@ resulting from the arguments. This function shows the alert to the user. -The @callback will be called when the alert is dismissed. -It should call [method@Gtk.AlertDialog.choose_finish] -to obtain the result. - It is ok to pass `NULL` for the callback if the alert does not have more than one button. A simpler API for this case is [method@Gtk.AlertDialog.show]. @@ -7452,7 +7447,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. @@ -11858,7 +11853,7 @@ If none of these choices are appropriate, simply use > Please note that %GTK_BUTTONS_OK, %GTK_BUTTONS_YES_NO > and %GTK_BUTTONS_OK_CANCEL are discouraged by the -> [GNOME Human Interface Guidelines](http://library.gnome.org/devel/hig-book/stable/). +> [GNOME Human Interface Guidelines](https://developer.gnome.org/hig/). no buttons at all @@ -21149,9 +21144,7 @@ user, such as a title for the dialog and whether it should be modal. The dialog is shown with the [method@Gtk.ColorDialog.choose_rgba] -function. This API follows the GIO async pattern, and the -result can be obtained by calling -[method@Gtk.ColorDialog.choose_rgba_finish]. +function. See [class@Gtk.ColorDialogButton] for a convenient control that uses `GtkColorDialog` and presents the results. @@ -21164,11 +21157,7 @@ that uses `GtkColorDialog` and presents the results. This function initiates a color choice operation by -presenting a color chooser dialog to the user. - -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.ColorDialog.choose_rgba_finish] -to obtain the result. +presenting a color chooser dialog to the user. @@ -21812,7 +21801,8 @@ If it isn't, then the changes will take effect once that happens. - position of the item + position of the item. Must be less than the number of + items in the view. @@ -25816,6 +25806,9 @@ of this @provider. Signals that a parsing error occurred. +The expected error values are in the [error@Gtk.CssParserError] +and [enum@Gtk.CssParserWarning] enumerations. + The @path, @line and @position describe the actual location of the error as accurately as possible. @@ -25824,6 +25817,9 @@ the error. Errors may however cause parts of the given data or even all of it to not be parsed at all. So it is a useful idea to check that the parsing succeeds by connecting to this signal. +Errors in the [enum@Gtk.CssParserWarning] enumeration should not +be treated as fatal errors. + Note that this signal may be emitted at any time as the css provider may opt to defer parsing parts or all of the input to a later time than when a loading function was called. @@ -25872,6 +25868,47 @@ in the given `file` from the `start` location to the + + Creates a new `GtkCssSection` referring to the section +in the given `file` or the given `bytes` from the `start` location to the +`end` location. + + a new `GtkCssSection` + + + + + The file this section refers to + + + + The bytes this sections refers to + + + + The start location + + + + The end location + + + + + + Gets the bytes that @section was parsed from. + + the `GBytes` from which the `section` + was parsed + + + + + the section + + + + Returns the location in the CSS document where this section ends. @@ -26441,6 +26478,9 @@ only available when GTK has been configured with `-Ddebug=true`. Inverts the default text-direction. + + Information about deprecated CSS features. + Passed to various keybinding signals for deleting text. @@ -37099,10 +37139,7 @@ user, such as a title for the dialog and whether it should be modal. The dialog is shown with [method@Gtk.FileDialog.open], -[method@Gtk.FileDialog.save], etc. These APIs follow the -GIO async pattern, and the result can be obtained by calling -the corresponding finish function, for example -[method@Gtk.FileDialog.open_finish]. +[method@Gtk.FileDialog.save], etc. Creates a new `GtkFileDialog` object. @@ -37225,9 +37262,7 @@ file chooser dialog. This function initiates a file selection operation by presenting a file chooser dialog to the user. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.open_finish] -to obtain the result. +The @callback will be called when the dialog is dismissed. @@ -37280,9 +37315,7 @@ presenting a file chooser dialog to the user. The file chooser will initially be opened in the directory [property@Gtk.FileDialog:initial-folder]. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.open_multiple_finish] -to obtain the result. +The @callback will be called when the dialog is dismissed. @@ -37333,9 +37366,7 @@ returns the resulting files in a `GListModel`. This function initiates a file save operation by presenting a file chooser dialog to the user. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.save_finish] -to obtain the result. +The @callback will be called when the dialog is dismissed. @@ -37389,9 +37420,7 @@ If you pass @initial_folder, the file chooser will initially be opened in the parent directory of that folder, otherwise, it will be in the directory [property@Gtk.FileDialog:initial-folder]. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.select_folder_finish] -to obtain the result. +The @callback will be called when the dialog is dismissed. @@ -37444,9 +37473,7 @@ presenting a file chooser dialog to the user. The file chooser will initially be opened in the directory [property@Gtk.FileDialog:initial-folder]. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FileDialog.select_multiple_folders_finish] -to obtain the result. +The @callback will be called when the dialog is dismissed. @@ -37979,8 +38006,6 @@ may or may not show an app chooser dialog or launch the default application right away. The operation is started with the [method@Gtk.FileLauncher.launch] function. -This API follows the GIO async pattern, and the result can be obtained by -calling [method@Gtk.FileLauncher.launch_finish]. To launch uris that don't represent files, use [class@Gtk.UriLauncher]. @@ -38038,11 +38063,7 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. Launch an application to open the file. -This may present an app chooser dialog to the user. - -The @callback will be called when the operation is completed. -It should call [method@Gtk.FileLauncher.launch_finish] to obtain -the result. +This may present an app chooser dialog to the user. @@ -38092,11 +38113,7 @@ returns the result. Launch a file manager to show the file in its parent directory. This is only supported native files. It will fail if @file -is e.g. a http:// uri. - -The @callback will be called when the operation is completed. -It should call [method@Gtk.FileLauncher.open_containing_folder_finish] -to obtain the result. +is e.g. a http:// uri. @@ -41308,9 +41325,7 @@ user, such as a title for the dialog and whether it should be modal. The dialog is shown with the [method@Gtk.FontDialog.choose_font] -function or its variants. This API follows the GIO async pattern, -and the result can be obtained by calling the corresponding -finish function, such as [method@Gtk.FontDialog.choose_font_finish]. +function or its variants. See [class@Gtk.FontDialogButton] for a convenient control that uses `GtkFontDialog` and presents the results. @@ -41324,11 +41339,7 @@ that uses `GtkFontDialog` and presents the results. This function initiates a font selection operation by presenting a dialog to the user for selecting a font face -(i.e. a font family and style, but not a specific font size). - -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FontDialog.choose_face_finish] -to obtain the result. +(i.e. a font family and style, but not a specific font size). @@ -41379,11 +41390,7 @@ and returns the resulting font face. This function initiates a font selection operation by -presenting a dialog to the user for selecting a font family. - -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FontDialog.choose_family_finish] -to obtain the result. +presenting a dialog to the user for selecting a font family. @@ -41440,10 +41447,6 @@ to [method@Gtk.FontDialog.choose_family] is returned. This function initiates a font selection operation by presenting a dialog to the user for selecting a font. -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FontDialog.choose_font_finish] -to obtain the result. - If you want to let the user select font features as well, use [method@Gtk.FontDialog.choose_font_and_features] instead. @@ -41482,11 +41485,7 @@ presenting a dialog to the user for selecting a font and font features. Font features affect how the font is rendered, for example -enabling glyph variants or ligatures. - -The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.FontDialog.choose_font_and_features_finish] -to obtain the result. +enabling glyph variants or ligatures. @@ -46298,7 +46297,8 @@ If it isn't, then the changes will take effect once that happens. - position of the item + position of the item. Must be less than the number of + items in the view. @@ -59563,7 +59563,8 @@ If it isn't, then the changes will take effect once that happens. - position of the item + position of the item. Must be less than the number of + items in the view. @@ -59915,7 +59916,7 @@ against at application run time. - + 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. @@ -69738,7 +69739,7 @@ it is presented. Returns the page setup. - + the page setup @@ -69751,7 +69752,7 @@ it is presented. Returns the print settings for the print dialog. - + the settings @@ -69782,8 +69783,7 @@ print dialog. If you pass `NULL` as @setup, then this method will present a print dialog. Otherwise, it will attempt to print directly, without user interaction. -The @callback will be called when the printing is done. It should call -[method@Gtk.PrintDialog.print_finish] to obtain the results. +The @callback will be called when the printing is done. @@ -69818,10 +69818,7 @@ The @callback will be called when the printing is done. It should call This function prints a file. If you pass `NULL` as @setup, then this method will present a print dialog. -Otherwise, it will attempt to print directly, without user interaction. - -The @callback will be called when the printing is done. It should call -[method@Gtk.PrintDialog.print_file_finish] to obtain the results. +Otherwise, it will attempt to print directly, without user interaction. @@ -69887,7 +69884,7 @@ results, you need to explicitly close the output stream (it will be closed automatically if you just unref it). Be aware that the close call may not be instant as it operation will for the printer to finish printing. - + a [class@Gio.OutputStream] @@ -69991,10 +69988,8 @@ it is presented. and set up print settings and page setup. The @callback will be called when the dialog is dismissed. -It should call [method@Gtk.PrintDialog.setup_finish] -to obtain the results in the form of a [struct@Gtk.PrintSetup], -that can then be passed to [method@Gtk.PrintDialog.print] -or [method@Gtk.PrintDialog.print_file]. +The obtained [struct@Gtk.PrintSetup] can then be passed +to [method@Gtk.PrintDialog.print] or [method@Gtk.PrintDialog.print_file]. One possible use for this method is to have the user select a printer, then show a page setup UI in the application (e.g. to arrange images @@ -70032,7 +70027,7 @@ to do the printing without further user interaction. If the call was successful, it returns a [struct@Gtk.PrintSetup] which contains the print settings and page setup information that will be used to print. - + The `GtkPrintSetup` object that resulted from the call, or `NULL` if the call was not successful @@ -73965,7 +73960,7 @@ and copy them to the PrintDialog if they want to keep using them. It may be different from the `GtkPrintDialog`'s page setup if the user changed it during the setup process. - + the page setup, or `NULL` @@ -73981,7 +73976,7 @@ if the user changed it during the setup process. They may be different from the `GtkPrintDialog`'s settings if the user changed them during the setup process. - + the print settings, or `NULL` @@ -109914,8 +109909,6 @@ may or may not show an app chooser dialog or launch the default application right away. The operation is started with the [method@Gtk.UriLauncher.launch] function. -This API follows the GIO async pattern, and the result can be obtained by -calling [method@Gtk.UriLauncher.launch_finish]. To launch a file, use [class@Gtk.FileLauncher]. @@ -109947,11 +109940,7 @@ To launch a file, use [class@Gtk.FileLauncher]. Launch an application to open the uri. -This may present an app chooser dialog to the user. - -The @callback will be called when the operation is completed. -It should call [method@Gtk.UriLauncher.launch_finish] to obtain -the result. +This may present an app chooser dialog to the user. @@ -120294,7 +120283,6 @@ a given uri, or shows an error dialog if that fails. a given uri. The @callback will be called when the launch is completed. -It should call gtk_show_uri_full_finish() to obtain the result. This is the recommended call to be used as it passes information necessary for sandbox helpers to parent their dialogs properly. @@ -120333,8 +120321,8 @@ necessary for sandbox helpers to parent their dialogs properly. Finishes the gtk_show_uri() call and returns the result of the operation. - Use [method@Gtk.FileLauncher.launch_finish] or - [method@Gtk.UriLauncher.launch_finish] instead + Use [method@Gtk.FileLauncher.launch] or + [method@Gtk.UriLauncher.launch] instead %TRUE if the URI was shown successfully. Otherwise, %FALSE is returned and @error is set diff --git a/Pango-1.0.gir b/Pango-1.0.gir index 9bfdfb0e..dec9adc0 100644 --- a/Pango-1.0.gir +++ b/Pango-1.0.gir @@ -6768,6 +6768,25 @@ the iter to each call. + + Returns the character offset of the item from the beginning +of the itemized text. + +If the item has not been obtained from Pango's itemization +machinery, then the character offset is not available. In +that case, this function returns -1. + + the character offset of the item from the beginning + of the itemized text, or -1 + + + + + a `PangoItem` + + + + Modifies @orig to cover only the text after @split_index, and returns a new item that covers the text before @split_index that @@ -12145,15 +12164,15 @@ Two encoded version numbers can be compared as integers. The major component of the version of Pango available at compile-time. - + The micro component of the version of Pango available at compile-time. - + The minor component of the version of Pango available at compile-time. - + A string literal containing the version of Pango available at compile-time.