From f7dbcbed302aaab7dc56300d90f5934ff3ec00af Mon Sep 17 00:00:00 2001 From: sdroege <301846+sdroege@users.noreply.github.com> Date: Sun, 24 Nov 2024 01:27:37 +0000 Subject: [PATCH] Update GIR files --- GLib-2.0.gir | 1001 ++++++++------- Gdk-4.0.gir | 17 +- Gtk-4.0.gir | 3288 +++++++++++++++++++++++++------------------------- 3 files changed, 2196 insertions(+), 2110 deletions(-) diff --git a/GLib-2.0.gir b/GLib-2.0.gir index a25f65ab..946d46c1 100644 --- a/GLib-2.0.gir +++ b/GLib-2.0.gir @@ -30074,29 +30074,31 @@ g_strfreev (array); A value that can be passed as an option to [func@GLib.test_init]. -Creates a unique temporary directory for each unit test and uses -g_set_user_dirs() to set XDG directories to point into subdirectories of it -for the duration of the unit test. The directory tree is cleaned up after the -test finishes successfully. Note that this doesn’t take effect until -g_test_run() is called, so calls to (for example) g_get_user_home_dir() will -return the system-wide value when made in a test program’s main() function. +Creates a unique temporary directory for each unit test and uses sets +XDG directories to point into subdirectories of it for the duration of +the unit test. The directory tree is cleaned up after the test finishes +successfully. + +Note that this doesn’t take effect until [func@GLib.test_run] is called, +so calls to (for example) [func@GLib.get_home_dir] will return the +system-wide value when made in a test program’s main() function. The following functions will return subdirectories of the temporary directory when this option is used. The specific subdirectory paths in use are not guaranteed to be stable API — always use a getter function to retrieve them. - - g_get_home_dir() - - g_get_user_cache_dir() - - g_get_system_config_dirs() - - g_get_user_config_dir() - - g_get_system_data_dirs() - - g_get_user_data_dir() - - g_get_user_state_dir() - - g_get_user_runtime_dir() + - [func@GLib.get_home_dir] + - [func@GLib.get_user_cache_dir] + - [func@GLib.get_system_config_dirs] + - [func@GLib.get_user_config_dir] + - [func@GLib.get_system_data_dirs] + - [func@GLib.get_user_data_dir] + - [func@GLib.get_user_state_dir] + - [func@GLib.get_user_runtime_dir] The subdirectories may not be created by the test harness; as with normal -calls to functions like g_get_user_cache_dir(), the caller must be prepared -to create the directory if it doesn’t exist. +calls to functions like [func@GLib.get_user_cache_dir], the caller must +be prepared to create the directory if it doesn’t exist. @@ -30150,7 +30152,7 @@ If this option is given, [func@GLib.test_init] will not call [func@GLib.set_prgn - a #GTestCase + a test case @@ -30191,21 +30193,22 @@ argument. The type of file to return the filename for, when used with -g_test_build_filename(). +[func@GLib.test_build_filename]. These two options correspond rather directly to the 'dist' and 'built' terminology that automake uses and are explicitly used to -distinguish between the 'srcdir' and 'builddir' being separate. All -files in your project should either be dist (in the -`EXTRA_DIST` or `dist_schema_DATA` -sense, in which case they will always be in the srcdir) or built (in -the `BUILT_SOURCES` sense, in which case they will -always be in the builddir). - -Note: as a general rule of automake, files that are generated only as +distinguish between the 'srcdir' and 'builddir' being separate. All +files in your project should either be dist (in the `EXTRA_DIST` or +`dist_schema_DATA` sense, in which case they will always be in the +srcdir) or built (in the `BUILT_SOURCES` sense, in which case they +will always be in the builddir). + +Note: As a general rule of automake, files that are generated only as part of the build-from-git process (but then are distributed with the tarball) always go in srcdir (even if doing a srcdir != builddir -build from git) and are considered as distributed files. +build from git) and are considered as distributed files. + +The same principles apply for other build systems, such as meson. a file that was included in the distribution tarball @@ -30214,12 +30217,13 @@ build from git) and are considered as distributed files. - The type used for functions that operate on test fixtures. This is -used for the fixture setup and teardown functions as well as for the -testcases themselves. + The type used for functions that operate on test fixtures. -@user_data is a pointer to the data that was given when registering -the test case. +This is used for the fixture setup and teardown functions +as well as for the testcases themselves. + +@user_data is a pointer to the data that was given when +registering the test case. @fixture will be a pointer to the area of memory allocated by the test framework, of the size requested. If the requested size was @@ -30389,29 +30393,30 @@ zero then @fixture will be equal to @user_data. - Flags to pass to g_test_trap_subprocess() to control input and output. + Flags to pass to [func@GLib.test_trap_subprocess] to control input and output. -Note that in contrast with g_test_trap_fork(), the default is to -not show stdout and stderr. +Note that in contrast with [func@GLib.test_trap_fork], the default +behavior of [func@GLib.test_trap_subprocess] is to not show stdout +and stderr. Default behaviour. Since: 2.74 If this flag is given, the child - process will inherit the parent's stdin. Otherwise, the child's - stdin is redirected to `/dev/null`. + process will inherit the parent's stdin. Otherwise, the child's + stdin is redirected to `/dev/null`. If this flag is given, the child - process will inherit the parent's stdout. Otherwise, the child's - stdout will not be visible, but it will be captured to allow - later tests with g_test_trap_assert_stdout(). + process will inherit the parent's stdout. Otherwise, the child's + stdout will not be visible, but it will be captured to allow + later tests with [func@GLib.test_trap_assert_stdout]. If this flag is given, the child - process will inherit the parent's stderr. Otherwise, the child's - stderr will not be visible, but it will be captured to allow - later tests with g_test_trap_assert_stderr(). + process will inherit the parent's stderr. Otherwise, the child's + stderr will not be visible, but it will be captured to allow + later tests with [func@GLib.test_trap_assert_stderr]. @@ -30423,11 +30428,11 @@ not show stdout and stderr. - a #GTestSuite + a test suite - a #GTestCase + a test case @@ -30439,34 +30444,35 @@ not show stdout and stderr. - a #GTestSuite + a test suite - another #GTestSuite + another test suite - Free the @suite and all nested #GTestSuites. + Frees the @suite and all nested suites. - a #GTestSuite + a test suite - Test traps are guards around forked tests. -These flags determine what traps to set. - #GTestTrapFlags is used only with g_test_trap_fork(), -which is deprecated. g_test_trap_subprocess() uses -#GTestSubprocessFlags. + Flags to pass to [func@GLib.test_trap_fork] to control input and output. + +Test traps are guards around forked tests. These flags determine what traps to set. + `GTestTrapFlags` is used only with [func@GLib.test_trap_fork], + which is deprecated. Its replacement, [func@GLib.test_trap_subprocess] uses + [flags@GLib.TestSubprocessFlags]. Default behaviour. Since: 2.74 @@ -41442,15 +41448,17 @@ there's no worry about sign extension if characters are signed. Debugging macro to terminate the application if the assertion -fails. If the assertion fails (i.e. the expression is not true), +fails. + +If the assertion fails (i.e. the expression is not true), an error message is logged and the application is terminated. The macro can be turned off in final releases of code by defining -`G_DISABLE_ASSERT` when compiling the application, so code must -not depend on any side effects from @expr. Similarly, it must not be used -in unit tests, otherwise the unit tests will be ineffective if compiled with -`G_DISABLE_ASSERT`. Use g_assert_true() and related macros in unit tests -instead. +`G_DISABLE_ASSERT` when compiling the application, so code must not +depend on any side effects from @expr. Similarly, it must not be used +in unit tests, otherwise the unit tests will be ineffective if compiled +with `G_DISABLE_ASSERT`. Use [func@GLib.assert_true] and related macros +in unit tests instead. the expression to check @@ -41460,17 +41468,17 @@ instead. Debugging macro to compare two floating point numbers. -The effect of `g_assert_cmpfloat (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. +The effect of `g_assert_cmpfloat (n1, op, n2)` is the same as +`g_assert_true (n1 op n2)`. The advantage of this macro is +that it can produce a message that includes the actual values +of @n1 and @n2. a floating point number - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another floating point number @@ -41500,15 +41508,15 @@ actual values of @n1 and @n2. Debugging macro to compare to unsigned integers. -This is a variant of g_assert_cmpuint() that displays the numbers -in hexadecimal notation in the message. +This is a variant of [func@GLib.assert_cmpuint] that displays +the numbers in hexadecimal notation in the message. an unsigned integer - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another unsigned integer @@ -41518,17 +41526,17 @@ in hexadecimal notation in the message. Debugging macro to compare two integers. -The effect of `g_assert_cmpint (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. +The effect of `g_assert_cmpint (n1, op, n2)` is the same as +`g_assert_true (n1 op n2)`. The advantage of this macro is +that it can produce a message that includes the actual values +of @n1 and @n2. an integer - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another integer @@ -41536,101 +41544,105 @@ actual values of @n1 and @n2. - Debugging macro to compare memory regions. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. + Debugging macro to compare memory regions. -The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is -the same as `g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`. -The advantage of this macro is that it can produce a message that -includes the actual values of @l1 and @l2. +If the comparison fails, an error message is logged and the +application is either terminated or the testcase marked as failed. -@m1 may be %NULL if (and only if) @l1 is zero; similarly for @m2 and @l2. +The effect of `g_assert_cmpmem (m1, l1, m2, l2)` is the same as +`g_assert_true (l1 == l2 && memcmp (m1, m2, l1) == 0)`. The advantage +of this macro is that it can produce a message that includes the actual +values of @l1 and @l2. -|[<!-- language="C" --> +@m1 may be `NULL` if (and only if) @l1 is zero; similarly for @m2 and @l2. + +```c g_assert_cmpmem (buf->data, buf->len, expected, sizeof (expected)); -]| +``` pointer to a buffer - length of @m1 + length of @m1 in bytes pointer to another buffer - length of @m2 + length of @m2 in bytes - Debugging macro to compare two strings. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. -The strings are compared using g_strcmp0(). + Debugging macro to compare two strings. -The effect of `g_assert_cmpstr (s1, op, s2)` is -the same as `g_assert_true (g_strcmp0 (s1, s2) op 0)`. -The advantage of this macro is that it can produce a message that -includes the actual values of @s1 and @s2. +If the comparison fails, an error message is logged and the +application is either terminated or the testcase marked as failed. +The strings are compared using [GLib.strcmp0]. -|[<!-- language="C" --> +The effect of `g_assert_cmpstr (s1, op, s2)` is the same as +`g_assert_true (g_strcmp0 (s1, s2) op 0)`. The advantage of this +macro is that it can produce a message that includes the actual +values of @s1 and @s2. + +```c g_assert_cmpstr (mystring, ==, "fubar"); -]| +``` - a string (may be %NULL) + a string - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` - another string (may be %NULL) + another string - Debugging macro to check if two %NULL-terminated string arrays (i.e. 2 -#GStrv) are equal. If they are not equal, an error message is logged and the -application is either terminated or the testcase marked as failed. -If both arrays are %NULL, the check passes. If one array is %NULL but the -other is not, an error message is logged. + Debugging macro to check if two `NULL`-terminated string arrays (i.e. 2 +`GStrv`) are equal. + +If they are not equal, an error message is logged and the application is +either terminated or the testcase marked as failed. If both arrays are +`NULL`, the check passes. If one array is `NULL` but the other is not, +an error message is logged. The effect of `g_assert_cmpstrv (strv1, strv2)` is the same as `g_assert_true (g_strv_equal (strv1, strv2))` (if both arrays are not -%NULL). The advantage of this macro is that it can produce a message that +`NULL`). The advantage of this macro is that it can produce a message that includes how @strv1 and @strv2 are different. -|[<!-- language="C" --> +```c const char *expected[] = { "one", "two", "three", NULL }; g_assert_cmpstrv (mystrv, expected); -]| +``` - a string array (may be %NULL) + a string array - another string array (may be %NULL) + another string array Debugging macro to compare two unsigned integers. -The effect of `g_assert_cmpuint (n1, op, n2)` is -the same as `g_assert_true (n1 op n2)`. The advantage -of this macro is that it can produce a message that includes the -actual values of @n1 and @n2. +The effect of `g_assert_cmpuint (n1, op, n2)` is the same as +`g_assert_true (n1 op n2)`. The advantage of this macro is +that it can produce a message that includes the actual values +of @n1 and @n2. an unsigned integer - The comparison operator to use. - One of `==`, `!=`, `<`, `>`, `<=`, `>=`. + the comparison operator to use. + One of `==`, `!=`, `<`, `>`, `<=`, `>=` another unsigned integer @@ -41638,42 +41650,43 @@ actual values of @n1 and @n2. - Debugging macro to compare two #GVariants. If the comparison fails, -an error message is logged and the application is either terminated -or the testcase marked as failed. The variants are compared using -g_variant_equal(). + Debugging macro to compare two [struct@GLib.Variant] values. + +If the comparison fails, an error message is logged and the +application is either terminated or the testcase marked as failed. +The variants are compared using [method@GLib.Variant.equal]. The effect of `g_assert_cmpvariant (v1, v2)` is the same as -`g_assert_true (g_variant_equal (v1, v2))`. The advantage of this macro is -that it can produce a message that includes the actual values of @v1 and @v2. +`g_assert_true (g_variant_equal (v1, v2))`. The advantage of +this macro is that it can produce a message that includes the +actual values of @v1 and @v2. - pointer to a #GVariant + pointer to a `GVariant` - pointer to another #GVariant + pointer to another `GVariant` Debugging macro to check that a method has returned -the correct #GError. +the correct [struct@GLib.Error]. -The effect of `g_assert_error (err, dom, c)` is -the same as `g_assert_true (err != NULL && err->domain -== dom && err->code == c)`. The advantage of this -macro is that it can produce a message that includes the incorrect -error message and code. +The effect of `g_assert_error (err, dom, c)` is the same as +`g_assert_true (err != NULL && err->domain == dom && err->code == c)`. +The advantage of this macro is that it can produce a message that +includes the incorrect error message and code. This can only be used to test for a specific error. If you want to test that @err is set, but don't care what it's set to, just use `g_assert_nonnull (err)`. - a #GError, possibly %NULL + a `GError` - the expected error domain (a #GQuark) + the expected error domain (a `GQuark`) the expected error code @@ -41687,11 +41700,11 @@ If the assertion fails (i.e. the expression is not false), an error message is logged and the application is either terminated or the testcase marked as failed. -Note that unlike g_assert(), this macro is unaffected by whether +Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. +conversely, [func@GLib.assert] should not be used in tests. -See g_test_set_nonfatal_assertions(). +See [func@GLib.test_set_nonfatal_assertions]. the expression to check @@ -41706,7 +41719,7 @@ success. If the assertion fails (i.e. the @expr returns a negative value), an error message is logged and the testcase is marked as failed. The error message will contain the value of `errno` and its human-readable message from -g_strerror(). +[func@GLib.strerror]. This macro will clear the value of `errno` before executing @expr. @@ -41716,30 +41729,30 @@ This macro will clear the value of `errno` before executing @expr. - Debugging macro to check that a #GError is not set. + Debugging macro to check that a [struct@GLib.Error] is not set. -The effect of `g_assert_no_error (err)` is -the same as `g_assert_true (err == NULL)`. The advantage -of this macro is that it can produce a message that includes -the error message and code. +The effect of `g_assert_no_error (err)` is the same as +`g_assert_true (err == NULL)`. The advantage of this macro +is that it can produce a message that includes the error +message and code. - a #GError, possibly %NULL + a `GError` - Debugging macro to check an expression is not %NULL. + Debugging macro to check an expression is not `NULL`. -If the assertion fails (i.e. the expression is %NULL), +If the assertion fails (i.e. the expression is `NULL`), an error message is logged and the application is either terminated or the testcase marked as failed. -Note that unlike g_assert(), this macro is unaffected by whether +Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. +conversely, [func@GLib.assert] should not be used in tests. -See g_test_set_nonfatal_assertions(). +See [func@GLib.test_set_nonfatal_assertions]. the expression to check @@ -41747,26 +41760,27 @@ See g_test_set_nonfatal_assertions(). - Debugging macro to terminate the application if it is ever -reached. If it is reached, an error message is logged and the -application is terminated. + Debugging macro to terminate the application if it is ever reached. + +If it is reached, an error message is logged and the application +is terminated. The macro can be turned off in final releases of code by defining -`G_DISABLE_ASSERT` when compiling the application. Hence, it should not be -used in unit tests, where assertions should always be effective. +`G_DISABLE_ASSERT` when compiling the application. Hence, it should +not be used in unit tests, where assertions should always be effective. - Debugging macro to check an expression is %NULL. + Debugging macro to check an expression is `NULL`. -If the assertion fails (i.e. the expression is not %NULL), +If the assertion fails (i.e. the expression is not `NULL`), an error message is logged and the application is either terminated or the testcase marked as failed. -Note that unlike g_assert(), this macro is unaffected by whether +Note that unlike [func@GLib.assert], this macro is unaffected by whether `G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. +conversely, [func@GLib.assert] should not be used in tests. -See g_test_set_nonfatal_assertions(). +See [func@GLib.test_set_nonfatal_assertions]. the expression to check @@ -41780,11 +41794,12 @@ If the assertion fails (i.e. the expression is not true), an error message is logged and the application is either terminated or the testcase marked as failed. -Note that unlike g_assert(), this macro is unaffected by whether -`G_DISABLE_ASSERT` is defined. Hence it should only be used in tests and, -conversely, g_assert() should not be used in tests. +Note that unlike [func@GLib.assert], this macro is unaffected by +whether `G_DISABLE_ASSERT` is defined. Hence it should only be used +in tests and, conversely, [func@GLib.assert] should not be used +in tests. -See g_test_set_nonfatal_assertions(). +See [func@GLib.test_set_nonfatal_assertions]. the expression to check @@ -41997,8 +42012,8 @@ See g_test_set_nonfatal_assertions(). - Internal function used to print messages from the public g_assert() and -g_assert_not_reached() macros. + Internal function used to print messages from the public +g_assert() and g_assert_not_reached() macros. @@ -55514,20 +55529,22 @@ Also see [func@GLib.strchomp] and [func@GLib.strstrip]. - Compares @str1 and @str2 like strcmp(). Handles %NULL -gracefully by sorting it before non-%NULL strings. -Comparing two %NULL pointers returns 0. + Compares @str1 and @str2 like `strcmp()`. + +Handles `NULL` gracefully by sorting it before non-`NULL` strings. +Comparing two `NULL` pointers returns 0. - an integer less than, equal to, or greater than zero, if @str1 is <, == or > than @str2. + an integer less than, equal to, or greater than zero, + if @str1 is <, == or > than @str2 - a C string or %NULL + a string - another C string or %NULL + another string @@ -56352,114 +56369,124 @@ Two empty arrays are considered equal. Neither @strv1 nor @strv2 may be - Hook up a new test case at @testpath, similar to g_test_add_func(). -A fixture data structure with setup and teardown functions may be provided, -similar to g_test_create_case(). + Hooks up a new test case at @testpath. + +This function is similar to [func@GLib.test_add_func]. + +A fixture data structure with setup and teardown functions +may be provided, similar to [func@GLib.test_create_case]. -g_test_add() is implemented as a macro, so that the fsetup(), ftest() and -fteardown() callbacks can expect a @Fixture pointer as their first argument -in a type safe manner. They otherwise have type #GTestFixtureFunc. +`g_test_add()` is implemented as a macro, so that the @fsetup, +@ftest and @fteardown callbacks can expect a @Fixture pointer +as their first argument in a type safe manner. They otherwise +have type `GTestFixtureFunc`. - The test path for a new test case. + the test path for a new test case - The type of a fixture data structure. + the type of a fixture data structure - Data argument for the test functions. + data argument for the test functions - The function to set up the fixture data. + the function to set up the fixture data - The actual test function. + the actual test function - The function to tear down the fixture data. + the function to tear down the fixture data - Create a new test case, similar to g_test_create_case(). However -the test is assumed to use no fixture, and test suites are automatically -created on the fly and added to the root fixture, based on the -slash-separated portions of @testpath. The @test_data argument -will be passed as first argument to @test_func. + Creates a new test case. + +This function is similar to [func@GLib.test_create_case]. +However the test is assumed to use no fixture, and test suites are +automatically created on the fly and added to the root fixture, +based on the /-separated portions of @testpath. The @test_data +argument will be passed as first argument to @test_func. If @testpath includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly -required via the `-p` command-line option or g_test_trap_subprocess(). +required via the `-p` command-line option or [func@GLib.test_trap_subprocess]. No component of @testpath may start with a dot (`.`) if the -%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to -do so even if it isn’t. +[const@GLib.TEST_OPTION_ISOLATE_DIRS] option is being used; +and it is recommended to do so even if it isn’t. - /-separated test case path name for the test. + a /-separated name for the test - Test data argument for the test function. + data for the @test_func - The test function to invoke for this test. + the test function to invoke for this test - Create a new test case, as with g_test_add_data_func(), but freeing -@test_data after the test run is complete. + Creates a new test case. + +In constract to [func@GLib.test_add_data_func], this function +is freeing @test_data after the test run is complete. - /-separated test case path name for the test. + a /-separated name for the test - Test data argument for the test function. + data for @test_func - The test function to invoke for this test. + the test function to invoke for this test - #GDestroyNotify for @test_data. + #GDestroyNotify for @test_data - Create a new test case, similar to g_test_create_case(). However -the test is assumed to use no fixture, and test suites are automatically -created on the fly and added to the root fixture, based on the -slash-separated portions of @testpath. + Creates a new test case. + +This function is similar to [func@GLib.test_create_case]. +However the test is assumed to use no fixture, and test suites are +automatically created on the fly and added to the root fixture, +based on the /-separated portions of @testpath. If @testpath includes the component "subprocess" anywhere in it, the test will be skipped by default, and only run if explicitly -required via the `-p` command-line option or g_test_trap_subprocess(). +required via the `-p` command-line option or [func@GLib.test_trap_subprocess]. No component of @testpath may start with a dot (`.`) if the -%G_TEST_OPTION_ISOLATE_DIRS option is being used; and it is recommended to -do so even if it isn’t. +[const@GLib.TEST_OPTION_ISOLATE_DIRS] option is being used; and +it is recommended to do so even if it isn’t. - /-separated test case path name for the test. + a /-separated name for the test - The test function to invoke for this test. + the test function to invoke for this test @@ -56520,18 +56547,17 @@ expected via [func@GLib.test_expect_message] then they will be ignored. - This function adds a message to test reports that -associates a bug URI with a test case. + Adds a message to test reports that associates a bug URI with a test case. -Bug URIs are constructed from a base URI set with g_test_bug_base() -and @bug_uri_snippet. If g_test_bug_base() has not been called, it is +Bug URIs are constructed from a base URI set with [func@GLib.test_bug_base] +and @bug_uri_snippet. If [func@GLib.test_bug_base] has not been called, it is assumed to be the empty string, so a full URI can be provided to -g_test_bug() instead. +[func@GLib.test_bug] instead. -Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet if it -is already a valid URI. - -See also: g_test_summary() +See also [func@GLib.test_summary]. + +Since GLib 2.70, the base URI is not prepended to @bug_uri_snippet +if it is already a valid URI. @@ -56543,10 +56569,10 @@ See also: g_test_summary() - Specify the base URI for bug reports. + Specifies the base URI for bug reports. The base URI is used to construct bug report messages for -g_test_message() when g_test_bug() is called. +[func@GLib.test_message] when [func@GLib.test_bug] is called. Calling this function outside of a test case sets the default base URI for all test cases. Calling it from within a test case changes the base URI for the scope of the test @@ -56555,8 +56581,8 @@ Bug URIs are constructed by appending a bug specific URI portion to @uri_pattern, or by replacing the special string `%s` within @uri_pattern if that is present. -If g_test_bug_base() is not called, bug URIs are formed solely -from the value provided by g_test_bug(). +If [func@GLib.test_bug_base] is not called, bug URIs are formed +solely from the value provided by [func@GLib.test_bug]. @@ -56570,28 +56596,28 @@ from the value provided by g_test_bug(). Creates the pathname to a data file that is required for a test. -This function is conceptually similar to g_build_filename() except -that the first argument has been replaced with a #GTestFileType -argument. +This function is conceptually similar to [func@GLib.build_filename] +except that the first argument has been replaced with a +[enum@GLib.TestFileType] argument. The data file should either have been distributed with the module -containing the test (%G_TEST_DIST) or built as part of the build -system of that module (%G_TEST_BUILT). +containing the test ([enum@GLib.TestFileType.dist] or built as part of the +buildcsystem of that module ([enum@GLib.TestFileType.built]). In order for this function to work in srcdir != builddir situations, -the G_TEST_SRCDIR and G_TEST_BUILDDIR environment variables need to -have been defined. As of 2.38, this is done by the glib.mk -included in GLib. Please ensure that your copy is up to date before +the `G_TEST_SRCDIR` and `G_TEST_BUILDDIR` environment variables need +to have been defined. As of 2.38, this is done by the glib.mk that is +included in GLib. Please ensure that your copy is up to date before using this function. In case neither variable is set, this function will fall back to -using the dirname portion of argv[0], possibly removing ".libs". +using the dirname portion of `argv[0]`, possibly removing ".libs". This allows for casual running of tests directly from the commandline in the srcdir == builddir case and should also support running of installed tests, assuming the data files have been installed in the same relative path as the test binary. - the path of the file, to be freed using g_free() + the path of the file, to be freed using [func@GLib.free] @@ -56604,31 +56630,31 @@ same relative path as the test binary. - %NULL-terminated additional path segments + `NULL`-terminated additional path segments - Create a new #GTestCase, named @test_name. + Creates a new [struct@GLib.TestCase]. -This API is fairly low level, and calling g_test_add() or g_test_add_func() -is preferable. +This API is fairly low level, and calling [func@GLib.test_add] or +[func@GLib.test_add_func] is preferable. When this test is executed, a fixture structure of size @data_size -will be automatically allocated and filled with zeros. Then @data_setup is -called to initialize the fixture. After fixture setup, the actual test +will be automatically allocated and filled with zeros. Then @data_setup +is called to initialize the fixture. After fixture setup, the actual test function @data_test is called. Once the test run completes, the -fixture structure is torn down by calling @data_teardown and -after that the memory is automatically released by the test framework. +fixture structure is torn down by calling @data_teardown and after +that the memory is automatically released by the test framework. Splitting up a test run into fixture setup, test function and fixture teardown is most useful if the same fixture type is used for -multiple tests. In this cases, g_test_create_case() will be -called with the same type of fixture (the @data_size argument), but varying -@test_name and @data_test arguments. +multiple tests. In this cases, [func@GLib.test_create_case] will be +called with the same type of fixture (the @data_size argument), but +varying @test_name and @data_test arguments. - a newly allocated #GTestCase. + a newly allocated test case @@ -56659,9 +56685,9 @@ called with the same type of fixture (the @data_size argument), but varying - Create a new test suite with the name @suite_name. + Creates a new test suite with the name @suite_name. - A newly allocated #GTestSuite instance. + a newly allocated test suite @@ -56672,7 +56698,7 @@ called with the same type of fixture (the @data_size argument), but varying - Attempt to disable system crash reporting infrastructure. + Attempts to disable system crash reporting infrastructure. This function should be called before exercising code paths that are expected or intended to crash, to avoid wasting resources in system-wide @@ -56736,9 +56762,10 @@ expected via [func@GLib.test_expect_message] then they will be ignored. - Indicates that a test failed. This function can be called -multiple times from the same test. You can use this function -if your test failed in a recoverable way. + Indicates that a test failed. + +This function can be called multiple times from the same test. +You can use this function if your test failed in a recoverable way. Do not use this function if the failure of a test could cause other tests to malfunction. @@ -56750,18 +56777,21 @@ the test. If not called from inside a test, this function does nothing. -Note that unlike g_test_skip() and g_test_incomplete(), this -function does not log a message alongside the test failure. +Note that unlike [func@GLib.test_skip] and [func@GLib.test_incomplete], +this function does not log a message alongside the test failure. If details of the test failure are available, either log them with -g_test_message() before g_test_fail(), or use g_test_fail_printf() -instead. +[func@GLib.test_message] before [func@GLib.test_fail], or use +[func@GLib.test_fail_printf] instead. - Equivalent to g_test_fail(), but also record a message like -g_test_skip_printf(). + Indicates that a test failed and records a message. + +Also see [func@GLib.test_fail]. + +The message is formatted as if by [func@GLib.strdup_printf]. @@ -56777,10 +56807,11 @@ g_test_skip_printf(). - Returns whether a test has already failed. This will -be the case when g_test_fail(), g_test_incomplete() -or g_test_skip() have been called, but also if an -assertion has failed. + Returns whether a test has already failed. + +This will be the case when [func@GLib.test_fail], +[func@GLib.test_incomplete] or [func@GLib.test_skip] have +been called, but also if an assertion has failed. This can be useful to return early from a test if continuing after a failed assertion might be harmful. @@ -56788,7 +56819,7 @@ continuing after a failed assertion might be harmful. The return value of this function is only meaningful if it is called from inside a test function. - %TRUE if the test has failed + true if the test has failed @@ -56796,7 +56827,7 @@ if it is called from inside a test function. Gets the pathname of the directory containing test files of the type specified by @file_type. -This is approximately the same as calling g_test_build_filename("."), +This is approximately the same as calling `g_test_build_filename(".")`, but you don't need to free the return value. the path of the directory, owned by GLib @@ -56812,9 +56843,9 @@ but you don't need to free the return value. Gets the pathname to a data file that is required for a test. -This is the same as g_test_build_filename() with two differences. +This is the same as [func@GLib.test_build_filename] with two differences. The first difference is that you must only use this function from within -a testcase function. The second difference is that you need not free +a testcase function. The second difference is that you need not free the return value — it will be automatically freed when the testcase finishes running. @@ -56836,7 +56867,7 @@ joined). - %NULL-terminated additional path segments + `NULL`-terminated additional path segments @@ -56844,8 +56875,8 @@ joined). Gets the test path for the test currently being run. -In essence, it will be the same string passed as the first argument to -e.g. g_test_add() when the test was added. +In essence, it will be the same string passed as the first argument +to e.g. [func@GLib.test_add] when the test was added. This function returns a valid string only within a test function. @@ -56856,16 +56887,17 @@ Note that this is a test path, not a file system path. - Get the toplevel test suite for the test path API. + Gets the toplevel test suite for the test path API. - the toplevel #GTestSuite + the toplevel test suite Indicates that a test failed because of some incomplete -functionality. This function can be called multiple times -from the same test. +functionality. + +This function can be called multiple times from the same test. Calling this function will not stop the test from running, you need to return from the test function yourself. So you can @@ -56884,8 +56916,11 @@ If not called from inside a test, this function does nothing. - Equivalent to g_test_incomplete(), but the explanation is formatted -as if by g_strdup_printf(). + Indicates that a test failed because of some incomplete +functionality. + +Equivalent to [func@GLib.test_incomplete], but the explanation +is formatted as if by [func@GLib.strdup_printf]. @@ -56901,13 +56936,14 @@ as if by g_strdup_printf(). - Initialize the GLib testing framework, e.g. by seeding the -test random number generator, the name for g_get_prgname() -and parsing test related command line args. + Initializes the GLib testing framework. + +This includes seeding the test random number generator, +setting the program name, and parsing test-related commandline args. This should be called before calling any other `g_test_*()` functions. -So far, the following arguments are understood: +The following arguments are understood: - `-l`: List test cases available in a test executable. - `--seed=SEED`: Provide a random seed to reproduce test @@ -56918,61 +56954,61 @@ So far, the following arguments are understood: - `-s PATH`: Skip all tests matching the given path. This can also be used to force a test to run that would otherwise be skipped (ie, a test whose name contains "/subprocess"). -- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according to these test modes: +- `-m {perf|slow|thorough|quick|undefined|no-undefined}`: Execute tests according + to these test modes: `perf`: Performance tests, may take long and report results (off by default). - `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize coverage - (off by default). + `slow`, `thorough`: Slow and thorough tests, may take quite long and maximize + coverage (off by default). `quick`: Quick tests, should run really quickly and give good coverage (the default). `undefined`: Tests for undefined behaviour, may provoke programming errors - under g_test_trap_subprocess() or g_test_expect_message() to check - that appropriate assertions or warnings are given (the default). + under [func@GLib.test_trap_subprocess] or [func@GLib.test_expect_message] + to check that appropriate assertions or warnings are given (the default). - `no-undefined`: Avoid tests for undefined behaviour + `no-undefined`: Avoid tests for undefined behaviour. - `--debug-log`: Debug test logging output. -Options which can be passed to @... are: +Any parsed arguments are removed from @argv, and @argc is adjust accordingly. + +The following options are supported: - - `G_TEST_OPTION_NO_PRGNAME`: Causes g_test_init() to not call - [func@GLib.set_prgname]. Since. 2.84 - - `G_TEST_OPTION_ISOLATE_DIRS`: Creates a unique temporary directory for each - unit test and uses g_set_user_dirs() to set XDG directories to point into - that temporary directory for the duration of the unit test. See the - documentation for %G_TEST_OPTION_ISOLATE_DIRS. - - `G_TEST_OPTION_NONFATAL_ASSERTIONS`: This has the same effect as - [func@GLib.test_set_nonfatal_assertions]. Since 2.84 +- `G_TEST_OPTION_NO_PRGNAME`: Causes g_test_init() to not call + [func@GLib.set_prgname]. Since. 2.84 +- `G_TEST_OPTION_ISOLATE_DIRS`: Creates a unique temporary directory for each + unit test and sets XDG directories to point there for the duration of the unit + test. See [const@GLib.TEST_OPTION_ISOLATE_DIRS]. +- `G_TEST_OPTION_NONFATAL_ASSERTIONS`: This has the same effect as + [func@GLib.test_set_nonfatal_assertions]. Since 2.84 -Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, -g_test_init() will print an error and exit. This is to prevent no-op tests -from being executed, as g_assert() is commonly (erroneously) used in unit -tests, and is a no-op when compiled with `G_DISABLE_ASSERT`. Ensure your -tests are compiled without `G_DISABLE_ASSERT` defined. +Since 2.58, if tests are compiled with `G_DISABLE_ASSERT` defined, `g_test_init()` +will print an error and exit. This is to prevent no-op tests from being executed, +as [func@GLib.assert] is commonly (erroneously) used in unit tests, and is a no-op +when compiled with `G_DISABLE_ASSERT`. Ensure your tests are compiled without +`G_DISABLE_ASSERT` defined. - Address of the @argc parameter of the main() function. - Changed if any arguments were handled. + address of the @argc parameter of `main()` - Address of the @argv parameter of main(). - Any parameters understood by g_test_init() stripped before return. + address of the @argv parameter of `main()` - %NULL-terminated list of special options, documented below. + `NULL`-terminated list of special options - Returns %TRUE if g_test_init() has been called. + Returns true if [func@GLib.test_init] has been called. Installs a non-error fatal log handler which can be @@ -57021,7 +57057,8 @@ writer function using [func@GLib.log_set_writer_func].See - Report the result of a performance or measurement test. + Reports the result of a performance or measurement test. + The test should generally strive to maximize the reported quantities (larger values are better than smaller ones), this and @maximized_quantity can determine sorting @@ -57039,13 +57076,13 @@ order for test result reports. - arguments to pass to the printf() function + printf-like arguments to @format - Add a message to the test report. + Adds a message to the test report. @@ -57061,7 +57098,8 @@ order for test result reports. - Report the result of a performance or measurement test. + Reports the result of a performance or measurement test. + The test should generally strive to minimize the reported quantities (smaller values are better than larger ones), this and @minimized_quantity can determine sorting @@ -57079,24 +57117,24 @@ order for test result reports. - arguments to pass to the printf() function + printf-like arguments to @format - Returns %TRUE if tests are run in performance mode. + Returns true if tests are run in performance mode. By default, tests are run in quick mode. In tests that use -g_test_init(), the option `-m perf` enables performance tests, while +[func@GLib.test_init], the option `-m perf` enables performance tests, while `-m quick` disables them. Enqueues a callback @destroy_func to be executed during the next test case teardown phase. -This is most useful to auto destroy allocated test resources at the end of a -test run. Resources are released in reverse queue order, that means +This is most useful to auto destroy allocated test resources at the end +of a test run. Resources are released in reverse queue order, that means enqueueing callback `A` before callback `B` will cause `B()` to be called before `A()` during teardown. @@ -57104,33 +57142,37 @@ before `A()` during teardown. - Destroy callback for teardown phase. + destroy callback for teardown phase - Destroy callback data. + destroy callback data - Enqueue a pointer to be released with g_free() during the next -teardown phase. This is equivalent to calling g_test_queue_destroy() -with a destroy callback of g_free(). + Enqueues a pointer to be released with [func@GLib.free] +during the next teardown phase. + +This is equivalent to calling [func@GLib.test_queue_destroy] +with a destroy callback of [func@GLib.free]. - the pointer to be stored. + the pointer to be stored Enqueue an object to be released with g_object_unref() during -the next teardown phase. This is equivalent to calling -g_test_queue_destroy() with a destroy callback of g_object_unref(). +the next teardown phase. + +This is equivalent to calling [func@GLib.test_queue_destroy] +with a destroy callback of g_object_unref(). the object to unref @@ -57138,37 +57180,42 @@ g_test_queue_destroy() with a destroy callback of g_object_unref(). - Returns %TRUE if tests are run in quick mode. -Exactly one of g_test_quick() and g_test_slow() is active in any run; -there is no "medium speed". + Returns true if tests are run in quick mode. + +Tests are always run in slow mode or in fast mode; there is no "medium speed". By default, tests are run in quick mode. In tests that use -g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` +[func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. - Returns %TRUE if tests are run in quiet mode. -In tests that use g_test_init(), the option `-q` or `--quiet` enables + Returns true if tests are run in quiet mode. + +In tests that use [func@GLib.test_init], the option `-q` or `--quiet` enables this, while `--verbose` disables it. -The default is neither g_test_verbose() nor g_test_quiet(). + +The default is neither verbose nor quiet. - Get a reproducible random bit (0 or 1), see g_test_rand_int() -for details on test case random numbers. + Get a reproducible random bit (0 or 1). + +See [func@GLib.test_rand_int] for details on test case random numbers. - Get a reproducible random floating point number, -see g_test_rand_int() for details on test case random numbers. + Gets a reproducible random floating point number. + +See [func@GLib.test_rand_int] for details on test case random numbers. - a random number from the seeded random number generator. + a random number from the seeded random number generator - Get a reproducible random floating pointer number out of a specified range, -see g_test_rand_int() for details on test case random numbers. + Gets a reproducible random floating point number out of a specified range. + +See [func@GLib.test_rand_int] for details on test case random numbers. - a number with @range_start <= number < @range_end. + a number with @range_start <= number < @range_end @@ -57183,7 +57230,7 @@ see g_test_rand_int() for details on test case random numbers. - Get a reproducible random integer number. + Gets a reproducible random integer number. The random numbers generated by the g_test_rand_*() family of functions change with every new test program start, unless the --seed option is @@ -57193,15 +57240,16 @@ For individual test cases however, the random number generator is reseeded, to avoid dependencies between tests and to make --seed effective for all test cases. - a random number from the seeded random number generator. + a random number from the seeded random number generator - Get a reproducible random integer number out of a specified range, -see g_test_rand_int() for details on test case random numbers. + Gets a reproducible random integer number out of a specified range. + +See [func@GLib.test_rand_int] for details on test case random numbers. - a number with @begin <= number < @end. + a number with @begin <= number < @end @@ -57216,12 +57264,14 @@ see g_test_rand_int() for details on test case random numbers. - Runs all tests under the toplevel suite which can be retrieved -with g_test_get_root(). Similar to g_test_run_suite(), the test -cases to be run are filtered according to test path arguments -(`-p testpath` and `-s testpath`) as parsed by g_test_init(). -g_test_run_suite() or g_test_run() may only be called once in a -program. + Runs all tests under the toplevel suite. + +The toplevel suite can be retrieved with [func@GLib.test_get_root]. + +Similar to [func@GLib.test_run_suite], the test cases to be run are +filtered according to test path arguments (`-p testpath` and `-s testpath`) +as parsed by [func@GLib.test_init]. [func@GLib.test_run_suite] or +[func@GLib.test_run] may only be called once in a program. In general, the tests and sub-suites within each suite are run in the order in which they are defined. However, note that prior to @@ -57229,7 +57279,7 @@ GLib 2.36, there was a bug in the `g_test_add_*` functions which caused them to create multiple suites with the same name, meaning that if you created tests "/foo/simple", "/bar/simple", and "/foo/using-bar" in that order, they would get -run in that order (since g_test_run() would run the first "/foo" +run in that order (since [func@GLib.test_run] would run the first "/foo" suite, then the "/bar" suite, then the second "/foo" suite). As of 2.36, this bug is fixed, and adding the tests in that order would result in a running order of "/foo/simple", "/foo/using-bar", @@ -57243,50 +57293,54 @@ desired running order. Eg, "/simple/foo", "/simple/bar", However, you should never make the actual result of a test depend on the order that tests are run in. If you need to ensure that some particular code runs before or after a given test case, use -g_test_add(), which lets you specify setup and teardown functions. +[func@GLib.test_add], which lets you specify setup and teardown functions. If all tests are skipped or marked as incomplete (expected failures), this function will return 0 if producing TAP output, or 77 (treated as "skip test" by Automake) otherwise. 0 on success, 1 on failure (assuming it returns at all), - 0 or 77 if all tests were skipped with g_test_skip() and/or - g_test_incomplete() + 0 or 77 if all tests were skipped or marked as incomplete - Execute the tests within @suite and all nested #GTestSuites. + Executes the tests within @suite and all nested test suites. + The test suites to be executed are filtered according to test path arguments (`-p testpath` and `-s testpath`) as parsed by -g_test_init(). See the g_test_run() documentation for more -information on the order that tests are run in. +[func@GLib.test_init]. See the [func@GLib.test_run] documentation +for more information on the order that tests are run in. -g_test_run_suite() or g_test_run() may only be called once -in a program. +[func@GLib.test_run_suite] or [func@GLib.test_run] may only be +called once in a program. 0 on success - a #GTestSuite + a test suite - Changes the behaviour of the various `g_assert_*()` macros, -g_test_assert_expected_messages() and the various -`g_test_trap_assert_*()` macros to not abort to program, but instead -call g_test_fail() and continue. (This also changes the behavior of -g_test_fail() so that it will not cause the test program to abort -after completing the failed test.) + Changes the behaviour of the various assertion macros. + +The `g_assert_*()` macros, `g_test_assert_expected_messages()` +and the various `g_test_trap_assert_*()` macros are changed +to not abort to program. -Note that the g_assert_not_reached() and g_assert() macros are not -affected by this. +Instead, they will call [func@GLib.test_fail] and continue. +(This also changes the behavior of [func@GLib.test_fail] so that +it will not cause the test program to abort after completing +the failed test.) -This function can only be called after g_test_init(). +Note that the [func@GLib.assert_not_reached] and [func@GLib.assert] +macros are not affected by this. + +This function can only be called after [func@GLib.test_init]. @@ -57311,8 +57365,10 @@ If not called from inside a test, this function does nothing. - Equivalent to g_test_skip(), but the explanation is formatted -as if by g_strdup_printf(). + Indicates that a test was skipped. + +Equivalent to [func@GLib.test_skip], but the explanation +is formatted as if by [func@GLib.strdup_printf]. @@ -57328,80 +57384,82 @@ as if by g_strdup_printf(). - Returns %TRUE if tests are run in slow mode. -Exactly one of g_test_quick() and g_test_slow() is active in any run; -there is no "medium speed". + Returns true if tests are run in slow mode. + +Tests are always run in slow mode or in fast mode; there is no "medium speed". By default, tests are run in quick mode. In tests that use -g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` +[func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. - Returns %TRUE (after g_test_init() has been called) if the test -program is running under g_test_trap_subprocess(). + Returns true if the test program is running under [func@GLib.test_trap_subprocess]. - %TRUE if the test program is running under -g_test_trap_subprocess(). + true if the test program is running under [func@GLib.test_trap_subprocess] - Set the summary for a test, which describes what the test checks, and how it -goes about checking it. This may be included in test report output, and is -useful documentation for anyone reading the source code or modifying a test -in future. It must be a single line. + Sets the summary for a test. + +This may be included in test report output, and is useful documentation for +anyone reading the source code or modifying a test in future. It must be a +single line, and it should summarise what the test checks, and how. This should be called at the top of a test function. For example: -|[<!-- language="C" --> + +```c static void test_array_sort (void) { g_test_summary ("Test my_array_sort() sorts the array correctly and stably, " "including testing zero length and one-element arrays."); - … + // ... } -]| - -See also: g_test_bug() +``` + +See also [func@GLib.test_bug]. - One or two sentences summarising what the test checks, and how it - checks it. + summary of the test purpose - Returns %TRUE if tests are run in thorough mode, equivalent to -g_test_slow(). + Returns true if tests are run in thorough mode. + +Thorough mode is equivalent to slow mode. By default, tests are run in quick mode. In tests that use -g_test_init(), the options `-m quick`, `-m slow` and `-m thorough` +[func@GLib.test_init], the options `-m quick`, `-m slow` and `-m thorough` can be used to change this. - Get the number of seconds since the last start of the timer with -g_test_timer_start(). + Gets the number of seconds since the last start of the timer with +[func@GLib.test_timer_start]. - the time since the last start of the timer in seconds, as a double + the time since the last start of the timer in seconds - Report the last result of g_test_timer_elapsed(). + Reports the last result of [func@GLib.test_timer_elapsed]. - the last result of g_test_timer_elapsed(), as a double + the last result of [func@GLib.test_timer_elapsed] - Start a timing test. Call g_test_timer_elapsed() when the task is supposed + Starts a timing test. + +Call [func@GLib.test_timer_elapsed] when the task is supposed to be done. Call this function again to restart the timer. @@ -57409,27 +57467,31 @@ to be done. Call this function again to restart the timer. Assert that the last test subprocess failed. -See g_test_trap_subprocess(). + +See [func@GLib.test_trap_subprocess]. This is sometimes used to test situations that are formally considered to -be undefined behaviour, like inputs that fail a g_return_if_fail() +be undefined behaviour, like inputs that fail a [func@GLib.return_if_fail] check. In these situations you should skip the entire test, including the -call to g_test_trap_subprocess(), unless g_test_undefined() returns %TRUE -to indicate that undefined behaviour may be tested. +call to [func@GLib.test_trap_subprocess], unless [func@GLib.test_undefined] +returns true to indicate that undefined behaviour may be tested. Assert that the last test subprocess passed. -See g_test_trap_subprocess(). + +See [func@GLib.test_trap_subprocess]. Assert that the stderr output of the last test subprocess -matches @serrpattern. See g_test_trap_subprocess(). +matches @serrpattern. -This is sometimes used to test situations that are formally -considered to be undefined behaviour, like code that hits a -g_assert() or g_error(). In these situations you should skip the -entire test, including the call to g_test_trap_subprocess(), unless -g_test_undefined() returns %TRUE to indicate that undefined +See [func@GLib.test_trap_subprocess]. + +This is sometimes used to test situations that are formally considered +to be undefined behaviour, like code that hits a [func@GLib.assert] or +[func@GLib.error]. In these situations you should skip the entire test, +including the call to [func@GLib.test_trap_subprocess], unless +[func@GLib.test_undefined] returns true to indicate that undefined behaviour may be tested. @@ -57439,7 +57501,9 @@ behaviour may be tested. Assert that the stderr output of the last test subprocess -does not match @serrpattern. See g_test_trap_subprocess(). +does not match @serrpattern. + +See [func@GLib.test_trap_subprocess]. a glob-style [pattern][glib-Glob-style-pattern-matching] @@ -57448,7 +57512,9 @@ does not match @serrpattern. See g_test_trap_subprocess(). Assert that the stdout output of the last test subprocess matches -@soutpattern. See g_test_trap_subprocess(). +@soutpattern. + +See [func@GLib.test_trap_subprocess]. a glob-style [pattern][glib-Glob-style-pattern-matching] @@ -57457,7 +57523,9 @@ does not match @serrpattern. See g_test_trap_subprocess(). Assert that the stdout output of the last test subprocess -does not match @soutpattern. See g_test_trap_subprocess(). +does not match @soutpattern. + +See [func@GLib.test_trap_subprocess]. a glob-style [pattern][glib-Glob-style-pattern-matching] @@ -57490,100 +57558,104 @@ does not match @soutpattern. See g_test_trap_subprocess(). - Fork the current test program to execute a test case that might + Forks the current test program to execute a test case that might not return or that might abort. If @usec_timeout is non-0, the forked test case is aborted and considered failing if its run time exceeds it. -The forking behavior can be configured with the #GTestTrapFlags flags. +The forking behavior can be configured with [flags@GLib.TestTrapFlags] +flags. In the following example, the test code forks, the forked child process produces some sample output and exits successfully. The forking parent process then asserts successful child program termination and validates child program outputs. -|[<!-- language="C" --> +```c static void test_fork_patterns (void) { if (g_test_trap_fork (0, G_TEST_TRAP_SILENCE_STDOUT | G_TEST_TRAP_SILENCE_STDERR)) { - g_print ("some stdout text: somagic17\n"); - g_printerr ("some stderr text: semagic43\n"); + g_print ("some stdout text: somagic17 +"); + g_printerr ("some stderr text: semagic43 +"); exit (0); // successful test run } g_test_trap_assert_passed (); g_test_trap_assert_stdout ("*somagic17*"); g_test_trap_assert_stderr ("*semagic43*"); } -]| +``` This function is implemented only on Unix platforms, is not always reliable due to problems inherent in fork-without-exec and doesn't set close-on-exec flag on its file descriptors. -Use g_test_trap_subprocess() instead. +Use func@GLib.test_trap_subprocess] instead. - %TRUE for the forked child and %FALSE for the executing parent process. + true for the forked child and false for the executing parent process. - Timeout for the forked test in micro seconds. + timeout for the forked test in microseconds - Flags to modify forking behaviour. + flags to modify forking behaviour - Check the result of the last g_test_trap_subprocess() call. + Checks the result of the last [func@GLib.test_trap_subprocess] call. - %TRUE if the last test subprocess terminated successfully. + true if the last test subprocess terminated successfully - Check the result of the last g_test_trap_subprocess() call. + Checks the result of the last [func@GLib.test_trap_subprocess] call. - %TRUE if the last test subprocess got killed due to a timeout. + true if the last test subprocess got killed due to a timeout Respawns the test program to run only @test_path in a subprocess. -This is equivalent to calling g_test_trap_subprocess_with_envp() with `envp` -set to %NULL. See the documentation for that function for full details. +This is equivalent to calling [func@GLib.test_trap_subprocess_with_envp] +with `envp` set to `NULL`. See the documentation for that function +for full details. - Test to run in a subprocess + test to run in a subprocess - Timeout for the subprocess test in micro seconds. + timeout for the subprocess test in microseconds. - Flags to modify subprocess behaviour. + flags to modify subprocess behaviour - Respawns the test program to run only @test_path in a subprocess with the -given @envp environment. + Respawns the test program to run only @test_path in a subprocess with +a given environment. This can be used for a test case that might not return, or that might abort. -If @test_path is %NULL then the same test is re-run in a subprocess. -You can use g_test_subprocess() to determine whether the test is in -a subprocess or not. +If @test_path is `NULL` then the same test is re-run in a subprocess. +You can use [func@GLib.test_subprocess] to determine whether the test +is in a subprocess or not. @test_path can also be the name of the parent test, followed by "`/subprocess/`" and then a name for the specific subtest (or just @@ -57591,35 +57663,34 @@ ending with "`/subprocess`" if the test only has one child test); tests with names of this form will automatically be skipped in the parent process. -If @envp is %NULL, the parent process’ environment will be inherited. +If @envp is `NULL`, the parent process’ environment will be inherited. If @usec_timeout is non-0, the test subprocess is aborted and considered failing if its run time exceeds it. -The subprocess behavior can be configured with the -#GTestSubprocessFlags flags. +The subprocess behavior can be configured with [flags@GLib.TestSubprocessFlags] +flags. -You can use methods such as g_test_trap_assert_passed(), -g_test_trap_assert_failed(), and g_test_trap_assert_stderr() to +You can use methods such as [func@GLib.test_trap_assert_passed], +[func@GLib.test_trap_assert_failed], and [func@GLib.test_trap_assert_stderr] to check the results of the subprocess. (But note that -g_test_trap_assert_stdout() and g_test_trap_assert_stderr() +[func@GLib.test_trap_assert_stdout] and [func@GLib.test_trap_assert_stderr] cannot be used if @test_flags specifies that the child should inherit the parent stdout/stderr.) -If your `main ()` needs to behave differently in -the subprocess, you can call g_test_subprocess() (after calling -g_test_init()) to see whether you are in a subprocess. +If your `main ()` needs to behave differently in the subprocess, you can +call [func@GLib.test_subprocess] (after calling [func@GLib.test_init]) +to see whether you are in a subprocess. Internally, this function tracks the child process using -g_child_watch_source_new(), so your process must not ignore `SIGCHLD`, and -must not attempt to watch or wait for the child process via another -mechanism. +[func@GLib.child_watch_source_new], so your process must not ignore +`SIGCHLD`, and must not attempt to watch or wait for the child process +via another mechanism. -The following example tests that calling -`my_object_new(1000000)` will abort with an error -message. +The following example tests that calling `my_object_new(1000000)` will +abort with an error message. -|[<!-- language="C" --> +```c static void test_create_large_object (void) { @@ -57664,38 +57735,40 @@ message. test_different_username); return g_test_run (); } -]| +``` - Test to run in a subprocess + test to run in a subprocess - Environment - to run the test in, or %NULL to inherit the parent’s environment. This must - be in the GLib filename encoding. + environment + to run the test in - Timeout for the subprocess test in micro seconds. + timeout for the subprocess test in microseconds - Flags to modify subprocess behaviour. + flags to modify subprocess behaviour - Returns %TRUE if tests may provoke assertions and other formally-undefined -behaviour, to verify that appropriate warnings are given. It might, in some -cases, be useful to turn this off with if running tests under valgrind; -in tests that use g_test_init(), the option `-m no-undefined` disables + Returns true if tests may provoke assertions and other formally-undefined +behaviour, to verify that appropriate warnings are given. + +This might, in some cases, be useful to turn this off (e.g. if running tests +under valgrind). + +In tests that use [func@GLib.test_init], the option `-m no-undefined` disables those tests, while `-m undefined` explicitly enables them (normally the default behaviour). @@ -57704,10 +57777,12 @@ Since GLib 2.68, if GLib was compiled with gcc or clang and is enabled, the default changes to not exercising undefined behaviour. - Returns %TRUE if tests are run in verbose mode. -In tests that use g_test_init(), the option `--verbose` enables this, + Returns true if tests are run in verbose mode. + +In tests that use [func@GLib.test_init], the option `--verbose` enables this, while `-q` or `--quiet` disables it. -The default is neither g_test_verbose() nor g_test_quiet(). + +The default is neither verbose nor quiet. This function creates a new thread. diff --git a/Gdk-4.0.gir b/Gdk-4.0.gir index 03dbc2ca..bbcc36c6 100644 --- a/Gdk-4.0.gir +++ b/Gdk-4.0.gir @@ -432,7 +432,7 @@ and need to be set before a color state object can be built. 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` @@ -1621,6 +1621,19 @@ when they are empty. In that case %NULL will be returned. + + Returns whether the content formats contain any formats. + + true if @formats contains no mime types and no GTypes + + + + + content formats + + + + Checks if @first and @second have any matching formats. @@ -1838,8 +1851,6 @@ is returned. - A `GdkContentFormatsBuilder` is an auxiliary struct used to create -new `GdkContentFormats`, and should not be kept around. Create a new `GdkContentFormatsBuilder` object. diff --git a/Gtk-4.0.gir b/Gtk-4.0.gir index b1377efb..adffcf29 100644 --- a/Gtk-4.0.gir +++ b/Gtk-4.0.gir @@ -4229,8 +4229,7 @@ covered by the [signal@Gtk.Adjustment::value-changed] signal. - A `GtkAlertDialog` object collects the arguments that -are needed to present a message to the user. + Collects the arguments that are needed to present a message to the user. The message is shown with the [method@Gtk.AlertDialog.choose] function. @@ -4248,7 +4247,7 @@ resulting from the arguments. - printf()-style format string + `printf()`-style format string @@ -4258,7 +4257,7 @@ resulting from the arguments. - This function shows the alert to the user. + Shows the alert to the user. It is ok to pass `NULL` for the callback if the alert does not have more than one button. A simpler API for @@ -4268,15 +4267,15 @@ this case is [method@Gtk.AlertDialog.show]. - a `GtkAlertDialog` + an alert dialog - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -4291,8 +4290,7 @@ this case is [method@Gtk.AlertDialog.show]. - Finishes the [method@Gtk.AlertDialog.choose] call -and returns the index of the button that was clicked. + Finishes the [method@Gtk.AlertDialog.choose] call. the index of the button that was clicked, or -1 if the dialog was cancelled and [property@Gtk.AlertDialog:cancel-button] @@ -4301,11 +4299,11 @@ and returns the index of the button that was clicked. - a `GtkAlertDialog` + an alert dialog - a `GAsyncResult` + the result @@ -4320,7 +4318,7 @@ and returns the index of the button that was clicked. - a `GtkAlertDialog` + an alert dialog @@ -4333,7 +4331,7 @@ and returns the index of the button that was clicked. - a `GtkAlertDialog` + an alert dialog @@ -4346,7 +4344,7 @@ and returns the index of the button that was clicked. - a `GtkAlertDialog` + an alert dialog @@ -4359,7 +4357,7 @@ and returns the index of the button that was clicked. - a `GtkAlertDialog` + an alert dialog @@ -4372,7 +4370,7 @@ and returns the index of the button that was clicked. - a `GtkAlertDialog` + an alert dialog @@ -4381,12 +4379,12 @@ and returns the index of the button that was clicked. Returns whether the alert blocks interaction with the parent window while it is presented. - `TRUE` if the alert is modal + true if the alert is modal - a `GtkAlertDialog` + an alert dialog @@ -4398,7 +4396,7 @@ with the parent window while it is presented. - a `GtkAlertDialog` + an alert dialog @@ -4419,7 +4417,7 @@ details of how this value is used. - a `GtkAlertDialog` + an alert dialog @@ -4438,7 +4436,7 @@ details of how this value is used. - a `GtkAlertDialog` + an alert dialog @@ -4454,7 +4452,7 @@ details of how this value is used. - a `GtkAlertDialog` + an alert dialog @@ -4470,7 +4468,7 @@ details of how this value is used. - a `GtkAlertDialog` + an alert dialog @@ -4487,7 +4485,7 @@ with the parent window while it is presented. - a `GtkAlertDialog` + an alert dialog @@ -4497,23 +4495,24 @@ with the parent window while it is presented. - Show the alert to the user. + Shows the alert to the user. -This function is a simple version of [method@Gtk.AlertDialog.choose] +This function is a simpler version of [method@Gtk.AlertDialog.choose] intended for dialogs with a single button. -If you want to cancel the dialog or if the alert has more than one button, -you should use that function instead and provide it with a #GCancellable or -callback respectively. + +If you want to cancel the dialog or if the alert has more than one +button, you should use that function instead and provide it with a +[class@Gio.Cancellable] and callback respectively. - a `GtkAlertDialog` + an alert dialog - the parent `GtkWindow` + the parent window @@ -4522,7 +4521,7 @@ callback respectively. Labels for buttons to show in the alert. The labels should be translated and may contain -a _ to indicate the mnemonic character. +a `_` character to indicate the mnemonic character. If this property is not set, then a 'Close' button is automatically created. @@ -4531,8 +4530,8 @@ automatically created. - This property determines what happens when the Escape key is -pressed while the alert is shown. + Determines what happens when the <kbd>Escape</kbd> key is pressed +while the alert is shown. If this property holds the index of a button in [property@Gtk.AlertDialog:buttons], then pressing Escape is treated as if that button was pressed. If it is -1 @@ -4543,8 +4542,8 @@ is treated as both cancel and default button, so 0 is returned. - This property determines what happens when the Return key is -pressed while the alert is shown. + Determines what happens when the <kbd>Return</kbd> key is pressed +while the alert is shown. If this property holds the index of a button in [property@Gtk.AlertDialog:buttons], then pressing Return is treated as if that button was pressed. If it is -1 @@ -4685,7 +4684,7 @@ the other one. - `GtkAnyFilter` matches an item when at least one of its filters matches. + Matches an item when at least one of its filters matches. To add filters to a `GtkAnyFilter`, use [method@Gtk.MultiFilter.append]. @@ -8314,8 +8313,7 @@ The default IO priority is %G_PRIORITY_DEFAULT. - `GtkBoolFilter` evaluates a boolean `GtkExpression` -to determine whether to include items. + Evaluates a boolean expression to determine whether to include items. Creates a new bool filter. @@ -8324,21 +8322,21 @@ to determine whether to include items. - The expression to evaluate + the expression to evaluate - Gets the expression that the filter uses to evaluate if -an item should be filtered. + Gets the expression that the filter evaluates for +each item. - a `GtkExpression` + the expression - a `GtkBoolFilter` + a bool filter @@ -8346,12 +8344,12 @@ an item should be filtered. Returns whether the filter inverts the expression. - %TRUE if the filter inverts + true if the filter inverts - a `GtkBoolFilter` + a bool filter @@ -8360,17 +8358,17 @@ an item should be filtered. Sets the expression that the filter uses to check if items should be filtered. -The expression must have a value type of %G_TYPE_BOOLEAN. +The expression must have a value type of `G_TYPE_BOOLEAN`. - a `GtkBoolFilter` + a bool filter - a `GtkExpression` + the expression @@ -8382,17 +8380,17 @@ The expression must have a value type of %G_TYPE_BOOLEAN. - a `GtkBoolFilter` + a bool filter - %TRUE to invert + true to invert - The boolean expression to evaluate on item. + The boolean expression to evaluate on each item. @@ -8493,15 +8491,15 @@ Each side can have different width. - The `GtkBox` widget arranges child widgets into a single row or column. + Arranges child widgets into a single row or column. ![An example GtkBox](box.png) Whether it is a row or column depends on the value of its [property@Gtk.Orientable:orientation] property. Within the other -dimension, all children are allocated the same size. Of course, the -[property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] properties -can be used on the children to influence their allocation. +dimension, all children are allocated the same size. The +[property@Gtk.Widget:halign] and [property@Gtk.Widget:valign] +properties can be used on the children to influence their allocation. Use repeated calls to [method@Gtk.Box.append] to pack widgets into a `GtkBox` from start to end. Use [method@Gtk.Box.remove] to remove widgets @@ -8524,15 +8522,15 @@ place in the box. # Accessibility -Until GTK 4.10, `GtkBox` used the `GTK_ACCESSIBLE_ROLE_GROUP` role. +Until GTK 4.10, `GtkBox` used the [enum@Gtk.AccessibleRole.group] role. -Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. +Starting from GTK 4.12, `GtkBox` uses the [enum@Gtk.AccessibleRole.generic] role. - Creates a new `GtkBox`. + Creates a new box. a new `GtkBox`. @@ -8543,95 +8541,97 @@ Starting from GTK 4.12, `GtkBox` uses the `GTK_ACCESSIBLE_ROLE_GENERIC` role. - the number of pixels to place by default between children + the number of pixels to place between children - Adds @child as the last child to @box. + Adds a child at the end. - a `GtkBox` + a box - the `GtkWidget` to append + the widget to append - Gets the value set by gtk_box_set_baseline_child(). + Gets the value set by [method@Gtk.Box.set_baseline_child]. the baseline child - a `GtkBox` + a box - Gets the value set by gtk_box_set_baseline_position(). + Gets the value set by [method@Gtk.Box.set_baseline_position]. the baseline position - a `GtkBox` + a box - Returns whether the box is homogeneous (all children are the -same size). + Returns whether the box is homogeneous. + +In a homogeneous box all children are the same size. - %TRUE if the box is homogeneous. + true if the box is homogeneous - a `GtkBox` + a box - Gets the value set by gtk_box_set_spacing(). + Gets the value set by [method@Gtk.Box.set_spacing]. spacing between children - a `GtkBox` + a box - Inserts @child in the position after @sibling in the list -of @box children. + Inserts a child at a specific position. + +The child is added after @sibling in the list of @box children. -If @sibling is %NULL, insert @child at the first position. +If @sibling is `NULL`, the @child is placed at the beginning. - a `GtkBox` + a box - the `GtkWidget` to insert + the widget to insert @@ -8641,23 +8641,23 @@ If @sibling is %NULL, insert @child at the first position. - Adds @child as the first child to @box. + Adds a child at the beginning. - a `GtkBox` + a box - the `GtkWidget` to prepend + the widget to prepend - Removes a child widget from @box. + Removes a child widget from the box. The child must have been added before with [method@Gtk.Box.append], [method@Gtk.Box.prepend], or @@ -8667,7 +8667,7 @@ The child must have been added before with - a `GtkBox` + a box @@ -8677,20 +8677,22 @@ The child must have been added before with - Moves @child to the position after @sibling in the list + Moves a child to a different position. + +The child is moved to the position after @sibling in the list of @box children. -If @sibling is %NULL, move @child to the first position. +If @sibling is `NULL`, the child is placed at the beginning. - a `GtkBox` + a box - the `GtkWidget` to move, must be a child of @box + the widget to move, must be a child of @box @@ -8708,11 +8710,11 @@ This affects only vertical boxes. - a `GtkBox` + a box - a child, or -1 + a child position, or -1 @@ -8730,41 +8732,41 @@ extra space available. - a `GtkBox` + a box - a `GtkBaselinePosition` + the baseline position - Sets whether or not all children of @box are given equal space + Sets whether or not all children are given equal space in the box. - a `GtkBox` + a box - a boolean value, %TRUE to create equal allotments, - %FALSE for variable allotments + true to create equal allotments, + false for variable allotments - Sets the number of pixels to place between children of @box. + Sets the number of pixels to place between children. - a `GtkBox` + a box @@ -8774,11 +8776,13 @@ in the box. - The child that determines the baseline, in vertical orientation. + The position of the child that determines the baseline. + +This is only relevant if the box is in vertical orientation. - The position of the baseline aligned widgets if extra space is available. + How to position baseline-aligned widgets if extra space is available. @@ -9891,9 +9895,9 @@ property types: as false values) - enumeration types (can be specified by their full C identifier their short name used when registering the enumeration type, or their integer value) -- flag types (can be specified by their C identifier, short name, integer - value, and optionally combined with “|” for bitwise OR, e.g. - “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase”) +- flag types (can be specified by their C identifier or short name, + optionally combined with “|” for bitwise OR, or a single integer value + e.g., “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase” or 520). - colors (in a format understood by [method@Gdk.RGBA.parse]) - `GVariant` (can be specified in the format understood by [func@GLib.Variant.parse]) @@ -20859,9 +20863,8 @@ It can be set to switch the color chooser into single-color editing mode. - A `GtkColorDialog` object collects the arguments that -are needed to present a color chooser dialog to the -user, such as a title for the dialog and whether it + Collects the arguments that are needed to present a color chooser +dialog to the 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] @@ -20877,18 +20880,17 @@ that uses `GtkColorDialog` and presents the results. - This function initiates a color choice operation by -presenting a color chooser dialog to the user. + Presents a color chooser dialog to the user. - a `GtkColorDialog` + a color dialog - the parent `GtkWindow` + the parent window @@ -20896,12 +20898,12 @@ presenting a color chooser dialog to the user. - a `GCancellable` to cancel the operation + a cancellable to cancel the operation - a callback to call when the - operation is complete + a callback to call + when the operation is complete @@ -20911,20 +20913,18 @@ presenting a color chooser dialog to the user. - Finishes the [method@Gtk.ColorDialog.choose_rgba] call and -returns the resulting color. + Finishes the [method@Gtk.ColorDialog.choose_rgba] call - the selected color, or - `NULL` and @error is set + the selected color - a `GtkColorDialog` + a color dialog - a `GAsyncResult` + the result @@ -20934,12 +20934,12 @@ returns the resulting color. blocks interaction with the parent window while it is presented. - `TRUE` if the color chooser dialog is modal + true if the color chooser dialog is modal - a `GtkColorDialog` + a color dialog @@ -20953,7 +20953,7 @@ color chooser dialog. - a `GtkColorDialog` + a color dialog @@ -20961,12 +20961,12 @@ color chooser dialog. Returns whether colors may have alpha. - `TRUE` if colors may have alpha + true if colors may have alpha - a `GtkColorDialog` + a color dailog @@ -20980,7 +20980,7 @@ while it is presented. - a `GtkColorDialog` + a color dialog @@ -20997,7 +20997,7 @@ color chooser dialog. - a `GtkColorDialog` + a color dialog @@ -21013,7 +21013,7 @@ color chooser dialog. - a `GtkColorDialog` + a color dialog @@ -21027,14 +21027,13 @@ color chooser dialog. - A title that may be shown on the color chooser -dialog that is presented by [method@Gtk.ColorDialog.choose_rgba]. + A title that may be shown on the color chooser dialog. Whether colors may have alpha (translucency). -When with-alpha is %FALSE, the color that is selected +When with-alpha is false, the color that is selected will be forced to have alpha == 1. @@ -25607,15 +25606,14 @@ structure if the reference count reaches 0. - `GtkCustomFilter` determines whether to include items with a callback. + Determines whether to include items with a callback. - Creates a new filter using the given @match_func to filter -items. + Creates a new filter using the given function to filter items. -If @match_func is %NULL, the filter matches all items. +If @match_func is `NULL`, the filter matches all items. If the filter func changes its filtering behavior, -gtk_filter_changed() needs to be called. +[method@Gtk.Filter.changed] needs to be called. a new `GtkCustomFilter` @@ -25638,19 +25636,19 @@ gtk_filter_changed() needs to be called. Sets the function used for filtering items. -If @match_func is %NULL, the filter matches all items. +If @match_func is `NULL`, the filter matches all items. If the filter func changes its filtering behavior, -gtk_filter_changed() needs to be called. +[method@Gtk.Filter.changed] needs to be called. -If a previous function was set, its @user_destroy will be -called now. +If a previous function was set, its @user_destroy +will be called. - a `GtkCustomFilter` + a custom filter @@ -25676,15 +25674,15 @@ called now. User function that is called to determine if the @item should be matched. -If the filter matches the item, this function must return %TRUE. If the -item should be filtered out, %FALSE must be returned. +If the filter matches the item, this function must return true. +If the item should be filtered out, false must be returned. - %TRUE to keep the item around + true to keep the item around - The item to be matched + the item to be matched @@ -34091,7 +34089,7 @@ It will only be emitted on devices capable of it. - `GtkEveryFilter` matches an item when each of its filters matches. + Matches an item when each of its filters matches. To add filters to a `GtkEveryFilter`, use [method@Gtk.MultiFilter.append]. @@ -36420,9 +36418,8 @@ The default binding for this signal is <kbd>Alt</kbd>-<kbd>Up& - A `GtkFileDialog` object collects the arguments that -are needed to present a file chooser dialog to the -user, such as a title for the dialog and whether it + Collects the arguments that are needed to present a file chooser +dialog to the user, such as a title for the dialog and whether it should be modal. The dialog is shown with [method@Gtk.FileDialog.open], @@ -36437,12 +36434,12 @@ The dialog is shown with [method@Gtk.FileDialog.open], Retrieves the text used by the dialog on its accept button. - the label shown on the file chooser's accept button. + the label shown on the file chooser's accept button - a `GtkFileDialog` + a file dialog @@ -36451,12 +36448,12 @@ The dialog is shown with [method@Gtk.FileDialog.open], Gets the filter that will be selected by default in the file chooser dialog. - the current filter + the default filter - a `GtkFileDialog` + a file dialog @@ -36465,13 +36462,13 @@ in the file chooser dialog. Gets the filters that will be offered to the user in the file chooser dialog. - the filters, as - a `GListModel` of `GtkFileFilters` + the filters, + as a list model of [class@Gtk.FileFilter] - a `GtkFileDialog` + a file dialog @@ -36485,7 +36482,7 @@ the file chooser dialog. - a `GtkFileDialog` + a file dialog @@ -36499,56 +36496,55 @@ initial folder in the file chooser dialog. - a `GtkFileDialog` + a file dialog - Gets the name for the file that should be initially set. + Gets the filename that will be initially selected. the name - a `GtkFileDialog` + a file dialog - Returns whether the file chooser dialog -blocks interaction with the parent window -while it is presented. + Returns whether the file chooser dialog blocks interaction +with the parent window while it is presented. - `TRUE` if the file chooser dialog is modal + true if the file chooser dialog is modal - a `GtkFileDialog` + a file dialog - Returns the title that will be shown on the -file chooser dialog. + Returns the title that will be shown on the file chooser dialog. the title - a `GtkFileDialog` + a file dialog - This function initiates a file selection operation by -presenting a file chooser dialog to the user. + Presents a file chooser dialog to the user. + +The file chooser dialog will be set up to select a single file. The @callback will be called when the dialog is dismissed. @@ -36556,15 +36552,15 @@ The @callback will be called when the dialog is dismissed. - a `GtkFileDialog` + a file dialog - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -36579,29 +36575,28 @@ The @callback will be called when the dialog is dismissed. - Finishes the [method@Gtk.FileDialog.open] call and -returns the resulting file. + Finishes the [method@Gtk.FileDialog.open] call. - the file that was selected. - Otherwise, `NULL` is returned and @error is set + the file that was selected - a `GtkFileDialog` + a file dialog - a `GAsyncResult` + the result - This function initiates a multi-file selection operation by -presenting a file chooser dialog to the user. + Presents a file chooser dialog to the user. -The file chooser will initially be opened in the directory +The file chooser dialog will be set up to select multiple files. + +The file chooser dialog will initially be opened in the directory [property@Gtk.FileDialog:initial-folder]. The @callback will be called when the dialog is dismissed. @@ -36610,15 +36605,15 @@ The @callback will be called when the dialog is dismissed. - a `GtkFileDialog` + a file dialog - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -36633,28 +36628,27 @@ The @callback will be called when the dialog is dismissed. - Finishes the [method@Gtk.FileDialog.open] call and -returns the resulting files in a `GListModel`. + Finishes the [method@Gtk.FileDialog.open] call. - the file that was selected, - as a `GListModel` of `GFiles`. Otherwise, `NULL` is returned - and @error is set + the files that were selected, + as a list model of [iface@Gio.File] - a `GtkFileDialog` + a file dialog - a `GAsyncResult` + the rsult - This function initiates a file save operation by -presenting a file chooser dialog to the user. + Presents a file chooser dialog to the user. + +The file chooser dialog will be save mode. The @callback will be called when the dialog is dismissed. @@ -36662,15 +36656,15 @@ The @callback will be called when the dialog is dismissed. - a `GtkFileDialog` + a file dialog - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -36685,30 +36679,29 @@ The @callback will be called when the dialog is dismissed. - Finishes the [method@Gtk.FileDialog.save] call and -returns the resulting file. + Finishes the [method@Gtk.FileDialog.save] call. - the file that was selected. - Otherwise, `NULL` is returned and @error is set + the file that was selected - a `GtkFileDialog` + a file dialog - a `GAsyncResult` + the result - This function initiates a directory selection operation by -presenting a file chooser dialog to the user. + Presents a file chooser dialog to the user. -If you pass @initial_folder, the file chooser will initially be -opened in the parent directory of that folder, otherwise, it +The file chooser dialog will be set up to select a single folder. + +If you pass @initial_folder, the file chooser dialog 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. @@ -36717,15 +36710,15 @@ The @callback will be called when the dialog is dismissed. - a `GtkFileDialog` + a file dialog - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -36740,30 +36733,30 @@ The @callback will be called when the dialog is dismissed. - Finishes the [method@Gtk.FileDialog.select_folder] call and -returns the resulting file. + Finishes the [method@Gtk.FileDialog.select_folder] call. - the file that was selected. - Otherwise, `NULL` is returned and @error is set + the folder that was selected - a `GtkFileDialog` + a file dialog - a `GAsyncResult` + the result - This function initiates a multi-directory selection operation by -presenting a file chooser dialog to the user. + Presents a file chooser dialog to the user. -The file chooser will initially be opened in the directory -[property@Gtk.FileDialog:initial-folder]. +The file chooser dialog will be set up to allow selecting +multiple folders. + +The file chooser dialog will initially be opened in the +directory [property@Gtk.FileDialog:initial-folder]. The @callback will be called when the dialog is dismissed. @@ -36771,15 +36764,15 @@ The @callback will be called when the dialog is dismissed. - a `GtkFileDialog` + a file dialog - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -36794,21 +36787,19 @@ The @callback will be called when the dialog is dismissed. - Finishes the [method@Gtk.FileDialog.select_multiple_folders] -call and returns the resulting files in a `GListModel`. + Finishes the [method@Gtk.FileDialog.select_multiple_folders] call. - the file that was selected, - as a `GListModel` of `GFiles`. Otherwise, `NULL` is returned - and @error is set + the folders that were selected, + as a list model of [iface@Gio.File] - a `GtkFileDialog` + a file dialog - a `GAsyncResult` + the result @@ -36816,14 +36807,15 @@ call and returns the resulting files in a `GListModel`. Sets the label shown on the file chooser's accept button. -Leaving the accept label unset or setting it as `NULL` will fall back to -a default label, depending on what API is used to launch the file dialog. +Leaving the accept label unset or setting it as `NULL` will +fall back to a default label, depending on what API is used +to launch the file dialog. - a `GtkFileDialog` + a file dialog @@ -36836,7 +36828,7 @@ a default label, depending on what API is used to launch the file dialog. Sets the filter that will be selected by default in the file chooser dialog. -If set to %NULL, the first item in [property@Gtk.FileDialog:filters] +If set to `NULL`, the first item in [property@Gtk.FileDialog:filters] will be used as the default filter. If that list is empty, the dialog will be unfiltered. @@ -36844,11 +36836,11 @@ will be unfiltered. - a `GtkFileDialog` + a file dialog - a `GtkFileFilter` + the file filter @@ -36861,11 +36853,11 @@ in the file chooser dialog. - a `GtkFileDialog` + a file dialog - a `GListModel` of `GtkFileFilters` + a list model of [class@Gtk.FileFilter] @@ -36875,19 +36867,19 @@ in the file chooser dialog. the file chooser dialog. This function is a shortcut for calling both -gtk_file_dialog_set_initial_folder() and -gtk_file_dialog_set_initial_name() with the directory and -name of @file respectively. +[method@Gtk.FileDialog.set_initial_folder] and +[method@Gtk.FileDialog.set_initial_name] with the +directory and name of @file, respectively. - a `GtkFileDialog` + a file dialog - a `GFile` + a file @@ -36900,45 +36892,47 @@ initial folder in the file chooser dialog. - a `GtkFileDialog` + a file dialog - a `GFile` + a file - Sets the name for the file that should be initially set. -For saving dialogs, this will usually be pre-entered into the name field. + Sets the filename that will be initially selected. -If a file with this name already exists in the directory set via -[property@Gtk.FileDialog:initial-folder], the dialog should preselect it. +For save dialogs, @name will usually be pre-entered into the +name field. + +If a file with this name already exists in the directory set +via [property@Gtk.FileDialog:initial-folder], the dialog will +preselect it. - a `GtkFileDialog` + a file dialog - a UTF8 string + a string - Sets whether the file chooser dialog -blocks interaction with the parent window -while it is presented. + Sets whether the file chooser dialog blocks interaction +with the parent window while it is presented. - a `GtkFileDialog` + a file dialog @@ -36948,14 +36942,13 @@ while it is presented. - Sets the title that will be shown on the -file chooser dialog. + Sets the title that will be shown on the file chooser dialog. - a `GtkFileDialog` + a file dialog @@ -36969,39 +36962,44 @@ file chooser dialog. - The default filter, that is, the filter that is initially -active in the file chooser dialog. + The default filter. + +This filter is initially active in the file chooser dialog. -If the default filter is %NULL, the first filter of [property@Gtk.FileDialog:filters] +If the default filter is `NULL`, the first filter of [property@Gtk.FileDialog:filters] is used as the default filter. If that property contains no filter, the dialog will be unfiltered. -If [property@Gtk.FileDialog:filters] is not %NULL, the default filter should be part -of the list. If it is not, the dialog may choose to not make it available. +If [property@Gtk.FileDialog:filters] is not `NULL`, the default filter should be +part of the list. If it is not, the dialog may choose to not make it available. The list of filters. -See [property@Gtk.FileDialog:default-filter] about how those two properties interact. +See [property@Gtk.FileDialog:default-filter] about how these +two properties interact. - The initial file, that is, the file that is initially selected -in the file chooser dialog + The initial file. + +This file is initially selected in the file chooser dialog -This is a utility property that sets both [property@Gtk.FileDialog:initial-folder] and -[property@Gtk.FileDialog:initial-name]. +This is a utility property that sets both [property@Gtk.FileDialog:initial-folder] +and [property@Gtk.FileDialog:initial-name]. - The initial folder, that is, the directory that is initially -opened in the file chooser dialog + The initial folder. + +This is the directory that is initially opened in the file chooser dialog. - The initial name, that is, the filename that is initially -selected in the file chooser dialog. + The initial name. + +This is the name of the file that is initially selected in the file chooser dialog. @@ -37019,10 +37017,10 @@ selected in the file chooser dialog. - `GtkFileFilter` filters files by name or mime type. + Filters files by name or mime type. `GtkFileFilter` can be used to restrict the files being shown in a -`GtkFileChooser`. Files can be filtered based on their name (with +file chooser. Files can be filtered based on their name (with [method@Gtk.FileFilter.add_pattern] or [method@Gtk.FileFilter.add_suffix]) or on their mime type (with [method@Gtk.FileFilter.add_mime_type]). @@ -37032,8 +37030,8 @@ type application/rtf, since application/rtf is a subclass of text/plain. Note that `GtkFileFilter` allows wildcards for the subtype of a mime type, so you can e.g. filter for image/\*. -Normally, file filters are used by adding them to a `GtkFileChooser` -(see [method@Gtk.FileChooser.add_filter]), but it is also possible to +Normally, file filters are used by adding them to a file chooser +(see [method@Gtk.FileDialog.set_filters]), but it is also possible to manually use a file filter on any [class@Gtk.FilterListModel] containing `GFileInfo` objects. @@ -37103,13 +37101,13 @@ The variant must be in the format produced by - Adds a rule allowing a given mime type to @filter. + Adds a rule allowing a given mime type. - A `GtkFileFilter` + A file filter @@ -37119,7 +37117,7 @@ The variant must be in the format produced by - Adds a rule allowing a shell style glob to a filter. + Adds a rule allowing a shell style glob pattern. Note that it depends on the platform whether pattern matching ignores case or not. On Windows, it does, on @@ -37129,18 +37127,17 @@ other platforms, it doesn't. - a `GtkFileFilter` + a file filter - a shell style glob + a shell style glob pattern - Adds a rule allowing image files in the formats supported -by GdkPixbuf. + Adds a rule allowing image files in the formats supported by `GdkPixbuf`. This is equivalent to calling [method@Gtk.FileFilter.add_mime_type] for all the supported mime types. @@ -37149,7 +37146,7 @@ for all the supported mime types. - a `GtkFileFilter` + a file filter @@ -37157,8 +37154,7 @@ for all the supported mime types. Adds a suffix match rule to a filter. -This is similar to adding a match for the pattern -"*.@suffix". +This is similar to adding a match for the pattern "*.@suffix". In contrast to pattern matches, suffix matches are *always* case-insensitive. @@ -37167,7 +37163,7 @@ are *always* case-insensitive. - a `GtkFileFilter` + a file filter @@ -37181,8 +37177,7 @@ are *always* case-insensitive. passed to this filter. This function will not typically be used by applications; -it is intended principally for use in the implementation -of `GtkFileChooser`. +it is intended for use in file chooser implementation. the attributes @@ -37191,7 +37186,7 @@ of `GtkFileChooser`. - a `GtkFileFilter` + a file filter @@ -37201,12 +37196,12 @@ of `GtkFileChooser`. See [method@Gtk.FileFilter.set_name]. - The human-readable name of the filter + the human-readable name of the filter - a `GtkFileFilter` + a file filter @@ -37214,19 +37209,18 @@ See [method@Gtk.FileFilter.set_name]. Sets a human-readable name of the filter. -This is the string that will be displayed in the file chooser +This is the string that will be displayed in the user interface if there is a selectable list of filters. - a `GtkFileFilter` + a file filter - the human-readable-name for the filter, or %NULL - to remove any existing name. + the human-readable name for the filter @@ -37239,7 +37233,7 @@ if there is a selectable list of filters. - a `GtkFileFilter` + a file filter @@ -37253,8 +37247,8 @@ if there is a selectable list of filters. The human-readable name of the filter. -This is the string that will be displayed in the file chooser -user interface if there is a selectable list of filters. +This is the string that will be displayed in the user interface +if there is a selectable list of filters. @@ -37271,8 +37265,7 @@ user interface if there is a selectable list of filters. - A `GtkFileLauncher` object collects the arguments that are needed to open a -file with an application. + Collects the arguments that are needed to open a file with an application. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application @@ -37295,14 +37288,14 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. - Returns whether to ask the user to choose an app for opening the file. + Returns whether to ask the user which app to use. - `TRUE` if always asking for app + true if always asking the user - a `GtkFileLauncher` + a file launcher @@ -37315,7 +37308,7 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. - a `GtkFileLauncher` + a file launcher @@ -37323,18 +37316,18 @@ To launch uris that don't represent files, use [class@Gtk.UriLauncher]. Returns whether to make the file writable for the handler. - `TRUE` if the file will be made writable + true if the file will be made writable - a `GtkFileLauncher` + a file launcher - Launch an application to open the file. + Launches an application to open the file. This may present an app chooser dialog to the user. @@ -37342,15 +37335,15 @@ This may present an app chooser dialog to the user. - a `GtkFileLauncher` + a file launcher - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -37368,40 +37361,39 @@ This may present an app chooser dialog to the user. Finishes the [method@Gtk.FileLauncher.launch] call and returns the result. - `TRUE` if an application was launched, - or `FALSE` and @error is set + true if an application was launched - a `GtkFileLauncher` + a file launcher - a `GAsyncResult` + the result - Launch a file manager to show the file in its parent directory. + Launches a file manager to show the file in its parent directory. -This is only supported native files. It will fail if @file +This is only supported for native files. It will fail if @file is e.g. a http:// uri. - a `GtkFileLauncher` + a file launcher - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -37419,34 +37411,35 @@ is e.g. a http:// uri. Finishes the [method@Gtk.FileLauncher.open_containing_folder] call and returns the result. - `TRUE` if an application was launched, - or `FALSE` and @error is set + true if an application was launched - a `GtkFileLauncher` + a file launcher - a `GAsyncResult` + the result - Sets whether to awlays ask the user to choose an app for opening the file. -If `FALSE`, the file might be opened with a default app or the previous choice. + Sets whether to awlays ask the user which app to use. + +If false, the file might be opened with a default app +or the previous choice. - a `GtkFileLauncher` + a file launcher - a `gboolean` + whether to always ask @@ -37458,11 +37451,11 @@ If `FALSE`, the file might be opened with a default app or the previous choice.< - a `GtkFileLauncher` + a file launcher - a `GFile` + the file @@ -37474,11 +37467,11 @@ If `FALSE`, the file might be opened with a default app or the previous choice.< - a `GtkFileLauncher` + a file launcher - a `gboolean` + whether to make the file writable @@ -37503,12 +37496,11 @@ the file might be opened with a default app or the previous choice. - A `GtkFilter` object describes the filtering to be performed by a -[class@Gtk.FilterListModel]. + Describes the filtering to be performed by a [class@Gtk.FilterListModel]. The model will use the filter to determine if it should include items or not by calling [method@Gtk.Filter.match] for each item and only -keeping the ones that the function returns %TRUE for. +keeping the ones that the function returns true for. Filters may change what items they match through their lifetime. In that case, they will emit the [signal@Gtk.Filter::changed] signal to notify @@ -37522,14 +37514,14 @@ various widgets to easily allow searches. However, in particular for large lists or complex search methods, it is also possible to subclass `GtkFilter` and provide one's own filter. - Gets the known strictness of @filters. + Gets the known strictness of a filter. -If the strictness is not known, %GTK_FILTER_MATCH_SOME is returned. +If the strictness is not known, [enum@Gtk.FilterMatch.some] is returned. This value may change after emission of the [signal@Gtk.Filter::changed] signal. -This function is meant purely for optimization purposes, filters can +This function is meant purely for optimization purposes. Filters can choose to omit implementing it, but `GtkFilterListModel` uses it. the strictness of @self @@ -37537,7 +37529,7 @@ choose to omit implementing it, but `GtkFilterListModel` uses it. - a `GtkFilter` + a filter @@ -37545,13 +37537,12 @@ choose to omit implementing it, but `GtkFilterListModel` uses it. Checks if the given @item is matched by the filter or not. - %TRUE if the filter matches the item and a filter model should - keep it, %FALSE if not. + true if the filter matches the item - a `GtkFilter` + a filter @@ -37578,24 +37569,24 @@ subclasses and should not be called from other functions. - a `GtkFilter` + a filter - How the filter changed + how the filter changed - Gets the known strictness of @filters. + Gets the known strictness of a filter. -If the strictness is not known, %GTK_FILTER_MATCH_SOME is returned. +If the strictness is not known, [enum@Gtk.FilterMatch.some] is returned. This value may change after emission of the [signal@Gtk.Filter::changed] signal. -This function is meant purely for optimization purposes, filters can +This function is meant purely for optimization purposes. Filters can choose to omit implementing it, but `GtkFilterListModel` uses it. the strictness of @self @@ -37603,7 +37594,7 @@ choose to omit implementing it, but `GtkFilterListModel` uses it. - a `GtkFilter` + a filter @@ -37611,13 +37602,12 @@ choose to omit implementing it, but `GtkFilterListModel` uses it. Checks if the given @item is matched by the filter or not. - %TRUE if the filter matches the item and a filter model should - keep it, %FALSE if not. + true if the filter matches the item - a `GtkFilter` + a filter @@ -37656,21 +37646,21 @@ documentation for details. using the filter to optimize refiltering items. If you are writing an implementation and are not sure which -value to pass, %GTK_FILTER_CHANGE_DIFFERENT is always a correct +value to pass, `GTK_FILTER_CHANGE_DIFFERENT` is always a correct choice. The filter change cannot be - described with any of the other enumeration values. + described with any of the other enumeration values The filter is less strict than - it was before: All items that it used to return %TRUE for - still return %TRUE, others now may, too. + it was before: All items that it used to return true + still return true, others now may, too. The filter is more strict than - it was before: All items that it used to return %FALSE for - still return %FALSE, others now may, too. + it was before: All items that it used to return false + still return false, others now may, too. @@ -37680,13 +37670,12 @@ choice. - %TRUE if the filter matches the item and a filter model should - keep it, %FALSE if not. + true if the filter matches the item - a `GtkFilter` + a filter @@ -37704,7 +37693,7 @@ choice. - a `GtkFilter` + a filter @@ -37970,19 +37959,19 @@ types match. Describes the known strictness of a filter. Note that for filters where the strictness is not known, -%GTK_FILTER_MATCH_SOME is always an acceptable value, +`GTK_FILTER_MATCH_SOME` is always an acceptable value, even if a filter does match all or no items. The filter matches some items, - gtk_filter_match() may return %TRUE or %FALSE + [method@Gtk.Filter.match] may return true or false The filter does not match any item, - gtk_filter_match() will always return %FALSE. + [method@Gtk.Filter.match] will always return false The filter matches all items, - gtk_filter_match() will alays return %TRUE. + [method@Gtk.Filter.match] will alays return true @@ -40504,10 +40493,8 @@ the selected font has any features or axes. - A `GtkFontDialog` object collects the arguments that -are needed to present a font chooser dialog to the -user, such as a title for the dialog and whether it -should be modal. + Collects the arguments that are needed to present a font chooser dialog +to the 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. @@ -40522,19 +40509,21 @@ 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). + Presents a font chooser dialog to the user. + +The font chooser dialog will be set up for selecting a font face. + +A font face represents a font family and style, but no specific font size. - a `GtkFontDialog` + a font dialog - the parent `GtkWindow` + the parent window @@ -40542,7 +40531,7 @@ presenting a dialog to the user for selecting a font face - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -40557,36 +40546,36 @@ presenting a dialog to the user for selecting a font face - Finishes the [method@Gtk.FontDialog.choose_face] call -and returns the resulting font face. + Finishes the [method@Gtk.FontDialog.choose_face] call. the selected font face - a `GtkFontDialog` + a font dialog - a `GAsyncResult` + the result - This function initiates a font selection operation by -presenting a dialog to the user for selecting a font family. + Presents a font chooser dialog to the user. + +The font chooser dialog will be set up for selecting a font family. - a `GtkFontDialog` + a font dialog - the parent `GtkWindow` + the parent window @@ -40594,7 +40583,7 @@ presenting a dialog to the user for selecting a font family. - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -40609,8 +40598,7 @@ presenting a dialog to the user for selecting a font family. - Finishes the [method@Gtk.FontDialog.choose_family] call -and returns the resulting family. + Finishes the [method@Gtk.FontDialog.choose_family] call. This function never returns an error. If the operation is not finished successfully, the value passed as @initial_value @@ -40621,18 +40609,19 @@ to [method@Gtk.FontDialog.choose_family] is returned. - a `GtkFontDialog` + a font dialog - a `GAsyncResult` + the result - This function initiates a font selection operation by -presenting a dialog to the user for selecting a font. + Presents a font chooser dialog to the user. + +The font chooser dialog will be set up for selecting a font. If you want to let the user select font features as well, use [method@Gtk.FontDialog.choose_font_and_features] instead. @@ -40641,11 +40630,11 @@ use [method@Gtk.FontDialog.choose_font_and_features] instead. - a `GtkFontDialog` + a font dialog - the parent `GtkWindow` + the parent window @@ -40653,7 +40642,7 @@ use [method@Gtk.FontDialog.choose_font_and_features] instead. - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -40668,9 +40657,10 @@ use [method@Gtk.FontDialog.choose_font_and_features] instead. - This function initiates a font selection operation by -presenting a dialog to the user for selecting a font and -font features. + Presents a font chooser dialog to the user. + +The font chooser dialog will be set up for selecting a font +and specify features for the selected font. Font features affect how the font is rendered, for example enabling glyph variants or ligatures. @@ -40679,11 +40669,11 @@ enabling glyph variants or ligatures. - a `GtkFontDialog` + a font dialog - the parent `GtkWindow` + the parent window @@ -40691,7 +40681,7 @@ enabling glyph variants or ligatures. - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -40706,20 +40696,21 @@ enabling glyph variants or ligatures. - Finishes the [method@Gtk.FontDialog.choose_font_and_features] -call and returns the resulting font description and font features. + Finishes the [method@Gtk.FontDialog.choose_font_and_features] call. + +The selected font and features are returned in @font_desc and +@font_features. - `TRUE` if a font was selected. Otherwise `FALSE` is returned - and @error is set + true if a font was selected - a `GtkFontDialog` + a font dialog - a `GAsyncResult` + the result @@ -40737,19 +40728,18 @@ call and returns the resulting font description and font features. - Finishes the [method@Gtk.FontDialog.choose_font] call -and returns the resulting font description. + Finishes the [method@Gtk.FontDialog.choose_font] call. the selected font - a `GtkFontDialog` + a font dialog - a `GAsyncResult` + the result @@ -40763,7 +40753,7 @@ in the font chooser dialog. - a `GtkFontDialog` + a font dialog @@ -40777,7 +40767,7 @@ or `NULL` for the default fontmap. - a `GtkFontDialog` + a font dialog @@ -40790,36 +40780,34 @@ or `NULL` for the default fontmap. - a `GtkFontDialog` + a font dialog - Returns whether the font chooser dialog -blocks interaction with the parent window -while it is presented. + Returns whether the font chooser dialog blocks interaction +with the parent window while it is presented. - `TRUE` if the font chooser dialog is modal + true if the font chooser dialog is modal - a `GtkFontDialog` + a font dialog - Returns the title that will be shown on the -font chooser dialog. + Returns the title that will be shown on the font chooser dialog. the title - a `GtkFontDialog` + a font dialog @@ -40828,18 +40816,18 @@ font chooser dialog. Adds a filter that decides which fonts to display in the font chooser dialog. -The `GtkFilter` must be able to handle both `PangoFontFamily` +The filter must be able to handle both `PangoFontFamily` and `PangoFontFace` objects. - a `GtkFontDialog` + a font dialog - a `GtkFilter` + the filter @@ -40853,7 +40841,7 @@ If @fontmap is `NULL`, the default fontmap is used. - a `GtkFontDialog` + a font dialog @@ -40869,7 +40857,7 @@ If @fontmap is `NULL`, the default fontmap is used. - a `GtkFontDialog` + a font dialog @@ -40879,15 +40867,14 @@ If @fontmap is `NULL`, the default fontmap is used. - Sets whether the font chooser dialog -blocks interaction with the parent window -while it is presented. + Sets whether the font chooser dialog blocks interaction +with the parent window while it is presented. - a `GtkFontDialog` + a font dialog @@ -40897,14 +40884,13 @@ while it is presented. - Sets the title that will be shown on the -font chooser dialog. + Sets the title that will be shown on the font chooser dialog. - a `GtkFontDialog` + a font dialog @@ -40914,12 +40900,11 @@ font chooser dialog. - Sets a filter to restrict what fonts are shown -in the font chooser dialog. + A filter to restrict what fonts are shown in the font chooser dialog. - Sets a custom font map to select fonts from. + A custom font map to select fonts from. A custom font map can be used to present application-specific fonts instead of or in addition to the normal system fonts. @@ -53081,10 +53066,9 @@ triggering @self. - The `GtkLabel` widget displays a small amount of text. + Displays a small amount of text. -As the name implies, most labels are used to label another widget -such as a [class@Button]. +Most labels are used to label another widget (such as an [class@Entry]). ![An example GtkLabel](label.png) @@ -53170,7 +53154,7 @@ content instead. ## Accessibility -`GtkLabel` uses the %GTK_ACCESSIBLE_ROLE_LABEL role. +`GtkLabel` uses the [enum@Gtk.AccessibleRole.label] role. ## Mnemonics @@ -53215,9 +53199,8 @@ gtk_label_set_mnemonic_widget (GTK_LABEL (label), entry); ## Markup (styled text) -To make it easy to format text in a label (changing colors, -fonts, etc.), label text can be provided in a simple -markup format: +To make it easy to format text in a label (changing colors, fonts, etc.), +label text can be provided in a simple markup format: Here’s how to create a label with a small font: ```c @@ -53228,7 +53211,7 @@ gtk_label_set_markup (GTK_LABEL (label), "<small>Small text</small>" (See the Pango manual for complete documentation] of available tags, [func@Pango.parse_markup]) -The markup passed to [method@Gtk.Label.set_markup] must be valid; for example, +The markup passed to [method@Gtk.Label.set_markup] must be valid XML; for example, literal `<`, `>` and `&` characters must be escaped as `&lt;`, `&gt;`, and `&amp;`. If you pass text obtained from the user, file, or a network to [method@Gtk.Label.set_markup], you’ll want to escape it with @@ -53239,16 +53222,16 @@ on a label; [method@Gtk.Label.set_attributes] may be a simpler way to set attributes in some cases. Be careful though; [struct@Pango.AttrList] tends to cause internationalization problems, unless you’re applying attributes to the entire string (i.e. unless you set the range of each attribute -to [0, %G_MAXINT)). The reason is that specifying the start_index and -end_index for a [struct@Pango.Attribute] requires knowledge of the exact +to [0, `G_MAXINT`)). The reason is that specifying the `start_index` and +`end_index` for a [struct@Pango.Attribute] requires knowledge of the exact string being displayed, so translations will cause problems. ## Selectable labels Labels can be made selectable with [method@Gtk.Label.set_selectable]. -Selectable labels allow the user to copy the label contents to -the clipboard. Only labels that contain useful-to-copy information—such -as error messages—should be made selectable. +Selectable labels allow the user to copy the label contents to the +clipboard. Only labels that contain useful-to-copy information — such +as error messages — should be made selectable. ## Text layout @@ -53276,11 +53259,11 @@ labels will be rewrapped to use all of the available width. ## Links GTK supports markup for clickable hyperlinks in addition to regular Pango -markup. The markup for links is borrowed from HTML, using the `<a>` with -“href“, “title“ and “class“ attributes. GTK renders links similar to the -way they appear in web browsers, with colored, underlined text. The “title“ -attribute is displayed as a tooltip on the link. The “class“ attribute is -used as style class on the CSS node for the link. +markup. The markup for links is borrowed from HTML, using the `<a>` tag +with “href“, “title“ and “class“ attributes. GTK renders links similar to +the way they appear in web browsers, with colored, underlined text. The +“title“ attribute is displayed as a tooltip on the link. The “class“ +attribute is used as style class on the CSS node for the link. An example of inline links looks like this: @@ -53303,20 +53286,20 @@ with the [signal@Gtk.Label::activate-link] signal and the Creates a new label with the given text inside it. -You can pass %NULL to get an empty label widget. +You can pass `NULL` to get an empty label widget. - the new `GtkLabel` + the new label - The text of the label + the text of the label - Creates a new `GtkLabel`, containing the text in @str. + Creates a new label with the given text inside it, and a mnemonic. If characters in @str are preceded by an underscore, they are underlined. If you need a literal underscore character in a label, use @@ -53326,17 +53309,17 @@ to activate another widget, chosen automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. If [method@Gtk.Label.set_mnemonic_widget] is not called, then the first -activatable ancestor of the `GtkLabel` will be chosen as the mnemonic +activatable ancestor of the label will be chosen as the mnemonic widget. For instance, if the label is inside a button or menu item, the button or menu item will automatically become the mnemonic widget and be activated by the mnemonic. - the new `GtkLabel` + the new label - The text of the label, with an underscore in front of the + the text of the label, with an underscore in front of the mnemonic character @@ -53357,13 +53340,13 @@ attributes for the label, use - a `GtkLabel` + a label - Returns the URI for the currently active link in the label. + Returns the URI for the active link in the label. The active link is the one under the mouse pointer or, in a selectable label, the link in which the text cursor is currently @@ -53372,33 +53355,33 @@ positioned. This function is intended for use in a [signal@Gtk.Label::activate-link] handler or for use in a [signal@Gtk.Widget::query-tooltip] handler. - the currently active URI + the active URI - a `GtkLabel` + a label - Returns the ellipsizing position of the label. + Returns the ellipsization mode of the label. See [method@Gtk.Label.set_ellipsize]. - `PangoEllipsizeMode` + the ellipsization mode - a `GtkLabel` + a label - Gets the extra menu model of @label. + Gets the extra menu model of the label. See [method@Gtk.Label.set_extra_menu]. @@ -53407,7 +53390,7 @@ See [method@Gtk.Label.set_extra_menu]. - a `GtkLabel` + a label @@ -53417,12 +53400,12 @@ See [method@Gtk.Label.set_extra_menu]. See [method@Gtk.Label.set_justify]. - `GtkJustification` + the justification value - a `GtkLabel` + a label @@ -53433,19 +53416,18 @@ See [method@Gtk.Label.set_justify]. The returned text includes any embedded underlines indicating mnemonics and Pango markup. (See [method@Gtk.Label.get_text]). - the text of the label widget. This string is - owned by the widget and must not be modified or freed. + the text of the label widget - a `GtkLabel` + a label - Gets the `PangoLayout` used to display the label. + Gets the Pango layout used to display the label. The layout is useful to e.g. convert text positions to pixel positions, in combination with [method@Gtk.Label.get_layout_offsets]. @@ -53458,25 +53440,25 @@ at any time, so it should be considered read-only. - a `GtkLabel` + a label - Obtains the coordinates where the label will draw its `PangoLayout`. + Obtains the coordinates where the label will draw its Pango layout. The coordinates are useful to convert mouse events into coordinates inside the [class@Pango.Layout], e.g. to take some action if some part of the label is clicked. Remember when using the [class@Pango.Layout] -functions you need to convert to and from pixels using PANGO_PIXELS() +functions you need to convert to and from pixels using `PANGO_PIXELS()` or [const@Pango.SCALE]. - a `GtkLabel` + a label @@ -53495,27 +53477,27 @@ label should be limited. See [method@Gtk.Label.set_lines]. - The number of lines + the number of lines - a `GtkLabel` + a label - Retrieves the desired maximum width of @label, in characters. + Retrieves the maximum width of the label in characters. See [method@Gtk.Label.set_width_chars]. - the maximum width of the label in characters. + the maximum width of the label, in characters - a `GtkLabel` + a label @@ -53532,30 +53514,29 @@ mnemonic set up it returns `GDK_KEY_VoidSymbol`. - a `GtkLabel` + a label - Retrieves the target of the mnemonic (keyboard shortcut) of this -label. + Retrieves the mnemonic target of this label. See [method@Gtk.Label.set_mnemonic_widget]. the target of the label’s mnemonic, - or %NULL if none has been set and the default algorithm will be used. + or `NULL` if none has been set and the default algorithm will be used. - a `GtkLabel` + a label - Returns line wrap mode used by the label. + Returns natural line wrap mode used by the label. See [method@Gtk.Label.set_natural_wrap_mode]. @@ -53564,7 +53545,7 @@ See [method@Gtk.Label.set_natural_wrap_mode]. - a `GtkLabel` + a label @@ -53572,33 +53553,35 @@ See [method@Gtk.Label.set_natural_wrap_mode]. Returns whether the label is selectable. - %TRUE if the user can copy text from the label + true if the user can copy text from the label - a `GtkLabel` + a label - Gets the selected range of characters in the label. + Gets the selected range of characters in the label. + +The returned @start and @end positions are in characters. - %TRUE if selection is non-empty + true if selection is non-empty - a `GtkLabel` + a label - return location for start of selection, as a character offset + return location for start of selection - return location for end of selection, as a character offset + return location for end of selection @@ -53606,48 +53589,45 @@ See [method@Gtk.Label.set_natural_wrap_mode]. Returns whether the label is in single line mode. - %TRUE when the label is in single line mode. + true if the label is in single line mode - a `GtkLabel` + a label - Gets the tabs for @self. + Gets the tab stops for the label. -The returned array will be %NULL if “standard” (8-space) tabs are used. -Free the return value with [method@Pango.TabArray.free]. +The returned array will be `NULL` if “standard” (8-space) tabs are used. copy of default tab array, - or %NULL if standard tabs are used; must be freed with - [method@Pango.TabArray.free]. + or `NULL` if standard tabs are used - a `GtkLabel` + a label - Fetches the text from a label. + Gets the text of the label. The returned text is as it appears on screen. This does not include any embedded underlines indicating mnemonics or Pango markup. (See [method@Gtk.Label.get_label]) - the text in the label widget. This is the internal - string used by the label, and must not be modified. + the text in the label widget - a `GtkLabel` + a label @@ -53657,43 +53637,42 @@ any embedded underlines indicating mnemonics or Pango markup. (See See [method@Gtk.Label.set_use_markup]. - %TRUE if the label’s text will be parsed for markup. + true if the label’s text will be parsed for markup - a `GtkLabel` + a label - Returns whether an embedded underlines in the label indicate mnemonics. + Returns whether underlines in the label indicate mnemonics. See [method@Gtk.Label.set_use_underline]. - %TRUE whether an embedded underline in the label indicates - the mnemonic accelerator keys. + true if underlines in the label indicate mnemonics - a `GtkLabel` + a label - Retrieves the desired width of @label, in characters. + Retrieves the desired width of the label in characters. See [method@Gtk.Label.set_width_chars]. - the width of the label in characters. + the desired width of the label, in characters - a `GtkLabel` + a label @@ -53703,12 +53682,12 @@ See [method@Gtk.Label.set_width_chars]. See [method@Gtk.Label.set_wrap]. - %TRUE if the lines of the label are automatically wrapped. + true if the lines of the label are automatically wrapped - a `GtkLabel` + a label @@ -53723,7 +53702,7 @@ See [method@Gtk.Label.set_wrap_mode]. - a `GtkLabel` + a label @@ -53733,12 +53712,12 @@ See [method@Gtk.Label.set_wrap_mode]. See the [property@Gtk.Label:xalign] property. - the xalign property + the xalign value - a `GtkLabel` + a label @@ -53748,12 +53727,12 @@ See the [property@Gtk.Label:xalign] property. See the [property@Gtk.Label:yalign] property. - the yalign property + the yalign value - a `GtkLabel` + a label @@ -53769,15 +53748,15 @@ this function has no effect. If @start_offset or - a `GtkLabel` + a label - start offset (in characters not bytes) + start offset, in characters - end offset (in characters not bytes) + end offset, in characters @@ -53788,19 +53767,21 @@ this function has no effect. If @start_offset or The attributes set with this function will be applied and merged with any other attributes previously effected by way of the [property@Gtk.Label:use-underline] or [property@Gtk.Label:use-markup] -properties. While it is not recommended to mix markup strings with -manually set attributes, if you must; know that the attributes will -be applied to the label after the markup string is parsed. +properties + +While it is not recommended to mix markup strings with manually set +attributes, if you must; know that the attributes will be applied +to the label after the markup string is parsed. - a `GtkLabel` + a label - a [struct@Pango.AttrList] + a list of style attributes @@ -53808,58 +53789,58 @@ be applied to the label after the markup string is parsed. Sets the mode used to ellipsize the text. -The text will be ellipsized if there is not enough space -to render the entire string. +The text will be ellipsized if there is not +enough space to render the entire string. - a `GtkLabel` + a label - a `PangoEllipsizeMode` + the ellipsization mode - Sets a menu model to add when constructing -the context menu for @label. + Sets a menu model to add to the context menu of the label. - a `GtkLabel` + a label - a `GMenuModel` + a menu model - Sets the alignment of the lines in the text of the label relative to -each other. + Sets the alignment of lines in the label relative to each other. + +This function has no effect on labels containing only a single line. + +[enum@Gtk.Justification.left] is the default value when the widget +is first created with [ctor@Gtk.Label.new]. -%GTK_JUSTIFY_LEFT is the default value when the widget is first created -with [ctor@Gtk.Label.new]. If you instead want to set the alignment of -the label as a whole, use [method@Gtk.Widget.set_halign] instead. -[method@Gtk.Label.set_justify] has no effect on labels containing -only a single line. +If you instead want to set the alignment of the label as a whole, +use [method@Gtk.Widget.set_halign] instead. - a `GtkLabel` + a label - a `GtkJustification` + the new justification @@ -53875,7 +53856,7 @@ and [property@Gtk.Label:use-markup] properties. - a `GtkLabel` + a label @@ -53895,7 +53876,7 @@ Set this to -1 if you don’t want to limit the number of lines. - a `GtkLabel` + a label @@ -53910,8 +53891,8 @@ Set this to -1 if you don’t want to limit the number of lines. The string must be marked up with Pango markup (see [func@Pango.parse_markup]). -If the @str is external data, you may need to escape it -with g_markup_escape_text() or g_markup_printf_escaped(): +If @str is external data, you may need to escape it +with [func@GLib.markup_escape_text] or [func@GLib.markup_printf_escaped]: ```c GtkWidget *self = gtk_label_new (NULL); @@ -53924,24 +53905,20 @@ gtk_label_set_markup (GTK_LABEL (self), markup); g_free (markup); ``` -This function will set the [property@Gtk.Label:use-markup] property -to %TRUE as a side effect. - -If you set the label contents using the [property@Gtk.Label:label] -property you should also ensure that you set the -[property@Gtk.Label:use-markup] property accordingly. +This function sets the [property@Gtk.Label:use-markup] property +to true. -See also: [method@Gtk.Label.set_text] +Also see [method@Gtk.Label.set_text]. - a `GtkLabel` + a label - a markup string + the markup string @@ -53961,27 +53938,27 @@ automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. - a `GtkLabel` + a label - a markup string + the markup string - Sets the desired maximum width in characters of @label to @n_chars. + Sets the maximum width of the label in characters. - a `GtkLabel` + a label - the new desired maximum width, in characters. + the new maximum width, in characters. @@ -53993,33 +53970,33 @@ If the label has been set so that it has a mnemonic key (using i.e. [method@Gtk.Label.set_markup_with_mnemonic], [method@Gtk.Label.set_text_with_mnemonic], [ctor@Gtk.Label.new_with_mnemonic] -or the [property@Gtk.Label:use_underline] property) the label can be -associated with a widget that is the target of the mnemonic. When the -label is inside a widget (like a [class@Gtk.Button] or a -[class@Gtk.Notebook] tab) it is automatically associated with the correct -widget, but sometimes (i.e. when the target is a [class@Gtk.Entry] next to -the label) you need to set it explicitly using this function. +or the [property@Gtk.Label:use_underline] property) the label can +be associated with a widget that is the target of the mnemonic. +When the label is inside a widget (like a [class@Gtk.Button] or a +[class@Gtk.Notebook] tab) it is automatically associated with the +correct widget, but sometimes (i.e. when the target is a [class@Gtk.Entry] +next to the label) you need to set it explicitly using this function. The target widget will be accelerated by emitting the -[signal@Gtk.Widget::mnemonic-activate] signal on it. The default handler for -this signal will activate the widget if there are no mnemonic collisions -and toggle focus between the colliding widgets otherwise. +[signal@Gtk.Widget::mnemonic-activate] signal on it. The default handler +for this signal will activate the widget if there are no mnemonic +collisions and toggle focus between the colliding widgets otherwise. - a `GtkLabel` + a label - the target `GtkWidget`, or %NULL to unset + the target widget - Select the line wrapping for the natural size request. + Selects the line wrapping for the natural size request. This only affects the natural size requested, for the actual wrapping used, see the [property@Gtk.Label:wrap-mode] property. @@ -54028,7 +54005,7 @@ see the [property@Gtk.Label:wrap-mode] property. - a `GtkLabel` + a label @@ -54047,11 +54024,11 @@ for copy-and-paste. - a `GtkLabel` + a label - %TRUE to allow selecting text in the label + true to allow selecting text in the label @@ -54063,60 +54040,56 @@ for copy-and-paste. - a `GtkLabel` + a label - %TRUE if the label should be in single line mode + true to enable single line mode - Sets the default tab stops for paragraphs in @self. + Sets tab stops for the label. - a `GtkLabel` + a label - tabs as a `PangoTabArray` + tab stops - Sets the text within the `GtkLabel` widget. - -It overwrites any text that was there before. + Sets the text for the label. -This function will clear any previously set mnemonic accelerators, -and set the [property@Gtk.Label:use-underline] property to %FALSE as -a side effect. +It overwrites any text that was there before and clears any +previously set mnemonic accelerators, and sets the +[property@Gtk.Label:use-underline] and +[property@Gtk.Label:use-markup] properties to false. -This function will set the [property@Gtk.Label:use-markup] property -to %FALSE as a side effect. - -See also: [method@Gtk.Label.set_markup] +Also see [method@Gtk.Label.set_markup]. - a `GtkLabel` + a label - The text you want to set + the text to show in @self - Sets the label’s text from the string @str. + Sets the text for the label, with mnemonics. If characters in @str are preceded by an underscore, they are underlined indicating that they represent a keyboard accelerator called a mnemonic. @@ -54127,11 +54100,11 @@ automatically, or explicitly using [method@Gtk.Label.set_mnemonic_widget]. - a `GtkLabel` + a label - a string + the text @@ -54145,11 +54118,11 @@ See [method@Gtk.Label.set_markup]. - a `GtkLabel` + a label - %TRUE if the label’s text should be parsed for markup. + true if the label’s text should be parsed for markup. @@ -54161,23 +54134,23 @@ See [method@Gtk.Label.set_markup]. - a `GtkLabel` + a label - %TRUE if underlines in the text indicate mnemonics + true if underlines in the text indicate mnemonics - Sets the desired width in characters of @label to @n_chars. + Sets the desired width in characters of the label. - a `GtkLabel` + a label @@ -54187,27 +54160,27 @@ See [method@Gtk.Label.set_markup]. - Toggles line wrapping within the `GtkLabel` widget. + Toggles line wrapping within the label. -%TRUE makes it break lines if text exceeds the widget’s size. -%FALSE lets the text get cut off by the edge of the widget if +True makes it break lines if text exceeds the widget’s size. +false lets the text get cut off by the edge of the widget if it exceeds the widget size. -Note that setting line wrapping to %TRUE does not make the label -wrap at its parent container’s width, because GTK widgets -conceptually can’t make their requisition depend on the parent -container’s size. For a label that wraps at a specific position, -set the label’s width using [method@Gtk.Widget.set_size_request]. +Note that setting line wrapping to true does not make the label +wrap at its parent widget’s width, because GTK widgets conceptually +can’t make their requisition depend on the parent widget’s size. +For a label that wraps at a specific position, set the label’s width +using [method@Gtk.Widget.set_size_request]. - a `GtkLabel` + a label - the setting + whether to wrap lines @@ -54216,17 +54189,19 @@ set the label’s width using [method@Gtk.Widget.set_size_request]. Controls how line wrapping is done. This only affects the label if line wrapping is on. (See -[method@Gtk.Label.set_wrap]) The default is %PANGO_WRAP_WORD -which means wrap on word boundaries. +[method@Gtk.Label.set_wrap]) -For sizing behavior, also consider the [property@Gtk.Label:natural-wrap-mode] -property. +The default is [enum@Pango.WrapMode.word], which means +wrap on word boundaries. + +For sizing behavior, also consider the +[property@Gtk.Label:natural-wrap-mode] property. - a `GtkLabel` + a label @@ -54244,7 +54219,7 @@ See the [property@Gtk.Label:xalign] property. - a `GtkLabel` + a label @@ -54262,7 +54237,7 @@ See the [property@Gtk.Label:yalign] property. - a `GtkLabel` + a label @@ -54280,10 +54255,11 @@ See the [property@Gtk.Label:yalign] property. not have enough room to display the entire string. Note that setting this property to a value other than -%PANGO_ELLIPSIZE_NONE has the side-effect that the label requests +[enum.Pango.EllipsizeMode.none] has the side-effect that the label requests only enough space to display the ellipsis "...". In particular, this means that ellipsizing labels do not work well in notebook tabs, unless -the [property@Gtk.NotebookPage:tab-expand] child property is set to %TRUE. +the [property@Gtk.NotebookPage:tab-expand] child property is set to true. + Other ways to set a label's width are [method@Gtk.Widget.set_size_request] and [method@Gtk.Label.set_width_chars]. @@ -54304,13 +54280,13 @@ See [property@Gtk.Label:xalign] for that. If the string contains Pango markup (see [func@Pango.parse_markup]), you will have to set the [property@Gtk.Label:use-markup] property to -%TRUE in order for the label to display the markup attributes. See also +true in order for the label to display the markup attributes. See also [method@Gtk.Label.set_markup] for a convenience function that sets both this property and the [property@Gtk.Label:use-markup] property at the same time. If the string contains underlines acting as mnemonics, you will have to -set the [property@Gtk.Label:use-underline] property to %TRUE in order +set the [property@Gtk.Label:use-underline] property to true in order for the label to display them. @@ -54319,6 +54295,7 @@ for the label to display them. should be limited. This property has no effect if the label is not wrapping or ellipsized. + Set this property to -1 if you don't want to limit the number of lines. @@ -54327,8 +54304,8 @@ Set this property to -1 if you don't want to limit the number of lines. If this property is set to -1, the width will be calculated automatically. -See the section on [text layout](class.Label.html#text-layout) for details of how -[property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] +See the section on [text layout](class.Label.html#text-layout) for details +of how [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] determine the width of ellipsized and wrapped labels. @@ -54343,11 +54320,11 @@ determine the width of ellipsized and wrapped labels. Select the line wrapping for the natural size request. -This only affects the natural size requested. For the actual wrapping used, -see the [property@Gtk.Label:wrap-mode] property. +This only affects the natural size requested. For the actual wrapping +used, see the [property@Gtk.Label:wrap-mode] property. -The default is %GTK_NATURAL_WRAP_INHERIT, which inherits the behavior of the -[property@Gtk.Label:wrap-mode] property. +The default is [enum@Gtk.NaturalWrapMode.inherit], which inherits +the behavior of the [property@Gtk.Label:wrap-mode] property. @@ -54368,13 +54345,13 @@ of text changes would be distracting, e.g. in a statusbar. - %TRUE if the text of the label includes Pango markup. + True if the text of the label includes Pango markup. See [func@Pango.parse_markup]. - %TRUE if the text of the label indicates a mnemonic with an _ + True if the text of the label indicates a mnemonic with an `_` before the mnemonic character. @@ -54383,20 +54360,20 @@ before the mnemonic character. If this property is set to -1, the width will be calculated automatically. -See the section on [text layout](class.Label.html#text-layout) for details of how -[property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] +See the section on [text layout](class.Label.html#text-layout) for details +of how [property@Gtk.Label:width-chars] and [property@Gtk.Label:max-width-chars] determine the width of ellipsized and wrapped labels. - %TRUE if the label text will wrap if it gets too wide. + True if the label text will wrap if it gets too wide. Controls how the line wrapping is done. This only affects the formatting if line wrapping is on (see the -[property@Gtk.Label:wrap] property). The default is %PANGO_WRAP_WORD, +[property@Gtk.Label:wrap] property). The default is [enum@Pango.WrapMode.word], which means wrap on word boundaries. For sizing behavior, also consider the [property@Gtk.Label:natural-wrap-mode] @@ -54420,7 +54397,7 @@ labels size allocation is positioned in the space available for the label. Gets emitted when the user activates a link in the label. -The ::activate-current-link is a [keybinding signal](class.SignalAction.html). +The `::activate-current-link` is a [keybinding signal](class.SignalAction.html). Applications may also emit the signal with g_signal_emit_by_name() if they need to control activation of URIs programmatically. @@ -54436,7 +54413,7 @@ The default bindings for this signal are all forms of the <kbd>Enter</k Applications may connect to it to override the default behaviour, which is to call [method@Gtk.FileLauncher.launch]. - %TRUE if the link has been activated + true if the link has been activated @@ -54449,7 +54426,7 @@ which is to call [method@Gtk.FileLauncher.launch]. Gets emitted to copy the selection to the clipboard. -The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html). +The `::copy-clipboard` signal is a [keybinding signal](class.SignalAction.html). The default binding for this signal is <kbd>Ctrl</kbd>+<kbd>c</kbd>. @@ -54459,16 +54436,16 @@ The default binding for this signal is <kbd>Ctrl</kbd>+<kbd>c& Gets emitted when the user initiates a cursor movement. -The ::move-cursor signal is a [keybinding signal](class.SignalAction.html). +The `::move-cursor` signal is a [keybinding signal](class.SignalAction.html). If the cursor is not visible in @entry, this signal causes the viewport to be moved instead. Applications should not connect to it, but may emit it with -g_signal_emit_by_name() if they need to control the cursor -programmatically. +[func@GObject.signal_emit_by_name] if they need to control +the cursor programmatically. -The default bindings for this signal come in two variants, -the variant with the <kbd>Shift</kbd> modifier extends the selection, +The default bindings for this signal come in two variants, the +variant with the <kbd>Shift</kbd> modifier extends the selection, the variant without the <kbd>Shift</kbd> modifier does not. There are too many key combinations to list them all here. @@ -54489,7 +54466,7 @@ There are too many key combinations to list them all here. - %TRUE if the move should extend the selection + true if the move should extend the selection @@ -61593,37 +61570,36 @@ cursor position. - `GtkMultiFilter` is the base class for filters that combine multiple filters. + Base class for filters that combine multiple filters. - Adds a @filter to @self to use for matching. + Adds a filter. - a `GtkMultiFilter` + a multi filter - A new filter to use + a filter to add - Removes the filter at the given @position from the list of filters used -by @self. + Removes a filter. -If @position is larger than the number of filters, nothing happens and -the function returns. +If @position is larger than the number of filters, +nothing happens. - a `GtkMultiFilter` + a multi filter @@ -61633,11 +61609,15 @@ the function returns. - The type of items. See [method@Gio.ListModel.get_item_type]. + The type of items. + +See [method@Gio.ListModel.get_item_type]. - The number of items. See [method@Gio.ListModel.get_n_items]. + The number of items. + +See [method@Gio.ListModel.get_n_items]. @@ -75655,9 +75635,10 @@ size for children calling. See [func@distribute_natural_allocation]. - A `GtkRequisition` represents the desired size of a widget. See -[GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) for -more information. + Represents the desired size of a widget. + +See [GtkWidget’s geometry management section](class.Widget.html#height-for-width-geometry-management) +for more information. the widget’s desired width @@ -75671,9 +75652,7 @@ more information. The struct is initialized to zero. - a new empty `GtkRequisition`. The newly - allocated `GtkRequisition` should be freed with - [method@Gtk.Requisition.free] + a new empty `GtkRequisition` @@ -86743,10 +86722,9 @@ stack with the exact @context_id. - `GtkStringFilter` determines whether to include items by comparing -strings to a fixed search term. + Determines whether to include items by comparing strings to a fixed search term. -The strings are obtained from the items by evaluating a `GtkExpression` +The strings are obtained from the items by evaluating an expression set with [method@Gtk.StringFilter.set_expression], and they are compared against a search term set with [method@Gtk.StringFilter.set_search]. @@ -86767,7 +86745,7 @@ and by providing a property to look up on the item. - The expression to evaluate + the expression to evaluate @@ -86776,12 +86754,12 @@ and by providing a property to look up on the item. Gets the expression that the string filter uses to obtain strings from items. - a `GtkExpression` + the expression - a `GtkStringFilter` + a string filter @@ -86789,12 +86767,12 @@ obtain strings from items. Returns whether the filter ignores case differences. - %TRUE if the filter ignores case + true if the filter ignores case - a `GtkStringFilter` + a string filter @@ -86807,7 +86785,7 @@ obtain strings from items. - a `GtkStringFilter` + a string filter @@ -86815,12 +86793,12 @@ obtain strings from items. Gets the search term. - The search term + the search term - a `GtkStringFilter` + a string filter @@ -86829,17 +86807,17 @@ obtain strings from items. Sets the expression that the string filter uses to obtain strings from items. -The expression must have a value type of %G_TYPE_STRING. +The expression must have a value type of `G_TYPE_STRING`. - a `GtkStringFilter` + a string filter - a `GtkExpression` + the expression @@ -86851,11 +86829,11 @@ The expression must have a value type of %G_TYPE_STRING. - a `GtkStringFilter` + a string filter - %TRUE to ignore case + true to ignore case @@ -86867,7 +86845,7 @@ The expression must have a value type of %G_TYPE_STRING. - a `GtkStringFilter` + a string filter @@ -86883,18 +86861,18 @@ The expression must have a value type of %G_TYPE_STRING. - a `GtkStringFilter` + a string filter - The string to search for - or %NULL to clear the search + the string to search for - The expression to evaluate on item to get a string to compare with. + The expression to evaluate on each item to get a +string to compare with. @@ -86919,15 +86897,15 @@ The expression must have a value type of %G_TYPE_STRING. Specifies how search strings are matched inside text. The search string and - text must match exactly. + text must match exactly The search string - must be contained as a substring inside the text. + must be contained as a substring inside the text The text must begin - with the search string. + with the search string @@ -88502,29 +88480,29 @@ See also: [method@Gtk.TreeSortable.set_sort_column_id] - The `GtkText` widget is a single-line text entry widget. + A single-line text entry. `GtkText` is the common implementation of single-line text editing that is shared between [class@Gtk.Entry], [class@Gtk.PasswordEntry], -[class@Gtk.SpinButton], and other widgets. In all of these, `GtkText` is -used as the delegate for the [iface@Gtk.Editable] implementation. +[class@Gtk.SpinButton], and other widgets. In all of these, a `GtkText` +instance is used as the delegate for the [iface@Gtk.Editable] implementation. -A fairly large set of key bindings are supported by default. If the -entered text is longer than the allocation of the widget, the widget -will scroll so that the cursor position is visible. +A large number of key bindings s supported by default. If the entered +text is longer than the allocation of the widget, the widget will scroll +so that the cursor position is visible. When using an entry for passwords and other sensitive information, it can be put into “password mode” using [method@Gtk.Text.set_visibility]. -In this mode, entered text is displayed using a “invisible” character. +In this mode, entered text is displayed using an “invisible” character. By default, GTK picks the best invisible character that is available in the current font, but it can be changed with [method@Gtk.Text.set_invisible_char]. -If you are looking to add icons or progress display in an entry, look -at [class@Gtk.Entry]. There other alternatives for more specialized use -cases, such as [class@Gtk.SearchEntry]. +If you want to add icons or progress display in an entry, look at +[class@Gtk.Entry]. There are other alternatives for more specialized +use cases, such as [class@Gtk.SearchEntry]. -If you need multi-line editable text, look at [class@Gtk.TextView]. +If you need multi-line editable text, use [class@Gtk.TextView]. # Shortcuts and Gestures @@ -88576,6 +88554,7 @@ text[.read-only] ├── undershoot.right ├── [selection] ├── [block-cursor] +├── [cursor-handle[.top/.bottom][.insertion-cursor]] ╰── [window.popup] ``` @@ -88601,7 +88580,7 @@ there is just a single handle for the text cursor, it gets the style class # Accessibility -`GtkText` uses the %GTK_ACCESSIBLE_ROLE_NONE role, which causes it to be +`GtkText` uses the [enum@Gtk.AccessibleRole.none] role, which causes it to be skipped for accessibility. This is because `GtkText` is expected to be used as a delegate for a `GtkEditable` implementation that will be represented to accessibility. @@ -88613,26 +88592,26 @@ to accessibility. Creates a new `GtkText`. - a new `GtkText`. + the new `GtkText` - Creates a new `GtkText` with the specified text buffer. + Creates a new `GtkText` with the specified buffer. a new `GtkText` - The buffer to use for the new `GtkText`. + the buffer to use for the new `GtkText`. - Determine the positions of the strong and weak cursors if the -insertion point in the layout is at @position. + Determine the positions of the strong and weak cursors for a +given character position. The position of each cursor is stored as a zero-width rectangle. The strong cursor location is the location where characters of @@ -88646,7 +88625,7 @@ The rectangle positions are in widget coordinates. - a `GtkText` + a text widget @@ -88664,23 +88643,23 @@ The rectangle positions are in widget coordinates. - Returns whether pressing Enter will activate -the default widget for the window containing @self. + Returns whether pressing <kbd>Enter</kbd> will activate +the default widget for the window containing the widget. See [method@Gtk.Text.set_activates_default]. - %TRUE if the `GtkText` will activate the default widget + true if @self will activate the default widget - a `GtkText` + a text widget - Gets the attribute list that was set on the `GtkText`. + Gets the attribute list that was set on the text widget. See [method@Gtk.Text.set_attributes]. @@ -88689,41 +88668,40 @@ See [method@Gtk.Text.set_attributes]. - a `GtkText` + a text widget - Get the `GtkEntryBuffer` object which holds the text for + Get the entry buffer object which holds the text for this widget. - A `GtkEntryBuffer` object. + the entry buffer object - a `GtkText` + a text widget - Returns whether Emoji completion is enabled for this -`GtkText` widget. + Returns whether Emoji completion is enabled. - %TRUE if Emoji completion is enabled + true if Emoji completion is enabled - a `GtkText` + a text widget - Gets the menu model for extra items in the context menu. + Gets the extra menu model of the text widget. See [method@Gtk.Text.set_extra_menu]. @@ -88732,33 +88710,33 @@ See [method@Gtk.Text.set_extra_menu]. - a `GtkText` + a text widget - Gets the input hints of the `GtkText`. + Gets the input hints of the text widget. the input hints - a `GtkText` + a text widget - Gets the input purpose of the `GtkText`. + Gets the input purpose of the text widget. the input purpose - a `GtkText` + a text widget @@ -88771,208 +88749,208 @@ so the value returned by this function is not very useful unless it has been explicitly set with [method@Gtk.Text.set_invisible_char]. the current invisible char, or 0, if @text does not - show invisible text at all. + show invisible text at all - a `GtkText` + a text widget - Retrieves the maximum allowed length of the text in @self. + Retrieves the maximum allowed length of the contents. See [method@Gtk.Text.set_max_length]. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_max_length] on it. - the maximum allowed number of characters - in `GtkText`, or 0 if there is no maximum. + the maximum allowed number of characters, or 0 if + there is no limit - a `GtkText` + a text widget - Gets whether text is overwritten when typing in the `GtkText`. + Gets whether text is overwritten when typing. See [method@Gtk.Text.set_overwrite_mode]. - whether the text is overwritten when typing + whether text is overwritten when typing - a `GtkText` + a text widget - Retrieves the text that will be displayed when -@self is empty and unfocused + Retrieves the text that will be displayed when the text widget +is empty and unfocused -If no placeholder text has been set, %NULL will be returned. +See [method@Gtk.Text.set_placeholder_text]. the placeholder text - a `GtkText` + a text widget - Returns whether the `GtkText` will grow and shrink + Returns whether the text widget will grow and shrink with the content. - %TRUE if @self will propagate the text width + true if @self will propagate the text width - a `GtkText` + a text widget - Gets the tabstops that were set on the `GtkText`. + Gets the tab stops for the text widget. See [method@Gtk.Text.set_tabs]. - the tabstops + the tab stops - a `GtkText` + a text widget - Retrieves the current length of the text in @self. + Retrieves the length of the contents. This is equivalent to getting @self's `GtkEntryBuffer` and calling [method@Gtk.EntryBuffer.get_length] on it. - the current number of characters - in `GtkText`, or 0 if there are none. + the length of the contents, in characters - a `GtkText` + a text widget - Returns whether the `GtkText` will truncate multi-line text -that is pasted into the widget + Returns whether pasted text will be truncated to the first line. - %TRUE if @self will truncate multi-line text + true if @self will truncate pasted multi-line text - a `GtkText` + a text widget - Retrieves whether the text in @self is visible. + Retrieves whether the text is visible. - %TRUE if the text is currently visible + true if the text is visible - a `GtkText` + a text widget - Causes @self to have keyboard focus. + Causes the text widget to have the keyboard focus. It behaves like [method@Gtk.Widget.grab_focus], -except that it doesn't select the contents of @self. +except that it does not select the contents of @self. + You only want to call this on some special entries -which the user usually doesn't want to replace all text in, -such as search-as-you-type entries. +which the user usually doesn't want to replace all +text in, such as search-as-you-type entries. - %TRUE if focus is now inside @self + true if focus is now inside @self - a `GtkText` + a text widget - If @activates is %TRUE, pressing Enter will activate -the default widget for the window containing @self. + Sets whether pressing <kbd>Enter</kbd> will activate +the default widget. -This usually means that the dialog containing the `GtkText` -will be closed, since the default widget is usually one of +This usually means that the dialog containing @self will +be closed, since the default widget is usually one of the dialog buttons. - a `GtkText` + a text widget - %TRUE to activate window’s default widget on Enter keypress + true to activate window’s default widget on + <kbd>Enter</kbd> keypress - Sets attributes that are applied to the text. + Apply attributes to the contents of the text widget. - a `GtkText` + a text widget - a `PangoAttrList` + a list of style attributes - Set the `GtkEntryBuffer` object which holds the text for + Set the entry buffer object which holds the text for this widget. - a `GtkText` + a text widget - a `GtkEntryBuffer` + an entry buffer object @@ -88988,51 +88966,49 @@ keyword. - a `GtkText` + a text widget - %TRUE to enable Emoji completion + true to enable Emoji completion - Sets a menu model to add when constructing -the context menu for @self. + Sets a menu model to add to the context menu of the text widget. - a `GtkText` + a text widget - a `GMenuModel` + a menu model - Sets input hints that allow input methods -to fine-tune their behaviour. + Sets hints that allow input methods to fine-tune their behaviour. - a `GtkText` + a text widget - the hints + input hints - Sets the input purpose of the `GtkText`. + Sets the input purpose of the text widget. This can be used by on-screen keyboards and other input methods to adjust their behaviour. @@ -89041,11 +89017,11 @@ input methods to adjust their behaviour. - a `GtkText` + a text widget - the purpose + the input purpose @@ -89062,7 +89038,7 @@ as they type. - a `GtkText` + a text widget @@ -89072,9 +89048,9 @@ as they type. - Sets the maximum allowed length of the contents of the widget. + Sets the maximum allowed length of the contents. -If the current contents are longer than the given length, then +If the current contents are longer than the given length, they will be truncated to fit. This is equivalent to getting @self's `GtkEntryBuffer` and @@ -89084,26 +89060,25 @@ calling [method@Gtk.EntryBuffer.set_max_length] on it. - a `GtkText` + a text widget - the maximum length of the `GtkText`, or 0 for no maximum. + the maximum length of the text, or 0 for no maximum. (other than the maximum length of entries.) The value passed - in will be clamped to the range 0-65536. + in will be clamped to the range 0-65536 - Sets whether the text is overwritten when typing -in the `GtkText`. + Sets whether the text is overwritten when typing. - a `GtkText` + a text widget @@ -89113,16 +89088,17 @@ in the `GtkText`. - Sets text to be displayed in @self when it is empty. + Sets the text to be displayed when the text widget is +empty and unfocused. This can be used to give a visual hint of the expected -contents of the `GtkText`. +contents of the text widget. - a `GtkText` + a text widget @@ -89133,59 +89109,58 @@ contents of the `GtkText`. - Sets whether the `GtkText` should grow and shrink with the content. + Sets whether the text widget should grow and shrink with the content. - a `GtkText` + a text widget - %TRUE to propagate the text width + true to propagate the text width - Sets tabstops that are applied to the text. + Sets tab stops for the text widget. - a `GtkText` + a text widget - a `PangoTabArray` + tab stops - Sets whether the `GtkText` should truncate multi-line text -that is pasted into the widget. + Sets whether pasted text should be truncated to the first line. - a `GtkText` + a text widget - %TRUE to truncate multi-line text + true to truncate multi-line text - Sets whether the contents of the `GtkText` are visible or not. + Sets whether the contents of the text widget are visible or not. -When visibility is set to %FALSE, characters are displayed -as the invisible char, and will also appear that way when +When visibility is set to false, characters are displayed +as the invisible char, and it will also appear that way when the text in the widget is copied to the clipboard. By default, GTK picks the best invisible character available @@ -89193,20 +89168,20 @@ in the current font, but it can be changed with [method@Gtk.Text.set_invisible_char]. Note that you probably want to set [property@Gtk.Text:input-purpose] -to %GTK_INPUT_PURPOSE_PASSWORD or %GTK_INPUT_PURPOSE_PIN to -inform input methods about the purpose of this self, -in addition to setting visibility to %FALSE. +to [enum@Gtk.InputPurpose.password] or [enum@Gtk.InputPurpose.pin] +to inform input methods about the purpose of this widget, in addition +to setting visibility to false. - a `GtkText` + a text widget - %TRUE if the contents of the `GtkText` are displayed - as plaintext + true if the contents of the text widget are displayed + as plain text @@ -89221,17 +89196,17 @@ char is used again. - a `GtkText` + a text widget - Whether to activate the default widget when Enter is pressed. + Whether to activate the default widget when <kbd>Enter</kbd> is pressed. - A list of Pango attributes to apply to the text of the `GtkText`. + A list of Pango attributes to apply to the text. This is mainly useful to change the size or weight of the text. @@ -89248,18 +89223,17 @@ The `PangoAttribute`'s @start_index and @end_index must refer to the - A menu model whose contents will be appended to -the context menu. + A menu model whose contents will be appended to the context menu. - Which IM (input method) module should be used for this self. + Which input method module should be used. See [class@Gtk.IMMulticontext]. -Setting this to a non-%NULL value overrides the system-wide -IM module setting. See the [property@Gtk.Settings:gtk-im-module] -property. +Setting this to a non-`NULL` value overrides the system-wide +input method. See the [property@Gtk.Settings:gtk-im-module] +setting. @@ -89270,11 +89244,11 @@ their behaviour. The purpose of this text field. -This property can be used by on-screen keyboards and other input +This information can be used by on-screen keyboards and other input methods to adjust their behaviour. -Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or -%GTK_INPUT_PURPOSE_PIN is independent from setting +Note that setting the purpose to [enum@Gtk.InputPurpose.password] +or [enum@Gtk.InputPurpose.pin] is independent from setting [property@Gtk.Text:visibility]. @@ -89283,7 +89257,7 @@ Note that setting the purpose to %GTK_INPUT_PURPOSE_PASSWORD or - Whether the invisible char has been set for the `GtkText`. + Whether the invisible char has been set. @@ -89293,7 +89267,7 @@ Zero indicates no limit. - If text is overwritten when typing in the `GtkText`. + If text is overwritten when typing. @@ -89310,15 +89284,15 @@ and unfocused. - A list of tabstops to apply to the text of the `GtkText`. + Custom tabs for this text widget. - When %TRUE, pasted multi-line text is truncated to the first line. + When true, pasted multi-line text is truncated to the first line. - If %FALSE, the text is masked with the “invisible char”. + If false, the text is masked with the “invisible char”. @@ -89373,9 +89347,9 @@ The default bindings for this signal are This is a [keybinding signal](class.SignalAction.html). -If the @type is %GTK_DELETE_CHARS, GTK deletes the selection -if there is one, otherwise it deletes the requested number -of characters. +If the @type is [enum@Gtk.DeleteType.chars], GTK deletes the +selection if there is one, otherwise it deletes the requested +number of characters. The default bindings for this signal are <kbd>Delete</kbd> for deleting a character and <kbd>Ctrl</kbd>+<kbd>Delete</kbd> @@ -89385,7 +89359,7 @@ for deleting a word. - the granularity of the deletion, as a `GtkDeleteType` + the granularity of the deletion @@ -89449,7 +89423,7 @@ There are too many key combinations to list them all here. - the granularity of the move, as a `GtkMovementStep` + the granularity of the move @@ -89457,7 +89431,7 @@ There are too many key combinations to list them all here. - %TRUE if the move should extend the selection + true if the move should extend the selection @@ -97737,10 +97711,12 @@ drawing with the ::snapshot_layer vfunc. - Callback type for adding a function to update animations. See gtk_widget_add_tick_callback(). + Callback type for adding a function to update animations. + +See [method@Gtk.Widget.add_tick_callback]. - %G_SOURCE_CONTINUE if the tick callback should continue to be called, - %G_SOURCE_REMOVE if the tick callback should be removed. + `G_SOURCE_CONTINUE` if the tick callback should continue + to be called, `G_SOURCE_REMOVE` if it should be removed @@ -97749,11 +97725,11 @@ drawing with the ::snapshot_layer vfunc. - the frame clock for the widget (same as calling gtk_widget_get_frame_clock()) + the frame clock for the widget - user data passed to gtk_widget_add_tick_callback(). + user data passed to [method@Gtk.Widget.add_tick_callback]. @@ -108424,8 +108400,7 @@ has some similarity to strcmp() returning 0 for equal strings. - A `GtkUriLauncher` object collects the arguments that are needed to open a uri -with an application. + Collects the arguments that are needed to open a uri with an application. Depending on system configuration, user preferences and available APIs, this may or may not show an app chooser dialog or launch the default application @@ -108455,13 +108430,13 @@ To launch a file, use [class@Gtk.FileLauncher]. - a `GtkUriLauncher` + an uri launcher - Launch an application to open the uri. + Launches an application to open the uri. This may present an app chooser dialog to the user. @@ -108469,15 +108444,15 @@ This may present an app chooser dialog to the user. - a `GtkUriLauncher` + an uri launcher - the parent `GtkWindow` + the parent window - a `GCancellable` to cancel the operation + a cancellable to cancel the operation @@ -108495,17 +108470,16 @@ This may present an app chooser dialog to the user. Finishes the [method@Gtk.UriLauncher.launch] call and returns the result. - `TRUE` if an application was launched, - or `FALSE` and @error is set + true if an application was launched - a `GtkUriLauncher` + an uri launcher - a `GAsyncResult` + the result @@ -108517,7 +108491,7 @@ returns the result. - a `GtkUriLauncher` + an uri launcher @@ -109091,8 +109065,7 @@ theme, then the normal (potentially colorful) icons will be used. The base class for all widgets. -`GtkWidget` is the base class all widgets in GTK derive from. It manages the -widget lifecycle, layout, states and style. +It manages the widget lifecycle, layout, states and style. ### Height-for-width Geometry Management @@ -109149,7 +109122,7 @@ will be recursively executed while widgets allocate their children. Each widget, once allocated a size, will go on to first share the space in one orientation among its children and then request each child's height for its target allocated width or its width for allocated height, -depending. In this way a `GtkWidget` will typically be requested its size +depending. In this way a widget will typically be requested its size a number of times before actually being allocated a size. The size a widget is finally allocated can of course differ from the size it has requested. For this reason, `GtkWidget` caches a small number of results @@ -109486,11 +109459,11 @@ foo_widget_class_init (FooWidgetClass *klass) - Obtains the current default reading direction. + Obtains the default reading direction. See [func@Gtk.Widget.set_default_direction]. - the current default direction. + the current default direction @@ -109503,7 +109476,8 @@ See [method@Gtk.Widget.set_direction]. - the new default direction. This cannot be %GTK_TEXT_DIR_NONE. + the new default direction, either [enum@Gtk.TextDirection.ltr] + or [enum@Gtk.TextDirection.rtl] @@ -109527,12 +109501,12 @@ See [method@Gtk.Widget.set_direction]. - Tests if the point at (@x, @y) is contained in @widget. + Tests if a given point is contained in the widget. -The coordinates for (@x, @y) must be in widget coordinates, so +The coordinates for (x, y) must be in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. - %TRUE if @widget contains (@x, @y). + true if @widget contains the point (x, y) @@ -109616,27 +109590,28 @@ allocation capabilities. - Causes @widget to have the keyboard focus for the `GtkWindow` it's inside. + Causes @widget to have the keyboard focus for the window +that it belongs to. If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of @widget -that is focusable, it will not take focus and %FALSE will be returned. +that is focusable, it will not take focus and false will be returned. Calling [method@Gtk.Widget.grab_focus] on an already focused widget -is allowed, should not have an effect, and return %TRUE. +is allowed, should not have an effect, and return true. - %TRUE if focus is now inside @widget. + true if focus is now inside @widget - a `GtkWidget` + a widget - Reverses the effects of gtk_widget_show(). + Reverses the effects of [method.Gtk.Widget.show]. This is causing the widget to be hidden (invisible to the user). Use [method@Gtk.Widget.set_visible] instead @@ -109645,48 +109620,49 @@ This is causing the widget to be hidden (invisible to the user). - a `GtkWidget` + a widget - Emits the `::keynav-failed` signal on the widget. + Emits the [signal@Gtk.Widget::keynav-failed] signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary. The return value of this function should be interpreted in a way similar to the return value of -[method@Gtk.Widget.child_focus]. When %TRUE is returned, -stay in the widget, the failed keyboard navigation is OK +[method@Gtk.Widget.child_focus]. When true is returned, +stay in the widget, the failed keyboard navigation is ok and/or there is nowhere we can/should move the focus to. -When %FALSE is returned, the caller should continue with +When false is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [method@Gtk.Widget.child_focus] on the widget’s toplevel. The default [signal@Gtk.Widget::keynav-failed] handler returns -%FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. -For the other values of `GtkDirectionType` it returns %TRUE. +false for [enum@Gtk.DirectionType.tab-forward] and +[enum@Gtk.DirectionType.tab-backward]. For the other values +of [enum@Gtk.DirectionType] it returns true. -Whenever the default handler returns %TRUE, it also calls +Whenever the default handler returns true, it also calls [method@Gtk.Widget.error_bell] to notify the user of the failed keyboard navigation. -A use case for providing an own implementation of ::keynav-failed +A use case for providing an own implementation of `::keynav-failed` (either by connecting to it or by overriding it) would be a row of [class@Gtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. - %TRUE if stopping keyboard navigation is fine, %FALSE + true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard - navigation attempt in its parent container(s). + navigation attempt in its parent widget - a `GtkWidget` + a widget @@ -109704,7 +109680,7 @@ This function is only for use in widget implementations. - a `GtkWidget` + a widget @@ -109759,20 +109735,18 @@ a more details on implementing `GtkWidgetClass.measure()`. - Emits the ::mnemonic-activate signal. - -See [signal@Gtk.Widget::mnemonic-activate]. + Emits the [signal@Gtk.Widget::mnemonic-activate] signal. - %TRUE if the signal has been handled + true if the signal has been handled - a `GtkWidget` + a widget - %TRUE if there are other widgets with the same mnemonic + true if there are other widgets with the same mnemonic @@ -109838,7 +109812,7 @@ called after the widget is realized automatically, such as - a `GtkWidget` + a widget @@ -109856,7 +109830,7 @@ called after the widget is realized automatically, such as - Set @child as the current focus child of @widget. + Set the focus child of the widget. This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call @@ -109866,12 +109840,12 @@ If you want a certain widget to get the input focus, call - a `GtkWidget` + a widget - a direct child widget of @widget or %NULL - to unset the focus child of @widget + a direct child widget of @widget + or `NULL` to unset the focus child @@ -109884,16 +109858,16 @@ Any widget that isn’t shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. -When a toplevel container is shown, it is immediately realized and +When a toplevel widget is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their -toplevel container is realized and mapped. +toplevel widget is realized and mapped. Use [method@Gtk.Widget.set_visible] instead - a `GtkWidget` + a widget @@ -109971,14 +109945,15 @@ This function is only for use in widget implementations. - a `GtkWidget` + a widget - Causes a widget to be unrealized (frees all GDK resources -associated with the widget). + Causes a widget to be unrealized. + +This frees all GDK resources associated with the widget. This function is only useful in widget implementations. @@ -109986,7 +109961,7 @@ This function is only useful in widget implementations. - a `GtkWidget` + a widget @@ -110004,14 +109979,14 @@ This function is only useful in widget implementations. - Enable or disable an action installed with -gtk_widget_class_install_action(). + Enables or disables an action installed with +[method@Gtk.WidgetClass.install_action]. - a `GtkWidget` + a widget @@ -110025,45 +110000,46 @@ gtk_widget_class_install_action(). - For widgets that can be “activated” (buttons, menu items, etc.), -this function activates them. + Activates the widget. The activation will emit the signal set using -[method@Gtk.WidgetClass.set_activate_signal] during class initialization. +[method@Gtk.WidgetClass.set_activate_signal] +during class initialization. Activation is what happens when you press <kbd>Enter</kbd> -on a widget during key navigation. +on a widget. -If you wish to handle the activation keybinding yourself, it is -recommended to use [method@Gtk.WidgetClass.add_shortcut] with an action -created with [ctor@Gtk.SignalAction.new]. +If you wish to handle the activation keybinding yourself, +it is recommended to use [method@Gtk.WidgetClass.add_shortcut] +with an action created with [ctor@Gtk.SignalAction.new]. -If @widget isn't activatable, the function returns %FALSE. +If @widget is not activatable, the function returns false. - %TRUE if the widget was activatable + true if the widget was activated - a `GtkWidget` that’s activatable + a widget that is activatable - Looks up the action in the action groups associated -with @widget and its ancestors, and activates it. + Activates an action for the widget. + +The action is looked up in the action groups associated with +@widget and its ancestors. This is a wrapper around [method@Gtk.Widget.activate_action_variant] that constructs the @args variant according to @format_string. - %TRUE if the action was activated, %FALSE if the action - does not exist + true if the action was activated - a `GtkWidget` + a widget @@ -110071,7 +110047,7 @@ that constructs the @args variant according to @format_string. - GVariant format string for arguments + `GVariant` format string for arguments @@ -110081,8 +110057,10 @@ that constructs the @args variant according to @format_string. - Looks up the action in the action groups associated with -@widget and its ancestors, and activates it. + Activates an action for the widget. + +The action is looked up in the action groups associated with +@widget and its ancestors. If the action is in an action group added with [method@Gtk.Widget.insert_action_group], the @name is expected @@ -110090,15 +110068,14 @@ to be prefixed with the prefix that was used when the group was inserted. The arguments must match the actions expected parameter type, -as returned by `g_action_get_parameter_type()`. +as returned by [method@Gio.Action.get_parameter_type]. - %TRUE if the action was activated, %FALSE if the - action does not exist. + true if the action was activated - a `GtkWidget` + a widget @@ -110112,19 +110089,25 @@ as returned by `g_action_get_parameter_type()`. - Activates the `default.activate` action from @widget. + Activates the `default.activate` action for the widget. + +The action is looked up in the same was as for +[method@Gtk.Widget.activate_action]. - a `GtkWidget` + a widget - Adds @controller to @widget so that it will receive events. + Adds an event controller to the widget. + +The event controllers of a widget handle the events that are +propagated to the widget. You will usually want to call this function right after creating any kind of [class@Gtk.EventController]. @@ -110133,18 +110116,18 @@ creating any kind of [class@Gtk.EventController]. - a `GtkWidget` + a widget - a `GtkEventController` that hasn't been + an event controller that hasn't been added to a widget yet - Adds a style class to @widget. + Adds a style class to the widget. After calling this function, the widget’s style will match for @css_class, according to CSS matching rules. @@ -110156,12 +110139,11 @@ style again. - a `GtkWidget` + a widget - The style class to add to @widget, without - the leading '.' used for notation of style classes + style class to add to @widget, without the leading period @@ -110169,20 +110151,21 @@ style again. Adds a widget to the list of mnemonic labels for this widget. -See [method@Gtk.Widget.list_mnemonic_labels]. Note the -list of mnemonic labels for the widget is cleared when the -widget is destroyed, so the caller must make sure to update -its internal state at this point as well. +See [method@Gtk.Widget.list_mnemonic_labels]. + +Note that the list of mnemonic labels for the widget is cleared +when the widget is destroyed, so the caller must make sure +to update its internal state at this point as well. - a `GtkWidget` + a widget - a `GtkWidget` that acts as a mnemonic label for @widget + a widget that acts as a mnemonic label for @widget @@ -110195,30 +110178,32 @@ Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every -frame or every few frames. The tick callback does not automatically -imply a relayout or repaint. If you want a repaint or relayout, and -aren’t changing widget properties that would trigger that (for example, -changing the text of a `GtkLabel`), then you will have to call -[method@Gtk.Widget.queue_resize] or [method@Gtk.Widget.queue_draw] -yourself. +frame or every few frames. + +The tick callback does not automatically imply a relayout or repaint. +If you want a repaint or relayout, and aren’t changing widget properties +that would trigger that (for example, changing the text of a label), +then you will have to call [method@Gtk.Widget.queue_resize] or +[method@Gtk.Widget.queue_draw] yourself. [method@Gdk.FrameClock.get_frame_time] should generally be used for timing continuous animations and -[method@Gdk.FrameTimings.get_predicted_presentation_time] if you are -trying to display isolated frames at particular times. +[method@Gdk.FrameTimings.get_predicted_presentation_time] should be +used if you are trying to display isolated frames at particular times. This is a more convenient alternative to connecting directly to the -[signal@Gdk.FrameClock::update] signal of `GdkFrameClock`, since you -don't have to worry about when a `GdkFrameClock` is assigned to a widget. +[signal@Gdk.FrameClock::update] signal of the frame clock, since you +don't have to worry about when a frame clock is assigned to a widget. + +To remove a tick callback, pass the ID that is returned by this function +to [method@Gtk.Widget.remove_tick_callback]. - an id for the connection of this callback. Remove the callback - by passing the id returned from this function to - [method@Gtk.Widget.remove_tick_callback] + an ID for this callback - a `GtkWidget` + a widget @@ -110231,20 +110216,21 @@ don't have to worry about when a `GdkFrameClock` is assigned to a widget. - function to call to free @user_data when the callback is removed. + function to call to free @user_data - This function is only used by `GtkWidget` subclasses, to -assign a size, position and (optionally) baseline to their -child widgets. + Assigns size, position, (optionally) a baseline and transform +to a child widget. In this function, the allocation and baseline may be adjusted. The given allocation will be forced to be bigger than the widget's minimum size, as well as at least 0×0 in size. +This function is only used by widget implementations. + For a version that does not take a transform, see [method@Gtk.Widget.size_allocate]. @@ -110252,23 +110238,23 @@ For a version that does not take a transform, see - A `GtkWidget` + a widget - New width of @widget + new width - New height of @widget + new height - New baseline of @widget, or -1 + new baseline, or -1 - Transformation to be applied to @widget + transformation to be applied @@ -110277,30 +110263,30 @@ For a version that does not take a transform, see Called by widgets as the user moves around the window using keyboard shortcuts. -The @direction argument indicates what kind of motion is taking place (up, -down, left, right, tab forward, tab backward). +The @direction argument indicates what kind of motion is taking +place (up, down, left, right, tab forward, tab backward). -This function calls the [vfunc@Gtk.Widget.focus] virtual function; widgets -can override the virtual function in order to implement appropriate focus -behavior. +This function calls the [vfunc@Gtk.Widget.focus] virtual function; +widgets can override the virtual function in order to implement +appropriate focus behavior. -The default `focus()` virtual function for a widget should return `TRUE` if -moving in @direction left the focus on a focusable location inside that -widget, and `FALSE` if moving in @direction moved the focus outside the -widget. When returning `TRUE`, widgets normally call [method@Gtk.Widget.grab_focus] -to place the focus accordingly; when returning `FALSE`, they don’t modify -the current focus location. +The default `focus()` virtual function for a widget should return +true if moving in @direction left the focus on a focusable location +inside that widget, and false if moving in @direction moved the focus +outside the widget. When returning true, widgets normally call +[method@Gtk.Widget.grab_focus] to place the focus accordingly; +when returning false, they don’t modify the current focus location. This function is used by custom widget implementations; if you're writing an app, you’d use [method@Gtk.Widget.grab_focus] to move the focus to a particular widget. - %TRUE if focus ended up inside @widget + true if focus ended up inside @widget - a `GtkWidget` + a widget @@ -110316,23 +110302,23 @@ The bounds of widget are (the bounding box of) the region that it is expected to draw in. See the [coordinate system](coordinates.html) overview to learn more. -If the operation is successful, %TRUE is returned. If @widget has no +If the operation is successful, true is returned. If @widget has no bounds or the bounds cannot be expressed in @target's coordinate space -(for example if both widgets are in different windows), %FALSE is +(for example if both widgets are in different windows), false is returned and @bounds is set to the zero rectangle. It is valid for @widget and @target to be the same widget. - %TRUE if the bounds could be computed + true if the bounds could be computed - the `GtkWidget` to query + the widget to query - the `GtkWidget` + the target widget @@ -110342,10 +110328,10 @@ It is valid for @widget and @target to be the same widget. - Computes whether a container should give this widget + Computes whether a parent widget should give this widget extra space when possible. -Containers should check this, rather than looking at +Widgets with children should check this, rather than looking at [method@Gtk.Widget.get_hexpand] or [method@Gtk.Widget.get_vexpand]. This function already checks whether the widget is visible, so @@ -110361,7 +110347,7 @@ the widget may expand if some of its children do. - the widget + a widget @@ -110372,22 +110358,23 @@ the widget may expand if some of its children do. Translates the given @point in @widget's coordinates to coordinates -relative to @target’s coordinate system. +in @target’s coordinate system. In order to perform this operation, both widgets must share a -common ancestor. +a common ancestor. If that is not the case, @out_point is set +to (0, 0) and false is returned. - %TRUE if the point could be determined, %FALSE on failure. - In this case, 0 is stored in @out_point. + true if @src_widget and @dest_widget have a common + ancestor, false otherwise - the `GtkWidget` to query + the widget to query - the `GtkWidget` to transform into + the widget to transform into @@ -110395,7 +110382,7 @@ common ancestor. - Set to the corresponding coordinates in + set to the corresponding coordinates in @target's coordinate system @@ -110412,12 +110399,12 @@ case @out_transform gets set to the identity matrix. To learn more about widget coordinate systems, see the coordinate system [overview](coordinates.html). - %TRUE if the transform could be computed, %FALSE otherwise + true if the transform could be computed - a `GtkWidget` + a widget @@ -110432,12 +110419,12 @@ system [overview](coordinates.html). - Tests if the point at (@x, @y) is contained in @widget. + Tests if a given point is contained in the widget. -The coordinates for (@x, @y) must be in widget coordinates, so +The coordinates for (x, y) must be in widget coordinates, so (0, 0) is assumed to be the top left of @widget's content area. - %TRUE if @widget contains (@x, @y). + true if @widget contains the point (x, y) @@ -110456,9 +110443,10 @@ The coordinates for (@x, @y) must be in widget coordinates, so - Creates a new `PangoContext` with the appropriate font map, -font options, font description, and base direction for drawing -text for this widget. + Creates a new `PangoContext` that is configured for the widget. + +The `PangoContext` will have the appropriate font map, +font options, font description, and base direction set. See also [method@Gtk.Widget.get_pango_context]. @@ -110467,18 +110455,19 @@ See also [method@Gtk.Widget.get_pango_context]. - a `GtkWidget` + a widget - Creates a new `PangoLayout` with the appropriate font map, -font description, and base direction for drawing text for -this widget. + Creates a new `PangoLayout` that is configured for the widget. + +The `PangoLayout` will have the appropriate font map, +font description, and base direction set. If you keep a `PangoLayout` created in this way around, -you need to re-create it when the widget `PangoContext` +you need to re-create it when the widgets `PangoContext` is replaced. This can be tracked by listening to changes of the [property@Gtk.Widget:root] property on the widget. @@ -110487,7 +110476,7 @@ of the [property@Gtk.Widget:root] property on the widget. - a `GtkWidget` + a widget @@ -110497,16 +110486,16 @@ of the [property@Gtk.Widget:root] property on the widget. - Clears the template children for the given widget. + Clears the template children for the widget. -This function is the opposite of [method@Gtk.Widget.init_template], and -it is used to clear all the template children from a widget instance. -If you bound a template child to a field in the instance structure, or -in the instance private data structure, the field will be set to `NULL` -after this function returns. +This function is the opposite of [method@Gtk.Widget.init_template], +and it is used to clear all the template children from a widget +instance. If you bound a template child to a field in the instance +structure, or in the instance private data structure, the field will +be set to `NULL` after this function returns. You should call this function inside the `GObjectClass.dispose()` -implementation of any widget that called `gtk_widget_init_template()`. +implementation of any widget that called [method@Gtk.Widget.init_template]. Typically, you will want to call this function last, right before chaining up to the parent type's dispose implementation, e.g. @@ -110539,12 +110528,12 @@ some_widget_dispose (GObject *gobject) Checks to see if a drag movement has passed the GTK drag threshold. - %TRUE if the drag threshold has been passed. + true if the drag threshold has been passed - a `GtkWidget` + a widget @@ -110566,9 +110555,9 @@ some_widget_dispose (GObject *gobject) - Notifies the user about an input-related error on this widget. + Notifies the user about an input-related error on the widget. -If the [property@Gtk.Settings:gtk-error-bell] setting is %TRUE, +If the [property@Gtk.Settings:gtk-error-bell] setting is true, it calls [method@Gdk.Surface.beep], otherwise it does nothing. Note that the effect of [method@Gdk.Surface.beep] can be configured @@ -110579,13 +110568,13 @@ environment or window manager that is used. - a `GtkWidget` + a widget - Returns the baseline that has currently been allocated to @widget. + Returns the baseline that has currently been allocated to the widget. This function is intended to be used when implementing handlers for the `GtkWidget`Class.snapshot() function, and when allocating @@ -110603,7 +110592,7 @@ child widgets in `GtkWidget`Class.size_allocate(). - Returns the height that has currently been allocated to @widget. + Returns the height that has currently been allocated to the widget. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). @@ -110620,7 +110609,7 @@ system [overview](coordinates.html). - Returns the width that has currently been allocated to @widget. + Returns the width that has currently been allocated to the widget. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). @@ -110639,7 +110628,7 @@ system [overview](coordinates.html). Retrieves the widget’s allocation. -Note, when implementing a layout container: a widget’s allocation +Note, when implementing a layout widget: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent typically calls [method@Gtk.Widget.size_allocate] with an allocation, and that allocation is then adjusted (to handle margin @@ -110649,9 +110638,9 @@ was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the [method@Gtk.Widget.size_allocate] allocation, however. -So a layout container is guaranteed that its children stay inside +So a layout widget is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the -container assigned. +widget assigned. Use [method@Gtk.Widget.compute_bounds], [method@Gtk.Widget.get_width] or [method@Gtk.Widget.get_height] instead. @@ -110659,7 +110648,7 @@ container assigned. - a `GtkWidget` + a widget @@ -110669,7 +110658,7 @@ container assigned. - Gets the first ancestor of @widget with type @widget_type. + Gets the first ancestor of the widget with type @widget_type. For example, `gtk_widget_get_ancestor (widget, GTK_TYPE_BOX)` gets the first `GtkBox` that’s an ancestor of @widget. No @@ -110684,7 +110673,7 @@ considers @widget to be an ancestor of itself. - a `GtkWidget` + a widget @@ -110694,11 +110683,11 @@ considers @widget to be an ancestor of itself. - Returns the baseline that has currently been allocated to @widget. + Returns the baseline that has currently been allocated to the widget. This function is intended to be used when implementing handlers -for the `GtkWidget`Class.snapshot() function, and when allocating -child widgets in `GtkWidget`Class.size_allocate(). +for the `GtkWidgetClass.snapshot()` function, and when allocating +child widgets in `GtkWidgetClass.size_allocate()`. the baseline of the @widget, or -1 if none @@ -110711,58 +110700,58 @@ child widgets in `GtkWidget`Class.size_allocate(). - Determines whether the input focus can enter @widget or any + Determines whether the input focus can enter the widget or any of its children. -See [method@Gtk.Widget.set_focusable]. +See [method@Gtk.Widget.set_can_focus]. - %TRUE if the input focus can enter @widget, %FALSE otherwise + true if the input focus can enter @widget - a `GtkWidget` + a widget - Queries whether @widget can be the target of pointer events. + Queries whether the widget can be the target of pointer events. - %TRUE if @widget can receive pointer events + true if @widget can receive pointer events - a `GtkWidget` + a widget - Gets the value set with gtk_widget_set_child_visible(). + Gets the value set with [method@Gtk.Widget.set_child_visible]. If you feel a need to use this function, your code probably needs reorganization. -This function is only useful for container implementations +This function is only useful for widget implementations and should never be called by an application. - %TRUE if the widget is mapped with the parent. + true if the widget is mapped with the parent - a `GtkWidget` + a widget - Gets the clipboard object for @widget. + Gets the clipboard object for the widget. This is a utility function to get the clipboard object for the -`GdkDisplay` that @widget is using. +display that @widget is using. Note that this function always works, even when @widget is not realized yet. @@ -110772,24 +110761,23 @@ realized yet. - a `GtkWidget` + a widget - Gets the current foreground color for the widget’s -CSS style. + Gets the current foreground color for the widget’s style. This function should only be used in snapshot -implementations that need to do custom -drawing with the foreground color. +implementations that need to do custom drawing +with the foreground color. - a `GtkWidget` + a widget @@ -110799,84 +110787,81 @@ drawing with the foreground color. - Returns the list of style classes applied to @widget. + Returns the list of style classes applied to the widget. - a %NULL-terminated list of - css classes currently applied to @widget. The returned - list must freed using g_strfreev(). + a `NULL`-terminated list of + css classes currently applied to @widget - a `GtkWidget` + a widget - Returns the CSS name that is used for @self. + Returns the CSS name of the widget. the CSS name - a `GtkWidget` + a widget - Queries the cursor set on @widget. + Gets the cursor set on the widget. See [method@Gtk.Widget.set_cursor] for details. the cursor - currently in use or %NULL if the cursor is inherited + that is set on @widget - a `GtkWidget` + a widget - Gets the reading direction for a particular widget. + Gets the reading direction for the widget. See [method@Gtk.Widget.set_direction]. - the reading direction for the widget. + the reading direction for the widget - a `GtkWidget` + a widget - Get the `GdkDisplay` for the toplevel window associated with -this widget. + Get the display for the window that the widget belongs to. This function can only be called after the widget has been -added to a widget hierarchy with a `GtkWindow` at the top. +added to a widget hierarchy with a `GtkRoot` at the top. -In general, you should only create display specific +In general, you should only create display-specific resources when a widget has been realized, and you should free those resources when the widget is unrealized. - the `GdkDisplay` for the toplevel - for this widget. + the display for this widget - a `GtkWidget` + a widget @@ -110884,28 +110869,28 @@ free those resources when the widget is unrealized. Returns the widget’s first child. -This API is primarily meant for widget implementations. +This function is primarily meant for widget implementations. - The widget's first child + the widget's first child - a `GtkWidget` + a widget - Returns the current focus child of @widget. + Returns the focus child of the widget. - The current focus + the current focus child of @widget - a `GtkWidget` + a widget @@ -110916,49 +110901,49 @@ with the mouse. See [method@Gtk.Widget.set_focus_on_click]. - %TRUE if the widget should grab focus when it is + true if the widget should grab focus when it is clicked with the mouse - a `GtkWidget` + a widget - Determines whether @widget can own the input focus. + Determines whether the widget can own the input focus. See [method@Gtk.Widget.set_focusable]. - %TRUE if @widget can own the input focus, %FALSE otherwise + true if @widget can own the input focus - a `GtkWidget` + a widget - Gets the font map of @widget. + Gets the font map of the widget. See [method@Gtk.Widget.set_font_map]. - A `PangoFontMap` + the font map of @widget - a `GtkWidget` + a widget - Returns the `cairo_font_options_t` of widget. + Returns the `cairo_font_options_t` of the widget. Seee [method@Gtk.Widget.set_font_options]. @@ -110967,7 +110952,7 @@ Seee [method@Gtk.Widget.set_font_options]. - a `GtkWidget` + a widget @@ -110984,34 +110969,34 @@ the start of the animation with an initial value from by calling [method@Gdk.FrameClock.get_frame_time] again during each repaint. [method@Gdk.FrameClock.request_phase] will result in a new frame on the -clock, but won’t necessarily repaint any widgets. To repaint a -widget, you have to use [method@Gtk.Widget.queue_draw] which invalidates -the widget (thus scheduling it to receive a draw on the next -frame). gtk_widget_queue_draw() will also end up requesting a frame +clock, but won’t necessarily repaint any widgets. To repaint a widget, +you have to use [method@Gtk.Widget.queue_draw] which invalidates the +widget (thus scheduling it to receive a draw on the next frame). +[method@Gtk.Widget.queue_draw] will also end up requesting a frame on the appropriate frame clock. -A widget’s frame clock will not change while the widget is -mapped. Reparenting a widget (which implies a temporary unmap) can -change the widget’s frame clock. +A widget’s frame clock will not change while the widget is mapped. +Reparenting a widget (which implies a temporary unmap) can change +the widget’s frame clock. Unrealized widgets do not have a frame clock. - a `GdkFrameClock` + the frame clock - a `GtkWidget` + a widget - Gets the horizontal alignment of @widget. + Gets the horizontal alignment of the widget. For backwards compatibility reasons this method will never return one of the baseline alignments, but instead it will convert it to -`GTK_ALIGN_FILL` or `GTK_ALIGN_CENTER`. +[enum@Gtk.Align.fill] or [enum@Gtk.Align.center]. Baselines are not supported for horizontal alignment. @@ -111020,7 +111005,7 @@ Baselines are not supported for horizontal alignment. - a `GtkWidget` + a widget @@ -111028,12 +111013,12 @@ Baselines are not supported for horizontal alignment. Returns the current value of the `has-tooltip` property. - current value of `has-tooltip` on @widget. + current value of `has-tooltip` on @widget - a `GtkWidget` + a widget @@ -111055,7 +111040,7 @@ system [overview](coordinates.html). - a `GtkWidget` + a widget @@ -111064,13 +111049,12 @@ system [overview](coordinates.html). Gets whether the widget would like any available extra horizontal space. -When a user resizes a `GtkWindow`, widgets with expand=TRUE -generally receive the extra space. For example, a list or -scrollable area or document in your window would often be set to -expand. +When a user resizes a window, widgets with expand set to true generally +receive the extra space. For example, a list or scrollable area +or document in your window would often be set to expand. -Containers should use [method@Gtk.Widget.compute_expand] rather -than this function, to see whether a widget, or any of its children, +Widgets with children should use [method@Gtk.Widget.compute_expand] +rather than this function, to see whether any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also. @@ -111083,14 +111067,13 @@ wants to expand. - the widget + a widget - Gets whether gtk_widget_set_hexpand() has been used -to explicitly set the expand flag on this widget. + Gets whether the `hexpand` flag has been explicitly set. If [property@Gtk.Widget:hexpand] property is set, then it overrides any computed expand value based on child widgets. @@ -111105,7 +111088,7 @@ for completeness and consistency. - the widget + a widget @@ -111113,94 +111096,94 @@ for completeness and consistency. Returns the widget’s last child. -This API is primarily meant for widget implementations. +This function is primarily meant for widget implementations. - The widget's last child + the widget's last child - a `GtkWidget` + a widget - Retrieves the layout manager used by @widget. + Retrieves the layout manager of the widget. See [method@Gtk.Widget.set_layout_manager]. - a `GtkLayoutManager` + the layout manager of @widget - a `GtkWidget` + a widget - Whether the widget is mapped. + Returns whether the widget is mapped. - %TRUE if the widget is mapped, %FALSE otherwise. + true if the widget is mapped - a `GtkWidget` + a widget - Gets the bottom margin of @widget. + Gets the bottom margin of the widget. The bottom margin of @widget - a `GtkWidget` + a widget - Gets the end margin of @widget. + Gets the end margin of the widget. The end margin of @widget - a `GtkWidget` + a widget - Gets the start margin of @widget. + Gets the start margin of the widget. The start margin of @widget - a `GtkWidget` + a widget - Gets the top margin of @widget. + Gets the top margin of the widget. The top margin of @widget - a `GtkWidget` + a widget @@ -111210,21 +111193,20 @@ See [method@Gtk.Widget.set_layout_manager]. See [method@Gtk.Widget.set_name] for the significance of widget names. - name of the widget. This string is owned by GTK and - should not be modified or freed + name of the widget - a `GtkWidget` + a widget - Returns the nearest `GtkNative` ancestor of @widget. + Returns the nearest `GtkNative` ancestor of the widget. -This function will return %NULL if the widget is not +This function will return `NULL` if the widget is not contained inside a widget tree with a native ancestor. `GtkNative` widgets will return themselves here. @@ -111234,7 +111216,7 @@ contained inside a widget tree with a native ancestor. - a `GtkWidget` + a widget @@ -111242,29 +111224,29 @@ contained inside a widget tree with a native ancestor. Returns the widget’s next sibling. -This API is primarily meant for widget implementations. +This function is primarily meant for widget implementations. - The widget's next sibling + the widget's next sibling - a `GtkWidget` + a widget - #Fetches the requested opacity for this widget. + Fetches the requested opacity for the widget. See [method@Gtk.Widget.set_opacity]. - the requested opacity for this widget. + the requested opacity for this widget - a `GtkWidget` + a widget @@ -111272,19 +111254,21 @@ See [method@Gtk.Widget.set_opacity]. Returns the widget’s overflow value. - The widget's overflow. + The widget's overflow value - a `GtkWidget` + a widget - Gets a `PangoContext` with the appropriate font map, font description, -and base direction for this widget. + Gets a `PangoContext` that is configured for the widget. + +The `PangoContext` will have the appropriate font map, font description, +and base direction set. Unlike the context returned by [method@Gtk.Widget.create_pango_context], this context is owned by the widget (it can be used until the screen @@ -111293,25 +111277,25 @@ and will be updated to match any changes to the widget’s attributes. This can be tracked by listening to changes of the [property@Gtk.Widget:root] property on the widget. - the `PangoContext` for the widget. + the `PangoContext` for the widget - a `GtkWidget` + a widget - Returns the parent widget of @widget. + Returns the parent widget of the widget. the parent widget of @widget - a `GtkWidget` + a widget @@ -111352,23 +111336,23 @@ Use [method@Gtk.Widget.measure] if you want to support baseline alignment. Returns the widget’s previous sibling. -This API is primarily meant for widget implementations. +This function is primarily meant for widget implementations. - The widget's previous sibling + the widget's previous sibling - a `GtkWidget` + a widget - Gets the primary clipboard of @widget. + Gets the primary clipboard of the widget. This is a utility function to get the primary clipboard object -for the `GdkDisplay` that @widget is using. +for the display that @widget is using. Note that this function always works, even when @widget is not realized yet. @@ -111378,38 +111362,37 @@ realized yet. - a `GtkWidget` + a widget - Determines whether @widget is realized. + Determines whether the widget is realized. - %TRUE if @widget is realized, %FALSE otherwise + true if @widget is realized - a `GtkWidget` + a widget - Determines whether @widget is always treated as the default widget + Determines whether the widget is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default. See [method@Gtk.Widget.set_receives_default]. - %TRUE if @widget acts as the default widget when focused, - %FALSE otherwise + true if @widget acts as the default widget when focused - a `GtkWidget` + a widget @@ -111434,9 +111417,9 @@ allocation capabilities. - Returns the `GtkRoot` widget of @widget. + Returns the `GtkRoot` widget of the widget. -This function will return %NULL if the widget is not contained +This function will return `NULL` if the widget is not contained inside a widget tree with a root widget. `GtkRoot` widgets will return themselves here. @@ -111446,7 +111429,7 @@ inside a widget tree with a root widget. - a `GtkWidget` + a widget @@ -111458,14 +111441,20 @@ coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2). -See [method@Gdk.Surface.get_scale_factor]. +See [method@Gdk.Surface.get_scale_factor]. + +Note that modern systems may support *fractional* scaling, +where the scale factor is not an integer. On such systems, +this function will return the next higher integer value, +but you probably want to use [method@Gdk.Surface.get_scale] +to get the fractional scale value. the scale factor for @widget - a `GtkWidget` + a widget @@ -111480,30 +111469,30 @@ The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See [method@Gtk.Widget.is_sensitive]. - %TRUE if the widget is sensitive + true if the widget is sensitive - a `GtkWidget` + a widget - Gets the settings object holding the settings used for this widget. + Gets the settings object holding the settings used for the widget. Note that this function can only be called when the `GtkWidget` is attached to a toplevel, since the settings object is specific -to a particular `GdkDisplay`. If you want to monitor the widget for +to a particular display. If you want to monitor the widget for changes in its settings, connect to the `notify::display` signal. - the relevant `GtkSettings` object + the relevant settings object - a `GtkWidget` + a widget @@ -111514,20 +111503,20 @@ changes in its settings, connect to the `notify::display` signal. Which dimension is returned depends on @orientation. This is equivalent to calling [method@Gtk.Widget.get_width] -for %GTK_ORIENTATION_HORIZONTAL or [method@Gtk.Widget.get_height] -for %GTK_ORIENTATION_VERTICAL, but can be used when +for [enum@Gtk.Orientation.horizontal] or [method@Gtk.Widget.get_height] +for [enum@Gtk.Orientation.vertical], but can be used when writing orientation-independent code, such as when implementing [iface@Gtk.Orientable] widgets. To learn more about widget sizes, see the coordinate system [overview](coordinates.html). - The size of @widget in @orientation. + the size of @widget in @orientation - a `GtkWidget` + a widget @@ -111537,21 +111526,22 @@ system [overview](coordinates.html). - Gets the size request that was explicitly set for the widget using -gtk_widget_set_size_request(). + Gets the size request that was explicitly set for the widget. A value of -1 stored in @width or @height indicates that that dimension has not been set explicitly and the natural requisition -of the widget will be used instead. See -[method@Gtk.Widget.set_size_request]. To get the size a widget will -actually request, call [method@Gtk.Widget.measure] instead of -this function. +of the widget will be used instead. + +See [method@Gtk.Widget.set_size_request]. + +To get the size a widget will actually request, call +[method@Gtk.Widget.measure] instead of this function. - a `GtkWidget` + a widget @@ -111567,7 +111557,7 @@ this function. Returns the widget state as a flag set. -It is worth mentioning that the effective %GTK_STATE_FLAG_INSENSITIVE +It is worth mentioning that the effective [flags@Gtk.StateFlags.insensitive] state will be returned, that is, also based on parent insensitivity, even if @widget itself is sensitive. @@ -111575,36 +111565,36 @@ Also note that if you are looking for a way to obtain the [flags@Gtk.StateFlags] to pass to a [class@Gtk.StyleContext] method, you should look at [method@Gtk.StyleContext.get_state]. - The state flags for widget + the state flags of widget - a `GtkWidget` + a widget - Returns the style context associated to @widget. + Returns the style context associated to the widget. The returned object is guaranteed to be the same for the lifetime of @widget. Style contexts will be removed in GTK 5 - the widget’s `GtkStyleContext` + the widgets style context - a `GtkWidget` + a widget - Fetch an object build from the template XML for @widget_type in -this @widget instance. + Fetches an object build from the template XML for @widget_type in +the widget. This will only report children which were previously declared with [method@Gtk.WidgetClass.bind_template_child_full] or one of its @@ -111614,13 +111604,13 @@ This function is only meant to be called for code which is private to the @widget_type which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets. - The object built in the template XML with + the object built in the template XML with the id @name - A `GtkWidget` + a widget @@ -111628,30 +111618,30 @@ bindings which cannot easily make use of the GObject structure offsets. - The “id” of the child defined in the template XML + ID of the child defined in the template XML - Gets the contents of the tooltip for @widget. + Gets the contents of the tooltip for the widget. If the tooltip has not been set using [method@Gtk.Widget.set_tooltip_markup], this -function returns %NULL. +function returns `NULL`. the tooltip text - a `GtkWidget` + a widget - Gets the contents of the tooltip for @widget. + Gets the contents of the tooltip for the widget. If the @widget's tooltip was set using [method@Gtk.Widget.set_tooltip_markup], @@ -111662,20 +111652,20 @@ this function will return the escaped text. - a `GtkWidget` + a widget - Gets the vertical alignment of @widget. + Gets the vertical alignment of the widget. the vertical alignment of @widget - a `GtkWidget` + a widget @@ -111691,14 +111681,13 @@ See [method@Gtk.Widget.get_hexpand] for more detail. - the widget + a widget - Gets whether gtk_widget_set_vexpand() has been used to -explicitly set the expand flag on this widget. + Gets whether the `vexpand` flag has been explicitly set. See [method@Gtk.Widget.get_hexpand_set] for more detail. @@ -111707,7 +111696,7 @@ See [method@Gtk.Widget.get_hexpand_set] for more detail. - the widget + a widget @@ -111724,12 +111713,12 @@ obscured in any way. See [method@Gtk.Widget.set_visible]. - %TRUE if the widget is visible + true if the widget is visible - a `GtkWidget` + a widget @@ -111751,61 +111740,60 @@ system [overview](coordinates.html). - a `GtkWidget` + a widget - Causes @widget to have the keyboard focus for the `GtkWindow` it's inside. + Causes @widget to have the keyboard focus for the window +that it belongs to. If @widget is not focusable, or its [vfunc@Gtk.Widget.grab_focus] implementation cannot transfer the focus to a descendant of @widget -that is focusable, it will not take focus and %FALSE will be returned. +that is focusable, it will not take focus and false will be returned. Calling [method@Gtk.Widget.grab_focus] on an already focused widget -is allowed, should not have an effect, and return %TRUE. +is allowed, should not have an effect, and return true. - %TRUE if focus is now inside @widget. + true if focus is now inside @widget - a `GtkWidget` + a widget - Returns whether @css_class is currently applied to @widget. + Returns whether a style class is currently applied to the widget. - %TRUE if @css_class is currently applied to @widget, - %FALSE otherwise. + true if @css_class is currently applied to @widget - a `GtkWidget` + a widget - A style class, without the leading '.' - used for notation of style classes + style class, without the leading period - Determines whether @widget is the current default widget + Determines whether the widget is the current default widget within its toplevel. - %TRUE if @widget is the current default widget - within its toplevel, %FALSE otherwise + true if @widget is the current default widget + within its toplevel - a `GtkWidget` + a widget @@ -111817,12 +111805,12 @@ See [method@Gtk.Widget.is_focus] for the difference between having the global input focus, and only having the focus within a toplevel. - %TRUE if the widget has the global input focus. + true if the widget has the global input focus - a `GtkWidget` + a widget @@ -111839,18 +111827,18 @@ information about focus indication. To find out if the widget has the global input focus, use [method@Gtk.Widget.has_focus]. - %TRUE if the widget should display a “focus rectangle” + true if the widget should display a “focus rectangle” - a `GtkWidget` + a widget - Reverses the effects of gtk_widget_show(). + Reverses the effects of [method.Gtk.Widget.show]. This is causing the widget to be hidden (invisible to the user). Use [method@Gtk.Widget.set_visible] instead @@ -111859,7 +111847,7 @@ This is causing the widget to be hidden (invisible to the user). - a `GtkWidget` + a widget @@ -111870,12 +111858,12 @@ This is causing the widget to be hidden (invisible to the user). This information can sometimes be used to avoid doing unnecessary work. - %TRUE if @widget is being destroyed + true if @widget is being destroyed - a `GtkWidget` + a widget @@ -111888,7 +111876,7 @@ for any class which assigned itself a template using [method@Gtk.WidgetClass.set_template]. It is important to call this function in the instance initializer -of a `GtkWidget` subclass and not in `GObject.constructed()` or +of a widget subclass and not in `GObject.constructed()` or `GObject.constructor()` for two reasons: - derived widgets will assume that the composite widgets @@ -111906,13 +111894,13 @@ an instance initialization function. - a `GtkWidget` + a widget - Inserts @group into @widget. + Inserts an action group into the widget's actions. Children of @widget that implement [iface@Gtk.Actionable] can then be associated with actions in @group by setting their @@ -111923,14 +111911,14 @@ even if you insert a group with prefix @prefix, actions with the same prefix will still be inherited from the parent, unless the group contains an action with the same name. -If @group is %NULL, a previously inserted group for @name is +If @group is `NULL`, a previously inserted group for @name is removed from @widget. - a `GtkWidget` + a widget @@ -111938,37 +111926,40 @@ removed from @widget. - a `GActionGroup`, or %NULL to remove - the previously inserted group for @name + an action group - Inserts @widget into the child widget list of @parent. + Sets the parent widget of the widget. + +In contrast to [method@Gtk.Widget.set_parent], this function +inserts @widget at a specific position into the list of children +of the @parent widget. It will be placed after @previous_sibling, or at the beginning if -@previous_sibling is %NULL. +@previous_sibling is `NULL`. -After calling this function, `gtk_widget_get_prev_sibling(widget)` +After calling this function, `gtk_widget_get_prev_sibling (widget)` will return @previous_sibling. If @parent is already set as the parent widget of @widget, this function can also be used to reorder @widget in the child widget list of @parent. -This API is primarily meant for widget implementations; if you are +This function is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children. - a `GtkWidget` + a widget - the parent `GtkWidget` to insert @widget into + the parent widget to insert @widget into @@ -111978,29 +111969,33 @@ just using a widget, you *must* use its own API for adding children. - Inserts @widget into the child widget list of @parent. + Sets the parent widget of the widget. + +In contrast to [method@Gtk.Widget.set_parent], this function +inserts @widget at a specific position into the list of children +of the @parent widget. It will be placed before @next_sibling, or at the end if -@next_sibling is %NULL. +@next_sibling is `NULL`. -After calling this function, `gtk_widget_get_next_sibling(widget)` +After calling this function, `gtk_widget_get_next_sibling (widget)` will return @next_sibling. If @parent is already set as the parent widget of @widget, this function can also be used to reorder @widget in the child widget list of @parent. -This API is primarily meant for widget implementations; if you are +This function is primarily meant for widget implementations; if you are just using a widget, you *must* use its own API for adding children. - a `GtkWidget` + a widget - the parent `GtkWidget` to insert @widget into + the parent widget to insert @widget into @@ -112010,16 +112005,15 @@ just using a widget, you *must* use its own API for adding children. - Determines whether @widget is somewhere inside @ancestor, -possibly with intermediate containers. + Determines whether the widget is a descendent of @ancestor. - %TRUE if @ancestor contains @widget as a child, - grandchild, great grandchild, etc. + true if @ancestor contains @widget as a child, + grandchild, great grandchild, etc - a `GtkWidget` + a widget @@ -112029,16 +112023,16 @@ possibly with intermediate containers. - Determines whether @widget can be drawn to. + Determines whether the widget can be drawn to. A widget can be drawn if it is mapped and visible. - %TRUE if @widget is drawable, %FALSE otherwise + true if @widget is drawable - a `GtkWidget` + a widget @@ -112052,12 +112046,12 @@ property is necessarily set; [property@Gtk.Widget:has-focus] will only be set if the toplevel widget additionally has the global input focus. - %TRUE if the widget is the focus widget. + true if the widget is the focus widget - a `GtkWidget` + a widget @@ -112068,12 +112062,12 @@ global input focus. This means it is sensitive itself and also its parent widget is sensitive. - %TRUE if the widget is effectively sensitive + true if the widget is effectively sensitive - a `GtkWidget` + a widget @@ -112087,53 +112081,54 @@ This function does not check if the widget is obscured in any way. See also [method@Gtk.Widget.get_visible] and [method@Gtk.Widget.set_visible]. - %TRUE if the widget and all its parents are visible + true if the widget and all its parents are visible - a `GtkWidget` + a widget - Emits the `::keynav-failed` signal on the widget. + Emits the [signal@Gtk.Widget::keynav-failed] signal on the widget. This function should be called whenever keyboard navigation within a single widget hits a boundary. The return value of this function should be interpreted in a way similar to the return value of -[method@Gtk.Widget.child_focus]. When %TRUE is returned, -stay in the widget, the failed keyboard navigation is OK +[method@Gtk.Widget.child_focus]. When true is returned, +stay in the widget, the failed keyboard navigation is ok and/or there is nowhere we can/should move the focus to. -When %FALSE is returned, the caller should continue with +When false is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling [method@Gtk.Widget.child_focus] on the widget’s toplevel. The default [signal@Gtk.Widget::keynav-failed] handler returns -%FALSE for %GTK_DIR_TAB_FORWARD and %GTK_DIR_TAB_BACKWARD. -For the other values of `GtkDirectionType` it returns %TRUE. +false for [enum@Gtk.DirectionType.tab-forward] and +[enum@Gtk.DirectionType.tab-backward]. For the other values +of [enum@Gtk.DirectionType] it returns true. -Whenever the default handler returns %TRUE, it also calls +Whenever the default handler returns true, it also calls [method@Gtk.Widget.error_bell] to notify the user of the failed keyboard navigation. -A use case for providing an own implementation of ::keynav-failed +A use case for providing an own implementation of `::keynav-failed` (either by connecting to it or by overriding it) would be a row of [class@Gtk.Entry] widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys. - %TRUE if stopping keyboard navigation is fine, %FALSE + true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard - navigation attempt in its parent container(s). + navigation attempt in its parent widget - a `GtkWidget` + a widget @@ -112156,15 +112151,14 @@ must call `g_list_foreach (result, (GFunc)g_object_ref, NULL)` first, and then unref all the widgets afterwards. the list - of mnemonic labels; free this list with g_list_free() when you - are done with it. + of mnemonic labels - a `GtkWidget` + a widget @@ -112178,7 +112172,7 @@ This function is only for use in widget implementations. - a `GtkWidget` + a widget @@ -112233,26 +112227,24 @@ a more details on implementing `GtkWidgetClass.measure()`. - Emits the ::mnemonic-activate signal. - -See [signal@Gtk.Widget::mnemonic-activate]. + Emits the [signal@Gtk.Widget::mnemonic-activate] signal. - %TRUE if the signal has been handled + true if the signal has been handled - a `GtkWidget` + a widget - %TRUE if there are other widgets with the same mnemonic + true if there are other widgets with the same mnemonic - Returns a `GListModel` to track the children of @widget. + Returns a list model to track the children of the widget. Calling this function will enable extra internal bookkeeping to track children and emit signals on the returned listmodel. @@ -112263,19 +112255,18 @@ because of the slowdowns. - a `GListModel` tracking @widget's children + a list model tracking @widget's children - a `GtkWidget` + a widget - Returns a `GListModel` to track the [class@Gtk.EventController]s -of @widget. + Returns a list model to track the event controllers of the widget. Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned listmodel. @@ -112286,34 +112277,33 @@ because of the slowdowns. - a `GListModel` tracking @widget's controllers + a list model tracking @widget's controllers - a `GtkWidget` + a widget - Finds the descendant of @widget closest to the point (@x, @y). + Finds the descendant of the widget closest to a point. -The point must be given in widget coordinates, so (0, 0) is assumed -to be the top left of @widget's content area. +The point (x, y) must be given in widget coordinates, so (0, 0) +is assumed to be the top left of @widget's content area. -Usually widgets will return %NULL if the given coordinate is not +Usually widgets will return `NULL` if the given coordinate is not contained in @widget checked via [method@Gtk.Widget.contains]. Otherwise they will recursively try to find a child that does -not return %NULL. Widgets are however free to customize their +not return `NULL`. Widgets are however free to customize their picking algorithm. This function is used on the toplevel to determine the widget below the mouse cursor for purposes of hover highlighting and delivering events. - The widget descendant at - the given point + the widget's descendant at (x, y) @@ -112322,15 +112312,15 @@ delivering events. - X coordinate to test, relative to @widget's origin + x coordinate to test, relative to @widget's origin - Y coordinate to test, relative to @widget's origin + y coordinate to test, relative to @widget's origin - Flags to influence what is picked + flags to influence what is picked @@ -112351,13 +112341,15 @@ This function is only for use in widget implementations. - a `GtkWidget` + a widget - Schedules this widget to be redrawn in the paint phase + Schedules this widget to be redrawn. + +The redraw will happen in the paint phase of the current or the next frame. This means @widget's [vfunc@Gtk.Widget.snapshot] @@ -112367,7 +112359,7 @@ implementation will be called. - a `GtkWidget` + a widget @@ -112391,7 +112383,7 @@ This function is only for use in widget implementations. - a `GtkWidget` + a widget @@ -112418,16 +112410,16 @@ called after the widget is realized automatically, such as - a `GtkWidget` + a widget - Removes @controller from @widget, so that it doesn't process -events anymore. + Removes an event controller from the widget. -It should not be used again. +The removed event controller will not receive any more events, +and should not be used again. Widgets will remove all event controllers automatically when they are destroyed, there is normally no need to call this function. @@ -112436,17 +112428,17 @@ are destroyed, there is normally no need to call this function. - a `GtkWidget` + a widget - a `GtkEventController` + an event controller - Removes a style from @widget. + Removes a style from the widget. After this, the style of @widget will stop matching for @css_class. @@ -112454,12 +112446,11 @@ After this, the style of @widget will stop matching for @css_class. - a `GtkWidget` + a widget - The style class to remove from @widget, without - the leading '.' used for notation of style classes + style class to remove from @widget, without the leading period @@ -112467,49 +112458,49 @@ After this, the style of @widget will stop matching for @css_class. Removes a widget from the list of mnemonic labels for this widget. -See [method@Gtk.Widget.list_mnemonic_labels]. The widget must -have previously been added to the list with +See [method@Gtk.Widget.list_mnemonic_labels]. + +The widget must have previously been added to the list with [method@Gtk.Widget.add_mnemonic_label]. - a `GtkWidget` + a widget - a `GtkWidget` that was previously set as a mnemonic - label for @widget with [method@Gtk.Widget.add_mnemonic_label] + a widget that is a mnemonic label for @widget Removes a tick callback previously registered with -gtk_widget_add_tick_callback(). +[method@Gtk.Widget.add_tick_callback]. - a `GtkWidget` + a widget - an id returned by [method@Gtk.Widget.add_tick_callback] + an ID returned by [method@Gtk.Widget.add_tick_callback] - Specifies whether the input focus can enter the widget -or any of its children. + Sets whether the input focus can enter the widget or +any of its children. -Applications should set @can_focus to %FALSE to mark a +Applications should set @can_focus to false to mark a widget as for pointer/touch use only. -Note that having @can_focus be %TRUE is only one of the +Note that having @can_focus be true is only one of the necessary conditions for being focusable. A widget must also be sensitive and focusable and not have an ancestor that is marked as not can-focus in order to receive input @@ -112522,24 +112513,24 @@ the input focus on a widget. - a `GtkWidget` + a widget - whether or not the input focus can enter + whether the input focus can enter the widget or any of its children - Sets whether @widget can be the target of pointer events. + Sets whether the widget can be the target of pointer events. - a `GtkWidget` + a widget @@ -112550,12 +112541,12 @@ the input focus on a widget. - Sets whether @widget should be mapped along with its parent. + Sets whether the widget should be mapped along with its parent. The child visibility can be set for widget before it is added to a container with [method@Gtk.Widget.set_parent], to avoid mapping children unnecessary before immediately unmapping them. -However it will be reset to its default state of %TRUE when the +However it will be reset to its default state of true when the widget is removed from a container. Note that changing the child visibility of a widget does not @@ -112564,37 +112555,36 @@ a widget is computed from all visible children, whether or not they are mapped. If this is not the case, the container can queue a resize itself. -This function is only useful for container implementations +This function is only useful for widget implementations and should never be called by an application. - a `GtkWidget` + a widget - if %TRUE, @widget should be mapped along - with its parent. + whether @widget should be mapped along + with its parent - Clear all style classes applied to @widget -and replace them with @classes. + Replaces the current style classes of the widget with @classes. - a `GtkWidget` + a widget - %NULL-terminated list of style classes to apply to @widget. + `NULL`-terminated list of style classes @@ -112602,17 +112592,17 @@ and replace them with @classes. - Sets the cursor to be shown when pointer devices point -towards @widget. + Sets the cursor to be shown when the pointer hovers over +the widget. -If the @cursor is NULL, @widget will use the cursor -inherited from the parent widget. +If the @cursor is `NULL`, @widget will use the cursor +inherited from its parent. - a `GtkWidget` + a widget @@ -112622,51 +112612,53 @@ inherited from the parent widget. - Sets a named cursor to be shown when pointer devices point -towards @widget. + Sets the cursor to be shown when the pointer hovers over +the widget. This is a utility function that creates a cursor via [ctor@Gdk.Cursor.new_from_name] and then sets it on @widget with [method@Gtk.Widget.set_cursor]. See those functions for details. -On top of that, this function allows @name to be %NULL, which +On top of that, this function allows @name to be `NULL`, which will do the same as calling [method@Gtk.Widget.set_cursor] -with a %NULL cursor. +with a `NULL` cursor. - a `GtkWidget` + a widget - The name of the cursor + the name of the cursor - Sets the reading direction on a particular widget. + Sets the reading direction on the widget. This direction controls the primary direction for widgets containing text, and also the direction in which the children of a container are packed. The ability to set the direction is present in order so that correct localization into languages with -right-to-left reading directions can be done. Generally, applications -will let the default reading direction present, except for containers -where the containers are arranged in an order that is explicitly -visual rather than logical (such as buttons for text justification). +right-to-left reading directions can be done. -If the direction is set to %GTK_TEXT_DIR_NONE, then the value -set by [func@Gtk.Widget.set_default_direction] will be used. +Generally, applications will let the default reading direction +prevail, except for widgets where the children are arranged in +an order that is explicitly visual rather than logical (such as +buttons for text justification). + +If the direction is set to [enum@Gtk.TextDirection.none], then +the value set by [func@Gtk.Widget.set_default_direction] will be used. - a `GtkWidget` + a widget @@ -112676,7 +112668,7 @@ set by [func@Gtk.Widget.set_default_direction] will be used. - Set @child as the current focus child of @widget. + Set the focus child of the widget. This function is only suitable for widget implementations. If you want a certain widget to get the input focus, call @@ -112686,12 +112678,12 @@ If you want a certain widget to get the input focus, call - a `GtkWidget` + a widget - a direct child widget of @widget or %NULL - to unset the focus child of @widget + a direct child widget of @widget + or `NULL` to unset the focus child @@ -112708,7 +112700,7 @@ the main area of the application. - a `GtkWidget` + a widget @@ -112719,12 +112711,12 @@ the main area of the application. - Specifies whether @widget can own the input focus. + Sets whether the widget can own the input focus. -Widget implementations should set @focusable to %TRUE in +Widget implementations should set @focusable to true in their init() function if they want to receive keyboard input. -Note that having @focusable be %TRUE is only one of the +Note that having @focusable be true is only one of the necessary conditions for being focusable. A widget must also be sensitive and can-focus and not have an ancestor that is marked as not can-focus in order to receive input @@ -112737,7 +112729,7 @@ the input focus on a widget. - a `GtkWidget` + a widget @@ -112747,7 +112739,7 @@ the input focus on a widget. - Sets the font map to use for Pango rendering. + Sets the font map to use for text rendering in the widget. The font map is the object that is used to look up fonts. Setting a custom font map can be useful in special situations, @@ -112760,19 +112752,18 @@ When not set, the widget will inherit the font map from its parent. - a `GtkWidget` + a widget - a `PangoFontMap`, or %NULL to unset any - previously set font map + a `PangoFontMap` - Sets the `cairo_font_options_t` used for Pango rendering -in this widget. + Sets the `cairo_font_options_t` used for text rendering +in the widget. When not set, the default font options for the `GdkDisplay` will be used. @@ -112781,24 +112772,24 @@ will be used. - a `GtkWidget` + a widget - a `cairo_font_options_t` + a `cairo_font_options_t` struct to unset any previously set default font options - Sets the horizontal alignment of @widget. + Sets the horizontal alignment of the widget. - a `GtkWidget` + a widget @@ -112808,17 +112799,17 @@ will be used. - Sets the `has-tooltip` property on @widget to @has_tooltip. + Sets the `has-tooltip` property on the widget. - a `GtkWidget` + a widget - whether or not @widget has a tooltip. + whether or not @widget has a tooltip @@ -112827,10 +112818,9 @@ will be used. Sets whether the widget would like any available extra horizontal space. -When a user resizes a `GtkWindow`, widgets with expand=TRUE -generally receive the extra space. For example, a list or -scrollable area or document in your window would often be set to -expand. +When a user resizes a window, widgets with expand set to true generally +receive the extra space. For example, a list or scrollable area +or document in your window would often be set to expand. Call this function to set the expand flag if you would like your widget to become larger horizontally when the window has extra @@ -112839,15 +112829,15 @@ room. By default, widgets automatically expand if any of their children want to expand. (To see if a widget will automatically expand given its current children and state, call [method@Gtk.Widget.compute_expand]. -A container can decide how the expandability of children affects the -expansion of the container by overriding the compute_expand virtual -method on `GtkWidget`.). +A widget can decide how the expandability of children affects its +own expansion by overriding the `compute_expand` virtual method on +`GtkWidget`.). Setting hexpand explicitly with this function will override the automatic expand behavior. This function forces the widget to expand or not to expand, -regardless of children. The override occurs because +regardless of children. The override occurs because [method@Gtk.Widget.set_hexpand] sets the hexpand-set property (see [method@Gtk.Widget.set_hexpand_set]) which causes the widget’s hexpand value to be used, rather than looking at children and widget state. @@ -112856,7 +112846,7 @@ value to be used, rather than looking at children and widget state. - the widget + a widget @@ -112885,7 +112875,7 @@ for completeness and consistency. - the widget + a widget @@ -112895,30 +112885,30 @@ for completeness and consistency. - Sets the layout manager delegate instance that provides an -implementation for measuring and allocating the children of @widget. + Sets the layout manager to use for measuring and allocating children +of the widget. - a `GtkWidget` + a widget - a `GtkLayoutManager` + a layout manager - Sets the bottom margin of @widget. + Sets the bottom margin of the widget. - a `GtkWidget` + a widget @@ -112928,13 +112918,13 @@ implementation for measuring and allocating the children of @widget. - Sets the end margin of @widget. + Sets the end margin of the widget. - a `GtkWidget` + a widget @@ -112944,13 +112934,13 @@ implementation for measuring and allocating the children of @widget. - Sets the start margin of @widget. + Sets the start margin of the widget. - a `GtkWidget` + a widget @@ -112960,13 +112950,13 @@ implementation for measuring and allocating the children of @widget. - Sets the top margin of @widget. + Sets the top margin of the widget. - a `GtkWidget` + a widget @@ -112992,7 +112982,7 @@ of alphanumeric symbols, dashes and underscores will suffice. - a `GtkWidget` + a widget @@ -113002,7 +112992,7 @@ of alphanumeric symbols, dashes and underscores will suffice. - Request the @widget to be rendered partially transparent. + Requests the widget to be rendered partially transparent. An opacity of 0 is fully transparent and an opacity of 1 is fully opaque. @@ -113010,8 +113000,8 @@ is fully opaque. Opacity works on both toplevel widgets and child widgets, although there are some limitations: For toplevel widgets, applying opacity depends on the capabilities of the windowing system. On X11, this -has any effect only on X displays with a compositing manager, -see gdk_display_is_composited(). On Windows and Wayland it should +has any effect only on X displays with a compositing manager, see +[method@Gdk.Display.is_composited]. On Windows and Wayland it will always work, although setting a window’s opacity after the window has been shown may cause some flicker. @@ -113020,16 +113010,17 @@ a toplevel to be partially translucent, all of its content will appear translucent, since it is ultimatively rendered on that toplevel. The opacity value itself is not inherited by child widgets (since that would make widgets deeper in the hierarchy -progressively more translucent). As a consequence, [class@Gtk.Popover]s -and other [iface@Gtk.Native] widgets with their own surface will use their -own opacity value, and thus by default appear non-translucent, -even if they are attached to a toplevel that is translucent. +progressively more translucent). As a consequence, [class@Gtk.Popover] +instances and other [iface@Gtk.Native] widgets with their own surface +will use their own opacity value, and thus by default appear +non-translucent, even if they are attached to a toplevel that +is translucent. - a `GtkWidget` + a widget @@ -113039,31 +113030,31 @@ even if they are attached to a toplevel that is translucent. - Sets how @widget treats content that is drawn outside the -widget's content area. + Sets how the widget treats content that is drawn outside the +it's content area. See the definition of [enum@Gtk.Overflow] for details. This setting is provided for widget implementations and should not be used by application code. -The default value is %GTK_OVERFLOW_VISIBLE. +The default value is [enum@Gtk.Overflow.visible]. - a `GtkWidget` + a widget - desired overflow + desired overflow value - Sets @parent as the parent widget of @widget. + Sets the parent widget of the widget. This takes care of details such as updating the state and style of the child to reflect its new location and resizing the parent. @@ -113076,7 +113067,7 @@ This function is useful only when implementing subclasses of - a `GtkWidget` + a widget @@ -113086,7 +113077,7 @@ This function is useful only when implementing subclasses of - Specifies whether @widget will be treated as the default + Sets whether the widget will be treated as the default widget within its toplevel when it has the focus, even if another widget is the default. @@ -113094,17 +113085,17 @@ another widget is the default. - a `GtkWidget` + a widget - whether or not @widget can be a default widget. + whether or not @widget can be a default widget - Sets the sensitivity of a widget. + Sets the sensitivity of the widget. A widget is sensitive if the user can interact with it. Insensitive widgets are “grayed out” and the user can’t @@ -113115,17 +113106,17 @@ interact with them. Insensitive widgets are known as - a `GtkWidget` + a widget - %TRUE to make the widget sensitive + true to make the widget sensitive - Sets the minimum size of a widget. + Sets the minimum size of the widget. That is, the widget’s size request will be at least @width by @height. You can use this function to force a widget to @@ -113139,9 +113130,8 @@ the size request. Note the inherent danger of setting any fixed size - themes, translations into other languages, different fonts, and user action -can all change the appropriate size for a given widget. So, it's -basically impossible to hardcode a size that will always be -correct. +can all change the appropriate size for a given widget. So, it is +basically impossible to hardcode a size that will always work. The size request of a widget is the smallest size a widget can accept while still functioning well and drawing itself correctly. @@ -113165,7 +113155,7 @@ of `GtkWidget`. - a `GtkWidget` + a widget @@ -113183,8 +113173,8 @@ of `GtkWidget`. Typical widget states are insensitive, prelighted, etc. -This function accepts the values %GTK_STATE_FLAG_DIR_LTR and -%GTK_STATE_FLAG_DIR_RTL but ignores them. If you want to set +This function accepts the values [flags@Gtk.StateFlags.dir-ltr] and +[flags@Gtk.StateFlags.dir-rtl] but ignores them. If you want to set the widget's direction, use [method@Gtk.Widget.set_direction]. This function is for use in widget implementations. @@ -113193,22 +113183,23 @@ This function is for use in widget implementations. - a `GtkWidget` + a widget - State flags to turn on + state flags to turn on - Whether to clear state before turning on @flags + whether to clear state before turning on @flags - Sets @markup as the contents of the tooltip, which is marked -up with Pango markup. + Sets the contents of the tooltip for widget. + +@markup must contain Pango markup. This function will take care of setting the [property@Gtk.Widget:has-tooltip] as a side effect, and of the @@ -113220,7 +113211,7 @@ See also [method@Gtk.Tooltip.set_markup]. - a `GtkWidget` + a widget @@ -113230,7 +113221,7 @@ See also [method@Gtk.Tooltip.set_markup]. - Sets @text as the contents of the tooltip. + Sets the contents of the tooltip for the widget. If @text contains any markup, it will be escaped. @@ -113245,7 +113236,7 @@ See also [method@Gtk.Tooltip.set_text]. - a `GtkWidget` + a widget @@ -113255,13 +113246,13 @@ See also [method@Gtk.Tooltip.set_text]. - Sets the vertical alignment of @widget. + Sets the vertical alignment of the widget. - a `GtkWidget` + a widget @@ -113280,7 +113271,7 @@ See [method@Gtk.Widget.set_hexpand] for more detail. - the widget + a widget @@ -113310,14 +113301,14 @@ See [method@Gtk.Widget.set_hexpand_set] for more detail. Sets the visibility state of @widget. -Note that setting this to %TRUE doesn’t mean the widget is +Note that setting this to true doesn’t mean the widget is actually viewable, see [method@Gtk.Widget.get_visible]. - a `GtkWidget` + a widget @@ -113327,13 +113318,14 @@ actually viewable, see [method@Gtk.Widget.get_visible]. - Returns whether @widget should contribute to + Returns whether the widget should contribute to the measuring and allocation of its parent. -This is %FALSE for invisible children, but also -for children that have their own surface. +This is false for invisible children, but also +for children that have their own surface, such +as [class@Gtk.Popover] instances. - %TRUE if child should be included in + true if child should be included in measuring and allocating @@ -113352,16 +113344,16 @@ Any widget that isn’t shown will not appear on the screen. Remember that you have to show the containers containing a widget, in addition to the widget itself, before it will appear onscreen. -When a toplevel container is shown, it is immediately realized and +When a toplevel widget is shown, it is immediately realized and mapped; other shown widgets are realized and mapped when their -toplevel container is realized and mapped. +toplevel widget is realized and mapped. Use [method@Gtk.Widget.set_visible] instead - a `GtkWidget` + a widget @@ -113376,7 +113368,7 @@ This is a simple form of [method@Gtk.Widget.allocate]. - a `GtkWidget` + a widget @@ -113384,13 +113376,13 @@ This is a simple form of [method@Gtk.Widget.allocate]. - The baseline of the child, or -1 + the baseline of the child, or -1 - Snapshot the a child of @widget. + Snapshots a child of the widget. When a widget receives a call to the snapshot function, it must send synthetic [vfunc@Gtk.Widget.snapshot] calls @@ -113400,16 +113392,16 @@ of doing this. A widget, when it receives a call to its gtk_widget_snapshot_child() once for each child, passing in the @snapshot the widget received. -gtk_widget_snapshot_child() takes care of translating the origin of -@snapshot, and deciding whether the child needs to be snapshot. +This function takes care of translating the origin of @snapshot, +and deciding whether the child needs to be snapshot. -This function does nothing for children that implement `GtkNative`. +It does nothing for children that implement `GtkNative`. - a `GtkWidget` + a widget @@ -113417,62 +113409,61 @@ This function does nothing for children that implement `GtkNative`. - `GtkSnapshot` as passed to the widget. In particular, no - calls to gtk_snapshot_translate() or other transform calls should - have been made. + snapshot as passed to the widget. In particular, no + calls to [method@Gtk.Snapshot.translate] or other transform calls + should have been made - Translate coordinates relative to @src_widget’s allocation + Translates coordinates relative to @src_widget’s allocation to coordinates relative to @dest_widget’s allocations. In order to perform this operation, both widget must share -a common ancestor. - Use gtk_widget_compute_point() instead +a common ancestor. If that is not the case, @dest_x and @dest_y +are set to 0 and false is returned. + Use [method@Gtk.Widget.compute_point] instead - %FALSE if @src_widget and @dest_widget have no common - ancestor. In this case, 0 is stored in *@dest_x and *@dest_y. - Otherwise %TRUE. + true if @src_widget and @dest_widget have a common + ancestor, false otherwise - a `GtkWidget` + a widget - a `GtkWidget` + another widget - X position relative to @src_widget + X position in widget coordinates of @src_widget - Y position relative to @src_widget + Y position in widget coordinates of @src_widget - location to store X position relative to @dest_widget + location to store X position in widget coordinates of @dest_widget - location to store Y position relative to @dest_widget + location to store Y position in widget coordinates of @dest_widget - Triggers a tooltip query on the display where the toplevel -of @widget is located. + Triggers a tooltip query on the display of the widget. - a `GtkWidget` + a widget @@ -113486,13 +113477,13 @@ This function is only for use in widget implementations. - a `GtkWidget` + a widget - Dissociate @widget from its parent. + Removes @widget from its parent. This function is only for use in widget implementations, typically in dispose. @@ -113501,14 +113492,15 @@ typically in dispose. - a `GtkWidget` + a widget - Causes a widget to be unrealized (frees all GDK resources -associated with the widget). + Causes a widget to be unrealized. + +This frees all GDK resources associated with the widget. This function is only useful in widget implementations. @@ -113516,7 +113508,7 @@ This function is only useful in widget implementations. - a `GtkWidget` + a widget @@ -113532,11 +113524,11 @@ This function is for use in widget implementations. - a `GtkWidget` + a widget - State flags to turn off + state flags to turn off @@ -113593,15 +113585,16 @@ This property is only relevant for widgets that can take focus. - Enables or disables the emission of the ::query-tooltip signal on @widget. + Enables or disables the emission of the [signal@Gtk.Widget::query-tooltip] +signal on @widget. -A value of %TRUE indicates that @widget can have a tooltip, in this case +A true value indicates that @widget can have a tooltip, in this case the widget will be queried using [signal@Gtk.Widget::query-tooltip] to determine whether it will provide a tooltip or not. - Override for height request of the widget. + Overrides for height request of the widget. If this is -1, the natural request will be used. @@ -113615,8 +113608,8 @@ If this is -1, the natural request will be used. - The `GtkLayoutManager` instance to use to compute the preferred size -of the widget, and allocate its children. + The [class@Gtk.LayoutManager] instance to use to compute +the preferred size of the widget, and allocate its children. This property is meant to be set by widget implementations, typically in their instance init function. @@ -113686,7 +113679,7 @@ typically in their instance init function. The `GtkRoot` widget of the widget tree containing this widget. -This will be %NULL if the widget is not contained in a root widget. +This will be `NULL` if the widget is not contained in a root widget. @@ -113704,8 +113697,8 @@ with Pango markup. Also see [method@Gtk.Tooltip.set_markup]. This is a convenience property which will take care of getting the -tooltip shown if the given string is not %NULL: -[property@Gtk.Widget:has-tooltip] will automatically be set to %TRUE +tooltip shown if the given string is not `NULL`: +[property@Gtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signal@Gtk.Widget::query-tooltip] in the default signal handler. @@ -113719,8 +113712,8 @@ Note that if both [property@Gtk.Widget:tooltip-text] and Also see [method@Gtk.Tooltip.set_text]. This is a convenience property which will take care of getting the -tooltip shown if the given string is not %NULL: -[property@Gtk.Widget:has-tooltip] will automatically be set to %TRUE +tooltip shown if the given string is not `NULL`: +[property@Gtk.Widget:has-tooltip] will automatically be set to true and there will be taken care of [signal@Gtk.Widget::query-tooltip] in the default signal handler. @@ -113745,7 +113738,7 @@ Note that if both [property@Gtk.Widget:tooltip-text] and - Override for width request of the widget. + Overrides for width request of the widget. If this is -1, the natural request will be used. @@ -113774,7 +113767,7 @@ This signal is not suitable for saving widget state. - the previous text direction of @widget + the previous text direction @@ -113790,9 +113783,9 @@ This signal is not suitable for saving widget state. See [method@Gtk.Widget.keynav_failed] for details. - %TRUE if stopping keyboard navigation is fine, %FALSE + true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard - navigation attempt in its parent widget(s). + navigation attempt in its parent widget @@ -113809,7 +113802,7 @@ A widget is mapped when the widget is visible (which is controlled with [property@Gtk.Widget:visible]) and all its parents up to the toplevel widget are also visible. -The ::map signal can be used to determine whether a widget will be drawn, +The `::map` signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of [signal@Gtk.Widget::unmap]. @@ -113820,15 +113813,15 @@ emission of [signal@Gtk.Widget::unmap]. Emitted when a widget is activated via a mnemonic. The default handler for this signal activates @widget if @group_cycling -is %FALSE, or just makes @widget grab focus if @group_cycling is %TRUE. +is false, or just makes @widget grab focus if @group_cycling is true. - %TRUE to stop other handlers from being invoked for the event. -%FALSE to propagate the event further. + true to stop other handlers from being invoked for the event, + false to propagate the event further - %TRUE if there are other widgets with the same mnemonic + true if there are other widgets with the same mnemonic @@ -113836,7 +113829,7 @@ is %FALSE, or just makes @widget grab focus if @group_cycling is %TRUE. Emitted when the focus is moved. -The ::move-focus signal is a [keybinding signal](class.SignalAction.html). +The `::move-focus` signal is a [keybinding signal](class.SignalAction.html). The default bindings for this signal are <kbd>Tab</kbd> to move forward, and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward. @@ -113854,34 +113847,31 @@ and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward.Emitted when the widget’s tooltip is about to be shown. This happens when the [property@Gtk.Widget:has-tooltip] property -is %TRUE and the hover timeout has expired with the cursor hovering -"above" @widget; or emitted when @widget got focus in keyboard mode. +is true and the hover timeout has expired with the cursor hovering +above @widget; or emitted when @widget got focus in keyboard mode. Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case -%TRUE should be returned, %FALSE otherwise. Note that if -@keyboard_mode is %TRUE, the values of @x and @y are undefined and -should not be used. +true should be returned, false otherwise. Note that if @keyboard_mode +is true, the values of @x and @y are undefined and should not be used. The signal handler is free to manipulate @tooltip with the therefore destined function calls. - %TRUE if @tooltip should be shown right now, %FALSE otherwise. + true if @tooltip should be shown right now, false otherwise - the x coordinate of the cursor position where the request has - been emitted, relative to @widget's left side + the x coordinate of the cursor position in widget coordinates - the y coordinate of the cursor position where the request has - been emitted, relative to @widget's top + the y coordinate of the cursor position in widget coordinates - %TRUE if the tooltip was triggered using the keyboard + true if the tooltip was triggered using the keyboard @@ -113914,7 +113904,7 @@ See [method@Gtk.Widget.get_state_flags]. - The previous state flags. + the previous state flags @@ -113925,7 +113915,7 @@ See [method@Gtk.Widget.get_state_flags]. A widget is unmapped when either it or any of its parents up to the toplevel widget have been set as hidden. -As ::unmap indicates that a widget will not be shown any longer, +As `::unmap` indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget. @@ -113943,7 +113933,7 @@ or the widget has been unmapped (that is, it is going to be hidden). The type of the callback functions used for activating -actions installed with gtk_widget_class_install_action(). +actions installed with [method@Gtk.WidgetClass.install_action]. The @parameter must match the @parameter_type of the action. @@ -113980,7 +113970,7 @@ The @parameter must match the @parameter_type of the action. - a `GtkWidget` + a widget @@ -113994,7 +113984,7 @@ The @parameter must match the @parameter_type of the action. - a `GtkWidget` + a widget @@ -114011,7 +114001,7 @@ The @parameter must match the @parameter_type of the action. - a `GtkWidget` + a widget @@ -114027,7 +114017,7 @@ The @parameter must match the @parameter_type of the action. - a `GtkWidget` + a widget @@ -114043,7 +114033,7 @@ The @parameter must match the @parameter_type of the action. - a `GtkWidget` + a widget @@ -114060,7 +114050,7 @@ The @parameter must match the @parameter_type of the action. - a `GtkWidget` + a widget @@ -114233,16 +114223,16 @@ The @parameter must match the @parameter_type of the action. %FALSE, and just grabs the focus if @group_cycling is %TRUE. - %TRUE if the signal has been handled + true if the signal has been handled - a `GtkWidget` + a widget - %TRUE if there are other widgets with the same mnemonic + true if there are other widgets with the same mnemonic @@ -114253,12 +114243,12 @@ The @parameter must match the @parameter_type of the action. `GtkWindow` it’s inside. - %TRUE if focus is now inside @widget. + true if focus is now inside @widget - a `GtkWidget` + a widget @@ -114288,12 +114278,12 @@ The @parameter must match the @parameter_type of the action. - a `GtkWidget` + a widget - a direct child widget of @widget or %NULL - to unset the focus child of @widget + a direct child widget of @widget + or `NULL` to unset the focus child @@ -114319,14 +114309,14 @@ The @parameter must match the @parameter_type of the action. Signal emitted if keyboard navigation fails. - %TRUE if stopping keyboard navigation is fine, %FALSE + true if stopping keyboard navigation is fine, false if the emitting widget should try to handle the keyboard - navigation attempt in its parent container(s). + navigation attempt in its parent widget - a `GtkWidget` + a widget @@ -114438,7 +114428,7 @@ The @parameter must match the @parameter_type of the action. Vfunc for gtk_widget_contains(). - %TRUE if @widget contains (@x, @y). + true if @widget contains the point (x, y) @@ -114467,14 +114457,14 @@ The @parameter must match the @parameter_type of the action. Creates a new shortcut for @widget_class that calls the given @callback -with arguments read according to @format_string. +with arguments according to @format_string. The arguments and format string must be provided in the same way as -with g_variant_new(). +with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class -initialization. It does not provide for user_data, if you need that, +initialization. It does not provide for user data, if you need that, you will have to use [method@Gtk.WidgetClass.add_shortcut] with a custom shortcut. @@ -114498,8 +114488,7 @@ shortcut. - GVariant format string for arguments - or %NULL for no arguments + `GVariant` format string for arguments @@ -114513,7 +114502,7 @@ shortcut. @action_name with arguments read according to @format_string. The arguments and format string must be provided in the same way as -with g_variant_new(). +with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class @@ -114539,8 +114528,7 @@ initialization. - GVariant format string for arguments - or %NULL for no arguments + `GVariant` format string for arguments @@ -114554,7 +114542,7 @@ initialization. @signal with arguments read according to @format_string. The arguments and format string must be provided in the same way as -with g_variant_new(). +with [ctor@GLib.Variant.new]. This function is a convenience wrapper around [method@Gtk.WidgetClass.add_shortcut] and must be called during class @@ -114580,8 +114568,7 @@ initialization. - GVariant format string for arguments - or %NULL for no arguments + `GVariant` format string for arguments @@ -114596,7 +114583,7 @@ initialization. Every instance created for @widget_class or its subclasses will inherit this shortcut and trigger it. -Shortcuts added this way will be triggered in the %GTK_PHASE_BUBBLE +Shortcuts added this way will be triggered in the [enum@Gtk.PropagationPhase.bubble] phase, which means they may also trigger if child widgets have focus. This function must only be used in class initialization functions @@ -114610,17 +114597,18 @@ otherwise it is not guaranteed that the shortcut will be installed. - the `GtkShortcut` to add + the shortcut to add - Declares a @callback_symbol to handle @callback_name from -the template XML defined for @widget_type. + Associates a name to be used in GtkBuilder XML with a symbol. This function is not supported after [method@Gtk.WidgetClass.set_template_scope] -has been used on @widget_class. See [method@Gtk.BuilderCScope.add_callback_symbol]. +has been used on @widget_class. + +See [method@Gtk.BuilderCScope.add_callback_symbol]. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. @@ -114629,22 +114617,22 @@ class initializer after calling [method@Gtk.WidgetClass.set_template]. - A `GtkWidgetClass` + a widget class - The name of the callback as expected in the template XML + name of the callback as expected in the template XML - The callback symbol + the callback symbol - Automatically assign an object declared in the class template XML to -be set to a location on a freshly built instance’s private data, or + Assigns an object declared in the class template XML to be set to +a location on a freshly built instance’s private data, or alternatively accessible via [method@Gtk.Widget.get_template_child]. The struct can point either into the public instance, then you should @@ -114653,14 +114641,14 @@ private struct, then you should use `G_PRIVATE_OFFSET(WidgetType, member)`. An explicit strong reference will be held automatically for the duration of your instance’s life cycle, it will be released automatically when -`GObjectClass.dispose()` runs on your instance and if a @struct_offset -that is `!= 0` is specified, then the automatic location in your instance -public or private data will be set to %NULL. You can however access an -automated child pointer the first time your classes `GObjectClass.dispose()` -runs, or alternatively in [signal@Gtk.Widget::destroy]. +`GObjectClass.dispose()` runs on your instance and if a nonzero @struct_offset +is specified, then the automatic location in your instance public or private +data will be set to `NULL`. You can however access an automated child pointer +the first time your classes `GObjectClass.dispose()` runs, or alternatively +in [signal@Gtk.Widget::destroy]. If @internal_child is specified, [vfunc@Gtk.Buildable.get_internal_child] -will be automatically implemented by the `GtkWidget` class so there is no +will be automatically implemented by the widget class so there is no need to implement it manually. The wrapper macros [func@Gtk.widget_class_bind_template_child], @@ -114676,28 +114664,28 @@ initializer after calling [method@Gtk.WidgetClass.set_template]. - A `GtkWidgetClass` + a widget class - The “id” of the child defined in the template XML + ID of the child defined in the template XML - Whether the child should be accessible as an “internal-child” + whether the child should be accessible as an “internal-child” when this class is used in GtkBuilder XML - The structure offset into the composite widget’s instance + The offset into the composite widget’s instance public or private structure where the automated child pointer should be set, - or 0 to not assign the pointer. + or 0 to not assign the pointer - Retrieves the accessible role used by the given `GtkWidget` class. + Retrieves the accessible role used by the given widget class. Different accessible roles have different states, and are rendered differently by assistive technologies. @@ -114709,7 +114697,7 @@ See also: [method@Gtk.Accessible.get_accessible_role]. - a `GtkWidgetClass` + a widget class @@ -114717,7 +114705,7 @@ See also: [method@Gtk.Accessible.get_accessible_role]. Retrieves the signal id for the activation signal. -the activation signal is set using +The activation signal is set using [method@Gtk.WidgetClass.set_activate_signal]. a signal id, or 0 if the widget class does not @@ -114726,7 +114714,7 @@ the activation signal is set using - a `GtkWidgetClass` + a widget class @@ -114752,29 +114740,30 @@ used by widgets of class @widget_class. See also: [method@Gtk.WidgetClass.set_layout_manager_type]. - type of a `GtkLayoutManager` subclass, or %G_TYPE_INVALID + type of a `GtkLayoutManager` subclass, or `G_TYPE_INVALID` - a `GtkWidgetClass` + a widget class - This should be called at class initialization time to specify -actions to be added for all instances of this class. + Adds an action for all instances of a widget class. + +This function should be called at class initialization time. Actions installed by this function are stateless. The only state -they have is whether they are enabled or not (which can be changed with -[method@Gtk.Widget.action_set_enabled]). +they have is whether they are enabled or not (which can be changed +with [method@Gtk.Widget.action_set_enabled]). - a `GtkWidgetClass` + a widget class @@ -114812,7 +114801,7 @@ of the same type as the property. - a `GtkWidgetClass` + a widget class @@ -114820,15 +114809,15 @@ of the same type as the property. - name of the property in instances of @widget_class - or any parent class. + name of a property in instances of @widget_class + or any parent class - Returns details about the @index_-th action that has been -installed for @widget_class during class initialization. + Returns details about an action that has been +installed for @widget_class. See [method@Gtk.WidgetClass.install_action] for details on how to install actions. @@ -114837,13 +114826,12 @@ Note that this function will also return actions defined by parent classes. You can identify those by looking at @owner. - %TRUE if the action was found, %FALSE if @index_ - is out of range + true if the action was found - a `GtkWidget` class + a widget class @@ -114869,7 +114857,7 @@ at @owner. - Sets the accessible role used by the given `GtkWidget` class. + Sets the accessible role used by the given widget class. Different accessible roles have different states, and are rendered differently by assistive technologies. @@ -114878,29 +114866,28 @@ rendered differently by assistive technologies. - a `GtkWidgetClass` + a widget class - the `GtkAccessibleRole` used by the @widget_class + the accessible role to use - Sets the `GtkWidgetClass.activate_signal` field with the -given @signal_id. + Sets the activation signal for a widget class. The signal will be emitted when calling [method@Gtk.Widget.activate]. -The @signal_id must have been registered with `g_signal_new()` -or g_signal_newv() before calling this function. +The @signal_id must have been registered with [function.GObject.signal_new] +or [func@GObject.signal_newv] before calling this function. - a `GtkWidgetClass` + a widget class @@ -114910,19 +114897,20 @@ or g_signal_newv() before calling this function. - Sets the `GtkWidgetClass.activate_signal` field with the signal id for -the given @signal_name. + Sets the activation signal for a widget class. + +The signal id will by looked up by @signal_name. The signal will be emitted when calling [method@Gtk.Widget.activate]. -The @signal_name of @widget_type must have been registered with -g_signal_new() or g_signal_newv() before calling this function. +The @signal_name must have been registered with [function.GObject.signal_new] +or [func@GObject.signal_newv] before calling this function. - a `GtkWidgetClass` + a widget class @@ -114964,11 +114952,11 @@ of widgets. - a `GtkWidgetClass` + a widget class - The object type that implements the `GtkLayoutManager` + the object type that implements the `GtkLayoutManager` for @widget_class @@ -114988,18 +114976,18 @@ Note that any class that installs templates must call - A `GtkWidgetClass` + a widget class - A `GBytes` holding the `GtkBuilder` XML + `GBytes` holding the `GtkBuilder` XML A convenience function that calls [method@Gtk.WidgetClass.set_template] -with the contents of a `GResource`. +with the contents of a resource. Note that any class that installs templates must call [method@Gtk.Widget.init_template] in the widget’s instance @@ -115009,19 +114997,19 @@ initializer. - A `GtkWidgetClass` + a widget class - The name of the resource to load the template from + resource path to load the template from - For use in language bindings, this will override the default -`GtkBuilderScope` to be used when parsing GtkBuilder XML from -this class’s template data. + Overrides the default scope to be used when parsing the class template. + +This function is intended for language bindings. Note that this must be called from a composite widget classes class initializer after calling [method@Gtk.WidgetClass.set_template]. @@ -115030,11 +115018,11 @@ initializer after calling [method@Gtk.WidgetClass.set_template]. - A `GtkWidgetClass` + a widget class - The `GtkBuilderScope` to use when loading + `GtkBuilderScope` to use when loading the class template @@ -117553,6 +117541,16 @@ necessary. + + Prevents GTK from using portals. + +This is equivalent to setting `GDK_DEBUG=no-portals` in the environment. + +This should only be used in portal implementations, apps must not call it. + + + + Prevents [func@Gtk.init] and [func@Gtk.init_check] from automatically calling `setlocale (LC_ALL, "")`. @@ -119169,13 +119167,13 @@ This function transfers the ownership of the `expression` to the `GValue`. Binds a callback function defined in a template to the @widget_class. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_callback_full() function. It is not -supported after gtk_widget_class_set_template_scope() has been used -on @widget_class. +This macro is a convenience wrapper around +[method@Gtk.WidgetClass.bind_template_callback_full]. It is not +supported after [method@Gtk.WidgetClass.set_template_scope] has been +called on @widget_class. - a `GtkWidgetClass` + a widget class the callback symbol @@ -119185,14 +119183,14 @@ on @widget_class. Binds a child widget defined in a template to the @widget_class. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_child_full() function. +This macro is a convenience wrapper around +[method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName instance structure. - a `GtkWidgetClass` + a widget class the type name of this widget @@ -119203,18 +119201,19 @@ instance structure. - Binds a child widget defined in a template to the @widget_class, and -also makes it available as an internal child in GtkBuilder, under the -name @member_name. + Binds a child widget defined in a template to the @widget_class. + +Additionally, the child widget is made available as an internal +child in `GtkBuilder`, under the name @member_name. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_child_full() function. +This macro is a convenience wrapper around +[method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName instance structure. - a `GtkWidgetClass` + a widget class the type name, in CamelCase @@ -119225,18 +119224,19 @@ instance structure. - Binds a child widget defined in a template to the @widget_class, and -also makes it available as an internal child in GtkBuilder, under the -name @member_name. + Binds a child widget defined in a template to the @widget_class. + +Additionally, the child is made available as an internal child +in `GtkBuilder`, under the name @member_name. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_child_full() function. +This macro is a convenience wrapper around +[method@Gtk.WidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName private data structure. - a `GtkWidgetClass` + a widget class the type name, in CamelCase @@ -119249,15 +119249,15 @@ private data structure. Binds a child widget defined in a template to the @widget_class. -This macro is a convenience wrapper around the -gtk_widget_class_bind_template_child_full() function. +This macro is a convenience wrapper around +[method@GtkWidgetClass.bind_template_child_full]. This macro will use the offset of the @member_name inside the @TypeName -private data structure (it uses G_PRIVATE_OFFSET(), so the private struct -must be added with G_ADD_PRIVATE()). +private data structure (it uses `G_PRIVATE_OFFSET()`, so the private struct +must be added with `G_ADD_PRIVATE())`. - a `GtkWidgetClass` + a widget class the type name of this widget