diff --git a/GLib-2.0.gir b/GLib-2.0.gir index 0a894f0..96473ec 100644 --- a/GLib-2.0.gir +++ b/GLib-2.0.gir @@ -8,13 +8,18 @@ and/or use gtk-doc annotations. --> Integer representing a day of the month; between 1 and 31. -#G_DATE_BAD_DAY represents an invalid day of the month. + +The %G_DATE_BAD_DAY value represents an invalid day of the month. - Integer representing a year; #G_DATE_BAD_YEAR is the invalid -value. The year must be 1 or higher; negative (BC) years are not -allowed. The year is represented with four digits. + Integer type representing a year. + +The %G_DATE_BAD_YEAR value is the invalid value. The year +must be 1 or higher; negative ([BCE](https://en.wikipedia.org/wiki/Common_Era)) +years are not allowed. + +The year is represented with four digits. @@ -70,7 +75,9 @@ g_auto(). Simply a replacement for `time_t`. It has been deprecated since it is not equivalent to `time_t` on 64-bit platforms -with a 64-bit `time_t`. Unrelated to #GTimer. +with a 64-bit `time_t`. + +Unrelated to #GTimer. Note that #GTime is defined to always be a 32-bit integer, unlike `time_t` which may be 64-bit on some systems. Therefore, @@ -79,6 +86,7 @@ address of a #GTime variable as argument to the UNIX time() function. Instead, do the following: + |[<!-- language="C" --> time_t ttime; GTime gtime; @@ -239,7 +247,7 @@ gboolean result = g_array_binary_search (garray, &i, cmpint, &matched_in A #GCompareFunc used to locate @target. - + return location for the index of the element, if found. @@ -510,7 +518,28 @@ pointer to the element to clear, rather than the element itself. Note that in contrast with other uses of #GDestroyNotify functions, @clear_func is expected to clear the contents of -the array element it is given, but not free the element itself. +the array element it is given, but not free the element itself. + +|[<!-- language="C" --> +typedef struct +{ + gchar *str; + GObject *obj; +} ArrayElement; + +static void +array_element_clear (ArrayElement *element) +{ + g_clear_pointer (&element->str, g_free); + g_clear_object (&element->obj); +} + +// main code +GArray *garray = g_array_new (FALSE, FALSE, sizeof (ArrayElement)); +g_array_set_clear_func (garray, (GDestroyNotify) array_element_clear); +// assign data to the structure +g_array_free (garray, TRUE); +]| @@ -664,7 +693,7 @@ data = g_array_steal (some_array, &data_len); - + pointer to retrieve the number of elements of the original array @@ -714,9 +743,9 @@ thread. - The GAsyncQueue struct is an opaque data structure which represents -an asynchronous queue. It should only be accessed through the -g_async_queue_* functions. + An opaque data structure which represents an asynchronous queue. + +It should only be accessed through the `g_async_queue_*` functions. Returns the length of the queue. @@ -1283,7 +1312,7 @@ the queue is destroyed after the final unref. - + function to free queue elements @@ -1296,8 +1325,7 @@ See #G_BYTE_ORDER. - The `GBookmarkFile` structure contains only -private data and should not be directly accessed. + An opaque data structure representing a set of bookmarks. Adds the application with @name and @exec to the list of applications that have registered a bookmark for @uri into @@ -2903,7 +2931,7 @@ to the caller. - + pointer to retrieve the number of elements of the original array @@ -3139,6 +3167,50 @@ not be returned if @size is non-zero. + + Gets a pointer to a region in @bytes. + +The region starts at @offset many bytes from the start of the data +and contains @n_elements many elements of @element_size size. + +@n_elements may be zero, but @element_size must always be non-zero. +Ideally, @element_size is a static constant (eg: sizeof a struct). + +This function does careful bounds checking (including checking for +arithmetic overflows) and returns a non-%NULL pointer if the +specified region lies entirely within the @bytes. If the region is +in some way out of range, or if an overflow has occurred, then %NULL +is returned. + +Note: it is possible to have a valid zero-size region. In this case, +the returned pointer will be equal to the base pointer of the data of +@bytes, plus @offset. This will be non-%NULL except for the case +where @bytes itself was a zero-sized region. Since it is unlikely +that you will be using this function to check for a zero-sized region +in a zero-sized @bytes, %NULL effectively always means "error". + + the requested region, or %NULL in case of an error + + + + + a #GBytes + + + + a non-zero element size + + + + an offset to the start of the region within the @bytes + + + + the number of elements in the region + + + + Get the size of the byte data in the #GBytes. @@ -3314,6 +3386,7 @@ in #GScannerConfig. An opaque structure representing a checksumming operation. + To create a new GChecksum, use g_checksum_new(). To free a GChecksum, use g_checksum_free(). @@ -3492,8 +3565,12 @@ date to include new hashing algorithm types. Prototype of a #GChildWatchSource callback, called when a child -process has exited. To interpret @status, see the documentation -for g_spawn_check_exit_status(). +process has exited. + +To interpret @wait_status, see the documentation +for g_spawn_check_wait_status(). In particular, +on Unix platforms, note that it is usually not equal +to the integer passed to `exit()` or returned from `main()`. @@ -3502,9 +3579,9 @@ for g_spawn_check_exit_status(). the process id of the child process - + Status information about the child process, encoded - in a platform-specific manner + in a platform-specific manner @@ -3967,6 +4044,30 @@ where cleanup is not supported. + + A convenience macro which defines two functions. First, returning +the #GQuark for the extended error type @ErrorType; it is called +`error_type_quark()`. Second, returning the private data from a +passed #GError; it is called `error_type_get_private()`. + +For this macro to work, a type named `ErrorTypePrivate` should be +defined, `error_type_private_init()`, `error_type_private_copy()` +and `error_type_private_clear()` functions need to be either +declared or defined. The functions should be similar to +#GErrorInitFunc, #GErrorCopyFunc and #GErrorClearFunc, +respectively, but they should receive the private data type instead +of #GError. + +See [Extended #GError Domains][gerror-extended-domains] for an example. + + + name to return a #GQuark for + + + prefix for the function name + + + A convenience macro which defines a function returning the #GQuark for the name @QN. The function will be named @@ -4115,6 +4216,18 @@ in the macro, so you shouldn't use double quotes. + + + + + + + + + + + + This macro is similar to %G_GNUC_DEPRECATED_FOR, and can be used to mark functions declarations as deprecated. Unlike %G_GNUC_DEPRECATED_FOR, it @@ -4257,6 +4370,18 @@ int my_mistake (void); + + + + + + + + + + + + @@ -4389,6 +4514,18 @@ int my_mistake (void); + + + + + + + + + + + + @@ -4521,6 +4658,18 @@ int my_mistake (void); + + + + + + + + + + + + The directory separator character. This is '/' on UNIX machines and '\' under Windows. @@ -4532,9 +4681,9 @@ This is "/" on UNIX machines and "\" under Windows. - The #GData struct is an opaque data structure to represent a -[Keyed Data List][glib-Keyed-Data-Lists]. It should only be -accessed via the following functions. + An opaque data structure that represents a keyed data list. + +See also: [Keyed data lists][glib-Keyed-Data-Lists]. Specifies the type of function passed to g_dataset_foreach(). It is @@ -4562,7 +4711,7 @@ with the @user_data parameter supplied to g_dataset_foreach(). Represents a day between January 1, Year 1 and a few thousand years in the future. None of its members should be accessed directly. -If the #GDate-struct is obtained from g_date_new(), it will be safe +If the `GDate` is obtained from g_date_new(), it will be safe to mutate but invalid and thus not safe for calendrical computations. If it's declared on the stack, it will contain garbage so must be @@ -4584,12 +4733,12 @@ and year. the day of the day-month-year representation of the date, - as a number between 1 and 31 + as a number between 1 and 31 the day of the day-month-year representation of the date, - as a number between 1 and 12 + as a number between 1 and 12 @@ -5474,8 +5623,8 @@ to mark a number as a day, month, or year. - Enumeration representing a month; values are #G_DATE_JANUARY, -#G_DATE_FEBRUARY, etc. #G_DATE_BAD_MONTH is the invalid value. + Enumeration representing a month; values are %G_DATE_JANUARY, +%G_DATE_FEBRUARY, etc. %G_DATE_BAD_MONTH is the invalid value. invalid value @@ -5517,8 +5666,7 @@ to mark a number as a day, month, or year. - `GDateTime` is an opaque structure whose members -cannot be accessed directly. + An opaque structure that represents a date and time, including a time zone. Creates a new #GDateTime corresponding to the given date and time in the time zone @tz. @@ -7075,7 +7223,141 @@ a certain case, your code will still work. + + This function registers an extended #GError domain. +@error_type_name will be duplicated. Otherwise does the same as +g_error_domain_register_static(). + + #GQuark representing the error domain + + + + + string to create a #GQuark from + + + + size of the private error data in bytes + + + + function initializing fields of the private error data + + + + function copying fields of the private error data + + + + function freeing fields of the private error data + + + + + + This function registers an extended #GError domain. + +@error_type_name should not be freed. @error_type_private_size must +be greater than 0. + +@error_type_init receives an initialized #GError and should then initialize +the private data. + +@error_type_copy is a function that receives both original and a copy +#GError and should copy the fields of the private error data. The standard +#GError fields are already handled. + +@error_type_clear receives the pointer to the error, and it should free the +fields of the private error data. It should not free the struct itself though. + +Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it +already takes care of passing valid information to this function. + + #GQuark representing the error domain + + + + + static string to create a #GQuark from + + + + size of the private error data in bytes + + + + function initializing fields of the private error data + + + + function copying fields of the private error data + + + + function freeing fields of the private error data + + + + + + Specifies the type of function which is called when an extended +error instance is freed. It is passed the error pointer about to be +freed, and should free the error's private data fields. + +Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it +already takes care of getting the private data from @error. + + + + + + extended error to clear + + + + + + Specifies the type of function which is called when an extended +error instance is copied. It is passed the pointer to the +destination error and source error, and should copy only the fields +of the private data from @src_error to @dest_error. + +Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it +already takes care of getting the private data from @src_error and +@dest_error. + + + + + + source extended error + + + + destination extended error + + + + + + Specifies the type of function which is called just after an +extended error instance is created and its fields filled. It should +only initialize the fields in the private data, which can be +received with the generated `*_get_private()` function. + +Normally, it is better to use G_DEFINE_EXTENDED_ERROR(), as it +already takes care of getting the private data from @error. + + + + + + extended error + + + + The possible errors, used in the @v_error field of #GTokenValue, when the token is a %G_TOKEN_ERROR. @@ -7240,27 +7522,27 @@ differences in when a system will report a given error, etc. performance. No guarantees about file consistency or durability. - The most dangerous setting, which is slightly faster than other settings. + The most dangerous setting, which is slightly faster than other settings. Guarantee file consistency: after a crash, - either the old version of the file or the new version of the file will be - available, but not a mixture. On Unix systems this equates to an `fsync()` - on the file and use of an atomic `rename()` of the new version of the file - over the old. + either the old version of the file or the new version of the file will be + available, but not a mixture. On Unix systems this equates to an `fsync()` + on the file and use of an atomic `rename()` of the new version of the file + over the old. Guarantee file durability: after a crash, the - new version of the file will be available. On Unix systems this equates to - an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or - the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the - directory containing the file after calling `rename()`. + new version of the file will be available. On Unix systems this equates to + an `fsync()` on the file (if %G_FILE_SET_CONTENTS_CONSISTENT is unset), or + the effects of %G_FILE_SET_CONTENTS_CONSISTENT plus an `fsync()` on the + directory containing the file after calling `rename()`. Only apply consistency and durability - guarantees if the file already exists. This may speed up file operations - if the file doesn’t currently exist, but may result in a corrupted version - of the new file if the system crashes while writing it. + guarantees if the file already exists. This may speed up file operations + if the file doesn’t currently exist, but may result in a corrupted version + of the new file if the system crashes while writing it. @@ -8141,7 +8423,7 @@ first to transfer ownership of the keys. - + the length of the returned array @@ -10488,23 +10770,23 @@ This function cannot be called on a channel with %NULL encoding. A bitwise combination representing a condition to watch for on an event source. - + There is data to read. - + Data can be written (without blocking). - + There is urgent data to read. - + Error condition. - + Hung up (the connection has been broken, usually for pipes and sockets). - + Invalid request. The file descriptor is not open. @@ -10754,140 +11036,141 @@ details about the meanings of the keys below. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string list + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string list giving the available application actions. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of strings giving the categories in which the desktop entry should be shown in a menu. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the tooltip for the desktop entry. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean set to true -if the application is D-Bus activatable. + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean +set to true if the application is D-Bus activatable. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string giving the command line to execute. It is only valid for desktop entries with the `Application` type. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the generic name of the desktop entry. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the desktop entry has been deleted by the user. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the name of the icon to be displayed for the desktop entry. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of strings giving the MIME types supported by this desktop entry. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a localized + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a localized string giving the specific name of the desktop entry. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of strings identifying the environments that should not display the desktop entry. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the desktop entry should be shown in menus. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a list of + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a list of strings identifying the environments that should display the desktop entry. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string containing the working directory to run the program in. It is only valid for desktop entries with the `Application` type. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the application supports the [Startup Notification Protocol Specification](http://www.freedesktop.org/Standards/startup-notification-spec). - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is string + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is string identifying the WM class or name hint of a window that the application will create, which can be used to emulate Startup Notification with older applications. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a boolean stating whether the program should be run in a terminal window. -It is only valid for desktop entries with the -`Application` type. + +It is only valid for desktop entries with the `Application` type. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string giving the file name of a binary on disk used to determine if the program is actually installed. It is only valid for desktop entries with the `Application` type. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string -giving the type of the desktop entry. Usually -#G_KEY_FILE_DESKTOP_TYPE_APPLICATION, -#G_KEY_FILE_DESKTOP_TYPE_LINK, or -#G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string +giving the type of the desktop entry. + +Usually %G_KEY_FILE_DESKTOP_TYPE_APPLICATION, +%G_KEY_FILE_DESKTOP_TYPE_LINK, or +%G_KEY_FILE_DESKTOP_TYPE_DIRECTORY. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string giving the URL to access. It is only valid for desktop entries with the `Link` type. - A key under #G_KEY_FILE_DESKTOP_GROUP, whose value is a string + A key under %G_KEY_FILE_DESKTOP_GROUP, whose value is a string giving the version of the Desktop Entry Specification used for the desktop entry file. - The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing applications. - The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing directories. - The value of the #G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop + The value of the %G_KEY_FILE_DESKTOP_KEY_TYPE, key for desktop entries representing links to documents. @@ -12220,7 +12503,7 @@ reaches zero, frees the key file and all its allocated memory. Error codes returned by key file parsing. the text being parsed was in - an unknown encoding + an unknown encoding document was ill-formed @@ -12245,15 +12528,15 @@ reaches zero, frees the key file and all its allocated memory. Use this flag if you plan to write the - (possibly modified) contents of the key file back to a file; - otherwise all comments will be lost when the key file is - written back. + (possibly modified) contents of the key file back to a file; + otherwise all comments will be lost when the key file is + written back. Use this flag if you plan to write the - (possibly modified) contents of the key file back to a file; - otherwise only the translations for the current language will be - written back. + (possibly modified) contents of the key file back to a file; + otherwise only the translations for the current language will be + written back. @@ -12285,7 +12568,7 @@ See #G_BYTE_ORDER. Works like g_mutex_lock(), but for a lock defined with -#G_LOCK_DEFINE. +%G_LOCK_DEFINE. the name of the lock @@ -12293,16 +12576,17 @@ See #G_BYTE_ORDER. - The #G_LOCK_ macros provide a convenient interface to #GMutex. -#G_LOCK_DEFINE defines a lock. It can appear in any place where + The `G_LOCK_` macros provide a convenient interface to #GMutex. +%G_LOCK_DEFINE defines a lock. It can appear in any place where variable definitions may appear in programs, i.e. in the first block of a function or outside of functions. The @name parameter will be mangled to get the name of the #GMutex. This means that you can use names of existing variables as the parameter - e.g. the name of the variable you intend to protect with the lock. Look at our -give_me_next_number() example using the #G_LOCK macros: +give_me_next_number() example using the `G_LOCK` macros: + +Here is an example for using the `G_LOCK` convenience macros: -Here is an example for using the #G_LOCK convenience macros: |[<!-- language="C" --> G_LOCK_DEFINE (current_number); @@ -12326,7 +12610,7 @@ Here is an example for using the #G_LOCK convenience macros: - This works like #G_LOCK_DEFINE, but it creates a static object. + This works like %G_LOCK_DEFINE, but it creates a static object. the name of the lock @@ -12334,7 +12618,7 @@ Here is an example for using the #G_LOCK convenience macros: - This declares a lock, that is defined with #G_LOCK_DEFINE in another + This declares a lock, that is defined with %G_LOCK_DEFINE in another module. @@ -13371,7 +13655,7 @@ should return %G_LOG_WRITER_UNHANDLED. This allows writer functions to be chained and fall back to simpler handlers in case of failure. %G_LOG_WRITER_HANDLED if the log entry was handled successfully; - %G_LOG_WRITER_UNHANDLED otherwise + %G_LOG_WRITER_UNHANDLED otherwise @@ -13449,7 +13733,7 @@ linked against at application run time. The maximum value which can be held in a #guint8. - + The micro version number of the GLib library. Like #gtk_micro_version, but from the headers used at @@ -13473,7 +13757,7 @@ linked against at application run time. The minimum value which can be held in a #gint8. - + The minor version number of the GLib library. Like #gtk_minor_version, but from the headers used at @@ -13689,7 +13973,7 @@ afterwards. In any other case, an idle source is created to call @function and that source is attached to @context (presumably to be run in another -thread). The idle source is attached with #G_PRIORITY_DEFAULT +thread). The idle source is attached with %G_PRIORITY_DEFAULT priority. If you want a different priority, use g_main_context_invoke_full(). @@ -17341,9 +17625,35 @@ set_local_count (gint count) - + A GPatternSpec struct is the 'compiled' form of a pattern. This structure is opaque and its fields cannot be accessed directly. + + Compiles a pattern to a #GPatternSpec. + + a newly-allocated #GPatternSpec + + + + + a zero-terminated UTF-8 encoded string + + + + + + Copies @pspec in a new #GPatternSpec. + + a copy of @pspec. + + + + + a #GPatternSpec + + + + Compares two compiled pattern specs and returns whether they will match the same set of strings. @@ -17374,19 +17684,67 @@ match the same set of strings. - - Compiles a pattern to a #GPatternSpec. - - a newly-allocated #GPatternSpec - + + Matches a string against a compiled pattern. Passing the correct +length of the string given is mandatory. The reversed string can be +omitted by passing %NULL, this is more efficient if the reversed +version of the string to be matched is not at hand, as +g_pattern_match() will only construct it if the compiled pattern +requires reverse matches. + +Note that, if the user code will (possibly) match a string against a +multitude of patterns containing wildcards, chances are high that +some patterns will require a reversed string. In this case, it's +more efficient to provide the reversed string to avoid multiple +constructions thereof in the various calls to g_pattern_match(). + +Note also that the reverse of a UTF-8 encoded string can in general +not be obtained by g_strreverse(). This works only if the string +does not contain any multibyte characters. GLib offers the +g_utf8_strreverse() function to reverse UTF-8 encoded strings. + + %TRUE if @string matches @pspec + - - a zero-terminated UTF-8 encoded string + + a #GPatternSpec + + + + the length of @string (in bytes, i.e. strlen(), + not g_utf8_strlen()) + + + + the UTF-8 encoded string to match + + + + the reverse of @string or %NULL - + + + Matches a string against a compiled pattern. If the string is to be +matched against more than one pattern, consider using +g_pattern_match() instead while supplying the reversed string. + + %TRUE if @string matches @pspec + + + + + a #GPatternSpec + + + + the UTF-8 encoded string to match + + + + Represents a file descriptor, which events to poll for, and which events @@ -17689,7 +18047,7 @@ checks, such as string comparisons, use g_ptr_array_find_with_equal_func().pointer to look for - + return location for the index of the element, if found @@ -17727,7 +18085,7 @@ equality is used. equality - + return location for the index of the element, if found @@ -18252,7 +18610,7 @@ g_assert (chunk_buffer->len == 0); - + pointer to retrieve the number of elements of the original array @@ -23727,7 +24085,11 @@ This does not unref the #GSource: if you still hold a reference, use g_source_unref() to drop it. This function is safe to call from any thread, regardless of which thread -the #GMainContext is running in. +the #GMainContext is running in. + +If the source is currently attached to a #GMainContext, destroying it +will effectively unset the callback similar to calling g_source_set_callback(). +This can mean, that the data's #GDestroyNotify gets called right away. @@ -24117,7 +24479,10 @@ to the type of source you are using, such as g_idle_add() or g_timeout_add(). It is safe to call this function multiple times on a source which has already been attached to a context. The changes will take effect for the next time -the source is dispatched after this call returns. +the source is dispatched after this call returns. + +Note that g_source_destroy() for a currently attached source has the effect +of also unsetting the callback. @@ -24253,7 +24618,9 @@ to include details like the event type in the source name. Use caution if changing the name while another thread may be accessing it with g_source_get_name(); that function does not copy the value, and changing the value will free it while the other thread -may be attempting to use it. +may be attempting to use it. + +Also see g_source_set_static_name(). @@ -24329,6 +24696,24 @@ Do not call this API on a #GSource that you did not create. + + A variant of g_source_set_name() that does not +duplicate the @name, and can only be used with +string literals. + + + + + + a #GSource + + + + debug name for the source + + + + Decreases the reference count of a source by one. If the resulting reference count is zero the source and associated @@ -24793,6 +25178,59 @@ See g_stat() for more information. string before it needs to be reallocated. May be larger than @len. + + Creates a new #GString, initialized with the given string. + + the new #GString + + + + + the initial text to copy into the string, or %NULL to + start with an empty string + + + + + + Creates a new #GString with @len bytes of the @init buffer. +Because a length is provided, @init need not be nul-terminated, +and can contain embedded nul bytes. + +Since this function does not stop at nul bytes, it is the caller's +responsibility to ensure that @init has at least @len addressable +bytes. + + a new #GString + + + + + initial contents of the string + + + + length of @init to use + + + + + + Creates a new #GString, with enough space for @dfl_size +bytes. This is useful if you are going to add a lot of +text to the string and don't want it to be reallocated +too often. + + the new #GString + + + + + the default size of the space allocated to hold the string + + + + Adds a string onto the end of a #GString, expanding it if necessary. @@ -25366,6 +25804,40 @@ to contain the results. The previous contents of the + + Replaces the string @find with the string @replace in a #GString up to +@limit times. If the number of instances of @find in the #GString is +less than @limit, all instances are replaced. If @limit is `0`, +all instances of @find are replaced. + +If @find is the empty string, since versions 2.69.1 and 2.68.4 the +replacement will be inserted no more than once per possible position +(beginning of string, end of string and between characters). This did +not work correctly in earlier versions. + + the number of find and replace operations performed. + + + + + a #GString + + + + the string to find in @string + + + + the string to insert in place of @find + + + + the maximum instances of @find to replace with @replace, or `0` for +no limit + + + + Sets the length of a #GString. If the length is less than the current length, the string will be truncated. If the @@ -25579,6 +26051,131 @@ though you should not change anything after the end of the string. + + #GStrvBuilder is a method of easily building dynamically sized +NULL-terminated string arrays. + +The following example shows how to build a two element array: + +|[<!-- language="C" --> + g_autoptr(GStrvBuilder) builder = g_strv_builder_new (); + g_strv_builder_add (builder, "hello"); + g_strv_builder_add (builder, "world"); + g_auto(GStrv) array = g_strv_builder_end (builder); +]| + + Add a string to the end of the array. + +Since 2.68 + + + + + + a #GStrvBuilder + + + + a string. + + + + + + Appends all the given strings to the builder. + +Since 2.70 + + + + + + a #GStrvBuilder + + + + one or more strings followed by %NULL + + + + + + Appends all the strings in the given vector to the builder. + +Since 2.70 + + + + + + a #GStrvBuilder + + + + the vector of strings to add + + + + + + + + Ends the builder process and returns the constructed NULL-terminated string +array. The returned value should be freed with g_strfreev() when no longer +needed. + + the constructed string array. + +Since 2.68 + + + + + + + a #GStrvBuilder + + + + + + Atomically increments the reference count of @builder by one. +This function is thread-safe and may be called from any thread. + + The passed in #GStrvBuilder + + + + + a #GStrvBuilder + + + + + + Decreases the reference count on @builder. + +In the event that there are no more references, releases all memory +associated with the #GStrvBuilder. + + + + + + a #GStrvBuilder allocated by g_strv_builder_new() + + + + + + Creates a new #GStrvBuilder with a reference count of 1. +Use g_strv_builder_unref() on the returned value when no longer needed. + + the new #GStrvBuilder + + + + 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 @@ -25626,7 +26223,7 @@ to create the directory if it doesn’t exist. Works like g_mutex_trylock(), but for a lock defined with -#G_LOCK_DEFINE. +%G_LOCK_DEFINE. the name of the lock @@ -25635,6 +26232,18 @@ to create the directory if it doesn’t exist. An opaque structure representing a test case. + + Free the @test_case. + + + + + + a #GTestCase + + + + @@ -25925,6 +26534,18 @@ not show stdout and stderr. + + Free the @suite and all nested #GTestSuites. + + + + + + a #GTestSuite + + + + Test traps are guards around forked tests. @@ -26460,6 +27081,41 @@ Note, even in case of error a valid #GThreadPool is returned. + + This function creates a new thread pool similar to g_thread_pool_new() +but allowing @item_free_func to be specified to free the data passed +to g_thread_pool_push() in the case that the #GThreadPool is stopped +and freed before all tasks have been executed. + + the new #GThreadPool + + + + + a function to execute in the threads of the new thread pool + + + + user data that is handed over to @func every time it + is called + + + + used to pass as a free function to + g_async_queue_new_full() + + + + the maximal number of threads to execute concurrently + in the new thread pool, `-1` means no limit + + + + should this thread pool be exclusive? + + + + This function will set the maximum @interval that a thread waiting in the pool for new tasks can be idle for before @@ -26527,7 +27183,8 @@ transitions, for example). Represents a precise time, with seconds and microseconds. -Similar to the struct timeval returned by the gettimeofday() + +Similar to the struct timeval returned by the `gettimeofday()` UNIX system call. GLib is attempting to unify around the use of 64-bit integers to @@ -26671,6 +27328,84 @@ g_time_zone_new_identifier(). + + Creates a #GTimeZone corresponding to @identifier. If @identifier cannot be +parsed or loaded, %NULL is returned. + +@identifier can either be an RFC3339/ISO 8601 time offset or +something that would pass as a valid value for the `TZ` environment +variable (including %NULL). + +In Windows, @identifier can also be the unlocalized name of a time +zone for standard time, for example "Pacific Standard Time". + +Valid RFC3339 time offsets are `"Z"` (for UTC) or +`"±hh:mm"`. ISO 8601 additionally specifies +`"±hhmm"` and `"±hh"`. Offsets are +time values to be added to Coordinated Universal Time (UTC) to get +the local time. + +In UNIX, the `TZ` environment variable typically corresponds +to the name of a file in the zoneinfo database, an absolute path to a file +somewhere else, or a string in +"std offset [dst [offset],start[/time],end[/time]]" (POSIX) format. +There are no spaces in the specification. The name of standard +and daylight savings time zone must be three or more alphabetic +characters. Offsets are time values to be added to local time to +get Coordinated Universal Time (UTC) and should be +`"[±]hh[[:]mm[:ss]]"`. Dates are either +`"Jn"` (Julian day with n between 1 and 365, leap +years not counted), `"n"` (zero-based Julian day +with n between 0 and 365) or `"Mm.w.d"` (day d +(0 <= d <= 6) of week w (1 <= w <= 5) of month m (1 <= m <= 12), day +0 is a Sunday). Times are in local wall clock time, the default is +02:00:00. + +In Windows, the "tzn[+|–]hh[:mm[:ss]][dzn]" format is used, but also +accepts POSIX format. The Windows format uses US rules for all time +zones; daylight savings time is 60 minutes behind the standard time +with date and time of change taken from Pacific Standard Time. +Offsets are time values to be added to the local time to get +Coordinated Universal Time (UTC). + +g_time_zone_new_local() calls this function with the value of the +`TZ` environment variable. This function itself is independent of +the value of `TZ`, but if @identifier is %NULL then `/etc/localtime` +will be consulted to discover the correct time zone on UNIX and the +registry will be consulted or GetTimeZoneInformation() will be used +to get the local time zone on Windows. + +If intervals are not available, only time zone rules from `TZ` +environment variable or other means, then they will be computed +from year 1900 to 2037. If the maximum year for the rules is +available and it is greater than 2037, then it will followed +instead. + +See +[RFC3339 §5.6](http://tools.ietf.org/html/rfc3339#section-5.6) +for a precise definition of valid RFC3339 time offsets +(the `time-offset` expansion) and ISO 8601 for the +full list of valid time offsets. See +[The GNU C Library manual](http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html) +for an explanation of the possible +values of the `TZ` environment variable. See +[Microsoft Time Zone Index Values](http://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx) +for the list of time zones on Windows. + +You should release the return value by calling g_time_zone_unref() +when you are done with it. + + the requested timezone, or %NULL on + failure + + + + + a timezone identifier + + + + Creates a #GTimeZone corresponding to local time. The local time zone may change between invocations to this function; for example, @@ -27284,6 +28019,26 @@ parameter passed to g_tree_traverse(). If the function returns + + Specifies the type of function passed to g_tree_foreach_node(). It is +passed each node, together with the @user_data parameter passed to +g_tree_foreach_node(). If the function returns %TRUE, the traversal is +stopped. + + %TRUE to stop the traversal + + + + + a #GTreeNode + + + + user data passed to g_tree_foreach_node() + + + + Specifies the type of traversal performed by g_tree_traverse(), g_node_traverse() and g_node_find(). The different orders are @@ -27317,10 +28072,76 @@ illustrated here: efficient than the other orders. - + The GTree struct is an opaque data structure representing a [balanced binary tree][glib-Balanced-Binary-Trees]. It should be accessed only by using the following functions. + + Creates a new #GTree. + + a newly allocated #GTree + + + + + the function used to order the nodes in the #GTree. + It should return values similar to the standard strcmp() function - + 0 if the two arguments are equal, a negative value if the first argument + comes before the second, or a positive value if the first argument comes + after the second. + + + + + + Creates a new #GTree like g_tree_new() and allows to specify functions +to free the memory allocated for the key and value that get called when +removing the entry from the #GTree. + + a newly allocated #GTree + + + + + qsort()-style comparison function + + + + data to pass to comparison function + + + + a function to free the memory allocated for the key + used when removing the entry from the #GTree or %NULL if you don't + want to supply such a function + + + + a function to free the memory allocated for the + value used when removing the entry from the #GTree or %NULL if you + don't want to supply such a function + + + + + + Creates a new #GTree with a comparison function that accepts user data. +See g_tree_new() for more details. + + a newly allocated #GTree + + + + + qsort()-style comparison function + + + + data to pass to comparison function + + + + Removes all keys and values from the #GTree and decreases its reference count by one. If keys and/or values are dynamically @@ -27366,6 +28187,34 @@ the tree, then walk the list and remove each item. + + Calls the given function for each of the nodes in the #GTree. +The function is passed the pointer to the particular node, and the given +@data parameter. The tree traversal happens in-order. + +The tree may not be modified while iterating over it (you can't +add/remove items). To remove all items matching a predicate, you need +to add each item to a list in your #GTraverseFunc as you walk over +the tree, then walk the list and remove each item. + + + + + + a #GTree + + + + the function to call for each node visited. + If this function returns %TRUE, the traversal is stopped. + + + + user data to pass to the function + + + + Gets the height of a #GTree. @@ -27406,6 +28255,39 @@ only this function does not return the inserted or set node. + + Inserts a key/value pair into a #GTree. + +If the given key already exists in the #GTree its corresponding value +is set to the new value. If you supplied a @value_destroy_func when +creating the #GTree, the old value is freed using that function. If +you supplied a @key_destroy_func when creating the #GTree, the passed +key is freed using that function. + +The tree is automatically 'balanced' as new key/value pairs are added, +so that the distance from the root to every leaf is as small as possible. +The cost of maintaining a balanced tree while inserting new key/value +result in a O(n log(n)) operation where most of the other operations +are O(log(n)). + + the inserted (or set) node. + + + + + a #GTree + + + + the key to insert + + + + the value corresponding to the key + + + + Gets the value corresponding to the given key. Since a #GTree is automatically balanced as key/value pairs are added, key lookup @@ -27454,6 +28336,50 @@ g_tree_remove(). + + Gets the tree node corresponding to the given key. Since a #GTree is +automatically balanced as key/value pairs are added, key lookup +is O(log n) (where n is the number of key/value pairs in the tree). + + the tree node corresponding to + the key, or %NULL if the key was not found + + + + + a #GTree + + + + the key to look up + + + + + + Gets the lower bound node corresponding to the given key, +or %NULL if the tree is empty or all the nodes in the tree +have keys that are strictly lower than the searched key. + +The lower bound is the first node that has its key greater +than or equal to the searched key. + + the tree node corresponding to + the lower bound, or %NULL if the tree is empty or has only + keys strictly lower than the searched key. + + + + + a #GTree + + + + the key to calculate the lower bound for + + + + Gets the number of nodes in a #GTree. @@ -27467,11 +28393,39 @@ g_tree_remove(). - + + Returns the first in-order node of the tree, or %NULL +for an empty tree. + + the first node in the tree + + + + + a #GTree + + + + + + Returns the last in-order node of the tree, or %NULL +for an empty tree. + + the last node in the tree + + + + + a #GTree + + + + + Increments the reference count of @tree by one. It is safe to call this function from any thread. - + the passed in #GTree @@ -27509,6 +28463,19 @@ are O(log(n)). + + Removes all nodes from a #GTree and destroys their keys and values, +then resets the #GTree’s root to %NULL. + + + + + + a #GTree + + + + Inserts a new key and value into a #GTree as g_tree_replace_node() does, only this function does not return the inserted or set node. @@ -27530,6 +28497,35 @@ only this function does not return the inserted or set node. + + Inserts a new key and value into a #GTree similar to g_tree_insert_node(). +The difference is that if the key already exists in the #GTree, it gets +replaced by the new key. If you supplied a @value_destroy_func when +creating the #GTree, the old value is freed using that function. If you +supplied a @key_destroy_func when creating the #GTree, the old key is +freed using that function. + +The tree is automatically 'balanced' as new key/value pairs are added, +so that the distance from the root to every leaf is as small as possible. + + the inserted (or set) node. + + + + + a #GTree + + + + the key to insert + + + + the value corresponding to the key + + + + Searches a #GTree using @search_func. @@ -27560,6 +28556,36 @@ pairs that have a larger key. + + Searches a #GTree using @search_func. + +The @search_func is called with a pointer to the key of a key/value +pair in the tree, and the passed in @user_data. If @search_func returns +0 for a key/value pair, then the corresponding node is returned as +the result of g_tree_search(). If @search_func returns -1, searching +will proceed among the key/value pairs that have a smaller key; if +@search_func returns 1, searching will proceed among the key/value +pairs that have a larger key. + + the node corresponding to the + found key, or %NULL if the key was not found + + + + + a #GTree + + + + a function used to search the #GTree + + + + the data passed as the second argument to @search_func + + + + Removes a key and its associated value from a #GTree without calling the key and value destroy functions. @@ -27628,72 +28654,87 @@ It is safe to call this function from any thread. - - Creates a new #GTree. - - a newly allocated #GTree - + + Gets the upper bound node corresponding to the given key, +or %NULL if the tree is empty or all the nodes in the tree +have keys that are lower than or equal to the searched key. + +The upper bound is the first node that has its key strictly greater +than the searched key. + + the tree node corresponding to the + upper bound, or %NULL if the tree is empty or has only keys + lower than or equal to the searched key. + - - the function used to order the nodes in the #GTree. - It should return values similar to the standard strcmp() function - - 0 if the two arguments are equal, a negative value if the first argument - comes before the second, or a positive value if the first argument comes - after the second. - + + a #GTree + + + + the key to calculate the upper bound for + - - - Creates a new #GTree like g_tree_new() and allows to specify functions -to free the memory allocated for the key and value that get called when -removing the entry from the #GTree. - - a newly allocated #GTree - + + + + An opaque type which identifies a specific node in a #GTree. + + Gets the key stored at a particular tree node. + + the key at the node. + - - qsort()-style comparison function - - - - data to pass to comparison function - - - - a function to free the memory allocated for the key - used when removing the entry from the #GTree or %NULL if you don't - want to supply such a function - - - - a function to free the memory allocated for the - value used when removing the entry from the #GTree or %NULL if you - don't want to supply such a function - - + + a #GTree node + + - - - Creates a new #GTree with a comparison function that accepts user data. -See g_tree_new() for more details. - - a newly allocated #GTree - + + + Returns the next in-order node of the tree, or %NULL +if the passed node was already the last one. + + the next node in the tree + - - qsort()-style comparison function - - - - data to pass to comparison function - - + + a #GTree node + + - + + + Returns the previous in-order node of the tree, or %NULL +if the passed node was already the first one. + + the previous node in the tree + + + + + a #GTree node + + + + + + Gets the value stored at a particular tree node. + + the value at the node. + + + + + a #GTree node + + + + This macro can be used to mark a function declaration as unavailable. @@ -27763,7 +28804,7 @@ if (G_UNLIKELY (random () == 1)) Works like g_mutex_unlock(), but for a lock defined with -#G_LOCK_DEFINE. +%G_LOCK_DEFINE. the name of the lock @@ -27901,7 +28942,10 @@ See [Unicode Line Breaking Algorithm](http://www.unicode.org/unicode/reports/tr1 Hangul LVT Syllable (H3) - Closing Parenthesis (CP). Since 2.28 + Closing Parenthesis (CP). Since 2.28. Deprecated: 2.70: Use %G_UNICODE_BREAK_CLOSE_PARENTHESIS instead. + + + Closing Parenthesis (CP). Since 2.70 Conditional Japanese Starter (CJ). Since: 2.32 @@ -29732,6 +30776,12 @@ parse it with. Same as %G_URI_FLAGS_ENCODED, for the fragment only. + + A scheme-based normalization will be applied. + For example, when parsing an HTTP URI changing omitted path to `/` and + omitted port to `80`; and when building a URI, changing empty path to `/` + and default port `80`). This only supports a subset of known schemes. (Since: 2.68) + Flags describing what parts of the URI to hide in @@ -29936,7 +30986,9 @@ enumeration. A stack-allocated #GVariantBuilder must be initialized if it is used together with g_auto() to avoid warnings or crashes if function returns before g_variant_builder_init() is called on the -builder. This macro can be used as initializer instead of an +builder. + +This macro can be used as initializer instead of an explicit zeroing a variable when declaring it and a following g_variant_builder_init(), but it cannot be assigned to a variable. @@ -29945,7 +30997,7 @@ lifetime issues, as copying the @variant_type does not happen in the G_VARIANT_BUILDER_INIT() call, but rather in functions that make sure that #GVariantBuilder is valid. -|[ +|[<!-- language="C" --> g_auto(GVariantBuilder) builder = G_VARIANT_BUILDER_INIT (G_VARIANT_TYPE_BYTESTRING); ]| @@ -29958,6 +31010,7 @@ make sure that #GVariantBuilder is valid. A stack-allocated #GVariantDict must be initialized if it is used together with g_auto() to avoid warnings or crashes if function returns before g_variant_dict_init() is called on the builder. + This macro can be used as initializer instead of an explicit zeroing a variable when declaring it and a following g_variant_dict_init(), but it cannot be assigned to a variable. @@ -29971,7 +31024,7 @@ value has to be a constant expression, the only possible value of safely with a different @asv right after the variable was initialized with G_VARIANT_DICT_INIT(). -|[ +|[<!-- language="C" --> g_autoptr(GVariant) variant = get_asv_variant (); g_auto(GVariantDict) dict = G_VARIANT_DICT_INIT (variant); ]| @@ -30002,7 +31055,10 @@ Since 2.24 In order to use this function, you must include string.h yourself, because this macro may use memmove() and GLib does not include -string.h for you. +string.h for you. + +Each invocation of `G_VA_COPY (ap1, ap2)` must be matched with a +corresponding `va_end (ap1)` call in the same function. the va_list variable to place a copy of @ap2 in @@ -30075,19 +31131,19 @@ see g_variant_ref_sink(). concurrently accessed in any way from any number of threads without problems. -#GVariant is heavily optimised for dealing with data in serialised +#GVariant is heavily optimised for dealing with data in serialized form. It works particularly well with data located in memory-mapped -files. It can perform nearly all deserialisation operations in a +files. It can perform nearly all deserialization operations in a small constant time, usually touching only a single memory page. -Serialised #GVariant data can also be sent over the network. +Serialized #GVariant data can also be sent over the network. #GVariant is largely compatible with D-Bus. Almost all types of #GVariant instances can be sent over D-Bus. See #GVariantType for -exceptions. (However, #GVariant's serialisation format is not the same -as the serialisation format of a D-Bus message body: use #GDBusMessage, +exceptions. (However, #GVariant's serialization format is not the same +as the serialization format of a D-Bus message body: use #GDBusMessage, in the gio library, for those.) -For space-efficiency, the #GVariant serialisation format does not +For space-efficiency, the #GVariant serialization format does not automatically include the variant's length, type or endianness, which must either be implied from context (such as knowledge that a particular file format always contains a little-endian @@ -30117,14 +31173,14 @@ current implementation. The information here is subject to change in the future. The memory allocated by #GVariant can be grouped into 4 broad -purposes: memory for serialised data, memory for the type +purposes: memory for serialized data, memory for the type information cache, buffer management memory and memory for the #GVariant structure itself. -## Serialised Data Memory +## Serialized Data Memory This is the memory that is used for storing GVariant data in -serialised form. This is what would be sent over the network or +serialized form. This is what would be sent over the network or what would end up on disk, not counting any indicator of the endianness, or of the length or type of the top-level variant. @@ -30158,7 +31214,7 @@ item inside the variant. As an example, consider a dictionary mapping strings to variants. In the case that the dictionary is empty, 0 bytes are required for -the serialisation. +the serialization. If we add an item "width" that maps to the int32 value of 500 then we will use 4 byte to store the int32 (so 6 for the variant @@ -30184,7 +31240,7 @@ dictionary. For each GVariant type that currently exists in the program a type information structure is kept in the type information cache. The -type information structure is required for rapid deserialisation. +type information structure is required for rapid deserialization. Continuing with the above example, if a #GVariant exists with the type "a{sv}" then a type information struct will exist for @@ -30229,14 +31285,14 @@ structure is required for many different values of the same type. ## Buffer Management Memory #GVariant uses an internal buffer management structure to deal -with the various different possible sources of serialised data +with the various different possible sources of serialized data that it uses. The buffer is responsible for ensuring that the correct call is made when the data is no longer in use by #GVariant. This may involve a g_free() or a g_slice_free() or even g_mapped_file_unref(). One buffer management structure is used for each chunk of -serialised data. The size of the buffer management structure +serialized data. The size of the buffer management structure is 4 * (void *). On 32-bit systems, that's 16 bytes. ## GVariant structure @@ -30246,7 +31302,7 @@ systems, that's 24 bytes. #GVariant structures only exist if they are explicitly created with API calls. For example, if a #GVariant is constructed out of -serialised data for the example given above (with the dictionary) +serialized data for the example given above (with the dictionary) then although there are 9 individual values that comprise the entire dictionary (two keys, two values, two variants containing the values, two dictionary entries, plus the dictionary itself), @@ -30256,8 +31312,8 @@ dictionary. If calls are made to start accessing the other values then #GVariant instances will exist for those values only for as long as they are in use (ie: until you call g_variant_unref()). The -type information is shared. The serialised data and the buffer -management structure for that serialised data is shared by the +type information is shared. The serialized data and the buffer +management structure for that serialized data is shared by the child. ## Summary @@ -30265,12 +31321,12 @@ child. To put the entire example together, for our dictionary mapping strings to variants (with two entries, as given above), we are using 91 bytes of memory for type information, 29 bytes of memory -for the serialised data, 16 bytes for buffer management and 24 +for the serialized data, 16 bytes for buffer management and 24 bytes for the #GVariant instance, or a total of 160 bytes, plus malloc overhead. If we were to use g_variant_get_child_value() to access the two dictionary entries, we would use an additional 48 bytes. If we were to have other dictionaries of the same type, we -would use more memory for the serialised data and buffer +would use more memory for the serialized data and buffer management for those dictionaries, but the type information would be shared. @@ -30468,7 +31524,7 @@ fixed-size as are tuples containing only other fixed-sized types. @element_size must be the size of a single element in the array. For example, if calling this function for an array of 32-bit integers, you might say sizeof(gint32). This value isn't used except for the purpose -of a double-check that the form of the serialised data matches the caller's +of a double-check that the form of the serialized data matches the caller's expectation. @n_elements must be the length of the @elements array. @@ -30496,8 +31552,8 @@ expectation. - Constructs a new serialised-mode #GVariant instance. This is the -inner interface for creation of new serialised values that gets + Constructs a new serialized-mode #GVariant instance. This is the +inner interface for creation of new serialized values that gets called from various functions in gvariant.c. A reference is taken on @bytes. @@ -30525,7 +31581,7 @@ GLib 2.60) or (in older versions) fail and exit the process. - Creates a new #GVariant instance from serialised data. + Creates a new #GVariant instance from serialized data. @type is the type of #GVariant instance that will be constructed. The interpretation of @data depends on knowing the type. @@ -30535,8 +31591,8 @@ unchanging value until such a time as @notify is called with @user_data. If the contents of @data change before that time then the result is undefined. -If @data is trusted to be serialised data in normal form then -@trusted should be %TRUE. This applies to serialised data created +If @data is trusted to be serialized data in normal form then +@trusted should be %TRUE. This applies to serialized data created within this process or read from a trusted location on the disk (such as a file installed in /usr/lib alongside your application). You should set trusted to %FALSE if @data is read from the network, a @@ -30564,7 +31620,7 @@ process. - the serialised data + the serialized data @@ -31464,7 +32520,7 @@ g_variant_unref() when you're done with it. Note that values borrowed from the returned child are not guaranteed to still be valid after the child is freed even if you still hold a reference -to @value, if @value has not been serialised at the time this function is +to @value, if @value has not been serialized at the time this function is called. To avoid this, you can serialize @value by calling g_variant_get_data() and optionally ignoring the return value. @@ -31490,33 +32546,33 @@ This function is O(1). - Returns a pointer to the serialised form of a #GVariant instance. + Returns a pointer to the serialized form of a #GVariant instance. The returned data may not be in fully-normalised form if read from an untrusted source. The returned data must not be freed; it remains valid for as long as @value exists. -If @value is a fixed-sized value that was deserialised from a -corrupted serialised container then %NULL may be returned. In this +If @value is a fixed-sized value that was deserialized from a +corrupted serialized container then %NULL may be returned. In this case, the proper thing to do is typically to use the appropriate number of nul bytes in place of @value. If @value is not fixed-sized then %NULL is never returned. -In the case that @value is already in serialised form, this function -is O(1). If the value is not already in serialised form, -serialisation occurs implicitly and is approximately O(n) in the size +In the case that @value is already in serialized form, this function +is O(1). If the value is not already in serialized form, +serialization occurs implicitly and is approximately O(n) in the size of the result. -To deserialise the data returned by this function, in addition to the -serialised data, you must know the type of the #GVariant, and (if the +To deserialize the data returned by this function, in addition to the +serialized data, you must know the type of the #GVariant, and (if the machine might be different) the endianness of the machine that stored it. As a result, file formats or network messages that incorporate -serialised #GVariants must include this information either +serialized #GVariants must include this information either implicitly (for instance "the file always contains a %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or explicitly (by storing the type and/or endianness in addition to the -serialised data). +serialized data). - the serialised form of @value, or %NULL + the serialized form of @value, or %NULL @@ -31527,7 +32583,7 @@ serialised data). - Returns a pointer to the serialised form of a #GVariant instance. + Returns a pointer to the serialized form of a #GVariant instance. The semantics of this function are exactly the same as g_variant_get_data(), except that the returned #GBytes holds a reference to the variant data. @@ -31559,7 +32615,7 @@ other than %G_VARIANT_TYPE_DOUBLE. - Provides access to the serialised data for an array of fixed-sized + Provides access to the serialized data for an array of fixed-sized items. @value must be an array with fixed-sized elements. Numeric types are @@ -31567,7 +32623,7 @@ fixed-size, as are tuples containing only other fixed-sized types. @element_size must be the size of a single element in the array, as given by the section on -[serialized data memory][gvariant-serialised-data-memory]. +[serialized data memory][gvariant-serialized-data-memory]. In particular, arrays of these fixed-sized types can be interpreted as an array of the given C type, with @element_size set to the size @@ -31580,7 +32636,7 @@ the appropriate type: For example, if calling this function for an array of 32-bit integers, you might say `sizeof(gint32)`. This value isn't used except for the purpose -of a double-check that the form of the serialised data matches the caller's +of a double-check that the form of the serialized data matches the caller's expectation. @n_elements, which must be non-%NULL, is set equal to the number of @@ -31704,7 +32760,7 @@ If @value is found not to be in normal form then a new trusted #GVariant is created with the same value as @value. It makes sense to call this function if you've received #GVariant -data from untrusted sources and you want to ensure your serialised +data from untrusted sources and you want to ensure your serialized output is definitely in normal form. If @value is already in normal form, a new reference will be returned @@ -31759,13 +32815,13 @@ with g_variant_store(). If @value has a fixed-sized type then this function always returned that fixed size. -In the case that @value is already in serialised form or the size has +In the case that @value is already in serialized form or the size has already been calculated (ie: this function has been called before) then this function is O(1). Otherwise, the size is calculated, an operation which is approximately O(n) in the number of values involved. - the serialised size of @value + the serialized size of @value @@ -32038,7 +33094,7 @@ counts. Checks if @value is in normal form. The main reason to do this is to detect if a given chunk of -serialised data is in normal form: load the data into a #GVariant +serialized data is in normal form: load the data into a #GVariant using g_variant_new_from_data() and then use this function to check. @@ -32294,15 +33350,15 @@ are not floating. - Stores the serialised form of @value at @data. @data should be + Stores the serialized form of @value at @data. @data should be large enough. See g_variant_get_size(). The stored data is in machine native byte order but may not be in fully-normalised form if read from an untrusted source. See g_variant_get_normal_form() for a solution. -As with g_variant_get_data(), to be able to deserialise the -serialised variant successfully, its type and (if the destination +As with g_variant_get_data(), to be able to deserialize the +serialized variant successfully, its type and (if the destination machine might be different) its endianness must also be available. This function is approximately O(n) in the size of @data. @@ -32315,7 +33371,7 @@ This function is approximately O(n) in the size of @data. - the location to store the serialised data at + the location to store the serialized data at @@ -34530,6 +35586,11 @@ Thus it provides the same advantages and pitfalls as alloca(): way as out of stack space situations from infinite function recursion, i.e. with a segmentation fault. +- Allowing @size to be specified by an untrusted party would allow for them + to trigger a segmentation fault by specifying a large size, leading to a + denial of service vulnerability. @size must always be entirely under the + control of the program. + - Special care has to be taken when mixing alloca() with GNU C variable sized arrays. Stack space allocated with alloca() in the same scope as a variable sized array will be freed together with the variable sized array upon exit of that scope, and @@ -35641,6 +36702,31 @@ includes the actual values of @s1 and @s2. + + 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 +includes how @strv1 and @strv2 are different. + +|[<!-- language="C" --> + const char *expected[] = { "one", "two", "three", NULL }; + g_assert_cmpstrv (mystrv, expected); +]| + + + a string array (may be %NULL) + + + another string array (may be %NULL) + + + Debugging macro to compare two unsigned integers. @@ -35915,6 +37001,37 @@ See g_test_set_nonfatal_assertions(). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -36682,7 +37799,11 @@ resources allocated for @mem_block. - Atomically decreases the reference count. + Atomically decreases the reference count. + +If %TRUE is returned, the reference count reached 0. After this point, @arc +is an undefined state and must be reinitialized with +g_atomic_ref_count_init() to be used again. %TRUE if the reference count reached 0, and %FALSE otherwise @@ -36707,7 +37828,7 @@ resources allocated for @mem_block. - Initializes a reference count variable. + Initializes a reference count variable to 1. @@ -36965,7 +38086,8 @@ between 0 and 31 then the result is undefined. This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work -reliably. +reliably. While @address has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`. @@ -37049,7 +38171,8 @@ between 0 and 31 then the result is undefined. This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work -reliably. +reliably. While @address has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`. %TRUE if the lock was acquired @@ -37072,7 +38195,8 @@ woken up. This function accesses @address atomically. All other accesses to @address must be atomic in order for this function to work -reliably. +reliably. While @address has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`. @@ -37118,7 +38242,7 @@ registered; the URI and MIME type of an icon, to be used when displaying the bookmark inside a GUI. Here is an example of a bookmark file: -[bookmarks.xbel](https://git.gnome.org/browse/glib/tree/glib/tests/bookmarks.xbel) +[bookmarks.xbel](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/glib/tests/bookmarks.xbel) A bookmark file might contain more than one bookmark; each bookmark is accessed through its URI. @@ -37369,7 +38493,7 @@ to the caller. - + pointer to retrieve the number of elements of the original array @@ -37474,24 +38598,25 @@ See your C library manual for more details about chdir(). Checks that the GLib library in use is compatible with the -given version. Generally you would pass in the constants -#GLIB_MAJOR_VERSION, #GLIB_MINOR_VERSION, #GLIB_MICRO_VERSION -as the three arguments to this function; that produces -a check that the library in use is compatible with -the version of GLib the application or module was compiled -against. +given version. + +Generally you would pass in the constants %GLIB_MAJOR_VERSION, +%GLIB_MINOR_VERSION, %GLIB_MICRO_VERSION as the three arguments +to this function; that produces a check that the library in use +is compatible with the version of GLib the application or module +was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version -@required_major.required_minor.@required_micro. Second +`@required_major.required_minor.@required_micro`. Second the running library must be binary compatible with the -version @required_major.required_minor.@required_micro +version `@required_major.@required_minor.@required_micro` (same major version.) - - %NULL if the GLib library is compatible with the - given version, or a string describing the version mismatch. - The returned string is owned by GLib and must not be modified - or freed. + + %NULL if the GLib library is + compatible with the given version, or a string describing the + version mismatch. The returned string is owned by GLib and must + not be modified or freed. @@ -37557,10 +38682,10 @@ not supported. Sets a function to be called when the child indicated by @pid -exits, at a default priority, #G_PRIORITY_DEFAULT. +exits, at a default priority, %G_PRIORITY_DEFAULT. If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() -you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to +you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to the spawn function for the child watching to work. Note that on platforms where #GPid must be explicitly closed @@ -37583,8 +38708,8 @@ need greater control. process id to watch. On POSIX the positive pid of a child -process. On Windows a handle for a process (which doesn't have to be -a child). + process. On Windows a handle for a process (which doesn't have + to be a child). @@ -37602,10 +38727,10 @@ a child). exits, at the priority @priority. If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() -you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to +you will need to pass %G_SPAWN_DO_NOT_REAP_CHILD as flag to the spawn function for the child watching to work. -In many programs, you will want to call g_spawn_check_exit_status() +In many programs, you will want to call g_spawn_check_wait_status() in the callback to determine whether or not the child exited successfully. @@ -37629,7 +38754,7 @@ need greater control. the priority of the idle source. Typically this will be in the - range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. @@ -39661,6 +40786,12 @@ perhaps along with additional context known only to the calling function (the file being opened, or whatever - though in the g_file_get_contents() case, the @message already contains a filename). +Since error messages may be displayed to the user, they need to be valid +UTF-8 (all GTK widgets expect text to be UTF-8). Keep this in mind in +particular when formatting error messages with filenames, which are in +the 'filename encoding', and need to be turned into UTF-8 using +g_filename_to_utf8(), g_filename_display_name() or g_utf8_make_valid(). + Note, however, that many error messages are too technical to display to the user in an application, so prefer to use g_error_matches() to categorize errors from called functions, and build an appropriate error message for the context @@ -40039,15 +41170,16 @@ supported. Gets a #GFileError constant based on the passed-in @err_no. + For example, if you pass in `EEXIST` this function returns -#G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably +%G_FILE_ERROR_EXIST. Unlike `errno` values, you can portably assume that all #GFileError values will exist. Normally a #GFileError value goes into a #GError returned from a function that manipulates files. So you would use g_file_error_from_errno() when constructing a #GError. - #GFileError corresponding to the given @errno + #GFileError corresponding to the given @err_no @@ -41086,7 +42218,7 @@ data for all users is used instead. A typical path is This folder is used for application data that is not user specific. For example, an application can store a spell-check dictionary, a database of clip art, or a log file in the -CSIDL_COMMON_APPDATA folder. This information will not roam and is available +FOLDERID_ProgramData folder. This information will not roam and is available to anyone using the computer. The return value is cached and modifying it at runtime is not supported, as @@ -41114,8 +42246,8 @@ If `XDG_DATA_DIRS` is undefined, the first elements in the list are the Application Data and Documents folders for All Users. (These can be determined only on Windows 2000 or later and are not present in the list on other -Windows versions.) See documentation for CSIDL_COMMON_APPDATA and -CSIDL_COMMON_DOCUMENTS. +Windows versions.) See documentation for FOLDERID_ProgramData and +FOLDERID_PublicDocuments. Then follows the "share" subfolder in the installation folder for the package containing the DLL that calls this function, if it can @@ -41177,7 +42309,7 @@ On Windows it follows XDG Base Directory Specification if `XDG_CACHE_HOME` is de If `XDG_CACHE_HOME` is undefined, the directory that serves as a common repository for temporary Internet files is used instead. A typical path is `C:\Documents and Settings\username\Local Settings\Temporary Internet Files`. -See the [documentation for `CSIDL_INTERNET_CACHE`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_internet_cache). +See the [documentation for `FOLDERID_InternetCache`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). The return value is cached and modifying it at runtime is not supported, as it’s not thread-safe to modify environment variables at runtime. @@ -41199,7 +42331,7 @@ In this case the directory retrieved will be `XDG_CONFIG_HOME`. On Windows it follows XDG Base Directory Specification if `XDG_CONFIG_HOME` is defined. If `XDG_CONFIG_HOME` is undefined, the folder to use for local (as opposed to roaming) application data is used instead. See the -[documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). +[documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). Note that in this case on Windows it will be the same as what g_get_user_data_dir() returns. @@ -41223,7 +42355,7 @@ In this case the directory retrieved will be `XDG_DATA_HOME`. On Windows it follows XDG Base Directory Specification if `XDG_DATA_HOME` is defined. If `XDG_DATA_HOME` is undefined, the folder to use for local (as opposed to roaming) application data is used instead. See the -[documentation for `CSIDL_LOCAL_APPDATA`](https://msdn.microsoft.com/en-us/library/windows/desktop/bb762494%28v=vs.85%29.aspx#csidl_local_appdata). +[documentation for `FOLDERID_LocalAppData`](https://docs.microsoft.com/en-us/windows/win32/shell/knownfolderid). Note that in this case on Windows it will be the same as what g_get_user_config_dir() returns. @@ -41324,19 +42456,6 @@ backward-compatibility with the old ASCII-only DNS, by defining an ASCII-Compatible Encoding of any given Unicode name, which can be used with non-IDN-aware applications and protocols. (For example, "Παν語.org" maps to "xn--4wa8awb4637h.org".) - - - #GStrvBuilder is a method of easily building dynamically sized -NULL-terminated string arrays. - -The following example shows how to build a two element array: - -|[<!-- language="C" --> - g_autoptr(GStrvBuilder) builder = g_strv_builder_new (); - g_strv_builder_add (builder, "hello"); - g_strv_builder_add (builder, "world"); - g_auto(GStrv) array = g_strv_builder_end (builder); -]| Most of GLib is intended to be portable; in contrast, this set of @@ -42129,7 +43248,7 @@ more convenient than the raw iconv wrappers. Adds a function to be called whenever there are no higher priority events pending to the default main loop. The function is given the -default idle priority, #G_PRIORITY_DEFAULT_IDLE. If the function +default idle priority, %G_PRIORITY_DEFAULT_IDLE. If the function returns %FALSE it is automatically removed from the list of event sources and will not be called again. @@ -42158,7 +43277,9 @@ use a custom main context. Adds a function to be called whenever there are no higher priority -events pending. If the function returns %FALSE it is automatically +events pending. + +If the function returns %G_SOURCE_REMOVE or %FALSE it is automatically removed from the list of event sources and will not be called again. See [memory management of sources][mainloop-memory-management] for details @@ -42176,7 +43297,7 @@ use a custom main context. the priority of the idle source. Typically this will be in the - range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE. + range between %G_PRIORITY_DEFAULT_IDLE and %G_PRIORITY_HIGH_IDLE. @@ -42906,17 +44027,17 @@ output via the structured log writer function (see g_log_set_writer_func()). - the log domain, usually #G_LOG_DOMAIN, or %NULL -for the default + the log domain, usually %G_LOG_DOMAIN, or %NULL + for the default the log level, either from #GLogLevelFlags - or a user-defined level + or a user-defined level - the message format. See the printf() documentation + the message format. See the `printf()` documentation @@ -43078,31 +44199,35 @@ This function is mostly intended to be used with Sets the log handler for a domain and a set of log levels. + To handle fatal and recursive messages the @log_levels parameter -must be combined with the #G_LOG_FLAG_FATAL and #G_LOG_FLAG_RECURSION +must be combined with the %G_LOG_FLAG_FATAL and %G_LOG_FLAG_RECURSION bit flags. -Note that since the #G_LOG_LEVEL_ERROR log level is always fatal, if +Note that since the %G_LOG_LEVEL_ERROR log level is always fatal, if you want to set a handler for this log level you must combine it with -#G_LOG_FLAG_FATAL. +%G_LOG_FLAG_FATAL. This has no effect if structured logging is enabled; see [Using Structured Logging][using-structured-logging]. Here is an example for adding a log handler for all warning messages in the default domain: + |[<!-- language="C" --> g_log_set_handler (NULL, G_LOG_LEVEL_WARNING | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); ]| This example adds a log handler for all critical messages from GTK+: + |[<!-- language="C" --> g_log_set_handler ("Gtk", G_LOG_LEVEL_CRITICAL | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); ]| This example adds a log handler for all messages from GLib: + |[<!-- language="C" --> g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL | G_LOG_FLAG_RECURSION, my_log_handler, NULL); @@ -43114,14 +44239,14 @@ g_log_set_handler ("GLib", G_LOG_LEVEL_MASK | G_LOG_FLAG_FATAL the log domain, or %NULL for the default "" - application domain + application domain the log levels to apply the log handler for. - To handle fatal and recursive messages as well, combine - the log levels with the #G_LOG_FLAG_FATAL and - #G_LOG_FLAG_RECURSION bit flags. + To handle fatal and recursive messages as well, combine + the log levels with the %G_LOG_FLAG_FATAL and + %G_LOG_FLAG_RECURSION bit flags. @@ -43146,14 +44271,14 @@ This has no effect if structured logging is enabled; see the log domain, or %NULL for the default "" - application domain + application domain the log levels to apply the log handler for. - To handle fatal and recursive messages as well, combine - the log levels with the #G_LOG_FLAG_FATAL and - #G_LOG_FLAG_RECURSION bit flags. + To handle fatal and recursive messages as well, combine + the log levels with the %G_LOG_FLAG_FATAL and + %G_LOG_FLAG_RECURSION bit flags. @@ -43200,10 +44325,12 @@ There can only be one writer function. It is an error to set more than one. - Log a message with structured data. The message will be passed through to -the log writer set by the application using g_log_set_writer_func(). If the -message is fatal (i.e. its log level is %G_LOG_LEVEL_ERROR), the program will -be aborted by calling G_BREAKPOINT() at the end of this function. If the log writer returns + Log a message with structured data. + +The message will be passed through to the log writer set by the application +using g_log_set_writer_func(). If the message is fatal (i.e. its log level +is %G_LOG_LEVEL_ERROR), the program will be aborted by calling +G_BREAKPOINT() at the end of this function. If the log writer returns %G_LOG_WRITER_UNHANDLED (failure), no other fallback writers will be tried. See the documentation for #GLogWriterFunc for information on chaining writers. @@ -43237,9 +44364,10 @@ Other fields you may commonly want to pass into this function: Note that `CODE_FILE`, `CODE_LINE` and `CODE_FUNC` are automatically set by the logging macros, G_DEBUG_HERE(), g_message(), g_warning(), g_critical(), g_error(), etc, if the symbols `G_LOG_USE_STRUCTURED` is defined before including -glib.h. +`glib.h`. For example: + |[<!-- language="C" --> g_log_structured (G_LOG_DOMAIN, G_LOG_LEVEL_DEBUG, "MESSAGE_ID", "06d4df59e6c24647bfe69d2c27ef0b4e", @@ -43260,6 +44388,7 @@ as a field with #GLogField.length set to zero, otherwise it will be interpreted as a string. For example: + |[<!-- language="C" --> const GLogField fields[] = { { "MESSAGE", "This is a debug message.", -1 }, @@ -43441,6 +44570,76 @@ up to the writer function to determine which log messages are fatal. + + Configure whether the built-in log functions +(g_log_default_handler() for the old-style API, and both +g_log_writer_default() and g_log_writer_standard_streams() for the +structured API) will output all log messages to `stderr`. + +By default, log messages of levels %G_LOG_LEVEL_INFO and +%G_LOG_LEVEL_DEBUG are sent to `stdout`, and other log messages are +sent to `stderr`. This is problematic for applications that intend +to reserve `stdout` for structured output such as JSON or XML. + +This function sets global state. It is not thread-aware, and should be +called at the very start of a program, before creating any other threads +or creating objects that could create worker threads of their own. + + + + + + If %TRUE, use `stderr` for log messages that would + normally have appeared on `stdout` + + + + + + Check whether g_log_writer_default() and g_log_default_handler() would +ignore a message with the given domain and level. + +As with g_log_default_handler(), this function drops debug and informational +messages unless their log domain (or `all`) is listed in the space-separated +`G_MESSAGES_DEBUG` environment variable. + +This can be used when implementing log writers with the same filtering +behaviour as the default, but a different destination or output format: + +|[<!-- language="C" --> + if (g_log_writer_default_would_drop (log_level, log_domain)) + return G_LOG_WRITER_HANDLED; +]| + +or to skip an expensive computation if it is only needed for a debugging +message, and `G_MESSAGES_DEBUG` is not set: + +|[<!-- language="C" --> + if (!g_log_writer_default_would_drop (G_LOG_LEVEL_DEBUG, G_LOG_DOMAIN)) + { + gchar *result = expensive_computation (my_object); + + g_debug ("my_object result: %s", result); + g_free (result); + } +]| + + %TRUE if the log message would be dropped by GLib's + default log handlers + + + + + log level, either from #GLogLevelFlags, or a user-defined + level + + + + log domain + + + + Format a structured log message as a string suitable for outputting to the terminal (or elsewhere). This will include the values of all fields it knows @@ -43637,12 +44836,21 @@ application domain + + + + + + + + + @@ -43671,7 +44879,7 @@ functions which operate on a #GMainContext or a built-in #GSource are thread-safe. Each event source is assigned a priority. The default priority, -#G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. +%G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities. Values greater than 0 denote lower priorities. Events from high priority sources are always processed before events from lower priority sources. @@ -44249,6 +45457,28 @@ from @mem. If @mem is %NULL it returns %NULL. + + Allocates @byte_size bytes of memory, and copies @byte_size bytes into it +from @mem. If @mem is %NULL it returns %NULL. + +This replaces g_memdup(), which was prone to integer overflows when +converting the argument from a #gsize to a #guint. + + a pointer to the newly-allocated copy of the memory, + or %NULL if @mem is %NULL. + + + + + the memory to copy. + + + + the number of bytes to copy. + + + + Copies a block of memory @len bytes long, from @src to @dest. The source and destination areas may overlap. @@ -44680,7 +45910,13 @@ so might hide memory allocation errors. - Wraps g_alloca() in a more typesafe manner. + Wraps g_alloca() in a more typesafe manner. + +As mentioned in the documentation for g_alloca(), @n_structs must always be +entirely under the control of the program, or you may introduce a denial of +service vulnerability. In addition, the multiplication of @struct_type by +@n_structs is not checked, so an overflow may lead to a remote code execution +vulnerability. Type of memory chunks to be allocated @@ -45103,7 +46339,7 @@ static GOptionEntry entries[] = { "verbose", 'v', 0, G_OPTION_ARG_NONE, &verbose, "Be verbose", NULL }, { "beep", 'b', 0, G_OPTION_ARG_NONE, &beep, "Beep when done", NULL }, { "rand", 0, 0, G_OPTION_ARG_NONE, &randomize, "Randomize the data", NULL }, - { NULL } + G_OPTION_ENTRY_NULL }; int @@ -45307,7 +46543,7 @@ is not an absolute path it returns %NULL. - + Matches a string against a compiled pattern. Passing the correct length of the string given is mandatory. The reversed string can be omitted by passing %NULL, this is more efficient if the reversed @@ -45325,6 +46561,7 @@ Note also that the reverse of a UTF-8 encoded string can in general not be obtained by g_strreverse(). This works only if the string does not contain any multibyte characters. GLib offers the g_utf8_strreverse() function to reverse UTF-8 encoded strings. + Use g_pattern_spec_match() instead %TRUE if @string matches @pspec @@ -45369,10 +46606,11 @@ g_pattern_match_string() repeatedly. - + Matches a string against a compiled pattern. If the string is to be matched against more than one pattern, consider using g_pattern_match() instead while supplying the reversed string. + Use g_pattern_spec_match_string() instead %TRUE if @string matches @pspec @@ -45409,7 +46647,10 @@ pattern compilation. pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of -the pointer. +the pointer. + +While @address has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`. @@ -45425,11 +46666,14 @@ the pointer. - This is equivalent to g_bit_trylock, but working on pointers (or + This is equivalent to g_bit_trylock(), but working on pointers (or other pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of -the pointer. +the pointer. + +While @address has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`. %TRUE if the lock was acquired @@ -45450,7 +46694,10 @@ the pointer. pointer-sized values). For portability reasons, you may only lock on the bottom 32 bits of -the pointer. +the pointer. + +While @address has a `volatile` qualifier, this is a historical +artifact and the argument passed to it should not be `volatile`. @@ -45529,6 +46776,23 @@ error condition) then also do nothing. + + Prefixes @prefix to an existing error message. If @err or *@err is +%NULL (i.e.: no error variable) then do nothing. + + + + + + a return location for a #GError, or %NULL + + + + string to prefix @err with + + + + Outputs a formatted message via the print handler. The default print handler simply outputs the message to stdout, without @@ -45692,7 +46956,7 @@ checks, such as string comparisons, use g_ptr_array_find_with_equal_func().pointer to look for - + return location for the index of the element, if found @@ -45730,7 +46994,7 @@ equality is used. equality - + return location for the index of the element, if found @@ -46366,7 +47630,11 @@ but care is taken to detect possible overflow during multiplication. - Decreases the reference count. + Decreases the reference count. + +If %TRUE is returned, the reference count reached 0. After this point, @rc +is an undefined state and must be reinitialized with +g_ref_count_init() to be used again. %TRUE if the reference count reached 0, and %FALSE otherwise @@ -46391,7 +47659,7 @@ but care is taken to detect possible overflow during multiplication. - Initializes a reference count variable. + Initializes a reference count variable to 1. @@ -47301,12 +48569,16 @@ are good enough in practice, though. Parses a command line into an argument vector, in much the same way the shell would, but without many of the expansions the shell would perform (variable expansion, globs, operators, filename expansion, -etc. are not supported). The results are defined to be the same as -those you would get from a UNIX98 /bin/sh, as long as the input -contains none of the unsupported shell expansions. If the input -does contain such expansions, they are passed through -literally. Possible errors are those from the #G_SHELL_ERROR -domain. Free the returned vector with g_strfreev(). +etc. are not supported). + +The results are defined to be the same as those you would get from +a UNIX98 `/bin/sh`, as long as the input contains none of the +unsupported shell expansions. If the input does contain such expansions, +they are passed through literally. + +Possible errors are those from the %G_SHELL_ERROR domain. + +Free the returned vector with g_strfreev(). %TRUE on success, %FALSE if error set @@ -47331,10 +48603,14 @@ domain. Free the returned vector with g_strfreev(). Quotes a string so that the shell (/bin/sh) will interpret the -quoted string to mean @unquoted_string. If you pass a filename to -the shell, for example, you should first quote it with this -function. The return value must be freed with g_free(). The -quoting style used is undefined (single or double quotes may be +quoted string to mean @unquoted_string. + +If you pass a filename to the shell, for example, you should first +quote it with this function. + +The return value must be freed with g_free(). + +The quoting style used is undefined (single or double quotes may be used). quoted string @@ -47348,27 +48624,33 @@ used). - Unquotes a string as the shell (/bin/sh) would. Only handles -quotes; if a string contains file globs, arithmetic operators, -variables, backticks, redirections, or other special-to-the-shell -features, the result will be different from the result a real shell -would produce (the variables, backticks, etc. will be passed -through literally instead of being expanded). This function is -guaranteed to succeed if applied to the result of + Unquotes a string as the shell (/bin/sh) would. + +This function only handles quotes; if a string contains file globs, +arithmetic operators, variables, backticks, redirections, or other +special-to-the-shell features, the result will be different from the +result a real shell would produce (the variables, backticks, etc. +will be passed through literally instead of being expanded). + +This function is guaranteed to succeed if applied to the result of g_shell_quote(). If it fails, it returns %NULL and sets the -error. The @quoted_string need not actually contain quoted or -escaped text; g_shell_unquote() simply goes through the string and -unquotes/unescapes anything that the shell would. Both single and -double quotes are handled, as are escapes including escaped -newlines. The return value must be freed with g_free(). Possible -errors are in the #G_SHELL_ERROR domain. +error. + +The @quoted_string need not actually contain quoted or escaped text; +g_shell_unquote() simply goes through the string and unquotes/unescapes +anything that the shell would. Both single and double quotes are +handled, as are escapes including escaped newlines. + +The return value must be freed with g_free(). + +Possible errors are in the %G_SHELL_ERROR domain. Shell quoting rules are a bit strange. Single quotes preserve the literal string exactly. escape sequences are not allowed; not even -\' - if you want a ' in the quoted text, you have to do something -like 'foo'\''bar'. Double quotes allow $, `, ", \, and newline to -be escaped with backslash. Otherwise double quotes preserve things -literally. +`\'` - if you want a `'` in the quoted text, you have to do something +like `'foo'\''bar'`. Double quotes allow `$`, ```, `"`, `\`, and +newline to be escaped with backslash. Otherwise double quotes +preserve things literally. an unquoted string @@ -47420,17 +48702,19 @@ returned. Allocates a block of memory from the slice allocator. + The block address handed out can be expected to be aligned -to at least 1 * sizeof (void*), -though in general slices are 2 * sizeof (void*) bytes aligned, -if a malloc() fallback implementation is used instead, -the alignment may be reduced in a libc dependent fashion. +to at least `1 * sizeof (void*)`, though in general slices +are `2 * sizeof (void*)` bytes aligned; if a `malloc()` +fallback implementation is used instead, the alignment may +be reduced in a libc dependent fashion. + Note that the underlying slice allocation mechanism can be changed with the [`G_SLICE=always-malloc`][G_SLICE] environment variable. - a pointer to the allocated memory block, which will be %NULL if and - only if @mem_size is 0 + a pointer to the allocated memory block, which will + be %NULL if and only if @mem_size is 0 @@ -47545,6 +48829,7 @@ If @mem_block is %NULL, this function does nothing. Frees a linked list of memory blocks of structure type @type. + The memory blocks must be equal-sized, allocated via g_slice_alloc() or g_slice_alloc0() and linked together by a @next pointer (similar to #GSList). The name of the @@ -47883,7 +49168,7 @@ child_watch_cb (GPid pid, gpointer user_data) { g_message ("Child %" G_PID_FORMAT " exited %s", pid, - g_spawn_check_exit_status (status, NULL) ? "normally" : "abnormally"); + g_spawn_check_wait_status (status, NULL) ? "normally" : "abnormally"); // Free any resources associated with the child here, such as I/O channels // on its stdout and stderr FDs. If you have no code to put in the @@ -47897,13 +49182,15 @@ child_watch_cb (GPid pid, ]| - See g_spawn_async_with_pipes() for a full description; this function + Executes a child program asynchronously. + +See g_spawn_async_with_pipes() for a full description; this function simply calls the g_spawn_async_with_pipes() without any pipes. You should call g_spawn_close_pid() on the returned child process reference when you don't need it any more. -If you are writing a GTK+ application, and the program you are spawning is a +If you are writing a GTK application, and the program you are spawning is a graphical application too, then to ensure that the spawned program opens its windows on the right screen, you may want to use #GdkAppLaunchContext, #GAppLaunchContext, or set the %DISPLAY environment variable. @@ -47954,7 +49241,9 @@ are different concepts on Windows. - Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, + Executes a child program asynchronously. + +Identical to g_spawn_async_with_pipes_and_fds() but with `n_fds` set to zero, so no FD assignments are used. %TRUE on success, %FALSE if an error was set @@ -48065,51 +49354,348 @@ so no FD assignments are used. - - Set @error if @exit_status indicates the child exited abnormally -(e.g. with a nonzero exit code, or via a fatal signal). + + Executes a child program asynchronously (your program will not +block waiting for the child to exit). -The g_spawn_sync() and g_child_watch_add() family of APIs return an -exit status for subprocesses encoded in a platform-specific way. -On Unix, this is guaranteed to be in the same format waitpid() returns, -and on Windows it is guaranteed to be the result of GetExitCodeProcess(). +The child program is specified by the only argument that must be +provided, @argv. @argv should be a %NULL-terminated array of strings, +to be passed as the argument vector for the child. The first string +in @argv is of course the name of the program to execute. By default, +the name of the program must be a full path. If @flags contains the +%G_SPAWN_SEARCH_PATH flag, the `PATH` environment variable is used to +search for the executable. If @flags contains the +%G_SPAWN_SEARCH_PATH_FROM_ENVP flag, the `PATH` variable from @envp +is used to search for the executable. If both the +%G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP flags are +set, the `PATH` variable from @envp takes precedence over the +environment variable. -Prior to the introduction of this function in GLib 2.34, interpreting -@exit_status required use of platform-specific APIs, which is problematic -for software using GLib as a cross-platform layer. +If the program name is not a full path and %G_SPAWN_SEARCH_PATH flag +is not used, then the program will be run from the current directory +(or @working_directory, if specified); this might be unexpected or even +dangerous in some cases when the current directory is world-writable. -Additionally, many programs simply want to determine whether or not -the child exited successfully, and either propagate a #GError or -print a message to standard error. In that common case, this function -can be used. Note that the error message in @error will contain -human-readable information about the exit status. +On Windows, note that all the string or string vector arguments to +this function and the other `g_spawn*()` functions are in UTF-8, the +GLib file name encoding. Unicode characters that are not part of +the system codepage passed in these arguments will be correctly +available in the spawned program only if it uses wide character API +to retrieve its command line. For C programs built with Microsoft's +tools it is enough to make the program have a `wmain()` instead of +`main()`. `wmain()` has a wide character argument vector as parameter. -The @domain and @code of @error have special semantics in the case -where the process has an "exit code", as opposed to being killed by -a signal. On Unix, this happens if WIFEXITED() would be true of -@exit_status. On Windows, it is always the case. +At least currently, mingw doesn't support `wmain()`, so if you use +mingw to develop the spawned program, it should call +g_win32_get_command_line() to get arguments in UTF-8. -The special semantics are that the actual exit code will be the -code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR. -This allows you to differentiate between different exit codes. +On Windows the low-level child process creation API `CreateProcess()` +doesn't use argument vectors, but a command line. The C runtime +library's `spawn*()` family of functions (which g_spawn_async_with_pipes() +eventually calls) paste the argument vector elements together into +a command line, and the C runtime startup code does a corresponding +reconstruction of an argument vector from the command line, to be +passed to `main()`. Complications arise when you have argument vector +elements that contain spaces or double quotes. The `spawn*()` functions +don't do any quoting or escaping, but on the other hand the startup +code does do unquoting and unescaping in order to enable receiving +arguments with embedded spaces or double quotes. To work around this +asymmetry, g_spawn_async_with_pipes() will do quoting and escaping on +argument vector elements that need it before calling the C runtime +`spawn()` function. -If the process was terminated by some means other than an exit -status, the domain will be %G_SPAWN_ERROR, and the code will be -%G_SPAWN_ERROR_FAILED. +The returned @child_pid on Windows is a handle to the child +process, not its identifier. Process handles and process +identifiers are different concepts on Windows. -This function just offers convenience; you can of course also check -the available platform via a macro such as %G_OS_UNIX, and use -WIFEXITED() and WEXITSTATUS() on @exit_status directly. Do not attempt -to scan or parse the error message string; it may be translated and/or -change in future versions of GLib. +@envp is a %NULL-terminated array of strings, where each string +has the form `KEY=VALUE`. This will become the child's environment. +If @envp is %NULL, the child inherits its parent's environment. + +@flags should be the bitwise OR of any flags you want to affect the +function's behaviour. The %G_SPAWN_DO_NOT_REAP_CHILD means that the +child will not automatically be reaped; you must use a child watch +(g_child_watch_add()) to be notified about the death of the child process, +otherwise it will stay around as a zombie process until this process exits. +Eventually you must call g_spawn_close_pid() on the @child_pid, in order to +free resources which may be associated with the child process. (On Unix, +using a child watch is equivalent to calling waitpid() or handling +the `SIGCHLD` signal manually. On Windows, calling g_spawn_close_pid() +is equivalent to calling `CloseHandle()` on the process handle returned +in @child_pid). See g_child_watch_add(). + +Open UNIX file descriptors marked as `FD_CLOEXEC` will be automatically +closed in the child process. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN means that +other open file descriptors will be inherited by the child; otherwise all +descriptors except stdin/stdout/stderr will be closed before calling `exec()` +in the child. %G_SPAWN_SEARCH_PATH means that @argv[0] need not be an +absolute path, it will be looked for in the `PATH` environment +variable. %G_SPAWN_SEARCH_PATH_FROM_ENVP means need not be an +absolute path, it will be looked for in the `PATH` variable from +@envp. If both %G_SPAWN_SEARCH_PATH and %G_SPAWN_SEARCH_PATH_FROM_ENVP +are used, the value from @envp takes precedence over the environment. + +%G_SPAWN_STDOUT_TO_DEV_NULL means that the child's standard output +will be discarded, instead of going to the same location as the parent's +standard output. If you use this flag, @stdout_pipe_out must be %NULL. + +%G_SPAWN_STDERR_TO_DEV_NULL means that the child's standard error +will be discarded, instead of going to the same location as the parent's +standard error. If you use this flag, @stderr_pipe_out must be %NULL. + +%G_SPAWN_CHILD_INHERITS_STDIN means that the child will inherit the parent's +standard input (by default, the child's standard input is attached to +`/dev/null`). If you use this flag, @stdin_pipe_out must be %NULL. + +It is valid to pass the same FD in multiple parameters (e.g. you can pass +a single FD for both @stdout_fd and @stderr_fd, and include it in +@source_fds too). + +@source_fds and @target_fds allow zero or more FDs from this process to be +remapped to different FDs in the spawned process. If @n_fds is greater than +zero, @source_fds and @target_fds must both be non-%NULL and the same length. +Each FD in @source_fds is remapped to the FD number at the same index in +@target_fds. The source and target FD may be equal to simply propagate an FD +to the spawned process. FD remappings are processed after standard FDs, so +any target FDs which equal @stdin_fd, @stdout_fd or @stderr_fd will overwrite +them in the spawned process. + +%G_SPAWN_FILE_AND_ARGV_ZERO means that the first element of @argv is +the file to execute, while the remaining elements are the actual +argument vector to pass to the file. Normally g_spawn_async_with_pipes() +uses @argv[0] as the file to execute, and passes all of @argv to the child. + +@child_setup and @user_data are a function and user data. On POSIX +platforms, the function is called in the child after GLib has +performed all the setup it plans to perform (including creating +pipes, closing file descriptors, etc.) but before calling `exec()`. +That is, @child_setup is called just before calling `exec()` in the +child. Obviously actions taken in this function will only affect +the child, not the parent. + +On Windows, there is no separate `fork()` and `exec()` functionality. +Child processes are created and run with a single API call, +`CreateProcess()`. There is no sensible thing @child_setup +could be used for on Windows so it is ignored and not called. + +If non-%NULL, @child_pid will on Unix be filled with the child's +process ID. You can use the process ID to send signals to the child, +or to use g_child_watch_add() (or `waitpid()`) if you specified the +%G_SPAWN_DO_NOT_REAP_CHILD flag. On Windows, @child_pid will be +filled with a handle to the child process only if you specified the +%G_SPAWN_DO_NOT_REAP_CHILD flag. You can then access the child +process using the Win32 API, for example wait for its termination +with the `WaitFor*()` functions, or examine its exit code with +`GetExitCodeProcess()`. You should close the handle with `CloseHandle()` +or g_spawn_close_pid() when you no longer need it. + +If non-%NULL, the @stdin_pipe_out, @stdout_pipe_out, @stderr_pipe_out +locations will be filled with file descriptors for writing to the child's +standard input or reading from its standard output or standard error. +The caller of g_spawn_async_with_pipes() must close these file descriptors +when they are no longer in use. If these parameters are %NULL, the +corresponding pipe won't be created. + +If @stdin_pipe_out is %NULL, the child's standard input is attached to +`/dev/null` unless %G_SPAWN_CHILD_INHERITS_STDIN is set. + +If @stderr_pipe_out is NULL, the child's standard error goes to the same +location as the parent's standard error unless %G_SPAWN_STDERR_TO_DEV_NULL +is set. + +If @stdout_pipe_out is NULL, the child's standard output goes to the same +location as the parent's standard output unless %G_SPAWN_STDOUT_TO_DEV_NULL +is set. + +@error can be %NULL to ignore errors, or non-%NULL to report errors. +If an error is set, the function returns %FALSE. Errors are reported +even if they occur in the child (for example if the executable in +`@argv[0]` is not found). Typically the `message` field of returned +errors should be displayed to users. Possible errors are those from +the #G_SPAWN_ERROR domain. + +If an error occurs, @child_pid, @stdin_pipe_out, @stdout_pipe_out, +and @stderr_pipe_out will not be filled with valid values. + +If @child_pid is not %NULL and an error does not occur then the returned +process reference must be closed using g_spawn_close_pid(). + +On modern UNIX platforms, GLib can use an efficient process launching +codepath driven internally by `posix_spawn()`. This has the advantage of +avoiding the fork-time performance costs of cloning the parent process +address space, and avoiding associated memory overcommit checks that are +not relevant in the context of immediately executing a distinct process. +This optimized codepath will be used provided that the following conditions +are met: + +1. %G_SPAWN_DO_NOT_REAP_CHILD is set +2. %G_SPAWN_LEAVE_DESCRIPTORS_OPEN is set +3. %G_SPAWN_SEARCH_PATH_FROM_ENVP is not set +4. @working_directory is %NULL +5. @child_setup is %NULL +6. The program is of a recognised binary format, or has a shebang. + Otherwise, GLib will have to execute the program through the + shell, which is not done using the optimized codepath. + +If you are writing a GTK application, and the program you are spawning is a +graphical application too, then to ensure that the spawned program opens its +windows on the right screen, you may want to use #GdkAppLaunchContext, +#GAppLaunchContext, or set the `DISPLAY` environment variable. + + %TRUE on success, %FALSE if an error was set + + + + + child's current working + directory, or %NULL to inherit parent's, in the GLib file name encoding + + + + child's argument + vector, in the GLib file name encoding + + + + + + + child's environment, or %NULL to inherit parent's, in the GLib file + name encoding + + + + + + flags from #GSpawnFlags + + + + function to run in the child just before `exec()` + + + + user data for @child_setup + + + + file descriptor to use for child's stdin, or `-1` + + + + file descriptor to use for child's stdout, or `-1` + + + + file descriptor to use for child's stderr, or `-1` + + + + array of FDs from the parent + process to make available in the child process + + + + + + array of FDs to remap + @source_fds to in the child process + + + + + + number of FDs in @source_fds and @target_fds + + + + return location for child process ID, or %NULL + + + + return location for file descriptor to write to child's stdin, or %NULL + + + + return location for file descriptor to read child's stdout, or %NULL + + + + return location for file descriptor to read child's stderr, or %NULL + + + + + + An old name for g_spawn_check_wait_status(), deprecated because its +name is misleading. + +Despite the name of the function, @wait_status must be the wait status +as returned by g_spawn_sync(), g_subprocess_get_status(), `waitpid()`, +etc. On Unix platforms, it is incorrect for it to be the exit status +as passed to `exit()` or returned by g_subprocess_get_exit_status() or +`WEXITSTATUS()`. + Use g_spawn_check_wait_status() instead, and check whether your code is conflating wait and exit statuses. %TRUE if child exited successfully, %FALSE otherwise (and @error will be set) - - An exit code as returned from g_spawn_sync() + + A status as returned from g_spawn_sync() + + + + + + Set @error if @wait_status indicates the child exited abnormally +(e.g. with a nonzero exit code, or via a fatal signal). + +The g_spawn_sync() and g_child_watch_add() family of APIs return the +status of subprocesses encoded in a platform-specific way. +On Unix, this is guaranteed to be in the same format waitpid() returns, +and on Windows it is guaranteed to be the result of GetExitCodeProcess(). + +Prior to the introduction of this function in GLib 2.34, interpreting +@wait_status required use of platform-specific APIs, which is problematic +for software using GLib as a cross-platform layer. + +Additionally, many programs simply want to determine whether or not +the child exited successfully, and either propagate a #GError or +print a message to standard error. In that common case, this function +can be used. Note that the error message in @error will contain +human-readable information about the wait status. + +The @domain and @code of @error have special semantics in the case +where the process has an "exit code", as opposed to being killed by +a signal. On Unix, this happens if WIFEXITED() would be true of +@wait_status. On Windows, it is always the case. + +The special semantics are that the actual exit code will be the +code set in @error, and the domain will be %G_SPAWN_EXIT_ERROR. +This allows you to differentiate between different exit codes. + +If the process was terminated by some means other than an exit +status (for example if it was killed by a signal), the domain will be +%G_SPAWN_ERROR and the code will be %G_SPAWN_ERROR_FAILED. + +This function just offers convenience; you can of course also check +the available platform via a macro such as %G_OS_UNIX, and use +WIFEXITED() and WEXITSTATUS() on @wait_status directly. Do not attempt +to scan or parse the error message string; it may be translated and/or +change in future versions of GLib. + +Prior to version 2.70, g_spawn_check_exit_status() provides the same +functionality, although under a misleading name. + + %TRUE if child exited successfully, %FALSE otherwise (and + @error will be set) + + + + + A platform-specific wait status as returned from g_spawn_sync() @@ -48131,8 +49717,9 @@ though it doesn't do anything under UNIX. A simple version of g_spawn_async() that parses a command line with -g_shell_parse_argv() and passes it to g_spawn_async(). Runs a -command line in the background. Unlike g_spawn_async(), the +g_shell_parse_argv() and passes it to g_spawn_async(). + +Runs a command line in the background. Unlike g_spawn_async(), the %G_SPAWN_SEARCH_PATH flag is enabled, other flags are not. Note that %G_SPAWN_SEARCH_PATH can have security implications, so consider using g_spawn_async() directly if appropriate. Possible @@ -48152,17 +49739,24 @@ The same concerns on Windows apply as for g_spawn_command_line_sync(). A simple version of g_spawn_sync() with little-used parameters -removed, taking a command line instead of an argument vector. See -g_spawn_sync() for full details. @command_line will be parsed by -g_shell_parse_argv(). Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag -is enabled. Note that %G_SPAWN_SEARCH_PATH can have security -implications, so consider using g_spawn_sync() directly if -appropriate. Possible errors are those from g_spawn_sync() and those +removed, taking a command line instead of an argument vector. + +See g_spawn_sync() for full details. + +The @command_line argument will be parsed by g_shell_parse_argv(). + +Unlike g_spawn_sync(), the %G_SPAWN_SEARCH_PATH flag is enabled. +Note that %G_SPAWN_SEARCH_PATH can have security implications, so +consider using g_spawn_sync() directly if appropriate. + +Possible errors are those from g_spawn_sync() and those from g_shell_parse_argv(). -If @exit_status is non-%NULL, the platform-specific exit status of +If @wait_status is non-%NULL, the platform-specific status of the child is stored there; see the documentation of -g_spawn_check_exit_status() for how to use and interpret this. +g_spawn_check_wait_status() for how to use and interpret this. +On Unix platforms, note that it is usually not equal +to the integer passed to `exit()` or returned from `main()`. On Windows, please note the implications of g_shell_parse_argv() parsing @command_line. Parsing is done according to Unix shell rules, not @@ -48194,8 +49788,8 @@ separator. You need to enclose such paths with single quotes, like - - return location for child exit status, as returned by waitpid() + + return location for child wait status, as returned by waitpid() @@ -48212,20 +49806,24 @@ separator. You need to enclose such paths with single quotes, like Executes a child synchronously (waits for the child to exit before returning). + All output from the child is stored in @standard_output and @standard_error, if those parameters are non-%NULL. Note that you must set the %G_SPAWN_STDOUT_TO_DEV_NULL and %G_SPAWN_STDERR_TO_DEV_NULL flags when passing %NULL for @standard_output and @standard_error. -If @exit_status is non-%NULL, the platform-specific exit status of +If @wait_status is non-%NULL, the platform-specific status of the child is stored there; see the documentation of -g_spawn_check_exit_status() for how to use and interpret this. +g_spawn_check_wait_status() for how to use and interpret this. +On Unix platforms, note that it is usually not equal +to the integer passed to `exit()` or returned from `main()`. + Note that it is invalid to pass %G_SPAWN_DO_NOT_REAP_CHILD in @flags, and on POSIX platforms, the same restrictions as for g_child_watch_source_new() apply. If an error occurs, no data is returned in @standard_output, -@standard_error, or @exit_status. +@standard_error, or @wait_status. This function calls g_spawn_async_with_pipes() internally; see that function for full details on the other parameters and details on @@ -48278,8 +49876,8 @@ how these functions work on Windows. - - return location for child exit status, as returned by waitpid(), or %NULL + + return location for child wait status, as returned by waitpid(), or %NULL @@ -48608,21 +50206,24 @@ known. For each character in @string, if the character is not in @valid_chars, -replaces the character with @substitutor. Modifies @string in place, -and return @string itself, not a copy. The return value is to allow -nesting such as +replaces the character with @substitutor. + +Modifies @string in place, and return @string itself, not a copy. The +return value is to allow nesting such as: + |[<!-- language="C" --> g_ascii_strup (g_strcanon (str, "abc", '?')) ]| -In order to modify a copy, you may use `g_strdup()`: +In order to modify a copy, you may use g_strdup(): + |[<!-- language="C" --> reformatted = g_strcanon (g_strdup (const_str), "abc", '?'); ... g_free (reformatted); ]| - @string + the modified @string @@ -48766,22 +50367,26 @@ often requires the pieces to be reordered. Converts any delimiter characters in @string to @new_delimiter. + Any characters in @string which are found in @delimiters are changed to the @new_delimiter character. Modifies @string in place, -and returns @string itself, not a copy. The return value is to -allow nesting such as +and returns @string itself, not a copy. + +The return value is to allow nesting such as: + |[<!-- language="C" --> g_ascii_strup (g_strdelimit (str, "abc", '?')) ]| -In order to modify a copy, you may use `g_strdup()`: +In order to modify a copy, you may use g_strdup(): + |[<!-- language="C" --> reformatted = g_strdelimit (g_strdup (const_str), "abc", '?'); ... g_free (reformatted); ]| - @string + the modified @string @@ -48998,60 +50603,6 @@ g_string_chunk_insert_const(). To free the entire #GStringChunk use g_string_chunk_free(). It is not possible to free individual strings. - - Creates a new #GString, initialized with the given string. - - the new #GString - - - - - the initial text to copy into the string, or %NULL to -start with an empty string - - - - - - Creates a new #GString with @len bytes of the @init buffer. -Because a length is provided, @init need not be nul-terminated, -and can contain embedded nul bytes. - -Since this function does not stop at nul bytes, it is the caller's -responsibility to ensure that @init has at least @len addressable -bytes. - - a new #GString - - - - - initial contents of the string - - - - length of @init to use - - - - - - Creates a new #GString, with enough space for @dfl_size -bytes. This is useful if you are going to add a lot of -text to the string and don't want it to be reallocated -too often. - - the new #GString - - - - - the default size of the space allocated to - hold the string - - - - This section describes a number of utility functions for creating, duplicating, and manipulating strings. @@ -49777,10 +51328,14 @@ do so even if it isn’t. This function 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 assumed to be the empty string, so a full URI can be provided to -g_test_bug() instead. +g_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() @@ -49788,7 +51343,7 @@ See also: g_test_summary() - Bug specific bug tracker URI portion. + Bug specific bug tracker URI or URI portion. @@ -49804,7 +51359,7 @@ a test case changes the base URI for the scope of the test case only. 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. +`%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(). @@ -49988,11 +51543,34 @@ need to return from the test function yourself. So you can produce additional diagnostic messages or even continue running the test. -If not called from inside a test, this function does nothing. +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. +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. + + Equivalent to g_test_fail(), but also record a message like +g_test_skip_printf(). + + + + + + the format string + + + + printf-like arguments to @format + + + + Returns whether a test has already failed. This will be the case when g_test_fail(), g_test_incomplete() @@ -50058,6 +51636,18 @@ 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. + +This function returns a valid string only within a test function. + + the test path for the test currently being run + + + Get the toplevel test suite for the test path API. @@ -50086,6 +51676,23 @@ 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(). + + + + + + the format string + + + + printf-like arguments to @format + + + + Initialize the GLib testing framework, e.g. by seeding the test random number generator, the name for g_get_prgname() @@ -50461,6 +52068,23 @@ 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(). + + + + + + the format string + + + + printf-like arguments to @format + + + + Returns %TRUE (after g_test_init() has been called) if the test program is running under g_test_trap_subprocess(). @@ -51195,10 +52819,12 @@ g_date_time_unref (dt); Sets a function to be called at regular intervals, with the default -priority, #G_PRIORITY_DEFAULT. The function is called repeatedly -until it returns %FALSE, at which point the timeout is automatically -destroyed and the function will not be called again. The first call -to the function will be at the end of the first @interval. +priority, %G_PRIORITY_DEFAULT. + +The given @function is called repeatedly until it returns %G_SOURCE_REMOVE +or %FALSE, at which point the timeout is automatically destroyed and the +function will not be called again. The first call to the function will be +at the end of the first @interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. @@ -51231,7 +52857,7 @@ time. See g_get_monotonic_time(). the time between calls to the function, in milliseconds - (1/1000ths of a second) + (1/1000ths of a second) @@ -51276,12 +52902,12 @@ See g_get_monotonic_time(). the priority of the timeout source. Typically this will be in - the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. the time between calls to the function, in milliseconds - (1/1000ths of a second) + (1/1000ths of a second) @@ -51300,8 +52926,10 @@ See g_get_monotonic_time(). Sets a function to be called at regular intervals with the default -priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until -it returns %FALSE, at which point the timeout is automatically destroyed +priority, %G_PRIORITY_DEFAULT. + +The function is called repeatedly until it returns %G_SOURCE_REMOVE +or %FALSE, at which point the timeout is automatically destroyed and the function will not be called again. This internally creates a main loop source using @@ -51341,17 +52969,18 @@ time. See g_get_monotonic_time(). Sets a function to be called at regular intervals, with @priority. -The function is called repeatedly until it returns %FALSE, at which -point the timeout is automatically destroyed and the function will -not be called again. + +The function is called repeatedly until it returns %G_SOURCE_REMOVE +or %FALSE, at which point the timeout is automatically destroyed and +the function will not be called again. Unlike g_timeout_add(), this function operates at whole second granularity. The initial starting point of the timer is determined by the implementation and the implementation is expected to group multiple timers together so that -they fire all at the same time. -To allow this grouping, the @interval to the first timer is rounded -and can deviate up to one second from the specified interval. -Subsequent timer iterations will generally run at the specified interval. +they fire all at the same time. To allow this grouping, the @interval to the +first timer is rounded and can deviate up to one second from the specified +interval. Subsequent timer iterations will generally run at the specified +interval. Note that timeout functions may be delayed, due to the processing of other event sources. Thus they should not be relied on for precise timing. @@ -51385,7 +53014,7 @@ time. See g_get_monotonic_time(). the priority of the timeout source. Typically this will be in - the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH. + the range between %G_PRIORITY_DEFAULT and %G_PRIORITY_HIGH. @@ -51808,6 +53437,12 @@ portable in any way, shape or form. These macros only allow storing integers in pointers, and only preserve 32 bits of the integer; values outside the range of a 32-bit integer will be mangled. + + + + + + GLib defines a number of commonly used types, which can be divided into several groups: @@ -51854,13 +53489,13 @@ added to the result after the converted text. If @len < 0, then the string is nul-terminated. - + location to store number of bytes read, or %NULL. If an error occurs then the index of the invalid input is stored here. - + location to store number of #gunichar2 written, or %NULL. The value stored here does not include the trailing 0. @@ -51888,12 +53523,12 @@ to UTF-8. The result will be terminated with a 0 byte. If @len < 0, then the string is nul-terminated. - + location to store number of characters read, or %NULL. - + location to store number of bytes written or %NULL. The value here stored does not include the trailing 0 byte. @@ -53781,14 +55416,14 @@ nul-terminated. If @len < 0, then the string is nul-terminated. - + location to store number of words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. - + location to store number of characters written, or %NULL. The value stored here does not include the trailing 0 character. @@ -53826,14 +55461,14 @@ unpaired surrogates or partial character sequences. If @len < 0, then the string is nul-terminated. - + location to store number of words read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. - + location to store number of bytes written, or %NULL. The value stored here does not include the trailing 0 byte. @@ -54070,10 +55705,15 @@ readable as-is. - Skips to the next character in a UTF-8 string. The string must be -valid; this macro is as fast as possible, and has no error-checking. -You would use this macro to iterate over a string character by -character. The macro returns the start of the next UTF-8 character. + Skips to the next character in a UTF-8 string. + +The string must be valid; this macro is as fast as possible, and has +no error-checking. + +You would use this macro to iterate over a string character by character. + +The macro returns the start of the next UTF-8 character. + Before using this macro, use g_utf8_validate() to validate strings that may contain invalid UTF-8. @@ -54413,7 +56053,7 @@ string after the converted text. then the string is nul-terminated. - + location to store number of bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be @@ -54422,7 +56062,7 @@ string after the converted text. invalid input is stored here. - + location to store number of characters written or %NULL. The value here stored does not include the trailing 0 character. @@ -54451,7 +56091,7 @@ will be added to the string after the converted text. then the string is nul-terminated. - + location to store the number of characters in the result, or %NULL. @@ -54477,14 +56117,14 @@ added to the result after the converted text. If @len < 0, then the string is nul-terminated. - + location to store number of bytes read, or %NULL. If %NULL, then %G_CONVERT_ERROR_PARTIAL_INPUT will be returned in case @str contains a trailing partial character. If an error occurs then the index of the invalid input is stored here. - + location to store number of #gunichar2 written, or %NULL. The value stored here does not include the trailing 0. diff --git a/GModule-2.0.gir b/GModule-2.0.gir index 1d85fab..29b42bc 100644 --- a/GModule-2.0.gir +++ b/GModule-2.0.gir @@ -113,17 +113,41 @@ directory it will return `\Windows\mylibrary.dll`. + + + + + + A thin wrapper function around g_module_open_full() + + a #GModule on success, or %NULL on failure + + + + + the name of the file containing the module, or %NULL + to obtain a #GModule representing the main program itself + + + + the flags used for opening the module. This can be the + logical OR of any of the #GModuleFlags. + + + + + Opens a module. If the module has already been opened, its reference count is incremented. -First of all g_module_open() tries to open @file_name as a module. +First of all g_module_open_full() tries to open @file_name as a module. If that fails and @file_name has the ".la"-suffix (and is a libtool archive) it tries to open the corresponding module. If that fails and it doesn't have the proper module suffix for the platform (#G_MODULE_SUFFIX), this suffix will be appended and the corresponding module will be opened. If that fails and @file_name doesn't have the -".la"-suffix, this suffix is appended and g_module_open() tries to open +".la"-suffix, this suffix is appended and g_module_open_full() tries to open the corresponding module. If eventually that fails as well, %NULL is returned. @@ -168,6 +192,15 @@ error. + + Errors returned by g_module_open_full(). + + there was an error loading or opening a module file + + + a module returned an error from its `g_module_check_init()` function + + Flags passed to g_module_open(). Note that these flags are not supported on all platforms. @@ -240,6 +273,11 @@ directory it will return `\Windows\mylibrary.dll`. + + + + + Checks if modules are supported on the current platform. diff --git a/GObject-2.0.gir b/GObject-2.0.gir index edaf7b3..c9b4770 100644 --- a/GObject-2.0.gir +++ b/GObject-2.0.gir @@ -10,9 +10,11 @@ and/or use gtk-doc annotations. --> This is the signature of marshaller functions, required to marshall arrays of parameter values to signal emissions into C language callback -invocations. It is merely an alias to #GClosureMarshal since the #GClosure -mechanism takes over responsibility of actual function invocation for the -signal system. +invocations. + +It is merely an alias to #GClosureMarshal since the #GClosure mechanism +takes over responsibility of actual function invocation for the signal +system. @@ -46,10 +48,10 @@ For instance: G_ADD_PRIVATE (MyObject)) ]| -Will add MyObjectPrivate as the private data to any instance of the MyObject -type. +Will add `MyObjectPrivate` as the private data to any instance of the +`MyObject` type. -G_DEFINE_TYPE_* macros will automatically create a private function +`G_DEFINE_TYPE_*` macros will automatically create a private function based on the arguments to this macro, which can be used to safely retrieve the private data from an instance of the type; for instance: @@ -77,7 +79,7 @@ retrieve the private data from an instance of the type; for instance: } ]| -Note that this macro can only be used together with the G_DEFINE_TYPE_* +Note that this macro can only be used together with the `G_DEFINE_TYPE_*` macros, since it depends on variable names from those macros. Also note that private structs added with these macros must have a struct @@ -94,8 +96,9 @@ case the returned pointer must not be dereferenced. A convenience macro to ease adding private data to instances of a new dynamic -type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See -G_ADD_PRIVATE() for details, it is similar but for static types. +type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). + +See G_ADD_PRIVATE() for details, it is similar but for static types. Note that this macro can only be used together with the G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable @@ -115,8 +118,11 @@ names from that macro. A callback function used by the type system to finalize those portions of a derived types class structure that were setup from the corresponding -GBaseInitFunc() function. Class finalization basically works the inverse -way in which class initialization is performed. +GBaseInitFunc() function. + +Class finalization basically works the inverse way in which class +initialization is performed. + See GClassInitFunc() for a discussion of the class initialization process. @@ -130,9 +136,12 @@ See GClassInitFunc() for a discussion of the class initialization process. A callback function used by the type system to do base initialization -of the class structures of derived types. It is called as part of the -initialization process of all derived classes and should reallocate -or reset all dynamic class members copied over from the parent class. +of the class structures of derived types. + +This function is called as part of the initialization process of all derived +classes and should reallocate or reset all dynamic class members copied over +from the parent class. + For example, class members (such as strings) that are not sufficiently handled by a plain memory copy of the parent class into the derived class have to be altered. See GClassInitFunc() for a discussion of the class @@ -150,9 +159,10 @@ initialization process. #GBinding is the representation of a binding between a property on a #GObject instance (or source) and another property on another #GObject -instance (or target). Whenever the source property changes, the same -value is applied to the target property; for instance, the following -binding: +instance (or target). + +Whenever the source property changes, the same value is applied to the +target property; for instance, the following binding: |[<!-- language="C" --> g_object_bind_property (object1, "property-a", @@ -225,7 +235,43 @@ and target properties, instead of relying on the last reference on the binding, source, and target instances to drop. #GBinding is available since GObject 2.26 - + + Retrieves the #GObject instance used as the source of the binding. + +A #GBinding can outlive the source #GObject as the binding does not hold a +strong reference to the source. If the source is destroyed before the +binding then this function will return %NULL. + + the source #GObject, or %NULL if the + source does not exist any more. + + + + + a #GBinding + + + + + + Retrieves the #GObject instance used as the target of the binding. + +A #GBinding can outlive the target #GObject as the binding does not hold a +strong reference to the target. If the target is destroyed before the +binding then this function will return %NULL. + + the target #GObject, or %NULL if the + target does not exist any more. + + + + + a #GBinding + + + + + Retrieves the flags passed when constructing the #GBinding. the #GBindingFlags used by the #GBinding @@ -238,7 +284,7 @@ binding, source, and target instances to drop. - + Retrieves the #GObject instance used as the source of the binding. A #GBinding can outlive the source #GObject as the binding does not hold a @@ -262,7 +308,7 @@ function. - + Retrieves the name of the property of #GBinding:source used as the source of the binding. @@ -276,7 +322,7 @@ of the binding. - + Retrieves the #GObject instance used as the target of the binding. A #GBinding can outlive the target #GObject as the binding does not hold a @@ -300,7 +346,7 @@ function. - + Retrieves the name of the property of #GBinding:target used as the target of the binding. @@ -336,15 +382,15 @@ g_object_bind_property() and is owned by the binding. - + Flags to be used to control the #GBinding - + The #GObject that should be used as the source of the binding - + The name of the property of #GBinding:source that should be used as the source of the binding. @@ -352,11 +398,11 @@ This should be in [canonical form][canonical-parameter-names] to get the best performance. - + The #GObject that should be used as the target of the binding - + The name of the property of #GBinding:target that should be used as the target of the binding. @@ -370,21 +416,21 @@ best performance. g_object_bind_property_full(). This enumeration can be extended at later date. - + The default binding; if the source property changes, the target property is updated with its value. - + Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. - + Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target. - + If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for @@ -393,8 +439,9 @@ This enumeration can be extended at later date. - A function to be called to transform @from_value to @to_value. If -this is the @transform_to function of a binding, then @from_value + A function to be called to transform @from_value to @to_value. + +If this is the @transform_to function of a binding, then @from_value is the @source_property on the @source object, and @to_value is the @target_property on the @target object. If this is the @transform_from function of a %G_BINDING_BIDIRECTIONAL binding, @@ -2365,6 +2412,7 @@ the first parameter. Get the total number of notifiers connected with the closure @cl. + The count includes the meta marshaller, the finalize and invalidate notifiers and the marshal guards. Note that each guard counts as two notifiers. See g_closure_set_meta_marshal(), g_closure_add_finalize_notifier(), @@ -2377,18 +2425,23 @@ g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). The type used for callback functions in structure definitions and function -signatures. This doesn't mean that all callback functions must take no -parameters and return void. The required signature of a callback function -is determined by the context in which is used (e.g. the signal to which it -is connected). Use G_CALLBACK() to cast the callback function to a #GCallback. +signatures. + +This doesn't mean that all callback functions must take no parameters and +return void. The required signature of a callback function is determined by +the context in which is used (e.g. the signal to which it is connected). + +Use G_CALLBACK() to cast the callback function to a #GCallback. A callback function used by the type system to finalize a class. + This function is rarely needed, as dynamically allocated class resources should be handled by GBaseInitFunc() and GBaseFinalizeFunc(). + Also, specification of a GClassFinalizeFunc() in the #GTypeInfo structure of a static type is invalid, because classes of static types will never be finalized (they are artificially kept alive when their @@ -2409,8 +2462,9 @@ reference count drops to zero). A callback function used by the type system to initialize the class -of a specific type. This function should initialize all static class -members. +of a specific type. + +This function should initialize all static class members. The initialization process of a class involves: @@ -2479,6 +2533,7 @@ type_b_class_init (TypeBClass *class) class->static_float = 3.14159265358979323846; } ]| + Initialization of TypeBClass will first cause initialization of TypeAClass (derived classes reference their parent classes, see g_type_class_ref() on this). @@ -2518,8 +2573,9 @@ time. - A #GClosure represents a callback supplied by the programmer. It -will generally comprise a function of some kind and a marshaller + A #GClosure represents a callback supplied by the programmer. + +It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to convert the arguments for the invocation from #GValues into a suitable form, perform the callback on the converted arguments, @@ -2562,38 +2618,38 @@ callback function/data pointer combination: - g_closure_invalidate() and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away. - + - + - + - + - + - + - + - + Indicates whether the closure is currently being invoked with g_closure_invoke() - + Indicates whether the closure has been invalidated by g_closure_invalidate() - + @@ -2652,8 +2708,9 @@ when implementing new types of closures. Allocates a struct of the given size and initializes the initial -part as a #GClosure. This function is mainly useful when -implementing new types of closures. +part as a #GClosure. + +This function is mainly useful when implementing new types of closures: |[<!-- language="C" --> typedef struct _MyClosure MyClosure; @@ -2705,11 +2762,12 @@ MyClosure *my_closure_new (gpointer data) Registers a finalization notifier which will be called when the -reference count of @closure goes down to 0. Multiple finalization -notifiers on a single closure are invoked in unspecified order. If -a single call to g_closure_unref() results in the closure being -both invalidated and finalized, then the invalidate notifiers will -be run before the finalize notifiers. +reference count of @closure goes down to 0. + +Multiple finalization notifiers on a single closure are invoked in +unspecified order. If a single call to g_closure_unref() results in +the closure being both invalidated and finalized, then the invalidate +notifiers will be run before the finalize notifiers. @@ -2730,9 +2788,10 @@ be run before the finalize notifiers. Registers an invalidation notifier which will be called when the -@closure is invalidated with g_closure_invalidate(). Invalidation -notifiers are invoked before finalization notifiers, in an -unspecified order. +@closure is invalidated with g_closure_invalidate(). + +Invalidation notifiers are invoked before finalization notifiers, +in an unspecified order. @@ -2753,9 +2812,11 @@ unspecified order. Adds a pair of notifiers which get invoked before and after the -closure callback, respectively. This is typically used to protect -the extra arguments for the duration of the callback. See -g_object_watch_closure() for an example of marshal guards. +closure callback, respectively. + +This is typically used to protect the extra arguments for the +duration of the callback. See g_object_watch_closure() for an +example of marshal guards. @@ -2788,7 +2849,9 @@ g_object_watch_closure() for an example of marshal guards. Sets a flag on the closure to indicate that its calling environment has become invalid, and thus causes any future invocations of g_closure_invoke() on this @closure to be -ignored. Also, invalidation notifiers installed on the closure will +ignored. + +Also, invalidation notifiers installed on the closure will be called at this point. Note that unless you are holding a reference to the closure yourself, the invalidation notifiers may unref the closure and cause it to be destroyed, so if you need to @@ -2903,12 +2966,16 @@ Notice that notifiers are automatically removed after they are run. - Sets the marshaller of @closure. The `marshal_data` -of @marshal provides a way for a meta marshaller to provide additional -information to the marshaller. (See g_closure_set_meta_marshal().) For -GObject's C predefined marshallers (the g_cclosure_marshal_*() + Sets the marshaller of @closure. + +The `marshal_data` of @marshal provides a way for a meta marshaller to +provide additional information to the marshaller. + +For GObject's C predefined marshallers (the `g_cclosure_marshal_*()` functions), what it provides is a callback function to use instead of -@closure->callback. +@closure->callback. + +See also: g_closure_set_meta_marshal() @@ -2924,12 +2991,15 @@ functions), what it provides is a callback function to use instead of - Sets the meta marshaller of @closure. A meta marshaller wraps -@closure->marshal and modifies the way it is called in some -fashion. The most common use of this facility is for C callbacks. + Sets the meta marshaller of @closure. + +A meta marshaller wraps the @closure's marshal and modifies the way +it is called in some fashion. The most common use of this facility +is for C callbacks. + The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), are used everywhere, but the way that we get the callback function -differs. In most cases we want to use @closure->callback, but in +differs. In most cases we want to use the @closure's callback, but in other cases we want to use some different technique to retrieve the callback function. @@ -2958,27 +3028,34 @@ the right callback and passes it to the marshaller as the - Takes over the initial ownership of a closure. Each closure is -initially created in a "floating" state, which means that the initial -reference count is not owned by any caller. g_closure_sink() checks -to see if the object is still floating, and if so, unsets the -floating state and decreases the reference count. If the closure -is not floating, g_closure_sink() does nothing. The reason for the -existence of the floating state is to prevent cumbersome code -sequences like: + Takes over the initial ownership of a closure. + +Each closure is initially created in a "floating" state, which means +that the initial reference count is not owned by any caller. + +This function checks to see if the object is still floating, and if so, +unsets the floating state and decreases the reference count. If the +closure is not floating, g_closure_sink() does nothing. + +The reason for the existence of the floating state is to prevent +cumbersome code sequences like: + |[<!-- language="C" --> closure = g_cclosure_new (cb_func, cb_data); g_source_set_closure (source, closure); g_closure_unref (closure); // GObject doesn't really need this ]| + Because g_source_set_closure() (and similar functions) take ownership of the initial reference count, if it is unowned, we instead can write: + |[<!-- language="C" --> g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); ]| Generally, this function is used together with g_closure_ref(). An example of storing a closure for later notification looks like: + |[<!-- language="C" --> static GClosure *notify_closure = NULL; void @@ -3011,8 +3088,10 @@ g_closure_ref() should be called prior to this function. Decrements the reference count of a closure after it was previously -incremented by the same caller. If no other callers are using the -closure, then the closure will be destroyed and freed. +incremented by the same caller. + +If no other callers are using the closure, then the closure will be +destroyed and freed. @@ -3108,7 +3187,7 @@ header file for a type which is intended to be subclassed. You might use it in a header as follows: -|[ +|[<!-- language="C" --> #ifndef _gtk_frobber_h_ #define _gtk_frobber_h_ @@ -3135,26 +3214,26 @@ GtkWidget * gtk_frobber_new (void); This results in the following things happening: -- the usual gtk_frobber_get_type() function is declared with a return type of #GType +- the usual `gtk_frobber_get_type()` function is declared with a return type of #GType -- the GtkFrobber struct is created with GtkWidget as the first and only item. You are expected to use +- the `GtkFrobber` struct is created with `GtkWidget` as the first and only item. You are expected to use a private structure from your .c file to store your instance variables. -- the GtkFrobberClass type is defined as a typedef to struct _GtkFrobberClass, which is left undefined. +- the `GtkFrobberClass` type is defined as a typedef to `struct _GtkFrobberClass`, which is left undefined. You should do this from the header file directly after you use the macro. -- the GTK_FROBBER() and GTK_FROBBER_CLASS() casts are emitted as static inline functions along with - the GTK_IS_FROBBER() and GTK_IS_FROBBER_CLASS() type checking functions and GTK_FROBBER_GET_CLASS() +- the `GTK_FROBBER()` and `GTK_FROBBER_CLASS()` casts are emitted as `static inline` functions along with + the `GTK_IS_FROBBER()` and `GTK_IS_FROBBER_CLASS()` type checking functions and `GTK_FROBBER_GET_CLASS()` function. - g_autoptr() support being added for your type, based on the type of your parent class You can only use this function if your parent type also supports g_autoptr(). -Because the type macro (GTK_TYPE_FROBBER in the above example) is not a callable, you must continue to +Because the type macro (`GTK_TYPE_FROBBER` in the above example) is not a callable, you must continue to manually define this as a macro for yourself. -The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro +The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. If you are writing a library, it is important to note that it is possible to convert a type from using @@ -3169,30 +3248,30 @@ If you must use G_DECLARE_DERIVABLE_TYPE() you should be sure to include some pa class structure to leave space for the addition of future virtual functions. - The name of the new type, in camel case (like GtkWidget) + The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words - separated by '_' (like 'gtk_widget') + separated by `_` (like `gtk_widget`) - The name of the module, in all caps (like 'GTK') + The name of the module, in all caps (like `GTK`) - The bare name of the type, in all caps (like 'WIDGET') + The bare name of the type, in all caps (like `WIDGET`) - the name of the parent type, in camel case (like GtkWidget) + the name of the parent type, in camel case (like `GtkWidget`) - A convenience macro for emitting the usual declarations in the header file for a type which is not (at the -present time) intended to be subclassed. + A convenience macro for emitting the usual declarations in the header file +for a type which is not (at the present time) intended to be subclassed. You might use it in a header as follows: -|[ +|[<!-- language="C" --> #ifndef _myapp_window_h_ #define _myapp_window_h_ @@ -3210,15 +3289,15 @@ MyAppWindow * my_app_window_new (void); This results in the following things happening: -- the usual my_app_window_get_type() function is declared with a return type of #GType +- the usual `my_app_window_get_type()` function is declared with a return type of #GType -- the MyAppWindow types is defined as a typedef of struct _MyAppWindow. The struct itself is not +- the `MyAppWindow` type is defined as a `typedef` of `struct _MyAppWindow`. The struct itself is not defined and should be defined from the .c file before G_DEFINE_TYPE() is used. -- the MY_APP_WINDOW() cast is emitted as static inline function along with the MY_APP_IS_WINDOW() type +- the `MY_APP_WINDOW()` cast is emitted as `static inline` function along with the `MY_APP_IS_WINDOW()` type checking function -- the MyAppWindowClass type is defined as a struct containing GtkWindowClass. This is done for the +- the `MyAppWindowClass` type is defined as a struct containing `GtkWindowClass`. This is done for the convenience of the person defining the type and should not be considered to be part of the ABI. In particular, without a firm declaration of the instance structure, it is not possible to subclass the type and therefore the fact that the size of the class structure is exposed is not a concern and it can be @@ -3228,10 +3307,10 @@ This results in the following things happening: You can only use this function if your parent type also supports g_autoptr(). -Because the type macro (MY_APP_TYPE_WINDOW in the above example) is not a callable, you must continue to +Because the type macro (`MY_APP_TYPE_WINDOW` in the above example) is not a callable, you must continue to manually define this as a macro for yourself. -The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro +The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE(). @@ -3243,29 +3322,29 @@ subclassed. Once a class structure has been exposed it is not possible to chang reorder items without breaking the API and/or ABI. - The name of the new type, in camel case (like GtkWidget) + The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words - separated by '_' (like 'gtk_widget') + separated by `_` (like `gtk_widget`) - The name of the module, in all caps (like 'GTK') + The name of the module, in all caps (like `GTK`) - The bare name of the type, in all caps (like 'WIDGET') + The bare name of the type, in all caps (like `WIDGET`) - the name of the parent type, in camel case (like GtkWidget) + the name of the parent type, in camel case (like `GtkWidget`) - A convenience macro for emitting the usual declarations in the header file for a GInterface type. + A convenience macro for emitting the usual declarations in the header file for a #GInterface type. You might use it in a header as follows: -|[ +|[<!-- language="C" --> #ifndef _my_model_h_ #define _my_model_h_ @@ -3289,45 +3368,46 @@ gpointer my_model_get_item (MyModel *model); This results in the following things happening: -- the usual my_model_get_type() function is declared with a return type of #GType +- the usual `my_model_get_type()` function is declared with a return type of #GType -- the MyModelInterface type is defined as a typedef to struct _MyModelInterface, +- the `MyModelInterface` type is defined as a typedef to `struct _MyModelInterface`, which is left undefined. You should do this from the header file directly after you use the macro. -- the MY_MODEL() cast is emitted as static inline functions along with - the MY_IS_MODEL() type checking function and MY_MODEL_GET_IFACE() function. +- the `MY_MODEL()` cast is emitted as `static inline` functions along with + the `MY_IS_MODEL()` type checking function and `MY_MODEL_GET_IFACE()` function. - g_autoptr() support being added for your type, based on your prerequisite type. You can only use this function if your prerequisite type also supports g_autoptr(). -Because the type macro (MY_TYPE_MODEL in the above example) is not a callable, you must continue to +Because the type macro (`MY_TYPE_MODEL` in the above example) is not a callable, you must continue to manually define this as a macro for yourself. -The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro +The declaration of the `_get_type()` function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. - The name of the new type, in camel case (like GtkWidget) + The name of the new type, in camel case (like `GtkWidget`) The name of the new type in lowercase, with words - separated by '_' (like 'gtk_widget') + separated by `_` (like `gtk_widget`) - The name of the module, in all caps (like 'GTK') + The name of the module, in all caps (like `GTK`) - The bare name of the type, in all caps (like 'WIDGET') + The bare name of the type, in all caps (like `WIDGET`) - the name of the prerequisite type, in camel case (like GtkWidget) + the name of the prerequisite type, in camel case (like `GtkWidget`) A convenience macro for type implementations. + Similar to G_DEFINE_TYPE(), but defines an abstract type. See G_DEFINE_TYPE_EXTENDED() for an example. @@ -3336,7 +3416,7 @@ See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in lowercase, with words - separated by '_'. + separated by `_`. The #GType of the parent type. @@ -3345,9 +3425,11 @@ See G_DEFINE_TYPE_EXTENDED() for an example. A convenience macro for type implementations. + Similar to G_DEFINE_TYPE_WITH_CODE(), but defines an abstract type and -allows you to insert custom code into the *_get_type() function, e.g. +allows you to insert custom code into the `*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). + See G_DEFINE_TYPE_EXTENDED() for an example. @@ -3355,18 +3437,19 @@ See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in lowercase, with words - separated by '_'. + separated by `_`. The #GType of the parent type. - Custom code that gets inserted in the @type_name_get_type() function. + Custom code that gets inserted in the `type_name_get_type()` function. Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. + See G_DEFINE_TYPE_EXTENDED() for an example. @@ -3374,7 +3457,7 @@ See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in lowercase, with words - separated by '_'. + separated by `_`. The #GType of the parent type. @@ -3382,15 +3465,30 @@ See G_DEFINE_TYPE_EXTENDED() for an example. - A convenience macro for boxed type implementations, which defines a -type_name_get_type() function registering the boxed type. + A convenience macro for defining a new custom boxed type. + +Using this macro is the recommended way of defining new custom boxed +types, over calling g_boxed_type_register_static() directly. It defines +a `type_name_get_type()` function which will return the newly defined +#GType, enabling lazy instantiation. + +|[<!-- language="C" --> +G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free) + +void +foo () +{ + GType type = my_struct_get_type (); + // ... your code ... +} +]| The name of the new type, in Camel case The name of the new type, in lowercase, with words - separated by '_' + separated by `_` the #GBoxedCopyFunc for the new type @@ -3402,8 +3500,9 @@ type_name_get_type() function registering the boxed type. A convenience macro for boxed type implementations. + Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the -type_name_get_type() function, e.g. to register value transformations with +`type_name_get_type()` function, e.g. to register value transformations with g_value_register_transform_func(), for instance: |[<!-- language="C" --> @@ -3421,7 +3520,7 @@ defined boxed type is exposed in the `g_define_type_id` variable. The name of the new type, in lowercase, with words - separated by '_' + separated by `_` the #GBoxedCopyFunc for the new type @@ -3430,7 +3529,7 @@ defined boxed type is exposed in the `g_define_type_id` variable. the #GBoxedFreeFunc for the new type - Custom code that gets inserted in the *_get_type() function + Custom code that gets inserted in the `*_get_type()` function @@ -3438,9 +3537,10 @@ defined boxed type is exposed in the `g_define_type_id` variable. A convenience macro for dynamic type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these) and a static variable named -`t_n`_parent_class pointing to the parent class. Furthermore, -it defines a `*_get_type()` and a static `*_register_type()` functions -for use in your `module_init()`. +`t_n`_parent_class pointing to the parent class. + +Furthermore, it defines a `*_get_type()` and a static `*_register_type()` +functions for use in your `module_init()`. See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. @@ -3460,7 +3560,7 @@ See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. A more general version of G_DEFINE_DYNAMIC_TYPE() which allows to specify #GTypeFlags and custom code. -|[ +|[<!-- language="C" --> G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, gtk_gadget, GTK_TYPE_THING, @@ -3468,8 +3568,10 @@ G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, gtk_gadget_gizmo_init)); ]| + expands to -|[ + +|[<!-- language="C" --> static void gtk_gadget_init (GtkGadget *self); static void gtk_gadget_class_init (GtkGadgetClass *klass); static void gtk_gadget_class_finalize (GtkGadgetClass *klass); @@ -3536,9 +3638,71 @@ gtk_gadget_register_type (GTypeModule *type_module) + + A convenience macro for type implementations. + +Similar to G_DEFINE_TYPE(), but defines a final type. + +See G_DEFINE_TYPE_EXTENDED() for an example. + + + the name of the new type, in Camel case + + + the name of the new type, in lower case, with words + separated by `_` (snake case) + + + the #GType of the parent type + + + + + A convenience macro for type implementations. + +Similar to G_DEFINE_TYPE_WITH_CODE(), but defines a final type and +allows you to insert custom code into the `*_get_type()` function, e.g. +interface implementations via G_IMPLEMENT_INTERFACE(). + +See G_DEFINE_TYPE_EXTENDED() for an example. + + + the name of the new type, in Camel case + + + the name of the new type, in lower case, with words + separated by `_` (snake case) + + + the #GType of the parent type + + + Custom code that gets inserted in the `type_name_get_type()` function. + + + + + A convenience macro for type implementations. + +Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines a final type. + +See G_DEFINE_TYPE_EXTENDED() for an example. + + + the name of the new type, in Camel case + + + the name of the new type, in lower case, with words + separated by `_` (snake case) + + + the #GType of the parent type + + + A convenience macro for #GTypeInterface definitions, which declares -a default vtable initialization function and defines a *_get_type() +a default vtable initialization function and defines a `*_get_type()` function. The macro expects the interface initialization function to have the @@ -3555,64 +3719,66 @@ must write the #GTypeInterface definitions manually. The name of the new type, in Camel case. - The name of the new type, in lowercase, with words separated by '_'. + The name of the new type, in lowercase, with words separated by `_`. - The #GType of the prerequisite type for the interface, or 0 -(%G_TYPE_INVALID) for no prerequisite type. + The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID +for no prerequisite type. - A convenience macro for #GTypeInterface definitions. Similar to -G_DEFINE_INTERFACE(), but allows you to insert custom code into the -*_get_type() function, e.g. additional interface implementations -via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See -G_DEFINE_TYPE_EXTENDED() for a similar example using + A convenience macro for #GTypeInterface definitions. + +Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code +into the `*_get_type()` function, e.g. additional interface implementations +via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. + +See G_DEFINE_TYPE_EXTENDED() for a similar example using G_DEFINE_TYPE_WITH_CODE(). The name of the new type, in Camel case. - The name of the new type, in lowercase, with words separated by '_'. + The name of the new type, in lowercase, with words separated by `_`. - The #GType of the prerequisite type for the interface, or 0 -(%G_TYPE_INVALID) for no prerequisite type. + The #GType of the prerequisite type for the interface, or %G_TYPE_INVALID +for no prerequisite type. - Custom code that gets inserted in the *_get_type() function. + Custom code that gets inserted in the `*_get_type()` function. A convenience macro for pointer type implementations, which defines a -type_name_get_type() function registering the pointer type. +`type_name_get_type()` function registering the pointer type. The name of the new type, in Camel case The name of the new type, in lowercase, with words - separated by '_' + separated by `_` A convenience macro for pointer type implementations. Similar to G_DEFINE_POINTER_TYPE(), but allows to insert -custom code into the type_name_get_type() function. +custom code into the `type_name_get_type()` function. The name of the new type, in Camel case The name of the new type, in lowercase, with words - separated by '_' + separated by `_` - Custom code that gets inserted in the *_get_type() function + Custom code that gets inserted in the `*_get_type()` function @@ -3620,7 +3786,7 @@ custom code into the type_name_get_type() function. A convenience macro for type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these) and a static variable named `t_n_parent_class` -pointing to the parent class. Furthermore, it defines a *_get_type() function. +pointing to the parent class. Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED() for an example. @@ -3628,7 +3794,7 @@ See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in lowercase, with words - separated by '_'. + separated by `_`. The #GType of the parent type. @@ -3648,7 +3814,9 @@ G_DEFINE_TYPE_EXTENDED (GtkGadget, G_IMPLEMENT_INTERFACE (TYPE_GIZMO, gtk_gadget_gizmo_init)); ]| + expands to + |[<!-- language="C" --> static void gtk_gadget_init (GtkGadget *self); static void gtk_gadget_class_init (GtkGadgetClass *klass); @@ -3669,8 +3837,8 @@ static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self) GType gtk_gadget_get_type (void) { - static volatile gsize g_define_type_id__volatile = 0; - if (g_once_init_enter (&g_define_type_id__volatile)) + static gsize static_g_define_type_id = 0; + if (g_once_init_enter (&static_g_define_type_id)) { GType g_define_type_id = g_type_register_static_simple (GTK_TYPE_WIDGET, @@ -3690,11 +3858,12 @@ gtk_gadget_get_type (void) }; g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); } - g_once_init_leave (&g_define_type_id__volatile, g_define_type_id); + g_once_init_leave (&static_g_define_type_id, g_define_type_id); } - return g_define_type_id__volatile; + return static_g_define_type_id; } ]| + The only pieces which have to be manually provided are the definitions of the instance and class structure and the definitions of the instance and class init functions. @@ -3704,7 +3873,7 @@ class init functions. The name of the new type, in lowercase, with words - separated by '_'. + separated by `_`. The #GType of the parent type. @@ -3713,27 +3882,28 @@ class init functions. #GTypeFlags to pass to g_type_register_static() - Custom code that gets inserted in the *_get_type() function. + Custom code that gets inserted in the `*_get_type()` function. A convenience macro for type implementations. + Similar to G_DEFINE_TYPE(), but allows you to insert custom code into the -*_get_type() function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). +`*_get_type()` function, e.g. interface implementations via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. - The name of the new type in lowercase, with words separated by '_'. + The name of the new type in lowercase, with words separated by `_`. The #GType of the parent type. - Custom code that gets inserted in the *_get_type() function. + Custom code that gets inserted in the `*_get_type()` function. @@ -3742,11 +3912,12 @@ See G_DEFINE_TYPE_EXTENDED() for an example. initialization function, an instance initialization function (see #GTypeInfo for information about these), a static variable named `t_n_parent_class` pointing to the parent class, and adds private instance data to the type. -Furthermore, it defines a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() + +Furthermore, it defines a `*_get_type()` function. See G_DEFINE_TYPE_EXTENDED() for an example. Note that private structs added with this macros must have a struct -name of the form @TN Private. +name of the form `TN ## Private`. The private instance data can be retrieved using the automatically generated getter function `t_n_get_instance_private()`. @@ -3758,7 +3929,7 @@ See also: G_ADD_PRIVATE() The name of the new type, in lowercase, with words - separated by '_'. + separated by `_`. The #GType of the parent type. @@ -3896,7 +4067,7 @@ nickname. of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). See G_DEFINE_TYPE_EXTENDED() for an example. -Note that this macro can only be used together with the G_DEFINE_TYPE_* +Note that this macro can only be used together with the `G_DEFINE_TYPE_*` macros, since it depends on variable names from those macros. @@ -3909,8 +4080,9 @@ macros, since it depends on variable names from those macros. A convenience macro to ease interface addition in the @_C_ section -of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_DEFINE_DYNAMIC_TYPE_EXTENDED() -for an example. +of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). + +See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. Note that this macro can only be used together with the G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable @@ -3926,7 +4098,9 @@ names from that macro. Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) -pointer. Depending on the current debugging level, this function may invoke +pointer. + +Depending on the current debugging level, this function may invoke certain runtime checks to identify invalid casts. @@ -4245,14 +4419,15 @@ or derived. - All the fields in the GInitiallyUnowned structure -are private to the #GInitiallyUnowned implementation and should never be -accessed directly. + A type for objects that have an initially floating reference. + +All the fields in the `GInitiallyUnowned` structure are private to the +implementation and should never be accessed directly. - + @@ -4410,8 +4585,10 @@ accessed directly. A callback function used by the type system to initialize a new -instance of a type. This function initializes all instance members and -allocates any resources required by it. +instance of a type. + +This function initializes all instance members and allocates any resources +required by it. Initialization of a derived instance involves calling all its parent types instance initializers, so the class member of the instance @@ -4437,6 +4614,7 @@ zeros before this function is called. A callback function used by the type system to finalize an interface. + This function should destroy any internal data and release any resources allocated by the corresponding GInterfaceInitFunc() function. @@ -4471,8 +4649,10 @@ used specifically for managing interface types. A callback function used by the type system to initialize a new -interface. This function should initialize all internal data and -allocate any resources required by the interface. +interface. + +This function should initialize all internal data and* allocate any +resources required by the interface. The members of @iface_data are guaranteed to have been filled with zeros before this function is called. @@ -4492,6 +4672,7 @@ zeros before this function is called. Casts a #GObject or derived pointer into a (GObject*) pointer. + Depending on the current debugging level, this function may invoke certain runtime checks to identify invalid casts. @@ -4576,8 +4757,10 @@ properties in set_property() and get_property() implementations. - All the fields in the GObject structure are private -to the #GObject implementation and should never be accessed directly. + The base object type. + +All the fields in the `GObject` structure are private to the implementation +and should never be accessed directly. Creates a new instance of a #GObject subtype and sets its properties. @@ -4990,10 +5173,12 @@ thread. Use #GWeakRef if thread-safety is required. Creates a binding between @source_property on @source and @target_property -on @target. Whenever the @source_property is changed the @target_property is +on @target. + +Whenever the @source_property is changed the @target_property is updated using the same value. For instance: -|[ +|[<!-- language="C" --> g_object_bind_property (action, "active", widget, "sensitive", 0); ]| @@ -5683,7 +5868,8 @@ reference count of the object is decreased by one. - data to pass to @notify + data to pass to @notify, or %NULL to + match any toggle refs with the @notify argument. @@ -6102,6 +6288,53 @@ g_object_set_qdata_full(). + + If @object is floating, sink it. Otherwise, do nothing. + +In other words, this function will convert a floating reference (if +present) into a full reference. + +Typically you want to use g_object_ref_sink() in order to +automatically do the correct thing with respect to floating or +non-floating references, but there is one specific scenario where +this function is helpful. + +The situation where this function is helpful is when creating an API +that allows the user to provide a callback function that returns a +GObject. We certainly want to allow the user the flexibility to +return a non-floating reference from this callback (for the case +where the object that is being returned already exists). + +At the same time, the API style of some popular GObject-based +libraries (such as Gtk) make it likely that for newly-created GObject +instances, the user can be saved some typing if they are allowed to +return a floating reference. + +Using this function on the return value of the user's callback allows +the user to do whichever is more convenient for them. The caller will +alway receives exactly one full reference to the value: either the +one that was returned in the first place, or a floating reference +that has been converted to a full reference. + +This function has an odd interaction when combined with +g_object_ref_sink() running at the same time in another thread on +the same #GObject instance. If g_object_ref_sink() runs first then +the result will be that the floating reference is converted to a hard +reference. If g_object_take_ref() runs first then the result will be +that the floating reference is converted to a hard reference and an +additional reference on top of that one is added. It is best to avoid +this situation. + + @object + + + + + a #GObject + + + + Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on @object @@ -6217,7 +6450,7 @@ Use #GWeakRef if thread-safety is required. - + @@ -6238,11 +6471,13 @@ and common practice is to do that only when the value has actually changed. This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this: + |[<!-- language="C" --> g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view) ]| + It is important to note that you must use [canonical parameter names][canonical-parameter-names] as detail strings for the notify signal. @@ -6619,9 +6854,8 @@ g_param_spec_get_redirect_target(). - The GObjectConstructParam struct is an auxiliary -structure used to hand #GParamSpec/#GValue pairs to the @constructor of -a #GObjectClass. + The GObjectConstructParam struct is an auxiliary structure used to hand +#GParamSpec/#GValue pairs to the @constructor of a #GObjectClass. the #GParamSpec of the construct parameter @@ -6946,7 +7180,7 @@ Since 2.13.0 Evaluates to the @field_name inside the @inst private data structure for @TypeName. -Note that this macro can only be used together with the G_DEFINE_TYPE_* +Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. @@ -6968,7 +7202,7 @@ those macros. Evaluates to a pointer to the @field_name inside the @inst private data structure for @TypeName. -Note that this macro can only be used together with the G_DEFINE_TYPE_* +Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. @@ -6987,7 +7221,7 @@ those macros. Evaluates to the offset of the @field inside the instance private data structure for @TypeName. -Note that this macro can only be used together with the G_DEFINE_TYPE_* +Note that this macro can only be used together with the `G_DEFINE_TYPE_*` and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. @@ -7001,7 +7235,9 @@ those macros. Through the #GParamFlags flag values, certain aspects of parameters -can be configured. See also #G_PARAM_STATIC_STRINGS. +can be configured. + +See also: %G_PARAM_STATIC_STRINGS the parameter is readable @@ -7723,11 +7959,14 @@ properties. - This is a type of #GParamSpec type that simply redirects operations to -another paramspec. All operations other than getting or -setting the value are redirected, including accessing the nick and -blurb, validating a value, and so forth. See -g_param_spec_get_redirect_target() for retrieving the overridden + A #GParamSpec derived structure that redirects operations to +other types of #GParamSpec. + +All operations other than getting or setting the value are redirected, +including accessing the nick and blurb, validating a value, and so +forth. + +See g_param_spec_get_redirect_target() for retrieving the overridden property. #GParamSpecOverride is used in implementing g_object_class_override_property(), and will not be directly useful unless you are implementing a new base type similar to GObject. @@ -7755,9 +7994,10 @@ properties. A #GParamSpecPool maintains a collection of #GParamSpecs which can be -quickly accessed by owner and name. The implementation of the #GObject property -system uses such a pool to store the #GParamSpecs of the properties all object -types. +quickly accessed by owner and name. + +The implementation of the #GObject property system uses such a pool to +store the #GParamSpecs of the properties all object types. Inserts a #GParamSpec in the pool. @@ -7924,6 +8164,7 @@ properties. This structure is used to provide the type system with the information required to initialize and destruct (finalize) a parameter's class and instances thereof. + The initialized structure is passed to the g_param_type_register_static() The type system will perform a deep copy of this structure, so its memory does not need to be persistent across invocation of @@ -8165,14 +8406,19 @@ to hand parameter name/value pairs to g_object_newv(). The signal accumulator is a special callback function that can be used to collect return values of the various callbacks that are called -during a signal emission. The signal accumulator is specified at signal -creation time, if it is left %NULL, no accumulation of callback return -values is performed. The return value of signal emissions is then the -value returned by the last callback. +during a signal emission. + +The signal accumulator is specified at signal creation time, if it is +left %NULL, no accumulation of callback return values is performed. +The return value of signal emissions is then the value returned by the +last callback. The accumulator function returns whether the signal emission - should be aborted. Returning %FALSE means to abort the - current emission and %TRUE is returned for continuation. + should be aborted. Returning %TRUE will continue with + the signal emission. Returning %FALSE will abort the current emission. + Since 2.62, returning %FALSE will skip to the CLEANUP stage. In this case, + emission will occur as normal in the CLEANUP stage and the handler's + return value will be accumulated. @@ -8196,9 +8442,10 @@ value returned by the last callback. - A simple function pointer to get invoked when the signal is emitted. This -allows you to tie a hook to the signal type, so that it will trap all -emissions of that signal, from any object. + A simple function pointer to get invoked when the signal is emitted. + +Emission hooks allow you to tie a hook to the signal type, so that it will +trap all emissions of that signal, from any object. You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. @@ -8230,9 +8477,7 @@ You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. - The signal flags are used to specify a signal's behaviour, the overall -signal description outlines how especially the RUN flags control the -stages of a signal emission. + The signal flags are used to specify a signal's behaviour. Invoke the object method handler in the first emission stage. @@ -8271,6 +8516,11 @@ stages of a signal emission. in a future version. A warning will be generated if it is connected while running with G_ENABLE_DIAGNOSTIC=1. Since 2.32. + + Only used in #GSignalAccumulator accumulator + functions for the #GSignalInvocationHint::run_type field to mark the first + call to the accumulator function for a signal emission. Since 2.68. + The #GSignalInvocationHint structure is used to pass on additional information @@ -8286,7 +8536,9 @@ to callbacks during a signal emission. The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, - %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. + %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP and %G_SIGNAL_ACCUMULATOR_FIRST_RUN. + %G_SIGNAL_ACCUMULATOR_FIRST_RUN is only set for the first run of the accumulator + function for a signal emission. @@ -8314,8 +8566,9 @@ match signals by. - A structure holding in-depth information for a specific signal. It is -filled in by the g_signal_query() function. + A structure holding in-depth information for a specific signal. + +See also: g_signal_query() The signal id of the signal being queried, or 0 if the signal to be queried was unknown. @@ -8473,6 +8726,7 @@ This macro should only be used in type implementations. Gets the private class structure for a particular type. + The private structure must have been registered in the get_type() function with g_type_add_class_private(). @@ -8525,6 +8779,7 @@ This macro should only be used in type implementations. The fundamental type which is the ancestor of @type. + Fundamental types are types that serve as ultimate bases for the derived types, thus they are the roots of distinct inheritance hierarchies. @@ -8588,6 +8843,7 @@ This macro should only be used in type implementations. Gets the private structure for a particular type. + The private structure must have been registered in the class_init function with g_type_class_add_private(). @@ -8666,6 +8922,15 @@ types). + + Checks if @type is a final type. A final type cannot be derived any +further. + + + a #GType value + + + Checks whether @type "is a" %G_TYPE_FLAGS. @@ -8693,6 +8958,7 @@ process of creating an instance (object) of this type. Checks if @type is an interface type. + An interface type provides a pure API, the implementation of which is provided by another type (which is then said to conform to the interface). GLib interfaces are somewhat analogous to Java @@ -8723,6 +8989,7 @@ g_type_interface_add_prerequisite() for an alternative). Checks whether the passed in type ID can be used for g_value_init(). + That is, this macro checks whether this type provides an implementation of the #GTypeValueTable functions required for a type to create a #GValue of. @@ -8751,6 +9018,7 @@ an abstract base type for derived value types. Get the type ID for the fundamental type number @x. + Use g_type_fundamental_next() instead of this macro to create new fundamental types. @@ -8820,7 +9088,9 @@ type id with G_TYPE_MAKE_FUNDAMENTAL(). A callback function used for notification when the state -of a toggle reference changes. See g_object_add_toggle_ref(). +of a toggle reference changes. + +See also: g_object_add_toggle_ref() @@ -9080,10 +9350,11 @@ exist already. A callback function which is called when the reference count of a class -drops to zero. It may use g_type_class_ref() to prevent the class from -being freed. You should not call g_type_class_unref() from a -#GTypeClassCacheFunc function to prevent infinite recursion, use -g_type_class_unref_uncached() instead. +drops to zero. + +It may use g_type_class_ref() to prevent the class from being freed. You +should not call g_type_class_unref() from a #GTypeClassCacheFunc function +to prevent infinite recursion, use g_type_class_unref_uncached() instead. The functions have to check the class id passed in to figure whether they actually want to cache the class of this type, since all @@ -9139,6 +9410,10 @@ environment variable. that introduces a value table, but can't be used for g_value_init() + + Indicates a final type. A final type is a non-derivable + leaf node in a deep derivable type hierarchy tree. Since: 2.70 + Bit masks used to check or determine specific characteristics of a @@ -9147,7 +9422,7 @@ fundamental type. Indicates a classed type - Indicates an instantiable type (implies classed) + Indicates an instantiatable type (implies classed) Indicates a flat derivable type @@ -9310,6 +9585,24 @@ not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + + Returns the most specific instantiatable prerequisite of an +interface type. If the interface type has no instantiatable +prerequisite, %G_TYPE_INVALID is returned. + +See g_type_interface_add_prerequisite() for more information +about prerequisites. + + the instantiatable prerequisite type or %G_TYPE_INVALID if none + + + + + an interface type + + + + Returns the #GTypeInterface structure of an interface to which the passed in class conforms. @@ -9355,6 +9648,7 @@ passed in class conforms. A callback called after an interface vtable is initialized. + See g_type_add_interface_check(). @@ -9373,16 +9667,20 @@ See g_type_add_interface_check(). #GTypeModule provides a simple implementation of the #GTypePlugin -interface. The model of #GTypeModule is a dynamically loaded module -which implements some number of types and interface implementations. +interface. + +The model of #GTypeModule is a dynamically loaded module which +implements some number of types and interface implementations. + When the module is loaded, it registers its types and interfaces using g_type_module_register_type() and g_type_module_add_interface(). As long as any instances of these types and interface implementations are in use, the module is kept loaded. When the types and interfaces are gone, the module may be unloaded. If the types and interfaces become used again, the module will be reloaded. Note that the last -unref cannot happen in module code, since that would lead to the -caller's code being unloaded before g_object_unref() returns to it. +reference cannot be released from within the module code, since that +would lead to the caller's code being unloaded before g_object_unref() +returns to it. Keeping track of whether the module should be loaded or not is done by using a use count - it starts at zero, and whenever it is greater than @@ -9690,9 +9988,10 @@ the @load and @unload functions in #GTypeModuleClass must be implemented. - The GObject type system supports dynamic loading of types. -The #GTypePlugin interface is used to handle the lifecycle -of dynamically loaded types. It goes as follows: + An interface that handles the lifecycle of dynamically loaded types. + +The GObject type system supports dynamic loading of types. +It goes as follows: 1. The type is initially introduced (usually upon loading the module the first time, or by your main application that knows what modules @@ -9857,7 +10156,7 @@ the lifecycle of dynamically loaded types. - the #GType of an instantiable type to which the interface + the #GType of an instantiatable type to which the interface is added @@ -9922,7 +10221,8 @@ to increase the use count of @plugin. A structure holding information for a specific type. -It is filled in by the g_type_query() function. + +See also: g_type_query() the #GType value of the type @@ -10334,10 +10634,12 @@ marshalling the signal argument into GValues. An opaque structure used to hold different types of values. + The data within the structure has protected scope: it is accessible only to functions within a #GTypeValueTable structure, or implementations of the g_value_*() API. That is, code portions which implement new fundamental types. + #GValue users cannot make any assumptions about how data is stored within the 2 element @data union, and the @g_type member should only be accessed through the G_VALUE_TYPE() macro. @@ -11138,6 +11440,7 @@ the #GValue still exists). Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + The boxed value is assumed to be static, and is thus not duplicated when setting the #GValue. @@ -11176,7 +11479,7 @@ is more appropriate. - Set the contents of a %G_TYPE_STRING #GValue to @v_string. + Set the contents of a %G_TYPE_STRING #GValue to a copy of @v_string. @@ -11716,9 +12019,11 @@ g_value_register_transform_func(). A #GWeakNotify function can be added to an object as a callback that gets -triggered when the object is finalized. Since the object is already being -finalized when the #GWeakNotify is called, there's not much you could do -with the object, apart from e.g. using its address as hash-index or the like. +triggered when the object is finalized. + +Since the object is already being disposed when the #GWeakNotify is called, +there's not much you could do with the object, apart from e.g. using its +address as hash-index or the like. @@ -11728,17 +12033,18 @@ with the object, apart from e.g. using its address as hash-index or the like. - the object being finalized + the object being disposed - A structure containing a weak reference to a #GObject. It can either -be empty (i.e. point to %NULL), or point to an object for as long as -at least one "strong" reference to that object exists. Before the -object's #GObjectClass.dispose method is called, every #GWeakRef -associated with becomes empty (i.e. points to %NULL). + A structure containing a weak reference to a #GObject. + +A `GWeakRef` can either be empty (i.e. point to %NULL), or point to an +object for as long as at least one "strong" reference to that object +exists. Before the object's #GObjectClass.dispose method is called, +every #GWeakRef associated with becomes empty (i.e. points to %NULL). Like #GValue, #GWeakRef can be statically allocated, stack- or heap-allocated, or embedded in larger structures. @@ -11924,8 +12230,14 @@ This macro should only be used in regression tests. This function creates a new %G_TYPE_BOXED derived type id for a new -boxed type with name @name. Boxed type handling functions have to be -provided to copy and free opaque boxed structures of this type. +boxed type with name @name. + +Boxed type handling functions have to be provided to copy and free +opaque boxed structures of this type. + +For the general case, it is recommended to use #G_DEFINE_BOXED_TYPE +instead of calling g_boxed_type_register_static() directly. The macro +will create the appropriate `*_get_type()` function for the boxed type. New %G_TYPE_BOXED derived type id for @name. @@ -13187,10 +13499,11 @@ may change in the future. - #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only -thing the type system needs to know about the structures is how to copy them -(a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that -they are treated as opaque chunks of memory. + #GBoxed is a generic wrapper mechanism for arbitrary C structures. + +The only thing the type system needs to know about the structures is how to +copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc); +beyond that, they are treated as opaque chunks of memory. Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-#GObject @@ -13209,11 +13522,16 @@ g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref(). The #GValue structure is basically a variable container that consists of a type identifier and a specific value of that type. + The type identifier within a #GValue structure always determines the type of the associated value. + To create an undefined #GValue structure, simply create a zero-filled #GValue structure. To initialize the #GValue, use the g_value_init() -function. A #GValue cannot be used until it is initialized. +function. A #GValue cannot be used until it is initialized. Before +destruction you must always use g_value_unset() to make sure allocated +memory is freed. + The basic type operations (such as freeing and copying) are determined by the #GTypeValueTable associated with the type ID stored in the #GValue. Other #GValue operations (such as converting values between types) are @@ -13275,10 +13593,38 @@ main (int argc, g_printf ("%s\n", g_value_get_string (&b)); return 0; } +]| + +See also [gobject-Standard-Parameter-and-Value-Types] for more information on +validation of #GValue. + +For letting a #GValue own (and memory manage) arbitrary types or pointers, +they need to become a [boxed type][gboxed]. The example below shows how +the pointer `mystruct` of type `MyStruct` is used as a [boxed type][gboxed]. + +|[<!-- language="C" --> +typedef struct { ... } MyStruct; +G_DEFINE_BOXED_TYPE (MyStruct, my_struct, my_struct_copy, my_struct_free) + +// These two lines normally go in a public header. By GObject convention, +// the naming scheme is NAMESPACE_TYPE_NAME: +#define MY_TYPE_STRUCT (my_struct_get_type ()) +GType my_struct_get_type (void); + +void +foo () +{ + GValue *value = g_new0 (GValue, 1); + g_value_init (value, MY_TYPE_STRUCT); + g_value_set_boxed (value, mystruct); + // [... your code ....] + g_value_unset (value); + g_value_free (value); +} ]| - The GType API is the foundation of the GObject system. It provides the + The GType API is the foundation of the GObject system. It provides the facilities for registering and managing all fundamental data types, user-defined object and interface types. @@ -13349,15 +13695,18 @@ as a "floating" reference. This means that it is not specifically claimed to be "owned" by any code portion. The main motivation for providing floating references is C convenience. In particular, it allows code to be written as: + |[<!-- language="C" --> container = create_container (); container_add_child (container, create_child()); ]| + If container_add_child() calls g_object_ref_sink() on the passed-in child, no reference of the newly created child is leaked. Without floating references, container_add_child() can only g_object_ref() the new child, so to implement this code without reference leaks, it would have to be written as: + |[<!-- language="C" --> Child *child; container = create_container (); @@ -13365,6 +13714,7 @@ child = create_child (); container_add_child (container, child); g_object_unref (child); ]| + The floating reference can be converted into an ordinary reference by calling g_object_ref_sink(). For already sunken objects (objects that don't have a floating reference anymore), g_object_ref_sink() is equivalent @@ -14222,10 +14572,12 @@ See g_param_spec_internal() for details on property names. - Registers @name as the name of a new static type derived from -#G_TYPE_PARAM. The type system uses the information contained in -the #GParamSpecTypeInfo structure pointed to by @info to manage the -#GParamSpec type and its instances. + Registers @name as the name of a new static type derived +from #G_TYPE_PARAM. + +The type system uses the information contained in the #GParamSpecTypeInfo +structure pointed to by @info to manage the #GParamSpec type and its +instances. The new type identifier. @@ -14319,7 +14671,9 @@ operate on #GValue containers. Parameter names need to start with a letter (a-z or A-Z). Subsequent characters can be letters, numbers or a '-'. -All other characters are replaced by a '-' during construction. +All other characters are replaced by a '-' during construction. + +See also #GValue for more information. Ensures that the contents of @value comply with the specifications @@ -14381,12 +14735,13 @@ pointer type with name @name. - Updates a #GObject pointer to refer to @new_object. It increments the -reference count of @new_object (if non-%NULL), decrements the reference -count of the current value of @object_ptr (if non-%NULL), and assigns -@new_object to @object_ptr. The assignment is not atomic. + Updates a #GObject pointer to refer to @new_object. -@object_ptr must not be %NULL. +It increments the reference count of @new_object (if non-%NULL), decrements +the reference count of the current value of @object_ptr (if non-%NULL), and +assigns @new_object to @object_ptr. The assignment is not atomic. + +@object_ptr must not be %NULL, but can point to a %NULL value. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary @@ -14411,18 +14766,20 @@ One convenient usage of this function is in implementing property setters: a pointer to the new #GObject to - assign to it, or %NULL to clear the pointer + assign to @object_ptr, or %NULL to clear the pointer - Updates a pointer to weakly refer to @new_object. It assigns @new_object -to @weak_pointer_location and ensures that @weak_pointer_location will -automatically be set to %NULL if @new_object gets destroyed. The assignment -is not atomic. The weak reference is not thread-safe, see -g_object_add_weak_pointer() for details. + Updates a pointer to weakly refer to @new_object. -@weak_pointer_location must not be %NULL. +It assigns @new_object to @weak_pointer_location and ensures +that @weak_pointer_location will automatically be set to %NULL +if @new_object gets destroyed. The assignment is not atomic. +The weak reference is not thread-safe, see g_object_add_weak_pointer() +for details. + +The @weak_pointer_location argument must not be %NULL. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary @@ -14854,7 +15211,8 @@ if no handlers are connected, in contrast to g_signal_emitv(). parameters to be passed to the signal, followed by a location for the return value. If the return type of the signal - is #G_TYPE_NONE, the return value location can be omitted. + is %G_TYPE_NONE, the return value location can be omitted. The + number of parameters to pass to this function is defined when creating the signal. @@ -16659,6 +17017,24 @@ not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + + Returns the most specific instantiatable prerequisite of an +interface type. If the interface type has no instantiatable +prerequisite, %G_TYPE_INVALID is returned. + +See g_type_interface_add_prerequisite() for more information +about prerequisites. + + the instantiatable prerequisite type or %G_TYPE_INVALID if none + + + + + an interface type + + + + Returns the #GTypeInterface structure of an interface to which the passed in class conforms. diff --git a/Gdk-3.0.gir b/Gdk-3.0.gir index 73b1ece..76f0da4 100644 --- a/Gdk-3.0.gir +++ b/Gdk-3.0.gir @@ -593,8 +593,8 @@ To make the cursor invisible, use %GDK_BLANK_CURSOR. Creates a new cursor from the set of builtin cursors. - - a new #GdkCursor + + a new #GdkCursor, or %NULL on failure @@ -14770,7 +14770,7 @@ See gdk_keymap_get_caps_lock_state(). - + @@ -17666,7 +17666,7 @@ or any other error occurs. the format for the new surface - + width of the new surface @@ -21594,6 +21594,17 @@ context @cr. + + [Cairo](http://cairographics.org) is a graphics +library that supports vector graphics and image compositing that +can be used with GDK. GTK+ does all of its drawing using cairo. + +GDK does not wrap the cairo API, instead it allows to create cairo +contexts which can be used to draw on #GdkWindows. Additional +functions allow use #GdkRectangles with cairo and to use #GdkColors, +#GdkRGBAs, #GdkPixbufs and #GdkWindows as sources for drawing +operations. + Adds the given rectangle to the current path of @cr. @@ -21783,6 +21794,29 @@ and “\#ffffffffffff”). + + A #GdkColor represents a color. + +When working with cairo, it is often more convenient +to use a #GdkRGBA instead, and #GdkColor has been +deprecated in favor of #GdkRGBA. + + + These functions are used to create and destroy cursors. +There is a number of standard cursors, but it is also +possible to construct new cursors from pixbufs. There +may be limitations as to what kinds of cursors can be +constructed on a given display, see +gdk_display_supports_cursor_alpha(), +gdk_display_supports_cursor_color(), +gdk_display_get_default_cursor_size() and +gdk_display_get_maximal_cursor_size(). + +Cursors by themselves are not very interesting, they must be be +bound to a window for users to see them. This is done with +gdk_window_set_cursor() or by setting the cursor member of the +#GdkWindowAttr passed to gdk_window_new(). + Disables multidevice support in GDK. This call must happen prior to gdk_display_open(), gtk_init(), gtk_init_with_args() or @@ -21796,6 +21830,17 @@ any way and doesn’t observe the presence of XInput 2. + + These functions provide a low level interface for drag and drop. +The X backend of GDK supports both the Xdnd and Motif drag and drop +protocols transparently, the Win32 backend supports the WM_DROPFILES +protocol. + +GTK+ provides a higher level abstraction based on top of these functions, +and so they are not normally needed in GTK+ applications. +See the [Drag and Drop][gtk3-Drag-and-Drop] section of +the GTK+ documentation for more information. + Aborts a drag without dropping. @@ -22267,6 +22312,21 @@ motion events from a %GDK_MOTION_NOTIFY event usually works like this: + + The event structures contain data specific to each type of event in GDK. + +> A common mistake is to forget to set the event mask of a widget so that +> the required events are received. See gtk_widget_set_events(). + + + This section describes functions dealing with events from the window +system. + +In GTK+ applications the events are handled automatically in +gtk_main_do_event() and passed on to the appropriate widgets, so these +functions are rarely needed. Though some of the fields in the +[Event Structures][gdk3-Event-Structures] are useful. + If both events contain X/Y information, this function will return %TRUE and return in @angle the relative angle from @event1 to @event2. The rotation @@ -22354,6 +22414,26 @@ This is rarely needed by applications. + + The functions in this section are intended to be used in test programs. +They allow to simulate some user input. + + + This section describes the GDK initialization functions and miscellaneous +utility functions, as well as deprecation facilities. + +The GDK and GTK+ headers annotate deprecated APIs in a way that produces +compiler warnings if these deprecated APIs are used. The warnings +can be turned off by defining the macro %GDK_DISABLE_DEPRECATION_WARNINGS +before including the glib.h header. + +GDK and GTK+ also provide support for building applications against +defined subsets of deprecated or new APIs. Define the macro +%GDK_VERSION_MIN_REQUIRED to specify up to what version +you want to receive warnings about deprecated APIs. Define the +macro %GDK_VERSION_MAX_ALLOWED to specify the newest version +whose API you want to use. + Obtains the root window (parent all other windows are inside) for the default display and screen. @@ -22507,6 +22587,70 @@ application. + + Key values are the codes which are sent whenever a key is pressed or released. +They appear in the #GdkEventKey.keyval field of the +#GdkEventKey structure, which is passed to signal handlers for the +#GtkWidget::key-press-event and #GtkWidget::key-release-event signals. +The complete list of key values can be found in the +`gdk/gdkkeysyms.h` header file. + +Key values are regularly updated from the upstream X.org X11 implementation, +so new values are added regularly. They will be prefixed with GDK_KEY_ rather +than XF86XK_ or XK_ (for older symbols). + +Key values can be converted into a string representation using +gdk_keyval_name(). The reverse function, converting a string to a key value, +is provided by gdk_keyval_from_name(). + +The case of key values can be determined using gdk_keyval_is_upper() and +gdk_keyval_is_lower(). Key values can be converted to upper or lower case +using gdk_keyval_to_upper() and gdk_keyval_to_lower(). + +When it makes sense, key values can be converted to and from +Unicode characters with gdk_keyval_to_unicode() and gdk_unicode_to_keyval(). + +# Groups # {#key-group-explanation} + +One #GdkKeymap object exists for each user display. gdk_keymap_get_default() +returns the #GdkKeymap for the default display; to obtain keymaps for other +displays, use gdk_keymap_get_for_display(). A keymap +is a mapping from #GdkKeymapKey to key values. You can think of a #GdkKeymapKey +as a representation of a symbol printed on a physical keyboard key. That is, it +contains three pieces of information. First, it contains the hardware keycode; +this is an identifying number for a physical key. Second, it contains the +“level” of the key. The level indicates which symbol on the +key will be used, in a vertical direction. So on a standard US keyboard, the key +with the number “1“ on it also has the exclamation point (”!”) character on +it. The level indicates whether to use the “1” or the “!” symbol. The letter +keys are considered to have a lowercase letter at level 0, and an uppercase +letter at level 1, though only the uppercase letter is printed. Third, the +#GdkKeymapKey contains a group; groups are not used on standard US keyboards, +but are used in many other countries. On a keyboard with groups, there can be 3 +or 4 symbols printed on a single key. The group indicates movement in a +horizontal direction. Usually groups are used for two different languages. In +group 0, a key might have two English characters, and in group 1 it might have +two Hebrew characters. The Hebrew characters will be printed on the key next to +the English characters. + +In order to use a keymap to interpret a key event, it’s necessary to first +convert the keyboard state into an effective group and level. This is done via a +set of rules that varies widely according to type of keyboard and user +configuration. The function gdk_keymap_translate_keyboard_state() accepts a +keyboard state -- consisting of hardware keycode pressed, active modifiers, and +active group -- applies the appropriate rules, and returns the group/level to be +used to index the keymap, along with the modifiers which did not affect the +group and level. i.e. it returns “unconsumed modifiers.” The keyboard group may +differ from the effective group used for keymap lookups because some keys don't +have multiple groups - e.g. the Enter key is always in group 0 regardless of +keyboard state. + +Note that gdk_keymap_translate_keyboard_state() also returns the keyval, i.e. it +goes ahead and performs the keymap lookup in addition to telling you which +effective group/level values were used for the lookup. #GdkEventKey already +contains this keyval, however, so you don’t normally need to call +gdk_keymap_translate_keyboard_state() just to get the keyval. + Obtains the upper- and lower-case versions of the keyval @symbol. Examples of keyvals are #GDK_KEY_a, #GDK_KEY_Enter, #GDK_KEY_F1, etc. @@ -22805,6 +22949,97 @@ changes to the screen’s font rendering settings. + + Pango is the text layout system used by GDK and GTK+. The functions +and types in this section are used to obtain clip regions for +#PangoLayouts, and to get #PangoContexts that can be used with +GDK. + +Creating a #PangoLayout object is the first step in rendering text, +and requires getting a handle to a #PangoContext. For GTK+ programs, +you’ll usually want to use gtk_widget_get_pango_context(), or +gtk_widget_create_pango_layout(), rather than using the lowlevel +gdk_pango_context_get_for_screen(). Once you have a #PangoLayout, you +can set the text and attributes of it with Pango functions like +pango_layout_set_text() and get its size with pango_layout_get_size(). +(Note that Pango uses a fixed point system internally, so converting +between Pango units and pixels using [PANGO_SCALE][PANGO-SCALE-CAPS] +or the PANGO_PIXELS() macro.) + +Rendering a Pango layout is done most simply with pango_cairo_show_layout(); +you can also draw pieces of the layout with pango_cairo_show_layout_line(). + +## Draw transformed text with Pango and cairo ## {#rotated-example} + +|[<!-- language="C" --> +#define RADIUS 100 +#define N_WORDS 10 +#define FONT "Sans Bold 18" + +PangoContext *context; +PangoLayout *layout; +PangoFontDescription *desc; + +double radius; +int width, height; +int i; + +// Set up a transformation matrix so that the user space coordinates for +// where we are drawing are [-RADIUS, RADIUS], [-RADIUS, RADIUS] +// We first center, then change the scale + +width = gdk_window_get_width (window); +height = gdk_window_get_height (window); +radius = MIN (width, height) / 2.; + +cairo_translate (cr, + radius + (width - 2 * radius) / 2, + radius + (height - 2 * radius) / 2); + cairo_scale (cr, radius / RADIUS, radius / RADIUS); + +// Create a PangoLayout, set the font and text +context = gdk_pango_context_get_for_screen (screen); +layout = pango_layout_new (context); +pango_layout_set_text (layout, "Text", -1); +desc = pango_font_description_from_string (FONT); +pango_layout_set_font_description (layout, desc); +pango_font_description_free (desc); + +// Draw the layout N_WORDS times in a circle +for (i = 0; i < N_WORDS; i++) + { + double red, green, blue; + double angle = 2 * G_PI * i / n_words; + + cairo_save (cr); + + // Gradient from red at angle == 60 to blue at angle == 300 + red = (1 + cos (angle - 60)) / 2; + green = 0; + blue = 1 - red; + + cairo_set_source_rgb (cr, red, green, blue); + cairo_rotate (cr, angle); + + // Inform Pango to re-layout the text with the new transformation matrix + pango_cairo_update_layout (cr, layout); + + pango_layout_get_size (layout, &width, &height); + + cairo_move_to (cr, - width / 2 / PANGO_SCALE, - DEFAULT_TEXT_RADIUS); + pango_cairo_show_layout (cr, layout); + + cairo_restore (cr); + } + +g_object_unref (layout); +g_object_unref (context); +]| + +## Output of the [example][rotated-example] above. + +![](rotated-text.png) + Obtains a clip region which contains the areas where the given ranges of text would be drawn. @x_origin and @y_origin are the top left point @@ -23004,6 +23239,13 @@ instead. + + Pixbufs are client-side images. For details on how to create +and manipulate pixbufs, see the #GdkPixbuf API documentation. + +The functions described here allow to obtain pixbufs from +#GdkWindows and cairo surfaces. + Grabs the pointer (usually a mouse) so that all events are passed to this application until the pointer is ungrabbed with gdk_pointer_ungrab(), or @@ -23108,6 +23350,35 @@ public API and should not be used in application code. + + Each window under X can have any number of associated +“properties” attached to it. +Properties are arbitrary chunks of data identified by +“atom”s. (An “atom” +is a numeric index into a string table on the X server. They are used +to transfer strings efficiently between clients without +having to transfer the entire string.) A property +has an associated type, which is also identified +using an atom. + +A property has an associated “format”, +an integer describing how many bits are in each unit +of data inside the property. It must be 8, 16, or 32. +When data is transferred between the server and client, +if they are of different endianesses it will be byteswapped +as necessary according to the format of the property. +Note that on the client side, properties of format 32 +will be stored with one unit per long, +even if a long integer has more than 32 bits on the platform. +(This decision was apparently made for Xlib to maintain +compatibility with programs that assumed longs were 32 +bits, at the expense of programs that knew better.) + +The functions in this section are used to add, remove +and change properties on windows, to convert atoms +to and from strings and to manipulate some types of +data commonly stored in X window properties. + Changes the contents of a property on a window. @@ -23302,6 +23573,28 @@ The array returned by this function should not be freed. + + GDK provides the #GdkPoint and #GdkRectangle data types for representing pixels +and sets of pixels on the screen. Together with Cairo’s #cairo_region_t data +type, they make up the central types for representing graphical data. + +A #GdkPoint represents an x and y coordinate of a point. + +A #GdkRectangle represents the position and size of a rectangle. +The intersection of two rectangles can be computed with +gdk_rectangle_intersect(). To find the union of two rectangles use +gdk_rectangle_union(). + +#cairo_region_t is usually used for managing clipping of graphical operations. + + + #GdkRGBA is a convenient way to pass rgba colors around. +It’s based on cairo’s way to deal with colors and mirrors its behavior. +All values are in the range from 0.0 to 1.0 inclusive. So the color +(0.0, 0.0, 0.0, 0.0) represents transparent black and +(1.0, 1.0, 1.0, 1.0) is opaque white. Other values will be clamped +to this range when drawing. + Retrieves the contents of a selection in a given form. @@ -23536,6 +23829,37 @@ API instead. + + GDK’s selection functions, based on the [X selection mechanism]( +https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html), +provide a way to transfer arbitrary chunks of +data between programs. A “selection” is a essentially +a named clipboard, identified by a string interned as a #GdkAtom. By +claiming ownership of a selection, an application indicates that it will +be responsible for supplying its contents. The most common selections are +`PRIMARY` and `CLIPBOARD`. + +The contents of a selection can be represented in a number of formats, +called “targets”. Each target is identified by an atom. +A list of all possible targets supported by the selection owner can be +retrieved by requesting the special target `TARGETS`. When +a selection is retrieved, the data is accompanied by a type (an atom), and +a format (an integer, representing the number of bits per item). +See [Properties and Atoms][gdk3-Properties-and-Atoms] +for more information. + +The functions in this section only contain the lowlevel parts of the +selection protocol. A considerably more complicated implementation is needed +on top of this. GTK+ contains such an implementation in the functions in +`gtkselection.h` and programmers should use those functions +instead of the ones presented here. If you plan to implement selection +handling directly on top of the functions here, you should refer to the +[X Inter-Client Communication Conventions Manual (ICCCM)]( +https://www.x.org/releases/X11R7.6/doc/xorg-docs/specs/ICCCM/icccm.html). + +Note that although much of the selection API design is based on that of X, +it will work on other GDK backends too. + Sets a list of backends that GDK should try to use. @@ -23807,6 +24131,59 @@ a list of UTF-8 strings. + + For thread safety, GDK relies on the thread primitives in GLib, +and on the thread-safe GLib main loop. + +GLib is completely thread safe (all global data is automatically +locked), but individual data structure instances are not automatically +locked for performance reasons. So e.g. you must coordinate +accesses to the same #GHashTable from multiple threads. + +GTK+, however, is not thread safe. You should only use GTK+ and GDK +from the thread gtk_init() and gtk_main() were called on. +This is usually referred to as the “main thread”. + +Signals on GTK+ and GDK types, as well as non-signal callbacks, are +emitted in the main thread. + +You can schedule work in the main thread safely from other threads +by using gdk_threads_add_idle() and gdk_threads_add_timeout(): + +|[<!-- language="C" --> +static void +worker_thread (void) +{ + ExpensiveData *expensive_data = do_expensive_computation (); + + gdk_threads_add_idle (got_value, expensive_data); +} + +static gboolean +got_value (gpointer user_data) +{ + ExpensiveData *expensive_data = user_data; + + my_app->expensive_data = expensive_data; + gtk_button_set_sensitive (my_app->button, TRUE); + gtk_button_set_label (my_app->button, expensive_data->result_label); + + return G_SOURCE_REMOVE; +} +]| + +You should use gdk_threads_add_idle() and gdk_threads_add_timeout() +instead of g_idle_add() and g_timeout_add() since libraries not under +your control might be using the deprecated GDK locking mechanism. +If you are sure that none of the code in your application and libraries +use the deprecated gdk_threads_enter() or gdk_threads_leave() methods, +then you can safely use g_idle_add() and g_timeout_add(). + +For more information on this "worker thread" pattern, you should +also look at #GTask, which gives you high-level tools to perform +expensive tasks from worker threads, and will handle thread +management for you. + A wrapper for the common usage of gdk_threads_add_idle_full() assigning the default priority, #G_PRIORITY_DEFAULT_IDLE. @@ -24150,5 +24527,64 @@ is not specified; it may be as pseudo-escape sequences + + A #GdkVisual describes a particular video hardware display format. +It includes information about the number of bits used for each color, +the way the bits are translated into an RGB value for display, and +the way the bits are stored in memory. For example, a piece of display +hardware might support 24-bit color, 16-bit color, or 8-bit color; +meaning 24/16/8-bit pixel sizes. For a given pixel size, pixels can +be in different formats; for example the “red” element of an RGB pixel +may be in the top 8 bits of the pixel, or may be in the lower 4 bits. + +There are several standard visuals. The visual returned by +gdk_screen_get_system_visual() is the system’s default visual, and +the visual returned by gdk_screen_get_rgba_visual() should be used for +creating windows with an alpha channel. + +A number of functions are provided for determining the “best” available +visual. For the purposes of making this determination, higher bit depths +are considered better, and for visuals of the same bit depth, +%GDK_VISUAL_PSEUDO_COLOR is preferred at 8bpp, otherwise, the visual +types are ranked in the order of(highest to lowest) +%GDK_VISUAL_DIRECT_COLOR, %GDK_VISUAL_TRUE_COLOR, +%GDK_VISUAL_PSEUDO_COLOR, %GDK_VISUAL_STATIC_COLOR, +%GDK_VISUAL_GRAYSCALE, then %GDK_VISUAL_STATIC_GRAY. + + + A #GdkWindow is a (usually) rectangular region on the screen. +It’s a low-level object, used to implement high-level objects such as +#GtkWidget and #GtkWindow on the GTK+ level. A #GtkWindow is a toplevel +window, the thing a user might think of as a “window” with a titlebar +and so on; a #GtkWindow may contain many #GdkWindows. For example, +each #GtkButton has a #GdkWindow associated with it. + +# Composited Windows # {#COMPOSITED-WINDOWS} + +Normally, the windowing system takes care of rendering the contents +of a child window onto its parent window. This mechanism can be +intercepted by calling gdk_window_set_composited() on the child +window. For a “composited” window it is the +responsibility of the application to render the window contents at +the right spot. + +# Offscreen Windows # {#OFFSCREEN-WINDOWS} + +Offscreen windows are more general than composited windows, since +they allow not only to modify the rendering of the child window onto +its parent, but also to apply coordinate transformations. + +To integrate an offscreen window into a window hierarchy, one has +to call gdk_offscreen_window_set_embedder() and handle a number of +signals. The #GdkWindow::pick-embedded-child signal on the embedder +window is used to select an offscreen child at given coordinates, +and the #GdkWindow::to-embedder and #GdkWindow::from-embedder signals +on the offscreen window are used to translate coordinates between +the embedder and the offscreen window. + +For rendering an offscreen window onto its embedder, the contents +of the offscreen window are available as a surface, via +gdk_offscreen_window_get_surface(). + diff --git a/GdkPixbuf-2.0.gir b/GdkPixbuf-2.0.gir index a8bbf4f..473b7c5 100644 --- a/GdkPixbuf-2.0.gir +++ b/GdkPixbuf-2.0.gir @@ -10,7 +10,9 @@ and/or use gtk-doc annotations. --> This enumeration defines the color spaces that are supported by -the gdk-pixbuf library. Currently only RGB is supported. +the gdk-pixbuf library. + +Currently only RGB is supported. Indicates a red/green/blue additive color space. @@ -70,11 +72,12 @@ the gdk-pixbuf library. Currently only RGB is supported. - This enumeration describes the different interpolation modes that -can be used with the scaling functions. @GDK_INTERP_NEAREST is -the fastest scaling method, but has horrible quality when -scaling down. @GDK_INTERP_BILINEAR is the best choice if you -aren't sure what to choose, it has a good speed/quality balance. + Interpolation modes for scaling functions. + +The `GDK_INTERP_NEAREST` mode is the fastest scaling method, but has +horrible quality when scaling down; `GDK_INTERP_BILINEAR` is the best +choice if you aren't sure what to choose, it has a good speed/quality +balance. **Note**: Cubic filtering is missing from the list; hyperbolic interpolation is just as fast and results in higher quality. @@ -290,9 +293,6 @@ interpolation is just as fast and results in higher quality. - - - @@ -316,7 +316,7 @@ interpolation is just as fast and results in higher quality. "0.8.2" for example. - + Micro version of gdk-pixbuf library, that is the "2" in "0.8.2" for example. @@ -344,27 +344,160 @@ interpolation is just as fast and results in higher quality. - - Contains the full version of the gdk-pixbuf header as a string. + + Contains the full version of GdkPixbuf as a string. + This is the version being compiled against; contrast with -#gdk_pixbuf_version. +`gdk_pixbuf_version`. - This is the main structure in the gdk-pixbuf library. It is -used to represent images. It contains information about the -image's pixel data, its color space, bits per sample, width and -height, and the rowstride (the number of bytes between the start of -one row and the start of the next). + A pixel buffer. + +`GdkPixbuf` contains information about an image's pixel data, +its color space, bits per sample, width and height, and the +rowstride (the number of bytes between the start of one row +and the start of the next). + +## Creating new `GdkPixbuf` + +The most basic way to create a pixbuf is to wrap an existing pixel +buffer with a [class@GdkPixbuf.Pixbuf] instance. You can use the +[`ctor@GdkPixbuf.Pixbuf.new_from_data`] function to do this. + +Every time you create a new `GdkPixbuf` instance for some data, you +will need to specify the destroy notification function that will be +called when the data buffer needs to be freed; this will happen when +a `GdkPixbuf` is finalized by the reference counting functions. If +you have a chunk of static data compiled into your application, you +can pass in `NULL` as the destroy notification function so that the +data will not be freed. + +The [`ctor@GdkPixbuf.Pixbuf.new`] constructor function can be used +as a convenience to create a pixbuf with an empty buffer; this is +equivalent to allocating a data buffer using `malloc()` and then +wrapping it with `gdk_pixbuf_new_from_data()`. The `gdk_pixbuf_new()` +function will compute an optimal rowstride so that rendering can be +performed with an efficient algorithm. + +As a special case, you can use the [`ctor@GdkPixbuf.Pixbuf.new_from_xpm_data`] +function to create a pixbuf from inline XPM image data. + +You can also copy an existing pixbuf with the [method@Pixbuf.copy] +function. This is not the same as just acquiring a reference to +the old pixbuf instance: the copy function will actually duplicate +the pixel data in memory and create a new [class@Pixbuf] instance +for it. + +## Reference counting + +`GdkPixbuf` structures are reference counted. This means that an +application can share a single pixbuf among many parts of the +code. When a piece of the program needs to use a pixbuf, it should +acquire a reference to it by calling `g_object_ref()`; when it no +longer needs the pixbuf, it should release the reference it acquired +by calling `g_object_unref()`. The resources associated with a +`GdkPixbuf` will be freed when its reference count drops to zero. +Newly-created `GdkPixbuf` instances start with a reference count +of one. + +## Image Data + +Image data in a pixbuf is stored in memory in an uncompressed, +packed format. Rows in the image are stored top to bottom, and +in each row pixels are stored from left to right. + +There may be padding at the end of a row. + +The "rowstride" value of a pixbuf, as returned by [`method@GdkPixbuf.Pixbuf.get_rowstride`], +indicates the number of bytes between rows. + +**NOTE**: If you are copying raw pixbuf data with `memcpy()` note that the +last row in the pixbuf may not be as wide as the full rowstride, but rather +just as wide as the pixel data needs to be; that is: it is unsafe to do +`memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. Use +[method@GdkPixbuf.Pixbuf.copy] instead, or compute the width in bytes of the +last row as: + +```c +last_row = width * ((n_channels * bits_per_sample + 7) / 8); +``` + +The same rule applies when iterating over each row of a `GdkPixbuf` pixels +array. + +The following code illustrates a simple `put_pixel()` +function for RGB pixbufs with 8 bits per channel with an alpha +channel. + +```c +static void +put_pixel (GdkPixbuf *pixbuf, + int x, + int y, + guchar red, + guchar green, + guchar blue, + guchar alpha) +{ + int n_channels = gdk_pixbuf_get_n_channels (pixbuf); + + // Ensure that the pixbuf is valid + g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB); + g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8); + g_assert (gdk_pixbuf_get_has_alpha (pixbuf)); + g_assert (n_channels == 4); + + int width = gdk_pixbuf_get_width (pixbuf); + int height = gdk_pixbuf_get_height (pixbuf); + + // Ensure that the coordinates are in a valid range + g_assert (x >= 0 && x < width); + g_assert (y >= 0 && y < height); + + int rowstride = gdk_pixbuf_get_rowstride (pixbuf); + + // The pixel buffer in the GdkPixbuf instance + guchar *pixels = gdk_pixbuf_get_pixels (pixbuf); + + // The pixel we wish to modify + guchar *p = pixels + y * rowstride + x * n_channels; + p[0] = red; + p[1] = green; + p[2] = blue; + p[3] = alpha; +} +``` + +## Loading images + +The `GdkPixBuf` class provides a simple mechanism for loading +an image from a file in synchronous and asynchronous fashion. + +For GUI applications, it is recommended to use the asynchronous +stream API to avoid blocking the control flow of the application. + +Additionally, `GdkPixbuf` provides the [class@GdkPixbuf.PixbufLoader`] +API for progressive image loading. + +## Saving images + +The `GdkPixbuf` class provides methods for saving image data in +a number of file formats. The formatted data can be written to a +file or to a memory buffer. `GdkPixbuf` can also call a user-defined +callback on the data, which allows to e.g. write the image +to a socket or store it in a database. - Creates a new #GdkPixbuf structure and allocates a buffer for it. The -buffer has an optimal rowstride. Note that the buffer is not cleared; + Creates a new `GdkPixbuf` structure and allocates a buffer for it. + +If the allocation of the buffer failed, this function will return `NULL`. + +The buffer has an optimal rowstride. Note that the buffer is not cleared; you will have to fill it completely yourself. - A newly-created #GdkPixbuf with a reference count of 1, or -%NULL if not enough memory could be allocated for the image buffer. + A newly-created pixel buffer @@ -392,10 +525,13 @@ you will have to fill it completely yourself. Creates a new #GdkPixbuf out of in-memory readonly image data. + Currently only RGB images with 8 bits per sample are supported. -This is the #GBytes variant of gdk_pixbuf_new_from_data(). + +This is the `GBytes` variant of gdk_pixbuf_new_from_data(), useful +for language bindings. - A newly-created #GdkPixbuf structure with a reference count of 1. + A newly-created pixbuf @@ -430,18 +566,19 @@ This is the #GBytes variant of gdk_pixbuf_new_from_data(). - Creates a new #GdkPixbuf out of in-memory image data. Currently only RGB -images with 8 bits per sample are supported. + Creates a new #GdkPixbuf out of in-memory image data. + +Currently only RGB images with 8 bits per sample are supported. Since you are providing a pre-allocated pixel buffer, you must also specify a way to free that data. This is done with a function of -type #GdkPixbufDestroyNotify. When a pixbuf created with is +type `GdkPixbufDestroyNotify`. When a pixbuf created with is finalized, your destroy notification function will be called, and it is its responsibility to free the pixel array. -See also gdk_pixbuf_new_from_bytes(). +See also: [ctor@GdkPixbuf.Pixbuf.new_from_bytes] - A newly-created #GdkPixbuf structure with a reference count of 1. + A newly-created pixbuf @@ -487,42 +624,55 @@ drops to zero, or %NULL if the data should not be freed - Creates a new pixbuf by loading an image from a file. The file format is -detected automatically. If %NULL is returned, then @error will be set. -Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. - - A newly-created pixbuf with a reference count of 1, or %NULL if -any of several error conditions occurred: the file could not be opened, -there was no loader for the file's format, there was not enough memory to -allocate the image buffer, or the image file contained invalid data. + Creates a new pixbuf by loading an image from a file. + +The file format is detected automatically. + +If `NULL` is returned, then @error will be set. Possible errors are: + + - the file could not be opened + - there is no loader for the file's format + - there is not enough memory to allocate the image buffer + - the image buffer contains invalid data + +The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. + + A newly-created pixbuf Name of file to load, in the GLib file - name encoding + name encoding - Creates a new pixbuf by loading an image from a file. The file format is -detected automatically. If %NULL is returned, then @error will be set. -Possible errors are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. + Creates a new pixbuf by loading an image from a file. + +The file format is detected automatically. + +If `NULL` is returned, then @error will be set. Possible errors are: + + - the file could not be opened + - there is no loader for the file's format + - there is not enough memory to allocate the image buffer + - the image buffer contains invalid data + +The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. + The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. -When preserving the aspect ratio, a @width of -1 will cause the image -to be scaled to the exact given height, and a @height of -1 will cause +When preserving the aspect ratio, a `width` of -1 will cause the image +to be scaled to the exact given height, and a `height` of -1 will cause the image to be scaled to the exact given width. When not preserving -aspect ratio, a @width or @height of -1 means to not scale the image -at all in that dimension. Negative values for @width and @height are +aspect ratio, a `width` or `height` of -1 means to not scale the image +at all in that dimension. Negative values for `width` and `height` are allowed since 2.8. - - A newly-created pixbuf with a reference count of 1, or %NULL -if any of several error conditions occurred: the file could not be opened, -there was no loader for the file's format, there was not enough memory to -allocate the image buffer, or the image file contained invalid data. + + A newly-created pixbuf @@ -540,28 +690,32 @@ allocate the image buffer, or the image file contained invalid data. - %TRUE to preserve the image's aspect ratio + `TRUE` to preserve the image's aspect ratio Creates a new pixbuf by loading an image from a file. -The file format is detected automatically. If %NULL is returned, then -@error will be set. Possible errors are in the #GDK_PIXBUF_ERROR and -#G_FILE_ERROR domains. + +The file format is detected automatically. + +If `NULL` is returned, then @error will be set. Possible errors are: + + - the file could not be opened + - there is no loader for the file's format + - there is not enough memory to allocate the image buffer + - the image buffer contains invalid data + +The error domains are `GDK_PIXBUF_ERROR` and `G_FILE_ERROR`. The image will be scaled to fit in the requested size, preserving the image's aspect ratio. Note that the returned pixbuf may be smaller -than @width x @height, if the aspect ratio requires it. To load +than `width` x `height`, if the aspect ratio requires it. To load and image at the requested size, regardless of aspect ratio, use -gdk_pixbuf_new_from_file_at_scale(). - - A newly-created pixbuf with a reference count of 1, or -%NULL if any of several error conditions occurred: the file could not -be opened, there was no loader for the file's format, there was not -enough memory to allocate the image buffer, or the image file contained -invalid data. +[ctor@GdkPixbuf.Pixbuf.new_from_file_at_scale]. + + A newly-created pixbuf @@ -581,58 +735,60 @@ invalid data. - Create a #GdkPixbuf from a flat representation that is suitable for -storing as inline data in a program. This is useful if you want to -ship a program with images, but don't want to depend on any -external files. + Creates a `GdkPixbuf` from a flat representation that is suitable for +storing as inline data in a program. + +This is useful if you want to ship a program with images, but don't want +to depend on any external files. + +GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which allows +for conversion of `GdkPixbuf`s into such a inline representation. -gdk-pixbuf ships with a program called [gdk-pixbuf-csource][gdk-pixbuf-csource], -which allows for conversion of #GdkPixbufs into such a inline representation. In almost all cases, you should pass the `--raw` option to `gdk-pixbuf-csource`. A sample invocation would be: -|[ - gdk-pixbuf-csource --raw --name=myimage_inline myimage.png -]| +``` +gdk-pixbuf-csource --raw --name=myimage_inline myimage.png +``` For the typical case where the inline pixbuf is read-only static data, you don't need to copy the pixel data unless you intend to write to -it, so you can pass %FALSE for @copy_pixels. (If you pass `--rle` to -`gdk-pixbuf-csource`, a copy will be made even if @copy_pixels is %FALSE, -so using this option is generally a bad idea.) +it, so you can pass `FALSE` for `copy_pixels`. If you pass `--rle` to +`gdk-pixbuf-csource`, a copy will be made even if `copy_pixels` is `FALSE`, +so using this option is generally a bad idea. If you create a pixbuf from const inline data compiled into your program, it's probably safe to ignore errors and disable length checks, since things will always succeed: -|[ + +```c pixbuf = gdk_pixbuf_new_from_inline (-1, myimage_inline, FALSE, NULL); -]| +``` For non-const inline data, you could get out of memory. For untrusted inline data located at runtime, you could have corrupt inline data in addition. - Use #GResource instead. + Use `GResource` instead. - A newly-created #GdkPixbuf structure with a reference, - count of 1, or %NULL if an error occurred. + A newly-created pixbuf - Length in bytes of the @data argument or -1 to - disable length checks + Length in bytes of the `data` argument or -1 to + disable length checks Byte data containing a - serialized #GdkPixdata structure + serialized `GdkPixdata` structure Whether to copy the pixel data, or use direct pointers - @data for the resulting pixbuf + `data` for the resulting pixbuf @@ -640,13 +796,10 @@ addition. Creates a new pixbuf by loading an image from an resource. -The file format is detected automatically. If %NULL is returned, then +The file format is detected automatically. If `NULL` is returned, then @error will be set. - - A newly-created pixbuf, or %NULL if any of several error -conditions occurred: the file could not be opened, the image format is -not supported, there was not enough memory to allocate the image buffer, -the stream contained invalid data, or the operation was cancelled. + + A newly-created pixbuf @@ -659,7 +812,7 @@ the stream contained invalid data, or the operation was cancelled. Creates a new pixbuf by loading an image from an resource. -The file format is detected automatically. If %NULL is returned, then +The file format is detected automatically. If `NULL` is returned, then @error will be set. The image will be scaled to fit in the requested size, optionally @@ -670,11 +823,8 @@ exact given width. When not preserving aspect ratio, a @width or @height of -1 means to not scale the image at all in that dimension. The stream is not closed. - - A newly-created pixbuf, or %NULL if any of several error -conditions occurred: the file could not be opened, the image format is -not supported, there was not enough memory to allocate the image buffer, -the stream contained invalid data, or the operation was cancelled. + + A newly-created pixbuf @@ -691,7 +841,7 @@ the stream contained invalid data, or the operation was cancelled. - %TRUE to preserve the image's aspect ratio + `TRUE` to preserve the image's aspect ratio @@ -699,27 +849,27 @@ the stream contained invalid data, or the operation was cancelled. Creates a new pixbuf by loading an image from an input stream. -The file format is detected automatically. If %NULL is returned, then -@error will be set. The @cancellable can be used to abort the operation -from another thread. If the operation was cancelled, the error -%G_IO_ERROR_CANCELLED will be returned. Other possible errors are in -the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. +The file format is detected automatically. + +If `NULL` is returned, then `error` will be set. + +The `cancellable` can be used to abort the operation from another thread. +If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be +returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and +`G_IO_ERROR` domains. The stream is not closed. - - A newly-created pixbuf, or %NULL if any of several error -conditions occurred: the file could not be opened, the image format is -not supported, there was not enough memory to allocate the image buffer, -the stream contained invalid data, or the operation was cancelled. + + A newly-created pixbuf - a #GInputStream to load the pixbuf from + a `GInputStream` to load the pixbuf from - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore @@ -727,35 +877,32 @@ the stream contained invalid data, or the operation was cancelled. Creates a new pixbuf by loading an image from an input stream. -The file format is detected automatically. If %NULL is returned, then +The file format is detected automatically. If `NULL` is returned, then @error will be set. The @cancellable can be used to abort the operation from another thread. If the operation was cancelled, the error -%G_IO_ERROR_CANCELLED will be returned. Other possible errors are in -the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. +`G_IO_ERROR_CANCELLED` will be returned. Other possible errors are in +the `GDK_PIXBUF_ERROR` and `G_IO_ERROR` domains. The image will be scaled to fit in the requested size, optionally preserving the image's aspect ratio. -When preserving the aspect ratio, a @width of -1 will cause the image to be -scaled to the exact given height, and a @height of -1 will cause the image -to be scaled to the exact given width. If both @width and @height are +When preserving the aspect ratio, a `width` of -1 will cause the image to be +scaled to the exact given height, and a `height` of -1 will cause the image +to be scaled to the exact given width. If both `width` and `height` are given, this function will behave as if the smaller of the two values is passed as -1. -When not preserving aspect ratio, a @width or @height of -1 means to not +When not preserving aspect ratio, a `width` or `height` of -1 means to not scale the image at all in that dimension. The stream is not closed. - - A newly-created pixbuf, or %NULL if any of several error -conditions occurred: the file could not be opened, the image format is -not supported, there was not enough memory to allocate the image buffer, -the stream contained invalid data, or the operation was cancelled. + + A newly-created pixbuf - a #GInputStream to load the pixbuf from + a `GInputStream` to load the pixbuf from @@ -767,11 +914,11 @@ the stream contained invalid data, or the operation was cancelled. - %TRUE to preserve the image's aspect ratio + `TRUE` to preserve the image's aspect ratio - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore @@ -779,23 +926,24 @@ the stream contained invalid data, or the operation was cancelled. Finishes an asynchronous pixbuf creation operation started with gdk_pixbuf_new_from_stream_async(). - - a #GdkPixbuf or %NULL on error. Free the returned -object with g_object_unref(). + + the newly created pixbuf - a #GAsyncResult + a `GAsyncResult` - Creates a new pixbuf by parsing XPM data in memory. This data is commonly -the result of including an XPM file into a program's C source. + Creates a new pixbuf by parsing XPM data in memory. + +This data is commonly the result of including an XPM file into a +program's C source. - A newly-created pixbuf with a reference count of 1. + A newly-created pixbuf @@ -809,8 +957,10 @@ the result of including an XPM file into a program's C source. Calculates the rowstride that an image created with those values would -have. This is useful for front-ends and backends that want to sanity -check image values without needing to create them. +have. + +This function is useful for front-ends and backends that want to check +image values without needing to create a `GdkPixbuf`. the rowstride for the given values, or -1 in case of error. @@ -841,10 +991,8 @@ check image values without needing to create them. Parses an image file far enough to determine its format and size. - A #GdkPixbufFormat describing - the image format of the file or %NULL if the image format wasn't - recognized. The return value is owned by #GdkPixbuf and should - not be freed. + A `GdkPixbufFormat` describing + the image format of the file @@ -853,13 +1001,11 @@ check image values without needing to create them. - Return location for the width of the - image, or %NULL + Return location for the width of the image - Return location for the height of the - image, or %NULL + Return location for the height of the image @@ -883,11 +1029,11 @@ get the result of the operation. - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore - a #GAsyncReadyCallback to call when the file info is available + a `GAsyncReadyCallback` to call when the file info is available @@ -899,24 +1045,22 @@ get the result of the operation. Finishes an asynchronous pixbuf parsing operation started with gdk_pixbuf_get_file_info_async(). - - A #GdkPixbufFormat describing the image - format of the file or %NULL if the image format wasn't - recognized. The return value is owned by GdkPixbuf and should - not be freed. + + A `GdkPixbufFormat` describing the + image format of the file - a #GAsyncResult + a `GAsyncResult` - Return location for the width of the image, or %NULL + Return location for the width of the image, or `NULL` - Return location for the height of the image, or %NULL + Return location for the height of the image, or `NULL` @@ -926,16 +1070,14 @@ gdk_pixbuf_get_file_info_async(). by GdkPixbuf. A list of -#GdkPixbufFormats describing the supported image formats. The list should -be freed when it is no longer needed, but the structures themselves are -owned by #GdkPixbuf and should not be freed. + support image formats. - Initalizes the gdk-pixbuf loader modules referenced by the loaders.cache + Initalizes the gdk-pixbuf loader modules referenced by the `loaders.cache` file present inside that directory. This is to be used by applications that want to ship certain loaders @@ -953,7 +1095,7 @@ provided modules. - Path to directory where the loaders.cache is installed + Path to directory where the `loaders.cache` is installed @@ -965,21 +1107,22 @@ For more details see gdk_pixbuf_new_from_stream(), which is the synchronous version of this function. When the operation is finished, @callback will be called in the main thread. -You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the operation. +You can then call gdk_pixbuf_new_from_stream_finish() to get the result of +the operation. - a #GInputStream from which to load the pixbuf + a `GInputStream` from which to load the pixbuf - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore - a #GAsyncReadyCallback to call when the pixbuf is loaded + a `GAsyncReadyCallback` to call when the pixbuf is loaded @@ -1001,7 +1144,7 @@ You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the o - a #GInputStream from which to load the pixbuf + a `GInputStream` from which to load the pixbuf @@ -1013,15 +1156,15 @@ You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the o - %TRUE to preserve the image's aspect ratio + `TRUE` to preserve the image's aspect ratio - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore - a #GAsyncReadyCallback to call when the pixbuf is loaded + a `GAsyncReadyCallback` to call when the pixbuf is loaded @@ -1034,27 +1177,32 @@ You can then call gdk_pixbuf_new_from_stream_finish() to get the result of the o Finishes an asynchronous pixbuf save operation started with gdk_pixbuf_save_to_stream_async(). - %TRUE if the pixbuf was saved successfully, %FALSE if an error was set. + `TRUE` if the pixbuf was saved successfully, `FALSE` if an error was set. - a #GAsyncResult + a `GAsyncResult` Takes an existing pixbuf and adds an alpha channel to it. + If the existing pixbuf already had an alpha channel, the channel values are copied from the original; otherwise, the alpha channel is initialized to 255 (full opacity). -If @substitute_color is %TRUE, then the color specified by (@r, @g, @b) will be -assigned zero opacity. That is, if you pass (255, 255, 255) for the -substitute color, all white pixels will become fully transparent. +If `substitute_color` is `TRUE`, then the color specified by the +(`r`, `g`, `b`) arguments will be assigned zero opacity. That is, +if you pass `(255, 255, 255)` for the substitute color, all white +pixels will become fully transparent. + +If `substitute_color` is `FALSE`, then the (`r`, `g`, `b`) arguments +will be ignored. - A newly-created pixbuf with a reference count of 1. + A newly-created pixbuf @@ -1063,8 +1211,7 @@ substitute color, all white pixels will become fully transparent. - Whether to set a color to zero opacity. If this -is %FALSE, then the (@r, @g, @b) arguments will be ignored. + Whether to set a color to zero opacity. @@ -1083,22 +1230,22 @@ is %FALSE, then the (@r, @g, @b) arguments will be ignored. Takes an existing pixbuf and checks for the presence of an -associated "orientation" option, which may be provided by the -jpeg loader (which reads the exif orientation tag) or the -tiff loader (which reads the tiff orientation tag, and -compensates it for the partial transforms performed by -libtiff). If an orientation option/tag is present, the -appropriate transform will be performed so that the pixbuf -is oriented correctly. - - A newly-created pixbuf, %NULL if -not enough memory could be allocated for it, or a reference to the -input pixbuf (with an increased reference count). +associated "orientation" option. + +The orientation option may be provided by the JPEG loader (which +reads the exif orientation tag) or the TIFF loader (which reads +the TIFF orientation tag, and compensates it for the partial +transforms performed by libtiff). + +If an orientation option/tag is present, the appropriate transform +will be performed so that the pixbuf is oriented correctly. + + A newly-created pixbuf - A #GdkPixbuf. + a pixbuf with an orientation option @@ -1106,6 +1253,7 @@ input pixbuf (with an increased reference count). Creates a transformation of the source image @src by scaling by @scale_x and @scale_y then translating by @offset_x and @offset_y. + This gives an image in the coordinates of the destination pixbuf. The rectangle (@dest_x, @dest_y, @dest_width, @dest_height) is then alpha blended onto the corresponding rectangle of the @@ -1258,12 +1406,11 @@ function suitable for many tasks. - Creates a new #GdkPixbuf by scaling @src to @dest_width x -@dest_height and alpha blending the result with a checkboard of colors -@color1 and @color2. + Creates a new pixbuf by scaling `src` to `dest_width` x `dest_height` +and alpha blending the result with a checkboard of colors `color1` +and `color2`. - the new #GdkPixbuf, or %NULL if not enough memory could be -allocated for it. + the new pixbuf @@ -1302,12 +1449,13 @@ allocated for it. - Creates a new #GdkPixbuf with a copy of the information in the specified -@pixbuf. Note that this does not copy the options set on the original #GdkPixbuf, + Creates a new `GdkPixbuf` with a copy of the information in the specified +`pixbuf`. + +Note that this does not copy the options set on the original `GdkPixbuf`, use gdk_pixbuf_copy_options() for this. - A newly-created pixbuf with a reference count of 1, or %NULL if -not enough memory could be allocated. + A newly-created pixbuf @@ -1318,8 +1466,9 @@ not enough memory could be allocated. - Copies a rectangular area from @src_pixbuf to @dest_pixbuf. Conversion of -pixbuf formats is done automatically. + Copies a rectangular area from `src_pixbuf` to `dest_pixbuf`. + +Conversion of pixbuf formats is done automatically. If the source rectangle overlaps the destination rectangle on the same pixbuf, it will be overwritten during the copy operation. @@ -1363,40 +1512,44 @@ Therefore, you can not use this function to scroll a pixbuf. - Copy the key/value pair options attached to a #GdkPixbuf to another. + Copies the key/value pair options attached to a `GdkPixbuf` to another +`GdkPixbuf`. + This is useful to keep original metadata after having manipulated a file. However be careful to remove metadata which you've already applied, such as the "orientation" option after rotating the image. - %TRUE on success. + `TRUE` on success. - a #GdkPixbuf to copy options from + the source pixbuf - the #GdkPixbuf to copy options to + the destination pixbuf Clears a pixbuf to the given RGBA value, converting the RGBA value into -the pixbuf's pixel format. The alpha will be ignored if the pixbuf -doesn't have an alpha channel. +the pixbuf's pixel format. + +The alpha component will be ignored if the pixbuf doesn't have an alpha +channel. - a #GdkPixbuf + a `GdkPixbuf` - RGBA pixel to clear to - (0xffffffff is opaque white, 0x00000000 transparent black) + RGBA pixel to used to clear (`0xffffffff` is opaque white, + `0x00000000` transparent black) @@ -1405,8 +1558,7 @@ doesn't have an alpha channel. Flips a pixbuf horizontally or vertically and returns the result in a new pixbuf. - the new #GdkPixbuf, or %NULL -if not enough memory could be allocated for it. + the new pixbuf @@ -1415,7 +1567,7 @@ if not enough memory could be allocated for it. - %TRUE to flip horizontally, %FALSE to flip vertically + `TRUE` to flip horizontally, `FALSE` to flip vertically @@ -1462,7 +1614,7 @@ if not enough memory could be allocated for it. Queries whether a pixbuf has an alpha channel (opacity information). - %TRUE if it has an alpha channel, %FALSE otherwise. + `TRUE` if it has an alpha channel, `FALSE` otherwise. @@ -1514,14 +1666,13 @@ Since 2.32 the JPEG and PNG loaders set "x-dpi" and "y-dpi" if the file contains image density information in dots per inch. Since 2.36.6, the JPEG loader sets the "comment" option with the comment EXIF tag. - - the value associated with @key. This is a nul-terminated -string that should not be freed or %NULL if @key was not found. + + the value associated with `key` - a #GdkPixbuf + a `GdkPixbuf` @@ -1531,13 +1682,12 @@ string that should not be freed or %NULL if @key was not found. - Returns a #GHashTable with a list of all the options that may have been -attached to the @pixbuf when it was loaded, or that may have been -attached by another function using gdk_pixbuf_set_option(). - -See gdk_pixbuf_get_option() for more details. + Returns a `GHashTable` with a list of all the options that may have been +attached to the `pixbuf` when it was loaded, or that may have been +attached by another function using [method@GdkPixbuf.Pixbuf.set_option]. - a #GHashTable of key/values + a #GHashTable + of key/values pairs @@ -1545,20 +1695,21 @@ See gdk_pixbuf_get_option() for more details. - a #GdkPixbuf + a `GdkPixbuf` - Queries a pointer to the pixel data of a pixbuf. - - A pointer to the pixbuf's pixel data. -Please see the section on [image data][image-data] for information -about how the pixel data is stored in memory. + Queries a pointer to the pixel data of a pixbuf. This function will cause an implicit copy of the pixbuf data if the -pixbuf was created from read-only data. +pixbuf was created from read-only data. + +Please see the section on [image data](#image-data) for information +about how the pixel data is stored in memory. + + A pointer to the pixbuf's pixel data. @@ -1571,14 +1722,16 @@ pixbuf was created from read-only data. - Queries a pointer to the pixel data of a pixbuf. - - A pointer to the pixbuf's -pixel data. Please see the section on [image data][image-data] -for information about how the pixel data is stored in memory. + Queries a pointer to the pixel data of a pixbuf. This function will cause an implicit copy of the pixbuf data if the -pixbuf was created from read-only data. +pixbuf was created from read-only data. + +Please see the section on [image data](#image-data) for information +about how the pixel data is stored in memory. + + A pointer to the pixbuf's +pixel data. @@ -1622,13 +1775,14 @@ the start of a row and the start of the next row. - Creates a new pixbuf which represents a sub-region of @src_pixbuf. + Creates a new pixbuf which represents a sub-region of `src_pixbuf`. + The new pixbuf shares its pixels with the original pixbuf, so writing to one affects both. The new pixbuf holds a reference to -@src_pixbuf, so @src_pixbuf will not be finalized until the new +`src_pixbuf`, so `src_pixbuf` will not be finalized until the new pixbuf is finalized. -Note that if @src_pixbuf is read-only, this function will force it +Note that if `src_pixbuf` is read-only, this function will force it to be mutable. a new pixbuf @@ -1636,7 +1790,7 @@ to be mutable. - a #GdkPixbuf + a `GdkPixbuf` @@ -1659,9 +1813,10 @@ to be mutable. Provides a #GBytes buffer containing the raw pixel data; the data -must not be modified. This function allows skipping the implicit -copy that must be made if gdk_pixbuf_get_pixels() is called on a -read-only pixbuf. +must not be modified. + +This function allows skipping the implicit copy that must be made +if gdk_pixbuf_get_pixels() is called on a read-only pixbuf. A new reference to a read-only copy of the pixel data. Note that for mutable pixbufs, this function will @@ -1677,10 +1832,10 @@ read-only pixbuf. - Provides a read-only pointer to the raw pixel data; must not be -modified. This function allows skipping the implicit copy that -must be made if gdk_pixbuf_get_pixels() is called on a read-only -pixbuf. + Provides a read-only pointer to the raw pixel data. + +This function allows skipping the implicit copy that must be made +if gdk_pixbuf_get_pixels() is called on a read-only pixbuf. a read-only pointer to the raw pixel data @@ -1707,14 +1862,14 @@ pixbuf. - Remove the key/value pair option attached to a #GdkPixbuf. + Removes the key/value pair option attached to a `GdkPixbuf`. - %TRUE if an option was removed, %FALSE if not. + `TRUE` if an option was removed, `FALSE` if not. - a #GdkPixbuf + a `GdkPixbuf` @@ -1727,10 +1882,9 @@ pixbuf. Rotates a pixbuf by a multiple of 90 degrees, and returns the result in a new pixbuf. -If @angle is 0, a copy of @src is returned, avoiding any rotation. +If `angle` is 0, this function will return a copy of `src`. - the new #GdkPixbuf, or %NULL -if not enough memory could be allocated for it. + the new pixbuf @@ -1745,14 +1899,20 @@ if not enough memory could be allocated for it. - Modifies saturation and optionally pixelates @src, placing the result in -@dest. @src and @dest may be the same pixbuf with no ill effects. If -@saturation is 1.0 then saturation is not changed. If it's less than 1.0, + Modifies saturation and optionally pixelates `src`, placing the result in +`dest`. + +The `src` and `dest` pixbufs must have the same image format, size, and +rowstride. + +The `src` and `dest` arguments may be the same pixbuf with no ill effects. + +If `saturation` is 1.0 then saturation is not changed. If it's less than 1.0, saturation is reduced (the image turns toward grayscale); if greater than -1.0, saturation is increased (the image gets more vivid colors). If @pixelate -is %TRUE, then pixels are faded in a checkerboard pattern to create a -pixelated image. @src and @dest must have the same image format, size, and -rowstride. +1.0, saturation is increased (the image gets more vivid colors). + +If `pixelate` is `TRUE`, then pixels are faded in a checkerboard pattern to +create a pixelated image. @@ -1781,7 +1941,7 @@ and "bmp" are possible file formats to save in, but more formats may be installed. The list of all writable formats can be determined in the following way: -|[ +```c void add_if_writable (GdkPixbufFormat *data, GSList **list) { if (gdk_pixbuf_format_is_writable (data)) @@ -1792,60 +1952,68 @@ GSList *formats = gdk_pixbuf_get_formats (); GSList *writable_formats = NULL; g_slist_foreach (formats, add_if_writable, &writable_formats); g_slist_free (formats); -]| +``` -If @error is set, %FALSE will be returned. Possible errors include -those in the #GDK_PIXBUF_ERROR domain and those in the #G_FILE_ERROR domain. +If `error` is set, `FALSE` will be returned. Possible errors include +those in the `GDK_PIXBUF_ERROR` domain and those in the `G_FILE_ERROR` +domain. -The variable argument list should be %NULL-terminated; if not empty, +The variable argument list should be `NULL`-terminated; if not empty, it should contain pairs of strings that modify the save parameters. For example: -|[ -gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL); -]| -Currently only few parameters exist. JPEG images can be saved with a -"quality" parameter; its value should be in the range [0,100]. JPEG -and PNG density can be set by setting the "x-dpi" and "y-dpi" parameters -to the appropriate values in dots per inch. +```c +gdk_pixbuf_save (pixbuf, handle, "jpeg", &error, "quality", "100", NULL); +``` + +Currently only few parameters exist. + +JPEG images can be saved with a "quality" parameter; its value should be +in the range `[0, 100]`. JPEG and PNG density can be set by setting the +"x-dpi" and "y-dpi" parameters to the appropriate values in dots per inch. Text chunks can be attached to PNG images by specifying parameters of the form "tEXt::key", where key is an ASCII string of length 1-79. The values are UTF-8 encoded strings. The PNG compression level can be specified using the "compression" parameter; it's value is in an -integer in the range of [0,9]. +integer in the range of `[0, 9]`. ICC color profiles can also be embedded into PNG, JPEG and TIFF images. The "icc-profile" value should be the complete ICC profile encoded into base64. -|[ -gchar *contents; -gchar *contents_encode; +```c +char *contents; gsize length; -g_file_get_contents ("/home/hughsie/.color/icc/L225W.icm", &contents, &length, NULL); -contents_encode = g_base64_encode ((const guchar *) contents, length); -gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL); -]| -TIFF images recognize: (1) a "bits-per-sample" option (integer) which -can be either 1 for saving bi-level CCITTFAX4 images, or 8 for saving -8-bits per sample; (2) a "compression" option (integer) which can be -1 for no compression, 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for -DEFLATE (see the libtiff documentation and tiff.h for all supported -codec values); (3) an "icc-profile" option (zero-terminated string) -containing a base64 encoded ICC color profile. +// icm_path is set elsewhere +g_file_get_contents (icm_path, &contents, &length, NULL); + +char *contents_encode = g_base64_encode ((const guchar *) contents, length); + +gdk_pixbuf_save (pixbuf, handle, "png", &error, "icc-profile", contents_encode, NULL); +``` + +TIFF images recognize: + + 1. a "bits-per-sample" option (integer) which can be either 1 for saving + bi-level CCITTFAX4 images, or 8 for saving 8-bits per sample + 2. a "compression" option (integer) which can be 1 for no compression, + 2 for Huffman, 5 for LZW, 7 for JPEG and 8 for DEFLATE (see the libtiff + documentation and tiff.h for all supported codec values) + 3. an "icc-profile" option (zero-terminated string) containing a base64 + encoded ICC color profile. ICO images can be saved in depth 16, 24, or 32, by using the "depth" parameter. When the ICO saver is given "x_hot" and "y_hot" parameters, it produces a CUR instead of an ICO. - whether an error was set + `TRUE` on success, and `FALSE` otherwise - a #GdkPixbuf. + a `GdkPixbuf`. @@ -1857,32 +2025,37 @@ it produces a CUR instead of an ICO. - return location for error, or %NULL + return location for error - list of key-value save options, followed by %NULL + list of key-value save options, followed by `NULL` - Saves pixbuf to a new buffer in format @type, which is currently "jpeg", -"png", "tiff", "ico" or "bmp". This is a convenience function that uses -gdk_pixbuf_save_to_callback() to do the real work. Note that the buffer -is not nul-terminated and may contain embedded nuls. -If @error is set, %FALSE will be returned and @buffer will be set to -%NULL. Possible errors include those in the #GDK_PIXBUF_ERROR + Saves pixbuf to a new buffer in format `type`, which is currently "jpeg", +"png", "tiff", "ico" or "bmp". + +This is a convenience function that uses `gdk_pixbuf_save_to_callback()` +to do the real work. + +Note that the buffer is not `NUL`-terminated and may contain embedded `NUL` +characters. + +If @error is set, `FALSE` will be returned and @buffer will be set to +`NULL`. Possible errors include those in the `GDK_PIXBUF_ERROR` domain. -See gdk_pixbuf_save() for more details. +See `gdk_pixbuf_save()` for more details. whether an error was set - a #GdkPixbuf. + a `GdkPixbuf`. @@ -1901,7 +2074,7 @@ See gdk_pixbuf_save() for more details. - return location for error, or %NULL + return location for error, or `NULL` @@ -1911,16 +2084,19 @@ See gdk_pixbuf_save() for more details. - Saves pixbuf to a new buffer in format @type, which is currently "jpeg", -"tiff", "png", "ico" or "bmp". See gdk_pixbuf_save_to_buffer() -for more details. + Vector version of `gdk_pixbuf_save_to_buffer()`. + +Saves pixbuf to a new buffer in format @type, which is currently "jpeg", +"tiff", "png", "ico" or "bmp". + +See [method@GdkPixbuf.Pixbuf.save_to_buffer] for more details. whether an error was set - a #GdkPixbuf. + a `GdkPixbuf`. @@ -1938,36 +2114,39 @@ for more details. name of file format. - - name of options to set, %NULL-terminated + + name of options to set - + - + values for named options - + - Saves pixbuf in format @type by feeding the produced data to a -callback. Can be used when you want to store the image to something + Saves pixbuf in format `type` by feeding the produced data to a +callback. + +This function can be used when you want to store the image to something other than a file, such as an in-memory buffer or a socket. -If @error is set, %FALSE will be returned. Possible errors -include those in the #GDK_PIXBUF_ERROR domain and whatever the save + +If @error is set, `FALSE` will be returned. Possible errors +include those in the `GDK_PIXBUF_ERROR` domain and whatever the save function generates. -See gdk_pixbuf_save() for more details. +See [method@GdkPixbuf.Pixbuf.save] for more details. whether an error was set - a #GdkPixbuf. + a `GdkPixbuf`. @@ -1984,7 +2163,7 @@ See gdk_pixbuf_save() for more details. - return location for error, or %NULL + return location for error, or `NULL` @@ -1994,16 +2173,21 @@ See gdk_pixbuf_save() for more details. - Saves pixbuf to a callback in format @type, which is currently "jpeg", -"png", "tiff", "ico" or "bmp". If @error is set, %FALSE will be returned. See -gdk_pixbuf_save_to_callback () for more details. + Vector version of `gdk_pixbuf_save_to_callback()`. + +Saves pixbuf to a callback in format @type, which is currently "jpeg", +"png", "tiff", "ico" or "bmp". + +If @error is set, `FALSE` will be returned. + +See [method@GdkPixbuf.Pixbuf.save_to_callback] for more details. whether an error was set - a #GdkPixbuf. + a `GdkPixbuf`. @@ -2019,13 +2203,13 @@ gdk_pixbuf_save_to_callback () for more details. name of file format. - - name of options to set, %NULL-terminated + + name of options to set - + values for named options @@ -2034,29 +2218,29 @@ gdk_pixbuf_save_to_callback () for more details. - Saves @pixbuf to an output stream. + Saves `pixbuf` to an output stream. Supported file formats are currently "jpeg", "tiff", "png", "ico" or -"bmp". See gdk_pixbuf_save_to_buffer() for more details. +"bmp". See `gdk_pixbuf_save_to_buffer()` for more details. -The @cancellable can be used to abort the operation from another -thread. If the operation was cancelled, the error %G_IO_ERROR_CANCELLED -will be returned. Other possible errors are in the #GDK_PIXBUF_ERROR -and %G_IO_ERROR domains. +The `cancellable` can be used to abort the operation from another +thread. If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` +will be returned. Other possible errors are in the `GDK_PIXBUF_ERROR` +and `G_IO_ERROR` domains. -The stream is not closed. +The stream is not closed at the end of this call. - %TRUE if the pixbuf was saved successfully, %FALSE if an - error was set. + `TRUE` if the pixbuf was saved successfully, `FALSE` if an + error was set. - a #GdkPixbuf + a `GdkPixbuf` - a #GOutputStream to save the pixbuf to + a `GOutputStream` to save the pixbuf to @@ -2064,11 +2248,11 @@ The stream is not closed. - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore - return location for error, or %NULL + return location for error, or `NULL` @@ -2078,23 +2262,25 @@ The stream is not closed. - Saves @pixbuf to an output stream asynchronously. + Saves `pixbuf` to an output stream asynchronously. For more details see gdk_pixbuf_save_to_stream(), which is the synchronous version of this function. -When the operation is finished, @callback will be called in the main thread. -You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation. +When the operation is finished, `callback` will be called in the main thread. + +You can then call gdk_pixbuf_save_to_stream_finish() to get the result of +the operation. - a #GdkPixbuf + a `GdkPixbuf` - a #GOutputStream to which to save the pixbuf + a `GOutputStream` to which to save the pixbuf @@ -2102,11 +2288,11 @@ You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the op - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore - a #GAsyncReadyCallback to call when the pixbuf is saved + a `GAsyncReadyCallback` to call when the pixbuf is saved @@ -2120,88 +2306,92 @@ You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the op - Saves @pixbuf to an output stream. + Saves `pixbuf` to an output stream. Supported file formats are currently "jpeg", "tiff", "png", "ico" or -"bmp". See gdk_pixbuf_save_to_stream() for more details. +"bmp". + +See [method@GdkPixbuf.Pixbuf.save_to_stream] for more details. - %TRUE if the pixbuf was saved successfully, %FALSE if an - error was set. + `TRUE` if the pixbuf was saved successfully, `FALSE` if an + error was set. - a #GdkPixbuf + a `GdkPixbuf` - a #GOutputStream to save the pixbuf to + a `GOutputStream` to save the pixbuf to name of file format - - name of options to set, %NULL-terminated + + name of options to set - + - + values for named options - + - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore - Saves @pixbuf to an output stream asynchronously. + Saves `pixbuf` to an output stream asynchronously. For more details see gdk_pixbuf_save_to_streamv(), which is the synchronous version of this function. -When the operation is finished, @callback will be called in the main thread. -You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the operation. +When the operation is finished, `callback` will be called in the main thread. + +You can then call gdk_pixbuf_save_to_stream_finish() to get the result of +the operation. - a #GdkPixbuf + a `GdkPixbuf` - a #GOutputStream to which to save the pixbuf + a `GOutputStream` to which to save the pixbuf name of file format - - name of options to set, %NULL-terminated + + name of options to set - + - + values for named options - + - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object, `NULL` to ignore - a #GAsyncReadyCallback to call when the pixbuf is saved + a `GAsyncReadyCallback` to call when the pixbuf is saved @@ -2211,16 +2401,20 @@ You can then call gdk_pixbuf_save_to_stream_finish() to get the result of the op - Saves pixbuf to a file in @type, which is currently "jpeg", "png", "tiff", "ico" or "bmp". -If @error is set, %FALSE will be returned. -See gdk_pixbuf_save () for more details. + Vector version of `gdk_pixbuf_save()`. + +Saves pixbuf to a file in `type`, which is currently "jpeg", "png", "tiff", "ico" or "bmp". + +If @error is set, `FALSE` will be returned. + +See [method@GdkPixbuf.Pixbuf.save] for more details. whether an error was set - a #GdkPixbuf. + a `GdkPixbuf`. @@ -2231,16 +2425,16 @@ See gdk_pixbuf_save () for more details. name of file format. - - name of options to set, %NULL-terminated + + name of options to set - + - + values for named options - + @@ -2252,8 +2446,8 @@ then renders the rectangle (@dest_x, @dest_y, @dest_width, @dest_height) of the resulting image onto the destination image replacing the previous contents. -Try to use gdk_pixbuf_scale_simple() first, this function is -the industrial-strength power tool you can fall back to if +Try to use gdk_pixbuf_scale_simple() first; this function is +the industrial-strength power tool you can fall back to, if gdk_pixbuf_scale_simple() isn't powerful enough. If the source rectangle overlaps the destination rectangle on the @@ -2310,24 +2504,26 @@ results in rendering artifacts. - Create a new #GdkPixbuf containing a copy of @src scaled to -@dest_width x @dest_height. Leaves @src unaffected. @interp_type -should be #GDK_INTERP_NEAREST if you want maximum speed (but when -scaling down #GDK_INTERP_NEAREST is usually unusably ugly). The -default @interp_type should be #GDK_INTERP_BILINEAR which offers -reasonable quality and speed. + Create a new pixbuf containing a copy of `src` scaled to +`dest_width` x `dest_height`. -You can scale a sub-portion of @src by creating a sub-pixbuf -pointing into @src; see gdk_pixbuf_new_subpixbuf(). +This function leaves `src` unaffected. -If @dest_width and @dest_height are equal to the @src width and height, a -copy of @src is returned, avoiding any scaling. +The `interp_type` should be `GDK_INTERP_NEAREST` if you want maximum +speed (but when scaling down `GDK_INTERP_NEAREST` is usually unusably +ugly). The default `interp_type` should be `GDK_INTERP_BILINEAR` which +offers reasonable quality and speed. -For more complicated scaling/alpha blending see gdk_pixbuf_scale() -and gdk_pixbuf_composite(). +You can scale a sub-portion of `src` by creating a sub-pixbuf +pointing into `src`; see [method@GdkPixbuf.Pixbuf.new_subpixbuf]. + +If `dest_width` and `dest_height` are equal to the width and height of +`src`, this function will return an unscaled copy of `src`. + +For more complicated scaling/alpha blending see [method@GdkPixbuf.Pixbuf.scale] +and [method@GdkPixbuf.Pixbuf.composite]. - the new #GdkPixbuf, or %NULL if not enough memory could be -allocated for it. + the new pixbuf @@ -2350,16 +2546,17 @@ allocated for it. - Attaches a key/value pair as an option to a #GdkPixbuf. If @key already -exists in the list of options attached to @pixbuf, the new value is -ignored and %FALSE is returned. + Attaches a key/value pair as an option to a `GdkPixbuf`. + +If `key` already exists in the list of options attached to the `pixbuf`, +the new value is ignored and `FALSE` is returned. - %TRUE on success. + `TRUE` on success - a #GdkPixbuf + a `GdkPixbuf` @@ -2387,20 +2584,27 @@ ignored and %FALSE is returned. The number of bits per sample. + Currently only 8 bit per sample are supported. + The color space of the pixbuf. + +Currently, only `GDK_COLORSPACE_RGB` is supported. + Whether the pixbuf has an alpha channel. + The number of rows of the pixbuf. The number of samples per pixel. + Currently, only 3 or 4 samples per pixel are supported. @@ -2408,28 +2612,38 @@ Currently, only 3 or 4 samples per pixel are supported. + A pointer to the pixel data of the pixbuf. The number of bytes between the start of a row and -the start of the next row. This number must (obviously) -be at least as large as the width of the pixbuf. +the start of the next row. + +This number must (obviously) be at least as large as the +width of the pixbuf. + The number of columns of the pixbuf. - - These values can be passed to -gdk_pixbuf_xlib_render_to_drawable_alpha() to control how the alpha -channel of an image should be handled. This function can create a -bilevel clipping mask (black and white) and use it while painting -the image. In the future, when the X Window System gets an alpha -channel extension, it will be possible to do full alpha -compositing onto arbitrary drawables. For now both cases fall -back to a bilevel clipping mask. - it is unused since 2.42. + + Control the alpha channel for drawables. + +These values can be passed to gdk_pixbuf_xlib_render_to_drawable_alpha() +in gdk-pixbuf-xlib to control how the alpha channel of an image should +be handled. + +This function can create a bilevel clipping mask (black and white) and use +it while painting the image. + +In the future, when the X Window System gets an alpha channel extension, +it will be possible to do full alpha compositing onto arbitrary drawables. +For now both cases fall back to a bilevel clipping mask. + There is no user of GdkPixbufAlphaMode in GdkPixbuf, + and the Xlib utility functions have been split out to their own + library, gdk-pixbuf-xlib A bilevel clipping mask (black and white) will be created and used to draw the image. Pixels below 0.5 opacity @@ -2442,23 +2656,36 @@ back to a bilevel clipping mask. - An opaque struct representing an animation. + An opaque object representing an animation. + +The GdkPixBuf library provides a simple mechanism to load and +represent animations. An animation is conceptually a series of +frames to be displayed over time. + +The animation may not be represented as a series of frames +internally; for example, it may be stored as a sprite and +instructions for moving the sprite around a background. + +To display an animation you don't need to understand its +representation, however; you just ask `GdkPixbuf` what should +be displayed at a given point in time. - Creates a new animation by loading it from a file. The file format is -detected automatically. If the file's format does not support multi-frame -images, then an animation with a single frame will be created. Possible errors -are in the #GDK_PIXBUF_ERROR and #G_FILE_ERROR domains. - - A newly-created animation with a reference count of 1, or %NULL -if any of several error conditions ocurred: the file could not be opened, -there was no loader for the file's format, there was not enough memory to -allocate the image buffer, or the image file contained invalid data. + Creates a new animation by loading it from a file. + +The file format is detected automatically. + +If the file's format does not support multi-frame images, then an animation +with a single frame will be created. + +Possible errors are in the `GDK_PIXBUF_ERROR` and `G_FILE_ERROR` domains. + + A newly-created animation Name of file to load, in the GLib file - name encoding + name encoding @@ -2466,13 +2693,10 @@ allocate the image buffer, or the image file contained invalid data. Creates a new pixbuf animation by loading an image from an resource. -The file format is detected automatically. If %NULL is returned, then +The file format is detected automatically. If `NULL` is returned, then @error will be set. - - A newly-created animation, or %NULL if any of several error -conditions occurred: the file could not be opened, the image format is -not supported, there was not enough memory to allocate the image buffer, -the stream contained invalid data, or the operation was cancelled. + + A newly-created animation @@ -2485,37 +2709,36 @@ the stream contained invalid data, or the operation was cancelled. Creates a new animation by loading it from an input stream. -The file format is detected automatically. If %NULL is returned, then -@error will be set. The @cancellable can be used to abort the operation -from another thread. If the operation was cancelled, the error -%G_IO_ERROR_CANCELLED will be returned. Other possible errors are in -the #GDK_PIXBUF_ERROR and %G_IO_ERROR domains. +The file format is detected automatically. + +If `NULL` is returned, then @error will be set. + +The @cancellable can be used to abort the operation from another thread. +If the operation was cancelled, the error `G_IO_ERROR_CANCELLED` will be +returned. Other possible errors are in the `GDK_PIXBUF_ERROR` and +`G_IO_ERROR` domains. The stream is not closed. - - A newly-created pixbuf, or %NULL if any of several error -conditions occurred: the file could not be opened, the image format is -not supported, there was not enough memory to allocate the image buffer, -the stream contained invalid data, or the operation was cancelled. + + A newly-created animation - a #GInputStream to load the pixbuf from + a `GInputStream` to load the pixbuf from - optional #GCancellable object, %NULL to ignore + optional `GCancellable` object Finishes an asynchronous pixbuf animation creation operation started with -gdk_pixbuf_animation_new_from_stream_async(). - - a #GdkPixbufAnimation or %NULL on error. Free the returned -object with g_object_unref(). +[func@GdkPixbuf.PixbufAnimation.new_from_stream_async]. + + the newly created animation @@ -2531,7 +2754,7 @@ object with g_object_unref(). For more details see gdk_pixbuf_new_from_stream(), which is the synchronous version of this function. -When the operation is finished, @callback will be called in the main thread. +When the operation is finished, `callback` will be called in the main thread. You can then call gdk_pixbuf_animation_new_from_stream_finish() to get the result of the operation. @@ -2543,11 +2766,11 @@ result of the operation. - optional #GCancellable object, %NULL to ignore + optional #GCancellable object - a #GAsyncReadyCallback to call when the pixbuf is loaded + a `GAsyncReadyCallback` to call when the pixbuf is loaded @@ -2557,9 +2780,10 @@ result of the operation. - Get an iterator for displaying an animation. The iterator provides -the frames that should be displayed at a given time. It should be -freed after use with g_object_unref(). + Get an iterator for displaying an animation. + +The iterator provides the frames that should be displayed at a +given time. @start_time would normally come from g_get_current_time(), and marks the beginning of animation playback. After creating an iterator, you @@ -2571,7 +2795,7 @@ gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time the image is updated, you should reinstall the timeout with the new, possibly-changed delay time. -As a shortcut, if @start_time is %NULL, the result of +As a shortcut, if @start_time is `NULL`, the result of g_get_current_time() will be used automatically. To update the image (i.e. possibly change the result of @@ -2582,14 +2806,14 @@ If you're using #GdkPixbufLoader, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and gdk_pixbuf_animation_iter_on_currently_loading_frame() returns -%TRUE. In this case, the frame currently being fed into the loader +`TRUE`. In this case, the frame currently being fed into the loader has received new data, so needs to be refreshed. The delay time for a frame may also be modified after an area_updated signal, for example if the delay time for a frame is encoded in the data after the frame itself. So your timeout should be reinstalled after any area_updated signal. -A delay time of -1 is possible, indicating "infinite." +A delay time of -1 is possible, indicating "infinite". an iterator to move over the animation @@ -2622,12 +2846,17 @@ A delay time of -1 is possible, indicating "infinite." - If an animation is really just a plain image (has only one frame), -this function returns that image. If the animation is an animation, -this function returns a reasonable thing to display as a static -unanimated image, which might be the first frame, or something more -sophisticated. If an animation hasn't loaded any frames yet, this -function will return %NULL. + Retrieves a static image for the animation. + +If an animation is really just a plain image (has only one frame), +this function returns that image. + +If the animation is an animation, this function returns a reasonable +image to use as a static unanimated image, which might be the first +frame, or something more sophisticated depending on the file format. + +If an animation hasn't loaded any frames yet, this function will +return `NULL`. unanimated image representing the animation @@ -2640,12 +2869,14 @@ function will return %NULL. - If you load a file with gdk_pixbuf_animation_new_from_file() and it + Checks whether the animation is a static image. + +If you load a file with gdk_pixbuf_animation_new_from_file() and it turns out to be a plain, unanimated image, then this function will -return %TRUE. Use gdk_pixbuf_animation_get_static_image() to retrieve +return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve the image. - %TRUE if the "animation" was really just an image + `TRUE` if the "animation" was really just an image @@ -2669,9 +2900,10 @@ the image. - Get an iterator for displaying an animation. The iterator provides -the frames that should be displayed at a given time. It should be -freed after use with g_object_unref(). + Get an iterator for displaying an animation. + +The iterator provides the frames that should be displayed at a +given time. @start_time would normally come from g_get_current_time(), and marks the beginning of animation playback. After creating an iterator, you @@ -2683,7 +2915,7 @@ gdk_pixbuf_animation_iter_get_delay_time() milliseconds. Each time the image is updated, you should reinstall the timeout with the new, possibly-changed delay time. -As a shortcut, if @start_time is %NULL, the result of +As a shortcut, if @start_time is `NULL`, the result of g_get_current_time() will be used automatically. To update the image (i.e. possibly change the result of @@ -2694,14 +2926,14 @@ If you're using #GdkPixbufLoader, in addition to updating the image after the delay time, you should also update it whenever you receive the area_updated signal and gdk_pixbuf_animation_iter_on_currently_loading_frame() returns -%TRUE. In this case, the frame currently being fed into the loader +`TRUE`. In this case, the frame currently being fed into the loader has received new data, so needs to be refreshed. The delay time for a frame may also be modified after an area_updated signal, for example if the delay time for a frame is encoded in the data after the frame itself. So your timeout should be reinstalled after any area_updated signal. -A delay time of -1 is possible, indicating "infinite." +A delay time of -1 is possible, indicating "infinite". an iterator to move over the animation @@ -2718,12 +2950,17 @@ A delay time of -1 is possible, indicating "infinite." - If an animation is really just a plain image (has only one frame), -this function returns that image. If the animation is an animation, -this function returns a reasonable thing to display as a static -unanimated image, which might be the first frame, or something more -sophisticated. If an animation hasn't loaded any frames yet, this -function will return %NULL. + Retrieves a static image for the animation. + +If an animation is really just a plain image (has only one frame), +this function returns that image. + +If the animation is an animation, this function returns a reasonable +image to use as a static unanimated image, which might be the first +frame, or something more sophisticated depending on the file format. + +If an animation hasn't loaded any frames yet, this function will +return `NULL`. unanimated image representing the animation @@ -2749,12 +2986,14 @@ function will return %NULL. - If you load a file with gdk_pixbuf_animation_new_from_file() and it + Checks whether the animation is a static image. + +If you load a file with gdk_pixbuf_animation_new_from_file() and it turns out to be a plain, unanimated image, then this function will -return %TRUE. Use gdk_pixbuf_animation_get_static_image() to retrieve +return `TRUE`. Use gdk_pixbuf_animation_get_static_image() to retrieve the image. - %TRUE if the "animation" was really just an image + `TRUE` if the "animation" was really just an image @@ -2806,7 +3045,7 @@ virtual functions. - %TRUE if the "animation" was really just an image + `TRUE` if the "animation" was really just an image @@ -2869,11 +3108,13 @@ virtual functions. - An opaque struct representing an iterator which points to a + An opaque object representing an iterator which points to a certain position in an animation. - Possibly advances an animation to a new frame. Chooses the frame based -on the start time passed to gdk_pixbuf_animation_get_iter(). + Possibly advances an animation to a new frame. + +Chooses the frame based on the start time passed to +gdk_pixbuf_animation_get_iter(). @current_time would normally come from g_get_current_time(), and must be greater than or equal to the time passed to @@ -2882,17 +3123,17 @@ unchanged each time gdk_pixbuf_animation_iter_get_pixbuf() is called. That is, you can't go backward in time; animations only play forward. -As a shortcut, pass %NULL for the current time and g_get_current_time() +As a shortcut, pass `NULL` for the current time and g_get_current_time() will be invoked on your behalf. So you only need to explicitly pass @current_time if you're doing something odd like playing the animation at double speed. -If this function returns %FALSE, there's no need to update the animation +If this function returns `FALSE`, there's no need to update the animation display, assuming the display had been rendered prior to advancing; -if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf() +if `TRUE`, you need to call gdk_pixbuf_animation_iter_get_pixbuf() and update the display with the new pixbuf. - %TRUE if the image may need updating + `TRUE` if the image may need updating @@ -2908,9 +3149,10 @@ and update the display with the new pixbuf. Gets the number of milliseconds the current pixbuf should be displayed, -or -1 if the current pixbuf should be displayed forever. g_timeout_add() -conveniently takes a timeout in milliseconds, so you can use a timeout -to schedule the next update. +or -1 if the current pixbuf should be displayed forever. + +The `g_timeout_add()` function conveniently takes a timeout in milliseconds, +so you can use a timeout to schedule the next update. Note that some formats, like GIF, might clamp the timeout values in the image file to avoid updates that are just too quick. The minimum timeout @@ -2927,17 +3169,21 @@ for GIF images is currently 20 milliseconds. - Gets the current pixbuf which should be displayed; the pixbuf might not -be the same size as the animation itself + Gets the current pixbuf which should be displayed. + +The pixbuf might not be the same size as the animation itself (gdk_pixbuf_animation_get_width(), gdk_pixbuf_animation_get_height()). -This pixbuf should be displayed for -gdk_pixbuf_animation_iter_get_delay_time() milliseconds. The caller -of this function does not own a reference to the returned pixbuf; -the returned pixbuf will become invalid when the iterator advances -to the next frame, which may happen anytime you call -gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it -(don't just add a reference), as it may get recycled as you advance -the iterator. + +This pixbuf should be displayed for gdk_pixbuf_animation_iter_get_delay_time() +milliseconds. + +The caller of this function does not own a reference to the returned +pixbuf; the returned pixbuf will become invalid when the iterator +advances to the next frame, which may happen anytime you call +gdk_pixbuf_animation_iter_advance(). + +Copy the pixbuf to keep it (don't just add a reference), as it may get +recycled as you advance the iterator. the pixbuf to be displayed @@ -2951,12 +3197,13 @@ the iterator. Used to determine how to respond to the area_updated signal on -#GdkPixbufLoader when loading an animation. area_updated is emitted -for an area of the frame currently streaming in to the loader. So if -you're on the currently loading frame, you need to redraw the screen for -the updated area. +#GdkPixbufLoader when loading an animation. + +The `::area_updated` signal is emitted for an area of the frame currently +streaming in to the loader. So if you're on the currently loading frame, +you will need to redraw the screen for the updated area. - %TRUE if the frame we're on is partially loaded, or the last frame + `TRUE` if the frame we're on is partially loaded, or the last frame @@ -2967,8 +3214,10 @@ the updated area. - Possibly advances an animation to a new frame. Chooses the frame based -on the start time passed to gdk_pixbuf_animation_get_iter(). + Possibly advances an animation to a new frame. + +Chooses the frame based on the start time passed to +gdk_pixbuf_animation_get_iter(). @current_time would normally come from g_get_current_time(), and must be greater than or equal to the time passed to @@ -2977,17 +3226,17 @@ unchanged each time gdk_pixbuf_animation_iter_get_pixbuf() is called. That is, you can't go backward in time; animations only play forward. -As a shortcut, pass %NULL for the current time and g_get_current_time() +As a shortcut, pass `NULL` for the current time and g_get_current_time() will be invoked on your behalf. So you only need to explicitly pass @current_time if you're doing something odd like playing the animation at double speed. -If this function returns %FALSE, there's no need to update the animation +If this function returns `FALSE`, there's no need to update the animation display, assuming the display had been rendered prior to advancing; -if %TRUE, you need to call gdk_pixbuf_animation_iter_get_pixbuf() +if `TRUE`, you need to call gdk_pixbuf_animation_iter_get_pixbuf() and update the display with the new pixbuf. - %TRUE if the image may need updating + `TRUE` if the image may need updating @@ -3003,9 +3252,10 @@ and update the display with the new pixbuf. Gets the number of milliseconds the current pixbuf should be displayed, -or -1 if the current pixbuf should be displayed forever. g_timeout_add() -conveniently takes a timeout in milliseconds, so you can use a timeout -to schedule the next update. +or -1 if the current pixbuf should be displayed forever. + +The `g_timeout_add()` function conveniently takes a timeout in milliseconds, +so you can use a timeout to schedule the next update. Note that some formats, like GIF, might clamp the timeout values in the image file to avoid updates that are just too quick. The minimum timeout @@ -3022,17 +3272,21 @@ for GIF images is currently 20 milliseconds. - Gets the current pixbuf which should be displayed; the pixbuf might not -be the same size as the animation itself + Gets the current pixbuf which should be displayed. + +The pixbuf might not be the same size as the animation itself (gdk_pixbuf_animation_get_width(), gdk_pixbuf_animation_get_height()). -This pixbuf should be displayed for -gdk_pixbuf_animation_iter_get_delay_time() milliseconds. The caller -of this function does not own a reference to the returned pixbuf; -the returned pixbuf will become invalid when the iterator advances -to the next frame, which may happen anytime you call -gdk_pixbuf_animation_iter_advance(). Copy the pixbuf to keep it -(don't just add a reference), as it may get recycled as you advance -the iterator. + +This pixbuf should be displayed for gdk_pixbuf_animation_iter_get_delay_time() +milliseconds. + +The caller of this function does not own a reference to the returned +pixbuf; the returned pixbuf will become invalid when the iterator +advances to the next frame, which may happen anytime you call +gdk_pixbuf_animation_iter_advance(). + +Copy the pixbuf to keep it (don't just add a reference), as it may get +recycled as you advance the iterator. the pixbuf to be displayed @@ -3046,12 +3300,13 @@ the iterator. Used to determine how to respond to the area_updated signal on -#GdkPixbufLoader when loading an animation. area_updated is emitted -for an area of the frame currently streaming in to the loader. So if -you're on the currently loading frame, you need to redraw the screen for -the updated area. +#GdkPixbufLoader when loading an animation. + +The `::area_updated` signal is emitted for an area of the frame currently +streaming in to the loader. So if you're on the currently loading frame, +you will need to redraw the screen for the updated area. - %TRUE if the frame we're on is partially loaded, or the last frame + `TRUE` if the frame we're on is partially loaded, or the last frame @@ -3104,7 +3359,7 @@ virtual functions. - %TRUE if the frame we're on is partially loaded, or the last frame + `TRUE` if the frame we're on is partially loaded, or the last frame @@ -3118,7 +3373,7 @@ virtual functions. - %TRUE if the image may need updating + `TRUE` if the image may need updating @@ -3136,11 +3391,12 @@ virtual functions. A function of this type is responsible for freeing the pixel array -of a pixbuf. The gdk_pixbuf_new_from_data() function lets you -pass in a pre-allocated pixel array so that a pixbuf can be -created from it; in this case you will need to pass in a function -of #GdkPixbufDestroyNotify so that the pixel data can be freed -when the pixbuf is finalized. +of a pixbuf. + +The gdk_pixbuf_new_from_data() function lets you pass in a pre-allocated +pixel array so that a pixbuf can be created from it; in this case you +will need to pass in a function of type `GdkPixbufDestroyNotify` so that +the pixel data can be freed when the pixbuf is finalized. @@ -3159,9 +3415,10 @@ when the pixbuf is finalized. - An error code in the #GDK_PIXBUF_ERROR domain. Many gdk-pixbuf -operations can cause errors in this domain, or in the #G_FILE_ERROR -domain. + An error code in the `GDK_PIXBUF_ERROR` domain. + +Many gdk-pixbuf operations can cause errors in this domain, or in +the `G_FILE_ERROR` domain. An image file was broken somehow. @@ -3191,70 +3448,76 @@ domain. - A #GdkPixbufFormat contains information about the image format accepted by a -module. Only modules should access the fields directly, applications should -use the <function>gdk_pixbuf_format_*</function> functions. + A `GdkPixbufFormat` contains information about the image format accepted +by a module. + +Only modules should access the fields directly, applications should +use the `gdk_pixbuf_format_*` family of functions. - the name of the image format. + the name of the image format - the signature of the module. + the signature of the module - the message domain for the @description. + the message domain for the `description` - a description of the image format. + a description of the image format - a %NULL-terminated array of MIME types for the image format. - + the MIME types for the image format + + + - a %NULL-terminated array of typical filename extensions for the - image format. - + typical filename extensions for the + image format + + + - a combination of #GdkPixbufFormatFlags. + a combination of `GdkPixbufFormatFlags` - a boolean determining whether the loader is disabled. + a boolean determining whether the loader is disabled` a string containing license information, typically set to - shorthands like "GPL", "LGPL", etc. + shorthands like "GPL", "LGPL", etc. - Creates a copy of @format + Creates a copy of `format`. - the newly allocated copy of a #GdkPixbufFormat. Use + the newly allocated copy of a `GdkPixbufFormat`. Use gdk_pixbuf_format_free() to free the resources when done - a #GdkPixbufFormat + a pixbuf format - Frees the resources allocated when copying a #GdkPixbufFormat + Frees the resources allocated when copying a `GdkPixbufFormat` using gdk_pixbuf_format_copy() - a #GdkPixbufFormat + a pixbuf format @@ -3267,7 +3530,7 @@ using gdk_pixbuf_format_copy() - a #GdkPixbufFormat + a `GdkPixbufFormat` @@ -3276,31 +3539,31 @@ using gdk_pixbuf_format_copy() Returns the filename extensions typically used for files in the given format. - a %NULL-terminated array of filename extensions which must be -freed with g_strfreev() when it is no longer needed. + an array of + filename extensions - a #GdkPixbufFormat + a `GdkPixbufFormat` - Returns information about the license of the image loader for the format. The -returned string should be a shorthand for a wellknown license, e.g. "LGPL", -"GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. This -string should be freed with g_free() when it's no longer needed. + Returns information about the license of the image loader for the format. + +The returned string should be a shorthand for a well known license, e.g. +"LGPL", "GPL", "QPL", "GPL/QPL", or "other" to indicate some other license. - a string describing the license of @format. + a string describing the license of the pixbuf format - a #GdkPixbufFormat + a pixbuf format @@ -3308,15 +3571,14 @@ string should be freed with g_free() when it's no longer needed. Returns the mime types supported by the format. - a %NULL-terminated array of mime types which must be freed with -g_strfreev() when it is no longer needed. + an array of mime types - a #GdkPixbufFormat + a `GdkPixbufFormat` @@ -3329,36 +3591,38 @@ g_strfreev() when it is no longer needed. - a #GdkPixbufFormat + a `GdkPixbufFormat` - Returns whether this image format is disabled. See -gdk_pixbuf_format_set_disabled(). + Returns whether this image format is disabled. + +See gdk_pixbuf_format_set_disabled(). whether this image format is disabled. - a #GdkPixbufFormat + a `GdkPixbufFormat` - Returns %TRUE if the save option specified by @option_key is supported when + Returns `TRUE` if the save option specified by @option_key is supported when saving a pixbuf using the module implementing @format. + See gdk_pixbuf_save() for more information about option keys. - %TRUE if the specified option is supported + `TRUE` if the specified option is supported - a #GdkPixbufFormat + a pixbuf format @@ -3368,17 +3632,18 @@ See gdk_pixbuf_save() for more information about option keys. - Returns whether this image format is scalable. If a file is in a -scalable format, it is preferable to load it at the desired size, -rather than loading it at the default size and scaling the -resulting pixbuf to the desired size. + Returns whether this image format is scalable. + +If a file is in a scalable format, it is preferable to load it at +the desired size, rather than loading it at the default size and +scaling the resulting pixbuf to the desired size. whether this image format is scalable. - a #GdkPixbufFormat + a `GdkPixbufFormat` @@ -3391,26 +3656,29 @@ resulting pixbuf to the desired size. - a #GdkPixbufFormat + a `GdkPixbufFormat` - Disables or enables an image format. If a format is disabled, -gdk-pixbuf won't use the image loader for this format to load -images. Applications can use this to avoid using image loaders -with an inappropriate license, see gdk_pixbuf_format_get_license(). + Disables or enables an image format. + +If a format is disabled, GdkPixbuf won't use the image loader for +this format to load images. + +Applications can use this to avoid using image loaders with an +inappropriate license, see gdk_pixbuf_format_get_license(). - a #GdkPixbufFormat + a `GdkPixbufFormat` - %TRUE to disable the format @format + `TRUE` to disable the format @format @@ -3431,8 +3699,51 @@ operations. - The GdkPixbufLoader struct contains only private -fields. + Incremental image loader. + +`GdkPixbufLoader` provides a way for applications to drive the +process of loading an image, by letting them send the image data +directly to the loader instead of having the loader read the data +from a file. Applications can use this functionality instead of +`gdk_pixbuf_new_from_file()` or `gdk_pixbuf_animation_new_from_file()` +when they need to parse image data in small chunks. For example, +it should be used when reading an image from a (potentially) slow +network connection, or when loading an extremely large file. + +To use `GdkPixbufLoader` to load an image, create a new instance, +and call [method@GdkPixbuf.PixbufLoader.write] to send the data +to it. When done, [method@GdkPixbuf.PixbufLoader.close] should be +called to end the stream and finalize everything. + +The loader will emit three important signals throughout the process: + + - [signal@GdkPixbuf.PixbufLoader::size-prepared] will be emitted as + soon as the image has enough information to determine the size of + the image to be used. If you want to scale the image while loading + it, you can call [method@GdkPixbuf.PixbufLoader.set_size] in + response to this signal. + - [signal@GdkPixbuf.PixbufLoader::area-prepared] will be emitted as + soon as the pixbuf of the desired has been allocated. You can obtain + the `GdkPixbuf` instance by calling [method@GdkPixbuf.PixbufLoader.get_pixbuf]. + If you want to use it, simply acquire a reference to it. You can + also call `gdk_pixbuf_loader_get_pixbuf()` later to get the same + pixbuf. + - [signal@GdkPixbuf.PixbufLoader::area-updated] will be emitted every + time a region is updated. This way you can update a partially + completed image. Note that you do not know anything about the + completeness of an image from the updated area. For example, in an + interlaced image you will need to make several passes before the + image is done loading. + +## Loading an animation + +Loading an animation is almost as easy as loading an image. Once the +first [signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been +emitted, you can call [method@GdkPixbuf.PixbufLoader.get_animation] to +get the [class@GdkPixbuf.PixbufAnimation] instance, and then call +and [method@GdkPixbuf.PixbufAnimation.get_iter] to get a +[class@GdkPixbuf.PixbufAnimationIter] to retrieve the pixbuf for the +desired time stamp. Creates a new pixbuf loader object. @@ -3442,11 +3753,13 @@ fields. Creates a new pixbuf loader object that always attempts to parse -image data as if it were an image of mime type @mime_type, instead of -identifying the type automatically. Useful if you want an error if -the image isn't the expected mime type, for loading image formats -that can't be reliably identified by looking at the data, or if -the user manually forces a specific mime type. +image data as if it were an image of MIME type @mime_type, instead of +identifying the type automatically. + +This function is useful if you want an error if the image isn't the +expected MIME type; for loading image formats that can't be reliably +identified by looking at the data; or if the user manually forces a +specific MIME type. The list of supported mime types depends on what image loaders are installed, but typically "image/png", "image/jpeg", "image/gif", @@ -3468,10 +3781,12 @@ structs returned by gdk_pixbuf_get_formats(). Creates a new pixbuf loader object that always attempts to parse image data as if it were an image of type @image_type, instead of -identifying the type automatically. Useful if you want an error if -the image isn't the expected type, for loading image formats -that can't be reliably identified by looking at the data, or if -the user manually forces a specific type. +identifying the type automatically. + +This function is useful if you want an error if the image isn't the +expected type; for loading image formats that can't be reliably +identified by looking at the data; or if the user manually forces +a specific type. The list of supported image formats depends on what image loaders are installed, but typically "png", "jpeg", "gif", "tiff" and @@ -3550,19 +3865,22 @@ of the #GdkPixbufFormat structs returned by gdk_pixbuf_get_formats(). Informs a pixbuf loader that no further writes with gdk_pixbuf_loader_write() will occur, so that it can free its -internal loading structures. Also, tries to parse any data that -hasn't yet been parsed; if the remaining data is partial or -corrupt, an error will be returned. If %FALSE is returned, @error -will be set to an error from the #GDK_PIXBUF_ERROR or #G_FILE_ERROR -domains. If you're just cancelling a load rather than expecting it -to be finished, passing %NULL for @error to ignore it is -reasonable. +internal loading structures. -Remember that this does not unref the loader, so if you plan not to -use it anymore, please g_object_unref() it. +This function also tries to parse any data that hasn't yet been parsed; +if the remaining data is partial or corrupt, an error will be returned. + +If `FALSE` is returned, `error` will be set to an error from the +`GDK_PIXBUF_ERROR` or `G_FILE_ERROR` domains. + +If you're just cancelling a load rather than expecting it to be finished, +passing `NULL` for `error` to ignore it is reasonable. + +Remember that this function does not release a reference on the loader, so +you will need to explicitly release any reference you hold. - %TRUE if all image data written so far was successfully - passed out via the update_area signal + `TRUE` if all image data written so far was successfully + passed out via the update_area signal @@ -3574,13 +3892,16 @@ use it anymore, please g_object_unref() it. Queries the #GdkPixbufAnimation that a pixbuf loader is currently creating. -In general it only makes sense to call this function after the "area-prepared" -signal has been emitted by the loader. If the loader doesn't have enough -bytes yet (hasn't emitted the "area-prepared" signal) this function will -return %NULL. - - The #GdkPixbufAnimation that the loader is loading, or %NULL if -not enough data has been read to determine the information. + +In general it only makes sense to call this function after the +[signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been emitted by +the loader. + +If the loader doesn't have enough bytes yet, and hasn't emitted the `area-prepared` +signal, this function will return `NULL`. + + The animation that the loader is + currently loading @@ -3594,9 +3915,7 @@ not enough data has been read to determine the information. Obtains the available information about the format of the currently loading image file. - A #GdkPixbufFormat or -%NULL. The return value is owned by GdkPixbuf and should not be -freed. + A #GdkPixbufFormat @@ -3608,19 +3927,23 @@ freed. Queries the #GdkPixbuf that a pixbuf loader is currently creating. + In general it only makes sense to call this function after the -"area-prepared" signal has been emitted by the loader; this means -that enough data has been read to know the size of the image that -will be allocated. If the loader has not received enough data via -gdk_pixbuf_loader_write(), then this function returns %NULL. The -returned pixbuf will be the same in all future calls to the loader, -so simply calling g_object_ref() should be sufficient to continue -using it. Additionally, if the loader is an animation, it will -return the "static image" of the animation -(see gdk_pixbuf_animation_get_static_image()). - - The #GdkPixbuf that the loader is creating, or %NULL if not -enough data has been read to determine how to create the image buffer. +[signal@GdkPixbuf.PixbufLoader::area-prepared] signal has been +emitted by the loader; this means that enough data has been read +to know the size of the image that will be allocated. + +If the loader has not received enough data via gdk_pixbuf_loader_write(), +then this function returns `NULL`. + +The returned pixbuf will be the same in all future calls to the loader, +so if you want to keep using it, you should acquire a reference to it. + +Additionally, if the loader is an animation, it will return the "static +image" of the animation (see gdk_pixbuf_animation_get_static_image()). + + The pixbuf that the loader is + creating @@ -3631,9 +3954,10 @@ enough data has been read to determine how to create the image buffer. - Causes the image to be scaled while it is loaded. The desired -image size can be determined relative to the original size of -the image by calling gdk_pixbuf_loader_set_size() from a + Causes the image to be scaled while it is loaded. + +The desired image size can be determined relative to the original +size of the image by calling gdk_pixbuf_loader_set_size() from a signal handler for the ::size-prepared signal. Attempts to set the desired image size are ignored after the @@ -3657,15 +3981,10 @@ emission of the ::size-prepared signal. - This will cause a pixbuf loader to parse the next @count bytes of -an image. It will return %TRUE if the data was loaded successfully, -and %FALSE if an error occurred. In the latter case, the loader -will be closed, and will not accept further writes. If %FALSE is -returned, @error will be set to an error from the #GDK_PIXBUF_ERROR -or #G_FILE_ERROR domains. + Parses the next `count` bytes in the given image buffer. - %TRUE if the write was successful, or %FALSE if the loader -cannot parse the buffer. + `TRUE` if the write was successful, or + `FALSE` if the loader cannot parse the buffer @@ -3686,17 +4005,10 @@ cannot parse the buffer. - This will cause a pixbuf loader to parse a buffer inside a #GBytes -for an image. It will return %TRUE if the data was loaded successfully, -and %FALSE if an error occurred. In the latter case, the loader -will be closed, and will not accept further writes. If %FALSE is -returned, @error will be set to an error from the #GDK_PIXBUF_ERROR -or #G_FILE_ERROR domains. - -See also: gdk_pixbuf_loader_write() + Parses the next contents of the given image buffer. - %TRUE if the write was successful, or %FALSE if the loader -cannot parse the buffer. + `TRUE` if the write was successful, or `FALSE` if + the loader cannot parse the buffer @@ -3705,12 +4017,12 @@ cannot parse the buffer. - The image data as a #GBytes + The image data as a `GBytes` buffer. - + @@ -3718,18 +4030,23 @@ cannot parse the buffer. This signal is emitted when the pixbuf loader has allocated the -pixbuf in the desired size. After this signal is emitted, -applications can call gdk_pixbuf_loader_get_pixbuf() to fetch -the partially-loaded pixbuf. +pixbuf in the desired size. + +After this signal is emitted, applications can call +gdk_pixbuf_loader_get_pixbuf() to fetch the partially-loaded +pixbuf. This signal is emitted when a significant area of the image being -loaded has been updated. Normally it means that a complete -scanline has been read in, but it could be a different area as -well. Applications can use this signal to know when to repaint +loaded has been updated. + +Normally it means that a complete scanline has been read in, but +it could be a different area as well. + +Applications can use this signal to know when to repaint areas of an image that is being loaded. @@ -3755,6 +4072,7 @@ areas of an image that is being loaded. This signal is emitted when gdk_pixbuf_loader_close() is called. + It can be used by different parts of an application to receive notification when an image loader is closed by the code that drives it. @@ -3765,9 +4083,11 @@ drives it. This signal is emitted when the pixbuf loader has been fed the initial amount of data that is required to figure out the size -of the image that it will create. Applications can call -gdk_pixbuf_loader_set_size() in response to this signal to set -the desired size to which the image should be scaled. +of the image that it will create. + +Applications can call gdk_pixbuf_loader_set_size() in response +to this signal to set the desired size to which the image +should be scaled. @@ -3855,13 +4175,51 @@ the desired size to which the image should be scaled. - A #GdkPixbufModule contains the necessary functions to load and save + A `GdkPixbufModule` contains the necessary functions to load and save images in a certain file format. -A #GdkPixbufModule can be loaded dynamically from a #GModule. -Each loadable module must contain a #GdkPixbufModuleFillVtableFunc function -named <function>fill_vtable</function>, which will get called when the module -is loaded and must set the function pointers of the #GdkPixbufModule. +If `GdkPixbuf` has been compiled with `GModule` support, it can be extended +by modules which can load (and perhaps also save) new image and animation +formats. + +## Implementing modules + +The `GdkPixbuf` interfaces needed for implementing modules are contained in +`gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports +animations). They are not covered by the same stability guarantees as the +regular GdkPixbuf API. To underline this fact, they are protected by the +`GDK_PIXBUF_ENABLE_BACKEND` pre-processor symbol. + +Each loadable module must contain a `GdkPixbufModuleFillVtableFunc` function +named `fill_vtable`, which will get called when the module +is loaded and must set the function pointers of the `GdkPixbufModule`. + +In order to make format-checking work before actually loading the modules +(which may require calling `dlopen` to load image libraries), modules export +their signatures (and other information) via the `fill_info` function. An +external utility, `gdk-pixbuf-query-loaders`, uses this to create a text +file containing a list of all available loaders and their signatures. +This file is then read at runtime by `GdkPixbuf` to obtain the list of +available loaders and their signatures. + +Modules may only implement a subset of the functionality available via +`GdkPixbufModule`. If a particular functionality is not implemented, the +`fill_vtable` function will simply not set the corresponding +function pointers of the `GdkPixbufModule` structure. If a module supports +incremental loading (i.e. provides `begin_load`, `stop_load` and +`load_increment`), it doesn't have to implement `load`, since `GdkPixbuf` +can supply a generic `load` implementation wrapping the incremental loading. + +## Installing modules + +Installing a module is a two-step process: + + - copy the module file(s) to the loader directory (normally + `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the + environment variable `GDK_PIXBUF_MODULEDIR`) + - call `gdk-pixbuf-query-loaders` to update the module file (normally + `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden + by the environment variable `GDK_PIXBUF_MODULE_FILE`) the name of the module, usually the same as the usual file extension for images of this type, eg. "xpm", "jpeg" or "png". @@ -3872,11 +4230,11 @@ is loaded and must set the function pointers of the #GdkPixbufModule. - the loaded #GModule. + the loaded `GModule`. - a #GdkPixbufFormat holding information about the module. + a `GdkPixbufFormat` holding information about the module. @@ -4079,11 +4437,14 @@ is loaded and must set the function pointers of the #GdkPixbufModule. - The signature of a module is a set of prefixes. Prefixes are encoded as + The signature prefix for a module. + +The signature of a module is a set of prefixes. Prefixes are encoded as pairs of ordinary strings, where the second string, called the mask, if -not %NULL, must be of the same length as the first one and may contain +not `NULL`, must be of the same length as the first one and may contain ' ', '!', 'x', 'z', and 'n' to indicate bytes that must be matched, -not matched, "don't-care"-bytes, zeros and non-zeros. +not matched, "don't-care"-bytes, zeros and non-zeros, respectively. + Each prefix has an associated integer that describes the relevance of the prefix, with 0 meaning a mismatch and 100 a "perfect match". @@ -4093,19 +4454,19 @@ but also in the middle. Versions prior to 2.8 will interpret the '*' like an 'x'. The signature of a module is stored as an array of -#GdkPixbufModulePatterns. The array is terminated by a pattern -where the @prefix is %NULL. +`GdkPixbufModulePatterns`. The array is terminated by a pattern +where the `prefix` is `NULL`. - -<informalexample><programlisting> +```c GdkPixbufModulePattern *signature[] = { { "abcdx", " !x z", 100 }, { "bla", NULL, 90 }, { NULL, NULL, 0 } }; -</programlisting> -The example matches e.g. "auud\0" with relevance 100, and "blau" with -relevance 90.</informalexample> +``` + +In the example above, the signature matches e.g. "auud\0" with +relevance 100, and "blau" with relevance 90. the prefix for this pattern @@ -4228,6 +4589,7 @@ signal. The possible rotations which can be passed to gdk_pixbuf_rotate_simple(). + To make them easier to use, their numerical values are the actual degrees. No rotation. @@ -4243,14 +4605,16 @@ To make them easier to use, their numerical values are the actual degrees. - Specifies the type of the function passed to -gdk_pixbuf_save_to_callback(). It is called once for each block of -bytes that is "written" by gdk_pixbuf_save_to_callback(). If -successful it should return %TRUE. If an error occurs it should set -@error and return %FALSE, in which case gdk_pixbuf_save_to_callback() + Save functions used by [method@GdkPixbuf.Pixbuf.save_to_callback]. + +This function is called once for each block of bytes that is "written" +by `gdk_pixbuf_save_to_callback()`. + +If successful it should return `TRUE`; if an error occurs it should set +`error` and return `FALSE`, in which case `gdk_pixbuf_save_to_callback()` will fail with the same error. - %TRUE if successful, %FALSE (with @error set) if failed. + `TRUE` if successful, `FALSE` otherwise @@ -4352,292 +4716,10 @@ was constructed. - - The GdkPixBuf library provides a simple mechanism to load and -represent animations. An animation is conceptually a series of -frames to be displayed over time. The animation may not be -represented as a series of frames internally; for example, it may -be stored as a sprite and instructions for moving the sprite around -a background. To display an animation you don't need to understand -its representation, however; you just ask GdkPixBuf what should -be displayed at a given point in time. - - - The most basic way to create a pixbuf is to wrap an existing pixel -buffer with a #GdkPixbuf structure. You can use the -gdk_pixbuf_new_from_data() function to do this You need to specify -the destroy notification function that will be called when the -data buffer needs to be freed; this will happen when a #GdkPixbuf -is finalized by the reference counting functions If you have a -chunk of static data compiled into your application, you can pass -in %NULL as the destroy notification function so that the data -will not be freed. - -The gdk_pixbuf_new() function can be used as a convenience to -create a pixbuf with an empty buffer. This is equivalent to -allocating a data buffer using malloc() and then wrapping it with -gdk_pixbuf_new_from_data(). The gdk_pixbuf_new() function will -compute an optimal rowstride so that rendering can be performed -with an efficient algorithm. - -As a special case, you can use the gdk_pixbuf_new_from_xpm_data() -function to create a pixbuf from inline XPM image data. - -You can also copy an existing pixbuf with the gdk_pixbuf_copy() -function. This is not the same as just doing a g_object_ref() -on the old pixbuf; the copy function will actually duplicate the -pixel data in memory and create a new #GdkPixbuf structure for it. - - - The GdkPixBuf library provides a simple mechanism for loading -an image from a file in synchronous fashion. This means that the -library takes control of the application while the file is being -loaded; from the user's point of view, the application will block -until the image is done loading. - - -This interface can be used by applications in which blocking is -acceptable while an image is being loaded. It can also be used to -load small images in general. Applications that need progressive -loading can use the #GdkPixbufLoader functionality instead. - - - These functions allow to save a #GdkPixbuf in a number of -file formats. The formatted data can be written to a file -or to a memory buffer. GdkPixBuf can also call a user-defined -callback on the data, which allows to e.g. write the image -to a socket or store it in a database. - - - The #GdkPixbuf structure contains -information that describes an image in memory. - -## Image Data ## {#image-data} - -Image data in a pixbuf is stored in memory in uncompressed, -packed format. Rows in the image are stored top to bottom, and -in each row pixels are stored from left to right. There may be -padding at the end of a row. The "rowstride" value of a pixbuf, -as returned by gdk_pixbuf_get_rowstride(), indicates the number -of bytes between rows. - -## put_pixel() Example ## {#put-pixel} - -The following code illustrates a simple put_pixel() -function for RGB pixbufs with 8 bits per channel with an alpha -channel. It is not included in the gdk-pixbuf library for -performance reasons; rather than making several function calls -for each pixel, your own code can take shortcuts. - -|[<!-- language="C" --> -static void -put_pixel (GdkPixbuf *pixbuf, int x, int y, guchar red, guchar green, guchar blue, guchar alpha) -{ - int width, height, rowstride, n_channels; - guchar *pixels, *p; - - n_channels = gdk_pixbuf_get_n_channels (pixbuf); - - g_assert (gdk_pixbuf_get_colorspace (pixbuf) == GDK_COLORSPACE_RGB); - g_assert (gdk_pixbuf_get_bits_per_sample (pixbuf) == 8); - g_assert (gdk_pixbuf_get_has_alpha (pixbuf)); - g_assert (n_channels == 4); - - width = gdk_pixbuf_get_width (pixbuf); - height = gdk_pixbuf_get_height (pixbuf); - - g_assert (x >= 0 && x < width); - g_assert (y >= 0 && y < height); - - rowstride = gdk_pixbuf_get_rowstride (pixbuf); - pixels = gdk_pixbuf_get_pixels (pixbuf); - - p = pixels + y * rowstride + x * n_channels; - p[0] = red; - p[1] = green; - p[2] = blue; - p[3] = alpha; -} -]| - -This function will not work for pixbufs with images that are -other than 8 bits per sample or channel, but it will work for -most of the pixbufs that GTK+ uses. - -If you are doing memcpy() of raw pixbuf data, note that the last row -in the pixbuf may not be as wide as the full rowstride, but rather -just as wide as the pixel data needs to be. That is, it is unsafe to -do `memcpy (dest, pixels, rowstride * height)` to copy a whole pixbuf. -Use gdk_pixbuf_copy() instead, or compute the width in bytes of the -last row as `width * ((n_channels * bits_per_sample + 7) / 8)`. - - - #GdkPixbufLoader provides a way for applications to drive the -process of loading an image, by letting them send the image data -directly to the loader instead of having the loader read the data -from a file. Applications can use this functionality instead of -gdk_pixbuf_new_from_file() or gdk_pixbuf_animation_new_from_file() -when they need to parse image data in -small chunks. For example, it should be used when reading an -image from a (potentially) slow network connection, or when -loading an extremely large file. - - -To use #GdkPixbufLoader to load an image, just create a new one, and -call gdk_pixbuf_loader_write() to send the data to it. When done, -gdk_pixbuf_loader_close() should be called to end the stream and -finalize everything. The loader will emit three important signals -throughout the process. The first, #GdkPixbufLoader::size-prepared, -will be emitted as soon as the image has enough information to -determine the size of the image to be used. If you want to scale -the image while loading it, you can call gdk_pixbuf_loader_set_size() -in response to this signal. - - -The second signal, #GdkPixbufLoader::area-prepared, will be emitted as -soon as the pixbuf of the desired has been allocated. You can obtain it -by calling gdk_pixbuf_loader_get_pixbuf(). If you want to use it, simply -ref it. You can also call gdk_pixbuf_loader_get_pixbuf() later and get -the same pixbuf. - -The last signal, #GdkPixbufLoader::area-updated, gets emitted every time -a region is updated. This way you can update a partially completed image. -Note that you do not know anything about the completeness of an image -from the updated area. For example, in an interlaced image, you need to -make several passes before the image is done loading. - -# Loading an animation - -Loading an animation is almost as easy as loading an image. Once the first -#GdkPixbufLoader::area-prepared signal has been emitted, you can call -gdk_pixbuf_loader_get_animation() to get the #GdkPixbufAnimation struct -and gdk_pixbuf_animation_get_iter() to get a #GdkPixbufAnimationIter for -displaying it. - - - These macros and variables let you check the version of gdk-pixbuf -you're linking against. - - - Using #GdkPixdata, images can be compiled into an application, -making it unnecessary to refer to external image files at runtime. -GdkPixBuf includes a utility named gdk-pixbuf-csource, which -can be used to convert image files into #GdkPixdata structures suitable -for inclusion in C sources. To convert the #GdkPixdata structures back -into #GdkPixbufs, use gdk_pixbuf_from_pixdata. - -#GdkPixdata should not be used any more. #GResource should be used to save -the original compressed images inside the program's binary. - - - If GdkPixBuf has been compiled with GModule support, it can be extended by -modules which can load (and perhaps also save) new image and animation -formats. Each loadable module must export a -#GdkPixbufModuleFillInfoFunc function named `fill_info` and -a #GdkPixbufModuleFillVtableFunc function named -`fill_vtable`. - -In order to make format-checking work before actually loading the modules -(which may require dlopening image libraries), modules export their -signatures (and other information) via the `fill_info` function. An -external utility, gdk-pixbuf-query-loaders, uses this to create a text -file containing a list of all available loaders and their signatures. -This file is then read at runtime by GdkPixBuf to obtain the list of -available loaders and their signatures. - -Modules may only implement a subset of the functionality available via -#GdkPixbufModule. If a particular functionality is not implemented, the -`fill_vtable` function will simply not set the corresponding -function pointers of the #GdkPixbufModule structure. If a module supports -incremental loading (i.e. provides #begin_load, #stop_load and -#load_increment), it doesn't have to implement #load, since GdkPixBuf can -supply a generic #load implementation wrapping the incremental loading. - -Installing a module is a two-step process: -- copy the module file(s) to the loader directory (normally - `$libdir/gdk-pixbuf-2.0/$version/loaders`, unless overridden by the - environment variable `GDK_PIXBUF_MODULEDIR`) -- call gdk-pixbuf-query-loaders to update the module file (normally - `$libdir/gdk-pixbuf-2.0/$version/loaders.cache`, unless overridden by the - environment variable `GDK_PIXBUF_MODULE_FILE`) - -The GdkPixBuf interfaces needed for implementing modules are contained in -`gdk-pixbuf-io.h` (and `gdk-pixbuf-animation.h` if the module supports -animations). They are not covered by the same stability guarantees as the -regular GdkPixBuf API. To underline this fact, they are protected by -`#ifdef GDK_PIXBUF_ENABLE_BACKEND`. - - - #GdkPixbuf structures are reference counted. This means that an -application can share a single pixbuf among many parts of the -code. When a piece of the program needs to keep a pointer to a -pixbuf, it should add a reference to it by calling g_object_ref(). -When it no longer needs the pixbuf, it should subtract a reference -by calling g_object_unref(). The pixbuf will be destroyed when -its reference count drops to zero. Newly-created #GdkPixbuf -structures start with a reference count of one. - -> As #GdkPixbuf is derived from #GObject now, gdk_pixbuf_ref() and -> gdk_pixbuf_unref() are deprecated in favour of g_object_ref() -> and g_object_unref() resp. - -Finalizing a pixbuf means to free its pixel data and to free the -#GdkPixbuf structure itself. Most of the library functions that -create #GdkPixbuf structures create the pixel data by themselves -and define the way it should be freed; you do not need to worry -about those. - -To provide preallocated pixel data, use -gdk_pixbuf_new_from_bytes(). The gdk_pixbuf_new_from_data() API is -an older variant that predates the existence of #GBytes. - - - The GdkPixBuf contains functions to scale pixbufs, to scale -pixbufs and alpha blend against an existing image, and to scale -pixbufs and alpha blend against a solid color or checkerboard. -Alpha blending a checkerboard is a common way to show an image with -an alpha channel in image-viewing and editing software. - -Note that in these functions, the terms ‘alpha blending’ and ‘compositing’ -are used synonymously. - -Since the full-featured functions (gdk_pixbuf_scale(), -gdk_pixbuf_composite(), and gdk_pixbuf_composite_color()) are -rather complex to use and have many arguments, two simple -convenience functions are provided, gdk_pixbuf_scale_simple() and -gdk_pixbuf_composite_color_simple() which create a new pixbuf of a -given size, scale an original image to fit, and then return the -new pixbuf. - -If the destination pixbuf was created from a readonly source, these -operations will force a copy into a mutable buffer. - -Scaling and alpha blending functions take advantage of MMX hardware -acceleration on systems where MMX is supported. If gdk-pixbuf is built -with the Sun mediaLib library, these functions are instead accelerated -using mediaLib, which provides hardware acceleration on Intel, AMD, -and Sparc chipsets. If desired, mediaLib support can be turned off by -setting the `GDK_DISABLE_MEDIALIB` environment variable. - -The alpha blending function used is: - -|[<!-- language="plain" --> -Cd = Cs·As + Cd(1-As) -]| - -where `Cd` is the destination pixel color, `Cs` is the source pixel color, -and `As` is the source pixel alpha. - - - These functions provide miscellaneous utilities for manipulating -pixbufs. The pixel data in pixbufs may of course be manipulated -directly by applications, but several common operations can be -performed by these functions instead. - diff --git a/GdkPixdata-2.0.gir b/GdkPixdata-2.0.gir index 183a7a6..363d298 100644 --- a/GdkPixdata-2.0.gir +++ b/GdkPixdata-2.0.gir @@ -11,59 +11,73 @@ and/or use gtk-doc annotations. --> Magic number for #GdkPixdata structures. - + The length of a #GdkPixdata structure without the @pixel_data pointer. - - A #GdkPixdata contains pixbuf information in a form suitable for -serialization and streaming. + + A pixel buffer suitable for serialization and streaming. + +Using `GdkPixdata`, images can be compiled into an application, +making it unnecessary to refer to external image files at runtime. + +`GdkPixbuf` includes a utility named `gdk-pixbuf-csource`, which +can be used to convert image files into `GdkPixdata` structures suitable +for inclusion in C sources. To convert the `GdkPixdata` structures back +into a `GdkPixbuf`, use `gdk_pixbuf_from_pixdata()`. + `GdkPixdata` should not be used any more. `GResource` + should be used to save the original compressed images inside the + program's binary - magic number. A valid #GdkPixdata structure must have - #GDK_PIXBUF_MAGIC_NUMBER here. + magic number. A valid `GdkPixdata` structure must have + `GDK_PIXBUF_MAGIC_NUMBER` here less than 1 to disable length checks, otherwise - #GDK_PIXDATA_HEADER_LENGTH + length of @pixel_data. + `GDK_PIXDATA_HEADER_LENGTH` plus the length of `pixel_data` information about colorspace, sample width and - encoding, in a #GdkPixdataType. + encoding, in a `GdkPixdataType` - Distance in bytes between rows. + Distance in bytes between rows - Width of the image in pixels. + Width of the image in pixels - Height of the image in pixels. + Height of the image in pixels - @width x @height pixels, encoded according to @pixdata_type - and @rowstride. + `width` x `height` + pixels, encoded according to `pixdata_type` and `rowstride` Deserializes (reconstruct) a #GdkPixdata structure from a byte stream. + The byte stream consists of a straightforward writeout of the -#GdkPixdata fields in network byte order, plus the @pixel_data +`GdkPixdata` fields in network byte order, plus the `pixel_data` bytes the structure points to. -The @pixdata contents are reconstructed byte by byte and are checked -for validity. This function may fail with %GDK_PIXBUF_ERROR_CORRUPT_IMAGE -or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE. - Use #GResource instead. + +The `pixdata` contents are reconstructed byte by byte and are checked +for validity. + +This function may fail with `GDK_PIXBUF_ERROR_CORRUPT_IMAGE` +or `GDK_PIXBUF_ERROR_UNKNOWN_TYPE`. + Use `GResource` instead. - Upon successful deserialization %TRUE is returned, -%FALSE otherwise. + Upon successful deserialization `TRUE` is returned, +`FALSE` otherwise. @@ -85,23 +99,26 @@ or %GDK_PIXBUF_ERROR_UNKNOWN_TYPE. - Converts a #GdkPixbuf to a #GdkPixdata. If @use_rle is %TRUE, the -pixel data is run-length encoded into newly-allocated memory and a -pointer to that memory is returned. + Converts a `GdkPixbuf` to a `GdkPixdata`. + +If `use_rle` is `TRUE`, the pixel data is run-length encoded into +newly-allocated memory and a pointer to that memory is returned. Use #GResource instead. - If @use_rle is %TRUE, a pointer to the - newly-allocated memory for the run-length encoded pixel data, - otherwise %NULL. - + If `use_rle` is + `TRUE`, a pointer to the newly-allocated memory for the run-length + encoded pixel data, otherwise `NULL`. + + + - a #GdkPixdata to fill. + a `GdkPixdata` to fill. - the data to fill @pixdata with. + the data to fill `pixdata` with. @@ -139,33 +156,31 @@ structure. Generates C source code suitable for compiling images directly into programs. -gdk-pixbuf ships with a program called -[gdk-pixbuf-csource][gdk-pixbuf-csource], which offers a command -line interface to this function. +GdkPixbuf ships with a program called `gdk-pixbuf-csource`, which offers +a command line interface to this function. Use #GResource instead. - a newly-allocated string containing the C source form - of @pixdata. + a newly-allocated string buffer containing + the C source form of `pixdata`. - a #GdkPixdata to convert to C source. + a `GdkPixdata` to convert to C source - used for naming generated data structures or macros. + used for naming generated data structures or macros - a #GdkPixdataDumpType determining the kind of C - source to be generated. + the kind of C source to be generated - + An enumeration which is used by gdk_pixdata_to_csource() to determine the form of C source to be generated. The three values @GDK_PIXDATA_DUMP_PIXDATA_STREAM, @GDK_PIXDATA_DUMP_PIXDATA_STRUCT @@ -207,7 +222,7 @@ elements are optional flags that can be freely added. macro definition to decode run-length encoded image data. - + An enumeration containing three sets of flags for a #GdkPixdata struct: one for the used colorspace, one for the width of the samples and one for the encoding of the pixel data. @@ -241,34 +256,25 @@ for the encoding of the pixel data. mask for the encoding flags of the enum. - - Using #GdkPixdata, images can be compiled into an application, -making it unnecessary to refer to external image files at runtime. -GdkPixBuf includes a utility named gdk-pixbuf-csource, which -can be used to convert image files into #GdkPixdata structures suitable -for inclusion in C sources. To convert the #GdkPixdata structures back -into #GdkPixbufs, use gdk_pixbuf_from_pixdata. - -#GdkPixdata should not be used any more. #GResource should be used to save -the original compressed images inside the program's binary. - - Converts a #GdkPixdata to a #GdkPixbuf. If @copy_pixels is %TRUE or -if the pixel data is run-length-encoded, the pixel data is copied into -newly-allocated memory; otherwise it is reused. - Use #GResource instead. + Converts a `GdkPixdata` to a `GdkPixbuf`. + +If `copy_pixels` is `TRUE` or if the pixel data is run-length-encoded, +the pixel data is copied into newly-allocated memory; otherwise it is +reused. + Use `GResource` instead. - a new #GdkPixbuf. + a new pixbuf - a #GdkPixdata to convert into a #GdkPixbuf. + a #GdkPixdata to convert into a `GdkPixbuf`. whether to copy raw pixel data; run-length encoded - pixel data is always copied. + pixel data is always copied. diff --git a/GdkX11-3.0.gir b/GdkX11-3.0.gir index 350453b..724d503 100644 --- a/GdkX11-3.0.gir +++ b/GdkX11-3.0.gir @@ -1754,5 +1754,33 @@ gdk_x11_grab_server(). + + The functions in this section are specific to the GDK X11 backend. +To use them, you need to include the `<gdk/gdkx.h>` header and use +the X11-specific pkg-config files to build your application (either +`gdk-x11-3.0` or `gtk+-x11-3.0`). + +To make your code compile with other GDK backends, guard backend-specific +calls by an ifdef as follows. Since GDK may be built with multiple +backends, you should also check for the backend that is in use (e.g. by +using the GDK_IS_X11_DISPLAY() macro). +|[ +#ifdef GDK_WINDOWING_X11 + if (GDK_IS_X11_DISPLAY (display)) + { + // make X11-specific calls here + } + else +#endif +#ifdef GDK_WINDOWING_QUARTZ + if (GDK_IS_QUARTZ_DISPLAY (display)) + { + // make Quartz-specific calls here + } + else +#endif + g_error ("Unsupported GDK backend"); +]| + diff --git a/Gio-2.0.gir b/Gio-2.0.gir index 6c39646..3a15de3 100644 --- a/Gio-2.0.gir +++ b/Gio-2.0.gir @@ -486,7 +486,7 @@ If the @value GVariant is floating, it is consumed. - + Checks if @action is currently enabled. An action must be enabled in order to be activated or in order to @@ -502,7 +502,7 @@ have its state changed from outside callers. - + Queries the name of @action. the name of the action @@ -515,7 +515,7 @@ have its state changed from outside callers. - + Queries the type of the parameter that must be given when activating @action. @@ -535,7 +535,7 @@ In the case that this function returns %NULL, you must not give any - + Queries the current state of @action. If the action is not stateful then %NULL will be returned. If the @@ -585,7 +585,7 @@ g_variant_unref() when it is no longer required. - + Queries the type of the state of @action. If the action is stateful (e.g. created with @@ -609,29 +609,29 @@ will return %NULL and you must not call g_action_change_state(). - + If @action is currently enabled. If the action is disabled then calls to g_action_activate() and g_action_change_state() have no effect. - + The name of the action. This is mostly meaningful for identifying the action once it has been added to a #GActionGroup. It is immutable. - + The type of the parameter that must be given when activating the action. This is immutable, and may be %NULL if no parameter is needed when activating the action. - + The state of the action, or %NULL if the action is stateless. - + The #GVariantType of the state that the action has, or %NULL if the action is stateless. This is immutable. @@ -3495,16 +3495,16 @@ list available applications. Flags used when creating a #GAppInfo. - + No flags. - + Application opens in a terminal window. - + Application supports URI arguments. - + Application supports startup notification. Since 2.26 @@ -4477,13 +4477,13 @@ vfunc, to parse them in either the primary instance or the local instance, respectively. For an example of opening files with a GApplication, see -[gapplication-example-open.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-open.c). +[gapplication-example-open.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-open.c). For an example of using actions with GApplication, see -[gapplication-example-actions.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-actions.c). +[gapplication-example-actions.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-actions.c). For an example of using extra D-Bus hooks with GApplication, see -[gapplication-example-dbushooks.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-dbushooks.c). +[gapplication-example-dbushooks.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-dbushooks.c). @@ -5017,7 +5017,7 @@ finalized. - + Gets the unique identifier for @application. the identifier for @application, owned by @application @@ -5081,7 +5081,7 @@ registered. See g_application_get_is_registered(). - + Gets the flags for @application. See #GApplicationFlags. @@ -5096,7 +5096,7 @@ See #GApplicationFlags. - + Gets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to @@ -5112,7 +5112,7 @@ g_application_release() before the application stops running. - + Gets the application's current busy state, as set through g_application_mark_busy() or g_application_bind_busy_property(). @@ -5126,7 +5126,7 @@ g_application_mark_busy() or g_application_bind_busy_property(). - + Checks if @application is registered. An application is registered if g_application_register() has been @@ -5142,7 +5142,7 @@ successfully called. - + Checks if @application is remote. If @application is remote then it means that another instance of @@ -5164,7 +5164,7 @@ g_application_get_is_registered(). - + Gets the resource base path of @application. See g_application_set_resource_base_path() for more information. @@ -5207,7 +5207,9 @@ The busy state will be exposed to other processes, so a session shell will use that information to indicate the state to the user (e.g. with a spinner). -To cancel the busy indication, use g_application_unmark_busy(). +To cancel the busy indication, use g_application_unmark_busy(). + +The application must be registered before calling this function. @@ -5383,7 +5385,7 @@ commandline then you should implement your own #GApplication subclass and override local_command_line(). In this case, you most likely want to return %TRUE from your local_command_line() implementation to suppress the default handling. See -[gapplication-example-cmdline2.c][gapplication-example-cmdline2] +[gapplication-example-cmdline2.c][https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c] for an example. If, after the above is done, the use count of the application is zero @@ -5487,7 +5489,7 @@ g_application_withdraw_notification(). - + This used to be how actions were associated with a #GApplication. Now there is #GActionMap for that. Use the #GActionMap interface instead. Never ever @@ -5509,7 +5511,7 @@ action group), so you should really use #GActionMap instead. - + Sets the unique identifier for @application. The application id can only be modified if @application has not yet @@ -5548,7 +5550,7 @@ back to %NULL. - + Sets the flags for @application. The flags can only be modified if @application has not yet been @@ -5569,7 +5571,7 @@ See #GApplicationFlags. - + Sets the current inactivity timeout for the application. This is the amount of time (in milliseconds) after the last call to @@ -5652,7 +5654,7 @@ See g_option_context_set_summary() for more information. - + Sets (or unsets) the base resource path of @application. The path is used to automatically load various [application @@ -5768,30 +5770,30 @@ there is no need to explicitly withdraw the notification in that case. - + - + - + - + - + Whether the application is currently marked as busy through g_application_mark_busy() or g_application_bind_busy_property(). - + - + - + @@ -6236,7 +6238,7 @@ command_line (GApplication *application, } ]| The complete example can be found here: -[gapplication-example-cmdline.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline.c) +[gapplication-example-cmdline.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline.c) In more complicated cases, the handling of the comandline can be split between the launcher and the primary instance. @@ -6287,7 +6289,7 @@ to the #GApplication::command-line handler which runs in the primary instance. The complete example can be found here: -[gapplication-example-cmdline2.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline2.c) +[gapplication-example-cmdline2.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline2.c) If handling the commandline requires a lot of work, it may be better to defer it. @@ -6329,7 +6331,7 @@ later (in this example, in an idle). Note that it is necessary to hold the application until you are done with the commandline. The complete example can be found here: -[gapplication-example-cmdline3.c](https://git.gnome.org/browse/glib/tree/gio/tests/gapplication-example-cmdline3.c) +[gapplication-example-cmdline3.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gapplication-example-cmdline3.c) Gets the stdin of the invoking process. @@ -6494,7 +6496,7 @@ g_application_command_line_set_exit_status() for more information. - + Determines if @cmdline represents a remote invocation. %TRUE if the invocation was remote @@ -6686,7 +6688,7 @@ status of the local #GApplicationCommandLine is used. - + @@ -6761,32 +6763,32 @@ contains private data only. Flags used to define the behaviour of a #GApplication. - + Default - + Run as a service. In this mode, registration fails if the service is already running, and the application will initially wait up to 10 seconds for an initial activation message to arrive. - + Don't try to become the primary instance. - + This application handles opening files (in the primary instance). Note that this flag only affects the default implementation of local_command_line(), and has no effect if %G_APPLICATION_HANDLES_COMMAND_LINE is given. See g_application_run() for details. - + This application handles command line arguments (in the primary instance). Note that this flag only affect the default implementation of local_command_line(). See g_application_run() for details. - + Send the environment of the launching process to the primary instance. Set this flag if your application is expected to behave differently depending on certain @@ -6796,7 +6798,7 @@ contains private data only. to the #GApplication::command-line signal handler, via g_application_command_line_getenv(). - + Make no attempts to do any of the typical single-instance application negotiation, even if the application ID is given. The application neither attempts to become the @@ -6804,16 +6806,16 @@ contains private data only. owner already exists. Everything occurs in the local process. Since: 2.30. - + Allow users to override the application ID from the command line with `--gapplication-app-id`. Since: 2.48 - + Allow another instance to take over the bus name. Since: 2.60 - + Take over from another instance. This flag is usually set by passing `--gapplication-replace` on the commandline. Since: 2.60 @@ -6824,22 +6826,22 @@ contains private data only. #GAskPasswordFlags are used to request specific information from the user, or to notify the user of their choices in an authentication situation. - + operation requires a password. - + operation requires a username. - + operation requires a domain. - + operation supports saving settings. - + operation supports anonymous users. - + operation takes TCRYPT parameters (Since: 2.58) @@ -7323,7 +7325,11 @@ iteration of the [thread-default main context][g-main-context-push-thread-default] where the #GTask was created. All other users of #GAsyncReadyCallback must likewise call it asynchronously in a -later iteration of the main context. +later iteration of the main context. + +The asynchronous operation is guaranteed to have held a reference to +@source_object from the time when the `*_async()` function was called, until +after this callback returns. @@ -7899,7 +7905,7 @@ of bytes that are required to fill the buffer. - + Gets the size of the input buffer. the current buffer size. @@ -7992,7 +7998,7 @@ On error -1 is returned and @error is set accordingly. - + Sets the size of the internal buffer of @stream to @size, or to the size of the contents of the buffer. The buffer can never be resized smaller than its current contents. @@ -8010,7 +8016,7 @@ smaller than its current contents. - + @@ -8181,7 +8187,7 @@ size cannot be reduced below the size of the data within the buffer. - + Checks if the buffer automatically grows as data is added. %TRUE if the @stream's buffer automatically grows, @@ -8195,7 +8201,7 @@ size cannot be reduced below the size of the data within the buffer. - + Gets the size of the buffer in the @stream. the current size of the buffer. @@ -8208,7 +8214,7 @@ size cannot be reduced below the size of the data within the buffer. - + Sets whether or not the @stream's buffer should automatically grow. If @auto_grow is true, then each write will just make the buffer larger, and you must manually flush the buffer to actually write out @@ -8227,7 +8233,7 @@ the data to the underlying stream. - + Sets the size of the internal buffer to @size. @@ -8243,10 +8249,10 @@ the data to the underlying stream. - + - + @@ -8363,17 +8369,17 @@ the connection was disconnected. Flags used in g_bus_own_name(). - + No flags set. - + Allow another message bus connection to claim the name. - + If another message bus connection owns the name and have specified #G_BUS_NAME_OWNER_FLAGS_ALLOW_REPLACEMENT, then take the name from the other connection. - + If another message bus connection owns the name, immediately return an error from g_bus_own_name() rather than entering the waiting queue for that name. (Since 2.54) @@ -8405,10 +8411,10 @@ established has been closed. In that case, @connection will be Flags used in g_bus_watch_name(). - + No flags set. - + If no-one owns the name when beginning to watch the name, ask the bus to launch an owner for the name. @@ -8416,16 +8422,16 @@ name. An enumeration for well-known message buses. - + An alias for the message bus that activated the process, if any. - + Not a message bus. - + The system-wide message bus. - + The login session message bus. @@ -8451,7 +8457,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + Gets the #GBytes associated with the given @icon. a #GBytes. @@ -8464,7 +8470,7 @@ This cannot fail, but loading and interpreting the bytes may fail later on - + The bytes containing the icon. @@ -9059,7 +9065,7 @@ GIConv. - + Gets the #GCharsetConverter:use-fallback property. %TRUE if fallbacks are used by @converter @@ -9072,7 +9078,7 @@ GIConv. - + Sets the #GCharsetConverter:use-fallback property. @@ -9094,7 +9100,7 @@ GIConv. - + @@ -9398,13 +9404,13 @@ state that would produce output then that output is lost. Flags used when calling a g_converter_convert(). - + No flags. - + At end of input data - + Flush data @@ -9502,7 +9508,7 @@ As of GLib 2.34, #GConverterInputStream implements - + Gets the #GConverter that is used by @converter_stream. the converter of the converter input stream @@ -9515,7 +9521,7 @@ As of GLib 2.34, #GConverterInputStream implements - + @@ -9590,7 +9596,7 @@ As of GLib 2.34, #GConverterOutputStream implements - + Gets the #GConverter that is used by @converter_stream. the converter of the converter output stream @@ -9603,7 +9609,7 @@ As of GLib 2.34, #GConverterOutputStream implements - + @@ -9656,16 +9662,16 @@ As of GLib 2.34, #GConverterOutputStream implements Results returned from g_converter_convert(). - + There was an error during conversion. - + Some data was consumed or produced - + The conversion is finished - + Flushing is finished @@ -9864,25 +9870,25 @@ returned string may change in future GLib release. Enumeration describing different kinds of native credential types. - + Indicates an invalid native credential type. - + The native credentials type is a `struct ucred`. - + The native credentials type is a `struct cmsgcred`. - + The native credentials type is a `struct sockpeercred`. Added in 2.30. - + The native credentials type is a `ucred_t`. Added in 2.40. - + The native credentials type is a `struct unpcbid`. Added in 2.42. - + The native credentials type is a `struct xucred`. Added in 2.66. @@ -10012,6 +10018,31 @@ returned string may change in future GLib release. + + The value returned by handlers of the signals generated by +the `gdbus-codegen` tool to indicate that a method call has been +handled by an implementation. It is equal to %TRUE, but using +this macro is sometimes more readable. + +In code that needs to be backwards-compatible with older GLib, +use %TRUE instead, often written like this: + +|[ + g_dbus_method_invocation_return_error (invocation, ...); + return TRUE; // handled +]| + + + + The value returned by handlers of the signals generated by +the `gdbus-codegen` tool to indicate that a method call has not been +handled by an implementation. It is equal to %FALSE, but using +this macro is sometimes more readable. + +In code that needs to be backwards-compatible with older GLib, +use %FALSE instead. + + @@ -10177,7 +10208,7 @@ g_action_group_list_actions() to get the initial list. Information about an annotation. The reference count or -1 if statically allocated. - + The name of the annotation, e.g. "org.freedesktop.DBus.Deprecated". @@ -10247,7 +10278,7 @@ The cost of this function is O(n) in number of annotations. Information about an argument for a method or a signal. The reference count or -1 if statically allocated. - + Name of the argument, e.g. @unix_user_id. @@ -10434,25 +10465,25 @@ is authorized. Flags used in g_dbus_connection_call() and similar APIs. - + No flags set. - + The bus must not launch an owner for the destination name in response to this method invocation. - + the caller is prepared to wait for interactive authorization. Since 2.46. Capabilities negotiated with the remote peer. - + No flags set. - + The connection supports exchanging UNIX file descriptors with the remote peer. @@ -10491,22 +10522,22 @@ free it with g_object_unref(). ## An example D-Bus server # {#gdbus-server} Here is an example for a D-Bus server: -[gdbus-example-server.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-server.c) +[gdbus-example-server.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-server.c) ## An example for exporting a subtree # {#gdbus-subtree-server} Here is an example for exporting a subtree: -[gdbus-example-subtree.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-subtree.c) +[gdbus-example-subtree.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-subtree.c) ## An example for file descriptor passing # {#gdbus-unix-fd-client} Here is an example for passing UNIX file descriptors: -[gdbus-unix-fd-client.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-unix-fd-client.c) +[gdbus-unix-fd-client.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-unix-fd-client.c) ## An example for exporting a GObject # {#gdbus-export} Here is an example for exporting a #GObject: -[gdbus-example-export.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-export.c) +[gdbus-example-export.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-export.c) @@ -11452,7 +11483,7 @@ does. - + Gets the capabilities negotiated with the remote peer zero or more flags from the #GDBusCapabilityFlags enumeration @@ -11465,7 +11496,7 @@ does. - + Gets whether the process is terminated when @connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. @@ -11481,7 +11512,7 @@ closed by the remote peer. See - + Gets the flags used to construct this connection zero or more flags from the #GDBusConnectionFlags enumeration @@ -11494,7 +11525,7 @@ closed by the remote peer. See - + The GUID of the peer performing the role of server when authenticating. See #GDBusConnection:guid for more details. @@ -11549,7 +11580,7 @@ each application is a client. So this method will always return - + Gets the underlying stream used for IO. While the #GDBusConnection is active, it will interact with this @@ -11566,7 +11597,7 @@ the stream directly. - + Gets the unique name of @connection as assigned by the message bus. This can also be used to figure out if @connection is a message bus connection. @@ -12003,7 +12034,7 @@ Note that @message must be unlocked, unless @flags contain the - + Sets whether the process should be terminated when @connection is closed by the remote peer. See #GDBusConnection:exit-on-close for more details. @@ -12142,7 +12173,10 @@ function has returned. You should continue to iterate the #GMainContext until the #GDestroyNotify function passed to g_dbus_connection_signal_subscribe() is called, in order to avoid memory leaks through callbacks queued on the #GMainContext after it’s stopped being -iterated. +iterated. +Alternatively, any idle source with a priority lower than %G_PRIORITY_DEFAULT +that was scheduled after unsubscription, also indicates that all resources +of this subscription are released. @@ -12260,7 +12294,7 @@ when establishing the connection. A #GDBusAuthObserver object to assist in the authentication process or %NULL. - + Flags from the #GDBusCapabilityFlags enumeration representing connection features negotiated with the other peer. @@ -12269,7 +12303,7 @@ representing connection features negotiated with the other peer. A boolean specifying whether the connection has been closed. - + A boolean specifying whether the process will be terminated (by calling `raise(SIGTERM)`) if the connection is closed by the remote peer. @@ -12278,11 +12312,11 @@ Note that #GDBusConnection objects returned by g_bus_get_finish() and g_bus_get_sync() will (usually) have this property set to %TRUE. - + Flags from the #GDBusConnectionFlags enumeration. - + The GUID of the peer performing the role of server when authenticating. @@ -12295,10 +12329,19 @@ If you are constructing a #GDBusConnection and pass %G_DBUS_CONNECTION_FLAGS_AUTHENTICATION_CLIENT in the #GDBusConnection:flags property you will be able to read the GUID of the other peer here after the connection has been successfully -initialized. +initialized. + +Note that the +[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) +uses the term ‘UUID’ to refer to this, whereas GLib consistently uses the +term ‘GUID’ for historical reasons. + +Despite its name, the format of #GDBusConnection:guid does not follow +[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122) or the Microsoft +GUID format. - + The underlying #GIOStream used for I/O. If this is passed on construction and is a #GSocketConnection, @@ -12309,7 +12352,7 @@ stream from a worker thread, so it is not safe to interact with the stream directly. - + The unique name as assigned by the message bus or %NULL if the connection is not open or not a message bus connection. @@ -12349,174 +12392,178 @@ once. Flags used when creating a new #GDBusConnection. - + No flags set. - + Perform authentication against server. - + Perform authentication against client. - + When authenticating as a server, allow the anonymous authentication method. - + Pass this flag if connecting to a peer that is a message bus. This means that the Hello() method will be invoked as part of the connection setup. - + If set, processing of D-Bus messages is delayed until g_dbus_connection_start_message_processing() is called. + + When authenticating +as a server, require the UID of the peer to be the same as the UID of the server. (Since: 2.68) + Error codes for the %G_DBUS_ERROR error domain. - + A generic error; "something went wrong" - see the error message for more. - + There was not enough memory to complete an operation. - + The bus doesn't know how to launch a service to supply the bus name you wanted. - + The bus name you referenced doesn't exist (i.e. no application owns it). - + No reply to a message expecting one, usually means a timeout occurred. - + Something went wrong reading or writing to a socket, for example. - + A D-Bus bus address was malformed. - + Requested operation isn't supported (like ENOSYS on UNIX). - + Some limited resource is exhausted. - + Security restrictions don't allow doing what you're trying to do. - + Authentication didn't work. - + Unable to connect to server (probably caused by ECONNREFUSED on a socket). - + Certain timeout errors, possibly ETIMEDOUT on a socket. Note that %G_DBUS_ERROR_NO_REPLY is used for message reply timeouts. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMED_OUT also exists. We can't fix it for compatibility reasons so just be careful. - + No network access (probably ENETUNREACH on a socket). - + Can't bind a socket since its address is in use (i.e. EADDRINUSE). - + The connection is disconnected and you're trying to use it. - + Invalid arguments passed to a method call. - + Missing file. - + Existing file and the operation you're using does not silently overwrite. - + Method name you invoked isn't known by the object you invoked it on. - + Certain timeout errors, e.g. while starting a service. Warning: this is confusingly-named given that %G_DBUS_ERROR_TIMEOUT also exists. We can't fix it for compatibility reasons so just be careful. - + Tried to remove or modify a match rule that didn't exist. - + The match rule isn't syntactically valid. - + While starting a new process, the exec() call failed. - + While starting a new process, the fork() call failed. - + While starting a new process, the child exited with a status code. - + While starting a new process, the child exited on a signal. - + While starting a new process, something went wrong. - + We failed to setup the environment correctly. - + We failed to setup the config parser correctly. - + Bus name was not valid. - + Service file not found in system-services directory. - + Permissions are incorrect on the setuid helper. - + Service file invalid (Name, User or Exec missing). - + Tried to get a UNIX process ID and it wasn't available. - + Tried to get a UNIX process ID and it wasn't available. - + A type signature is not valid. - + A file contains invalid syntax or is otherwise broken. - + Asked for SELinux security context and it wasn't available. - + Asked for ADT audit data and it wasn't available. - + There's already an object with the requested object path. - + Object you invoked a method on isn't known. Since 2.42 - + Interface you invoked a method on isn't known by the object. Since 2.42 - + Property you tried to access isn't known by the object. Since 2.42 - + Property you tried to set is read-only. Since 2.42 @@ -13032,7 +13079,7 @@ reference should be freed with g_object_unref(). Information about a D-Bus interface. The reference count or -1 if statically allocated. - + The name of the D-Bus interface, e.g. "org.freedesktop.DBus.Properties". @@ -13736,10 +13783,10 @@ Free with g_variant_unref(). Flags describing the behavior of a #GDBusInterfaceSkeleton instance. - + No flags set. - + Each method invocation is handled in a thread dedicated to the invocation. This means that the method implementation can use blocking IO without blocking any other part of the process. It also means that the method implementation must @@ -14099,7 +14146,7 @@ is a #guchar. Free with g_free(). - + Checks whether @message is locked. To monitor changes to this value, conncet to the #GObject::notify signal to listen for changes on the #GDBusMessage:locked property. @@ -14206,7 +14253,9 @@ on the #GDBusMessage:locked property. - Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. + Convenience getter for the %G_DBUS_MESSAGE_HEADER_FIELD_SIGNATURE header field. + +This will always be non-%NULL, but may be an empty string. The value. @@ -14710,16 +14759,16 @@ well as the first string item in @message's body. - + Enumeration used to describe the byte order of a D-Bus message. - + The byte order is big endian. - + The byte order is little endian. @@ -14811,17 +14860,17 @@ a message to be sent to the other peer. Message flags used in #GDBusMessage. - + No flags set. - + A reply is not expected. - + The bus must not launch an owner for the destination name in response to this message. - + If set on a method call, this flag means that the caller is prepared to wait for interactive authorization. Since 2.46. @@ -14829,52 +14878,52 @@ authorization. Since 2.46. Header fields used in #GDBusMessage. - + Not a valid header field. - + The object path. - + The interface name. - + The method or signal name. - + The name of the error that occurred. - + The serial number the message is a reply to. - + The name the message is intended for. - + Unique name of the sender of the message (filled in by the bus). - + The signature of the message body. - + The number of UNIX file descriptors that accompany the message. Message types used in #GDBusMessage. - + Message is of invalid type. - + Method call. - + Method reply. - + Error reply. - + Signal emission. @@ -14882,7 +14931,7 @@ authorization. Since 2.46. Information about a method on an D-Bus interface. The reference count or -1 if statically allocated. - + The name of the D-Bus method, e.g. @RequestName. @@ -15353,7 +15402,7 @@ This method will take ownership of @invocation. See Information about nodes in a remote object hierarchy. The reference count or -1 if statically allocated. - + The path of the node or %NULL if omitted. Note that this may be a relative path. See the D-Bus specification for more details. @@ -15722,7 +15771,7 @@ and #GDBusObjectManagerServer for the service-side implementation. Gets the interface proxy for @interface_name at @object_path, if any. - + A #GDBusInterface instance or %NULL. Free with g_object_unref(). @@ -15744,7 +15793,7 @@ any. Gets the #GDBusObjectProxy at @object_path, if any. - + A #GDBusObject or %NULL. Free with g_object_unref(). @@ -15852,7 +15901,7 @@ any. Gets the interface proxy for @interface_name at @object_path, if any. - + A #GDBusInterface instance or %NULL. Free with g_object_unref(). @@ -15874,7 +15923,7 @@ any. Gets the #GDBusObjectProxy at @object_path, if any. - + A #GDBusObject or %NULL. Free with g_object_unref(). @@ -16346,7 +16395,7 @@ g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. - + Gets the #GDBusConnection used by @manager. A #GDBusConnection object. Do not free, @@ -16360,7 +16409,7 @@ g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version. - + Gets the flags that @manager was constructed with. Zero of more flags from the #GDBusObjectManagerClientFlags @@ -16374,7 +16423,7 @@ enumeration. - + Gets the name that @manager is for, or %NULL if not a message bus connection. @@ -16389,7 +16438,7 @@ belongs to @manager. - + The unique name that owns the name that @manager is for or %NULL if no-one currently owns that name. You can connect to the #GObject::notify signal to track changes to the @@ -16413,11 +16462,11 @@ exists. Free with g_free(). of this property. - + The #GDBusConnection to use. - + Flags from the #GDBusObjectManagerClientFlags enumeration. @@ -16434,11 +16483,11 @@ use for interface proxies or %NULL. The #gpointer user_data to pass to #GDBusObjectManagerClient:get-proxy-type-func. - + The well-known name or unique name that the manager is for. - + The unique name that owns #GDBusObjectManagerClient:name or %NULL if no-one is currently owning the name. Connect to the #GObject::notify signal to track changes to this property. @@ -16592,10 +16641,10 @@ that @manager was constructed in. Flags used when constructing a #GDBusObjectManagerClient. - + No flags set. - + If not set and the manager is for a well-known name, then request the bus to launch an owner for the name if no-one owns the name. This flag can only @@ -16644,7 +16693,7 @@ that @manager was constructed in. - + A #GDBusObject or %NULL. Free with g_object_unref(). @@ -16663,7 +16712,7 @@ that @manager was constructed in. - + A #GDBusInterface instance or %NULL. Free with g_object_unref(). @@ -16838,9 +16887,9 @@ if an object with the given path already exists. As such, the - + Gets the #GDBusConnection used by @manager. - + A #GDBusConnection object or %NULL if @manager isn't exported on a connection. The returned object should be freed with g_object_unref(). @@ -16870,7 +16919,7 @@ if an object with the given path already exists. As such, the - + Exports all objects managed by @manager on @connection. If @connection is %NULL, stops exporting objects. @@ -16908,7 +16957,7 @@ object path for @manager. - + The #GDBusConnection to export objects on. @@ -17195,7 +17244,7 @@ The default class handler just returns %TRUE. Information about a D-Bus property on a D-Bus interface. The reference count or -1 if statically allocated. - + The name of the D-Bus property, e.g. "SupportedFilesystems". @@ -17246,13 +17295,13 @@ the memory used is freed. Flags describing the access control of a D-Bus property. - + No flags set. - + Property is readable. - + Property is writable. @@ -17279,6 +17328,13 @@ then calls will be sent to the well-known name which may result in the message bus launching an owner (unless %G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set). +If the proxy is for a stateless D-Bus service, where the name owner may +be started and stopped between calls, the #GDBusProxy:g-name-owner tracking +of #GDBusProxy will cause the proxy to drop signal and property changes from +the service after it has restarted for the first time. When interacting +with a stateless D-Bus service, do not use #GDBusProxy — use direct D-Bus +method calls and signal connections. + The generic #GDBusProxy::g-properties-changed and #GDBusProxy::g-signal signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass @@ -17293,7 +17349,7 @@ and #GObject::notify) are emitted in the of the thread where the instance was constructed. An example using a proxy for a well-known name can be found in -[gdbus-example-watch-proxy.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-proxy.c) +[gdbus-example-watch-proxy.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-proxy.c) @@ -17977,8 +18033,12 @@ property for more details. - Gets the name that @proxy was constructed for. - + Gets the name that @proxy was constructed for. + +When connected to a message bus, this will usually be non-%NULL. +However, it may be %NULL for a proxy that communicates using a peer-to-peer +pattern. + A string owned by @proxy. Do not free. @@ -18289,24 +18349,24 @@ This signal corresponds to the Flags used when constructing an instance of a #GDBusProxy derived class. - + No flags set. - + Don't load properties. - + Don't connect to signals on the remote object. - + If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization or a method call. This flag is only meaningful in proxies for well-known names. - + If set, the property value for any __invalidated property__ will be (asynchronously) retrieved upon receiving the [`PropertiesChanged`](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties) D-Bus signal and the property will not cause emission of the #GDBusProxy::g-properties-changed signal. When the value is received the #GDBusProxy::g-properties-changed signal is emitted for the property along with the retrieved value. Since 2.32. - + If the proxy is for a well-known name, do not ask the bus to launch an owner during proxy initialization, but allow it to be autostarted by a method call. This flag is only meaningful in proxies for well-known names, @@ -18349,10 +18409,10 @@ that @manager was constructed in. Flags used when sending #GDBusMessages on a #GDBusConnection. - + No flags set. - + Do not automatically assign a serial number from the #GDBusConnection object when sending a message. @@ -18369,7 +18429,7 @@ To just export an object on a well-known name on a message bus, such as the session or system bus, you should instead use g_bus_own_name(). An example of peer-to-peer communication with GDBus can be found -in [gdbus-example-peer.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-peer.c). +in [gdbus-example-peer.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-peer.c). Note that a minimal #GDBusServer will accept connections from any peer. In many use-cases it will be necessary to add a #GDBusAuthObserver @@ -18427,10 +18487,12 @@ g_object_unref(). - + Gets a [D-Bus address](https://dbus.freedesktop.org/doc/dbus-specification.html#addresses) -string that can be used by clients to connect to @server. +string that can be used by clients to connect to @server. + +This is valid and non-empty if initializing the #GDBusServer succeeded. A D-Bus address string. Do not free, the string is owned by @server. @@ -18443,7 +18505,7 @@ by @server. - + Gets the flags for @server. A set of flags from the #GDBusServerFlags enumeration. @@ -18456,8 +18518,8 @@ by @server. - - Gets the GUID for @server. + + Gets the GUID for @server, as provided to g_dbus_server_new_sync(). A D-Bus GUID. Do not free this string, it is owned by @server. @@ -18518,16 +18580,18 @@ by @server. A #GDBusAuthObserver object to assist in the authentication process or %NULL. - + The D-Bus address that clients can use. - + Flags from the #GDBusServerFlags enumeration. - - The guid of the server. + + The GUID of the server. + +See #GDBusConnection:guid for more details. @@ -18567,18 +18631,22 @@ run. Flags used when creating a #GDBusServer. - + No flags set. - + All #GDBusServer::new-connection signals will run in separated dedicated threads (see signal for details). - + Allow the anonymous authentication method. + + Require the UID of the +peer to be the same as the UID of the server when authenticating. (Since: 2.68) + Signature for callback function used in g_dbus_connection_signal_subscribe(). @@ -18619,19 +18687,19 @@ authentication method. Flags used when subscribing to signals via g_dbus_connection_signal_subscribe(). - + No flags set. - + Don't actually send the AddMatch D-Bus call for this signal subscription. This gives you more control over which match rules you add (but you must add them manually). - + Match first arguments that contain a bus or interface name with the given namespace. - + Match first arguments that contain an object path that is either equivalent to the given path, or one of the paths is a subpath of the other. @@ -18641,7 +18709,7 @@ or one of the paths is a subpath of the other. Information about a signal on a D-Bus interface. The reference count or -1 if statically allocated. - + The name of the D-Bus signal, e.g. "NameOwnerChanged". @@ -18693,7 +18761,7 @@ the memory used is freed. Subtrees are flat. @node, if non-%NULL, is always exactly one segment of the object path (ie: it never contains a slash). - + A #GDBusInterfaceVTable or %NULL if you don't want to handle the methods. @@ -18728,7 +18796,7 @@ segment of the object path (ie: it never contains a slash). - + The type of the @enumerate function in #GDBusSubtreeVTable. This function is called when generating introspection data and also @@ -18737,10 +18805,10 @@ when preparing to dispatch incoming messages in the event that the specified (ie: to verify that the object path is valid). Hierarchies are not supported; the items that you return should not -contain the '/' character. +contain the `/` character. The return value will be freed with g_strfreev(). - + A newly allocated array of strings for node names that are children of @object_path. @@ -18767,10 +18835,10 @@ The return value will be freed with g_strfreev(). Flags passed to g_dbus_connection_register_subtree(). - + No flags set. - + Method calls to objects not in the enumerated range will still be dispatched. This is useful if you want to dynamically spawn objects in the subtree. @@ -18795,9 +18863,11 @@ The difference between returning %NULL and an array containing zero items is that the standard DBus interfaces will returned to the remote introspector in the empty array case, but not in the %NULL case. - + A %NULL-terminated array of pointers to #GDBusInterfaceInfo, or %NULL. - + + + @@ -18824,7 +18894,7 @@ case. Virtual table for handling subtrees registered with g_dbus_connection_register_subtree(). - + Function for enumerating child nodes. @@ -18948,7 +19018,7 @@ reading structured data directly from a binary input stream. - + Gets the byte order for the data input stream. the @stream's current #GDataStreamByteOrder. @@ -18961,7 +19031,7 @@ reading structured data directly from a binary input stream. - + Gets the current newline type for the @stream. #GDataStreamNewlineType for the given @stream. @@ -19530,7 +19600,7 @@ The returned string will always be nul-terminated on success. - + This function sets the byte order for the given @stream. All subsequent reads from the @stream will be read in the given @order. @@ -19547,7 +19617,7 @@ reads from the @stream will be read in the given @order. - + Sets the newline type for the @stream. Note that using G_DATA_STREAM_NEWLINE_TYPE_ANY is slightly unsafe. If a read @@ -19567,10 +19637,15 @@ chunk ends in "CR" we must read an additional byte to know if this is "CR" or - + + The :byte-order property determines the byte ordering that +is used when reading multi-byte entities (such as integers) +from the stream. - + + The :newline-type property determines what is considered +as a line ending when reading complete lines from the stream. @@ -19638,7 +19713,7 @@ writing data directly to an output stream. - + Gets the byte order for the stream. the #GDataStreamByteOrder for the @stream. @@ -19819,7 +19894,7 @@ writing data directly to an output stream. - + Sets the byte order of the data output stream to @order. @@ -19835,7 +19910,7 @@ writing data directly to an output stream. - + Determines the byte ordering that is used when writing multi-byte entities (such as integers) to the stream. @@ -19891,28 +19966,28 @@ multi-byte entities (such as integers) to the stream. #GDataStreamByteOrder is used to ensure proper endianness of streaming data sources across various machine architectures. - + Selects Big Endian byte order. - + Selects Little Endian byte order. - + Selects endianness based on host machine's architecture. #GDataStreamNewlineType is used when checking for or setting the line endings for a given file. - + Selects "LF" line endings, common on most modern UNIX platforms. - + Selects "CR" line endings. - + Selects "CR, LF" line ending, common on Microsoft Windows. - + Automatically try to handle any line ending type. @@ -20904,7 +20979,7 @@ The @key is looked up in the "Desktop Entry" group. - + When @info was created from a known filename, return it. In some situations such as the #GDesktopAppInfo returned from g_desktop_app_info_new_from_keyfile(), this function will return %NULL. @@ -21281,7 +21356,7 @@ explicitly listed in the "Actions" key of the [Desktop Entry] group. - + The origin filename of this #GDesktopAppInfo @@ -23116,31 +23191,31 @@ been pressed. Flags used when starting a drive. - + No flags set. Enumeration describing how a drive can be started/stopped. - + Unknown or drive doesn't support start/stop. - + The stop method will physically shut down the drive and e.g. power down the port the drive is attached to. - + The start/stop methods are used for connecting/disconnect to the drive over the network. - + The start/stop methods will assemble/disassemble a virtual drive from several physical drives. - + The start/stop methods will unlock/lock the disk (for example using the ATA <quote>SECURITY UNLOCK DEVICE</quote> command) @@ -23170,7 +23245,7 @@ assumed to communicate with the server identified by @server_identity. - + Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. @@ -23195,7 +23270,7 @@ the free the list with g_list_free(). - + Gets @conn's expected server identity a #GSocketConnectable describing the @@ -23210,7 +23285,7 @@ known. - + Gets @conn's validation flags the validation flags @@ -23223,7 +23298,7 @@ known. - + Sets @conn's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let @conn know what name to look for in the certificate when @@ -23242,7 +23317,7 @@ performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. - + Sets @conn's validation flags, to override the default set of checks performed when validating a server certificate. By default, %G_TLS_CERTIFICATE_VALIDATE_ALL is used. @@ -23260,7 +23335,7 @@ checks performed when validating a server certificate. By default, - + A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then @@ -23272,7 +23347,7 @@ subject DN of the certificate authority. - + A #GSocketConnectable describing the identity of the server that is expected on the other end of the connection. @@ -23289,7 +23364,7 @@ certificate we expect, which is useful for servers that serve virtual hosts. - + What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application @@ -23698,7 +23773,7 @@ case @error will be set - + Gets @conn's certificate, as set by g_dtls_connection_set_certificate(). @@ -23748,7 +23823,27 @@ negotiation or input required. - + + Returns the name of the current DTLS ciphersuite, or %NULL if the +connection has not handshaked or has been closed. Beware that the TLS +backend may use any of multiple different naming conventions, because +OpenSSL and GnuTLS have their own ciphersuite naming conventions that +are different from each other and different from the standard, IANA- +registered ciphersuite names. The ciphersuite name is intended to be +displayed to the user for informative purposes only, and parsing it +is not recommended. + + The name of the current DTLS ciphersuite, or %NULL + + + + + a #GDTlsConnection + + + + + Gets the certificate database that @conn uses to verify peer certificates. See g_dtls_connection_set_database(). @@ -23762,7 +23857,7 @@ peer certificates. See g_dtls_connection_set_database(). - + Get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If %NULL is returned, then no user interaction will occur for this connection. @@ -23777,7 +23872,7 @@ no user interaction will occur for this connection. - + Gets the name of the application-layer protocol negotiated during the handshake. @@ -23796,7 +23891,7 @@ g_dtls_connection_set_advertised_protocols(). - + Gets @conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) @@ -23811,7 +23906,7 @@ or failed. (It is not set during the emission of - + Gets the errors associated with validating @conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of #GDtlsConnection::accept-certificate.) @@ -23826,7 +23921,23 @@ not set during the emission of #GDtlsConnection::accept-certificate.) - + + Returns the current DTLS protocol version, which may be +%G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or +has been closed, or if the TLS backend has implemented a protocol version +that is not a recognized #GTlsProtocolVersion. + + The current DTLS protocol version + + + + + a #GDTlsConnection + + + + + Gets @conn rehandshaking mode. See g_dtls_connection_set_rehandshake_mode() for details. Changing the rehandshake mode is no longer @@ -23843,7 +23954,7 @@ g_dtls_connection_set_rehandshake_mode() for details. - + Tests whether or not @conn expects a proper TLS close notification when the connection is closed. See g_dtls_connection_set_require_close_notify() for details. @@ -23948,7 +24059,7 @@ case @error will be set. - + Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be @@ -23976,7 +24087,7 @@ for a list of registered protocol IDs. - + This sets the certificate that @conn will present to its peer during the TLS handshake. For a #GDtlsServerConnection, it is mandatory to set this, and that will normally be done at construct @@ -24009,7 +24120,7 @@ non-%NULL.) - + Sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See g_tls_backend_get_default_database(). If set to %NULL, then @@ -24032,7 +24143,7 @@ client-side connections, unless that bit is not set in - + Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. @@ -24053,7 +24164,7 @@ should occur for this connection. - + Since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and @@ -24075,7 +24186,7 @@ rekey operations. - + Sets whether or not @conn expects a proper TLS close notification before the connection is closed. If this is %TRUE (the default), then @conn will expect to receive a TLS close notification from its @@ -24211,7 +24322,7 @@ case @error will be set - + The list of application-layer protocols that the connection advertises that it is willing to speak. See g_dtls_connection_set_advertised_protocols(). @@ -24224,29 +24335,33 @@ g_dtls_connection_set_advertised_protocols(). implementation of #GDatagramBased, not just a #GSocket. - + The connection's certificate; see g_dtls_connection_set_certificate(). - + + The name of the DTLS ciphersuite in use. See g_dtls_connection_get_ciphersuite_name(). + + + The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database(). - + A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. - + The application-layer protocol negotiated during the TLS handshake. See g_dtls_connection_get_negotiated_protocol(). - + The connection's peer's certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GDtlsConnection::accept-certificate. @@ -24255,7 +24370,7 @@ during the emission of #GDtlsConnection::accept-certificate. detect when a handshake has occurred.) - + The errors noticed while verifying #GDtlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GDtlsClientConnection:validation-flags is not @@ -24264,13 +24379,17 @@ it may not be if #GDtlsClientConnection:validation-flags is not behavior. - + + The DTLS protocol version in use. See g_dtls_connection_get_protocol_version(). + + + The rehandshaking mode. See g_dtls_connection_set_rehandshake_mode(). The rehandshake mode is ignored. - + Whether or not proper TLS close notification is required. See g_dtls_connection_set_require_close_notify(). @@ -24666,7 +24785,7 @@ supported. More may be added in the future. - + Gives back the icon from @emblem. a #GIcon. The returned object belongs to @@ -24680,7 +24799,7 @@ supported. More may be added in the future. - + Gets the origin of the emblem. the origin of the emblem @@ -24693,10 +24812,10 @@ supported. More may be added in the future. - + - + @@ -24704,16 +24823,16 @@ supported. More may be added in the future. GEmblemOrigin is used to add information about the origin of the emblem to #GEmblem. - + Emblem of unknown origin - + Emblem adds device-specific information - + Emblem depicts live metadata, such as "readonly" - + Emblem comes from a user-defined tag, e.g. set by nautilus (in the future) @@ -24841,257 +24960,334 @@ of the emblems. See also #GEmblem for more information. A key in the "access" namespace for checking deletion privileges. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + This attribute will be %TRUE if the user is able to delete the file. A key in the "access" namespace for getting execution privileges. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + This attribute will be %TRUE if the user is able to execute the file. A key in the "access" namespace for getting read privileges. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + This attribute will be %TRUE if the user is able to read the file. A key in the "access" namespace for checking renaming privileges. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + This attribute will be %TRUE if the user is able to rename the file. A key in the "access" namespace for checking trashing privileges. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + This attribute will be %TRUE if the user is able to move the file to the trash. A key in the "access" namespace for getting write privileges. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + This attribute will be %TRUE if the user is able to write to the file. A key in the "dos" namespace for checking if the file's archive flag -is set. This attribute is %TRUE if the archive flag is set. This attribute -is only available for DOS file systems. Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. +is set. + +This attribute is %TRUE if the archive flag is set. + +This attribute is only available for DOS file systems. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "dos" namespace for checking if the file is a NTFS mount point (a volume mount or a junction point). + This attribute is %TRUE if file is a reparse point of type [IO_REPARSE_TAG_MOUNT_POINT](https://msdn.microsoft.com/en-us/library/dd541667.aspx). + This attribute is only available for DOS file systems. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "dos" namespace for checking if the file's backup flag -is set. This attribute is %TRUE if the backup flag is set. This attribute -is only available for DOS file systems. Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. +is set. + +This attribute is %TRUE if the backup flag is set. + +This attribute is only available for DOS file systems. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "dos" namespace for getting the file NTFS reparse tag. + This value is 0 for files that are not reparse points. + See the [Reparse Tags](https://msdn.microsoft.com/en-us/library/dd541667.aspx) -page for possible reparse tag values. Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_UINT32. +page for possible reparse tag values. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "etag" namespace for getting the value of the file's -entity tag. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. +entity tag. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - A key in the "filesystem" namespace for getting the number of bytes of free space left on the -file system. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT64. + A key in the "filesystem" namespace for getting the number of bytes +of free space left on the file system. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "filesystem" namespace for checking if the file system -is read only. Is set to %TRUE if the file system is read only. +is read only. + +Is set to %TRUE if the file system is read only. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "filesystem" namespace for checking if the file system -is remote. Is set to %TRUE if the file system is remote. +is remote. + +Is set to %TRUE if the file system is remote. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - A key in the "filesystem" namespace for getting the total size (in bytes) of the file system, -used in g_file_query_filesystem_info(). Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_UINT64. + A key in the "filesystem" namespace for getting the total size (in +bytes) of the file system, used in g_file_query_filesystem_info(). + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "filesystem" namespace for getting the file system's type. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - A key in the "filesystem" namespace for getting the number of bytes of used on the -file system. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT64. + A key in the "filesystem" namespace for getting the number of bytes +used by data on the file system. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "filesystem" namespace for hinting a file manager application whether it should preview (e.g. thumbnail) files on the -file system. The value for this key contain a -#GFilesystemPreviewType. +file system. + +The value for this key contain a #GFilesystemPreviewType. A key in the "gvfs" namespace that gets the name of the current -GVFS backend in use. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. +GVFS backend in use. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "id" namespace for getting a file identifier. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + An example use would be during listing files, to avoid recursive directory scanning. A key in the "id" namespace for getting the file system identifier. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + An example use would be during drag and drop to see if the source and target are on the same filesystem (default to move) or not (default to copy). - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be ejected. + A key in the "mountable" namespace for checking if a file (of +type G_FILE_TYPE_MOUNTABLE) can be ejected. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is mountable. + A key in the "mountable" namespace for checking if a file (of +type G_FILE_TYPE_MOUNTABLE) is mountable. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be polled. + A key in the "mountable" namespace for checking if a file (of +type G_FILE_TYPE_MOUNTABLE) can be polled. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started. + A key in the "mountable" namespace for checking if a file (of +type G_FILE_TYPE_MOUNTABLE) can be started. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be started -degraded. + A key in the "mountable" namespace for checking if a file (of +type G_FILE_TYPE_MOUNTABLE) can be started degraded. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) can be stopped. + A key in the "mountable" namespace for checking if a file (of +type G_FILE_TYPE_MOUNTABLE) can be stopped. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) is unmountable. + A key in the "mountable" namespace for checking if a file (of +type G_FILE_TYPE_MOUNTABLE) is unmountable. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for getting the HAL UDI for the mountable -file. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. +file. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - A key in the "mountable" namespace for checking if a file (of type G_FILE_TYPE_MOUNTABLE) -is automatically polled for media. + A key in the "mountable" namespace for checking if a file (of +type G_FILE_TYPE_MOUNTABLE) is automatically polled for media. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "mountable" namespace for getting the #GDriveStartStopType. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "mountable" namespace for getting the unix device. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "mountable" namespace for getting the unix device file. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "owner" namespace for getting the file owner's group. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "owner" namespace for getting the user name of the -file's owner. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. +file's owner. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "owner" namespace for getting the real name of the -user that owns the file. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. +user that owns the file. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "preview" namespace for getting a #GIcon that can be -used to get preview of the file. For example, it may be a low -resolution thumbnail without metadata. Corresponding -#GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. The value -for this key should contain a #GIcon. +used to get preview of the file. + +For example, it may be a low resolution thumbnail without metadata. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. + +The value for this key should contain a #GIcon. A key in the "recent" namespace for getting time, when the metadata for the -file in `recent:///` was last changed. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_INT64. +file in `recent:///` was last changed. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT64. A key in the "selinux" namespace for getting the file's SELinux -context. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_STRING. Note that this attribute is only -available if GLib has been built with SELinux support. +context. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + +Note that this attribute is only available if GLib has been built +with SELinux support. A key in the "standard" namespace for getting the amount of disk space -that is consumed by the file (in bytes). This will generally be larger -than the file size (due to block size overhead) but can occasionally be -smaller (for example, for sparse files). +that is consumed by the file (in bytes). + +This will generally be larger than the file size (due to block size +overhead) but can occasionally be smaller (for example, for sparse files). + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "standard" namespace for getting the content type of the file. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. + The value for this key should contain a valid content type. A key in the "standard" namespace for getting the copy name of the file. + The copy name is an optional version of the name. If available it's always in UTF8, and corresponds directly to the original filename (only transcoded to UTF8). This is useful if you want to copy the file to another filesystem that @@ -25103,6 +25299,7 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the description of the file. + The description is a utf8 string that describes the file, generally containing the filename, but can also contain further information. Example descriptions could be "filename (on hostname)" for a remote file or "filename (in trash)" @@ -25114,13 +25311,16 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the display name of the file. + A display name is guaranteed to be in UTF-8 and can thus be displayed in the UI. It is guaranteed to be set on every file. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for edit name of the file. + An edit name is similar to the display name, but it is meant to be used when you want to rename the file in the UI. The display name might contain information you don't want in the new filename (such as @@ -25131,25 +25331,31 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the fast content type. + The fast content type isn't as reliable as the regular one, as it only uses the filename to guess it, but it is faster to calculate than the regular content type. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for getting the icon for the file. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. + The value for this key should contain a #GIcon. A key in the "standard" namespace for checking if a file is a backup file. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for checking if a file is hidden. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. @@ -25157,12 +25363,15 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for checking if the file is a symlink. Typically the actual type is something else, if we followed the symlink to get the type. + On Windows NTFS mountpoints are considered to be symlinks as well. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for checking if a file is virtual. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. @@ -25170,29 +25379,35 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for checking if a file is volatile. This is meant for opaque, non-POSIX-like backends to indicate that the URI is not persistent. Applications should look -at #G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI. +at %G_FILE_ATTRIBUTE_STANDARD_SYMLINK_TARGET for the persistent URI. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "standard" namespace for getting the name of the file. + The name is the on-disk filename which may not be in any known encoding, and can thus not be generally displayed as is. It is guaranteed to be set on every file. -Use #G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the + +Use %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME if you need to display the name in a user interface. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "standard" namespace for getting the file's size (in bytes). + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "standard" namespace for setting the sort order of a file. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_INT32. + An example use would be in file managers, which would use this key to set the order files are displayed. Files with smaller sort order should be sorted first, and files without sort order as if sort order @@ -25201,36 +25416,45 @@ was zero. A key in the "standard" namespace for getting the symbolic icon for the file. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_OBJECT. + The value for this key should contain a #GIcon. A key in the "standard" namespace for getting the symlink target, if the file -is a symlink. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. +is a symlink. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "standard" namespace for getting the target URI for the file, in the case of %G_FILE_TYPE_SHORTCUT or %G_FILE_TYPE_MOUNTABLE files. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. A key in the "standard" namespace for storing file types. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. + The value for this key should contain a #GFileType. A key in the "thumbnail" namespace for checking if thumbnailing failed. -This attribute is %TRUE if thumbnailing failed. Corresponding -#GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. + +This attribute is %TRUE if thumbnailing failed. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for checking whether the thumbnail is outdated. + This attribute is %TRUE if the thumbnail is up-to-date with the file it represents, and %FALSE if the file has been modified since the thumbnail was generated. @@ -25242,156 +25466,206 @@ Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "thumbnail" namespace for getting the path to the thumbnail -image. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. +image. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "time" namespace for getting the time the file was last -accessed. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the -file was last accessed, in seconds since the UNIX epoch. +accessed. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and +contains the time since the file was last accessed, in seconds since the +UNIX epoch. A key in the "time" namespace for getting the microseconds of the time -the file was last accessed. This should be used in conjunction with -#G_FILE_ATTRIBUTE_TIME_ACCESS. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. +the file was last accessed. + +This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_ACCESS. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the time the file was last -changed. Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, -and contains the time since the file was last changed, in seconds since the -UNIX epoch. +changed. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, +and contains the time since the file was last changed, in seconds since +the UNIX epoch. This corresponds to the traditional UNIX ctime. A key in the "time" namespace for getting the microseconds of the time -the file was last changed. This should be used in conjunction with -#G_FILE_ATTRIBUTE_TIME_CHANGED. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. +the file was last changed. + +This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CHANGED. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the time the file was created. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the file was created, in seconds since the UNIX epoch. -This may correspond to Linux stx_btime, FreeBSD st_birthtim, NetBSD -st_birthtime or NTFS ctime. +This may correspond to Linux `stx_btime`, FreeBSD `st_birthtim`, NetBSD +`st_birthtime` or NTFS `ctime`. A key in the "time" namespace for getting the microseconds of the time -the file was created. This should be used in conjunction with -#G_FILE_ATTRIBUTE_TIME_CREATED. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. +the file was created. + +This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_CREATED. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "time" namespace for getting the time the file was last -modified. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT64, and contains the time since the -file was modified, in seconds since the UNIX epoch. +modified. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64, and +contains the time since the file was modified, in seconds since the UNIX +epoch. A key in the "time" namespace for getting the microseconds of the time -the file was last modified. This should be used in conjunction with -#G_FILE_ATTRIBUTE_TIME_MODIFIED. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. +the file was last modified. + +This should be used in conjunction with %G_FILE_ATTRIBUTE_TIME_MODIFIED. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - A key in the "trash" namespace. When requested against -items in `trash:///`, will return the date and time when the file -was trashed. The format of the returned string is YYYY-MM-DDThh:mm:ss. + A key in the "trash" namespace for getting the deletion date and time +of a file inside the `trash:///` folder. + +The format of the returned string is `YYYY-MM-DDThh:mm:ss`. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_STRING. - A key in the "trash" namespace. When requested against -`trash:///` returns the number of (toplevel) items in the trash folder. + A key in the "trash" namespace for getting the number of (toplevel) items +that are present in the `trash:///` folder. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. - A key in the "trash" namespace. When requested against -items in `trash:///`, will return the original path to the file before it -was trashed. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. + A key in the "trash" namespace for getting the original path of a file +inside the `trash:///` folder before it was trashed. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BYTE_STRING. A key in the "unix" namespace for getting the number of blocks allocated -for the file. This attribute is only available for UNIX file systems. +for the file. + +This attribute is only available for UNIX file systems. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "unix" namespace for getting the block size for the file -system. This attribute is only available for UNIX file systems. +system. + +This attribute is only available for UNIX file systems. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the device id of the device the -file is located on (see stat() documentation). This attribute is only -available for UNIX file systems. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. +file is located on (see stat() documentation). + +This attribute is only available for UNIX file systems. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the group ID for the file. + This attribute is only available for UNIX file systems. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the inode of the file. -This attribute is only available for UNIX file systems. Corresponding -#GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. + +This attribute is only available for UNIX file systems. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT64. A key in the "unix" namespace for checking if the file represents a -UNIX mount point. This attribute is %TRUE if the file is a UNIX mount -point. Since 2.58, `/` is considered to be a mount point. +UNIX mount point. + +This attribute is %TRUE if the file is a UNIX mount point. + +Since 2.58, `/` is considered to be a mount point. + This attribute is only available for UNIX file systems. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_BOOLEAN. A key in the "unix" namespace for getting the mode of the file -(e.g. whether the file is a regular file, symlink, etc). See the -documentation for `lstat()`: this attribute is equivalent to the `st_mode` -member of `struct stat`, and includes both the file type and permissions. +(e.g. whether the file is a regular file, symlink, etc). + +See the documentation for `lstat()`: this attribute is equivalent to +the `st_mode` member of `struct stat`, and includes both the file type +and permissions. + This attribute is only available for UNIX file systems. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the number of hard links -for a file. See lstat() documentation. This attribute is only available -for UNIX file systems. Corresponding #GFileAttributeType is -%G_FILE_ATTRIBUTE_TYPE_UINT32. +for a file. + +See the documentation for `lstat()`. + +This attribute is only available for UNIX file systems. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the device ID for the file -(if it is a special file). See lstat() documentation. This attribute -is only available for UNIX file systems. Corresponding #GFileAttributeType -is %G_FILE_ATTRIBUTE_TYPE_UINT32. +(if it is a special file). + +See the documentation for `lstat()`. + +This attribute is only available for UNIX file systems. + +Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. A key in the "unix" namespace for getting the user ID for the file. + This attribute is only available for UNIX file systems. + Corresponding #GFileAttributeType is %G_FILE_ATTRIBUTE_TYPE_UINT32. @@ -28966,6 +29240,37 @@ g_file_append_to_async(). + + Prepares the file attribute query string for copying to @file. + +This function prepares an attribute query string to be +passed to g_file_query_info() to get a list of attributes +normally copied with the file (see g_file_copy_attributes() +for the detailed description). This function is used by the +implementation of g_file_copy_attributes() and is useful +when one needs to query and set the attributes in two +stages (e.g., for recursive move of a directory). + + an attribute query string for g_file_query_info(), + or %NULL if an error occurs. + + + + + a #GFile to copy attributes to + + + + a set of #GFileCopyFlags + + + + optional #GCancellable object, + %NULL to ignore + + + + Copies the file @source to the location specified by @destination. Can not handle recursive copies of directories. @@ -32957,13 +33262,13 @@ with g_file_unmount_mountable_with_operation(). Flags specifying the behaviour of an attribute. - + no flags set. - + copy the attribute values when the file is copied. - + copy the attribute values when the file is moved. @@ -33246,83 +33551,83 @@ the @matcher is automatically freed. Used by g_file_set_attributes_from_info() when setting file attributes. - + Attribute value is unset (empty). - + Attribute value is set. - + Indicates an error in setting the value. The data types for file attributes. - + indicates an invalid or uninitialized type. - + a null terminated UTF8 string. - + a zero terminated string of non-zero bytes. - + a boolean value. - + an unsigned 4-byte/32-bit integer. - + a signed 4-byte/32-bit integer. - + an unsigned 8-byte/64-bit integer. - + a signed 8-byte/64-bit integer. - + a #GObject. - + a %NULL terminated char **. Since 2.22 Flags used when copying or moving files. - + No flags set. - + Overwrite any existing files - + Make a backup of any existing files. - + Don't follow symlinks. - + Copy all file metadata instead of just default set used for copy (see #GFileInfo). - + Don't use copy and delete fallback if native move not supported. - + Leaves target file with default perms, instead of setting the source file perms. Flags used when an operation may create a file. - + No flags set. - + Create a file that can only be accessed by the current user. - + Replace the destination as if it didn't exist before. Don't try to keep any old permissions, replace instead of following links. This @@ -34645,7 +34950,7 @@ to be used as icon. - + Gets the #GFile associated with the given @icon. a #GFile. @@ -34658,7 +34963,7 @@ to be used as icon. - + The file containing the icon. @@ -37154,6 +37459,11 @@ You may call g_file_query_settable_attributes() and g_file_query_writable_namespaces() to discover the settable attributes of a particular file at runtime. +The direct accessors, such as g_file_info_get_name(), are slightly more +optimized than the generic attribute accessors, such as +g_file_info_get_attribute_byte_string().This optimization will matter +only if calling the API in a tight loop. + #GFileAttributeMatcher allows for searching through a #GFileInfo for attributes. @@ -37205,6 +37515,24 @@ and then copies all of the file attributes from @src_info to @dest_info. + + Gets the access time of the current @info and returns it as a +#GDateTime. + +This requires the %G_FILE_ATTRIBUTE_TIME_ACCESS attribute. If +%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC is provided, the resulting #GDateTime +will have microsecond precision. + + access time, or %NULL if unknown + + + + + a #GFileInfo. + + + + Gets the value of a attribute, formatted as a string. This escapes things as needed to make the string valid @@ -37479,6 +37807,24 @@ or %NULL if unknown. + + Gets the creation time of the current @info and returns it as a +#GDateTime. + +This requires the %G_FILE_ATTRIBUTE_TIME_CREATED attribute. If +%G_FILE_ATTRIBUTE_TIME_CREATED_USEC is provided, the resulting #GDateTime +will have microsecond precision. + + creation time, or %NULL if unknown + + + + + a #GFileInfo. + + + + Returns the #GDateTime representing the deletion date of the file, as available in G_FILE_ATTRIBUTE_TRASH_DELETION_DATE. If the @@ -37780,6 +38126,24 @@ types for the given @name_space, or %NULL on error. + + Sets the %G_FILE_ATTRIBUTE_TIME_ACCESS and +%G_FILE_ATTRIBUTE_TIME_ACCESS_USEC attributes in the file info to the +given date/time value. + + + + + + a #GFileInfo. + + + + a #GDateTime. + + + + Sets the @attribute to contain the given value, if possible. To unset the attribute, use %G_FILE_ATTRIBUTE_TYPE_INVALID for @type. @@ -38058,6 +38422,24 @@ See %G_FILE_ATTRIBUTE_STANDARD_CONTENT_TYPE. + + Sets the %G_FILE_ATTRIBUTE_TIME_CREATED and +%G_FILE_ATTRIBUTE_TIME_CREATED_USEC attributes in the file info to the +given date/time value. + + + + + + a #GFileInfo. + + + + a #GDateTime. + + + + Sets the display name for the current #GFileInfo. See %G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME. @@ -38684,21 +39066,21 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be set Flags that can be used with g_file_measure_disk_usage(). - + No flags set. - + Report any error encountered while traversing the directory tree. Normally errors are only reported for the toplevel file. - + Tally usage based on apparent file sizes. Normally, the block-size is used, if available, as this is a more accurate representation of disk space used. Compare with `du --apparent-size`. - + Do not cross mount point boundaries. Compare with `du -x`. @@ -38860,7 +39242,7 @@ thread that the monitor was created in. - + Sets the rate limit to which the @monitor will report consecutive change events to the same file. @@ -38881,7 +39263,7 @@ consecutive change events to the same file. - + @@ -39015,42 +39397,42 @@ In all the other cases, @other_file will be set to #NULL. Specifies what type of event a monitor event is. - + a file changed. - + a hint that this was probably the last change in a set of changes. - + a file was deleted. - + a file was created. - + a file attribute was changed. - + the file location will soon be unmounted. - + the file location was unmounted. - + the file was moved -- only sent if the (deprecated) %G_FILE_MONITOR_SEND_MOVED flag is set - + the file was renamed within the current directory -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. - + the file was moved into the monitored directory from another location -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46. - + the file was moved out of the monitored directory to another location -- only sent if the %G_FILE_MONITOR_WATCH_MOVES flag is set. Since: 2.46 @@ -39058,13 +39440,13 @@ In all the other cases, @other_file will be set to #NULL. Flags used to set what a #GFileMonitor will watch for. - + No flags set. - + Watch for mount events. - + Pair DELETED and CREATED events caused by file renames (moves) and send a single G_FILE_MONITOR_EVENT_MOVED event instead (NB: not supported on all backends; the default @@ -39072,11 +39454,11 @@ In all the other cases, @other_file will be set to #NULL. and CREATED events). Deprecated since 2.46: use %G_FILE_MONITOR_WATCH_MOVES instead. - + Watch for changes to the file made via another hard link. Since 2.36. - + Watch for rename operations on a monitored directory. This causes %G_FILE_MONITOR_EVENT_RENAMED, %G_FILE_MONITOR_EVENT_MOVED_IN and %G_FILE_MONITOR_EVENT_MOVED_OUT @@ -39613,10 +39995,10 @@ far along that operation is to the application. Flags used when querying a #GFileInfo. - + No flags set. - + Don't follow symlinks. @@ -39655,27 +40037,27 @@ files that symlink to files, and directories that symlink to directories. #GFileType enumeration cannot precisely represent this important distinction, which is why all Windows symlinks will continue to be reported as %G_FILE_TYPE_REGULAR or %G_FILE_TYPE_DIRECTORY. - + File's type is unknown. - + File handle represents a regular file. - + File handle represents a directory. - + File handle represents a symbolic link (Unix systems). - + File is a "special" file, such as a socket, fifo, block device, or character device. - + File is a shortcut (Windows systems). - + File is a mountable location. @@ -39805,13 +40187,13 @@ complete directory names, and not file names. Indicates a hint from the file system whether files should be previewed in a file manager. Returned as the value of the key #G_FILE_ATTRIBUTE_FILESYSTEM_USE_PREVIEW. - + Only preview files if user has explicitly requested it. - + Preview files if user has requested preview of "local" files. - + Never preview files. @@ -39820,7 +40202,7 @@ previewed in a file manager. Returned as the value of the key kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping. - + Gets the base stream for the filter stream. a #GInputStream. @@ -39833,7 +40215,7 @@ and byte order flipping. - + Returns whether the base stream will be closed when @stream is closed. @@ -39847,7 +40229,7 @@ closed. - + Sets whether the base stream will be closed when @stream is closed. @@ -39863,10 +40245,10 @@ closed. - + - + @@ -39907,7 +40289,7 @@ closed. kind of filtering operation on a base stream. Typical examples of filtering operations are character set conversion, compression and byte order flipping. - + Gets the base stream for the filter stream. a #GOutputStream. @@ -39920,7 +40302,7 @@ and byte order flipping. - + Returns whether the base stream will be closed when @stream is closed. @@ -39950,10 +40332,10 @@ closed. - + - + @@ -40104,161 +40486,161 @@ but should instead treat all unrecognized error codes the same as See also #GPollableReturn for a cheaper way of returning %G_IO_ERROR_WOULD_BLOCK to callers without allocating a #GError. - + Generic error condition for when an operation fails and no more specific #GIOErrorEnum value is defined. - + File not found. - + File already exists. - + File is a directory. - + File is not a directory. - + File is a directory that isn't empty. - + File is not a regular file. - + File is not a symbolic link. - + File cannot be mounted. - + Filename is too many characters. - + Filename is invalid or contains invalid characters. - + File contains too many symbolic links. - + No space left on drive. - + Invalid argument. - + Permission denied. - + Operation (or one of its parameters) not supported - + File isn't mounted. - + File is already mounted. - + File was closed. - + Operation was cancelled. See #GCancellable. - + Operations are still pending. - + File is read only. - + Backup couldn't be created. - + File's Entity Tag was incorrect. - + Operation timed out. - + Operation would be recursive. - + File is busy. - + Operation would block. - + Host couldn't be found (remote operations). - + Operation would merge files. - + Operation failed and a helper program has already interacted with the user. Do not display any error dialog. - + The current process has too many files open and can't open any more. Duplicate descriptors do count toward this limit. Since 2.20 - + The object has not been initialized. Since 2.22 - + The requested address is already in use. Since 2.22 - + Need more input to finish operation. Since 2.24 - + The input data was invalid. Since 2.24 - + A remote object generated an error that doesn't correspond to a locally registered #GError error domain. Use g_dbus_error_get_remote_error() to extract the D-Bus error name and g_dbus_error_strip_remote_error() to fix up the message so it matches what was received on the wire. Since 2.26. - + Host unreachable. Since 2.26 - + Network unreachable. Since 2.26 - + Connection refused. Since 2.26 - + Connection to proxy server failed. Since 2.26 - + Proxy authentication failed. Since 2.26 - + Proxy server needs authentication. Since 2.26 - + Proxy connection is not allowed by ruleset. Since 2.26 - + Broken pipe. Since 2.36 - + Connection closed by peer. Note that this is the same code as %G_IO_ERROR_BROKEN_PIPE; before 2.44 some "connection closed" errors returned %G_IO_ERROR_BROKEN_PIPE, but others returned %G_IO_ERROR_FAILED. Now they should all return the same value, which has this more logical name. Since 2.44. - + Transport endpoint is not connected. Since 2.44 - + Message too large. Since 2.48. @@ -40617,10 +40999,10 @@ in this scope. Flags for use with g_io_module_scope_new(). - + No module scan flags - + When using this scope to load or scan modules, automatically block a modules which has the same base basename as previously loaded module. @@ -40987,7 +41369,7 @@ classes. However, if you override one you must override all. - + Gets the input stream for this object. This is used for reading. @@ -41002,7 +41384,7 @@ Do not free. - + Gets the output stream for this object. This is used for writing. @@ -41103,10 +41485,10 @@ result of the operation. - + - + @@ -41287,18 +41669,18 @@ Do not free. GIOStreamSpliceFlags determine how streams should be spliced. - + Do not close either stream. - + Close the first stream after the splice. - + Close the second stream after the splice. - + Wait for both splice operations to finish before calling the callback. @@ -42161,6 +42543,12 @@ Do not free. + + + + + + @@ -43165,7 +43553,7 @@ freed after use. - + Gets @address's family @address's family @@ -43178,7 +43566,7 @@ freed after use. - + Tests whether @address is the "any" address for its family. %TRUE if @address is the "any" address for its family. @@ -43191,7 +43579,7 @@ freed after use. - + Tests whether @address is a link-local address (that is, if it identifies a host on a local network that is not connected to the Internet). @@ -43206,7 +43594,7 @@ Internet). - + Tests whether @address is the loopback address for its family. %TRUE if @address is the loopback address for its family. @@ -43219,7 +43607,7 @@ Internet). - + Tests whether @address is a global multicast address. %TRUE if @address is a global multicast address. @@ -43232,7 +43620,7 @@ Internet). - + Tests whether @address is a link-local multicast address. %TRUE if @address is a link-local multicast address. @@ -43245,7 +43633,7 @@ Internet). - + Tests whether @address is a node-local multicast address. %TRUE if @address is a node-local multicast address. @@ -43258,7 +43646,7 @@ Internet). - + Tests whether @address is an organization-local multicast address. %TRUE if @address is an organization-local multicast address. @@ -43271,7 +43659,7 @@ Internet). - + Tests whether @address is a site-local multicast address. %TRUE if @address is a site-local multicast address. @@ -43284,7 +43672,7 @@ Internet). - + Tests whether @address is a multicast address. %TRUE if @address is a multicast address. @@ -43297,7 +43685,7 @@ Internet). - + Tests whether @address is a site-local address such as 10.0.0.1 (that is, the address identifies a host on a local network that can not be reached directly from the Internet, but which may have @@ -43359,55 +43747,55 @@ freed after use. - + - + Whether this is the "any" address for its family. See g_inet_address_get_is_any(). - + Whether this is a link-local address. See g_inet_address_get_is_link_local(). - + Whether this is the loopback address for its family. See g_inet_address_get_is_loopback(). - + Whether this is a global multicast address. See g_inet_address_get_is_mc_global(). - + Whether this is a link-local multicast address. See g_inet_address_get_is_mc_link_local(). - + Whether this is a node-local multicast address. See g_inet_address_get_is_mc_node_local(). - + Whether this is an organization-local multicast address. See g_inet_address_get_is_mc_org_local(). - + Whether this is a site-local multicast address. See g_inet_address_get_is_mc_site_local(). - + Whether this is a multicast address. See g_inet_address_get_is_multicast(). - + Whether this is a site-local address. See g_inet_address_get_is_loopback(). @@ -43513,7 +43901,7 @@ on error. - + Gets @mask's base address @mask's base address @@ -43526,7 +43914,7 @@ on error. - + Gets the #GSocketFamily of @mask's address the #GSocketFamily of @mask's address @@ -43539,7 +43927,7 @@ on error. - + Gets @mask's length @mask's length @@ -43583,13 +43971,13 @@ on error. - + - + - + @@ -43648,7 +44036,7 @@ or %NULL if @address cannot be parsed. - + Gets @address's #GInetAddress. the #GInetAddress for @address, which must be @@ -43662,7 +44050,7 @@ g_object_ref()'d if it will be stored - + Gets the `sin6_flowinfo` field from @address, which must be an IPv6 address. @@ -43676,7 +44064,7 @@ which must be an IPv6 address. - + Gets @address's port. the port for @address @@ -43689,7 +44077,7 @@ which must be an IPv6 address. - + Gets the `sin6_scope_id` field from @address, which must be an IPv6 address. @@ -43703,17 +44091,17 @@ which must be an IPv6 address. - + - + The `sin6_flowinfo` field, for IPv6 addresses. - + - + @@ -44165,7 +44553,7 @@ override one you must override all. - + the number of bytes that will be read from the stream @@ -44498,7 +44886,7 @@ On error -1 is returned and @error is set accordingly. - + the number of bytes that will be read from the stream @@ -44544,7 +44932,7 @@ write your own loop around g_input_stream_read(). - + the number of bytes that will be read from the stream @@ -44584,7 +44972,7 @@ priority. Default priority is %G_PRIORITY_DEFAULT. - + the number of bytes that will be read from the stream @@ -44674,7 +45062,7 @@ override one you must override all. - + the number of bytes that will be read from the stream @@ -45032,7 +45420,7 @@ However, if you override one, you must override all. - + the number of bytes that will be read from the stream @@ -46403,13 +46791,14 @@ It is implemented on Linux using the [Low Memory Monitor](https://gitlab.freedes There is also an implementation for use inside Flatpak sandboxes. Possible actions to take when the signal is received are: -- Free caches -- Save files that haven't been looked at in a while to disk, ready to be reopened when needed -- Run a garbage collection cycle -- Try and compress fragmented allocations -- Exit on idle if the process has no reason to stay around -- Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to - the kernel (if supported by your libc) + + - Free caches + - Save files that haven't been looked at in a while to disk, ready to be reopened when needed + - Run a garbage collection cycle + - Try and compress fragmented allocations + - Exit on idle if the process has no reason to stay around + - Call [`malloc_trim(3)`](man:malloc_trim) to return cached heap pages to + the kernel (if supported by your libc) Note that some actions may not always improve system performance, and so should be profiled for your application. `malloc_trim()`, for example, may @@ -46508,18 +46897,18 @@ Note that because new values might be added, it is recommended that applications if (warning_level > G_MEMORY_MONITOR_WARNING_LEVEL_LOW) drop_caches (); ]| - + Memory on the device is low, processes should free up unneeded resources (for example, in-memory caches) so they can be used elsewhere. - + Same as @G_MEMORY_MONITOR_WARNING_LEVEL_LOW but the device has even less free memory, so processes should try harder to free up unneeded resources. If your process does not need to stay running, it is a good time for it to quit. - + The system will soon start terminating processes to reclaim memory, including background processes. @@ -46606,7 +46995,7 @@ for memory allocation. - + Gets any loaded data from the @ostream. Note that the returned pointer may become invalid on the next @@ -46623,7 +47012,7 @@ write or truncate operation on the stream. - + Returns the number of bytes from the start up to including the last byte written in the stream that has not been truncated away. @@ -46637,7 +47026,7 @@ byte written in the stream that has not been truncated away. - + Gets the size of the currently allocated data area (available from g_memory_output_stream_get_data()). @@ -46697,11 +47086,11 @@ freed using the free function set in @ostream's - + Pointer to buffer where data will be written. - + Size of data written to the buffer. @@ -46713,7 +47102,7 @@ freed using the free function set in @ostream's Function with realloc semantics called to enlarge the buffer. - + Current size of the data buffer. @@ -50449,7 +50838,7 @@ finalized. Flags used when mounting a mount. - + No flags set. @@ -50602,7 +50991,7 @@ improvements and auditing fixes. - + Check to see whether the mount operation is being used for an anonymous user. @@ -50616,7 +51005,7 @@ for an anonymous user. - + Gets a choice from the mount operation. an integer containing an index of the user's choice from @@ -50630,7 +51019,7 @@ the choice's list, or `0`. - + Gets the domain of the mount operation. a string set to the domain. @@ -50643,7 +51032,7 @@ the choice's list, or `0`. - + Check to see whether the mount operation is being used for a TCRYPT hidden volume. @@ -50657,7 +51046,7 @@ for a TCRYPT hidden volume. - + Check to see whether the mount operation is being used for a TCRYPT system volume. @@ -50671,7 +51060,7 @@ for a TCRYPT system volume. - + Gets a password from the mount operation. a string containing the password within @op. @@ -50684,7 +51073,7 @@ for a TCRYPT system volume. - + Gets the state of saving passwords for the mount operation. a #GPasswordSave flag. @@ -50697,7 +51086,7 @@ for a TCRYPT system volume. - + Gets a PIM from the mount operation. The VeraCrypt PIM within @op. @@ -50710,7 +51099,7 @@ for a TCRYPT system volume. - + Get the user name from the mount operation. a string containing the user name. @@ -50739,7 +51128,7 @@ for a TCRYPT system volume. - + Sets the mount operation to use an anonymous user if @anonymous is %TRUE. @@ -50755,7 +51144,7 @@ for a TCRYPT system volume. - + Sets a default choice for the mount operation. @@ -50771,7 +51160,7 @@ for a TCRYPT system volume. - + Sets the mount operation's domain. @@ -50787,7 +51176,7 @@ for a TCRYPT system volume. - + Sets the mount operation to use a hidden volume if @hidden_volume is %TRUE. @@ -50803,7 +51192,7 @@ for a TCRYPT system volume. - + Sets the mount operation to use a system volume if @system_volume is %TRUE. @@ -50819,7 +51208,7 @@ for a TCRYPT system volume. - + Sets the mount operation's password to @password. @@ -50835,7 +51224,7 @@ for a TCRYPT system volume. - + Sets the state of saving passwords for the mount operation. @@ -50851,7 +51240,7 @@ for a TCRYPT system volume. - + Sets the mount operation's PIM to @pim. @@ -50867,7 +51256,7 @@ for a TCRYPT system volume. - + Sets the user name within @op to @username. @@ -50883,25 +51272,25 @@ for a TCRYPT system volume. - + Whether to use an anonymous user when authenticating. - + The index of the user's choice when a question is asked during the mount operation. See the #GMountOperation::ask-question signal. - + The domain to use for the mount operation. - + Whether the device to be unlocked is a TCRYPT hidden volume. See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Hidden%20Volume.html). - + Whether the device to be unlocked is a TCRYPT system volume. In this context, a system volume is a volume with a bootloader and operating system installed. This is only supported for Windows @@ -50909,21 +51298,21 @@ operating systems. For further documentation, see [the VeraCrypt documentation](https://www.veracrypt.fr/en/System%20Encryption.html). - + The password that is used for authentication when carrying out the mount operation. - + Determines if and how the password information should be saved. - + The VeraCrypt PIM value, when unlocking a VeraCrypt volume. See [the VeraCrypt documentation](https://www.veracrypt.fr/en/Personal%20Iterations%20Multiplier%20(PIM).html). - + The user name that is used for authentication when carrying out the mount operation. @@ -51283,25 +51672,25 @@ primary text in a #GtkMessageDialog. #GMountOperationResult is returned as a result when a request for information is send by the mounting operation. - + The request was fulfilled and the user specified data is now available - + The user requested the mount operation to be aborted - + The request was unhandled (i.e. not implemented) Flags used when an unmounting a mount. - + No flags set. - + Unmount even if there are outstanding file operations on the mount. @@ -51577,7 +51966,7 @@ when to use application-specific proxy protocols. - + Gets @addr's hostname. This might be either UTF-8 or ASCII-encoded, depending on what @addr was created with. @@ -51591,7 +51980,7 @@ depending on what @addr was created with. - + Gets @addr's port number @addr's port (which may be 0) @@ -51604,7 +51993,7 @@ depending on what @addr was created with. - + Gets @addr's scheme @addr's scheme (%NULL if not built from URI) @@ -51617,13 +52006,13 @@ depending on what @addr was created with. - + - + - + @@ -51641,21 +52030,21 @@ depending on what @addr was created with. The host's network connectivity state, as reported by #GNetworkMonitor. - + The host is not configured with a route to the Internet; it may or may not be connected to a local network. - + The host is connected to a network, but does not appear to be able to reach the full Internet, perhaps due to upstream network problems. - + The host is behind a captive portal and cannot reach the full Internet. - + The host is connected to a network, and appears to be able to reach the full Internet. @@ -51873,7 +52262,7 @@ See g_network_monitor_can_reach_async(). - + Gets a more detailed networking state than g_network_monitor_get_network_available(). @@ -51904,7 +52293,7 @@ back to their "offline" behavior if the connection attempt fails. - + Checks if the network is available. "Available" here means that the system has a default route available for at least one of IPv4 or IPv6. It does not necessarily imply that the public Internet is @@ -51920,7 +52309,7 @@ reachable. See #GNetworkMonitor:network-available for more details. - + Checks if the network is metered. See #GNetworkMonitor:network-metered for more details. @@ -51934,13 +52323,13 @@ See #GNetworkMonitor:network-metered for more details. - + More detailed information about the host's network connectivity. See g_network_monitor_get_connectivity() and #GNetworkConnectivity for more details. - + Whether the network is considered available. That is, whether the system has a default route for at least one of IPv4 or IPv6. @@ -51960,7 +52349,7 @@ in its UI.) See also #GNetworkMonitor::network-changed. - + Whether the network is considered metered. That is, whether the system has traffic flowing through the default connection that is subject to limitations set by service providers. For example, traffic @@ -52119,7 +52508,7 @@ interface. - + Gets the domain that @srv serves. This might be either UTF-8 or ASCII-encoded, depending on what @srv was created with. @@ -52133,7 +52522,7 @@ ASCII-encoded, depending on what @srv was created with. - + Gets @srv's protocol name (eg, "tcp"). @srv's protocol name @@ -52146,7 +52535,7 @@ ASCII-encoded, depending on what @srv was created with. - + Gets the URI scheme used to resolve proxies. By default, the service name is used as scheme. @@ -52160,7 +52549,7 @@ is used as scheme. - + Gets @srv's service name (eg, "ldap"). @srv's service name @@ -52173,7 +52562,7 @@ is used as scheme. - + Set's the URI scheme used to resolve proxies. By default, the service name is used as scheme. @@ -52190,16 +52579,16 @@ is used as scheme. - + - + - + - + @@ -52229,6 +52618,29 @@ Since the user may click on a notification while the application is not running, applications using #GNotification should be able to be started as a D-Bus service, using #GApplication. +In order for #GNotification to work, the application must have installed +a `.desktop` file. For example: +|[ + [Desktop Entry] + Name=Test Application + Comment=Description of what Test Application does + Exec=gnome-test-application + Icon=org.gnome.TestApplication + Terminal=false + Type=Application + Categories=GNOME;GTK;TestApplication Category; + StartupNotify=true + DBusActivatable=true + X-GNOME-UsesNotifications=true +]| + +The `X-GNOME-UsesNotifications` key indicates to GNOME Control Center +that this application uses notifications, so it can be listed in the +Control Center’s ‘Notifications’ panel. + +The `.desktop` file must be named as `org.gnome.TestApplication.desktop`, +where `org.gnome.TestApplication` is the ID passed to g_application_new(). + User interaction with a notification (either the default action, or buttons) must be associated with actions on the application (ie: "app." actions). It is not possible to route user interaction @@ -52360,6 +52772,27 @@ its parameter. + + Sets the type of @notification to @category. Categories have a main +type like `email`, `im` or `device` and can have a detail separated +by a `.`, e.g. `im.received` or `email.arrived`. Setting the category +helps the notification server to select proper feedback to the user. + +Standard categories are [listed in the specification](https://specifications.freedesktop.org/notification-spec/latest/ar01s06.html). + + + + + + a #GNotification + + + + the category for @notification, or %NULL for no category + + + + Sets the default action of @notification to @detailed_action. This action is activated when the notification is clicked on. @@ -52518,22 +52951,22 @@ was sent on is activated. Priority levels for #GNotifications. - + the default priority, to be used for the majority of notifications (for example email messages, software updates, completed download/sync operations) - + for notifications that do not require immediate attention - typically used for contextual background information, such as contact birthdays or local weather - + for events that require more attention, usually because responses are time-sensitive (for example chat and SMS messages or alarms) - + for urgent notifications, or notifications that require a response in a short space of time (for example phone calls or emergency warnings) @@ -54623,14 +55056,14 @@ until @callback is called. GOutputStreamSpliceFlags determine how streams should be spliced. - + Do not close either stream. - + Close the source stream after the splice. - + Close the target stream after the splice. @@ -54691,6 +55124,23 @@ one buffer. + + + + + + + + Extension point for power profile usage monitoring functionality. +See [Extending GIO][extending-gio]. + + + + + + + + @@ -54772,13 +55222,13 @@ See [Extending GIO][extending-gio]. #Gvfs stores passwords in the Gnome keyring when this flag allows it to, and later retrieves it again from there. - + never save a password. - + save a password for the session. - + save a password permanently. @@ -55035,7 +55485,7 @@ g_permission_acquire(). - + Gets the value of the 'allowed' property. This property is %TRUE if the caller currently has permission to perform the action that @permission represents the permission to perform. @@ -55050,7 +55500,7 @@ the caller currently has permission to perform the action that - + Gets the value of the 'can-acquire' property. This property is %TRUE if it is generally possible to acquire the permission by calling g_permission_acquire(). @@ -55065,7 +55515,7 @@ g_permission_acquire(). - + Gets the value of the 'can-release' property. This property is %TRUE if it is generally possible to release the permission by calling g_permission_release(). @@ -55187,17 +55637,17 @@ g_permission_release(). - + %TRUE if the caller currently has permission to perform the action that @permission represents the permission to perform. - + %TRUE if it is generally possible to acquire the permission by calling g_permission_acquire(). - + %TRUE if it is generally possible to release the permission by calling g_permission_release(). @@ -55436,9 +55886,9 @@ to having been cancelled. a #GPollableInputStream - - a buffer to - read data into (which should be at least @count bytes long). + + a + buffer to read data into (which should be at least @count bytes long). @@ -55537,9 +55987,9 @@ to having been cancelled. a #GPollableInputStream - - a buffer to - read data into (which should be at least @count bytes long). + + a + buffer to read data into (which should be at least @count bytes long). @@ -55631,9 +56081,9 @@ readable. a #GPollableInputStream - - a buffer to - read data into (which should be at least @count bytes long). + + a + buffer to read data into (which should be at least @count bytes long). @@ -56102,13 +56552,13 @@ regularly happening errors like %G_IO_ERROR_WOULD_BLOCK. In case of %G_POLLABLE_RETURN_FAILED a #GError should be set for the operation to give details about the error that happened. - + Generic error condition for when an operation fails. - + The operation was successfully finished. - + The operation would block. @@ -56131,6 +56581,66 @@ g_pollable_output_stream_create_source(). + + #GPowerProfileMonitor makes it possible for applications as well as OS components +to monitor system power profiles and act upon them. It currently only exports +whether the system is in “Power Saver” mode (known as “Low Power” mode on +some systems). + +When in “Low Power” mode, it is recommended that applications: +- disabling automatic downloads +- reduce the rate of refresh from online sources such as calendar or + email synchronisation +- if the application has expensive visual effects, reduce them + +It is also likely that OS components providing services to applications will +lower their own background activity, for the sake of the system. + +There are a variety of tools that exist for power consumption analysis, but those +usually depend on the OS and hardware used. On Linux, one could use `upower` to +monitor the battery discharge rate, `powertop` to check on the background activity +or activity at all), `sysprof` to inspect CPU usage, and `intel_gpu_time` to +profile GPU usage. + +Don't forget to disconnect the #GPowerProfileMonitor::notify::power-saver-enabled +signal, and unref the #GPowerProfileMonitor itself when exiting. + + + Gets a reference to the default #GPowerProfileMonitor for the system. + + a new reference to the default #GPowerProfileMonitor + + + + + Gets whether the system is in “Power Saver” mode. + +You are expected to listen to the +#GPowerProfileMonitor::notify::power-saver-enabled signal to know when the profile has +changed. + + Whether the system is in “Power Saver” mode. + + + + + a #GPowerProfileMonitor + + + + + + Whether “Power Saver” mode is enabled on the system. + + + + + The virtual function table for #GPowerProfileMonitor. + + The parent interface. + + + A #GPropertyAction is a way to get a #GAction with a state value reflecting and controlling the value of a #GObject property. @@ -56524,7 +57034,7 @@ directly if you want to set those.) - + Gets @proxy's destination hostname; that is, the name of the host that will be connected to via the proxy, not the name of the proxy itself. @@ -56539,7 +57049,7 @@ itself. - + Gets @proxy's destination port; that is, the port on the destination host that will be connected to via the proxy, not the port number of the proxy itself. @@ -56554,7 +57064,7 @@ port number of the proxy itself. - + Gets the protocol that is being spoken to the destination server; eg, "http" or "ftp". @@ -56568,7 +57078,7 @@ server; eg, "http" or "ftp". - + Gets @proxy's password. the @proxy's password @@ -56581,7 +57091,7 @@ server; eg, "http" or "ftp". - + Gets @proxy's protocol. eg, "socks" or "http" the @proxy's protocol @@ -56594,7 +57104,7 @@ server; eg, "http" or "ftp". - + Gets the proxy URI that @proxy was constructed from. the @proxy's URI, or %NULL if unknown @@ -56607,7 +57117,7 @@ server; eg, "http" or "ftp". - + Gets @proxy's username. the @proxy's username @@ -56620,29 +57130,29 @@ server; eg, "http" or "ftp". - + - + - + The protocol being spoke to the destination host, or %NULL if the #GProxyAddress doesn't know. - + - + - + The URI string that the proxy was constructed from (or %NULL if the creator didn't specify this). - + @@ -58890,15 +59400,15 @@ done with it. (You can use g_resolver_free_addresses() to do this.) An error code used with %G_RESOLVER_ERROR in a #GError returned from a #GResolver routine. - + the requested name/address/service was not found - + the requested information could not be looked up due to a network error or similar problem - + unknown error @@ -58911,13 +59421,13 @@ from a #GResolver routine. Flags to modify lookup behavior. - + default behavior (same as g_resolver_lookup_by_name()) - + only resolve ipv4 addresses - + only resolve ipv6 addresses @@ -58953,19 +59463,19 @@ as a `guint32`, and the TTL as a `guint32`. %G_RESOLVER_RECORD_NS records are returned as variants with the signature `(s)`, representing a string of the hostname of the name server. - + look up DNS SRV records for a domain - + look up DNS MX records for a domain - + look up DNS TXT records for a name - + look up DNS SOA records for a zone - + look up DNS NS records for a domain @@ -59335,10 +59845,10 @@ returned. An error code used with %G_RESOURCE_ERROR in a #GError returned from a #GResource routine. - + no file was found at the requested path - + unknown error @@ -59352,16 +59862,16 @@ from a #GResource routine. GResourceFlags give information about a particular file inside a resource bundle. - + No flags set. - + The file is compressed. GResourceLookupFlags determine how resource path lookups are handled. - + No flags set. @@ -59742,7 +60252,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Tells the current position within the stream. - the offset from the beginning of the buffer. + the (positive or zero) offset from the beginning of the +buffer, zero if the target is not seekable. @@ -59853,7 +60364,8 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. Tells the current position within the stream. - the offset from the beginning of the buffer. + the (positive or zero) offset from the beginning of the +buffer, zero if the target is not seekable. @@ -59904,7 +60416,8 @@ partial result will be returned, without an error. - the offset from the beginning of the buffer. + the (positive or zero) offset from the beginning of the +buffer, zero if the target is not seekable. @@ -60079,7 +60592,7 @@ by the [glib-compile-schemas][glib-compile-schemas] utility. The input is a schema description in an XML format. A DTD for the gschema XML format can be found here: -[gschema.dtd](https://git.gnome.org/browse/glib/tree/gio/gschema.dtd) +[gschema.dtd](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/gschema.dtd) The [glib-compile-schemas][glib-compile-schemas] tool expects schema files to have the extension `.gschema.xml`. @@ -60942,7 +61455,7 @@ value. - + Returns whether the #GSettings object has any unapplied changes. This can only be the case if it is in 'delayed-apply' mode. @@ -61694,7 +62207,7 @@ If @value is floating then this function consumes the reference. g_settings_delay() for details. - + If this property is %TRUE, the #GSettings object has outstanding changes that will be applied when g_settings_apply() is called. @@ -62445,25 +62958,25 @@ will always be made in response to external events. Flags used when creating a binding. These flags determine in which direction the binding works. The default is to synchronize in both directions. - + Equivalent to `G_SETTINGS_BIND_GET|G_SETTINGS_BIND_SET` - + Update the #GObject property when the setting changes. It is an error to use this flag if the property is not writable. - + Update the setting when the #GObject property changes. It is an error to use this flag if the property is not readable. - + Do not try to bind a "sensitivity" property to the writability of the setting - + When set in addition to #G_SETTINGS_BIND_GET, set the #GObject property value initially from the setting, but do not listen for changes of the setting - + When passed to g_settings_bind(), uses a pair of mapping functions that invert the boolean value when mapping between the setting and the property. The setting and property must both be booleans. You cannot pass this flag to g_settings_bind_with_mapping(). @@ -62992,10 +63505,10 @@ directory. - Checks if the given @value is of the correct type and within the + Checks if the given @value is within the permitted range for @key. -It is a programmer error if @value is not of the correct type -- you +It is a programmer error if @value is not of the correct type — you must check for this first. %TRUE if @value is valid for @key @@ -63261,7 +63774,7 @@ If the @state #GVariant is floating, it is consumed. - + Sets the action as enabled or not. An action must be enabled in order to be activated or in order to @@ -63283,7 +63796,7 @@ of the action should not attempt to modify its enabled flag. - + Sets the state of the action. This directly updates the 'state' property to the given value. @@ -63327,7 +63840,7 @@ action state hints. - + If @action is currently enabled. If the action is disabled then calls to g_action_activate() and @@ -63344,7 +63857,7 @@ the action once it has been added to a #GSimpleActionGroup. action. - + The state of the action, or %NULL if the action is stateless. @@ -64324,7 +64837,7 @@ arguments are interpreted. - + Sets the default proxy on @resolver, to be used for any URIs that don't match #GSimpleProxyResolver:ignore-hosts or a proxy set via g_simple_proxy_resolver_set_uri_proxy(). @@ -64346,7 +64859,7 @@ the socks5, socks4a, and socks4 proxy types. - + Sets the list of ignored hosts. See #GSimpleProxyResolver:ignore-hosts for more details on how the @@ -64393,7 +64906,7 @@ types. - + The default proxy URI that will be used for any URI that doesn't match #GSimpleProxyResolver:ignore-hosts, and doesn't match any of the schemes set with g_simple_proxy_resolver_set_uri_proxy(). @@ -64403,7 +64916,7 @@ Note that as a special case, if this URI starts with to all three of the socks5, socks4a, and socks4 proxy types. - + A list of hostnames and IP addresses that the resolver should allow direct connections to. @@ -64948,7 +65461,7 @@ without blocking or truncating, or -1 on error. - + Gets the blocking mode of the socket. For details on blocking I/O, see g_socket_set_blocking(). @@ -64962,7 +65475,7 @@ see g_socket_set_blocking(). - + Gets the broadcast setting on @socket; if %TRUE, it is possible to send packets to broadcast addresses. @@ -65010,7 +65523,7 @@ that must be freed with g_object_unref(). - + Gets the socket family of the socket. a #GSocketFamily @@ -65023,7 +65536,7 @@ that must be freed with g_object_unref(). - + Returns the underlying OS socket object. On unix this is a socket file descriptor, and on Windows this is a Winsock2 SOCKET handle. This may be useful for @@ -65040,7 +65553,7 @@ on the socket. - + Gets the keepalive mode of the socket. For details on this, see g_socket_set_keepalive(). @@ -65054,7 +65567,7 @@ see g_socket_set_keepalive(). - + Gets the listen backlog setting of the socket. For details on this, see g_socket_set_listen_backlog(). @@ -65068,7 +65581,7 @@ see g_socket_set_listen_backlog(). - + Try to get the local address of a bound socket. This is only useful if the socket has been bound to a local address, either explicitly or implicitly when connecting. @@ -65084,7 +65597,7 @@ either explicitly or implicitly when connecting. - + Gets the multicast loopback setting on @socket; if %TRUE (the default), outgoing multicast packets will be looped back to multicast listeners on the same host. @@ -65099,7 +65612,7 @@ multicast listeners on the same host. - + Gets the multicast time-to-live setting on @socket; see g_socket_set_multicast_ttl() for more details. @@ -65152,7 +65665,7 @@ g_socket_get_option() will handle the conversion internally. - + Gets the socket protocol id the socket was created with. In case the protocol is unknown, -1 is returned. @@ -65166,7 +65679,7 @@ In case the protocol is unknown, -1 is returned. - + Try to get the remote address of a connected socket. This is only useful for connection oriented sockets that have been connected. @@ -65194,7 +65707,7 @@ useful for connection oriented sockets that have been connected. - + Gets the timeout setting of the socket. For details on this, see g_socket_set_timeout(). @@ -65208,7 +65721,7 @@ g_socket_set_timeout(). - + Gets the unicast time-to-live setting on @socket; see g_socket_set_ttl() for more details. @@ -66069,7 +66582,7 @@ on error - + Sets the blocking mode of the socket. In blocking mode all operations (which don’t take an explicit blocking parameter) block until they succeed or there is an error. In @@ -66093,7 +66606,7 @@ is a GSocket level feature. - + Sets whether @socket should allow sending to broadcast addresses. This is %FALSE by default. @@ -66111,7 +66624,7 @@ This is %FALSE by default. - + Sets or unsets the %SO_KEEPALIVE flag on the underlying socket. When this flag is set on a socket, the system will attempt to verify that the remote socket endpoint is still present if a sufficiently long period of @@ -66141,7 +66654,7 @@ garbage-collected if clients crash or become unreachable. - + Sets the maximum number of outstanding connections allowed when listening on this socket. If more clients than this are connecting to the socket and the application is not handling them @@ -66163,7 +66676,7 @@ effect if called after that. - + Sets whether outgoing multicast packets will be received by sockets listening on that multicast address on the same host. This is %TRUE by default. @@ -66182,7 +66695,7 @@ by default. - + Sets the time-to-live for outgoing multicast datagrams on @socket. By default, this is 1, meaning that multicast packets will not leave the local network. @@ -66235,7 +66748,7 @@ headers. - + Sets the time in seconds after which I/O operations on @socket will time out if they have not yet completed. @@ -66270,7 +66783,7 @@ cause the timeout to be reset. - + Sets the time-to-live for outgoing unicast packets on @socket. By default the platform-specific default value is used. @@ -66342,47 +66855,47 @@ of speaking IPv4. - + - + Whether the socket should allow sending to broadcast addresses. - + - + - + - + - + - + Whether outgoing multicast packets loop back to the local host. - + Time-to-live out outgoing multicast packets - + - + - + The timeout in seconds on socket I/O - + Time-to-live for outgoing unicast packets @@ -66477,7 +66990,7 @@ struct sockaddr - + Gets the socket family type of @address. the socket family type of @address @@ -66534,7 +67047,7 @@ struct sockaddr - + @@ -67393,7 +67906,7 @@ the result of the operation. - + Gets the proxy enable state; see g_socket_client_set_enable_proxy() whether proxying is enabled @@ -67406,7 +67919,7 @@ the result of the operation. - + Gets the socket family of the socket client. See g_socket_client_set_family() for details. @@ -67421,7 +67934,7 @@ See g_socket_client_set_family() for details. - + Gets the local address of the socket client. See g_socket_client_set_local_address() for details. @@ -67436,7 +67949,7 @@ See g_socket_client_set_local_address() for details. - + Gets the protocol name type of the socket client. See g_socket_client_set_protocol() for details. @@ -67451,7 +67964,7 @@ See g_socket_client_set_protocol() for details. - + Gets the #GProxyResolver being used by @client. Normally, this will be the resolver returned by g_proxy_resolver_get_default(), but you can override it with g_socket_client_set_proxy_resolver(). @@ -67482,7 +67995,7 @@ See g_socket_client_set_socket_type() for details. - + Gets the I/O timeout time for sockets created by @client. See g_socket_client_set_timeout() for details. @@ -67497,7 +68010,7 @@ See g_socket_client_set_timeout() for details. - + Gets whether @client creates TLS connections. See g_socket_client_set_tls() for details. @@ -67511,7 +68024,7 @@ g_socket_client_set_tls() for details. - + Gets the TLS validation flags used creating TLS connections via @client. @@ -67525,7 +68038,7 @@ g_socket_client_set_tls() for details. - + Sets whether or not @client attempts to make connections via a proxy server. When enabled (the default), #GSocketClient will use a #GProxyResolver to determine if a proxy protocol such as SOCKS is @@ -67546,7 +68059,7 @@ See also g_socket_client_set_proxy_resolver(). - + Sets the socket family of the socket client. If this is set to something other than %G_SOCKET_FAMILY_INVALID then the sockets created by this object will be of the specified @@ -67569,7 +68082,7 @@ be an ipv6 mapped to ipv4 address. - + Sets the local address of the socket client. The sockets created by this object will bound to the specified address (if not %NULL) before connecting. @@ -67591,7 +68104,7 @@ a specific interface. - + Sets the protocol of the socket client. The sockets created by this object will use of the specified protocol. @@ -67612,7 +68125,7 @@ protocol for the socket family and type. - + Overrides the #GProxyResolver used by @client. You can call this if you want to use specific proxies, rather than using the system default proxy settings. @@ -67656,7 +68169,7 @@ as GSocketClient is used for connection oriented services. - + Sets the I/O timeout for sockets created by @client. @timeout is a time in seconds, or 0 for no timeout (the default). @@ -67677,7 +68190,7 @@ to fail with %G_IO_ERROR_TIMED_OUT. - + Sets whether @client creates TLS (aka SSL) connections. If @tls is %TRUE, @client will wrap its connections in a #GTlsClientConnection and perform a TLS handshake when connecting. @@ -67710,7 +68223,7 @@ starts. - + Sets the TLS validation flags used when creating TLS connections via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. @@ -67727,29 +68240,29 @@ via @client. The default value is %G_TLS_CERTIFICATE_VALIDATE_ALL. - + - + - + - + - + The proxy resolver to use - + - + - + @@ -67889,37 +68402,37 @@ the future; unrecognized @event values should be ignored. #GSocketClient::event signal for more details. Additional values may be added to this type in the future. - + The client is doing a DNS lookup. - + The client has completed a DNS lookup. - + The client is connecting to a remote host (either a proxy or the destination server). - + The client has connected to a remote host. - + The client is negotiating with a proxy to connect to the destination server. - + The client has negotiated with the proxy server. - + The client is performing a TLS handshake. - + The client has performed a TLS handshake. - + The client is done with a particular #GSocketConnectable. @@ -68310,7 +68823,7 @@ applications to print e.g. "Connecting to example.com - + Gets the underlying #GSocket object of the connection. This can be useful if you want to do something unusual on it not supported by the #GSocketConnection APIs. @@ -68339,7 +68852,7 @@ g_socket_is_connected() on @connection's underlying #GSocket. - + @@ -68704,16 +69217,16 @@ object. The protocol family of a #GSocketAddress. (These values are identical to the system defines %AF_INET, %AF_INET6 and %AF_UNIX, if available.) - + no address family - + the UNIX domain family - + the IPv4 family - + the IPv6 family @@ -68802,7 +69315,7 @@ was cancelled, the error %G_IO_ERROR_CANCELLED will be returned. This is the asynchronous version of g_socket_listener_accept(). When the operation is finished @callback will be -called. You can then call g_socket_listener_accept_socket() +called. You can then call g_socket_listener_accept_finish() to get the result of the operation. @@ -69213,17 +69726,17 @@ the order they happen in is undefined. #GSocketListener::event signal for more details. Additional values may be added to this type in the future. - + The listener is about to bind a socket. - + The listener has bound a socket. - + The listener is about to start listening on this socket. - + The listener is now listening on this socket. @@ -69235,17 +69748,17 @@ The flags listed in the enum are some commonly available flags, but the values used for them are the same as on the platform, and any other flags are passed in/out as is. So to use a platform specific flag, just include the right system header and pass in the flag. - + No flags. - + Request to send/receive out of band data. - + Read data from the socket without removing it from the queue. - + Don't use a gateway to send out the packet, only send to hosts on directly connected networks. @@ -69259,19 +69772,19 @@ the particular family/type. This enum contains a set of commonly available and used protocols. You can also pass any other identifiers handled by the platform in order to use protocols not listed here. - + The protocol type is unknown - + The default protocol for the family/type - + TCP over IP - + UDP over IP - + SCTP over IP @@ -69518,17 +70031,17 @@ returned by g_socket_create_source(). Flags used when creating a #GSocket. Some protocols may not implement all the socket types. - + Type unknown or wrong - + Reliable connection-based byte streams (e.g. TCP). - + Connectionless, unreliable datagram passing. (e.g. UDP) - + Reliable connection-based passing of datagrams of fixed maximum length (e.g. SCTP). @@ -70160,7 +70673,7 @@ returned. This value has no particular meaning, but it can be used with the macros defined by the system headers such as WIFEXITED. It can also -be used with g_spawn_check_exit_status(). +be used with g_spawn_check_wait_status(). It is more likely that you want to use g_subprocess_get_if_exited() followed by g_subprocess_get_exit_status(). @@ -70342,7 +70855,7 @@ This is the asynchronous version of g_subprocess_wait(). - Combines g_subprocess_wait() with g_spawn_check_exit_status(). + Combines g_subprocess_wait() with g_spawn_check_wait_status(). %TRUE on success, %FALSE if process exited abnormally, or @cancellable was cancelled @@ -70360,7 +70873,7 @@ This is the asynchronous version of g_subprocess_wait(). - Combines g_subprocess_wait_async() with g_spawn_check_exit_status(). + Combines g_subprocess_wait_async() with g_spawn_check_wait_status(). This is the asynchronous version of g_subprocess_wait_check(). @@ -70440,42 +70953,42 @@ corresponding descriptor from the calling process. Note that it is a programmer error to mix 'incompatible' flags. For example, you may not request both %G_SUBPROCESS_FLAGS_STDOUT_PIPE and %G_SUBPROCESS_FLAGS_STDOUT_SILENCE. - + No flags. - + create a pipe for the stdin of the spawned process that can be accessed with g_subprocess_get_stdin_pipe(). - + stdin is inherited from the calling process. - + create a pipe for the stdout of the spawned process that can be accessed with g_subprocess_get_stdout_pipe(). - + silence the stdout of the spawned process (ie: redirect to `/dev/null`). - + create a pipe for the stderr of the spawned process that can be accessed with g_subprocess_get_stderr_pipe(). - + silence the stderr of the spawned process (ie: redirect to `/dev/null`). - + merge the stderr of the spawned process with whatever the stdout happens to be. This is a good way of directing both streams to a common log file, for example. - + spawned processes will inherit the file descriptors of their parent, unless those descriptors have been explicitly marked as close-on-exec. This flag has no effect @@ -70507,6 +71020,27 @@ and will be used as the environment that the process is launched in. + + Closes all the file descriptors previously passed to the object with +g_subprocess_launcher_take_fd(), g_subprocess_launcher_take_stderr_fd(), etc. + +After calling this method, any subsequent calls to g_subprocess_launcher_spawn() or g_subprocess_launcher_spawnv() will +return %G_IO_ERROR_CLOSED. This method is idempotent if +called more than once. + +This function is called automatically when the #GSubprocessLauncher +is disposed, but is provided separately so that garbage collected +language bindings can call it earlier to guarantee when FDs are closed. + + + + + + a #GSubprocessLauncher + + + + Returns the value of the environment variable @variable in the environment of processes launched from this launcher. @@ -71919,7 +72453,7 @@ g_task_set_check_cancellable() for more details. - + Gets the value of #GTask:completed. This changes from %FALSE to %TRUE after the task’s callback is invoked, and will return %FALSE if called from inside the callback. @@ -72312,9 +72846,9 @@ See #GTaskThreadFunc for more details about how @task_func is handled. Although GLib currently rate-limits the tasks queued via g_task_run_in_thread(), you should not assume that it will always -do this. If you have a very large number of tasks to run, but don't -want them to all run at once, you should only queue a limited -number of them at a time. +do this. If you have a very large number of tasks to run (several tens of +tasks), but don't want them to all run at once, you should only queue a +limited number of them (around ten) at a time. @@ -72524,7 +73058,7 @@ particular place. - + Whether the task has completed, meaning its callback (if set) has been invoked. This can only happen after g_task_return_pointer(), g_task_return_error() or one of the other return functions have been called @@ -72579,7 +73113,7 @@ Other than in that case, @task will be completed when the This is the subclass of #GSocketConnection that is created for TCP/IP sockets. - + Checks if graceful disconnects are used. See g_tcp_connection_set_graceful_disconnect(). @@ -72593,7 +73127,7 @@ g_tcp_connection_set_graceful_disconnect(). - + This enables graceful disconnects on close. A graceful disconnect means that we signal the receiving end that the connection is terminated and wait for it to close the connection before closing the connection. @@ -72617,7 +73151,7 @@ take a while. For this reason it is disabled by default. - + @@ -72656,7 +73190,7 @@ actually created is not directly a #GSocketConnection. - + Gets @conn's base #GIOStream @conn's base #GIOStream @@ -72669,7 +73203,7 @@ actually created is not directly a #GSocketConnection. - + @@ -72730,7 +73264,7 @@ you can proceed to set up a GTest fixture using the #GTestDBus scaffolding. An example of a test fixture for D-Bus services can be found here: -[gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c) +[gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c) Note that these examples only deal with isolating the D-Bus aspect of your service. To successfully run isolated unit tests on your service you may need @@ -72830,7 +73364,7 @@ g_dbus_connection_new_for_address(). - + Get the flags of the #GTestDBus object. the value of #GTestDBus:flags property @@ -72879,14 +73413,14 @@ must be called after g_test_run(). - + #GTestDBusFlags specifying the behaviour of the D-Bus session. Flags to define future #GTestDBus behaviour. - + No flags. @@ -72978,7 +73512,7 @@ to g_icon_hash(). - + Gets the names of icons from within @icon. a list of icon names. @@ -73016,7 +73550,7 @@ to g_icon_hash(). The icon name. - + A %NULL-terminated array of icon names. @@ -73180,13 +73714,13 @@ not return until the connection is closed. The client authentication mode for a #GTlsServerConnection. - + client authentication not required - + client authentication is requested - + client authentication is required @@ -73576,6 +74110,46 @@ the file will still be returned. + + Creates a #GTlsCertificate from a +[PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) URI. + +An example @pkcs11_uri would be `pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01` + +Where the token’s layout is: + +|[ +Object 0: + URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private + Type: Private key (RSA-2048) + ID: 01 + +Object 1: + URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert + Type: X.509 Certificate (RSA-2048) + ID: 01 +]| + +In this case the certificate and private key would both be detected and used as expected. +@pkcs_uri may also just reference an X.509 certificate object and then optionally +@private_key_pkcs11_uri allows using a private key exposed under a different URI. + +Note that the private key is not accessed until usage and may fail or require a PIN later. + + the new certificate, or %NULL on error + + + + + A PKCS \#11 URI + + + + A PKCS \#11 URI + + + + Creates one or more #GTlsCertificates from the PEM-encoded data in @file. If @file cannot be read or parsed, the function will @@ -73616,7 +74190,14 @@ in its chain) must be signed by it, or else value. (All other #GTlsCertificateFlags values will always be set or unset -as appropriate.) +as appropriate.) + +Because TLS session context is not used, #GTlsCertificate may not +perform as many checks on the certificates as #GTlsConnection would. +For example, certificate constraints cannot be honored, and some +revocation checks cannot be performed. The best way to verify TLS +certificates used by a TLS connection is to let #GTlsConnection +handle the verification. the appropriate #GTlsCertificateFlags @@ -73636,7 +74217,39 @@ as appropriate.) - + + Gets the value of #GTlsCertificate:dns-names. + + A #GPtrArray of +#GBytes elements, or %NULL if it's not available. + + + + + + + a #GTlsCertificate + + + + + + Gets the value of #GTlsCertificate:ip-addresses. + + A #GPtrArray +of #GInetAddress elements, or %NULL if it's not available. + + + + + + + a #GTlsCertificate + + + + + Gets the #GTlsCertificate representing @cert's issuer, if known The certificate of @cert's issuer, @@ -73651,6 +74264,58 @@ certificate. + + Returns the issuer name from the certificate. + + The issuer name, or %NULL if it's not available. + + + + + a #GTlsCertificate + + + + + + Returns the time at which the certificate became or will become invalid. + + The not-valid-after date, or %NULL if it's not available. + + + + + a #GTlsCertificate + + + + + + Returns the time at which the certificate became or will become valid. + + The not-valid-before date, or %NULL if it's not available. + + + + + a #GTlsCertificate + + + + + + Returns the subject name from the certificate. + + The subject name, or %NULL if it's not available. + + + + + a #GTlsCertificate + + + + Check if two #GTlsCertificate objects represent the same certificate. The raw DER byte data of the two certificates are checked for equality. @@ -73691,7 +74356,14 @@ in its chain) must be signed by it, or else value. (All other #GTlsCertificateFlags values will always be set or unset -as appropriate.) +as appropriate.) + +Because TLS session context is not used, #GTlsCertificate may not +perform as many checks on the certificates as #GTlsConnection would. +For example, certificate constraints cannot be honored, and some +revocation checks cannot be performed. The best way to verify TLS +certificates used by a TLS connection is to let #GTlsConnection +handle the verification. the appropriate #GTlsCertificateFlags @@ -73725,38 +74397,113 @@ This property and the #GTlsCertificate:certificate property represent the same data, just in different forms. - + + The DNS names from the certificate's Subject Alternative Names (SANs), +%NULL if unavailable. + + + + + + The IP addresses from the certificate's Subject Alternative Names (SANs), +%NULL if unavailable. + + + + + A #GTlsCertificate representing the entity that issued this certificate. If %NULL, this means that the certificate is either self-signed, or else the certificate of the issuer is not -available. +available. + +Beware the issuer certificate may not be the same as the +certificate that would actually be used to construct a valid +certification path during certificate verification. +[RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains +why an issuer certificate cannot be naively assumed to be part of the +the certification path (though GLib's TLS backends may not follow the +path building strategies outlined in this RFC). Due to the complexity +of certification path building, GLib does not provide any way to know +which certification path will actually be used. Accordingly, this +property cannot be used to make security-related decisions. Only +GLib itself should make security decisions about TLS certificates. - - The DER (binary) encoded representation of the certificate's -private key, in either PKCS#1 format or unencrypted PKCS#8 -format. This property (or the #GTlsCertificate:private-key-pem -property) can be set when constructing a key (eg, from a file), -but cannot be read. + + The issuer from the certificate, +%NULL if unavailable. + + + + The time at which this cert is no longer valid, +%NULL if unavailable. + + + + The time at which this cert is considered to be valid, +%NULL if unavailable. + + + + A URI referencing the [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) +objects containing an X.509 certificate and optionally a private key. -PKCS#8 format is supported since 2.32; earlier releases only -support PKCS#1. You can use the `openssl rsa` -tool to convert PKCS#8 keys to PKCS#1. +If %NULL, the certificate is either not backed by PKCS \#11 or the +#GTlsBackend does not support PKCS \#11. + + + + The DER (binary) encoded representation of the certificate's +private key, in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) +or unencrypted [PKCS \#8 format.](https://datatracker.ietf.org/doc/html/rfc5208) +PKCS \#8 format is supported since 2.32; earlier releases only +support PKCS \#1. You can use the `openssl rsa` tool to convert +PKCS \#8 keys to PKCS \#1. + +This property (or the #GTlsCertificate:private-key-pem property) +can be set when constructing a key (for example, from a file). +Since GLib 2.70, it is now also readable; however, be aware that if +the private key is backed by a PKCS \#11 URI – for example, if it +is stored on a smartcard – then this property will be %NULL. If so, +the private key must be referenced via its PKCS \#11 URI, +#GTlsCertificate:private-key-pkcs11-uri. You must check both +properties to see if the certificate really has a private key. +When this property is read, the output format will be unencrypted +PKCS \#8. - + The PEM (ASCII) encoded representation of the certificate's -private key in either PKCS#1 format ("`BEGIN RSA PRIVATE -KEY`") or unencrypted PKCS#8 format ("`BEGIN -PRIVATE KEY`"). This property (or the -#GTlsCertificate:private-key property) can be set when -constructing a key (eg, from a file), but cannot be read. +private key in either [PKCS \#1 format](https://datatracker.ietf.org/doc/html/rfc8017) +("`BEGIN RSA PRIVATE KEY`") or unencrypted +[PKCS \#8 format](https://datatracker.ietf.org/doc/html/rfc5208) +("`BEGIN PRIVATE KEY`"). PKCS \#8 format is supported since 2.32; +earlier releases only support PKCS \#1. You can use the `openssl rsa` +tool to convert PKCS \#8 keys to PKCS \#1. -PKCS#8 format is supported since 2.32; earlier releases only -support PKCS#1. You can use the `openssl rsa` -tool to convert PKCS#8 keys to PKCS#1. +This property (or the #GTlsCertificate:private-key property) +can be set when constructing a key (for example, from a file). +Since GLib 2.70, it is now also readable; however, be aware that if +the private key is backed by a PKCS \#11 URI - for example, if it +is stored on a smartcard - then this property will be %NULL. If so, +the private key must be referenced via its PKCS \#11 URI, +#GTlsCertificate:private-key-pkcs11-uri. You must check both +properties to see if the certificate really has a private key. +When this property is read, the output format will be unencrypted +PKCS \#8. + + + + A URI referencing a [PKCS \#11](https://docs.oasis-open.org/pkcs11/pkcs11-base/v3.0/os/pkcs11-base-v3.0-os.html) +object containing a private key. + + + + The subject from the cert, +%NULL if unavailable. @@ -73804,34 +74551,34 @@ used to set which validation steps to perform (eg, with g_tls_client_connection_set_validation_flags()), or to describe why a particular certificate was rejected (eg, in #GTlsConnection::accept-certificate). - + The signing certificate authority is not known. - + The certificate does not match the expected identity of the site that it was retrieved from. - + The certificate's activation time is still in the future - + The certificate has expired - + The certificate has been revoked according to the #GTlsConnection's certificate revocation list. - + The certificate's algorithm is considered insecure. - + Some other error occurred validating the certificate - + the combination of all of the above flags @@ -73841,36 +74588,36 @@ a particular certificate was rejected (eg, in Flags for g_tls_interaction_request_certificate(), g_tls_interaction_request_certificate_async(), and g_tls_interaction_invoke_request_certificate(). - + No flags An error code used with %G_TLS_CHANNEL_BINDING_ERROR in a #GError to indicate a TLS channel binding retrieval error. - + Either entire binding retrieval facility or specific binding type is not implemented in the TLS backend. - + The handshake is not yet complete on the connection which is a strong requirement for any existing binding type. - + Handshake is complete but binding data is not available. That normally indicates the TLS implementation failed to provide the binding data. For example, some implementations do not provide a peer certificate for resumed connections. - + Binding type is not supported on the current connection. This error could be triggered when requesting `tls-server-end-point` binding data for a certificate which has no hash function or uses multiple hash functions. - + Any other backend error preventing binding data retrieval. @@ -73887,11 +74634,11 @@ indicate a TLS channel binding retrieval error. or #GDtlsConnection, as documented by RFC 5929. The [`tls-unique-for-telnet`](https://tools.ietf.org/html/rfc5929#section-5) binding type is not currently implemented. - + [`tls-unique`](https://tools.ietf.org/html/rfc5929#section-3) binding type - + [`tls-server-end-point`](https://tools.ietf.org/html/rfc5929#section-4) binding type @@ -74010,7 +74757,7 @@ ticket to be copied without regard for privacy considerations. - + Gets the list of distinguished names of the Certificate Authorities that the server will accept certificates from. This will be set during the TLS handshake if the server requests a certificate. @@ -74035,7 +74782,7 @@ the free the list with g_list_free(). - + Gets @conn's expected server identity a #GSocketConnectable describing the @@ -74050,7 +74797,7 @@ known. - + SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details. SSL 3.0 is insecure. @@ -74065,7 +74812,7 @@ g_tls_client_connection_set_use_ssl3() for details. - + Gets @conn's validation flags the validation flags @@ -74078,7 +74825,7 @@ g_tls_client_connection_set_use_ssl3() for details. - + Sets @conn's expected server identity, which is used both to tell servers on virtual hosts which certificate to present, and also to let @conn know what name to look for in the certificate when @@ -74097,7 +74844,7 @@ performing %G_TLS_CERTIFICATE_BAD_IDENTITY validation, if enabled. - + Since GLib 2.42.1, SSL 3.0 is no longer supported. From GLib 2.42.1 through GLib 2.62, this function could be used to @@ -74123,7 +74870,7 @@ Since GLib 2.64, this function does nothing. - + Sets @conn's validation flags, to override the default set of checks performed when validating a server certificate. By default, %G_TLS_CERTIFICATE_VALIDATE_ALL is used. @@ -74141,7 +74888,7 @@ checks performed when validating a server certificate. By default, - + A list of the distinguished names of the Certificate Authorities that the server will accept client certificates signed by. If the server requests a client certificate during the handshake, then @@ -74153,7 +74900,7 @@ subject DN of the certificate authority. - + A #GSocketConnectable describing the identity of the server that is expected on the other end of the connection. @@ -74170,13 +74917,13 @@ certificate we expect, which is useful for servers that serve virtual hosts. - + SSL 3.0 is no longer supported. See g_tls_client_connection_set_use_ssl3() for details. SSL 3.0 is insecure. - + What steps to perform when validating a certificate received from a server. Server certificates that fail to validate in any of the ways indicated here will be rejected unless the application @@ -74249,6 +74996,25 @@ For DTLS (Datagram TLS) support, see #GDtlsConnection. + + Gets the name of the application-layer protocol negotiated during +the handshake. + +If the peer did not use the ALPN extension, or did not advertise a +protocol that matched one of @conn's protocols, or the TLS backend +does not support ALPN, then this will be %NULL. See +g_tls_connection_set_advertised_protocols(). + + the negotiated protocol, or %NULL + + + + + a #GTlsConnection + + + + Attempts a TLS handshake on @conn. @@ -74367,7 +75133,7 @@ case @error will be set. - + Gets @conn's certificate, as set by g_tls_connection_set_certificate(). @@ -74417,7 +75183,27 @@ negotiation or input required. - + + Returns the name of the current TLS ciphersuite, or %NULL if the +connection has not handshaked or has been closed. Beware that the TLS +backend may use any of multiple different naming conventions, because +OpenSSL and GnuTLS have their own ciphersuite naming conventions that +are different from each other and different from the standard, IANA- +registered ciphersuite names. The ciphersuite name is intended to be +displayed to the user for informative purposes only, and parsing it +is not recommended. + + The name of the current TLS ciphersuite, or %NULL + + + + + a #GTlsConnection + + + + + Gets the certificate database that @conn uses to verify peer certificates. See g_tls_connection_set_database(). @@ -74431,7 +75217,7 @@ peer certificates. See g_tls_connection_set_database(). - + Get the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. If %NULL is returned, then no user interaction will occur for this connection. @@ -74446,7 +75232,7 @@ no user interaction will occur for this connection. - + Gets the name of the application-layer protocol negotiated during the handshake. @@ -74465,7 +75251,7 @@ g_tls_connection_set_advertised_protocols(). - + Gets @conn's peer's certificate after the handshake has completed or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) @@ -74480,7 +75266,7 @@ or failed. (It is not set during the emission of - + Gets the errors associated with validating @conn's peer's certificate, after the handshake has completed or failed. (It is not set during the emission of #GTlsConnection::accept-certificate.) @@ -74495,7 +75281,23 @@ not set during the emission of #GTlsConnection::accept-certificate.) - + + Returns the current TLS protocol version, which may be +%G_TLS_PROTOCOL_VERSION_UNKNOWN if the connection has not handshaked, or +has been closed, or if the TLS backend has implemented a protocol version +that is not a recognized #GTlsProtocolVersion. + + The current TLS protocol version + + + + + a #GTlsConnection + + + + + Gets @conn rehandshaking mode. See g_tls_connection_set_rehandshake_mode() for details. Changing the rehandshake mode is no longer @@ -74512,7 +75314,7 @@ g_tls_connection_set_rehandshake_mode() for details. - + Tests whether or not @conn expects a proper TLS close notification when the connection is closed. See g_tls_connection_set_require_close_notify() for details. @@ -74528,7 +75330,7 @@ notification. - + Gets whether @conn uses the system certificate database to verify peer certificates. See g_tls_connection_set_use_system_certdb(). Use g_tls_connection_get_database() instead @@ -74638,7 +75440,7 @@ case @error will be set. - + Sets the list of application-layer protocols to advertise that the caller is willing to speak on this connection. The Application-Layer Protocol Negotiation (ALPN) extension will be @@ -74666,7 +75468,7 @@ for a list of registered protocol IDs. - + This sets the certificate that @conn will present to its peer during the TLS handshake. For a #GTlsServerConnection, it is mandatory to set this, and that will normally be done at construct @@ -74699,7 +75501,7 @@ non-%NULL.) - + Sets the certificate database that is used to verify peer certificates. This is set to the default database by default. See g_tls_backend_get_default_database(). If set to %NULL, then @@ -74722,7 +75524,7 @@ client-side connections, unless that bit is not set in - + Set the object that will be used to interact with the user. It will be used for things like prompting the user for passwords. @@ -74743,7 +75545,7 @@ should occur for this connection. - + Since GLib 2.64, changing the rehandshake mode is no longer supported and will have no effect. With TLS 1.3, rehandshaking has been removed from the TLS protocol, replaced by separate post-handshake authentication and @@ -74765,7 +75567,7 @@ rekey operations. - + Sets whether or not @conn expects a proper TLS close notification before the connection is closed. If this is %TRUE (the default), then @conn will expect to receive a TLS close notification from its @@ -74807,7 +75609,7 @@ operations are pending on @conn or the base I/O stream. - + Sets whether @conn uses the system certificate database to verify peer certificates. This is %TRUE by default. If set to %FALSE, then peer certificate validation will always set the @@ -74830,7 +75632,7 @@ client-side connections, unless that bit is not set in - + The list of application-layer protocols that the connection advertises that it is willing to speak. See g_tls_connection_set_advertised_protocols(). @@ -74846,29 +75648,33 @@ constructed, application code may only run its own operations on this stream when no #GIOStream operations are running. - + The connection's certificate; see g_tls_connection_set_certificate(). - + + The name of the TLS ciphersuite in use. See g_tls_connection_get_ciphersuite_name(). + + + The certificate database to use when verifying this TLS connection. If no certificate database is set, then the default database will be used. See g_tls_backend_get_default_database(). - + A #GTlsInteraction object to be used when the connection or certificate database need to interact with the user. This will be used to prompt the user for passwords where necessary. - + The application-layer protocol negotiated during the TLS handshake. See g_tls_connection_get_negotiated_protocol(). - + The connection's peer's certificate, after the TLS handshake has completed or failed. Note in particular that this is not yet set during the emission of #GTlsConnection::accept-certificate. @@ -74877,7 +75683,7 @@ during the emission of #GTlsConnection::accept-certificate. detect when a handshake has occurred.) - + The errors noticed while verifying #GTlsConnection:peer-certificate. Normally this should be 0, but it may not be if #GTlsClientConnection:validation-flags is not @@ -74886,18 +75692,22 @@ it may not be if #GTlsClientConnection:validation-flags is not behavior. - + + The TLS protocol version in use. See g_tls_connection_get_protocol_version(). + + + The rehandshaking mode. See g_tls_connection_set_rehandshake_mode(). The rehandshake mode is ignored. - + Whether or not proper TLS close notification is required. See g_tls_connection_set_require_close_notify(). - + Whether or not the system certificate database will be used to verify peer certificates. See g_tls_connection_set_use_system_certdb(). @@ -74963,8 +75773,10 @@ no one else overrides it. - + + The class structure for the #GTlsConnection type. + The parent class. @@ -75071,8 +75883,22 @@ case @error will be set. + + + + the negotiated protocol, or %NULL + + + + + a #GTlsConnection + + + + + - + @@ -75214,14 +76040,26 @@ Use g_object_unref() to release the certificate. - Look up the issuer of @certificate in the database. + Look up the issuer of @certificate in the database. The +#GTlsCertificate:issuer property of @certificate is not modified, and +the two certificates are not hooked into a chain. -The #GTlsCertificate:issuer property -of @certificate is not modified, and the two certificates are not hooked -into a chain. +This function can block. Use g_tls_database_lookup_certificate_issuer_async() +to perform the lookup operation asynchronously. -This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform -the lookup operation asynchronously. +Beware this function cannot be used to build certification paths. The +issuer certificate returned by this function may not be the same as +the certificate that would actually be used to construct a valid +certification path during certificate verification. +[RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains +why an issuer certificate cannot be naively assumed to be part of the +the certification path (though GLib's TLS backends may not follow the +path building strategies outlined in this RFC). Due to the complexity +of certification path building, GLib does not provide any way to know +which certification path will actually be used when verifying a TLS +certificate. Accordingly, this function cannot be used to make +security-related decisions. Only GLib itself should make security +decisions about TLS certificates. a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. @@ -75408,15 +76246,11 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele - Determines the validity of a certificate chain after looking up and -adding any missing certificates to the chain. + Determines the validity of a certificate chain, outside the context +of a TLS session. @chain is a chain of #GTlsCertificate objects each pointing to the next -certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially -consist of one or more certificates. After the verification process is -complete, @chain may be modified by adding missing certificates, or removing -extra certificates. If a certificate anchor was found, then it is added to -the @chain. +certificate in the chain by its #GTlsCertificate:issuer property. @purpose describes the purpose (or usage) for which the certificate is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER @@ -75443,8 +76277,27 @@ before it completes) then the return value will be accordingly. @error is not set when @chain is successfully analyzed but found to be invalid. -This function can block, use g_tls_database_verify_chain_async() to perform -the verification operation asynchronously. +Prior to GLib 2.48, GLib's default TLS backend modified @chain to +represent the certification path built by #GTlsDatabase during +certificate verification by adjusting the #GTlsCertificate:issuer +property of each certificate in @chain. Since GLib 2.48, this no +longer occurs, so you cannot rely on #GTlsCertificate:issuer to +represent the actual certification path used during certificate +verification. + +Because TLS session context is not used, #GTlsDatabase may not +perform as many checks on the certificates as #GTlsConnection would. +For example, certificate constraints cannot be honored, and some +revocation checks cannot be performed. The best way to verify TLS +certificates used by a TLS connection is to let #GTlsConnection +handle the verification. + +The TLS backend may attempt to look up and add missing certificates +to the chain. Since GLib 2.70, this may involve HTTP requests to +download missing certificates. + +This function can block. Use g_tls_database_verify_chain_async() to +perform the verification operation asynchronously. the appropriate #GTlsCertificateFlags which represents the result of verification. @@ -75681,14 +76534,26 @@ Use g_object_unref() to release the certificate. - Look up the issuer of @certificate in the database. + Look up the issuer of @certificate in the database. The +#GTlsCertificate:issuer property of @certificate is not modified, and +the two certificates are not hooked into a chain. -The #GTlsCertificate:issuer property -of @certificate is not modified, and the two certificates are not hooked -into a chain. +This function can block. Use g_tls_database_lookup_certificate_issuer_async() +to perform the lookup operation asynchronously. -This function can block, use g_tls_database_lookup_certificate_issuer_async() to perform -the lookup operation asynchronously. +Beware this function cannot be used to build certification paths. The +issuer certificate returned by this function may not be the same as +the certificate that would actually be used to construct a valid +certification path during certificate verification. +[RFC 4158](https://datatracker.ietf.org/doc/html/rfc4158) explains +why an issuer certificate cannot be naively assumed to be part of the +the certification path (though GLib's TLS backends may not follow the +path building strategies outlined in this RFC). Due to the complexity +of certification path building, GLib does not provide any way to know +which certification path will actually be used when verifying a TLS +certificate. Accordingly, this function cannot be used to make +security-related decisions. Only GLib itself should make security +decisions about TLS certificates. a newly allocated issuer #GTlsCertificate, or %NULL. Use g_object_unref() to release the certificate. @@ -75875,15 +76740,11 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele - Determines the validity of a certificate chain after looking up and -adding any missing certificates to the chain. + Determines the validity of a certificate chain, outside the context +of a TLS session. @chain is a chain of #GTlsCertificate objects each pointing to the next -certificate in the chain by its #GTlsCertificate:issuer property. The chain may initially -consist of one or more certificates. After the verification process is -complete, @chain may be modified by adding missing certificates, or removing -extra certificates. If a certificate anchor was found, then it is added to -the @chain. +certificate in the chain by its #GTlsCertificate:issuer property. @purpose describes the purpose (or usage) for which the certificate is being used. Typically @purpose will be set to #G_TLS_DATABASE_PURPOSE_AUTHENTICATE_SERVER @@ -75910,8 +76771,27 @@ before it completes) then the return value will be accordingly. @error is not set when @chain is successfully analyzed but found to be invalid. -This function can block, use g_tls_database_verify_chain_async() to perform -the verification operation asynchronously. +Prior to GLib 2.48, GLib's default TLS backend modified @chain to +represent the certification path built by #GTlsDatabase during +certificate verification by adjusting the #GTlsCertificate:issuer +property of each certificate in @chain. Since GLib 2.48, this no +longer occurs, so you cannot rely on #GTlsCertificate:issuer to +represent the actual certification path used during certificate +verification. + +Because TLS session context is not used, #GTlsDatabase may not +perform as many checks on the certificates as #GTlsConnection would. +For example, certificate constraints cannot be honored, and some +revocation checks cannot be performed. The best way to verify TLS +certificates used by a TLS connection is to let #GTlsConnection +handle the verification. + +The TLS backend may attempt to look up and add missing certificates +to the chain. Since GLib 2.70, this may involve HTTP requests to +download missing certificates. + +This function can block. Use g_tls_database_verify_chain_async() to +perform the verification operation asynchronously. the appropriate #GTlsCertificateFlags which represents the result of verification. @@ -76437,10 +77317,10 @@ objects. Use g_object_unref() on each certificate, and g_list_free() on the rele Flags for g_tls_database_lookup_certificate_for_handle(), g_tls_database_lookup_certificate_issuer(), and g_tls_database_lookup_certificates_issued_by(). - + No lookup flags - + Restrict lookup to certificates that have a private key. @@ -76448,42 +77328,42 @@ and g_tls_database_lookup_certificates_issued_by(). Flags for g_tls_database_verify_chain(). - + No verification flags An error code used with %G_TLS_ERROR in a #GError returned from a TLS-related routine. - + No TLS provider is available - + Miscellaneous TLS error - + The certificate presented could not be parsed or failed validation. - + The TLS handshake failed because the peer does not seem to be a TLS server. - + The TLS handshake failed because the peer's certificate was not acceptable. - + The TLS handshake failed because the server requested a client-side certificate, but none was provided. See g_tls_connection_set_certificate(). - + The TLS connection was closed without proper notice, which may indicate an attack. See g_tls_connection_set_require_close_notify(). - + The TLS handshake failed because the client sent the fallback SCSV, indicating a protocol downgrade attack. Since: 2.60 @@ -77233,15 +78113,15 @@ If the user cancels an interaction, then the result should be #GTlsInteractionResult is returned by various functions in #GTlsInteraction when finishing an interaction request. - + The interaction was unhandled (i.e. not implemented). - + The interaction completed, and resulting data is available. - + The interaction has failed, or was cancelled. and the operation should be aborted. @@ -77283,14 +78163,16 @@ for @length in contexts where you know the password will have a certain fixed length.) The password value (owned by the password object). - + + + a #GTlsPassword object - + location to place the length of the password. @@ -77330,7 +78212,7 @@ considered part of the password in this case.) - + Get a description string about what the password will be used for. The description of the password. @@ -77343,7 +78225,7 @@ considered part of the password in this case.) - + Get flags about the password. The flags about the password. @@ -77364,20 +78246,22 @@ for @length in contexts where you know the password will have a certain fixed length.) The password value (owned by the password object). - + + + a #GTlsPassword object - + location to place the length of the password. - + Get a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags(). @@ -77392,7 +78276,7 @@ g_tls_password_get_flags(). - + Set a description string about what the password will be used for. @@ -77408,7 +78292,7 @@ g_tls_password_get_flags(). - + Set flags about the password. @@ -77486,7 +78370,7 @@ considered part of the password in this case.) - + Set a user readable translated warning. Usually this warning is a representation of the password flags returned from g_tls_password_get_flags(). @@ -77504,13 +78388,13 @@ g_tls_password_get_flags(). - + - + - + @@ -77529,14 +78413,16 @@ g_tls_password_get_flags(). The password value (owned by the password object). - + + + a #GTlsPassword object - + location to place the length of the password. @@ -77590,35 +78476,82 @@ g_tls_password_get_flags(). Various flags for the password. - + No flags - + The password was wrong, and the user should retry. - + Hint to the user that the password has been wrong many times, and the user may not have many chances left. - + Hint to the user that this is the last try to get this password right. + + For PKCS #11, the user PIN is required. + Since: 2.70. + + + For PKCS #11, the security officer + PIN is required. Since: 2.70. + + + For PKCS #11, the context-specific + PIN is required. Since: 2.70. + + + The TLS or DTLS protocol version used by a #GTlsConnection or +#GDtlsConnection. The integer values of these versions are sequential +to ensure newer known protocol versions compare greater than older +known versions. Any known DTLS protocol version will compare greater +than any SSL or TLS protocol version. The protocol version may be +%G_TLS_PROTOCOL_VERSION_UNKNOWN if the TLS backend supports a newer +protocol version that GLib does not yet know about. This means that +it's possible for an unknown DTLS protocol version to compare less +than the TLS protocol versions. + + No protocol version or unknown protocol version + + + SSL 3.0, which is insecure and should not be used + + + TLS 1.0, which is insecure and should not be used + + + TLS 1.1, which is insecure and should not be used + + + TLS 1.2, defined by [RFC 5246](https://datatracker.ietf.org/doc/html/rfc5246) + + + TLS 1.3, defined by [RFC 8446](https://datatracker.ietf.org/doc/html/rfc8446) + + + DTLS 1.0, which is insecure and should not be used + + + DTLS 1.2, defined by [RFC 6347](https://datatracker.ietf.org/doc/html/rfc6347) + + When to allow rehandshaking. See g_tls_connection_set_rehandshake_mode(). Changing the rehandshake mode is no longer required for compatibility. Also, rehandshaking has been removed from the TLS protocol in TLS 1.3. - + Never allow rehandshaking - + Allow safe rehandshaking only - + Allow unsafe rehandshaking @@ -78080,7 +79013,7 @@ g_socket_get_credentials(). - + Gets the credentials stored in @message. A #GCredentials instance. Do not free, it is owned by @message. @@ -78093,7 +79026,7 @@ g_socket_get_credentials(). - + The credentials stored in the message. @@ -78418,7 +79351,7 @@ system-wide file descriptor limit. - + Gets the #GUnixFDList contained in @message. This function does not return a reference to the caller, but the returned list is valid for the lifetime of @message. @@ -78470,7 +79403,7 @@ descriptors contained in @message, an empty array is returned. - + @@ -78532,7 +79465,7 @@ when the stream is closed. - + Returns whether the file descriptor of @stream will be closed when the stream is closed. @@ -78546,7 +79479,7 @@ closed when the stream is closed. - + Return the UNIX file descriptor that the stream reads from. The file descriptor of @stream @@ -78559,7 +79492,7 @@ closed when the stream is closed. - + Sets whether the file descriptor of @stream shall be closed when the stream is closed. @@ -78576,11 +79509,11 @@ when the stream is closed. - + Whether to close the file descriptor when the stream is closed. - + The file descriptor that the stream reads from. @@ -78949,7 +79882,7 @@ the output stream is destroyed. - + Returns whether the file descriptor of @stream will be closed when the stream is closed. @@ -78963,7 +79896,7 @@ closed when the stream is closed. - + Return the UNIX file descriptor that the stream writes to. The file descriptor of @stream @@ -78976,7 +79909,7 @@ closed when the stream is closed. - + Sets whether the file descriptor of @stream shall be closed when the stream is closed. @@ -78993,11 +79926,11 @@ when the stream is closed. - + Whether to close the file descriptor when the stream is closed. - + The file descriptor that the stream writes to. @@ -79162,7 +80095,7 @@ its listening socket. - + Gets @address's type. a #GUnixSocketAddressType @@ -79189,7 +80122,7 @@ its listening socket. - + Gets @address's path, or for abstract sockets the "name". Guaranteed to be zero-terminated, but an abstract socket @@ -79229,10 +80162,10 @@ distinguishes between zero-padded and non-zero-padded abstract addresses. - + - + @@ -79267,19 +80200,19 @@ zeroes; this corresponds to %G_UNIX_SOCKET_ADDRESS_ABSTRACT_PADDED. However, many programs instead just use a portion of %sun_path, and pass an appropriate smaller length to bind() or connect(). This is %G_UNIX_SOCKET_ADDRESS_ABSTRACT. - + invalid - + anonymous - + a filesystem path - + an abstract name - + an abstract name, 0-padded to the full length of a unix socket name @@ -82209,7 +83142,8 @@ GIO was used to unmount. - Zlib decompression + #GZlibCompressor is an implementation of #GConverter that +compresses data using zlib. Creates a new #GZlibCompressor. @@ -82228,7 +83162,7 @@ GIO was used to unmount. - + Returns the #GZlibCompressor:file-info property. a #GFileInfo, or %NULL @@ -82241,7 +83175,7 @@ GIO was used to unmount. - + Sets @file_info in @compressor. If non-%NULL, and @compressor's #GZlibCompressor:format property is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, it will be used to set the file name and modification time in @@ -82264,7 +83198,7 @@ or after resetting it with g_converter_reset(). - + If set to a non-%NULL #GFileInfo object, and #GZlibCompressor:format is %G_ZLIB_COMPRESSOR_FORMAT_GZIP, the compressor will write the file name and modification time from the file info to the GZIP header. @@ -82285,18 +83219,19 @@ and modification time from the file info to the GZIP header. Used to select the type of data format to use for #GZlibDecompressor and #GZlibCompressor. - + deflate compression with zlib header - + gzip file format - + deflate compression with no header - Zlib decompression + #GZlibDecompressor is an implementation of #GConverter that +decompresses data compressed with zlib. Creates a new #GZlibDecompressor. @@ -82311,7 +83246,7 @@ and #GZlibCompressor. - + Retrieves the #GFileInfo constructed from the GZIP header data of compressed data processed by @compressor, or %NULL if @decompressor's #GZlibDecompressor:format property is not %G_ZLIB_COMPRESSOR_FORMAT_GZIP, @@ -82328,7 +83263,7 @@ data stream at all. - + A #GFileInfo containing the information found in the GZIP header of the data stream processed, or %NULL if the header was not yet fully processed, is not present at all, or the compressor's @@ -83843,12 +84778,61 @@ This is typically used when presenting errors to the end user. + + This is a language binding friendly version of g_dbus_escape_object_path_bytestring(). + + an escaped version of @s. Free with g_free(). + + + + + the string to escape + + + + + + Escapes @bytes for use in a D-Bus object path component. +@bytes is an array of zero or more nonzero bytes in an +unspecified encoding, followed by a single zero byte. + +The escaping method consists of replacing all non-alphanumeric +characters (see g_ascii_isalnum()) with their hexadecimal value +preceded by an underscore (`_`). For example: +`foo.bar.baz` will become `foo_2ebar_2ebaz`. + +This method is appropriate to use when the input is nearly +a valid object path component but is not when your input +is far from being a valid object path component. +Other escaping algorithms are also valid to use with +D-Bus object paths. + +This can be reversed with g_dbus_unescape_object_path(). + + an escaped version of @bytes. Free with g_free(). + + + + + the string of bytes to escape + + + + + + Generate a D-Bus GUID that can be used with e.g. g_dbus_connection_new(). -See the D-Bus specification regarding what strings are valid D-Bus -GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). +See the +[D-Bus specification](https://dbus.freedesktop.org/doc/dbus-specification.html#uuids) +regarding what strings are valid D-Bus GUIDs. The specification refers to +these as ‘UUIDs’ whereas GLib (for historical reasons) refers to them as +‘GUIDs’. The terms are interchangeable. + +Note that D-Bus GUIDs do not follow +[RFC 4122](https://datatracker.ietf.org/doc/html/rfc4122). A valid D-Bus GUID. Free with g_free(). @@ -83944,13 +84928,30 @@ checks. + + Check whether @string is a valid D-Bus error name. + +This function returns the same result as g_dbus_is_interface_name(), +because D-Bus error names are defined to have exactly the +same syntax as interface names. + + %TRUE if valid, %FALSE otherwise. + + + + + The string to check. + + + + Checks if @string is a D-Bus GUID. -See the D-Bus specification regarding what strings are valid D-Bus -GUID (for example, D-Bus GUIDs are not RFC-4122 compliant). +See the documentation for g_dbus_generate_guid() for more information about +the format of a GUID. - %TRUE if @string is a guid, %FALSE otherwise. + %TRUE if @string is a GUID, %FALSE otherwise. @@ -84029,6 +85030,30 @@ supported by this library, %FALSE if @error is set. + + Unescapes an string that was previously escaped with +g_dbus_escape_object_path(). If the string is in a format that could +not have been returned by g_dbus_escape_object_path(), this function +returns %NULL. + +Encoding alphanumeric characters which do not need to be +encoded is not allowed (e.g `_63` is not valid, the string +should contain `c` instead). + + an + unescaped version of @s, or %NULL if @s is not a string returned + from g_dbus_escape_object_path(). Free with g_free(). + + + + + + + the string to unescape + + + + Creates a new #GDtlsClientConnection wrapping @base_socket which is assumed to communicate with the server identified by @server_identity. @@ -84361,13 +85386,13 @@ The format of D-Bus introspection XML is specified in the Convenience API for owning bus names. A simple example for owning a name can be found in -[gdbus-example-own-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-own-name.c) +[gdbus-example-own-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-own-name.c) Convenience API for watching bus names. A simple example for watching a name can be found in -[gdbus-example-watch-name.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-example-watch-name.c) +[gdbus-example-watch-name.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-example-watch-name.c) Various utility routines related to D-Bus. @@ -84600,14 +85625,6 @@ Key and value names are not case sensitive. Full key name (excluding the pre-defined ancestor's name) can't exceed 255 UTF-16 characters, give or take. Value name can't exceed 16383 UTF-16 characters. Tree depth is limited to 512 levels. - - - #GZlibCompressor is an implementation of #GConverter that -compresses data using zlib. - - - #GZlibDecompressor is an implementation of #GConverter that -decompresses data compressed with zlib. Deserializes a #GIcon previously serialized using g_icon_serialize(). @@ -85215,6 +86232,13 @@ need to be a #GPollableOutputStream. + + Gets a reference to the default #GPowerProfileMonitor for the system. + + a new reference to the default #GPowerProfileMonitor + + + Find the `gio-proxy` extension point for a proxy implementation that supports the specified protocol. @@ -85684,8 +86708,10 @@ is set, it will be filled with a unix timestamp for checking if the mounts have changed since with g_unix_mounts_changed_since(). If more mounts have the same mount path, the last matching mount -is returned. - +is returned. + +This will return %NULL if there is no mount point at @mount_path. + a #GUnixMountEntry. @@ -85737,8 +86763,11 @@ is set, it will be filled with a unix timestamp for checking if the mounts have changed since with g_unix_mounts_changed_since(). If more mounts have the same mount path, the last matching mount -is returned. - +is returned. + +This will return %NULL if looking up the mount entry fails, if +@file_path doesn’t exist or there is an I/O error. + a #GUnixMountEntry. diff --git a/Graphene-1.0.gir b/Graphene-1.0.gir index 204cd23..618c08c 100644 --- a/Graphene-1.0.gir +++ b/Graphene-1.0.gir @@ -7,6 +7,14 @@ and/or use gtk-doc annotations. --> + + + + + + + + A 3D box, described as the volume between a minimum and a maximum vertices. @@ -1310,15 +1318,6 @@ a #graphene_frustum_t. - - - - - - - - - A structure capable of holding a 4x4 matrix. @@ -5412,9 +5411,6 @@ a size of 0, 0. - - - Initializes a #graphene_size_t with the given sizes when declaring it, e.g.: diff --git a/Gtk-3.0.gir b/Gtk-3.0.gir index 51c736f..3de9ca9 100644 --- a/Gtk-3.0.gir +++ b/Gtk-3.0.gir @@ -9104,7 +9104,7 @@ container that has been allocated. - + Like gtk_get_binary_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -20571,11 +20571,7 @@ The #GtkCellRendererAccel cell renderer was added in GTK+ 2.10. Determines if the edited accelerators are GTK+ accelerators. If they are, consumed modifiers are suppressed, only accelerators accepted by GTK+ are allowed, and the accelerators are rendered -in the same way as they are in menus. - -If the mode is set to %GTK_CELL_RENDERER_ACCEL_MODE_MODIFIER_TAP -then bare modifiers can be set as accelerators by tapping (ie: -pressing and immediately releasing) them. +in the same way as they are in menus. @@ -20719,10 +20715,7 @@ in the same way as they are in menus. GTK+ accelerators mode - Other accelerator mode -GTK_CELL_RENDERER_ACCEL_MODE_MODIFIER_TAP: Bare modifiers mode - - + Other accelerator mode @@ -35717,7 +35710,9 @@ This will also clear any previously set labels. Sets whether the label widget should fill all available -horizontal space allocated to @expander. +horizontal space allocated to @expander. + +Note that this function has no effect since 3.20. @@ -35827,6 +35822,9 @@ the next character should be used for the mnemonic accelerator key. + Whether the label widget should fill all available horizontal space. + +Note that this property is ignored since 3.20. @@ -35988,6 +35986,24 @@ expander is expanded. + + + + + + + + + + + + + + + + + + @@ -36272,7 +36288,7 @@ Please see the GLib documentation for more details about this variable. This means that while you can pass the result of -gtk_file_chooser_get_filename() to open() or fopen(), +gtk_file_chooser_get_filename() to g_open() or g_fopen(), you may not be able to directly set it as the text of a #GtkLabel widget unless you convert it first to UTF-8, which all GTK+ widgets expect. You should use g_filename_to_utf8() @@ -38859,6 +38875,22 @@ The default binding for this signal is `Alt + Up`. + + + + + + + + + + + + + + + + The parent class. @@ -41393,18 +41425,18 @@ The @text is used to show how the selected font looks. The font description as a #PangoFontDescription. - + The selected font features, in a format that is compatible with CSS and with Pango attributes. - + The language for which the #GtkFontChooser:font-features were selected, in a format that is compatible with CSS and with Pango attributes. - + The level of granularity to offer for selecting fonts. @@ -45544,10 +45576,8 @@ to #GtkGrid. For more information about migrating to #GtkGrid, see Creates a new #GtkHBox. - You can use gtk_box_new() with %GTK_ORIENTATION_HORIZONTAL instead, - which is a quick and easy change. But the recommendation is to switch to - #GtkGrid, since #GtkBox is going to go away eventually. - See [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. + You should use gtk_box_new() with a %GTK_ORIENTATION_HORIZONTAL + #GtkOrientable:orientation instead a new #GtkHBox. @@ -48039,6 +48069,8 @@ following files that is found: ~/.config/gtk-3.0/Compose, ~/.XCompose, Compose file). The syntax of these files is described in the Compose(5) manual page. +## Unicode characters + GtkIMContextSimple also supports numeric entry of Unicode characters by typing Ctrl-Shift-u, followed by a hexadecimal Unicode codepoint. For example, Ctrl-Shift-u 1 2 3 Enter yields U+0123 LATIN SMALL LETTER @@ -48051,14 +48083,17 @@ G WITH CEDILLA, i.e. ģ. + Adds an additional table from the X11 compose file. + A #GtkIMContextSimple + The path of compose file @@ -48088,8 +48123,7 @@ the length of the sequence should be zero.) - Maximum length of a sequence in the table - (cannot be greater than #GTK_MAX_COMPOSE_LEN) + Maximum length of a sequence in the table @@ -48317,7 +48351,7 @@ replaced by the slave corresponding to the new context id. signal in case of conversion failure. - + Like gtk_get_interface_age(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -49265,6 +49299,18 @@ against at application run time. + + + + + + + + + + + + @@ -50333,6 +50379,18 @@ against at application run time. + + + + + + + + + + + + @@ -50879,6 +50937,18 @@ against at application run time. + + + + + + + + + + + + @@ -60670,7 +60740,7 @@ private data. A GtkListBox is a vertical container that contains GtkListBoxRow -children. These rows can by dynamically sorted and filtered, and +children. These rows can be dynamically sorted and filtered, and headers can be added dynamically depending on the row content. It also allows keyboard and mouse navigation and selection like a typical list. @@ -63012,7 +63082,7 @@ against at application run time. - + Like gtk_get_micro_version(), but from the headers used at application compile time, rather than from the library linked against at application run time. @@ -67560,7 +67630,7 @@ Note that even though the recursive main loop gives the effect of a modal dialog (it prevents the user from interacting with other windows in the same window group while the dialog is run), callbacks such as timeouts, IO channel watches, DND drops, etc, will -be triggered during a gtk_nautilus_dialog_run() call. +be triggered during a gtk_native_dialog_run() call. response ID @@ -70288,6 +70358,24 @@ to its contents. + + + + + + + + + + + + + + + + + + @@ -73401,6 +73489,32 @@ instance with gtk_socket_add_id(). + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -84335,6 +84449,24 @@ when the child of a #GtkRevealer widget is shown or hidden. + + + + + + + + + + + + + + + + + + @@ -90782,6 +90914,34 @@ want to reuse it you must add a signal handler that returns %TRUE. + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -121780,9 +121940,6 @@ in #GtkComboBox or #GtkEntryCompletion. - - - @@ -124692,10 +124849,8 @@ to #GtkGrid. For more information about migrating to #GtkGrid, see Creates a new #GtkVBox. - You can use gtk_box_new() with %GTK_ORIENTATION_VERTICAL instead, - which is a quick and easy change. But the recommendation is to switch to - #GtkGrid, since #GtkBox is going to go away eventually. - See [Migrating from other containers to GtkGrid][gtk-migrating-GtkGrid]. + You should use gtk_box_new() with a %GTK_ORIENTATION_VERTICAL + #GtkOrientable:orientation instead a new #GtkVBox. @@ -141340,6 +141495,25 @@ but always returns %FALSE. + + The functions and objects described here make working with GTK+ and +GIO more convenient. + +#GtkMountOperation is needed when mounting volumes: +It is an implementation of #GMountOperation that can be used with +GIO functions for mounting volumes such as +g_file_mount_enclosing_volume(), g_file_mount_mountable(), +g_volume_mount(), g_mount_unmount_with_operation() and others. + +When necessary, #GtkMountOperation shows dialogs to ask for +passwords, questions or show processes blocking unmount. + +gtk_show_uri_on_window() is a convenient way to launch applications for URIs. + +Another object that is worth mentioning in this context is +#GdkAppLaunchContext, which provides visual feedback when lauching +applications. + Returns the binary age as passed to `libtool` when building the GTK+ library the process is running against. @@ -141541,6 +141715,940 @@ g_option_context_parse() to parse your commandline arguments. + + A button box should be used to provide a consistent layout of buttons +throughout your application. The layout/spacing can be altered by the +programmer, or if desired, by the user to alter the “feel” of a +program to a small degree. + +gtk_button_box_get_layout() and gtk_button_box_set_layout() retrieve and +alter the method used to spread the buttons in a button box across the +container, respectively. + +The main purpose of GtkButtonBox is to make sure the children have all the +same size. GtkButtonBox gives all children the same size, but it does allow +'outliers' to keep their own larger size. + +To exempt individual children from homogeneous sizing regardless of their +'outlier' status, you can set the non-homogeneous child +property. + +# CSS nodes + +GtkButtonBox uses a single CSS node with name buttonbox. + + + #GtkBindingSet provides a mechanism for configuring GTK+ key bindings +through CSS files. This eases key binding adjustments for application +developers as well as users and provides GTK+ users or administrators +with high key binding configurability which requires no application +or toolkit side changes. + +In order for bindings to work in a custom widget implementation, the +widget’s #GtkWidget:can-focus and #GtkWidget:has-focus properties +must both be true. For example, by calling gtk_widget_set_can_focus() +in the widget’s initialisation function; and by calling +gtk_widget_grab_focus() when the widget is clicked. + +# Installing a key binding + +A CSS file binding consists of a “binding-set” definition and a match +statement to apply the binding set to specific widget types. Details +on the matching mechanism are described under +[Selectors][gtkcssprovider-selectors] +in the #GtkCssProvider documentation. Inside the binding set +definition, key combinations are bound to one or more specific +signal emissions on the target widget. Key combinations are strings +consisting of an optional #GdkModifierType name and +[key names][gdk3-Keyboard-Handling] +such as those defined in `gdk/gdkkeysyms.h` +or returned from gdk_keyval_name(), they have to be parsable by +gtk_accelerator_parse(). Specifications of signal emissions consist +of a string identifying the signal name, and a list of signal specific +arguments in parenthesis. + +For example for binding Control and the left or right cursor keys +of a #GtkEntry widget to the #GtkEntry::move-cursor signal (so +movement occurs in 3-character steps), the following binding can be +used: + +|[ <!-- language="CSS" --> +@binding-set MoveCursor3 +{ + bind "<Control>Right" { "move-cursor" (visual-positions, 3, 0) }; + bind "<Control>Left" { "move-cursor" (visual-positions, -3, 0) }; +} + +entry +{ + -gtk-key-bindings: MoveCursor3; +} +]| + +# Unbinding existing key bindings + +GTK+ already defines a number of useful bindings for the widgets +it provides. Because custom bindings set up in CSS files take +precedence over the default bindings shipped with GTK+, overriding +existing bindings as demonstrated in +[Installing a key binding][gtk-bindings-install] +works as expected. The same mechanism can not be used to “unbind” +existing bindings, however. + +|[ <!-- language="CSS" --> +@binding-set MoveCursor3 +{ + bind "<Control>Right" { }; + bind "<Control>Left" { }; +} + +entry +{ + -gtk-key-bindings: MoveCursor3; +} +]| + +The above example will not have the desired effect of causing +“<Control>Right” and “<Control>Left” key presses to be ignored by GTK+. +Instead, it just causes any existing bindings from the bindings set +“MoveCursor3” to be deleted, so when “<Control>Right” or +“<Control>Left” are pressed, no binding for these keys is found in +binding set “MoveCursor3”. GTK+ will thus continue to search for +matching key bindings, and will eventually lookup and find the default +GTK+ bindings for entries which implement word movement. To keep GTK+ +from activating its default bindings, the “unbind” keyword can be used +like this: + +|[ <!-- language="CSS" --> +@binding-set MoveCursor3 +{ + unbind "<Control>Right"; + unbind "<Control>Left"; +} + +entry +{ + -gtk-key-bindings: MoveCursor3; +} +]| + +Now, GTK+ will find a match when looking up “<Control>Right” and +“<Control>Left” key presses before it resorts to its default bindings, +and the match instructs it to abort (“unbind”) the search, so the key +presses are not consumed by this widget. As usual, further processing +of the key presses, e.g. by an entry’s parent widget, is now possible. + + + The #GtkColorSelection is a widget that is used to select +a color. It consists of a color wheel and number of sliders +and entry boxes for color parameters such as hue, saturation, +value, red, green, blue, and opacity. It is found on the standard +color selection dialog box #GtkColorSelectionDialog. + + + The #GtkColorSelectionDialog provides a standard dialog which +allows the user to select a color much like the #GtkFileChooserDialog +provides a standard dialog for file selection. + +Use gtk_color_selection_dialog_get_color_selection() to get the +#GtkColorSelection widget contained within the dialog. Use this widget +and its gtk_color_selection_get_current_color() +function to gain access to the selected color. Connect a handler +for this widget’s #GtkColorSelection::color-changed signal to be notified +when the color changes. + +# GtkColorSelectionDialog as GtkBuildable # {#GtkColorSelectionDialog-BUILDER-UI} + +The GtkColorSelectionDialog implementation of the GtkBuildable interface +exposes the embedded #GtkColorSelection as internal child with the +name “color_selection”. It also exposes the buttons with the names +“ok_button”, “cancel_button” and “help_button”. + + + GTK+ has a rich set of functions for doing inter-process communication +via the drag-and-drop metaphor. + +As well as the functions listed here, applications may need to use some +facilities provided for [Selections][gtk3-Selections]. Also, the Drag and +Drop API makes use of signals in the #GtkWidget class. + + + GTK+ provides version information, primarily useful in configure checks +for builds that have a configure script. Applications will not typically +use the features described here. + + + The #GtkFontSelection widget lists the available fonts, styles and sizes, +allowing the user to select a font. +It is used in the #GtkFontSelectionDialog widget to provide a dialog box for +selecting fonts. + +To set the font which is initially selected, use +gtk_font_selection_set_font_name(). + +To get the selected font use gtk_font_selection_get_font_name(). + +To change the text which is shown in the preview area, use +gtk_font_selection_set_preview_text(). + +In GTK+ 3.2, #GtkFontSelection has been deprecated in favor of +#GtkFontChooser. + + + The #GtkFontSelectionDialog widget is a dialog box for selecting a font. + +To set the font which is initially selected, use +gtk_font_selection_dialog_set_font_name(). + +To get the selected font use gtk_font_selection_dialog_get_font_name(). + +To change the text which is shown in the preview area, use +gtk_font_selection_dialog_set_preview_text(). + +In GTK+ 3.2, #GtkFontSelectionDialog has been deprecated in favor of +#GtkFontChooserDialog. + +# GtkFontSelectionDialog as GtkBuildable # {#GtkFontSelectionDialog-BUILDER-UI} + +The GtkFontSelectionDialog implementation of the GtkBuildable interface +exposes the embedded #GtkFontSelection as internal child with the +name “font_selection”. It also exposes the buttons with the names +“ok_button”, “cancel_button” and “apply_button”. + + + A button box should be used to provide a consistent layout of buttons +throughout your application. The layout/spacing can be altered by the +programmer, or if desired, by the user to alter the “feel” of a +program to a small degree. + +A #GtkHButtonBox is created with gtk_hbutton_box_new(). Buttons are +packed into a button box the same way widgets are added to any other +container, using gtk_container_add(). You can also use +gtk_box_pack_start() or gtk_box_pack_end(), but for button boxes both +these functions work just like gtk_container_add(), ie., they pack the +button in a way that depends on the current layout style and on +whether the button has had gtk_button_box_set_child_secondary() called +on it. + +The spacing between buttons can be set with gtk_box_set_spacing(). The +arrangement and layout of the buttons can be changed with +gtk_button_box_set_layout(). + +GtkHButtonBox has been deprecated, use #GtkButtonBox instead. + + + Before using GTK+, you need to initialize it; initialization connects to the +window system display, and parses some standard command line arguments. The +gtk_init() macro initializes GTK+. gtk_init() exits the application if errors +occur; to avoid this, use gtk_init_check(). gtk_init_check() allows you to +recover from a failed GTK+ initialization - you might start up your +application in text mode instead. + +Like all GUI toolkits, GTK+ uses an event-driven programming model. When the +user is doing nothing, GTK+ sits in the “main loop” and +waits for input. If the user performs some action - say, a mouse click - then +the main loop “wakes up” and delivers an event to GTK+. GTK+ forwards the +event to one or more widgets. + +When widgets receive an event, they frequently emit one or more +“signals”. Signals notify your program that "something +interesting happened" by invoking functions you’ve connected to the signal +with g_signal_connect(). Functions connected to a signal are often termed +“callbacks”. + +When your callbacks are invoked, you would typically take some action - for +example, when an Open button is clicked you might display a +#GtkFileChooserDialog. After a callback finishes, GTK+ will return to the +main loop and await more user input. + +## Typical main() function for a GTK+ application + +|[<!-- language="C" --> +int +main (int argc, char **argv) +{ + GtkWidget *mainwin; + // Initialize i18n support with bindtextdomain(), etc. + + // ... + + // Initialize the widget set + gtk_init (&argc, &argv); + + // Create the main window + mainwin = gtk_window_new (GTK_WINDOW_TOPLEVEL); + + // Set up our GUI elements + + // ... + + // Show the application window + gtk_widget_show_all (mainwin); + + // Enter the main event loop, and wait for user interaction + gtk_main (); + + // The user lost interest + return 0; +} +]| + +It’s OK to use the GLib main loop directly instead of gtk_main(), though it +involves slightly more typing. See #GMainLoop in the GLib documentation. + + + #GtkPlacesView is a stock widget that displays a list of persistent drives +such as harddisk partitions and networks. #GtkPlacesView does not monitor +removable devices. + +The places view displays drives and networks, and will automatically mount +them when the user activates. Network addresses are stored even if they fail +to connect. When the connection is successful, the connected network is +shown at the network list. + +To make use of the places view, an application at least needs to connect +to the #GtkPlacesView::open-location signal. This is emitted when the user +selects a location to open in the view. + + + GTK+ provides resource file mechanism for configuring +various aspects of the operation of a GTK+ program +at runtime. + +> In GTK+ 3.0, resource files have been deprecated and replaced by +> CSS-like style sheets, which are understood by #GtkCssProvider. + +# Default Files # + +An application can cause GTK+ to parse a specific RC +file by calling gtk_rc_parse(). In addition to this, +certain files will be read at the end of gtk_init(). +Unless modified, the files looked for will be +`SYSCONFDIR/gtk-2.0/gtkrc` +and `.gtkrc-3.0` in the users home directory. +(`SYSCONFDIR` defaults to +`/usr/local/etc`. It can be changed with the +`--prefix` or `--sysconfdir` options when +configuring GTK+.) + +The set of these “default” files +can be retrieved with gtk_rc_get_default_files() +and modified with gtk_rc_add_default_file() and +gtk_rc_set_default_files(). +Additionally, the `GTK2_RC_FILES` environment variable +can be set to a #G_SEARCHPATH_SEPARATOR_S-separated list of files +in order to overwrite the set of default files at runtime. + +# Locale Specific Files # {#locale-specific-rc} + +For each RC file, in addition to the file itself, GTK+ will look for +a locale-specific file that will be parsed after the main file. +For instance, if `LANG` is set to `ja_JP.ujis`, +when loading the default file `~/.gtkrc` then GTK+ looks +for `~/.gtkrc.ja_JP` and `~/.gtkrc.ja`, +and parses the first of those that exists. + +# Pathnames and Patterns # + +A resource file defines a number of styles and key bindings and +attaches them to particular widgets. The attachment is done +by the `widget`, `widget_class`, +and `class` declarations. As an example +of such a statement: + +|[ +widget "mywindow.*.GtkEntry" style "my-entry-class" +]| + +attaches the style `"my-entry-class"` to all +widgets whose “widget path” matches the +“pattern” `"mywindow.*.GtkEntry"`. +That is, all #GtkEntry widgets which are part of a #GtkWindow named +`"mywindow"`. + +The patterns here are given in the standard shell glob syntax. +The `"?"` wildcard matches any character, while +`"*"` matches zero or more of any character. +The three types of matching are against the widget path, the +“class path” and the class hierarchy. Both the +widget path and the class path consist of a `"."` +separated list of all the parents of the widget and the widget itself +from outermost to innermost. The difference is that in the widget path, +the name assigned by gtk_widget_set_name() is used if present, otherwise +the class name of the widget, while for the class path, the class name is +always used. + +Since GTK+ 2.10, `widget_class` paths can also contain <classname> +substrings, which are matching the class with the given name and any +derived classes. For instance, +|[ +widget_class "*<GtkMenuItem>.GtkLabel" style "my-style" +]| +will match #GtkLabel widgets which are contained in any kind of menu item. + +So, if you have a #GtkEntry named `"myentry"`, inside of a horizontal +box in a window named `"mywindow"`, then the widget path is: +`"mywindow.GtkHBox.myentry"` while the class path is: +`"GtkWindow.GtkHBox.GtkEntry"`. + +Matching against class is a little different. The pattern match is done +against all class names in the widgets class hierarchy (not the layout +hierarchy) in sequence, so the pattern: +|[ +class "GtkButton" style "my-style" +]| +will match not just #GtkButton widgets, but also #GtkToggleButton and +#GtkCheckButton widgets, since those classes derive from #GtkButton. + +Additionally, a priority can be specified for each pattern, and styles +override other styles first by priority, then by pattern type and then +by order of specification (later overrides earlier). The priorities +that can be specified are (highest to lowest): + +- `highest` + +- `rc` + +- `theme` + +- `application` + +- `gtk` + +- `lowest` + +`rc` is the default for styles +read from an RC file, `theme` +is the default for styles read from theme RC files, +`application` +should be used for styles an application sets +up, and `gtk` is used for styles +that GTK+ creates internally. + +# Theme gtkrc Files # + +Theme RC files are loaded first from under the `~/.themes/`, +then from the directory from gtk_rc_get_theme_dir(). The files looked at will +be `gtk-3.0/gtkrc`. + +When the application prefers dark themes +(see the #GtkSettings:gtk-application-prefer-dark-theme property for details), +`gtk-3.0/gtkrc-dark` will be loaded first, and if not present +`gtk-3.0/gtkrc` will be loaded. + +# Optimizing RC Style Matches # + +Everytime a widget is created and added to the layout hierarchy of a #GtkWindow +("anchored" to be exact), a list of matching RC styles out of all RC styles read +in so far is composed. +For this, every RC style is matched against the widgets class path, +the widgets name path and widgets inheritance hierarchy. +As a consequence, significant slowdown can be caused by utilization of many +RC styles and by using RC style patterns that are slow or complicated to match +against a given widget. +The following ordered list provides a number of advices (prioritized by +effectiveness) to reduce the performance overhead associated with RC style +matches: + +1. Move RC styles for specific applications into RC files dedicated to those + applications and parse application specific RC files only from + applications that are affected by them. + This reduces the overall amount of RC styles that have to be considered + for a match across a group of applications. + +2. Merge multiple styles which use the same matching rule, for instance: + |[ + style "Foo" { foo_content } + class "X" style "Foo" + style "Bar" { bar_content } + class "X" style "Bar" + ]| + is faster to match as: + |[ + style "FooBar" { foo_content bar_content } + class "X" style "FooBar" + ]| + +3. Use of wildcards should be avoided, this can reduce the individual RC style + match to a single integer comparison in most cases. + +4. To avoid complex recursive matching, specification of full class names + (for `class` matches) or full path names (for + `widget` and `widget_class` matches) + is to be preferred over shortened names + containing `"*"` or `"?"`. + +5. If at all necessary, wildcards should only be used at the tail or head + of a pattern. This reduces the match complexity to a string comparison + per RC style. + +6. When using wildcards, use of `"?"` should be preferred + over `"*"`. This can reduce the matching complexity from + O(n^2) to O(n). For example `"Gtk*Box"` can be turned into + `"Gtk?Box"` and will still match #GtkHBox and #GtkVBox. + +7. The use of `"*"` wildcards should be restricted as much + as possible, because matching `"A*B*C*RestString"` can + result in matching complexities of O(n^2) worst case. + +# Toplevel Declarations # + +An RC file is a text file which is composed of a sequence +of declarations. `“#”` characters delimit comments and +the portion of a line after a `“#”` is ignored when parsing +an RC file. + +The possible toplevel declarations are: + +* `binding name + { ... }` + + Declares a binding set. + +* `class pattern + [ style | binding ][ : priority ] + name` + + Specifies a style or binding set for a particular + branch of the inheritance hierarchy. + +* `include filename` + + Parses another file at this point. If + filename is not an absolute filename, + it is searched in the directories of the currently open RC files. + + GTK+ also tries to load a + [locale-specific variant][locale-specific-rc] of + the included file. + +* `module_path path` + + Sets a path (a list of directories separated + by colons) that will be searched for theme engines referenced in + RC files. + +* `pixmap_path path` + + Sets a path (a list of directories separated + by colons) that will be searched for pixmaps referenced in + RC files. + +* `im_module_file pathname` + + Sets the pathname for the IM modules file. Setting this from RC files + is deprecated; you should use the environment variable `GTK_IM_MODULE_FILE` + instead. + +* `style name [ = + parent ] { ... }` + + Declares a style. + +* `widget pattern + [ style | binding ][ : priority ] + name` + + Specifies a style or binding set for a particular + group of widgets by matching on the widget pathname. + +* `widget_class pattern + [ style | binding ][ : priority ] + name` + + Specifies a style or binding set for a particular + group of widgets by matching on the class pathname. + +* setting = value + + Specifies a value for a [setting][GtkSettings]. + Note that settings in RC files are overwritten by system-wide settings + (which are managed by an XSettings manager on X11). + +# Styles # + +A RC style is specified by a `style` +declaration in a RC file, and then bound to widgets +with a `widget`, `widget_class`, +or `class` declaration. All styles +applying to a particular widget are composited together +with `widget` declarations overriding +`widget_class` declarations which, in +turn, override `class` declarations. +Within each type of declaration, later declarations override +earlier ones. + +Within a `style` declaration, the possible +elements are: + +* `bg[state] = color` + + Sets the color used for the background of most widgets. + +* `fg[state] = color` + + Sets the color used for the foreground of most widgets. + +* `base[state] = color` + + Sets the color used for the background of widgets displaying + editable text. This color is used for the background + of, among others, #GtkTextView, #GtkEntry. + +* `text[state] = + color` + + Sets the color used for foreground of widgets using + `base` for the background color. + +* `xthickness = + number` + + Sets the xthickness, which is used for various horizontal padding + values in GTK+. + +* `ythickness = + number` + + Sets the ythickness, which is used for various vertical padding + values in GTK+. + +* `bg_pixmap[state] = + pixmap` + + Sets a background pixmap to be used in place of the `bg` color + (or for #GtkText, in place of the `base` color. The special + value `"<parent>"` may be used to indicate that the widget should + use the same background pixmap as its parent. The special value + `"<none>"` may be used to indicate no background pixmap. + +* `font = font` + + Starting with GTK+ 2.0, the “font” and “fontset” + declarations are ignored; use “font_name” declarations instead. + +* `fontset = font` + + Starting with GTK+ 2.0, the “font” and “fontset” + declarations are ignored; use “font_name” declarations instead. + +* `font_name = font` + + Sets the font for a widget. font must be + a Pango font name, e.g. “Sans Italic 10” . + For details about Pango font names, see + pango_font_description_from_string(). + +* `stock["stock-id"] = { icon source specifications }` + + Defines the icon for a stock item. + +* `color["color-name"] = color specification` + + Since 2.10, this element can be used to defines symbolic colors. See below for + the syntax of color specifications. + +* `engine "engine" { engine-specific +settings }` + + Defines the engine to be used when drawing with this style. + +* `class::property = value` + + Sets a [style property][style-properties] for a widget class. + +The colors and background pixmaps are specified as a function of the +state of the widget. The states are: + +* `NORMAL` + + A color used for a widget in its normal state. + +* `ACTIVE` + + A variant of the `NORMAL` color used when the + widget is in the %GTK_STATE_ACTIVE state, and also for + the trough of a ScrollBar, tabs of a NoteBook + other than the current tab and similar areas. + Frequently, this should be a darker variant + of the `NORMAL` color. + +* `PRELIGHT` + + A color used for widgets in the %GTK_STATE_PRELIGHT state. This + state is the used for Buttons and MenuItems + that have the mouse cursor over them, and for + their children. + +* `SELECTED` + + A color used to highlight data selected by the user. + for instance, the selected items in a list widget, and the + selection in an editable widget. + +* `INSENSITIVE` + + A color used for the background of widgets that have + been set insensitive with gtk_widget_set_sensitive(). + +## Color Format ## {#color-format} + +Colors can be specified as a string containing a color name (GTK+ knows +all names from the X color database `/usr/lib/X11/rgb.txt`), +in one of the hexadecimal forms `#rrrrggggbbbb`, +`#rrrgggbbb`, `#rrggbb`, +or `#rgb`, where `r`, +`g` and `b` are +hex digits, or they can be specified as a triplet +`{ r, g, +b}`, where `r`, +`g` and `b` are either integers in +the range 0-65535 or floats in the range 0.0-1.0. + +Since 2.10, colors can also be specified by refering to a symbolic color, as +follows: `@color-name`, or by using expressions to combine +colors. The following expressions are currently supported: + +* mix (factor, color1, color2) + + Computes a new color by mixing color1 and + color2. The factor + determines how close the new color is to color1. + A factor of 1.0 gives pure color1, a factor of + 0.0 gives pure color2. + +* shade (factor, color) + + Computes a lighter or darker variant of color. + A factor of 1.0 leaves the color unchanged, smaller + factors yield darker colors, larger factors yield lighter colors. + +* lighter (color) + + This is an abbreviation for + `shade (1.3, color)`. + +* darker (color) + + This is an abbreviation for + `shade (0.7, color)`. + +Here are some examples of color expressions: + +|[ + mix (0.5, "red", "blue") + shade (1.5, mix (0.3, "#0abbc0", { 0.3, 0.5, 0.9 })) + lighter (@foreground) +]| + +In a `stock` definition, icon sources are specified as a +4-tuple of image filename or icon name, text direction, widget state, and size, in that +order. Each icon source specifies an image filename or icon name to use with a given +direction, state, and size. Filenames are specified as a string such +as `"itemltr.png"`, while icon names (looked up +in the current icon theme), are specified with a leading +`@`, such as `@"item-ltr"`. +The `*` character can be used as a +wildcard, and if direction/state/size are omitted they default to +`*`. So for example, the following specifies different icons to +use for left-to-right and right-to-left languages: + +|[<!-- language="C" --> +stock["my-stock-item"] = +{ + { "itemltr.png", LTR, *, * }, + { "itemrtl.png", RTL, *, * } +} +]| + +This could be abbreviated as follows: + +|[<!-- language="C" --> +stock["my-stock-item"] = +{ + { "itemltr.png", LTR }, + { "itemrtl.png", RTL } +} +]| + +You can specify custom icons for specific sizes, as follows: + +|[<!-- language="C" --> +stock["my-stock-item"] = +{ + { "itemmenusize.png", *, *, "gtk-menu" }, + { "itemtoolbarsize.png", *, *, "gtk-large-toolbar" } + { "itemgeneric.png" } // implicit *, *, * as a fallback +} +]| + +The sizes that come with GTK+ itself are `"gtk-menu"`, +`"gtk-small-toolbar"`, `"gtk-large-toolbar"`, +`"gtk-button"`, `"gtk-dialog"`. Applications +can define other sizes. + +It’s also possible to use custom icons for a given state, for example: + +|[<!-- language="C" --> +stock["my-stock-item"] = +{ + { "itemprelight.png", *, PRELIGHT }, + { "iteminsensitive.png", *, INSENSITIVE }, + { "itemgeneric.png" } // implicit *, *, * as a fallback +} +]| + +When selecting an icon source to use, GTK+ will consider text direction most +important, state second, and size third. It will select the best match based on +those criteria. If an attribute matches exactly (e.g. you specified +`PRELIGHT` or specified the size), GTK+ won’t modify the image; +if the attribute matches with a wildcard, GTK+ will scale or modify the image to +match the state and size the user requested. + +# Key bindings # + +Key bindings allow the user to specify actions to be +taken on particular key presses. The form of a binding +set declaration is: + +|[ +binding name { + bind key { + signalname (param, ...) + ... + } + ... +} +]| + +`key` is a string consisting of a series of modifiers followed by +the name of a key. The modifiers can be: + +- `<alt>` + +- `<ctl>` + +- `<control>` + +- `<meta>` + +- `<hyper>` + +- `<super>` + +- `<mod1>` + +- `<mod2>` + +- `<mod3>` + +- `<mod4>` + +- `<mod5>` + +- `<release>` + +- `<shft>` + +- `<shift>` + +`<shft>` is an alias for `<shift>`, `<ctl>` is an alias for +`<control>`, and `<alt>` is an alias for `<mod1>`. + +The action that is bound to the key is a sequence of signal names +(strings) followed by parameters for each signal. The signals must +be action signals. (See g_signal_new()). Each parameter can be a +float, integer, string, or unquoted string representing an enumeration +value. The types of the parameters specified must match the types of +the parameters of the signal. + +Binding sets are connected to widgets in the same manner as styles, +with one difference: Binding sets override other binding sets first +by pattern type, then by priority and then by order of specification. +The priorities that can be specified and their default values are the +same as for styles. + + + The selection mechanism provides the basis for different types +of communication between processes. In particular, drag and drop and +#GtkClipboard work via selections. You will very seldom or +never need to use most of the functions in this section directly; +#GtkClipboard provides a nicer interface to the same functionality. + +If an application is expected to exchange image data and work +on Windows, it is highly advised to support at least "image/bmp" target +for the widest possible compatibility with third-party applications. +#GtkClipboard already does that by using gtk_target_list_add_image_targets() +and gtk_selection_data_set_pixbuf() or gtk_selection_data_get_pixbuf(), +which is one of the reasons why it is advised to use #GtkClipboard. + +Some of the datatypes defined this section are used in +the #GtkClipboard and drag-and-drop API’s as well. The +#GtkTargetEntry and #GtkTargetList objects represent +lists of data types that are supported when sending or +receiving data. The #GtkSelectionData object is used to +store a chunk of data along with the data type and other +associated information. + + + > Since GTK+ 3.10, stock items are deprecated. You should instead set +> up whatever labels and/or icons you need using normal widget API, +> rather than relying on GTK+ providing ready-made combinations of these. + +Stock items represent commonly-used menu or toolbar items such as +“Open” or “Exit”. Each stock item is identified by a stock ID; +stock IDs are just strings, but macros such as #GTK_STOCK_OPEN are +provided to avoid typing mistakes in the strings. +Applications can register their own stock items in addition to those +built-in to GTK+. + +Each stock ID can be associated with a #GtkStockItem, which contains +the user-visible label, keyboard accelerator, and translation domain +of the menu or toolbar item; and/or with an icon stored in a +#GtkIconFactory. The connection between a +#GtkStockItem and stock icons is purely conventional (by virtue of +using the same stock ID); it’s possible to register a stock item but +no icon, and vice versa. Stock icons may have a RTL variant which gets +used for right-to-left locales. + + + GTK+ supports Drag-and-Drop in tree views with a high-level and a low-level +API. + +The low-level API consists of the GTK+ DND API, augmented by some treeview +utility functions: gtk_tree_view_set_drag_dest_row(), +gtk_tree_view_get_drag_dest_row(), gtk_tree_view_get_dest_row_at_pos(), +gtk_tree_view_create_row_drag_icon(), gtk_tree_set_row_drag_data() and +gtk_tree_get_row_drag_data(). This API leaves a lot of flexibility, but +nothing is done automatically, and implementing advanced features like +hover-to-open-rows or autoscrolling on top of this API is a lot of work. + +On the other hand, if you write to the high-level API, then all the +bookkeeping of rows is done for you, as well as things like hover-to-open +and auto-scroll, but your models have to implement the +#GtkTreeDragSource and #GtkTreeDragDest interfaces. + + + A button box should be used to provide a consistent layout of buttons +throughout your application. The layout/spacing can be altered by the +programmer, or if desired, by the user to alter the “feel” of a +program to a small degree. + +A #GtkVButtonBox is created with gtk_vbutton_box_new(). Buttons are +packed into a button box the same way widgets are added to any other +container, using gtk_container_add(). You can also use +gtk_box_pack_start() or gtk_box_pack_end(), but for button boxes both +these functions work just like gtk_container_add(), ie., they pack the +button in a way that depends on the current layout style and on +whether the button has had gtk_button_box_set_child_secondary() called +on it. + +The spacing between buttons can be set with gtk_box_set_spacing(). The +arrangement and layout of the buttons can be changed with +gtk_button_box_set_layout(). + +GtkVButtonBox has been deprecated, use #GtkButtonBox instead. + Looks up the icon size associated with @name. Use #GtkIconTheme instead. @@ -144566,7 +145674,7 @@ reused for future invocations of this function. - + A convenience function for launching the default application to show the uri. Like gtk_show_uri_on_window(), but takes a screen as transient parent instead of a window. @@ -144574,6 +145682,7 @@ as transient parent instead of a window. Note that this function is deprecated as it does not pass the necessary information for helpers to parent their dialog properly, when run from sandboxed applications for example. + Use gtk_show_uri_on_window() instead. %TRUE on success, %FALSE on error diff --git a/HarfBuzz-0.0.gir b/HarfBuzz-0.0.gir index 1932599..b22f42a 100644 --- a/HarfBuzz-0.0.gir +++ b/HarfBuzz-0.0.gir @@ -8,46 +8,89 @@ and/or use gtk-doc annotations. --> + Data type for booleans. + Data type for holding Unicode codepoints. Also +used to hold glyph IDs. - Data type for holding color values. + Data type for holding color values. Colors are eight bits per +channel RGB plus alpha transparency. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the extents for a font, in horizontal-direction +text segments. Extents must be returned in an #hb_glyph_extents output +parameter. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the extents for a font, in vertical-direction +text segments. Extents must be returned in an #hb_glyph_extents output +parameter. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the advance for a specified glyph, in +horizontal-direction text segments. Advances must be returned in +an #hb_position_t output parameter. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the advances for a sequence of glyphs, in +horizontal-direction text segments. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the (X,Y) coordinates (in font units) of the +origin for a glyph, in horizontal-direction text segments. Each +coordinate must be returned in an #hb_position_t output parameter. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the advance for a specified glyph, in +vertical-direction text segments. Advances must be returned in +an #hb_position_t output parameter. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the advances for a sequence of glyphs, in +vertical-direction text segments. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the (X,Y) coordinates (in font units) of the +origin for a glyph, in vertical-direction text segments. Each coordinate +must be returned in an #hb_position_t output parameter. + Data type for bitmasks. @@ -57,12 +100,17 @@ API. These can be used to fetch name strings from a font face. + Data type for holding a single coordinate value. +Contour points and other multi-dimensional data are +stored as tuples of #hb_position_t's. + Used when getting or setting AAT feature selectors. Indicates that +there is no selector index corresponding to the selector of interest. @@ -89,45 +137,62 @@ Set to U+FFFD REPLACEMENT CHARACTER. + Tests whether a text direction moves backward (from right to left, or from +bottom to top). Requires that the direction be valid. + #hb_direction_t to test + Tests whether a text direction moves forward (from left to right, or from +top to bottom). Requires that the direction be valid. + #hb_direction_t to test + Tests whether a text direction is horizontal. Requires +that the direction be valid. + #hb_direction_t to test + Tests whether a text direction is valid. + #hb_direction_t to test + Tests whether a text direction is vertical. Requires +that the direction be valid. + #hb_direction_t to test + Reverses a text direction. Requires that the direction +be valid. + #hb_direction_t to reverse - + @@ -158,6 +223,7 @@ Set to U+FFFD REPLACEMENT CHARACTER. + Constructs an #hb_tag_t from four characters. @@ -177,6 +243,7 @@ Set to U+FFFD REPLACEMENT CHARACTER. + Extracts the characters from an #hb_tag_t. @@ -195,521 +262,775 @@ Set to U+FFFD REPLACEMENT CHARACTER. - + - + + The selectors defined for specifying AAT feature settings. + Initial, unset feature selector + for #HB_AAT_LAYOUT_FEATURE_TYPE_ALL_TYPOGRAPHIC + for #HB_AAT_LAYOUT_FEATURE_TYPE_ALL_TYPOGRAPHIC + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LIGATURES + Deprecated + Deprecated + Deprecated + Deprecated + Deprecated + Deprecated + for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_SUBSTITUTION + for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_SUBSTITUTION + for #HB_AAT_LAYOUT_FEATURE_TYPE_LINGUISTIC_REARRANGEMENT + for #HB_AAT_LAYOUT_FEATURE_TYPE_LINGUISTIC_REARRANGEMENT + for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_SMART_SWASH_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_DIACRITICS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_DIACRITICS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_DIACRITICS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION + for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION + for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION + for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION + for #HB_AAT_LAYOUT_FEATURE_TYPE_VERTICAL_POSITION + for #HB_AAT_LAYOUT_FEATURE_TYPE_FRACTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_FRACTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_FRACTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_OVERLAPPING_CHARACTERS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_OVERLAPPING_CHARACTERS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_TYPOGRAPHIC_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_MATHEMATICAL_EXTRAS + for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ORNAMENT_SETS_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_DESIGN_COMPLEXITY_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLE_OPTIONS + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CHARACTER_SHAPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_CASE + for #HB_AAT_LAYOUT_FEATURE_TYPE_NUMBER_CASE + for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_TEXT_SPACING + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_TRANSLITERATION + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_ANNOTATION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_KANA_SPACING_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_KANA_SPACING_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_SPACING_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_SPACING_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_SPACING_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UNICODE_DECOMPOSITION_TYPE + Deprecated; use #HB_AAT_LAYOUT_FEATURE_SELECTOR_RUBY_KANA_OFF instead + Deprecated; use #HB_AAT_LAYOUT_FEATURE_SELECTOR_RUBY_KANA_ON instead + for #HB_AAT_LAYOUT_FEATURE_TYPE_RUBY_KANA + for #HB_AAT_LAYOUT_FEATURE_TYPE_RUBY_KANA + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_SYMBOL_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_IDEOGRAPHIC_ALTERNATIVES_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_VERTICAL_ROMAN_PLACEMENT_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_VERTICAL_ROMAN_PLACEMENT_TYPE + Deprecated; use #HB_AAT_LAYOUT_FEATURE_SELECTOR_CJK_ITALIC_ROMAN_OFF instead + Deprecated; use #HB_AAT_LAYOUT_FEATURE_SELECTOR_CJK_ITALIC_ROMAN_ON instead + for #HB_AAT_LAYOUT_FEATURE_TYPE_ITALIC_CJK_ROMAN + for #HB_AAT_LAYOUT_FEATURE_TYPE_ITALIC_CJK_ROMAN + for #HB_AAT_LAYOUT_FEATURE_TYPE_CASE_SENSITIVE_LAYOUT + for #HB_AAT_LAYOUT_FEATURE_TYPE_CASE_SENSITIVE_LAYOUT + for #HB_AAT_LAYOUT_FEATURE_TYPE_CASE_SENSITIVE_LAYOUT + for #HB_AAT_LAYOUT_FEATURE_TYPE_CASE_SENSITIVE_LAYOUT + for #HB_AAT_LAYOUT_FEATURE_TYPE_ALTERNATE_KANA + for #HB_AAT_LAYOUT_FEATURE_TYPE_ALTERNATE_KANA + for #HB_AAT_LAYOUT_FEATURE_TYPE_ALTERNATE_KANA + for #HB_AAT_LAYOUT_FEATURE_TYPE_ALTERNATE_KANA + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_STYLISTIC_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_CONTEXTUAL_ALTERNATIVES + for #HB_AAT_LAYOUT_FEATURE_TYPE_LOWER_CASE + for #HB_AAT_LAYOUT_FEATURE_TYPE_LOWER_CASE + for #HB_AAT_LAYOUT_FEATURE_TYPE_LOWER_CASE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UPPER_CASE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UPPER_CASE + for #HB_AAT_LAYOUT_FEATURE_TYPE_UPPER_CASE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_ROMAN_SPACING_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_ROMAN_SPACING_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_ROMAN_SPACING_TYPE + for #HB_AAT_LAYOUT_FEATURE_TYPE_CJK_ROMAN_SPACING_TYPE + The possible feature types defined for AAT shaping. + Initial, unset feature type @@ -793,7 +1114,7 @@ Set to U+FFFD REPLACEMENT CHARACTER. Makes a writable copy of @blob. - New blob, or nullptr if allocation failed. + The new blob, or nullptr if allocation failed @@ -835,13 +1156,15 @@ zero. Destroy with hb_blob_destroy(). + Creates a new blob containing the data from the +specified binary font file. - A hb_blob_t pointer with the content of the file + An #hb_blob_t pointer with the content of the file - font filename. + A font filename @@ -892,7 +1215,9 @@ See TODO:link object types for more information. + Fetches the data from a blob. + the byte data of @blob. @@ -903,6 +1228,7 @@ See TODO:link object types for more information. + The length in bytes of the data retrieved @@ -936,13 +1262,14 @@ or %NULL if failed. See TODO:link object types for more information. - the empty blob. + The empty blob. + Fetches the length of a blob's data. - the length of blob data in bytes. + the length of @blob data in bytes. @@ -953,23 +1280,27 @@ See TODO:link object types for more information. + Fetches the user data associated with the specified key, +attached to the specified font-functions structure. + A pointer to the user data - a blob. + a blob - key for data to get. + The user-data key to query + Tests whether a blob is immutable. - TODO + %true if @blob is immutable, false otherwise @@ -980,12 +1311,13 @@ See TODO:link object types for more information. + Makes a blob immutable. - a blob. + a blob @@ -1006,34 +1338,38 @@ See TODO:link object types for more information. + Attaches a user-data key/data pair to the specified blob. + %true if success, %false otherwise - a blob. + An #hb_blob_t - key for data to set. + The user-data key to set - data to set. + A pointer to the user data to set - callback to call when @data is not needed anymore. + A callback to call when @data is not needed anymore - whether to replace an existing data with the same key. + Whether to replace an existing data with the same key - + Data type for blobs. A blob wraps a chunk of binary +data and facilitates its lifecycle management between +a client program and HarfBuzz. Appends a character with the Unicode value of @codepoint to @buffer, and @@ -1049,15 +1385,15 @@ caller to ensure it is a valid Unicode code point. - an #hb_buffer_t. + An #hb_buffer_t - a Unicode code point. + A Unicode code point. - the cluster value of @codepoint. + The cluster value of @codepoint. @@ -1114,27 +1450,27 @@ Unicode code points that can fit in 8-bit strings. - an #hb_buffer_t. + An #hb_buffer_t an array of UTF-8 - characters to append. + characters to append - the length of the @text, or -1 if it is %NULL terminated. + the length of the @text, or -1 if it is %NULL terminated - the offset of the first character to add to the @buffer. + the offset of the first character to add to the @buffer the number of characters to add to the @buffer, or -1 for the - end of @text (assuming it is %NULL terminated). + end of @text (assuming it is %NULL terminated) @@ -1149,26 +1485,26 @@ see hb_buffer_set_replacement_codepoint(). - an #hb_buffer_t. + An #hb_buffer_t - an array of UTF-16 characters to append. + An array of UTF-16 characters to append - the length of the @text, or -1 if it is %NULL terminated. + The length of the @text, or -1 if it is %NULL terminated - the offset of the first character to add to the @buffer. + The offset of the first character to add to the @buffer - the number of characters to add to the @buffer, or -1 for the - end of @text (assuming it is %NULL terminated). + The number of characters to add to the @buffer, or -1 for the + end of @text (assuming it is %NULL terminated) @@ -1183,26 +1519,26 @@ see hb_buffer_set_replacement_codepoint(). - an #hb_buffer_t. + An #hb_buffer_t - an array of UTF-32 characters to append. + An array of UTF-32 characters to append - the length of the @text, or -1 if it is %NULL terminated. + The length of the @text, or -1 if it is %NULL terminated - the offset of the first character to add to the @buffer. + The offset of the first character to add to the @buffer - the number of characters to add to the @buffer, or -1 for the - end of @text (assuming it is %NULL terminated). + The number of characters to add to the @buffer, or -1 for the + end of @text (assuming it is %NULL terminated) @@ -1217,26 +1553,26 @@ see hb_buffer_set_replacement_codepoint(). - an #hb_buffer_t. + An #hb_buffer_t - an array of UTF-8 + An array of UTF-8 characters to append. - the length of the @text, or -1 if it is %NULL terminated. + The length of the @text, or -1 if it is %NULL terminated. - the offset of the first character to add to the @buffer. + The offset of the first character to add to the @buffer. - the number of characters to add to the @buffer, or -1 for the + The number of characters to add to the @buffer, or -1 for the end of @text (assuming it is %NULL terminated). @@ -1250,7 +1586,7 @@ see hb_buffer_set_replacement_codepoint(). - an #hb_buffer_t. + An #hb_buffer_t @@ -1262,11 +1598,11 @@ see hb_buffer_set_replacement_codepoint(). - an #hb_buffer_t. + An #hb_buffer_t - source #hb_buffer_t. + source #hb_buffer_t @@ -1287,12 +1623,28 @@ the replacement code point. - an #hb_buffer_t. + An #hb_buffer_t + Data type for holding HarfBuzz's clustering behavior options. The cluster level +dictates one aspect of how HarfBuzz will treat non-base characters +during shaping. + +In @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES, non-base +characters are merged into the cluster of the base character that precedes them. + +In @HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS, non-base characters are initially +assigned their own cluster values, which are not merged into preceding base +clusters. This allows HarfBuzz to perform additional operations like reorder +sequences of adjacent marks. + +@HB_BUFFER_CLUSTER_LEVEL_MONOTONE_GRAPHEMES is the default, because it maintains +backward compatibility with older versions of HarfBuzz. New client programs that +do not need to maintain such backward compatibility are recommended to use +@HB_BUFFER_CLUSTER_LEVEL_MONOTONE_CHARACTERS instead of the default. Return cluster values grouped by graphemes into monotone order. @@ -1359,6 +1711,31 @@ hb_buffer_allocation_successful() returns %false. + + + + + + + an #hb_buffer_t buffer. + + + + + + + + + + + + + + + + + + Deallocate the @buffer. Decreases the reference count on @buffer by one. If the result is zero, then @@ -1368,7 +1745,7 @@ Decreases the reference count on @buffer by one. If the result is zero, then - an #hb_buffer_t. + An #hb_buffer_t @@ -1457,25 +1834,30 @@ callers if just comparing two buffers is needed. + Fetches the cluster level of a buffer. The #hb_buffer_cluster_level_t +dictates one aspect of how HarfBuzz will treat non-base characters +during shaping. + The cluster level of @buffer - an #hb_buffer_t. + An #hb_buffer_t - see hb_buffer_set_content_type(). + Fetches the type of @buffer contents. Buffers are either empty, contain +characters (before shaping), or contain glyphs (the result of shaping). - The type of @buffer contents. + The type of @buffer contents - an #hb_buffer_t. + An #hb_buffer_t @@ -1488,25 +1870,27 @@ callers if just comparing two buffers is needed. - an #hb_buffer_t. + An #hb_buffer_t + Fetches an empty #hb_buffer_t. + The empty buffer - See hb_buffer_set_flags(). + Fetches the #hb_buffer_flags_t of @buffer. - The @buffer flags. + The @buffer flags - an #hb_buffer_t. + An #hb_buffer_t @@ -1524,11 +1908,11 @@ The value valid as long as buffer has not been modified. - an #hb_buffer_t. + An #hb_buffer_t - output array length. + The output-array length. @@ -1546,11 +1930,11 @@ The value valid as long as buffer has not been modified. - an #hb_buffer_t. + An #hb_buffer_t - output length. + The output length @@ -1558,12 +1942,12 @@ The value valid as long as buffer has not been modified. See hb_buffer_set_invisible_glyph(). - The @buffer invisible #hb_codepoint_t. + The @buffer invisible #hb_codepoint_t - an #hb_buffer_t. + An #hb_buffer_t @@ -1577,7 +1961,7 @@ The #hb_language_t of the buffer. Must not be freed by the caller. - an #hb_buffer_t. + An #hb_buffer_t @@ -1591,33 +1975,34 @@ The value valid as long as buffer has not been modified. - an #hb_buffer_t. + An #hb_buffer_t - See hb_buffer_set_replacement_codepoint(). + Fetches the #hb_codepoint_t that replaces invalid entries for a given encoding +when adding text to @buffer. - The @buffer replacement #hb_codepoint_t. + The @buffer replacement #hb_codepoint_t - an #hb_buffer_t. + An #hb_buffer_t - See hb_buffer_set_script(). + Fetches the script of @buffer. - The #hb_script_t of the @buffer. + The #hb_script_t of the @buffer - an #hb_buffer_t. + An #hb_buffer_t @@ -1629,36 +2014,42 @@ The value valid as long as buffer has not been modified. - an #hb_buffer_t. + An #hb_buffer_t - the output #hb_segment_properties_t. + The output #hb_segment_properties_t + Fetches the Unicode-functions structure of a buffer. + The Unicode-functions structure - an #hb_buffer_t. + An #hb_buffer_t + Fetches the user data associated with the specified key, +attached to the specified buffer. + A pointer to the user data - an #hb_buffer_t. + An #hb_buffer_t + The user-data key to query @@ -1688,6 +2079,21 @@ it is called. See documentation for that function for details. + + + An #hb_buffer_t + + + + + + Returns whether @buffer has glyph position data. +A buffer gains position data when hb_buffer_get_glyph_positions() is called on it, +and cleared of position data when hb_buffer_clear_contents() is called. + + %true if the @buffer has position array, %false otherwise. + + an #hb_buffer_t. @@ -1724,7 +2130,7 @@ The resulting clusters should behave identical to pre-reordering clusters. - an #hb_buffer_t. + An #hb_buffer_t @@ -1732,16 +2138,16 @@ The resulting clusters should behave identical to pre-reordering clusters. Pre allocates memory for @buffer to fit at least @size number of items. - %true if @buffer memory allocation succeeded, %false otherwise. + %true if @buffer memory allocation succeeded, %false otherwise - an #hb_buffer_t. + An #hb_buffer_t - number of items to pre allocate. + Number of items to pre allocate. @@ -1756,7 +2162,7 @@ The referenced #hb_buffer_t. - an #hb_buffer_t. + An #hb_buffer_t @@ -1769,7 +2175,7 @@ with hb_buffer_create(). - an #hb_buffer_t. + An #hb_buffer_t @@ -1781,7 +2187,7 @@ with hb_buffer_create(). - an #hb_buffer_t. + An #hb_buffer_t @@ -1795,31 +2201,85 @@ same cluster number) are reversed again. - an #hb_buffer_t. + An #hb_buffer_t - Reverses buffer contents between start to end. + Reverses buffer contents between @start and @end. - an #hb_buffer_t. + An #hb_buffer_t - start index. + start index - end index. + end index + + Serializes @buffer into a textual representation of its content, whether +Unicode codepoints or glyph identifiers and positioning information. This is +useful for showing the contents of the buffer, for example during debugging. +See the documentation of hb_buffer_serialize_unicode() and +hb_buffer_serialize_glyphs() for a description of the output format. + + The number of serialized items. + + + + + an #hb_buffer_t buffer. + + + + the first item in @buffer to serialize. + + + + the last item in @buffer to serialize. + + + + output string to + write serialized buffer into. + + + + + + the size of @buf. + + + + if not %NULL, will be set to the number of byes written into @buf. + + + + the #hb_font_t used to shape this buffer, needed to + read glyph names and extents. If %NULL, and empty font will be used. + + + + the #hb_buffer_serialize_format_t to use for formatting the output. + + + + the #hb_buffer_serialize_flags_t that control what glyph properties + to serialize. + + + + Flags that control what glyph information are serialized in hb_buffer_serialize_glyphs(). @@ -1906,6 +2366,7 @@ The serialized glyphs will look something like: ``` [uni0651=0@518,0+0|uni0628=0+1897] ``` + - The serialized glyphs are delimited with `[` and `]`. - Glyphs are separated with `|` - Each glyph starts with glyph name, or glyph index if @@ -1914,12 +2375,28 @@ The serialized glyphs will look something like: - If #HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set, the #hb_glyph_position_t in the format: - If both #hb_glyph_position_t.x_offset and #hb_glyph_position_t.y_offset are not 0, `@x_offset,y_offset`. Then, - `+x_advance`, then `,y_advance` if #hb_glyph_position_t.y_advance is not 0. Then, - - If #HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set, the - #hb_glyph_extents_t in the format - `&lt;x_bearing,y_bearing,width,height&gt;` + - If #HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set, the #hb_glyph_extents_t in the format `<x_bearing,y_bearing,width,height>` ## json -TODO. +A machine-readable, structured format. +The serialized glyphs will look something like: + +``` +[{"g":"uni0651","cl":0,"dx":518,"dy":0,"ax":0,"ay":0}, +{"g":"uni0628","cl":0,"dx":0,"dy":0,"ax":1897,"ay":0}] +``` + +Each glyph is a JSON object, with the following properties: +- `g`: the glyph name or glyph index if + #HB_BUFFER_SERIALIZE_FLAG_NO_GLYPH_NAMES flag is set. +- `cl`: #hb_glyph_info_t.cluster if + #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set. +- `dx`,`dy`,`ax`,`ay`: #hb_glyph_position_t.x_offset, #hb_glyph_position_t.y_offset, + #hb_glyph_position_t.x_advance and #hb_glyph_position_t.y_advance + respectively, if #HB_BUFFER_SERIALIZE_FLAG_NO_POSITIONS is not set. +- `xb`,`yb`,`w`,`h`: #hb_glyph_extents_t.x_bearing, #hb_glyph_extents_t.y_bearing, + #hb_glyph_extents_t.width and #hb_glyph_extents_t.height respectively if + #HB_BUFFER_SERIALIZE_FLAG_GLYPH_EXTENTS is set. The number of serialized items. @@ -1978,33 +2455,111 @@ A string array of buffer serialization formats. Should not be freed. + + Serializes @buffer into a textual representation of its content, +when the buffer contains Unicode codepoints (i.e., before shaping). This is +useful for showing the contents of the buffer, for example during debugging. +There are currently two supported serialization formats: + +## text +A human-readable, plain text format. +The serialized codepoints will look something like: + +``` + <U+0651=0|U+0628=1> +``` + +- Glyphs are separated with `|` +- Unicode codepoints are expressed as zero-padded four (or more) + digit hexadecimal numbers preceded by `U+` +- If #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set, the cluster + will be indicated with a `=` then #hb_glyph_info_t.cluster. + +## json +A machine-readable, structured format. +The serialized codepoints will be a list of objects with the following +properties: +- `u`: the Unicode codepoint as a decimal integer +- `cl`: #hb_glyph_info_t.cluster if + #HB_BUFFER_SERIALIZE_FLAG_NO_CLUSTERS is not set. + +For example: + +``` +[{u:1617,cl:0},{u:1576,cl:1}] +``` + + The number of serialized items. + + + + + an #hb_buffer_t buffer. + + + + the first item in @buffer to serialize. + + + + the last item in @buffer to serialize. + + + + output string to + write serialized buffer into. + + + + + + the size of @buf. + + + + if not %NULL, will be set to the number of byes written into @buf. + + + + the #hb_buffer_serialize_format_t to use for formatting the output. + + + + + + + + Sets the cluster level of a buffer. The #hb_buffer_cluster_level_t +dictates one aspect of how HarfBuzz will treat non-base characters +during shaping. - an #hb_buffer_t. + An #hb_buffer_t + The cluster level to set on the buffer - Sets the type of @buffer contents, buffers are either empty, contain -characters (before shaping) or glyphs (the result of shaping). + Sets the type of @buffer contents. Buffers are either empty, contain +characters (before shaping), or contain glyphs (the result of shaping). - an #hb_buffer_t. + An #hb_buffer_t - the type of buffer contents to set + The type of buffer contents to set @@ -2022,7 +2577,7 @@ direction. - an #hb_buffer_t. + An #hb_buffer_t @@ -2038,11 +2593,11 @@ direction. - an #hb_buffer_t. + An #hb_buffer_t - the buffer flags to set. + The buffer flags to set @@ -2057,7 +2612,7 @@ verbatim. - an #hb_buffer_t. + An #hb_buffer_t @@ -2081,11 +2636,11 @@ Use hb_language_from_string() to convert from BCP 47 language tags to - an #hb_buffer_t. + An #hb_buffer_t - an hb_language_t to set. + An hb_language_t to set @@ -2099,11 +2654,11 @@ end. - an #hb_buffer_t. + An #hb_buffer_t - the new length of @buffer. + The new length of @buffer @@ -2114,7 +2669,7 @@ end. - an #hb_buffer_t. + An #hb_buffer_t @@ -2138,7 +2693,7 @@ Default is %HB_BUFFER_REPLACEMENT_CODEPOINT_DEFAULT. - an #hb_buffer_t. + An #hb_buffer_t @@ -2162,11 +2717,11 @@ corresponding script from an ISO 15924 script tag. - an #hb_buffer_t. + An #hb_buffer_t - an #hb_script_t to set. + An #hb_script_t to set. @@ -2180,48 +2735,57 @@ hb_buffer_set_language() individually. - an #hb_buffer_t. + An #hb_buffer_t - an #hb_segment_properties_t to use. + An #hb_segment_properties_t to use + Sets the Unicode-functions structure of a buffer to +@unicode_funcs. - an #hb_buffer_t. + An #hb_buffer_t + The Unicode-functions structure + Attaches a user-data key/data pair to the specified buffer. + %true if success, %false otherwise - an #hb_buffer_t. + An #hb_buffer_t + The user-data key + A pointer to the user data + A callback to call when @data is not needed anymore + Whether to replace an existing data with the same key @@ -2289,21 +2853,35 @@ and output glyphs and their information after shaping. + Converts a string to an #hb_direction_t. + +Matching is loose and applies only to the first letter. For +examples, "LTR" and "left-to-right" will both return #HB_DIRECTION_LTR. + +Unmatched strings will return #HB_DIRECTION_INVALID. + The #hb_direction_t matching @str + String to convert + Length of @str, or -1 if it is %NULL-terminated + The direction of a text segment or buffer. + +A segment can also be tested for horizontal or vertical +orientation (irrespective of specific direction) with +HB_DIRECTION_IS_HORIZONTAL() or HB_DIRECTION_IS_VERTICAL(). Initial, unset direction. @@ -2321,11 +2899,14 @@ and output glyphs and their information after shaping. + Converts an #hb_direction_t to a string. + The string corresponding to @direction + The #hb_direction_t to convert @@ -2338,12 +2919,15 @@ be created using hb_face_builder_create(). + A face object created with hb_face_builder_create() + The #hb_tag_t of the table to add + The blob containing the table data to add @@ -2358,55 +2942,62 @@ font file by calling hb_face_reference_blob(). + Collects all of the Unicode characters covered by @face and adds +them to the #hb_set_t set @out. - font face. + A face object - set to add Unicode characters covered by @face to. + The set to add Unicode characters to + Collects all Unicode "Variation Selector" characters covered by @face and adds +them to the #hb_set_t set @out. - font face. + A face object - set to add Variation Selector characters covered by @face to. + The set to add Variation Selector characters to + Collects all Unicode characters for @variation_selector covered by @face and adds +them to the #hb_set_t set @out. - font face. + A face object + The Variation Selector to query - set to add Unicode characters for @variation_selector covered by @face to. + The set to add Unicode characters to - Get number of faces in a blob. + Fetches the number of faces in a blob. Number of faces in @blob @@ -2419,247 +3010,314 @@ font file by calling hb_face_reference_blob(). + Constructs a new face object from the specified blob and +a face index into that blob. This is used for blobs of +file formats such as Dfont and TTC that can contain more +than one face. + The new face object + #hb_blob_t to work upon + The index of the face within @blob + Variant of hb_face_create(), built for those cases where it is more +convenient to provide data for individual tables instead of the whole font +data. With the caveat that hb_face_get_table_tags() does not currently work +with faces created this way. + +Creates a new face object from the specified @user_data and @reference_table_func, +with the @destroy callback. + The new face object + Table-referencing function + A pointer to the user data + A callback to call when @data is not needed anymore + Decreases the reference count on a face object. When the +reference count reaches zero, the face is destroyed, +freeing all memory. - a face. + A face object + Fetches the singleton empty face object. + The empty face object + Fetches the glyph-count value of the specified face object. + The glyph-count value of @face - a face. + A face object + Fetches the face-index corresponding to the given face. + +<note>Note: face indices within a collection are zero-based.</note> + The index of @face. - a face. + A face object - Retrieves table tags for a face, if possible. + Fetches a list of all table tags for a face, if possible. The list returned will +begin at the offset provided - total number of tables, or 0 if not possible to list. + Total number of tables, or zero if it is not possible to list - a face. + A face object - index of first tag to return. + The index of first table tag to retrieve - - input length of @table_tags array, output number of items written. + + Input = the maximum number of table tags to return; + Output = the actual number of table tags returned (may be zero) - - array to write tags into. - + + The array of table tags found + + + + Fetches the units-per-em (upem) value of the specified face object. + The upem value of @face - a face. + A face object + Fetches the user data associated with the specified key, +attached to the specified face object. + A pointer to the user data - a face. + A face object + The user-data key to query + Tests whether the given face object is immutable. + True is @face is immutable, false otherwise - a face. + A face object + Makes the given face object immutable. - a face. + A face object + Increases the reference count on a face object. + The @face object - a face. + A face object + Fetches a pointer to the binary blob that contains the +specified face. Returns an empty blob if referencing face data is not +possible. + A pointer to the blob for @face - a face. + A face object + Fetches a reference to the specified table within +the specified face. + A pointer to the @tag table within @face - a face. + A face object + The #hb_tag_t of the table to query + Sets the glyph count for a face object to the specified value. - a face. + A face object + The glyph-count value to assign + Assigns the specified face-index to @face. Fails if the +face is immutable. + +<note>Note: face indices within a collection are zero-based.</note> - a face. + A face object + The index to assign + Sets the units-per-em (upem) for a face object to the specified value. - a face. + A face object + The units-per-em value to assign + Attaches a user-data key/data pair to the given face object. + %true if success, %false otherwise - a face. + A face object + The user-data key to set + A pointer to the user data + A callback to call when @data is not needed anymore + Whether to replace an existing data with the same key - + Data type for holding font faces. Parses a string into a #hb_feature_t. @@ -2700,7 +3358,7 @@ The format is Python-esque. Here is how it all works: </tgroup> </informaltable> - %true if @str is successfully parsed, %false otherwise. + %true if @str is successfully parsed, %false otherwise @@ -2727,13 +3385,13 @@ glyphs which are in clusters between @start (inclusive) and @end (exclusive). Setting start to @HB_FEATURE_GLOBAL_START and end to @HB_FEATURE_GLOBAL_END specifies that the feature always applies to the entire buffer. - a feature tag + The #hb_tag_t tag of the feature - 0 disables the feature, non-zero (usually 1) enables the feature. -For features implemented as lookup type 3 (like 'salt') the @value is a one -based index into the alternates. + The value of the feature. 0 disables the feature, non-zero (usually +1) enables the feature. For features implemented as lookup type 3 (like +'salt') the @value is a one based index into the alternates. @@ -2794,30 +3452,43 @@ allocating big enough size for @buf, 128 bytes is more than enough. + Adds the origin coordinates to an (X,Y) point coordinate, in +the specified glyph ID in the specified font. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. - a font. + #hb_font_t to work upon + The glyph ID to query + The direction of the text segment - + + Input = The original X coordinate + Output = The X coordinate plus the X-coordinate of the origin - + + Input = The original Y coordinate + Output = The Y coordinate plus the Y-coordinate of the origin + Constructs a new font object from the specified face. + The new font object @@ -2828,35 +3499,48 @@ allocating big enough size for @buf, 128 bytes is more than enough. + Constructs a sub-font font object from the specified @parent font, +replicating the parent's properties. + The new sub-font font object - parent font. + The parent font object + Decreases the reference count on the given font object. When the +reference count reaches zero, the font is destroyed, +freeing all memory. - a font. + #hb_font_t to work upon + Font-wide extent values, measured in font units. + +Note that typically @ascender is positive and @descender +negative, in coordinate systems that grow up. + The height of typographic ascenders. + The depth of typographic descenders. + The suggested line-spacing gap. @@ -2888,169 +3572,205 @@ allocating big enough size for @buf, 128 bytes is more than enough. + Creates a new #hb_font_funcs_t structure of font functions. + The font-functions structure + Decreases the reference count on a font-functions structure. When +the reference count reaches zero, the font-functions structure is +destroyed, freeing all memory. - font functions. + The font-functions structure + Fetches an empty font-functions structure. + The font-functions structure + Fetches the user data associated with the specified key, +attached to the specified font-functions structure. + A pointer to the user data - font functions. + The font-functions structure + The user-data key to query + Tests whether a font-functions structure is immutable. + %true if @ffuncs is immutable, false otherwise - font functions. + The font-functions structure + Makes a font-functions structure immutable. - font functions. + The font-functions structure + Increases the reference count on a font-functions structure. + The font-functions structure - font functions. + The font-functions structure + Sets the implementation function for #hb_font_get_font_h_extents_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_font_v_extents_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_glyph_contour_point_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_glyph_extents_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_glyph_from_name_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore @@ -3063,59 +3783,67 @@ hb_font_funcs_set_variation_glyph_func() instead. - font functions. + The font-functions structure - callback function. + callback function - data to pass to @func. + data to pass to @func - function to call when @user_data is not needed anymore. + function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_glyph_h_advance_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_glyph_h_advances_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore @@ -3141,81 +3869,97 @@ hb_font_funcs_set_variation_glyph_func() instead. + Sets the implementation function for #hb_font_get_glyph_h_origin_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_glyph_name_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_glyph_v_advance_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_glyph_v_advances_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore @@ -3241,140 +3985,180 @@ hb_font_funcs_set_variation_glyph_func() instead. + Sets the implementation function for #hb_font_get_glyph_v_origin_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_nominal_glyph_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_font_get_nominal_glyphs_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Attaches a user-data key/data pair to the specified font-functions structure. + %true if success, %false otherwise - font functions. + The font-functions structure + The user-data key to set + A pointer to the user data set + A callback to call when @data is not needed anymore + Whether to replace an existing data with the same key + Sets the implementation function for #hb_font_get_variation_glyph_func_t. - font functions. + A font-function structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore - + Data type containing a set of virtual methods used for +working on #hb_font_t font objects. + +HarfBuzz provides a lightweight default function for each of +the methods in #hb_font_funcs_t. Client programs can implement +their own replacements for the individual font functions, as +needed, and replace the default by calling the setter for a +method. + Fetches the empty font object. + The empty font object + Fetches the extents for a font in a text segment of the +specified direction. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. - a font. + #hb_font_t to work upon + The direction of the text segment + The #hb_glyph_extents_t retrieved + Fetches the face associated with the specified font object. + The #hb_face_t value - a font. + #hb_font_t to work upon @@ -3399,49 +4183,71 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the glyph ID for a Unicode code point in the specified +font, with an optional variation selector. + +If @variation_selector is 0, calls hb_font_get_nominal_glyph(); +otherwise calls hb_font_get_variation_glyph(). + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The Unicode code point to query + A variation-selector code point + The glyph ID retrieved + Fetches the advance for a glyph ID from the specified font, +in a text segment of the specified direction. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. - a font. + #hb_font_t to work upon + The glyph ID to query + The direction of the text segment + The horizontal advance retrieved + The vertical advance retrieved + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the advance for a specified glyph. The +method must return an #hb_position_t. @@ -3461,35 +4267,49 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the advances for a sequence of glyph IDs in the specified +font, in a text segment of the specified direction. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. - a font. + #hb_font_t to work upon + The direction of the text segment + The number of glyph IDs in the sequence queried + The first glyph ID to query + The stride between successive glyph IDs - + + The first advance retrieved - + + The stride between successive advances + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the advances for a sequence of glyphs. @@ -3521,55 +4341,79 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the (x,y) coordinates of a specified contour-point index +in the specified glyph, within the specified font. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The glyph ID to query + The contour-point index to query + The X value retrieved for the contour point + The Y value retrieved for the contour point + Fetches the (X,Y) coordinates of a specified contour-point index +in the specified glyph ID in the specified font, with respect +to the origin in a text segment in the specified direction. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The glyph ID to query + The contour-point index to query + The direction of the text segment + The X value retrieved for the contour point + The Y value retrieved for the contour point + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the (X,Y) coordinates (in font units) for a +specified contour point in a glyph. Each coordinate must be returned as +an #hb_position_t output parameter. @@ -3598,43 +4442,62 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the #hb_glyph_extents_t data for a glyph ID +in the specified font. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The glyph ID to query + The #hb_glyph_extents_t retrieved + Fetches the #hb_glyph_extents_t data for a glyph ID +in the specified font, with respect to the origin in +a text segment in the specified direction. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The glyph ID to query + The direction of the text segment + The #hb_glyph_extents_t retrieved + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the extents for a specified glyph. Extents must be +returned in an #hb_glyph_extents output parameter. @@ -3657,28 +4520,39 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the glyph ID that corresponds to a name string in the specified @font. + +<note>Note: @len == -1 means the name string is null-terminated.</note> + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The name string to query + The length of the name queried + The glyph ID retrieved + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the glyph ID that corresponds to a glyph-name +string. @@ -3729,104 +4603,138 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the advance for a glyph ID in the specified font, +for horizontal text segments. + The advance of @glyph within @font - a font. + #hb_font_t to work upon + The glyph ID to query + Fetches the advances for a sequence of glyph IDs in the specified +font, for horizontal text segments. - a font. + #hb_font_t to work upon + The number of glyph IDs in the sequence queried + The first glyph ID to query + The stride between successive glyph IDs - + + The first advance retrieved - + + The stride between successive advances + Fetches the kerning-adjustment value for a glyph-pair in +the specified font, in horizontal text segments. + +<note>It handles legacy kerning only (as returned by the corresponding +#hb_font_funcs_t function).</note> + The kerning adjustment value - a font. + #hb_font_t to work upon + The glyph ID of the left glyph in the glyph pair + The glyph ID of the right glyph in the glyph pair + Fetches the (X,Y) coordinates of the origin for a glyph ID +in the specified font, for horizontal text segments. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The glyph ID to query + The X coordinate of the origin + The Y coordinate of the origin + Fetches the kerning-adjustment value for a glyph-pair in the specified font. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. - a font. + #hb_font_t to work upon + The glyph ID of the first glyph in the glyph pair to query + The glyph ID of the second glyph in the glyph pair to query + The direction of the text segment + The horizontal kerning-adjustment value retrieved + The vertical kerning-adjustment value retrieved @@ -3854,28 +4762,37 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the glyph-name string for a glyph ID in the specified @font. + %true if data found, zero otherwise - a font. + #hb_font_t to work upon + The glyph ID to query - + + Name string retrieved for the glyph ID - + + Length of the glyph-name string retrieved + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the glyph name that corresponds to a +glyph ID. The name should be returned in a string output parameter. @@ -3901,29 +4818,43 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the (X,Y) coordinates of the origin for a glyph in +the specified font. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. - a font. + #hb_font_t to work upon + The glyph ID to query + The direction of the text segment + The X coordinate retrieved for the origin + The Y coordinate retrieved for the origin + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the (X,Y) coordinates (in font units) of the +origin for a glyph. Each coordinate must be returned in an #hb_position_t +output parameter. @@ -3949,114 +4880,156 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the advance for a glyph ID in the specified font, +for vertical text segments. + The advance of @glyph within @font - a font. + #hb_font_t to work upon + The glyph ID to query + Fetches the advances for a sequence of glyph IDs in the specified +font, for vertical text segments. - a font. + #hb_font_t to work upon + The number of glyph IDs in the sequence queried + The first glyph ID to query + The stride between successive glyph IDs - + + The first advance retrieved - + + The stride between successive advances + Fetches the kerning-adjustment value for a glyph-pair in +the specified font, in vertical text segments. + +<note>It handles legacy kerning only (as returned by the corresponding +#hb_font_funcs_t function).</note> + The kerning adjustment value - a font. + #hb_font_t to work upon + The glyph ID of the top glyph in the glyph pair + The glyph ID of the bottom glyph in the glyph pair + Fetches the (X,Y) coordinates of the origin for a glyph ID +in the specified font, for vertical text segments. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The glyph ID to query + The X coordinate of the origin + The Y coordinate of the origin + Fetches the extents for a specified font, in horizontal +text segments. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The font extents retrieved + Fetches the nominal glyph ID for a Unicode code point in the +specified font. + +This version of the function should not be used to fetch glyph IDs +for code points modified by variation selectors. For variation-selector +support, user hb_font_get_variation_glyph() or use hb_font_get_glyph(). + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The Unicode code point to query + The glyph ID retrieved + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the nominal glyph ID for a specified Unicode code +point. Glyph IDs must be returned in a #hb_codepoint_t output parameter. @@ -4105,6 +5078,11 @@ hb_font_funcs_set_variation_glyph_func() instead. + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the nominal glyph IDs for a sequence of +Unicode code points. Glyph IDs must be returned in a #hb_codepoint_t +output parameter. @@ -4136,127 +5114,161 @@ hb_font_funcs_set_variation_glyph_func() instead. + Fetches the parent font of @font. + The parent font object - a font. + #hb_font_t to work upon + Fetches the horizontal and vertical points-per-em (ppem) of a font. - a font. + #hb_font_t to work upon + Horizontal ppem value + Vertical ppem value - Gets the "point size" of the font. A value of 0 means unset. + Fetches the "point size" of a font. Used in CoreText to +implement optical sizing. - Point size. + Point size. A value of zero means "not set." - a font. + #hb_font_t to work upon + Fetches the horizontal and vertical scale of a font. - a font. + #hb_font_t to work upon + Horizontal scale value + Vertical scale value + Fetches the user-data object associated with the specified key, +attached to the specified font object. + Pointer to the user data - a font. + #hb_font_t to work upon + The user-data key to query + Fetches the extents for a specified font, in vertical +text segments. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The font extents retrieved - Return value is valid as long as variation coordinates of the font + Fetches the list of normalized variation coordinates currently +set on a font. + +Return value is valid as long as variation coordinates of the font are not modified. + #hb_font_t to work upon + Number of coordinates retrieved + Fetches the glyph ID for a Unicode code point when followed by +by the specified variation-selector code point, in the specified +font. + %true if data found, false otherwise - a font. + #hb_font_t to work upon + The Unicode code point to query + The variation-selector code point to query + The glyph ID retrieved + A virtual method for the #hb_font_funcs_t of an #hb_font_t object. + +This method should retrieve the glyph ID for a specified Unicode code point +followed by a specified Variation Selector code point. Glyph IDs must be +returned in a #hb_codepoint_t output parameter. @@ -4282,178 +5294,211 @@ are not modified. + Fetches the glyph ID from @font that matches the specified string. +Strings of the format `gidDDD` or `uniUUUU` are parsed automatically. + +<note>Note: @len == -1 means the string is null-terminated.</note> + %true if data found, false otherwise - a font. + #hb_font_t to work upon + string to query + The length of the string @s + The glyph ID corresponding to the string requested + Fetches the name of the specified glyph ID in @font and returns +it in string @s. + +If the glyph ID has no name in @font, a string of the form `gidDDD` is +generated, with `DDD` being the glyph ID. - a font. + #hb_font_t to work upon + The glyph ID to query - + + The string containing the glyph name - + + Length of string @s + Tests whether a font object is immutable. + %true if @font is immutable, false otherwise - a font. + #hb_font_t to work upon + Makes @font immutable. - a font. + #hb_font_t to work upon + Increases the reference count on the given font object. + The @font object - a font. + #hb_font_t to work upon - Sets font-face of @font. + Sets @face as the font-face value of @font. - a font. + #hb_font_t to work upon - new face. + The #hb_face_t to assign + Replaces the font-functions structure attached to a font, updating +the font's user-data with @font-data and the @destroy callback. - a font. + #hb_font_t to work upon + Data to attach to @font + The function to call when @font_data is not needed anymore + Replaces the user data attached to a font, updating the font's +@destroy callback. - a font. + #hb_font_t to work upon + Data to attach to @font + The function to call when @font_data is not needed anymore - Sets parent font of @font. + Sets the parent font of @font. - a font. + #hb_font_t to work upon - new parent. + The parent font object to assign + Sets the horizontal and vertical pixels-per-em (ppem) of a font. - a font. + #hb_font_t to work upon + Horizontal ppem value to assign + Vertical ppem value to assign - Sets "point size" of the font. Set to 0 to unset. + Sets the "point size" of a font. Set to zero to unset. +Used in CoreText to implement optical sizing. -There are 72 points in an inch. +<note>Note: There are 72 points in an inch.</note> - a font. + #hb_font_t to work upon @@ -4463,73 +5508,97 @@ There are 72 points in an inch. + Sets the horizontal and vertical scale of a font. - a font. + #hb_font_t to work upon + Horizontal scale value to assign + Vertical scale value to assign + Attaches a user-data key/data pair to the specified font object. - a font. + #hb_font_t to work upon + The user-data key + A pointer to the user data + A callback to call when @data is not needed anymore + Whether to replace an existing data with the same key + Applies a list of variation coordinates (in design-space units) +to a font. + #hb_font_t to work upon - + Array of variation coordinates to apply + + + + Number of coordinates to apply + Applies a list of variation coordinates (in normalized units) +to a font. + +<note>Note: Coordinates should be normalized to 2.14.</note> + #hb_font_t to work upon - + Array of variation coordinates to apply + + + + Number of coordinates to apply @@ -4551,47 +5620,62 @@ There are 72 points in an inch. + Applies a list of font-variation settings to a font. + #hb_font_t to work upon - + Array of variation settings to apply + + + + Number of variations to apply + Subtracts the origin coordinates from an (X,Y) point coordinate, +in the specified glyph ID in the specified font. + +Calls the appropriate direction-specific variant (horizontal +or vertical) depending on the value of @direction. - a font. + #hb_font_t to work upon + The glyph ID to query + The direction of the text segment - + + Input = The original X coordinate + Output = The X coordinate minus the X-coordinate of the origin - + + Input = The original Y coordinate + Output = The Y coordinate minus the Y-coordinate of the origin - - - + @@ -4724,16 +5808,23 @@ specified GUnicodeScript identifier. + Glyph extent values, measured in font units. + +Note that @height is negative, in coordinate systems that grow up. + Distance from the x-origin to the left extremum of the glyph. + Distance from the top extremum of the glyph to the y-origin. + Distance from the left extremum of the glyph to the right extremum. + Distance from the top extremum of the glyph to the bottom extremum. @@ -4762,12 +5853,12 @@ specified GUnicodeScript identifier. Returns glyph flags encoded within a #hb_glyph_info_t. - The #hb_glyph_flags_t encoded within @info. + The #hb_glyph_flags_t encoded within @info - a #hb_glyph_info_t. + a #hb_glyph_info_t @@ -4832,6 +5923,172 @@ glyph in both horizontal and vertical directions. All positions in + + Functions for querying AAT Layout features in the font face. + +HarfBuzz supports all of the AAT tables used to implement shaping. Other +AAT tables and their associated features are not supported. + + + Blobs wrap a chunk of binary data to handle lifecycle management of data +while it is passed between client and HarfBuzz. Blobs are primarily used +to create font faces, but also to access font face tables, as well as +pass around other binary data. + + + Buffers serve a dual role in HarfBuzz; before shaping, they hold +the input characters that are passed to hb_shape(), and after +shaping they hold the output glyphs. + + + Common data types used across HarfBuzz are defined here. + + + These API have been deprecated in favor of newer API, or because they +were deemed unnecessary. + + + A font face is an object that represents a single face from within a +font family. + +More precisely, a font face represents a single face in a binary font file. +Font faces are typically built from a binary blob and a face index. +Font faces are used to create fonts. + + + Functions for working with font objects. + +A font object represents a font face at a specific size and with +certain other parameters (pixels-per-em, points-per-em, variation +settings) specified. Font objects are created from font face +objects, and are used as input to hb_shape(), among other things. + +Client programs can optionally pass in their own functions that +implement the basic, lower-level queries of font objects. This set +of font functions is defined by the virtual methods in +#hb_font_funcs_t. + +HarfBuzz provides a built-in set of lightweight default +functions for each method in #hb_font_funcs_t. + + + Functions for using HarfBuzz with the FreeType library. + +HarfBuzz supports using FreeType to provide face and +font data. + +<note>Note that FreeType is not thread-safe, therefore these +functions are not thread-safe either.</note> + + + Functions for using HarfBuzz with the GLib library. + +HarfBuzz supports using GLib to provide Unicode data, by attaching +GLib functions to the virtual methods in a #hb_unicode_funcs_t function +structure. + + + Support for using HarfBuzz with the GObject library to provide +type data. + +The types and functions listed here are solely a linkage between +HarfBuzz's public data types and the GTypes used by the GObject framework. +HarfBuzz uses GObject introspection to generate its Python bindings +(and potentially other language bindings); client programs should never need +to access the GObject-integration mechanics. + +For client programs using the GNOME and GTK software stack, please see the +GLib and FreeType integration pages. + + + Functions for using HarfBuzz with fonts that include Graphite features. + +For Graphite features to work, you must be sure that HarfBuzz was compiled +with the `graphite2` shaping engine enabled. Currently, the default is to +not enable `graphite2` shaping. + + + Map objects are integer-to-integer hash-maps. Currently they are +not used in the HarfBuzz public API, but are provided for client's +use if desired. + + + Functions for fetching color-font information from OpenType font faces. + +HarfBuzz supports `COLR`/`CPAL`, `sbix`, `CBDT`, and `SVG` color fonts. + + + Functions for using OpenType fonts with hb_shape(). Note that fonts returned +by hb_font_create() default to using these functions, so most clients would +never need to call these functions directly. + + + Functions for querying OpenType Layout features in the font face. + + + Functions for fetching mathematics layout data from OpenType fonts. + +HarfBuzz itself does not implement a math layout solution. The +functions and types provided can be used by client programs to access +the font data necessary for typesetting OpenType Math layout. + + + Functions for fetching metadata from fonts. + + + Functions for fetching metrics from fonts. + + + Functions for fetching name strings from OpenType fonts. + + + Support functions for OpenType shaping related queries. + + + Functions for fetching information about OpenType Variable Fonts. + + + Set objects represent a mathematical set of integer values. They are +used in non-shaping APIs to query certain sets of characters or glyphs, +or other integer values. + + + Shaping is the central operation of HarfBuzz. Shaping operates on buffers, +which are sequences of Unicode characters that use the same font and have +the same text direction, script, and language. After shaping the buffer +contains the output glyphs and their positions. + + + Shape plans are an internal mechanism. Each plan contains state +describing how HarfBuzz will shape a particular text segment, based on +the combination of segment properties and the capabilities in the +font face in use. + +Shape plans are not used for shaping directly, but can be queried to +access certain information about how shaping will perform, given a set +of specific input parameters (script, language, direction, features, +etc.). + +Most client programs will not need to deal with shape plans directly. + + + Unicode functions are used to access Unicode character properties. +With these functions, client programs can query various properties from +the Unicode Character Database for any code point, such as General +Category (gc), Script (sc), Canonical Combining Class (ccc), etc. + +Client programs can optionally pass in their own Unicode functions +that implement the same queries. The set of functions available is +defined by the virtual methods in #hb_unicode_funcs_t. + +HarfBuzz provides built-in default functions for each method in +#hb_unicode_funcs_t. + + + These functions and macros allow accessing version of the HarfBuzz +library used at compile- as well as run-time, and to direct code +conditionally based on those versions, again, at compile- or run-time. + Converts @str representing a BCP 47 language tag to the corresponding #hb_language_t. @@ -4855,21 +6112,23 @@ The #hb_language_t corresponding to the BCP 47 language tag. - Get default language from current locale. + Fetch the default language from current locale. -Note that the first time this function is called, it calls +<note>Note that the first time this function is called, it calls "setlocale (LC_CTYPE, nullptr)" to fetch current locale. The underlying setlocale function is, in many implementations, NOT threadsafe. To avoid problems, call this function once before multiple threads can call it. This function is only used from hb_buffer_guess_segment_properties() by -HarfBuzz itself. +HarfBuzz itself.</note> + The default language of the locale as +an #hb_language_t - See hb_language_from_string(). + Converts an #hb_language_t to a string. A %NULL-terminated string representing the @language. Must not be freed by @@ -4878,14 +6137,14 @@ the caller. - an #hb_language_t to convert. + The #hb_language_t to convert - See hb_language_from_string(). + Converts an #hb_language_t to a string. A %NULL-terminated string representing the @language. Must not be freed by @@ -4894,187 +6153,247 @@ the caller. - an #hb_language_t to convert. + The #hb_language_t to convert + Tests whether memory allocation for a set was successful. + %true if allocation succeeded, false otherwise - a map. + A map + Clears out the contents of @map. - a map. + A map + Creates a new, initially empty map. + The new #hb_map_t + Removes @key and its stored value from @map. - a map. + A map + The key to delete + Decreases the reference count on a map. When +the reference count reaches zero, the map is +destroyed, freeing all memory. - a map. + A map + Fetches the value stored for @key in @map. - a map. + A map + The key to query + Fetches the singleton empty #hb_map_t. + The empty #hb_map_t + Returns the number of key-value pairs in the map. + The population of @map - a map. + A map + Fetches the user data associated with the specified key, +attached to the specified map. + A pointer to the user data - a map. + A map + The user-data key to query + Tests whether @key is an element of @map. + %true if @key is found in @map, false otherwise - a map. + A map + The key to query + Tests whether @map is empty (contains no elements). + %true if @map is empty - a map. + A map + Increases the reference count on a map. + The map - a map. + A map + Stores @key:@value in the map. - a map. + A map + The key to store in the map + The value to store for @key + Attaches a user-data key/data pair to the specified map. + %true if success, %false otherwise - a map. + A map + The user-data key to set + A pointer to the user data to set + A callback to call when @data is not needed anymore + Whether to replace an existing data with the same key - + Data type for holding integer-to-integer hash maps. + @HB_MEMORY_MODE_DUPLICATE +@HB_MEMORY_MODE_READONLY +@HB_MEMORY_MODE_WRITABLE +@HB_MEMORY_MODE_READONLY_MAY_MAKE_WRITABLE +Data type holding the memory modes available to +client programs. + +Regarding these various memory-modes: + +- In no case shall the HarfBuzz client modify memory + that is passed to HarfBuzz in a blob. If there is + any such possibility, @HB_MEMORY_MODE_DUPLICATE should be used + such that HarfBuzz makes a copy immediately, + +- Use @HB_MEMORY_MODE_READONLY otherwise, unless you really really + really know what you are doing, + +- @HB_MEMORY_MODE_WRITABLE is appropriate if you really made a + copy of data solely for the purpose of passing to + HarfBuzz and doing that just once (no reuse!), + +- If the font is mmap()ed, it's okay to use + @HB_MEMORY_READONLY_MAY_MAKE_WRITABLE, however, using that mode + correctly is very tricky. Use @HB_MEMORY_MODE_READONLY instead. @@ -5340,11 +6659,13 @@ If the requested palette has no name the result is #HB_OT_NAME_ID_INVALID. + Sets the font functions to use when working with @font. + #hb_font_t to work upon @@ -5535,7 +6856,7 @@ begin at the offset provided. Fetches name indices from feature parameters for "Stylistic Set" ('ssXX') or "Character Variant" ('cvXX') features. - true if data found, false otherwise + %true if data found, false otherwise @@ -5773,7 +7094,7 @@ a subfamily are not covered by the `size` feature. For more information on this distinction, see the [`size` feature documentation]( https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size). - true if data found, false otherwise + %true if data found, false otherwise @@ -5824,7 +7145,7 @@ https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size). Tests whether a face has any glyph classes defined in its GDEF table. - true if data found, false otherwise + %true if data found, false otherwise @@ -5836,7 +7157,7 @@ https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size). - true if the face has GPOS data, false otherwise + %true if the face has GPOS data, false otherwise @@ -5849,7 +7170,7 @@ https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size). Tests whether the specified face includes any GSUB substitutions. - true if data found, false otherwise + %true if data found, false otherwise @@ -5863,7 +7184,7 @@ https://docs.microsoft.com/en-us/typography/opentype/spec/features_pt#tag-size). Fetches the index of a given feature tag in the specified face's GSUB table or GPOS table, underneath the specified script and language. - true if the feature is found, false otherwise + %true if the feature is found, false otherwise @@ -5979,7 +7300,7 @@ returned will begin at the offset provided. Fetches the tag of a requested feature index in the given face's GSUB or GPOS table, underneath the specified script and language. - true if the feature is found, false otherwise + %true if the feature is found, false otherwise @@ -6013,7 +7334,7 @@ underneath the specified script and language. Fetches the index of a requested feature in the given face's GSUB or GPOS table, underneath the specified script and language. - true if the feature is found, false otherwise + %true if the feature is found, false otherwise @@ -6071,7 +7392,7 @@ specified face's GSUB table or GPOS table. - Array of glyphs that would be the substitued output of the lookup + Array of glyphs that would be the substituted output of the lookup @@ -6138,7 +7459,7 @@ specified lookup. Tests whether a specified lookup in the specified face would trigger a substitution on the given glyph sequence. - true if a substitution would be triggered, false otherwise + %true if a substitution would be triggered, false otherwise @@ -6191,7 +7512,7 @@ or GPOS table, underneath the specified script tag. ?? ?? - true if the language tag is found, false otherwise + %true if the language tag is found, false otherwise @@ -6257,7 +7578,7 @@ the specified script index. The list returned will begin at the offset provided. Fetches the index of a given language tag in the specified face's GSUB table or GPOS table, underneath the specified script index. - true if the language tag is found, false otherwise + %true if the language tag is found, false otherwise @@ -6335,7 +7656,7 @@ or GPOS table, at the specified variation coordinates. - The number of variation coorinates + The number of variation coordinates @@ -6348,7 +7669,7 @@ or GPOS table, at the specified variation coordinates. Fetches the index if a given script tag in the specified face's GSUB table or GPOS table. - true if the script is found, false otherwise + %true if the script is found, false otherwise @@ -7233,23 +8554,33 @@ used as long as @face is alive. + Computes the transitive closure of glyphs needed for a specified +input buffer under the given font and feature list. The closure is +computed as a set, not as a list. + #hb_font_t to work upon + The input buffer to compute from - + The features enabled on the buffer + + + + The number of features enabled on the buffer - + + The #hb_set_t set of glyphs comprising the transitive closure of the query @@ -7368,25 +8699,38 @@ the language tag results + Data type for holding variation-axis values. + +The minimum, default, and maximum values are in un-normalized, user scales. + +<note>Note: at present, the only flag defined for @flags is +#HB_OT_VAR_AXIS_FLAG_HIDDEN.</note> + Index of the axis in the variation-axis array + The #hb_tag_t tag identifying the design variation of the axis + The `name` table Name ID that provides display names for the axis + The #hb_ot_var_axis_flags_t flags for the axis + The mininum value on the variation axis that the font covers + The position on the variation axis corresponding to the font's defaults + The maximum value on the variation axis that the font covers @@ -7411,193 +8755,270 @@ the language tag results + Fetches the variation-axis information corresponding to the specified axis tag +in the specified face. + - use hb_ot_var_find_axis_info() instead + #hb_face_t to work upon + The #hb_tag_t of the variation axis to query + The index of the variation axis - + + The #hb_ot_var_axis_info_t of the axis tag queried + Fetches the variation-axis information corresponding to the specified axis tag +in the specified face. + true if data found, false otherwise + #hb_face_t to work upon + The #hb_tag_t of the variation axis to query - + + The #hb_ot_var_axis_info_t of the axis tag queried + Fetches a list of all variation axes in the specified face. The list returned will begin +at the offset provided. + use hb_ot_var_get_axis_infos() instead + #hb_face_t to work upon + offset of the first lookup to retrieve - + + Input = the maximum number of variation axes to return; + Output = the actual number of variation axes returned (may be zero) - - + + The array of variation axes found + + + + Fetches the number of OpenType variation axes included in the face. + the number of variation axes defined + The #hb_face_t to work on + Fetches a list of all variation axes in the specified face. The list returned will begin +at the offset provided. + the number of variation axes in the face + #hb_face_t to work upon + offset of the first lookup to retrieve - + + Input = the maximum number of variation axes to return; + Output = the actual number of variation axes returned (may be zero) - - + + The array of variation axes found + + + - + + Fetches the number of named instances included in the face. + the number of named instances defined + The #hb_face_t to work on - This function allows to verify the presence of OpenType variation data on the face. + Tests whether a face includes any OpenType variation data in the `fvar` table. - true if face has a `fvar' table and false otherwise + true if data found, false otherwise - #hb_face_t to test + The #hb_face_t to work on - + + Fetches the design-space coordinates corresponding to the given +named instance in the face. + the number of variation axes in the face + The #hb_face_t to work on + The index of the named instance to query - + + Input = the maximum number of coordinates to return; + Output = the actual number of coordinates returned (may be zero) - - + + The array of coordinates found for the query + + + - + + Fetches the `name` table Name ID that provides display names for +the "PostScript name" defined for the given named instance in the face. + the Name ID found for the PostScript name + The #hb_face_t to work on + The index of the named instance to query - + + Fetches the `name` table Name ID that provides display names for +the "Subfamily name" defined for the given named instance in the face. + the Name ID found for the Subfamily name + The #hb_face_t to work on + The index of the named instance to query + Normalizes the given design-space coordinates. The minimum and maximum +values for the axis are mapped to the interval [-1,1], with the default +axis value mapped to 0. + +Any additional scaling defined in the face's `avar` table is also +applied, as described at https://docs.microsoft.com/en-us/typography/opentype/spec/avar + The #hb_face_t to work on + The length of the coordinate array + The design-space coordinates to normalize - + + The normalized coordinates + Normalizes all of the coordinates in the given list of variation axes. + The #hb_face_t to work on + The array of variations to normalize + The number of variations to normalize - - + + The array of normalized coordinates + + + - + + The length of the coordinate array @@ -7654,21 +9075,186 @@ hb_script_from_iso15924_tag(). + Fetches the #hb_direction_t of a script when it is +set horizontally. All right-to-left scripts will return +#HB_DIRECTION_RTL. All left-to-right scripts will return +#HB_DIRECTION_LTR. Scripts that can be written either +horizontally or vertically will return #HB_DIRECTION_INVALID. +Unknown scripts will return #HB_DIRECTION_LTR. + The horizontal #hb_direction_t of @script + The #hb_script_t to query + Data type for scripts. Each #hb_script_t's value is an #hb_tag_t corresponding +to the four-letter values defined by [ISO 15924](https://unicode.org/iso15924/). + +See also the Script (sc) property of the Unicode Character Database. + HB_TAG ('Z','y','y','y') + HB_TAG ('Z','i','n','h') + HB_TAG ('Z','z','z','z') +@HB_SCRIPT_ARABIC +@HB_SCRIPT_ARMENIAN +@HB_SCRIPT_BENGALI +@HB_SCRIPT_CYRILLIC +@HB_SCRIPT_DEVANAGARI +@HB_SCRIPT_GEORGIAN +@HB_SCRIPT_GREEK +@HB_SCRIPT_GUJARATI +@HB_SCRIPT_GURMUKHI +@HB_SCRIPT_HANGUL +@HB_SCRIPT_HAN +@HB_SCRIPT_HEBREW +@HB_SCRIPT_HIRAGANA +@HB_SCRIPT_KANNADA +@HB_SCRIPT_KATAKANA +@HB_SCRIPT_LAO +@HB_SCRIPT_LATIN +@HB_SCRIPT_MALAYALAM +@HB_SCRIPT_ORIYA +@HB_SCRIPT_TAMIL +@HB_SCRIPT_TELUGU +@HB_SCRIPT_THAI +@HB_SCRIPT_TIBETAN +@HB_SCRIPT_BOPOMOFO +@HB_SCRIPT_BRAILLE +@HB_SCRIPT_CANADIAN_SYLLABICS +@HB_SCRIPT_CHEROKEE +@HB_SCRIPT_ETHIOPIC +@HB_SCRIPT_KHMER +@HB_SCRIPT_MONGOLIAN +@HB_SCRIPT_MYANMAR +@HB_SCRIPT_OGHAM +@HB_SCRIPT_RUNIC +@HB_SCRIPT_SINHALA +@HB_SCRIPT_SYRIAC +@HB_SCRIPT_THAANA +@HB_SCRIPT_YI +@HB_SCRIPT_DESERET +@HB_SCRIPT_GOTHIC +@HB_SCRIPT_OLD_ITALIC +@HB_SCRIPT_BUHID +@HB_SCRIPT_HANUNOO +@HB_SCRIPT_TAGALOG +@HB_SCRIPT_TAGBANWA +@HB_SCRIPT_CYPRIOT +@HB_SCRIPT_LIMBU +@HB_SCRIPT_LINEAR_B +@HB_SCRIPT_OSMANYA +@HB_SCRIPT_SHAVIAN +@HB_SCRIPT_TAI_LE +@HB_SCRIPT_UGARITIC +@HB_SCRIPT_BUGINESE +@HB_SCRIPT_COPTIC +@HB_SCRIPT_GLAGOLITIC +@HB_SCRIPT_KHAROSHTHI +@HB_SCRIPT_NEW_TAI_LUE +@HB_SCRIPT_OLD_PERSIAN +@HB_SCRIPT_SYLOTI_NAGRI +@HB_SCRIPT_TIFINAGH +@HB_SCRIPT_BALINESE +@HB_SCRIPT_CUNEIFORM +@HB_SCRIPT_NKO +@HB_SCRIPT_PHAGS_PA +@HB_SCRIPT_PHOENICIAN +@HB_SCRIPT_CARIAN +@HB_SCRIPT_CHAM +@HB_SCRIPT_KAYAH_LI +@HB_SCRIPT_LEPCHA +@HB_SCRIPT_LYCIAN +@HB_SCRIPT_LYDIAN +@HB_SCRIPT_OL_CHIKI +@HB_SCRIPT_REJANG +@HB_SCRIPT_SAURASHTRA +@HB_SCRIPT_SUNDANESE +@HB_SCRIPT_VAI +@HB_SCRIPT_AVESTAN +@HB_SCRIPT_BAMUM +@HB_SCRIPT_EGYPTIAN_HIEROGLYPHS +@HB_SCRIPT_IMPERIAL_ARAMAIC +@HB_SCRIPT_INSCRIPTIONAL_PAHLAVI +@HB_SCRIPT_INSCRIPTIONAL_PARTHIAN +@HB_SCRIPT_JAVANESE +@HB_SCRIPT_KAITHI +@HB_SCRIPT_LISU +@HB_SCRIPT_MEETEI_MAYEK +@HB_SCRIPT_OLD_SOUTH_ARABIAN +@HB_SCRIPT_OLD_TURKIC +@HB_SCRIPT_SAMARITAN +@HB_SCRIPT_TAI_THAM +@HB_SCRIPT_TAI_VIET +@HB_SCRIPT_BATAK +@HB_SCRIPT_BRAHMI +@HB_SCRIPT_MANDAIC +@HB_SCRIPT_CHAKMA +@HB_SCRIPT_MEROITIC_CURSIVE +@HB_SCRIPT_MEROITIC_HIEROGLYPHS +@HB_SCRIPT_MIAO +@HB_SCRIPT_SHARADA +@HB_SCRIPT_SORA_SOMPENG +@HB_SCRIPT_TAKRI +@HB_SCRIPT_BASSA_VAH +@HB_SCRIPT_CAUCASIAN_ALBANIAN +@HB_SCRIPT_DUPLOYAN +@HB_SCRIPT_ELBASAN +@HB_SCRIPT_GRANTHA +@HB_SCRIPT_KHOJKI +@HB_SCRIPT_KHUDAWADI +@HB_SCRIPT_LINEAR_A +@HB_SCRIPT_MAHAJANI +@HB_SCRIPT_MANICHAEAN +@HB_SCRIPT_MENDE_KIKAKUI +@HB_SCRIPT_MODI +@HB_SCRIPT_MRO +@HB_SCRIPT_NABATAEAN +@HB_SCRIPT_OLD_NORTH_ARABIAN +@HB_SCRIPT_OLD_PERMIC +@HB_SCRIPT_PAHAWH_HMONG +@HB_SCRIPT_PALMYRENE +@HB_SCRIPT_PAU_CIN_HAU +@HB_SCRIPT_PSALTER_PAHLAVI +@HB_SCRIPT_SIDDHAM +@HB_SCRIPT_TIRHUTA +@HB_SCRIPT_WARANG_CITI +@HB_SCRIPT_AHOM +@HB_SCRIPT_ANATOLIAN_HIEROGLYPHS +@HB_SCRIPT_HATRAN +@HB_SCRIPT_MULTANI +@HB_SCRIPT_OLD_HUNGARIAN +@HB_SCRIPT_SIGNWRITING +@HB_SCRIPT_ADLAM +@HB_SCRIPT_BHAIKSUKI +@HB_SCRIPT_MARCHEN +@HB_SCRIPT_OSAGE +@HB_SCRIPT_TANGUT +@HB_SCRIPT_NEWA +@HB_SCRIPT_MASARAM_GONDI +@HB_SCRIPT_NUSHU +@HB_SCRIPT_SOYOMBO +@HB_SCRIPT_ZANABAZAR_SQUARE +@HB_SCRIPT_DOGRA +@HB_SCRIPT_GUNJALA_GONDI +@HB_SCRIPT_HANIFI_ROHINGYA +@HB_SCRIPT_MAKASAR +@HB_SCRIPT_MEDEFAIDRIN +@HB_SCRIPT_OLD_SOGDIAN +@HB_SCRIPT_SOGDIAN +@HB_SCRIPT_ELYMAIC +@HB_SCRIPT_NANDINAGARI +@HB_SCRIPT_NYIAKENG_PUACHUE_HMONG +@HB_SCRIPT_WANCHO @@ -7979,10 +9565,11 @@ hb_script_from_iso15924_tag(). + #HB_TAG_NONE - See hb_script_from_iso15924_tag(). + Converts an #hb_script_t to a corresponding ISO 15924 script tag. An #hb_tag_t representing an ISO 15924 script tag. @@ -7997,7 +9584,7 @@ hb_script_from_iso15924_tag(). Checks the equality of two #hb_segment_properties_t's. - %true if all properties of @a equal those of @b, false otherwise. + %true if all properties of @a equal those of @b, %false otherwise. @@ -8048,204 +9635,238 @@ hb_buffer_get_segment_properties(), respectively. + Adds @codepoint to @set. - a set. + A set + The element to add to @set + Adds all of the elements from @first to @last +(inclusive) to @set. - a set. + A set + The first element to add to @set + The final element to add to @set + Tests whether memory allocation for a set was successful. + %true if allocation succeeded, false otherwise - a set. + A set + Clears out the contents of a set. - a set. + A set + Creates a new, initially empty set. + The new #hb_set_t + Removes @codepoint from @set. - a set. + A set + Removes @codepoint from @set + Removes all of the elements from @first to @last +(inclusive) from @set. - a set. + A set + The first element to remove from @set + The final element to remove from @set + Decreases the reference count on a set. When +the reference count reaches zero, the set is +destroyed, freeing all memory. - a set. + A set + Fetches the singleton empty #hb_set_t. + The empty #hb_set_t - Finds the maximum number in the set. + Finds the largest element in the set. - minimum of the set, or %HB_SET_VALUE_INVALID if set is empty. + maximum of @set, or %HB_SET_VALUE_INVALID if @set is empty. - a set. + A set - Finds the minimum number in the set. + Finds the smallest element in the set. - minimum of the set, or %HB_SET_VALUE_INVALID if set is empty. + minimum of @set, or %HB_SET_VALUE_INVALID if @set is empty. - a set. + A set - Returns the number of numbers in the set. + Returns the number of elements in the set. - set population. + The population of @set - a set. + A set + Fetches the user data associated with the specified key, +attached to the specified set. + A pointer to the user data - a set. + A set + The user-data key to query + Tests whether @codepoint belongs to @set. + %true if @codepoint is in @set, false otherwise - a set. + A set + The element to query + Makes @set the intersection of @set and @other. - a set. + A set + Another set + Inverts the contents of @set. - a set. + A set + Tests whether a set is empty (contains no elements). + %true if @set is empty @@ -8256,210 +9877,239 @@ hb_buffer_get_segment_properties(), respectively. + Tests whether @set and @other are equal (contain the same +elements). %TRUE if the two sets are equal, %FALSE otherwise. - a set. + A set - other set. + Another set + Tests whether @set is a subset of @larger_set. %TRUE if the @set is a subset of (or equal to) @larger_set, %FALSE otherwise. - a set. + A set - other set. + Another set - Gets the next number in @set that is greater than current value of @codepoint. + Fetches the next element in @set that is greater than current value of @codepoint. Set @codepoint to %HB_SET_VALUE_INVALID to get started. - whether there was a next value. + %true if there was a next value, false otherwise - a set. + A set + Input = Code point to query + Output = Code point retrieved - Gets the next consecutive range of numbers in @set that + Fetches the next consecutive range of elements in @set that are greater than current value of @last. Set @last to %HB_SET_VALUE_INVALID to get started. - whether there was a next range. + %true if there was a next range, false otherwise - a set. + A set - output first codepoint in the range. + The first code point in the range - input current last and output last codepoint in the range. + Input = The current last code point in the range + Output = The last code point in the range - Gets the previous number in @set that is lower than current value of @codepoint. + Fetches the previous element in @set that is lower than current value of @codepoint. Set @codepoint to %HB_SET_VALUE_INVALID to get started. - whether there was a previous value. + %true if there was a previous value, false otherwise - a set. + A set + Input = Code point to query + Output = Code point retrieved - Gets the previous consecutive range of numbers in @set that -are less than current value of @first. + Fetches the previous consecutive range of elements in @set that +are greater than current value of @last. Set @first to %HB_SET_VALUE_INVALID to get started. - whether there was a previous range. + %true if there was a previous range, false otherwise - a set. + A set - input current first and output first codepoint in the range. + Input = The current first code point in the range + Output = The first code point in the range - output last codepoint in the range. + The last code point in the range + Increases the reference count on a set. + The set - a set. + A set + Makes the contents of @set equal to the contents of @other. - a set. + A set + Another set + Attaches a user-data key/data pair to the specified set. + %true if success, %false otherwise - a set. + A set + The user-data key to set + A pointer to the user data to set + A callback to call when @data is not needed anymore + Whether to replace an existing data with the same key + Subtracts the contents of @other from @set. - a set. + A set + Another set + Makes @set the symmetric difference of @set +and @other. - a set. + A set + Another set - + Data type for holding a set of integers. #hb_set_t's are +used to gather and contain glyph IDs, Unicode code +points, and various other collections of discrete +values. + Makes @set the union of @set and @other. - a set. + A set + Another set @@ -8543,242 +10193,334 @@ will be used. + Constructs a shaping plan for a combination of @face, @user_features, @props, +and @shaper_list. + The shaping plan + #hb_face_t to use + The #hb_segment_properties_t of the segment + The list of user-selected features + The number of user-selected features + List of shapers to try - + + The variable-font version of #hb_shape_plan_create. +Constructs a shaping plan for a combination of @face, @user_features, @props, +and @shaper_list, plus the variation-space coordinates @coords. + The shaping plan + #hb_face_t to use + The #hb_segment_properties_t of the segment - + The list of user-selected features + + + + The number of user-selected features - + The list of variation-space coordinates + + + + The number of variation-space coordinates - + List of shapers to try + + + + Creates a cached shaping plan suitable for reuse, for a combination +of @face, @user_features, @props, and @shaper_list. + The shaping plan + #hb_face_t to use + The #hb_segment_properties_t of the segment + The list of user-selected features + The number of user-selected features + List of shapers to try - + + The variable-font version of #hb_shape_plan_create_cached. +Creates a cached shaping plan suitable for reuse, for a combination +of @face, @user_features, @props, and @shaper_list, plus the +variation-space coordinates @coords. + The shaping plan + #hb_face_t to use + The #hb_segment_properties_t of the segment - + The list of user-selected features + + + + The number of user-selected features - + The list of variation-space coordinates + + + + The number of variation-space coordinates - + List of shapers to try + + + + Decreases the reference count on the given shaping plan. When the +reference count reaches zero, the shaping plan is destroyed, +freeing all memory. - a shape plan. + A shaping plan + Executes the given shaping plan on the specified buffer, using +the given @font and @features. - a shape plan. + A shaping plan - a font. + The #hb_font_t to use - a buffer. + The #hb_buffer_t to work upon + Features to enable + The number of features to enable + Fetches the singleton empty shaping plan. + The empty shaping plan + Fetches the shaper from a given shaping plan. + The shaper - a shape plan. + A shaping plan + Fetches the user data associated with the specified key, +attached to the specified shaping plan. + A pointer to the user data - a shape plan. + A shaping plan + The user-data key to query + Increases the reference count on the given shaping plan. + @shape_plan - a shape plan. + A shaping plan + Attaches a user-data key/data pair to the given shaping plan. - a shape plan. + A shaping plan + The user-data key to set + A pointer to the user data + A callback to call when @data is not needed anymore + Whether to replace an existing data with the same key - + Data type for holding a shaping plan. + +Shape plans contain information about how HarfBuzz will shape a +particular text segment, based on the segment's properties and the +capabilities in the font face in use. + +Shape plans can be queried about how shaping will perform, given a set +of specific input parameters (script, language, direction, features, +etc.). + Converts a string into an #hb_tag_t. Valid tags +are four characters. Shorter input strings will be +padded with spaces. Longer input strings will be +truncated. + The #hb_tag_t corresponding to @str + String to convert + Length of @str, or -1 if it is %NULL-terminated + Converts an #hb_tag_t to a string and returns it in @buf. +Strings will be four characters long. + #hb_tag_t to convert + Converted string @@ -8786,225 +10528,330 @@ will be used. + Retrieves the Canonical Combining Class (ccc) property +of code point @unicode. + The #hb_unicode_combining_class_t of @unicode + The Unicode-functions structure + The code point to query + A virtual method for the #hb_unicode_funcs_t structure. + +This method should retrieve the Canonical Combining Class (ccc) +property for a specified Unicode code point. + The #hb_unicode_combining_class_t of @unicode + A Unicode-functions structure + The code point to query + User data pointer passed by the caller + Data type for the Canonical_Combining_Class (ccc) property +from the Unicode Character Database. + +<note>Note: newer versions of Unicode may add new values. +Client programs should be ready to handle any value in the 0..254 range +being returned from hb_unicode_combining_class().</note> + Spacing and enclosing marks; also many vowel and consonant signs, even if nonspacing + Marks which overlay a base letter or symbol + Diacritic nukta marks in Brahmi-derived scripts + Hiragana/Katakana voicing marks + Viramas + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Hebrew] + [Arabic] + [Arabic] + [Arabic] + [Arabic] + [Arabic] + [Arabic] + [Arabic] + [Arabic] + [Arabic] + [Syriac] + [Telugu] + [Telugu] + [Thai] + [Thai] + [Lao] + [Lao] + [Tibetan] + [Tibetan] + [Tibetan] + Marks attached at the bottom left + Marks attached directly below + Marks attached directly above + Marks attached at the top right + Distinct marks at the bottom left + Distinct marks directly below + Distinct marks at the bottom right + Distinct marks to the left + Distinct marks to the right + Distinct marks at the top left + Distinct marks directly above + Distinct marks at the top right + Distinct marks subtending two bases + Distinct marks extending above two bases + Greek iota subscript only + Invalid combining class + Composes the code point sequence @a,@b by canonical equivalence into +code point @ab. + True is @a,@b composed, false otherwise - Unicode functions. + The Unicode-functions structure + The first code point to compose + The second code point to compose + The composed code point + A virtual method for the #hb_unicode_funcs_t structure. + +This method should compose a sequence of two input Unicode code +points by canonical equivalence, returning the composed code +point in a #hb_codepoint_t output parameter (if successful). +The method must return an #hb_bool_t indicating the success +of the composition. + True is @a,@b composed, false otherwise + A Unicode-functions structure + The first code point to compose + The second code point to compose - + + The composed code point + user data pointer passed by the caller + Decomposes code point @ab by canonical equivalence, into code points +@a and @b. + True if @ab decomposed, false otherwise - Unicode functions. + The Unicode-functions structure + The code point to decompose + The first decomposed code point + The second decomposed code point + Fetches the compatibility decomposition of a Unicode +code point. Deprecated. - Unicode functions. + The Unicode-functions structure + Code point to decompose + Compatibility decomposition of @u @@ -9042,23 +10889,35 @@ of this function type must ensure that they do not write past the provided array + A virtual method for the #hb_unicode_funcs_t structure. + +This method should decompose an input Unicode code point, +returning the two decomposed code points in #hb_codepoint_t +output parameters (if successful). The method must return an +#hb_bool_t indicating the success of the composition. + True if @ab decomposed, false otherwise + A Unicode-functions structure + The code point to decompose - + + The first decomposed code point - + + The second decomposed code point + user data pointer passed by the caller @@ -9093,130 +10952,163 @@ of this function type must ensure that they do not write past the provided array + Creates a new #hb_unicode_funcs_t structure of Unicode functions. + The Unicode-functions structure + Parent Unicode-functions structure + Decreases the reference count on a Unicode-functions structure. When +the reference count reaches zero, the Unicode-functions structure is +destroyed, freeing all memory. - Unicode functions. + The Unicode-functions structure - - + + Fetches a pointer to the default Unicode-functions structure that is used +when no functions are explicitly set on #hb_buffer_t. + + a pointer to the #hb_unicode_funcs_t Unicode-functions structure + Fetches the singleton empty Unicode-functions structure. + The empty Unicode-functions structure + Fetches the parent of the Unicode-functions structure +@ufuncs. + The parent Unicode-functions structure - Unicode functions. + The Unicode-functions structure + Fetches the user-data associated with the specified key, +attached to the specified Unicode-functions structure. + A pointer to the user data - Unicode functions. + The Unicode-functions structure + The user-data key to query + Tests whether the specified Unicode-functions structure +is immutable. + %true if @ufuncs is immutable, false otherwise - Unicode functions. + The Unicode-functions structure + Makes the specified Unicode-functions structure +immutable. - Unicode functions. + The Unicode-functions structure + Increases the reference count on a Unicode-functions structure. + The Unicode-functions structure - Unicode functions. + The Unicode-functions structure + Sets the implementation function for #hb_unicode_combining_class_func_t. - a Unicode function structure + A Unicode-functions structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_unicode_compose_func_t. - a Unicode function structure + A Unicode-functions structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore @@ -9242,21 +11134,25 @@ of this function type must ensure that they do not write past the provided array + Sets the implementation function for #hb_unicode_decompose_func_t. - a Unicode function structure + A Unicode-functions structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore @@ -9282,241 +11178,342 @@ of this function type must ensure that they do not write past the provided array + Sets the implementation function for #hb_unicode_general_category_func_t. - a Unicode function structure + A Unicode-functions structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_unicode_mirroring_func_t. - a Unicode function structure + A Unicode-functions structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Sets the implementation function for #hb_unicode_script_func_t. - a Unicode function structure + A Unicode-functions structure + The callback function to assign + Data to pass to @func + The function to call when @user_data is not needed anymore + Attaches a user-data key/data pair to the specified Unicode-functions structure. + %true if success, %false otherwise - Unicode functions. + The Unicode-functions structure + The user-data key + A pointer to the user data + A callback to call when @data is not needed anymore + Whether to replace an existing data with the same key - + Data type containing a set of virtual methods used for +accessing various Unicode character properties. + +HarfBuzz provides a default function for each of the +methods in #hb_unicode_funcs_t. Client programs can implement +their own replacements for the individual Unicode functions, as +needed, and replace the default by calling the setter for a +method. + Retrieves the General Category (gc) property +of code point @unicode. + The #hb_unicode_general_category_t of @unicode + The Unicode-functions structure + The code point to query + A virtual method for the #hb_unicode_funcs_t structure. + +This method should retrieve the General Category property for +a specified Unicode code point. + The #hb_unicode_general_category_t of @unicode + A Unicode-functions structure + The code point to query + User data pointer passed by the caller + Data type for the "General_Category" (gc) property from +the Unicode Character Database. + [Cc] + [Cf] + [Cn] + [Co] + [Cs] + [Ll] + [Lm] + [Lo] + [Lt] + [Lu] + [Mc] + [Me] + [Mn] + [Nd] + [Nl] + [No] + [Pc] + [Pd] + [Pe] + [Pf] + [Pi] + [Po] + [Ps] + [Sc] + [Sk] + [Sm] + [So] + [Zl] + [Zp] + [Zs] + Retrieves the Bi-directional Mirroring Glyph code +point defined for code point @unicode. + The #hb_codepoint_t of the Mirroring Glyph for @unicode + The Unicode-functions structure + The code point to query + A virtual method for the #hb_unicode_funcs_t structure. + +This method should retrieve the Bi-Directional Mirroring Glyph +code point for a specified Unicode code point. + +<note>Note: If a code point does not have a specified +Bi-Directional Mirroring Glyph defined, the method should +return the original code point.</note> + The #hb_codepoint_t of the Mirroring Glyph for @unicode + A Unicode-functions structure + The code point to query + User data pointer passed by the caller + Retrieves the #hb_script_t script to which code +point @unicode belongs. + The #hb_script_t of @unicode + The Unicode-functions structure + The code point to query + A virtual method for the #hb_unicode_funcs_t structure. + +This method should retrieve the Script property for a +specified Unicode code point. + The #hb_script_t of @unicode + A Unicode-functions structure + The code point to query + User data pointer passed by the caller + Data structure for holding user-data keys. @@ -9566,10 +11563,15 @@ of this function type must ensure that they do not write past the provided array + Data type for holding variation data. Registered OpenType +variation-axis tags are listed at +https://docs.microsoft.com/en-us/typography/opentype/spec/dvaraxisreg + The #hb_tag_t tag of the variation-axis name + The value of the variation axis @@ -9612,31 +11614,38 @@ of this function type must ensure that they do not write past the provided array - Library major version component. + Library major version component - Library minor version component. + Library minor version component - Library micro version component. + Library micro version component + Tests the library version against a minimum value, +as three integer components. + True if the library is equal to or greater than +the test value, false otherwise + Library major version component + Library minor version component + Library micro version component @@ -9644,7 +11653,7 @@ of this function type must ensure that they do not write past the provided array Returns library version as a string with three components. - library version string. + Library version string diff --git a/Pango-1.0.gir b/Pango-1.0.gir index 22a42a6..c3c775a 100644 --- a/Pango-1.0.gir +++ b/Pango-1.0.gir @@ -10,12 +10,14 @@ and/or use gtk-doc annotations. --> - A #PangoGlyph represents a single glyph in the output form of a string. + A `PangoGlyph` represents a single glyph in the output form of a string. - The #PangoGlyphUnit type is used to store dimensions within -Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit. + The `PangoGlyphUnit` type is used to store dimensions within +Pango. + +Dimensions are stored in 1/%PANGO_SCALE of a device unit. (A device unit might be a pixel for screen display, or a point on a printer.) %PANGO_SCALE is currently 1024, and may change in the future (unlikely though), but you should not @@ -24,47 +26,55 @@ to convert from glyph units into device units with correct rounding. - The #PangoLayoutRun structure represents a single run within -a #PangoLayoutLine; it is simply an alternate name for -#PangoGlyphItem. -See the #PangoGlyphItem docs for details on the fields. + A `PangoLayoutRun` represents a single run within a `PangoLayoutLine`. + +It is simply an alternate name for [struct@Pango.GlyphItem]. +See the [struct@Pango.GlyphItem] docs for details on the fields. Whether the segment should be shifted to center around the baseline. -Used in vertical writing directions mostly. + +This is mainly used in vertical writing directions. - This flag is used to mark runs that hold ellipsized text, -in an ellipsized layout. + Whether this run holds ellipsized text. - This flag tells Pango to add a hyphen at the end of the -run during shaping. + Whether to add a hyphen at the end of the run during shaping. - Extracts the <firstterm>ascent</firstterm> from a #PangoRectangle -representing glyph extents. The ascent is the distance from the -baseline to the highest point of the character. This is positive if the + Extracts the *ascent* from a `PangoRectangle` +representing glyph extents. + +The ascent is the distance from the baseline to the +highest point of the character. This is positive if the glyph ascends above the baseline. - a #PangoRectangle + a `PangoRectangle` - This value can be used to set the start_index member of a #PangoAttribute -such that the attribute covers from the beginning of the text. - + Value for @start_index in `PangoAttribute` that indicates +the beginning of the text. + + + + Value for @end_index in `PangoAttribute` that indicates +the end of the text. + - A #PangoAlignment describes how to align the lines of a #PangoLayout within the -available space. If the #PangoLayout is set to justify -using pango_layout_set_justify(), this only has effect for partial lines. + `PangoAlignment` describes how to align the lines of a `PangoLayout` +within the available space. + +If the `PangoLayout` is set to justify using [method@Pango.Layout.set_justify], +this only has effect for partial lines. Put all available space on the right @@ -76,15 +86,15 @@ using pango_layout_set_justify(), this only has effect for partial lines. - The #PangoAnalysis structure stores information about + The `PangoAnalysis` structure stores information about the properties of a segment of text. unused - + unused - + the font for this segment. @@ -95,7 +105,7 @@ the properties of a segment of text. - the glyph orientation for this segment (A #PangoGravity). + the glyph orientation for this segment (A `PangoGravity`). @@ -103,7 +113,7 @@ the properties of a segment of text. - the detected script for this segment (A #PangoScript) (Since: 1.18). + the detected script for this segment (A `PangoScript`) (Since: 1.18). @@ -118,10 +128,11 @@ the properties of a segment of text. - The #PangoAttrClass structure stores the type and operations for -a particular type of attribute. The functions in this structure should -not be called directly. Instead, one should use the wrapper functions -provided for #PangoAttribute. + The `PangoAttrClass` structure stores the type and operations for +a particular type of attribute. + +The functions in this structure should not be called directly. Instead, +one should use the wrapper functions provided for `PangoAttribute`. the type ID for this attribute @@ -167,14 +178,14 @@ provided for #PangoAttribute. - The #PangoAttrColor structure is used to represent attributes that + The `PangoAttrColor` structure is used to represent attributes that are colors. the common portion of the attribute - the #PangoColor which is the value of the attribute + the `PangoColor` which is the value of the attribute @@ -195,7 +206,7 @@ are colors. Type of a function filtering a list of attributes. %TRUE if the attribute should be selected for -filtering, %FALSE otherwise. + filtering, %FALSE otherwise. @@ -210,7 +221,7 @@ filtering, %FALSE otherwise. - The #PangoAttrFloat structure is used to represent attributes with + The `PangoAttrFloat` structure is used to represent attributes with a float or double value. the common portion of the attribute @@ -222,7 +233,7 @@ a float or double value. - The #PangoAttrFontDesc structure is used to store an attribute that + The `PangoAttrFontDesc` structure is used to store an attribute that sets all aspects of the font description at once. the common portion of the attribute @@ -233,12 +244,14 @@ sets all aspects of the font description at once. - Create a new font description attribute. This attribute -allows setting family, style, weight, variant, stretch, -and size simultaneously. + Create a new font description attribute. + +This attribute allows setting family, style, weight, variant, +stretch, and size simultaneously. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -250,7 +263,7 @@ and size simultaneously. - The #PangoAttrFontFeatures structure is used to represent OpenType + The `PangoAttrFontFeatures` structure is used to represent OpenType font features as an attribute. the common portion of the attribute @@ -261,22 +274,27 @@ font features as an attribute. - Create a new font features tag attribute. + Create a new font features tag attribute. + +You can use this attribute to select OpenType font features like small-caps, +alternative glyphs, ligatures, etc. for fonts that support them. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - a string with OpenType font features, in CSS syntax + a string with OpenType font features, with the syntax of the [CSS +font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc) - The #PangoAttrInt structure is used to represent attributes with + The `PangoAttrInt` structure is used to represent attributes with an integer or enumeration value. the common portion of the attribute @@ -288,58 +306,60 @@ an integer or enumeration value. - The #PangoAttrIterator structure is used to represent an -iterator through a #PangoAttrList. A new iterator is created -with pango_attr_list_get_iterator(). Once the iterator -is created, it can be advanced through the style changes -in the text using pango_attr_iterator_next(). At each -style change, the range of the current style segment and the -attributes currently in effect can be queried. + A `PangoAttrIterator` is used to iterate through a `PangoAttrList`. + +A new iterator is created with [method@Pango.AttrList.get_iterator]. +Once the iterator is created, it can be advanced through the style +changes in the text using [method@Pango.AttrIterator.next]. At each +style change, the range of the current style segment and the attributes +currently in effect can be queried. - Copy a #PangoAttrIterator + Copy a `PangoAttrIterator`. the newly allocated - #PangoAttrIterator, which should be freed with - pango_attr_iterator_destroy(). + `PangoAttrIterator`, which should be freed with + [method@Pango.AttrIterator.destroy] - a #PangoAttrIterator. + a `PangoAttrIterator` - Destroy a #PangoAttrIterator and free all associated memory. + Destroy a `PangoAttrIterator` and free all associated memory. - a #PangoAttrIterator. + a `PangoAttrIterator` - Find the current attribute of a particular type at the iterator -location. When multiple attributes of the same type overlap, -the attribute whose range starts closest to the current location -is used. + Find the current attribute of a particular type +at the iterator location. + +When multiple attributes of the same type overlap, +the attribute whose range starts closest to the +current location is used. - the current attribute of the given type, - or %NULL if no attribute of that type applies to the - current location. + the current + attribute of the given type, or %NULL if no attribute + of that type applies to the current location. - a #PangoAttrIterator + a `PangoAttrIterator` - the type of attribute to find. + the type of attribute to find @@ -348,52 +368,54 @@ is used. Gets a list of all attributes at the current position of the iterator. - a list of - all attributes for the current range. - To free this value, call pango_attribute_destroy() on - each value and g_slist_free() on the list. + + a list of all attributes for the current range. To free + this value, call [method@Pango.Attribute.destroy] on each + value and g_slist_free() on the list. - a #PangoAttrIterator + a `PangoAttrIterator` - Get the font and other attributes at the current iterator position. + Get the font and other attributes at the current +iterator position. - a #PangoAttrIterator + a `PangoAttrIterator` - a #PangoFontDescription to fill in with the current values. - The family name in this structure will be set using - pango_font_description_set_family_static() using values from - an attribute in the #PangoAttrList associated with the iterator, - so if you plan to keep it around, you must call: - <literal>pango_font_description_set_family (desc, pango_font_description_get_family (desc))</literal>. + a `PangoFontDescription` to fill in with the current + values. The family name in this structure will be set using + [method@Pango.FontDescription.set_family_static] using + values from an attribute in the `PangoAttrList` associated + with the iterator, so if you plan to keep it around, you + must call: + `pango_font_description_set_family (desc, pango_font_description_get_family (desc))`. - - if non-%NULL, location to store language tag for item, or %NULL - if none is found. + + location to store language tag + for item, or %NULL if none is found. - - if non-%NULL, - location in which to store a list of non-font - attributes at the the current position; only the highest priority - value of each attribute will be added to this list. In order - to free this value, you must call pango_attribute_destroy() on - each member. + + + location in which to store a list of non-font attributes + at the the current position; only the highest priority + value of each attribute will be added to this list. In + order to free this value, you must call + [method@Pango.Attribute.destroy] on each member. @@ -403,20 +425,22 @@ iterator. Advance the iterator until the next change of style. - %FALSE if the iterator is at the end of the list, otherwise %TRUE + %FALSE if the iterator is at the end + of the list, otherwise %TRUE - a #PangoAttrIterator + a `PangoAttrIterator` - Get the range of the current segment. Note that the -stored return values are signed, not unsigned like -the values in #PangoAttribute. To deal with this API + Get the range of the current segment. + +Note that the stored return values are signed, not unsigned +like the values in `PangoAttribute`. To deal with this API oversight, stored return values that wouldn't fit into a signed integer are clamped to %G_MAXINT. @@ -424,7 +448,7 @@ a signed integer are clamped to %G_MAXINT. - a #PangoAttrIterator + a PangoAttrIterator @@ -439,21 +463,22 @@ a signed integer are clamped to %G_MAXINT. - The #PangoAttrLanguage structure is used to represent attributes that + The `PangoAttrLanguage` structure is used to represent attributes that are languages. the common portion of the attribute - the #PangoLanguage which is the value of the attribute + the `PangoLanguage` which is the value of the attribute Create a new language tag attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -465,45 +490,50 @@ are languages. - The #PangoAttrList structure represents a list of attributes -that apply to a section of text. The attributes are, in general, -allowed to overlap in an arbitrary fashion, however, if the -attributes are manipulated only through pango_attr_list_change(), -the overlap between properties will meet stricter criteria. + A `PangoAttrList` represents a list of attributes that apply to a section +of text. -Since the #PangoAttrList structure is stored as a linear list, -it is not suitable for storing attributes for large amounts -of text. In general, you should not use a single #PangoAttrList -for more than one paragraph of text. +The attributes in a `PangoAttrList` are, in general, allowed to overlap in +an arbitrary fashion. However, if the attributes are manipulated only through +[method@Pango.AttrList.change], the overlap between properties will meet +stricter criteria. + +Since the `PangoAttrList` structure is stored as a linear list, it is not +suitable for storing attributes for large amounts of text. In general, you +should not use a single `PangoAttrList` for more than one paragraph of text. - Create a new empty attribute list with a reference count of one. + Create a new empty attribute list with a reference +count of one. - the newly allocated #PangoAttrList, - which should be freed with pango_attr_list_unref(). + the newly allocated + `PangoAttrList`, which should be freed with + [method@Pango.AttrList.unref] - Insert the given attribute into the #PangoAttrList. It will -replace any attributes of the same type on that segment -and be merged with any adjoining attributes that are identical. + Insert the given attribute into the `PangoAttrList`. -This function is slower than pango_attr_list_insert() for -creating an attribute list in order (potentially much slower -for large lists). However, pango_attr_list_insert() is not -suitable for continually changing a set of attributes -since it never removes or combines existing attributes. +It will replace any attributes of the same type +on that segment and be merged with any adjoining +attributes that are identical. + +This function is slower than [method@Pango.AttrList.insert] +for creating an attribute list in order (potentially +much slower for large lists). However, +[method@Pango.AttrList.insert] is not suitable for +continually changing a set of attributes since it +never removes or combines existing attributes. - a #PangoAttrList + a `PangoAttrList` - the attribute to insert. Ownership of this - value is assumed by the list. + the attribute to insert @@ -511,55 +541,60 @@ since it never removes or combines existing attributes. Copy @list and return an identical new list. - the newly allocated #PangoAttrList, with a - reference count of one, which should - be freed with pango_attr_list_unref(). - Returns %NULL if @list was %NULL. + the newly allocated + `PangoAttrList`, with a reference count of one, + which should be freed with [method@Pango.AttrList.unref]. + Returns %NULL if @list was %NULL. - a #PangoAttrList, may be %NULL + a `PangoAttrList` - Checks whether @list and @other_list contain the same attributes and -whether those attributes apply to the same ranges. Beware that this -will return wrong values if any list contains duplicates. + Checks whether @list and @other_list contain the same +attributes and whether those attributes apply to the +same ranges. + +Beware that this will return wrong values if any list +contains duplicates. - %TRUE if the lists are equal, %FALSE if they aren't. + %TRUE if the lists are equal, %FALSE if + they aren't - a #PangoAttrList + a `PangoAttrList` - the other #PangoAttrList + the other `PangoAttrList` - Given a #PangoAttrList and callback function, removes any elements -of @list for which @func returns %TRUE and inserts them into -a new list. + Given a `PangoAttrList` and callback function, removes +any elements of @list for which @func returns %TRUE and +inserts them into a new list. - the new #PangoAttrList or - %NULL if no attributes of the given types were found. + the new + `PangoAttrList` or %NULL if no attributes of the + given types were found - a #PangoAttrList + a `PangoAttrList` - callback function; returns %TRUE - if an attribute should be filtered out. + callback function; + returns %TRUE if an attribute should be filtered out @@ -572,94 +607,99 @@ a new list. Gets a list of all attributes in @list. - a list of all attributes in @list. To free this value, call - pango_attribute_destroy() on each value and g_slist_free() - on the list. + a list of all attributes in @list. To free this value, + call [method@Pango.Attribute.destroy] on each value and + g_slist_free() on the list. - a #PangoAttrList + a `PangoAttrList` Create a iterator initialized to the beginning of the list. + @list must not be modified until this iterator is freed. - the newly allocated #PangoAttrIterator, which should - be freed with pango_attr_iterator_destroy(). + the newly allocated + `PangoAttrIterator`, which should be freed with + [method@Pango.AttrIterator.destroy] - a #PangoAttrList + a `PangoAttrList` - Insert the given attribute into the #PangoAttrList. It will -be inserted after all other attributes with a matching -@start_index. + Insert the given attribute into the `PangoAttrList`. + +It will be inserted after all other attributes with a +matching @start_index. - a #PangoAttrList + a `PangoAttrList` - the attribute to insert. Ownership of this - value is assumed by the list. + the attribute to insert - Insert the given attribute into the #PangoAttrList. It will -be inserted before all other attributes with a matching -@start_index. + Insert the given attribute into the `PangoAttrList`. + +It will be inserted before all other attributes with a +matching @start_index. - a #PangoAttrList + a `PangoAttrList` - the attribute to insert. Ownership of this - value is assumed by the list. + the attribute to insert - Increase the reference count of the given attribute list by one. + Increase the reference count of the given attribute +list by one. The attribute list passed in - a #PangoAttrList, may be %NULL + a `PangoAttrList` - This function opens up a hole in @list, fills it in with attributes from -the left, and then merges @other on top of the hole. + This function opens up a hole in @list, fills it +in with attributes from the left, and then merges +@other on top of the hole. This operation is equivalent to stretching every attribute that applies at position @pos in @list by an amount @len, -and then calling pango_attr_list_change() with a copy -of each attribute in @other in sequence (offset in position by @pos). +and then calling [method@Pango.AttrList.change] with a copy +of each attribute in @other in sequence (offset in position +by @pos). This operation proves useful for, for instance, inserting a pre-edit string in the middle of an edit buffer. @@ -668,11 +708,11 @@ a pre-edit string in the middle of an edit buffer. - a #PangoAttrList + a `PangoAttrList` - another #PangoAttrList + another `PangoAttrList` @@ -681,49 +721,49 @@ a pre-edit string in the middle of an edit buffer. the length of the spliced segment. (Note that this - must be specified since the attributes in @other - may only be present at some subsection of this range) + must be specified since the attributes in @other may only + be present at some subsection of this range) - Decrease the reference count of the given attribute list by one. -If the result is zero, free the attribute list and the attributes -it contains. + Decrease the reference count of the given attribute +list by one. + +If the result is zero, free the attribute list +and the attributes it contains. - a #PangoAttrList, may be %NULL + a `PangoAttrList` - Update indices of attributes in @list for -a change in the text they refer to. + Update indices of attributes in @list for a change in the +text they refer to. -The change that this function applies is -removing @remove bytes at position @pos -and inserting @add bytes instead. +The change that this function applies is removing @remove +bytes at position @pos and inserting @add bytes instead. -Attributes that fall entirely in the -(@pos, @pos + @remove) range are removed. +Attributes that fall entirely in the (@pos, @pos + @remove) +range are removed. -Attributes that start or end inside the -(@pos, @pos + @remove) range are shortened to -reflect the removal. +Attributes that start or end inside the (@pos, @pos + @remove) +range are shortened to reflect the removal. -Attributes start and end positions are updated -if they are behind @pos + @remove. +Attributes start and end positions are updated if they are +behind @pos + @remove. - a #PangoAttrList + a `PangoAttrList` @@ -742,7 +782,7 @@ if they are behind @pos + @remove. - The #PangoAttrShape structure is used to represent attributes which + The `PangoAttrShape` structure is used to represent attributes which impose shape restrictions. the common portion of the attribute @@ -757,7 +797,7 @@ impose shape restrictions. - user data set (see pango_attr_shape_new_with_data()) + user data set (see [func@Pango.AttrShape.new_with_data]) @@ -769,13 +809,16 @@ impose shape restrictions. - Create a new shape attribute. A shape is used to impose a -particular ink and logical rectangle on the result of shaping a -particular glyph. This might be used, for instance, for -embedding a picture or a widget inside a #PangoLayout. + Create a new shape attribute. + +A shape is used to impose a particular ink and logical +rectangle on the result of shaping a particular glyph. +This might be used, for instance, for embedding a picture +or a widget inside a `PangoLayout`. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -790,12 +833,15 @@ embedding a picture or a widget inside a #PangoLayout. - Like pango_attr_shape_new(), but a user data pointer is also -provided; this pointer can be accessed when later + Creates a new shape attribute. + +Like [func@Pango.AttrShape.new], but a user data pointer +is also provided; this pointer can be accessed when later rendering the glyph. - the newly allocated #PangoAttribute, which should be - freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -813,20 +859,20 @@ rendering the glyph. function to copy @data when the - attribute is copied. If %NULL, @data is simply - copied as a pointer. + attribute is copied. If %NULL, @data is simply copied + as a pointer function to free @data when the - attribute is freed, or %NULL + attribute is freed - The #PangoAttrSize structure is used to represent attributes which + The `PangoAttrSize` structure is used to represent attributes which set font size. the common portion of the attribute @@ -834,26 +880,27 @@ set font size. size of font, in units of 1/%PANGO_SCALE of a point (for -%PANGO_ATTR_SIZE) or of a device uni (for %PANGO_ATTR_ABSOLUTE_SIZE) + %PANGO_ATTR_SIZE) or of a device unit (for %PANGO_ATTR_ABSOLUTE_SIZE) whether the font size is in device units or points. -This field is only present for compatibility with Pango-1.8.0 -(%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will -be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE. + This field is only present for compatibility with Pango-1.8.0 + (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will + be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE. Create a new font-size attribute in fractional points. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - the font size, in %PANGO_SCALEths of a point. + the font size, in %PANGO_SCALE-ths of a point @@ -861,20 +908,21 @@ be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE. Create a new font-size attribute in device units. - the newly allocated #PangoAttribute, which should be - freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - the font size, in %PANGO_SCALEths of a device unit. + the font size, in %PANGO_SCALE-ths of a device unit - The #PangoAttrString structure is used to represent attributes with + The `PangoAttrString` structure is used to represent attributes with a string value. the common portion of the attribute @@ -886,114 +934,119 @@ a string value. - The #PangoAttrType -distinguishes between different types of attributes. Along with the -predefined values, it is possible to allocate additional values -for custom attributes using pango_attr_type_register(). The predefined -values are given below. The type of structure used to store the -attribute is listed in parentheses after the description. + The `PangoAttrType` distinguishes between different types of attributes. + +Along with the predefined values, it is possible to allocate additional +values for custom attributes using [func@AttrType.register]. The predefined +values are given below. The type of structure used to store the attribute is +listed in parentheses after the description. does not happen - language (#PangoAttrLanguage) + language ([struct@Pango.AttrLanguage]) - font family name list (#PangoAttrString) + font family name list ([struct@Pango.AttrString]) - font slant style (#PangoAttrInt) + font slant style ([struct@Pango.AttrInt]) - font weight (#PangoAttrInt) + font weight ([struct@Pango.AttrInt]) - font variant (normal or small caps) (#PangoAttrInt) + font variant (normal or small caps) ([struct@Pango.AttrInt]) - font stretch (#PangoAttrInt) + font stretch ([struct@Pango.AttrInt]) - font size in points scaled by %PANGO_SCALE (#PangoAttrInt) + font size in points scaled by %PANGO_SCALE ([struct@Pango.AttrInt]) - font description (#PangoAttrFontDesc) + font description ([struct@Pango.AttrFontDesc]) - foreground color (#PangoAttrColor) + foreground color ([struct@Pango.AttrColor]) - background color (#PangoAttrColor) + background color ([struct@Pango.AttrColor]) - whether the text has an underline (#PangoAttrInt) + whether the text has an underline ([struct@Pango.AttrInt]) - whether the text is struck-through (#PangoAttrInt) + whether the text is struck-through ([struct@Pango.AttrInt]) - baseline displacement (#PangoAttrInt) + baseline displacement ([struct@Pango.AttrInt]) - shape (#PangoAttrShape) + shape ([struct@Pango.AttrShape]) - font size scale factor (#PangoAttrFloat) + font size scale factor ([struct@Pango.AttrFloat]) - whether fallback is enabled (#PangoAttrInt) + whether fallback is enabled ([struct@Pango.AttrInt]) - letter spacing (#PangoAttrInt) + letter spacing ([struct@PangoAttrInt]) - underline color (#PangoAttrColor) + underline color ([struct@Pango.AttrColor]) - strikethrough color (#PangoAttrColor) + strikethrough color ([struct@Pango.AttrColor]) - font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt) + font size in pixels scaled by %PANGO_SCALE ([struct@Pango.AttrInt]) - base text gravity (#PangoAttrInt) + base text gravity ([struct@Pango.AttrInt]) - gravity hint (#PangoAttrInt) + gravity hint ([struct@Pango.AttrInt]) - OpenType font features (#PangoAttrString). Since 1.38 + OpenType font features ([struct@Pango.AttrString]). Since 1.38 - foreground alpha (#PangoAttrInt). Since 1.38 + foreground alpha ([struct@Pango.AttrInt]). Since 1.38 - background alpha (#PangoAttrInt). Since 1.38 + background alpha ([struct@Pango.AttrInt]). Since 1.38 - whether breaks are allowed (#PangoAttrInt). Since 1.44 + whether breaks are allowed ([struct@Pango.AttrInt]). Since 1.44 - how to render invisible characters (#PangoAttrInt). Since 1.44 + how to render invisible characters ([struct@Pango.AttrInt]). Since 1.44 - whether to insert hyphens at intra-word line breaks (#PangoAttrInt). Since 1.44 + whether to insert hyphens at intra-word line breaks ([struct@Pango.AttrInt]). Since 1.44 - whether the text has an overline (#PangoAttrInt). Since 1.46 + whether the text has an overline ([struct@Pango.AttrInt]). Since 1.46 - overline color (#PangoAttrColor). Since 1.46 + overline color ([struct@Pango.AttrColor]). Since 1.46 - Fetches the attribute type name passed in when registering the type using -pango_attr_type_register(). + Fetches the attribute type name. -The returned value is an interned string (see g_intern_string() for what -that means) that should not be modified or freed. +The attribute type name is the string passed in +when registering the type using +[func@Pango.AttrType.register]. + +The returned value is an interned string (see +g_intern_string() for what that means) that should +not be modified or freed. - the type ID name (which may be %NULL), or -%NULL if @type is a built-in Pango attribute type or invalid. + the type ID name (which + may be %NULL), or %NULL if @type is a built-in Pango + attribute type or invalid. @@ -1004,8 +1057,10 @@ that means) that should not be modified or freed. - Allocate a new attribute type ID. The attribute type name can be accessed -later by using pango_attr_type_get_name(). + Allocate a new attribute type ID. + +The attribute type name can be accessed later +by using [func@Pango.AttrType.get_name]. the new type ID. @@ -1019,12 +1074,14 @@ later by using pango_attr_type_get_name(). - The #PangoAttribute structure represents the common portions of all -attributes. Particular types of attributes include this structure -as their initial portion. The common portion of the attribute holds -the range to which the value in the type-specific part of the attribute -applies and should be initialized using pango_attribute_init(). -By default an attribute will have an all-inclusive range of [0,%G_MAXUINT]. + The `PangoAttribute` structure represents the common portions of all +attributes. + +Particular types of attributes include this structure as their initial +portion. The common portion of the attribute holds the range to which +the value in the type-specific part of the attribute applies and should +be initialized using [method@Pango.Attribute.init]. By default, an attribute +will have an all-inclusive range of [0,%G_MAXUINT]. the class structure holding information about the type of the attribute @@ -1041,73 +1098,75 @@ is not included in the range. Make a copy of an attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy]. - a #PangoAttribute + a `PangoAttribute` - Destroy a #PangoAttribute and free all associated memory. + Destroy a `PangoAttribute` and free all associated memory. - a #PangoAttribute. + a `PangoAttribute`. - Compare two attributes for equality. This compares only the -actual value of the two attributes and not the ranges that the -attributes apply to. + Compare two attributes for equality. + +This compares only the actual value of the two +attributes and not the ranges that the attributes +apply to. - %TRUE if the two attributes have the same value. + %TRUE if the two attributes have the same value - a #PangoAttribute + a `PangoAttribute` - another #PangoAttribute + another `PangoAttribute` - Initializes @attr's klass to @klass, -it's start_index to %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING -and end_index to %PANGO_ATTR_INDEX_TO_TEXT_END -such that the attribute applies + Initializes @attr's klass to @klass, it's start_index to +%PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING and end_index to +%PANGO_ATTR_INDEX_TO_TEXT_END such that the attribute applies to the entire text by default. - a #PangoAttribute + a `PangoAttribute` - a #PangoAttrClass + a `PangoAttrClass` - The #PangoBidiType type represents the bidirectional character + `PangoBidiType` represents the bidirectional character type of a Unicode character as specified by the -<ulink url="http://www.unicode.org/reports/tr9/">Unicode bidirectional algorithm</ulink>. +[Unicode bidirectional algorithm](http://www.unicode.org/reports/tr9/). Use fribidi for this information Left-to-Right @@ -1166,12 +1225,24 @@ type of a Unicode character as specified by the Other Neutrals + + Left-to-Right isolate. Since 1.48.6 + + + Right-to-Left isolate. Since 1.48.6 + + + First strong isolate. Since 1.48.6 + + + Pop directional isolate. Since 1.48.6 + - Determines the normative bidirectional character type of a -character, as specified in the Unicode Character Database. + Determines the bidirectional type of a character. -A simplified version of this function is available as -pango_unichar_direction(). +The bidirectional type is specified in the Unicode Character Database. + +A simplified version of this function is available as [func@unichar_direction]. the bidirectional character type, as used in the Unicode bidirectional algorithm. @@ -1204,7 +1275,7 @@ Unicode bidirectional algorithm. - The #PangoColor structure is used to + The `PangoColor` structure is used to represent a color in an uncalibrated RGB color-space. value of red component @@ -1219,53 +1290,55 @@ represent a color in an uncalibrated RGB color-space. - Creates a copy of @src, which should be freed with -pango_color_free(). Primarily used by language bindings, -not that useful otherwise (since colors can just be copied -by assignment in C). + Creates a copy of @src. + +The copy should be freed with [method@Pango.Color.free]. +Primarily used by language bindings, not that useful +otherwise (since colors can just be copied by assignment +in C). - the newly allocated #PangoColor, which - should be freed with pango_color_free(), or %NULL if - @src was %NULL. + the newly allocated `PangoColor`, + which should be freed with [method@Pango.Color.free] - color to copy, may be %NULL + color to copy - Frees a color allocated by pango_color_copy(). + Frees a color allocated by [method@Pango.Color.copy]. - an allocated #PangoColor, may be %NULL + an allocated `PangoColor` - Fill in the fields of a color from a string specification. The -string can either one of a large set of standard names. (Taken -from the CSS <ulink url="http://dev.w3.org/csswg/css-color/#named-colors">specification</ulink>), or it can be a hexadecimal -value in the -form '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb' or '&num;rrrrggggbbbb' where -'r', 'g' and 'b' are hex digits of the red, green, and blue -components of the color, respectively. (White in the four -forms is '&num;fff' '&num;ffffff' '&num;fffffffff' and '&num;ffffffffffff') + Fill in the fields of a color from a string specification. + +The string can either one of a large set of standard names. +(Taken from the CSS Color [specification](https://www.w3.org/TR/css-color-4/#named-colors), +or it can be a value in the form `#rgb`, `#rrggbb`, +`#rrrgggbbb` or `#rrrrggggbbbb`, where `r`, `g` and `b` +are hex digits of the red, green, and blue components +of the color, respectively. (White in the four forms is +`#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.) %TRUE if parsing of the specifier succeeded, - otherwise false. + otherwise %FALSE - a #PangoColor structure in which to store the - result, or %NULL + a `PangoColor` structure in which + to store the result @@ -1275,33 +1348,34 @@ forms is '&num;fff' '&num;ffffff' '&num;fffffffff' and '&num;fff - Fill in the fields of a color from a string specification. The -string can either one of a large set of standard names. (Taken -from the CSS <ulink url="http://dev.w3.org/csswg/css-color/#named-colors">specification</ulink>), or it can be a hexadecimal -value in the -form '&num;rgb' '&num;rrggbb' '&num;rrrgggbbb' or '&num;rrrrggggbbbb' where -'r', 'g' and 'b' are hex digits of the red, green, and blue -components of the color, respectively. (White in the four -forms is '&num;fff' '&num;ffffff' '&num;fffffffff' and '&num;ffffffffffff') + Fill in the fields of a color from a string specification. -Additionally, parse strings of the form -'&num;rgba', '&num;rrggbbaa', '&num;rrrrggggbbbbaaaa', -if @alpha is not %NULL, and set @alpha to the value specified -by the hex digits for 'a'. If no alpha component is found -in @spec, @alpha is set to 0xffff (for a solid color). +The string can either one of a large set of standard names. +(Taken from the CSS Color [specification](https://www.w3.org/TR/css-color-4/#named-colors), +or it can be a hexadecimal value in the form `#rgb`, +`#rrggbb`, `#rrrgggbbb` or `#rrrrggggbbbb` where `r`, `g` +and `b` are hex digits of the red, green, and blue components +of the color, respectively. (White in the four forms is +`#fff`, `#ffffff`, `#fffffffff` and `#ffffffffffff`.) + +Additionally, parse strings of the form `#rgba`, `#rrggbbaa`, +`#rrrrggggbbbbaaaa`, if @alpha is not %NULL, and set @alpha +to the value specified by the hex digits for `a`. If no alpha +component is found in @spec, @alpha is set to 0xffff (for a +solid color). %TRUE if parsing of the specifier succeeded, - otherwise false. + otherwise %FALSE - a #PangoColor structure in which to store the - result, or %NULL + a `PangoColor` structure in which + to store the result - return location for alpha, or %NULL + return location for alpha @@ -1311,46 +1385,53 @@ in @spec, @alpha is set to 0xffff (for a solid color). - Returns a textual specification of @color in the hexadecimal form -<literal>&num;rrrrggggbbbb</literal>, where <literal>r</literal>, -<literal>g</literal> and <literal>b</literal> are hex digits representing -the red, green, and blue components respectively. + Returns a textual specification of @color. + +The string is in the hexadecimal form `#rrrrggggbbbb`, +where `r`, `g` and `b` are hex digits representing the +red, green, and blue components respectively. - a newly-allocated text string that must be freed with g_free(). + a newly-allocated text string that must + be freed with g_free(). - a #PangoColor + a `PangoColor` - The #PangoContext structure stores global information -used to control the itemization process. + A `PangoContext` stores global information used to control the +itemization process. + +The information stored by `PangoContext` includes the fontmap used +to look up fonts, and default values such as the default language, +default gravity, or default font. + +To obtain a `PangoContext`, use [method@Pango.FontMap.create_context]. - Creates a new #PangoContext initialized to default values. + Creates a new `PangoContext` initialized to default values. This function is not particularly useful as it should always -be followed by a pango_context_set_font_map() call, and the -function pango_font_map_create_context() does these two steps +be followed by a [method@Pango.Context.set_font_map] call, and the +function [method@Pango.FontMap.create_context] does these two steps together and hence users are recommended to use that. If you are using Pango as part of a higher-level system, -that system may have it's own way of create a #PangoContext. -For instance, the GTK+ toolkit has, among others, -gdk_pango_context_get_for_screen(), and -gtk_widget_get_pango_context(). Use those instead. +that system may have it's own way of create a `PangoContext`. +For instance, the GTK toolkit has, among others, +`gtk_widget_get_pango_context()`. Use those instead. - the newly allocated #PangoContext, which should - be freed with g_object_unref(). + the newly allocated `PangoContext`, which should + be freed with g_object_unref(). - Forces a change in the context, which will cause any #PangoLayout + Forces a change in the context, which will cause any `PangoLayout` using this context to re-layout. This function is only useful when implementing a new backend @@ -1362,35 +1443,37 @@ and such data is changed. - a #PangoContext + a `PangoContext` - Retrieves the base direction for the context. See -pango_context_set_base_dir(). + Retrieves the base direction for the context. + +See [method@Pango.Context.set_base_dir]. the base direction for the context. - a #PangoContext + a `PangoContext` - Retrieves the base gravity for the context. See -pango_context_set_base_gravity(). + Retrieves the base gravity for the context. + +See [method@Pango.Context.set_base_gravity]. the base gravity for the context. - a #PangoContext + a `PangoContext` @@ -1399,56 +1482,59 @@ pango_context_set_base_gravity(). Retrieve the default font description for the context. a pointer to the context's default font - description. This value must not be modified or freed. + description. This value must not be modified or freed. - a #PangoContext + a `PangoContext` - Gets the #PangoFontMap used to look up fonts for this context. + Gets the `PangoFontMap` used to look up fonts for this context. - the font map for the #PangoContext. - This value is owned by Pango and should not be unreferenced. + the font map for the `PangoContext`. + This value is owned by Pango and should not be unreferenced. - a #PangoContext + a `PangoContext` - Retrieves the gravity for the context. This is similar to -pango_context_get_base_gravity(), except for when the base gravity -is %PANGO_GRAVITY_AUTO for which pango_gravity_get_for_matrix() is used -to return the gravity from the current context matrix. + Retrieves the gravity for the context. + +This is similar to [method@Pango.Context.get_base_gravity], +except for when the base gravity is %PANGO_GRAVITY_AUTO for +which [func@Pango.Gravity.get_for_matrix] is used to return the +gravity from the current context matrix. the resolved gravity for the context. - a #PangoContext + a `PangoContext` - Retrieves the gravity hint for the context. See -pango_context_set_gravity_hint() for details. + Retrieves the gravity hint for the context. + +See [method@Pango.Context.set_gravity_hint] for details. the gravity hint for the context. - a #PangoContext + a `PangoContext` @@ -1461,61 +1547,62 @@ pango_context_set_gravity_hint() for details. - a #PangoContext + a `PangoContext` Gets the transformation matrix that will be applied when -rendering with this context. See pango_context_set_matrix(). +rendering with this context. + +See [method@Pango.Context.set_matrix]. the matrix, or %NULL if no matrix has - been set (which is the same as the identity matrix). The returned - matrix is owned by Pango and must not be modified or freed. + been set (which is the same as the identity matrix). The returned + matrix is owned by Pango and must not be modified or freed. - a #PangoContext + a `PangoContext` - Get overall metric information for a particular font -description. Since the metrics may be substantially different for -different scripts, a language tag can be provided to indicate that -the metrics should be retrieved that correspond to the script(s) -used by that language. + Get overall metric information for a particular font description. -The #PangoFontDescription is interpreted in the same way as -by pango_itemize(), and the family name may be a comma separated -list of figures. If characters from multiple of these families -would be used to render the string, then the returned fonts would -be a composite of the metrics for the fonts loaded for the -individual families. +Since the metrics may be substantially different for different scripts, +a language tag can be provided to indicate that the metrics should be +retrieved that correspond to the script(s) used by that language. + +The `PangoFontDescription` is interpreted in the same way as by [func@itemize], +and the family name may be a comma separated list of names. If characters +from multiple of these families would be used to render the string, then +the returned fonts would be a composite of the metrics for the fonts loaded +for the individual families. - a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - when finished using the object. + a `PangoFontMetrics` object. The caller must call + [method@Pango.FontMetrics.unref] when finished using the object. - a #PangoContext + a `PangoContext` - a #PangoFontDescription structure. %NULL means that the - font description from the context will be used. + a `PangoFontDescription` structure. %NULL means that the + font description from the context will be used. language tag used to determine which script to get - the metrics for. %NULL means that the language tag from the context - will be used. If no language tag is set on the context, metrics - for the default language (as determined by pango_language_get_default()) - will be returned. + the metrics for. %NULL means that the language tag from the context + will be used. If no language tag is set on the context, metrics + for the default language (as determined by [func@Pango.Language.get_default] + will be returned. @@ -1528,29 +1615,31 @@ round glyph positions and widths. - a #PangoContext + a `PangoContext` - Returns the current serial number of @context. The serial number is -initialized to an small number larger than zero when a new context -is created and is increased whenever the context is changed using any -of the setter functions, or the #PangoFontMap it uses to find fonts has -changed. The serial may wrap, but will never have the value 0. Since it -can wrap, never compare it with "less than", always use "not equals". + Returns the current serial number of @context. -This can be used to automatically detect changes to a #PangoContext, and -is only useful when implementing objects that need update when their -#PangoContext changes, like #PangoLayout. +The serial number is initialized to an small number larger than zero +when a new context is created and is increased whenever the context +is changed using any of the setter functions, or the `PangoFontMap` it +uses to find fonts has changed. The serial may wrap, but will never +have the value 0. Since it can wrap, never compare it with "less than", +always use "not equals". + +This can be used to automatically detect changes to a `PangoContext`, +and is only useful when implementing objects that need update when their +`PangoContext` changes, like `PangoLayout`. The current serial number of @context. - a #PangoContext + a `PangoContext` @@ -1562,13 +1651,13 @@ is only useful when implementing objects that need update when their - a #PangoContext + a `PangoContext` - location to store a pointer to - an array of #PangoFontFamily *. This array should be freed - with g_free(). + location + to store a pointer to an array of `PangoFontFamily`. This array should + be freed with g_free(). @@ -1583,17 +1672,17 @@ is only useful when implementing objects that need update when their Loads the font in one of the fontmaps in the context that is the closest match for @desc. - the newly allocated #PangoFont - that was loaded, or %NULL if no font matched. + the newly allocated `PangoFont` + that was loaded, or %NULL if no font matched. - a #PangoContext + a `PangoContext` - a #PangoFontDescription describing the font to load + a `PangoFontDescription` describing the font to load @@ -1603,20 +1692,20 @@ that is the closest match for @desc. a font matching @desc. the newly allocated - #PangoFontset loaded, or %NULL if no font matched. + `PangoFontset` loaded, or %NULL if no font matched. - a #PangoContext + a `PangoContext` - a #PangoFontDescription describing the fonts to load + a `PangoFontDescription` describing the fonts to load - a #PangoLanguage the fonts will be used for + a `PangoLanguage` the fonts will be used for @@ -1627,7 +1716,7 @@ a font matching @desc. The base direction is used in applying the Unicode bidirectional algorithm; if the @direction is %PANGO_DIRECTION_LTR or %PANGO_DIRECTION_RTL, then the value will be used as the paragraph -direction in the Unicode bidirectional algorithm. A value of +direction in the Unicode bidirectional algorithm. A value of %PANGO_DIRECTION_WEAK_LTR or %PANGO_DIRECTION_WEAK_RTL is used only for paragraphs that do not contain any strong characters themselves. @@ -1635,7 +1724,7 @@ for paragraphs that do not contain any strong characters themselves. - a #PangoContext + a `PangoContext` @@ -1653,7 +1742,7 @@ The base gravity is used in laying vertical text out. - a #PangoContext + a `PangoContext` @@ -1669,7 +1758,7 @@ The base gravity is used in laying vertical text out. - a #PangoContext + a `PangoContext` @@ -1679,19 +1768,22 @@ The base gravity is used in laying vertical text out. - Sets the font map to be searched when fonts are looked-up in this context. -This is only for internal use by Pango backends, a #PangoContext obtained -via one of the recommended methods should already have a suitable font map. + Sets the font map to be searched when fonts are looked-up +in this context. + +This is only for internal use by Pango backends, a `PangoContext` +obtained via one of the recommended methods should already have a +suitable font map. - a #PangoContext + a `PangoContext` - the #PangoFontMap to set. + the `PangoFontMap` to set. @@ -1699,15 +1791,16 @@ via one of the recommended methods should already have a suitable font map. Sets the gravity hint for the context. -The gravity hint is used in laying vertical text out, and is only relevant -if gravity of the context as returned by pango_context_get_gravity() -is set %PANGO_GRAVITY_EAST or %PANGO_GRAVITY_WEST. +The gravity hint is used in laying vertical text out, and +is only relevant if gravity of the context as returned by +[method@Pango.Context.get_gravity] is set to %PANGO_GRAVITY_EAST +or %PANGO_GRAVITY_WEST. - a #PangoContext + a `PangoContext` @@ -1717,15 +1810,16 @@ is set %PANGO_GRAVITY_EAST or %PANGO_GRAVITY_WEST. - Sets the global language tag for the context. The default language -for the locale of the running process can be found using -pango_language_get_default(). + Sets the global language tag for the context. + +The default language for the locale of the running process +can be found using [func@Pango.Language.get_default]. - a #PangoContext + a `PangoContext` @@ -1736,21 +1830,23 @@ pango_language_get_default(). Sets the transformation matrix that will be applied when rendering -with this context. Note that reported metrics are in the user space -coordinates before the application of the matrix, not device-space -coordinates after the application of the matrix. So, they don't scale -with the matrix, though they may change slightly for different -matrices, depending on how the text is fit to the pixel grid. +with this context. + +Note that reported metrics are in the user space coordinates before +the application of the matrix, not device-space coordinates after the +application of the matrix. So, they don't scale with the matrix, though +they may change slightly for different matrices, depending on how the +text is fit to the pixel grid. - a #PangoContext + a `PangoContext` - a #PangoMatrix, or %NULL to unset any existing + a `PangoMatrix`, or %NULL to unset any existing matrix. (No matrix set is the same as setting the identity matrix.) @@ -1771,7 +1867,7 @@ compatible with previous Pango behavior. - a #PangoContext + a `PangoContext` @@ -1783,31 +1879,35 @@ compatible with previous Pango behavior. - The #PangoCoverage structure represents a map from Unicode characters -to #PangoCoverageLevel. It is an opaque structure with no public fields. + A `PangoCoverage` structure is a map from Unicode characters +to [enum@Pango.CoverageLevel] values. + +It is often necessary in Pango to determine if a particular +font can represent a particular character, and also how well +it can represent that character. The `PangoCoverage` is a data +structure that is used to represent that information. It is an +opaque structure with no public fields. - Create a new #PangoCoverage + Create a new `PangoCoverage` - the newly allocated #PangoCoverage, - initialized to %PANGO_COVERAGE_NONE - with a reference count of one, which - should be freed with pango_coverage_unref(). + the newly allocated `PangoCoverage`, initialized + to %PANGO_COVERAGE_NONE with a reference count of one, which + should be freed with [method@Pango.Coverage.unref]. - Convert data generated from pango_coverage_to_bytes() back -to a #PangoCoverage + Convert data generated from pango_coverage_to_bytes() +back to a `PangoCoverage`. This returns %NULL - a newly allocated - #PangoCoverage, or %NULL if the data was invalid. + a newly allocated `PangoCoverage` binary data - representing a #PangoCoverage + representing a `PangoCoverage` @@ -1819,30 +1919,29 @@ to a #PangoCoverage - Copy an existing #PangoCoverage. (This function may now be unnecessary -since we refcount the structure. File a bug if you use it.) + Copy an existing `PangoCoverage`. - the newly allocated #PangoCoverage, - with a reference count of one, which should be freed - with pango_coverage_unref(). + the newly allocated `PangoCoverage`, + with a reference count of one, which should be freed with + [method@Pango.Coverage.unref]. - a #PangoCoverage + a `PangoCoverage` - Determine whether a particular index is covered by @coverage + Determine whether a particular index is covered by @coverage. the coverage level of @coverage for character @index_. - a #PangoCoverage + a `PangoCoverage` @@ -1861,24 +1960,24 @@ the corresponding index in @other. - a #PangoCoverage + a `PangoCoverage` - another #PangoCoverage + another `PangoCoverage` - Increase the reference count on the #PangoCoverage by one + Increase the reference count on the `PangoCoverage` by one. @coverage - a #PangoCoverage + a `PangoCoverage` @@ -1890,7 +1989,7 @@ the corresponding index in @other. - a #PangoCoverage + a `PangoCoverage` @@ -1904,14 +2003,14 @@ the corresponding index in @other. - Convert a #PangoCoverage structure into a flat binary format + Convert a `PangoCoverage` structure into a flat binary format. This returns %NULL - a #PangoCoverage + a `PangoCoverage` @@ -1928,218 +2027,79 @@ the corresponding index in @other. - Decrease the reference count on the #PangoCoverage by one. + Decrease the reference count on the `PangoCoverage` by one. + If the result is zero, free the coverage and all associated memory. - a #PangoCoverage + a `PangoCoverage` - Used to indicate how well a font can represent a particular Unicode -character point for a particular script. + `PangoCoverageLevel` is used to indicate how well a font can +represent a particular Unicode character for a particular script. Since 1.44, only %PANGO_COVERAGE_NONE and %PANGO_COVERAGE_EXACT will be returned. - The character is not representable with the font. + The character is not representable with + the font. - The character is represented in a way that may be -comprehensible but is not the correct graphical form. -For instance, a Hangul character represented as a -a sequence of Jamos, or a Latin transliteration of a Cyrillic word. + The character is represented in a + way that may be comprehensible but is not the correct + graphical form. For instance, a Hangul character represented + as a a sequence of Jamos, or a Latin transliteration of a + Cyrillic word. - The character is represented as basically the correct -graphical form, but with a stylistic variant inappropriate for -the current script. + The character is represented as + basically the correct graphical form, but with a stylistic + variant inappropriate for the current script. - The character is represented as the correct graphical form. + The character is represented as the + correct graphical form. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Extracts the <firstterm>descent</firstterm> from a #PangoRectangle -representing glyph extents. The descent is the distance from the -baseline to the lowest point of the character. This is positive if the + Extracts the *descent* from a `PangoRectangle` +representing glyph extents. + +The descent is the distance from the baseline to the +lowest point of the character. This is positive if the glyph descends below the baseline. - a #PangoRectangle + a `PangoRectangle` - The #PangoDirection type represents a direction in the -Unicode bidirectional algorithm; not every value in this -enumeration makes sense for every usage of #PangoDirection; -for example, the return value of pango_unichar_direction() -and pango_find_base_dir() cannot be %PANGO_DIRECTION_WEAK_LTR -or %PANGO_DIRECTION_WEAK_RTL, since every character is either -neutral or has a strong direction; on the other hand -%PANGO_DIRECTION_NEUTRAL doesn't make sense to pass -to pango_itemize_with_base_dir(). + `PangoDirection` represents a direction in the Unicode bidirectional +algorithm. -The %PANGO_DIRECTION_TTB_LTR, %PANGO_DIRECTION_TTB_RTL -values come from an earlier interpretation of this -enumeration as the writing direction of a block of -text and are no longer used; See #PangoGravity for how +Not every value in this enumeration makes sense for every usage of +`PangoDirection`; for example, the return value of [func@unichar_direction] +and [func@find_base_dir] cannot be %PANGO_DIRECTION_WEAK_LTR or +%PANGO_DIRECTION_WEAK_RTL, since every character is either neutral +or has a strong direction; on the other hand %PANGO_DIRECTION_NEUTRAL +doesn't make sense to pass to [func@itemize_with_base_dir]. + +The %PANGO_DIRECTION_TTB_LTR, %PANGO_DIRECTION_TTB_RTL values come from +an earlier interpretation of this enumeration as the writing direction +of a block of text and are no longer used; See `PangoGravity` for how vertical text is handled in Pango. -If you are interested in text direction, you should -really use fribidi directly. PangoDirection is only -retained because it is used in some public apis. +If you are interested in text direction, you should really use fribidi +directly. `PangoDirection` is only retained because it is used in some +public apis. A strong left-to-right direction @@ -2164,74 +2124,11 @@ retained because it is used in some public apis. No direction specified - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - A string constant defining the engine type for language engines. -These engines derive from #PangoEngineLang. - - - - A string constant defining the engine type for shaping engines. -These engines derive from #PangoEngineShape. - - - The #PangoEllipsizeMode type describes what sort of (if any) -ellipsization should be applied to a line of text. In -the ellipsization process characters are removed from the + `PangoEllipsizeMode` describes what sort of ellipsization +should be applied to text. + +In the ellipsization process characters are removed from the text in order to make it fit to a given width and replaced with an ellipsis. @@ -2247,253 +2144,9 @@ with an ellipsis. Omit characters at the end of the text - - #PangoEngine is the base class for all types of language and -script specific engines. It has no functionality by itself. - - - - - - Class structure for #PangoEngine - - - - - - The #PangoEngineInfo structure contains information about a particular -engine. It contains the following fields: - - a unique string ID for the engine. - - - - a string identifying the engine type. - - - - a string identifying the render type. - - - - array of scripts this engine supports. - - - - number of items in @scripts. - - - - - The <firstterm>language engines</firstterm> are rendering-system independent -engines that determine line, word, and character breaks for character strings. -These engines are used in pango_break(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Class structure for #PangoEngineLang - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #PangoEngineScriptInfo structure contains -information about how the shaper covers a particular script. - - a #PangoScript. The value %PANGO_SCRIPT_COMMON has -the special meaning here of "all scripts" - - - - a semicolon separated list of languages that this -engine handles for this script. This may be empty, -in which case the engine is saying that it is a -fallback choice for all languages for this range, -but should not be used if another engine -indicates that it is specific for the language for -a given code point. An entry in this list of "*" -indicates that this engine is specific to all -languages for this range. - - - - - The <firstterm>shape engines</firstterm> are rendering-system dependent -engines that convert character strings into glyph strings. -These engines are used in pango_shape(). - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Class structure for #PangoEngineShape - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Casts a #GObject to a #PangoFont. - a #GObject. @@ -2528,10 +2181,8 @@ These engines are used in pango_shape(). - Casts a #GObject to a #PangoFontFace. - a #GObject. @@ -2548,10 +2199,8 @@ These engines are used in pango_shape(). - Casts a #GObject to a #PangoFontFamily. - a #GObject. @@ -2574,10 +2223,8 @@ These engines are used in pango_shape(). - Casts a #GObject to a #PangoFontMap. - a #GObject. @@ -2594,18 +2241,8 @@ These engines are used in pango_shape(). - The #PangoFont structure is used to represent -a font in a rendering-system-independent matter. -To create an implementation of a #PangoFont, -the rendering-system specific code should allocate -a larger structure that contains a nested -#PangoFont, fill in the <structfield>klass</structfield> member of -the nested #PangoFont with a pointer to -a appropriate #PangoFontClass, then call -pango_font_init() on the structure. - -The #PangoFont structure contains one member -which the implementation fills in. + A `PangoFont` is used to represent a font in a +rendering-system-independent manner. Frees an array of font descriptions. @@ -2614,7 +2251,7 @@ which the implementation fills in. a pointer -to an array of #PangoFontDescription, may be %NULL + to an array of `PangoFontDescription`, may be %NULL @@ -2637,15 +2274,16 @@ to an array of #PangoFontDescription, may be %NULL Returns a description of the font, with font size set in points. -Use pango_font_describe_with_absolute_size() if you want the font -size in device units. + +Use [method@Pango.Font.describe_with_absolute_size] if you want +the font size in device units. - a newly-allocated #PangoFontDescription object. + a newly-allocated `PangoFontDescription` object. - a #PangoFont + a `PangoFont` @@ -2663,13 +2301,13 @@ size in device units. Computes the coverage map for a given font and language tag. - a newly-allocated #PangoCoverage + a newly-allocated `PangoCoverage` object. - a #PangoFont + a `PangoFont` @@ -2680,6 +2318,7 @@ size in device units. Obtain the OpenType features that are provided by the font. + These are passed to the rendering system, together with features that have been explicitly set via attributes. @@ -2690,7 +2329,7 @@ rendering system enables by default. - a #PangoFont + a `PangoFont` @@ -2710,28 +2349,31 @@ rendering system enables by default. Gets the font map for which the font was created. -Note that the font maintains a <firstterm>weak</firstterm> reference -to the font map, so if all references to font map are dropped, the font -map will be finalized even if there are fonts created with the font -map that are still alive. In that case this function will return %NULL. -It is the responsibility of the user to ensure that the font map is kept -alive. In most uses this is not an issue as a #PangoContext holds -a reference to the font map. +Note that the font maintains a *weak* reference to +the font map, so if all references to font map are +dropped, the font map will be finalized even if there +are fonts created with the font map that are still alive. +In that case this function will return %NULL. + +It is the responsibility of the user to ensure that the +font map is kept alive. In most uses this is not an issue +as a `PangoContext` holds a reference to the font map. - the #PangoFontMap for the - font, or %NULL if @font is %NULL. + the `PangoFontMap` + for the font - a #PangoFont, or %NULL + a `PangoFont` - Gets the logical and ink extents of a glyph within a font. The -coordinate system for each rectangle has its origin at the + Gets the logical and ink extents of a glyph within a font. + +The coordinate system for each rectangle has its origin at the base line and horizontal origin of the character with increasing coordinates extending to the right and down. The macros PANGO_ASCENT(), PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert @@ -2745,7 +2387,7 @@ output variables and returns. - a #PangoFont + a `PangoFont` @@ -2753,105 +2395,84 @@ output variables and returns. - rectangle used to store the extents of the glyph - as drawn or %NULL to indicate that the result is not needed. + rectangle used to store the extents of the glyph as drawn - rectangle used to store the logical extents of - the glyph or %NULL to indicate that the result is not needed. + rectangle used to store the logical extents of the glyph - Gets overall metric information for a font. Since the metrics may be -substantially different for different scripts, a language tag can -be provided to indicate that the metrics should be retrieved that -correspond to the script(s) used by that language. + Gets overall metric information for a font. + +Since the metrics may be substantially different for different scripts, +a language tag can be provided to indicate that the metrics should be +retrieved that correspond to the script(s) used by that language. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. - a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - when finished using the object. + a `PangoFontMetrics` object. The caller must call + [method@Pango.FontMetrics.unref] when finished using the object. - a #PangoFont + a `PangoFont` - language tag used to determine which script to get the metrics - for, or %NULL to indicate to get the metrics for the entire font. + language tag used to determine which script + to get the metrics for, or %NULL to indicate to get the metrics for + the entire font. Returns a description of the font, with font size set in points. -Use pango_font_describe_with_absolute_size() if you want the font -size in device units. + +Use [method@Pango.Font.describe_with_absolute_size] if you want +the font size in device units. - a newly-allocated #PangoFontDescription object. + a newly-allocated `PangoFontDescription` object. - a #PangoFont + a `PangoFont` Returns a description of the font, with absolute font size set -(in device units). Use pango_font_describe() if you want the font -size in points. +in device units. + +Use [method@Pango.Font.describe] if you want the font size in points. - a newly-allocated #PangoFontDescription object. + a newly-allocated `PangoFontDescription` object. - a #PangoFont + a `PangoFont` - - Finds the best matching shaper for a font for a particular -language tag and character point. - Shape engines are no longer used - - the best matching shaper. - - - - - a #PangoFont - - - - the language tag - - - - a Unicode character. - - - - Computes the coverage map for a given font and language tag. - a newly-allocated #PangoCoverage + a newly-allocated `PangoCoverage` object. - a #PangoFont + a `PangoFont` @@ -2861,20 +2482,21 @@ language tag and character point. - Gets the #PangoFontFace to which @font belongs. + Gets the `PangoFontFace` to which @font belongs. - the #PangoFontFace + the `PangoFontFace` - a #PangoFont + a `PangoFont` Obtain the OpenType features that are provided by the font. + These are passed to the rendering system, together with features that have been explicitly set via attributes. @@ -2885,7 +2507,7 @@ rendering system enables by default. - a #PangoFont + a `PangoFont` @@ -2905,28 +2527,31 @@ rendering system enables by default. Gets the font map for which the font was created. -Note that the font maintains a <firstterm>weak</firstterm> reference -to the font map, so if all references to font map are dropped, the font -map will be finalized even if there are fonts created with the font -map that are still alive. In that case this function will return %NULL. -It is the responsibility of the user to ensure that the font map is kept -alive. In most uses this is not an issue as a #PangoContext holds -a reference to the font map. +Note that the font maintains a *weak* reference to +the font map, so if all references to font map are +dropped, the font map will be finalized even if there +are fonts created with the font map that are still alive. +In that case this function will return %NULL. + +It is the responsibility of the user to ensure that the +font map is kept alive. In most uses this is not an issue +as a `PangoContext` holds a reference to the font map. - the #PangoFontMap for the - font, or %NULL if @font is %NULL. + the `PangoFontMap` + for the font - a #PangoFont, or %NULL + a `PangoFont` - Gets the logical and ink extents of a glyph within a font. The -coordinate system for each rectangle has its origin at the + Gets the logical and ink extents of a glyph within a font. + +The coordinate system for each rectangle has its origin at the base line and horizontal origin of the character with increasing coordinates extending to the right and down. The macros PANGO_ASCENT(), PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert @@ -2940,7 +2565,7 @@ output variables and returns. - a #PangoFont + a `PangoFont` @@ -2948,56 +2573,56 @@ output variables and returns. - rectangle used to store the extents of the glyph - as drawn or %NULL to indicate that the result is not needed. + rectangle used to store the extents of the glyph as drawn - rectangle used to store the logical extents of - the glyph or %NULL to indicate that the result is not needed. + rectangle used to store the logical extents of the glyph - Get a hb_font_t object backing this font. + Get a `hb_font_t` object backing this font. -Note that the objects returned by this function -are cached and immutable. If you need to make -changes to the hb_font_t, use hb_font_create_sub_font(). +Note that the objects returned by this function are cached +and immutable. If you need to make changes to the `hb_font_t`, +use hb_font_create_sub_font(). - the hb_font_t object backing the - font, or %NULL if the font does not have one + the `hb_font_t` object + backing the font - a #PangoFont + a `PangoFont` - Gets overall metric information for a font. Since the metrics may be -substantially different for different scripts, a language tag can -be provided to indicate that the metrics should be retrieved that -correspond to the script(s) used by that language. + Gets overall metric information for a font. + +Since the metrics may be substantially different for different scripts, +a language tag can be provided to indicate that the metrics should be +retrieved that correspond to the script(s) used by that language. If @font is %NULL, this function gracefully sets some sane values in the output variables and returns. - a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - when finished using the object. + a `PangoFontMetrics` object. The caller must call + [method@Pango.FontMetrics.unref] when finished using the object. - a #PangoFont + a `PangoFont` - language tag used to determine which script to get the metrics - for, or %NULL to indicate to get the metrics for the entire font. + language tag used to determine which script + to get the metrics for, or %NULL to indicate to get the metrics for + the entire font. @@ -3011,7 +2636,7 @@ Returns %TRUE if @font can render @wc - a #PangoFont + a `PangoFont` @@ -3031,12 +2656,12 @@ Returns %TRUE if @font can render @wc - a newly-allocated #PangoFontDescription object. + a newly-allocated `PangoFontDescription` object. - a #PangoFont + a `PangoFont` @@ -3045,13 +2670,13 @@ Returns %TRUE if @font can render @wc - a newly-allocated #PangoCoverage + a newly-allocated `PangoCoverage` object. - a #PangoFont + a `PangoFont` @@ -3068,7 +2693,7 @@ Returns %TRUE if @font can render @wc - a #PangoFont + a `PangoFont` @@ -3076,13 +2701,11 @@ Returns %TRUE if @font can render @wc - rectangle used to store the extents of the glyph - as drawn or %NULL to indicate that the result is not needed. + rectangle used to store the extents of the glyph as drawn - rectangle used to store the logical extents of - the glyph or %NULL to indicate that the result is not needed. + rectangle used to store the logical extents of the glyph @@ -3091,18 +2714,19 @@ Returns %TRUE if @font can render @wc - a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - when finished using the object. + a `PangoFontMetrics` object. The caller must call + [method@Pango.FontMetrics.unref] when finished using the object. - a #PangoFont + a `PangoFont` - language tag used to determine which script to get the metrics - for, or %NULL to indicate to get the metrics for the entire font. + language tag used to determine which script + to get the metrics for, or %NULL to indicate to get the metrics for + the entire font. @@ -3111,13 +2735,13 @@ Returns %TRUE if @font can render @wc - the #PangoFontMap for the - font, or %NULL if @font is %NULL. + the `PangoFontMap` + for the font - a #PangoFont, or %NULL + a `PangoFont` @@ -3142,7 +2766,7 @@ Returns %TRUE if @font can render @wc - a #PangoFont + a `PangoFont` @@ -3174,15 +2798,17 @@ Returns %TRUE if @font can render @wc - The #PangoFontDescription structure represents the description -of an ideal font. These structures are used both to list -what fonts are available on the system and also for specifying -the characteristics of a font to load. + A `PangoFontDescription` describes a font in an implementation-independent +manner. + +`PangoFontDescription` structures are used both to list what fonts are +available on the system and also for specifying the characteristics of +a font to load. Creates a new font description structure with all fields unset. - the newly allocated #PangoFontDescription, which - should be freed using pango_font_description_free(). + the newly allocated `PangoFontDescription`, which + should be freed using [method@Pango.FontDescription.free]. @@ -3190,12 +2816,12 @@ the characteristics of a font to load. Determines if the style attributes of @new_match are a closer match for @desc than those of @old_match are, or if @old_match is %NULL, determines if @new_match is a match at all. -Approximate matching is done for -weight and style; other style attributes must match exactly. -Style attributes are all attributes other than family and size-related -attributes. Approximate matching for style considers PANGO_STYLE_OBLIQUE -and PANGO_STYLE_ITALIC as matches, but not as good a match as when the -styles are equal. + +Approximate matching is done for weight and style; other style attributes +must match exactly. Style attributes are all attributes other than family +and size-related attributes. Approximate matching for style considers +%PANGO_STYLE_OBLIQUE and %PANGO_STYLE_ITALIC as matches, but not as good +a match as when the styles are equal. Note that @old_match must match @desc. @@ -3204,72 +2830,74 @@ Note that @old_match must match @desc. - a #PangoFontDescription + a `PangoFontDescription` - a #PangoFontDescription, or %NULL + a `PangoFontDescription`, or %NULL - a #PangoFontDescription + a `PangoFontDescription` - Make a copy of a #PangoFontDescription. + Make a copy of a `PangoFontDescription`. - the newly allocated - #PangoFontDescription, which should be freed with - pango_font_description_free(), or %NULL if @desc was - %NULL. + the newly allocated `PangoFontDescription`, + which should be freed with [method@Pango.FontDescription.free], + or %NULL if @desc was %NULL. - a #PangoFontDescription, may be %NULL + a `PangoFontDescription`, may be %NULL - Like pango_font_description_copy(), but only a shallow copy is made -of the family name and other allocated fields. The result can only -be used until @desc is modified or freed. This is meant to be used -when the copy is only needed temporarily. + Make a copy of a `PangoFontDescription`, but don't duplicate +allocated fields. + +This is like [method@Pango.FontDescription.copy], but only a shallow +copy is made of the family name and other allocated fields. The result +can only be used until @desc is modified or freed. This is meant +to be used when the copy is only needed temporarily. - the newly allocated - #PangoFontDescription, which should be freed with - pango_font_description_free(), or %NULL if @desc was - %NULL. + the newly allocated `PangoFontDescription`, + which should be freed with [method@Pango.FontDescription.free], + or %NULL if @desc was %NULL. - a #PangoFontDescription, may be %NULL + a `PangoFontDescription`, may be %NULL - Compares two font descriptions for equality. Two font descriptions -are considered equal if the fonts they describe are provably identical. -This means that their masks do not have to match, as long as other fields -are all the same. (Two font descriptions may result in identical fonts -being loaded, but still compare %FALSE.) + Compares two font descriptions for equality. + +Two font descriptions are considered equal if the fonts they describe +are provably identical. This means that their masks do not have to match, +as long as other fields are all the same. (Two font descriptions may +result in identical fonts being loaded, but still compare %FALSE.) %TRUE if the two font descriptions are identical, - %FALSE otherwise. + %FALSE otherwise. - a #PangoFontDescription + a `PangoFontDescription` - another #PangoFontDescription + another `PangoFontDescription` @@ -3281,40 +2909,41 @@ being loaded, but still compare %FALSE.) - a #PangoFontDescription, may be %NULL + a `PangoFontDescription`, may be %NULL - Gets the family name field of a font description. See -pango_font_description_set_family(). + Gets the family name field of a font description. + +See [method@Pango.FontDescription.set_family]. the family name field for the font - description, or %NULL if not previously set. This - has the same life-time as the font description itself - and should not be freed. + description, or %NULL if not previously set. This has the same + life-time as the font description itself and should not be freed. - a #PangoFontDescription. + a `PangoFontDescription`. - Gets the gravity field of a font description. See -pango_font_description_set_gravity(). + Gets the gravity field of a font description. + +See [method@Pango.FontDescription.set_gravity]. - the gravity field for the font description. Use - pango_font_description_get_set_fields() to find out if - the field was explicitly set or not. + the gravity field for the font description. + Use [method@Pango.FontDescription.get_set_fields] to find out + if the field was explicitly set or not. - a #PangoFontDescription + a `PangoFontDescription` @@ -3328,145 +2957,158 @@ pango_font_description_set_gravity(). - a #PangoFontDescription + a `PangoFontDescription` Gets the size field of a font description. -See pango_font_description_set_size(). + +See [method@Pango.FontDescription.set_size]. - the size field for the font description in points or device units. - You must call pango_font_description_get_size_is_absolute() - to find out which is the case. Returns 0 if the size field has not - previously been set or it has been set to 0 explicitly. - Use pango_font_description_get_set_fields() to - find out if the field was explicitly set or not. + the size field for the font description in points + or device units. You must call + [method@Pango.FontDescription.get_size_is_absolute] to find out + which is the case. Returns 0 if the size field has not previously + been set or it has been set to 0 explicitly. + Use [method@Pango.FontDescription.get_set_fields] to find out + if the field was explicitly set or not. - a #PangoFontDescription + a `PangoFontDescription` - Determines whether the size of the font is in points (not absolute) or device units (absolute). -See pango_font_description_set_size() and pango_font_description_set_absolute_size(). + Determines whether the size of the font is in points (not absolute) +or device units (absolute). + +See [method@Pango.FontDescription.set_size] +and [method@Pango.FontDescription.set_absolute_size]. whether the size for the font description is in - points or device units. Use pango_font_description_get_set_fields() to - find out if the size field of the font description was explicitly set or not. + points or device units. Use [method@Pango.FontDescription.get_set_fields] + to find out if the size field of the font description was explicitly + set or not. - a #PangoFontDescription + a `PangoFontDescription` Gets the stretch field of a font description. -See pango_font_description_set_stretch(). + +See [method@Pango.FontDescription.set_stretch]. - the stretch field for the font description. Use - pango_font_description_get_set_fields() to find out if - the field was explicitly set or not. + the stretch field for the font description. + Use [method@Pango.FontDescription.get_set_fields] to find + out if the field was explicitly set or not. - a #PangoFontDescription. + a `PangoFontDescription`. - Gets the style field of a #PangoFontDescription. See -pango_font_description_set_style(). + Gets the style field of a `PangoFontDescription`. + +See [method@Pango.FontDescription.set_style]. the style field for the font description. - Use pango_font_description_get_set_fields() to find out if - the field was explicitly set or not. + Use [method@Pango.FontDescription.get_set_fields] to + find out if the field was explicitly set or not. - a #PangoFontDescription + a `PangoFontDescription` - Gets the variant field of a #PangoFontDescription. See -pango_font_description_set_variant(). + Gets the variant field of a `PangoFontDescription`. + +See [method@Pango.FontDescription.set_variant]. - the variant field for the font description. Use - pango_font_description_get_set_fields() to find out if - the field was explicitly set or not. + the variant field for the font description. + Use [method@Pango.FontDescription.get_set_fields] to find + out if the field was explicitly set or not. - a #PangoFontDescription. + a `PangoFontDescription`. - Gets the variations field of a font description. See -pango_font_description_set_variations(). + Gets the variations field of a font description. + +See [method@Pango.FontDescription.set_variations]. - the varitions field for the font - description, or %NULL if not previously set. This - has the same life-time as the font description itself - and should not be freed. + the variations field for the font + description, or %NULL if not previously set. This has the same + life-time as the font description itself and should not be freed. - a #PangoFontDescription + a `PangoFontDescription` - Gets the weight field of a font description. See -pango_font_description_set_weight(). + Gets the weight field of a font description. + +See [method@Pango.FontDescription.set_weight]. - the weight field for the font description. Use - pango_font_description_get_set_fields() to find out if - the field was explicitly set or not. + the weight field for the font description. + Use [method@Pango.FontDescription.get_set_fields] to find + out if the field was explicitly set or not. - a #PangoFontDescription + a `PangoFontDescription` - Computes a hash of a #PangoFontDescription structure suitable -to be used, for example, as an argument to g_hash_table_new(). -The hash value is independent of @desc->mask. + Computes a hash of a `PangoFontDescription` structure. + +This is suitable to be used, for example, as an argument +to g_hash_table_new(). The hash value is independent of @desc->mask. the hash value. - a #PangoFontDescription + a `PangoFontDescription` Merges the fields that are set in @desc_to_merge into the fields in -@desc. If @replace_existing is %FALSE, only fields in @desc that +@desc. + +If @replace_existing is %FALSE, only fields in @desc that are not already set are affected. If %TRUE, then fields that are already set will be replaced as well. @@ -3476,11 +3118,12 @@ If @desc_to_merge is %NULL, this function performs nothing. - a #PangoFontDescription + a `PangoFontDescription` - the #PangoFontDescription to merge from, or %NULL + the `PangoFontDescription` to merge from, + or %NULL @@ -3492,20 +3135,23 @@ If @desc_to_merge is %NULL, this function performs nothing. - Like pango_font_description_merge(), but only a shallow copy is made -of the family name and other allocated fields. @desc can only be -used until @desc_to_merge is modified or freed. This is meant -to be used when the merged font description is only needed temporarily. + Merges the fields that are set in @desc_to_merge into the fields in +@desc, without copying allocated fields. + +This is like [method@Pango.FontDescription.merge], but only a shallow copy +is made of the family name and other allocated fields. @desc can only +be used until @desc_to_merge is modified or freed. This is meant to +be used when the merged font description is only needed temporarily. - a #PangoFontDescription + a `PangoFontDescription` - the #PangoFontDescription to merge from + the `PangoFontDescription` to merge from @@ -3517,37 +3163,40 @@ to be used when the merged font description is only needed temporarily. - Sets the size field of a font description, in device units. This is mutually -exclusive with pango_font_description_set_size() which sets the font size -in points. + Sets the size field of a font description, in device units. + +This is mutually exclusive with [method@Pango.FontDescription.set_size] +which sets the font size in points. - a #PangoFontDescription + a `PangoFontDescription` - the new size, in Pango units. There are %PANGO_SCALE Pango units in one - device unit. For an output backend where a device unit is a pixel, a @size - value of 10 * PANGO_SCALE gives a 10 pixel font. + the new size, in Pango units. There are %PANGO_SCALE Pango units + in one device unit. For an output backend where a device unit is a pixel, + a @size value of 10 * PANGO_SCALE gives a 10 pixel font. - Sets the family name field of a font description. The family + Sets the family name field of a font description. + +The family name represents a family of related font styles, and will -resolve to a particular #PangoFontFamily. In some uses of -#PangoFontDescription, it is also possible to use a comma +resolve to a particular `PangoFontFamily`. In some uses of +`PangoFontDescription`, it is also possible to use a comma separated list of family names for this field. - a #PangoFontDescription. + a `PangoFontDescription`. @@ -3557,40 +3206,43 @@ separated list of family names for this field. - Like pango_font_description_set_family(), except that no + Sets the family name field of a font description, without copying the string. + +This is like [method@Pango.FontDescription.set_family], except that no copy of @family is made. The caller must make sure that the -string passed in stays around until @desc has been freed -or the name is set again. This function can be used if -@family is a static string such as a C string literal, or -if @desc is only needed temporarily. +string passed in stays around until @desc has been freed or the +name is set again. This function can be used if @family is a static +string such as a C string literal, or if @desc is only needed temporarily. - a #PangoFontDescription + a `PangoFontDescription` - a string representing the family name. + a string representing the family name - Sets the gravity field of a font description. The gravity field -specifies how the glyphs should be rotated. If @gravity is + Sets the gravity field of a font description. + +The gravity field +specifies how the glyphs should be rotated. If @gravity is %PANGO_GRAVITY_AUTO, this actually unsets the gravity mask on the font description. -This function is seldom useful to the user. Gravity should normally -be set on a #PangoContext. +This function is seldom useful to the user. Gravity should normally +be set on a `PangoContext`. - a #PangoFontDescription + a `PangoFontDescription` @@ -3600,37 +3252,42 @@ be set on a #PangoContext. - Sets the size field of a font description in fractional points. This is mutually -exclusive with pango_font_description_set_absolute_size(). + Sets the size field of a font description in fractional points. + +This is mutually exclusive with +[method@Pango.FontDescription.set_absolute_size]. - a #PangoFontDescription + a `PangoFontDescription` - the size of the font in points, scaled by PANGO_SCALE. (That is, - a @size value of 10 * PANGO_SCALE is a 10 point font. The conversion - factor between points and device units depends on system configuration - and the output device. For screen display, a logical DPI of 96 is - common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3 - pixel font. Use pango_font_description_set_absolute_size() if you need - a particular size in device units. + the size of the font in points, scaled by %PANGO_SCALE. + (That is, a @size value of 10 * PANGO_SCALE is a 10 point font. + The conversion factor between points and device units depends on + system configuration and the output device. For screen display, a + logical DPI of 96 is common, in which case a 10 point font corresponds + to a 10 * (96 / 72) = 13.3 pixel font. + Use [method@Pango.FontDescription.set_absolute_size] if you need + a particular size in device units. - Sets the stretch field of a font description. The stretch field -specifies how narrow or wide the font should be. + Sets the stretch field of a font description. + +The [enum@Pango.Stretch] field specifies how narrow or +wide the font should be. - a #PangoFontDescription + a `PangoFontDescription` @@ -3640,20 +3297,22 @@ specifies how narrow or wide the font should be. - Sets the style field of a #PangoFontDescription. The -#PangoStyle enumeration describes whether the font is slanted and -the manner in which it is slanted; it can be either -#PANGO_STYLE_NORMAL, #PANGO_STYLE_ITALIC, or #PANGO_STYLE_OBLIQUE. -Most fonts will either have a italic style or an oblique -style, but not both, and font matching in Pango will -match italic specifications with oblique fonts and vice-versa -if an exact match is not found. + Sets the style field of a `PangoFontDescription`. + +The [enum@Pango.Style] enumeration describes whether the font is +slanted and the manner in which it is slanted; it can be either +%PANGO_STYLE_NORMAL, %PANGO_STYLE_ITALIC, or %PANGO_STYLE_OBLIQUE. + +Most fonts will either have a italic style or an oblique style, +but not both, and font matching in Pango will match italic +specifications with oblique fonts and vice-versa if an exact +match is not found. - a #PangoFontDescription + a `PangoFontDescription` @@ -3663,14 +3322,16 @@ if an exact match is not found. - Sets the variant field of a font description. The #PangoVariant -can either be %PANGO_VARIANT_NORMAL or %PANGO_VARIANT_SMALL_CAPS. + Sets the variant field of a font description. + +The [enum@Pango.Variant] can either be %PANGO_VARIANT_NORMAL +or %PANGO_VARIANT_SMALL_CAPS. - a #PangoFontDescription + a `PangoFontDescription` @@ -3680,11 +3341,15 @@ can either be %PANGO_VARIANT_NORMAL or %PANGO_VARIANT_SMALL_CAPS. - Sets the variations field of a font description. OpenType -font variations allow to select a font instance by specifying -values for a number of axes, such as width or weight. + Sets the variations field of a font description. + +OpenType font variations allow to select a font instance by +specifying values for a number of axes, such as width or weight. + +The format of the variations string is + + AXIS1=VALUE,AXIS2=VALUE... -The format of the variations string is AXIS1=VALUE,AXIS2=VALUE..., with each AXIS a 4 character tag that identifies a font axis, and each VALUE a floating point number. Unknown axes are ignored, and values are clamped to their allowed range. @@ -3696,7 +3361,7 @@ a font. Both harfbuzz or freetype have API for this. - a #PangoFontDescription. + a `PangoFontDescription`. @@ -3706,18 +3371,20 @@ a font. Both harfbuzz or freetype have API for this. - Like pango_font_description_set_variations(), except that no -copy of @variations is made. The caller must make sure that the -string passed in stays around until @desc has been freed + Sets the variations field of a font description. + +This is like [method@Pango.FontDescription.set_variations], except +that no copy of @variations is made. The caller must make sure that +the string passed in stays around until @desc has been freed or the name is set again. This function can be used if -@variations is a static string such as a C string literal, or -if @desc is only needed temporarily. +@variations is a static string such as a C string literal, +or if @desc is only needed temporarily. - a #PangoFontDescription + a `PangoFontDescription` @@ -3727,16 +3394,18 @@ if @desc is only needed temporarily. - Sets the weight field of a font description. The weight field + Sets the weight field of a font description. + +The weight field specifies how bold or light the font should be. In addition -to the values of the #PangoWeight enumeration, other intermediate -numeric values are possible. +to the values of the [enum@Pango.Weight] enumeration, other +intermediate numeric values are possible. - a #PangoFontDescription + a `PangoFontDescription` @@ -3746,47 +3415,51 @@ numeric values are possible. - Creates a filename representation of a font description. The -filename is identical to the result from calling -pango_font_description_to_string(), but with underscores instead of -characters that are untypical in filenames, and in lower case only. + Creates a filename representation of a font description. + +The filename is identical to the result from calling +[method@Pango.FontDescription.to_string], but with underscores +instead of characters that are untypical in filenames, and in +lower case only. a new string that must be freed with g_free(). - a #PangoFontDescription + a `PangoFontDescription` - Creates a string representation of a font description. See -pango_font_description_from_string() for a description of the -format of the string representation. The family list in the -string description will only have a terminating comma if the -last word of the list is a valid style option. + Creates a string representation of a font description. + +See [func@Pango.FontDescription.from_string] for a description +of the format of the string representation. The family list in +the string description will only have a terminating comma if +the last word of the list is a valid style option. a new string that must be freed with g_free(). - a #PangoFontDescription + a `PangoFontDescription` - Unsets some of the fields in a #PangoFontDescription. The unset -fields will get back to their default values. + Unsets some of the fields in a `PangoFontDescription`. + +The unset fields will get back to their default values. - a #PangoFontDescription + a `PangoFontDescription` @@ -3796,10 +3469,11 @@ fields will get back to their default values. - Creates a new font description from a string representation in the -form + Creates a new font description from a string representation. -"\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", +The string must have the form + + "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list @@ -3837,9 +3511,9 @@ size in the resulting font description will be set to 0. A typical example: -"Cantarell Italic Light 15 \@wght=200" + "Cantarell Italic Light 15 \@wght=200" - a new #PangoFontDescription. + a new `PangoFontDescription`. @@ -3851,30 +3525,29 @@ A typical example: - The #PangoFontFace structure is used to represent a group of fonts with -the same family, slant, weight, width, but varying sizes. + A `PangoFontFace` is used to represent a group of fonts with +the same family, slant, weight, and width, but varying sizes. Returns the family, style, variant, weight and stretch of -a #PangoFontFace. The size field of the resulting font description +a `PangoFontFace`. The size field of the resulting font description will be unset. - a newly-created #PangoFontDescription structure - holding the description of the face. Use pango_font_description_free() - to free the result. + a newly-created `PangoFontDescription` structure + holding the description of the face. Use [method@Pango.FontDescription.free] + to free the result. - a #PangoFontFace + a `PangoFontFace` Gets a name representing the style of this face among the -different faces in the #PangoFontFamily for the face. This -name is unique among all faces in the family and is suitable -for displaying to users. +different faces in the `PangoFontFamily` for the face. The +name is suitable for displaying to users. the face name for the face. This string is owned by the face object and must not be modified or freed. @@ -3882,27 +3555,26 @@ for displaying to users. - a #PangoFontFace. + a `PangoFontFace`. - Gets the #PangoFontFamily that @face -belongs to. + Gets the `PangoFontFamily` that @face belongs to. - the #PangoFontFamily + the `PangoFontFamily` - a #PangoFontFace + a `PangoFontFace` - Returns whether a #PangoFontFace is synthesized by the underlying + Returns whether a `PangoFontFace` is synthesized by the underlying font rendering engine from another face, perhaps by shearing, emboldening, or lightening it. @@ -3911,28 +3583,30 @@ or lightening it. - a #PangoFontFace + a `PangoFontFace` - List the available sizes for a font. This is only applicable to bitmap -fonts. For scalable fonts, stores %NULL at the location pointed to by -@sizes and 0 at the location pointed to by @n_sizes. The sizes returned -are in Pango units and are sorted in ascending order. + List the available sizes for a font. + +This is only applicable to bitmap fonts. For scalable fonts, stores +%NULL at the location pointed to by @sizes and 0 at the location pointed +to by @n_sizes. The sizes returned are in Pango units and are sorted +in ascending order. - a #PangoFontFace. + a `PangoFontFace`. - location to store a pointer to an array of int. This array - should be freed with g_free(). + location to store a pointer to an array of int. This array + should be freed with g_free(). @@ -3945,26 +3619,25 @@ are in Pango units and are sorted in ascending order. Returns the family, style, variant, weight and stretch of -a #PangoFontFace. The size field of the resulting font description +a `PangoFontFace`. The size field of the resulting font description will be unset. - a newly-created #PangoFontDescription structure - holding the description of the face. Use pango_font_description_free() - to free the result. + a newly-created `PangoFontDescription` structure + holding the description of the face. Use [method@Pango.FontDescription.free] + to free the result. - a #PangoFontFace + a `PangoFontFace` Gets a name representing the style of this face among the -different faces in the #PangoFontFamily for the face. This -name is unique among all faces in the family and is suitable -for displaying to users. +different faces in the `PangoFontFamily` for the face. The +name is suitable for displaying to users. the face name for the face. This string is owned by the face object and must not be modified or freed. @@ -3972,27 +3645,26 @@ for displaying to users. - a #PangoFontFace. + a `PangoFontFace`. - Gets the #PangoFontFamily that @face -belongs to. + Gets the `PangoFontFamily` that @face belongs to. - the #PangoFontFamily + the `PangoFontFamily` - a #PangoFontFace + a `PangoFontFace` - Returns whether a #PangoFontFace is synthesized by the underlying + Returns whether a `PangoFontFace` is synthesized by the underlying font rendering engine from another face, perhaps by shearing, emboldening, or lightening it. @@ -4001,28 +3673,30 @@ or lightening it. - a #PangoFontFace + a `PangoFontFace` - List the available sizes for a font. This is only applicable to bitmap -fonts. For scalable fonts, stores %NULL at the location pointed to by -@sizes and 0 at the location pointed to by @n_sizes. The sizes returned -are in Pango units and are sorted in ascending order. + List the available sizes for a font. + +This is only applicable to bitmap fonts. For scalable fonts, stores +%NULL at the location pointed to by @sizes and 0 at the location pointed +to by @n_sizes. The sizes returned are in Pango units and are sorted +in ascending order. - a #PangoFontFace. + a `PangoFontFace`. - location to store a pointer to an array of int. This array - should be freed with g_free(). + location to store a pointer to an array of int. This array + should be freed with g_free(). @@ -4050,7 +3724,7 @@ are in Pango units and are sorted in ascending order. - a #PangoFontFace. + a `PangoFontFace`. @@ -4059,14 +3733,14 @@ are in Pango units and are sorted in ascending order. - a newly-created #PangoFontDescription structure - holding the description of the face. Use pango_font_description_free() - to free the result. + a newly-created `PangoFontDescription` structure + holding the description of the face. Use [method@Pango.FontDescription.free] + to free the result. - a #PangoFontFace + a `PangoFontFace` @@ -4079,13 +3753,13 @@ are in Pango units and are sorted in ascending order. - a #PangoFontFace. + a `PangoFontFace`. - location to store a pointer to an array of int. This array - should be freed with g_free(). + location to store a pointer to an array of int. This array + should be freed with g_free(). @@ -4105,7 +3779,7 @@ are in Pango units and are sorted in ascending order. - a #PangoFontFace + a `PangoFontFace` @@ -4114,12 +3788,12 @@ are in Pango units and are sorted in ascending order. - the #PangoFontFamily + the `PangoFontFamily` - a #PangoFontFace + a `PangoFontFace` @@ -4141,33 +3815,37 @@ are in Pango units and are sorted in ascending order. - The #PangoFontFamily structure is used to represent a family of related -font faces. The faces in a family share a common design, but differ in -slant, weight, width and other aspects. + A `PangoFontFamily` is used to represent a family of related +font faces. + +The font faces in a family share a common design, but differ in +slant, weight, width or other aspects. - Gets the #PangoFontFace of @family with the given name. + Gets the `PangoFontFace` of @family with the given name. - the #PangoFontFace, - or %NULL if no face with the given name exists. + the `PangoFontFace`, + or %NULL if no face with the given name exists. - a #PangoFontFamily + a `PangoFontFamily` the name of a face. If the name is %NULL, - the family's default face (fontconfig calls it "Regular") - will be returned. + the family's default face (fontconfig calls it "Regular") + will be returned. - Gets the name of the family. The name is unique among all -fonts for the font backend and can be used in a #PangoFontDescription -to specify that a face from this family is desired. + Gets the name of the family. + +The name is unique among all fonts for the font backend and can +be used in a `PangoFontDescription` to specify that a face from +this family is desired. the name of the family. This string is owned by the family object and must not be modified or freed. @@ -4175,14 +3853,16 @@ to specify that a face from this family is desired. - a #PangoFontFamily + a `PangoFontFamily` A monospace font is a font designed for text display where the the -characters form a regular grid. For Western languages this would +characters form a regular grid. + +For Western languages this would mean that the advance width of all characters are the same, but this categorization also includes Asian fonts which include double-width characters: characters that occupy two grid cells. @@ -4190,16 +3870,16 @@ g_unichar_iswide() returns a result that indicates whether a character is typically double-width in a monospace font. The best way to find out the grid-cell size is to call -pango_font_metrics_get_approximate_digit_width(), since the results -of pango_font_metrics_get_approximate_char_width() may be affected -by double-width characters. +[method@Pango.FontMetrics.get_approximate_digit_width], since the +results of [method@Pango.FontMetrics.get_approximate_char_width] may +be affected by double-width characters. %TRUE if the family is monospace. - a #PangoFontFamily + a `PangoFontFamily` @@ -4213,26 +3893,27 @@ produce different faces. - a #PangoFontFamily + a `PangoFontFamily` - Lists the different font faces that make up @family. The faces -in a family share a common design, but differ in slant, weight, + Lists the different font faces that make up @family. + +The faces in a family share a common design, but differ in slant, weight, width and other aspects. - a #PangoFontFamily + a `PangoFontFamily` - location to store an array of pointers to #PangoFontFace objects, + location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. @@ -4246,29 +3927,31 @@ width and other aspects. - Gets the #PangoFontFace of @family with the given name. + Gets the `PangoFontFace` of @family with the given name. - the #PangoFontFace, - or %NULL if no face with the given name exists. + the `PangoFontFace`, + or %NULL if no face with the given name exists. - a #PangoFontFamily + a `PangoFontFamily` the name of a face. If the name is %NULL, - the family's default face (fontconfig calls it "Regular") - will be returned. + the family's default face (fontconfig calls it "Regular") + will be returned. - Gets the name of the family. The name is unique among all -fonts for the font backend and can be used in a #PangoFontDescription -to specify that a face from this family is desired. + Gets the name of the family. + +The name is unique among all fonts for the font backend and can +be used in a `PangoFontDescription` to specify that a face from +this family is desired. the name of the family. This string is owned by the family object and must not be modified or freed. @@ -4276,14 +3959,16 @@ to specify that a face from this family is desired. - a #PangoFontFamily + a `PangoFontFamily` A monospace font is a font designed for text display where the the -characters form a regular grid. For Western languages this would +characters form a regular grid. + +For Western languages this would mean that the advance width of all characters are the same, but this categorization also includes Asian fonts which include double-width characters: characters that occupy two grid cells. @@ -4291,16 +3976,16 @@ g_unichar_iswide() returns a result that indicates whether a character is typically double-width in a monospace font. The best way to find out the grid-cell size is to call -pango_font_metrics_get_approximate_digit_width(), since the results -of pango_font_metrics_get_approximate_char_width() may be affected -by double-width characters. +[method@Pango.FontMetrics.get_approximate_digit_width], since the +results of [method@Pango.FontMetrics.get_approximate_char_width] may +be affected by double-width characters. %TRUE if the family is monospace. - a #PangoFontFamily + a `PangoFontFamily` @@ -4314,26 +3999,27 @@ produce different faces. - a #PangoFontFamily + a `PangoFontFamily` - Lists the different font faces that make up @family. The faces -in a family share a common design, but differ in slant, weight, + Lists the different font faces that make up @family. + +The faces in a family share a common design, but differ in slant, weight, width and other aspects. - a #PangoFontFamily + a `PangoFontFamily` - location to store an array of pointers to #PangoFontFace objects, + location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. @@ -4361,12 +4047,12 @@ width and other aspects. - a #PangoFontFamily + a `PangoFontFamily` - location to store an array of pointers to #PangoFontFace objects, + location to store an array of pointers to `PangoFontFace` objects, or %NULL. This array should be freed with g_free() when it is no longer needed. @@ -4389,7 +4075,7 @@ width and other aspects. - a #PangoFontFamily + a `PangoFontFamily` @@ -4403,7 +4089,7 @@ width and other aspects. - a #PangoFontFamily + a `PangoFontFamily` @@ -4417,7 +4103,7 @@ width and other aspects. - a #PangoFontFamily + a `PangoFontFamily` @@ -4426,19 +4112,19 @@ width and other aspects. - the #PangoFontFace, - or %NULL if no face with the given name exists. + the `PangoFontFace`, + or %NULL if no face with the given name exists. - a #PangoFontFamily + a `PangoFontFamily` the name of a face. If the name is %NULL, - the family's default face (fontconfig calls it "Regular") - will be returned. + the family's default face (fontconfig calls it "Regular") + will be returned. @@ -4453,31 +4139,25 @@ width and other aspects. - The #PangoFontMap represents the set of fonts available for a -particular rendering system. This is a virtual object with -implementations being specific to particular rendering systems. To -create an implementation of a #PangoFontMap, the rendering-system -specific code should allocate a larger structure that contains a nested -#PangoFontMap, fill in the <structfield>klass</structfield> member of the nested #PangoFontMap with a -pointer to a appropriate #PangoFontMapClass, then call -pango_font_map_init() on the structure. + A `PangoFontMap` represents the set of fonts available for a +particular rendering system. -The #PangoFontMap structure contains one member which the implementation -fills in. +This is a virtual object with implementations being specific to +particular rendering systems. - Forces a change in the context, which will cause any #PangoContext + Forces a change in the context, which will cause any `PangoContext` using this fontmap to change. This function is only useful when implementing a new backend for Pango, something applications won't do. Backends should -call this function if they have attached extra data to the context -and such data is changed. +call this function if they have attached extra data to the +context and such data is changed. - a #PangoFontMap + a `PangoFontMap` @@ -4498,12 +4178,12 @@ and such data is changed. Gets a font family by name. - the #PangoFontFamily + the `PangoFontFamily` - a #PangoFontMap + a `PangoFontMap` @@ -4513,24 +4193,25 @@ and such data is changed. - Returns the current serial number of @fontmap. The serial number is -initialized to an small number larger than zero when a new fontmap -is created and is increased whenever the fontmap is changed. It may -wrap, but will never have the value 0. Since it can wrap, never compare -it with "less than", always use "not equals". + Returns the current serial number of @fontmap. + +The serial number is initialized to an small number larger than zero +when a new fontmap is created and is increased whenever the fontmap +is changed. It may wrap, but will never have the value 0. Since it can +wrap, never compare it with "less than", always use "not equals". The fontmap can only be changed using backend-specific API, like changing fontmap resolution. -This can be used to automatically detect changes to a #PangoFontMap, like -in #PangoContext. +This can be used to automatically detect changes to a `PangoFontMap`, +like in `PangoContext`. The current serial number of @fontmap. - a #PangoFontMap + a `PangoFontMap` @@ -4542,12 +4223,13 @@ in #PangoContext. - a #PangoFontMap + a `PangoFontMap` - location to store a pointer to an array of #PangoFontFamily *. - This array should be freed with g_free(). + location to + store a pointer to an array of `PangoFontFamily` *. + This array should be freed with g_free(). @@ -4561,21 +4243,21 @@ in #PangoContext. Load the font in the fontmap that is the closest match for @desc. - the newly allocated #PangoFont - loaded, or %NULL if no font matched. + the newly allocated `PangoFont` + loaded, or %NULL if no font matched. - a #PangoFontMap + a `PangoFontMap` - the #PangoContext the font will be used with + the `PangoContext` the font will be used with - a #PangoFontDescription describing the font to load + a `PangoFontDescription` describing the font to load @@ -4585,63 +4267,64 @@ in #PangoContext. a font matching @desc. the newly allocated - #PangoFontset loaded, or %NULL if no font matched. + `PangoFontset` loaded, or %NULL if no font matched. - a #PangoFontMap + a `PangoFontMap` - the #PangoContext the font will be used with + the `PangoContext` the font will be used with - a #PangoFontDescription describing the font to load + a `PangoFontDescription` describing the font to load - a #PangoLanguage the fonts will be used for + a `PangoLanguage` the fonts will be used for - Forces a change in the context, which will cause any #PangoContext + Forces a change in the context, which will cause any `PangoContext` using this fontmap to change. This function is only useful when implementing a new backend for Pango, something applications won't do. Backends should -call this function if they have attached extra data to the context -and such data is changed. +call this function if they have attached extra data to the +context and such data is changed. - a #PangoFontMap + a `PangoFontMap` - Creates a #PangoContext connected to @fontmap. This is equivalent -to pango_context_new() followed by pango_context_set_font_map(). + Creates a `PangoContext` connected to @fontmap. + +This is equivalent to [ctor@Pango.Context.new] followed by +[method@Pango.Context.set_font_map]. If you are using Pango as part of a higher-level system, -that system may have it's own way of create a #PangoContext. -For instance, the GTK+ toolkit has, among others, -gdk_pango_context_get_for_screen(), and -gtk_widget_get_pango_context(). Use those instead. +that system may have it's own way of create a `PangoContext`. +For instance, the GTK toolkit has, among others, +gtk_widget_get_pango_context(). Use those instead. - the newly allocated #PangoContext, - which should be freed with g_object_unref(). + the newly allocated `PangoContext`, + which should be freed with g_object_unref(). - a #PangoFontMap + a `PangoFontMap` @@ -4649,12 +4332,12 @@ gtk_widget_get_pango_context(). Use those instead. Gets a font family by name. - the #PangoFontFamily + the `PangoFontFamily` - a #PangoFontMap + a `PangoFontMap` @@ -4664,24 +4347,25 @@ gtk_widget_get_pango_context(). Use those instead. - Returns the current serial number of @fontmap. The serial number is -initialized to an small number larger than zero when a new fontmap -is created and is increased whenever the fontmap is changed. It may -wrap, but will never have the value 0. Since it can wrap, never compare -it with "less than", always use "not equals". + Returns the current serial number of @fontmap. + +The serial number is initialized to an small number larger than zero +when a new fontmap is created and is increased whenever the fontmap +is changed. It may wrap, but will never have the value 0. Since it can +wrap, never compare it with "less than", always use "not equals". The fontmap can only be changed using backend-specific API, like changing fontmap resolution. -This can be used to automatically detect changes to a #PangoFontMap, like -in #PangoContext. +This can be used to automatically detect changes to a `PangoFontMap`, +like in `PangoContext`. The current serial number of @fontmap. - a #PangoFontMap + a `PangoFontMap` @@ -4693,12 +4377,13 @@ in #PangoContext. - a #PangoFontMap + a `PangoFontMap` - location to store a pointer to an array of #PangoFontFamily *. - This array should be freed with g_free(). + location to + store a pointer to an array of `PangoFontFamily` *. + This array should be freed with g_free(). @@ -4712,21 +4397,21 @@ in #PangoContext. Load the font in the fontmap that is the closest match for @desc. - the newly allocated #PangoFont - loaded, or %NULL if no font matched. + the newly allocated `PangoFont` + loaded, or %NULL if no font matched. - a #PangoFontMap + a `PangoFontMap` - the #PangoContext the font will be used with + the `PangoContext` the font will be used with - a #PangoFontDescription describing the font to load + a `PangoFontDescription` describing the font to load @@ -4736,24 +4421,24 @@ in #PangoContext. a font matching @desc. the newly allocated - #PangoFontset loaded, or %NULL if no font matched. + `PangoFontset` loaded, or %NULL if no font matched. - a #PangoFontMap + a `PangoFontMap` - the #PangoContext the font will be used with + the `PangoContext` the font will be used with - a #PangoFontDescription describing the font to load + a `PangoFontDescription` describing the font to load - a #PangoLanguage the fonts will be used for + a `PangoLanguage` the fonts will be used for @@ -4763,30 +4448,30 @@ a font matching @desc. - The #PangoFontMapClass structure holds the virtual functions for -a particular #PangoFontMap implementation. + The `PangoFontMapClass` structure holds the virtual functions for +a particular `PangoFontMap` implementation. - parent #GObjectClass. + parent `GObjectClass` - the newly allocated #PangoFont - loaded, or %NULL if no font matched. + the newly allocated `PangoFont` + loaded, or %NULL if no font matched. - a #PangoFontMap + a `PangoFontMap` - the #PangoContext the font will be used with + the `PangoContext` the font will be used with - a #PangoFontDescription describing the font to load + a `PangoFontDescription` describing the font to load @@ -4799,12 +4484,13 @@ a particular #PangoFontMap implementation. - a #PangoFontMap + a `PangoFontMap` - location to store a pointer to an array of #PangoFontFamily *. - This array should be freed with g_free(). + location to + store a pointer to an array of `PangoFontFamily` *. + This array should be freed with g_free(). @@ -4820,24 +4506,24 @@ a particular #PangoFontMap implementation. the newly allocated - #PangoFontset loaded, or %NULL if no font matched. + `PangoFontset` loaded, or %NULL if no font matched. - a #PangoFontMap + a `PangoFontMap` - the #PangoContext the font will be used with + the `PangoContext` the font will be used with - a #PangoFontDescription describing the font to load + a `PangoFontDescription` describing the font to load - a #PangoLanguage the fonts will be used for + a `PangoLanguage` the fonts will be used for @@ -4856,7 +4542,7 @@ can handle fonts of this fonts loaded with this fontmap. - a #PangoFontMap + a `PangoFontMap` @@ -4869,7 +4555,7 @@ can handle fonts of this fonts loaded with this fontmap. - a #PangoFontMap + a `PangoFontMap` @@ -4878,12 +4564,12 @@ can handle fonts of this fonts loaded with this fontmap. - the #PangoFontFamily + the `PangoFontFamily` - a #PangoFontMap + a `PangoFontMap` @@ -4910,8 +4596,8 @@ can handle fonts of this fonts loaded with this fontmap. - The bits in a #PangoFontMask correspond to fields in a -#PangoFontDescription that have been set. + The bits in a `PangoFontMask` correspond to the set fields in a +`PangoFontDescription`. the font family is specified. @@ -4938,11 +4624,13 @@ can handle fonts of this fonts loaded with this fontmap. - A #PangoFontMetrics structure holds the overall metric information -for a font (possibly restricted to a script). The fields of this -structure are private to implementations of a font backend. See -the documentation of the corresponding getters for documentation -of their meaning. + A `PangoFontMetrics` structure holds the overall metric information +for a font. + +The information in a `PangoFontMetrics` structure may be restricted +to a script. The fields of this structure are private to implementations +of a font backend. See the documentation of the corresponding getters +for documentation of their meaning. @@ -4975,6 +4663,7 @@ of their meaning. Gets the approximate character width for a font metrics structure. + This is merely a representative value useful, for example, for determining the initial size for a window. Actual characters in text will be wider and narrower than this. @@ -4984,13 +4673,14 @@ text will be wider and narrower than this. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure Gets the approximate digit width for a font metrics structure. + This is merely a representative value useful, for example, for determining the initial size for a window. Actual digits in text can be wider or narrower than this, though this value @@ -5002,48 +4692,51 @@ pango_font_metrics_get_approximate_char_width() for digits. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure - Gets the ascent from a font metrics structure. The ascent is -the distance from the baseline to the logical top of a line -of text. (The logical top may be above or below the top of the -actual drawn ink. It is necessary to lay out the text to figure -where the ink will be.) + Gets the ascent from a font metrics structure. + +The ascent is the distance from the baseline to the logical top +of a line of text. (The logical top may be above or below the top +of the actual drawn ink. It is necessary to lay out the text to +figure where the ink will be.) the ascent, in Pango units. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure - Gets the descent from a font metrics structure. The descent is -the distance from the baseline to the logical bottom of a line -of text. (The logical bottom may be above or below the bottom of the -actual drawn ink. It is necessary to lay out the text to figure -where the ink will be.) + Gets the descent from a font metrics structure. + +The descent is the distance from the baseline to the logical bottom +of a line of text. (The logical bottom may be above or below the +bottom of the actual drawn ink. It is necessary to lay out the text +to figure where the ink will be.) the descent, in Pango units. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure - Gets the line height from a font metrics structure. The -line height is the distance between successive baselines + Gets the line height from a font metrics structure. + +The line height is the distance between successive baselines in wrapped text. If the line height is not available, 0 is returned. @@ -5053,14 +4746,15 @@ If the line height is not available, 0 is returned. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure Gets the suggested position to draw the strikethrough. -The value returned is the distance <emphasis>above</emphasis> the + +The value returned is the distance *above* the baseline of the top of the strikethrough. the suggested strikethrough position, in Pango units. @@ -5068,7 +4762,7 @@ baseline of the top of the strikethrough. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure @@ -5081,24 +4775,24 @@ baseline of the top of the strikethrough. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure Gets the suggested position to draw the underline. -The value returned is the distance <emphasis>above</emphasis> the -baseline of the top of the underline. Since most fonts have -underline positions beneath the baseline, this value is typically -negative. + +The value returned is the distance *above* the baseline of the top +of the underline. Since most fonts have underline positions beneath +the baseline, this value is typically negative. the suggested underline position, in Pango units. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure @@ -5111,7 +4805,7 @@ negative. - a #PangoFontMetrics structure + a `PangoFontMetrics` structure @@ -5124,42 +4818,43 @@ negative. - a #PangoFontMetrics structure, may be %NULL + a `PangoFontMetrics` structure, may be %NULL - Decrease the reference count of a font metrics structure by one. If -the result is zero, frees the structure and any associated -memory. + Decrease the reference count of a font metrics structure by one. +If the result is zero, frees the structure and any associated memory. - a #PangoFontMetrics structure, may be %NULL + a `PangoFontMetrics` structure, may be %NULL - A #PangoFontset represents a set of #PangoFont to use -when rendering text. It is the result of resolving a -#PangoFontDescription against a particular #PangoContext. -It has operations for finding the component font for -a particular Unicode character, and for finding a composite -set of metrics for the entire fontset. + A `PangoFontset` represents a set of `PangoFont` to use when rendering text. + +A `PAngoFontset` is the result of resolving a `PangoFontDescription` +against a particular `PangoContext`. It has operations for finding the +component font for a particular Unicode character, and for finding a +composite set of metrics for the entire fontset. Iterates through all the fonts in a fontset, calling @func for -each one. If @func returns %TRUE, that stops the iteration. +each one. + +If @func returns %TRUE, that stops the iteration. - a #PangoFontset + a `PangoFontset` @@ -5173,16 +4868,15 @@ each one. If @func returns %TRUE, that stops the iteration. - Returns the font in the fontset that contains the best glyph for the -Unicode character @wc. + Returns the font in the fontset that contains the best glyph for a +Unicode character. - a #PangoFont. The caller must call - g_object_unref when finished with the font. + a `PangoFont` - a #PangoFontset + a `PangoFontset` @@ -5204,26 +4898,27 @@ Unicode character @wc. Get overall metric information for the fonts in the fontset. - a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - when finished using the object. + a `PangoFontMetrics` object - a #PangoFontset + a `PangoFontset` Iterates through all the fonts in a fontset, calling @func for -each one. If @func returns %TRUE, that stops the iteration. +each one. + +If @func returns %TRUE, that stops the iteration. - a #PangoFontset + a `PangoFontset` @@ -5237,16 +4932,15 @@ each one. If @func returns %TRUE, that stops the iteration. - Returns the font in the fontset that contains the best glyph for the -Unicode character @wc. + Returns the font in the fontset that contains the best glyph for a +Unicode character. - a #PangoFont. The caller must call - g_object_unref when finished with the font. + a `PangoFont` - a #PangoFontset + a `PangoFontset` @@ -5258,13 +4952,12 @@ Unicode character @wc. Get overall metric information for the fonts in the fontset. - a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - when finished using the object. + a `PangoFontMetrics` object - a #PangoFontset + a `PangoFontset` @@ -5274,22 +4967,21 @@ Unicode character @wc. - The #PangoFontsetClass structure holds the virtual functions for -a particular #PangoFontset implementation. + The `PangoFontsetClass` structure holds the virtual functions for +a particular `PangoFontset` implementation. - parent #GObjectClass. + parent `GObjectClass` - a #PangoFont. The caller must call - g_object_unref when finished with the font. + a `PangoFont` - a #PangoFontset + a `PangoFontset` @@ -5302,13 +4994,12 @@ a particular #PangoFontset implementation. - a #PangoFontMetrics object. The caller must call pango_font_metrics_unref() - when finished using the object. + a `PangoFontMetrics` object - a #PangoFontset + a `PangoFontset` @@ -5333,7 +5024,7 @@ a particular #PangoFontset implementation. - a #PangoFontset + a `PangoFontset` @@ -5377,15 +5068,15 @@ a particular #PangoFontset implementation. - A callback function used by pango_fontset_foreach() when enumerating -the fonts in a fontset. + Callback used by pango_fontset_foreach() when enumerating +fonts in a fontset. if %TRUE, stop iteration and return immediately. - a #PangoFontset + a `PangoFontset` @@ -5399,20 +5090,20 @@ the fonts in a fontset. - #PangoFontsetSimple is a implementation of the abstract -#PangoFontset base class in terms of an array of fonts, -which the creator provides when constructing the -#PangoFontsetSimple. + `PangoFontsetSimple` is a implementation of the abstract +`PangoFontset` base class as an array of fonts. + +When creating a `PangoFontsetSimple`, you have to provide +the array of fonts that make up the fontset. - Creates a new #PangoFontsetSimple for the given language. + Creates a new `PangoFontsetSimple` for the given language. - the newly allocated #PangoFontsetSimple, which should - be freed with g_object_unref(). + the newly allocated `PangoFontsetSimple` - a #PangoLanguage tag + a `PangoLanguage` tag @@ -5424,11 +5115,11 @@ which the creator provides when constructing the - a #PangoFontsetSimple. + a `PangoFontsetSimple`. - a #PangoFont. + a `PangoFont`. @@ -5436,12 +5127,12 @@ which the creator provides when constructing the Returns the number of fonts in the fontset. - the size of @fontset. + the size of @fontset - a #PangoFontsetSimple. + a `PangoFontsetSimple`. @@ -5449,7 +5140,7 @@ which the creator provides when constructing the - The way this unknown glyphs are rendered is backend specific. For example, + The way this unknown glyphs are rendered is backend specific. For example, a box with the hexadecimal Unicode code-point of the character written in it is what is done in the most common backends. @@ -5459,46 +5150,48 @@ is what is done in the most common backends. - The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a - special meaning, which is a zero-width empty glyph. This is useful for -example in shaper modules, to use as the glyph for various zero-width -Unicode characters (those passing pango_is_zero_width()). + A `PangoGlyph` value that indicates a zero-width empty glpyh. + +This is useful for example in shaper modules, to use as the glyph for +various zero-width Unicode characters (those passing [func@is_zero_width]). - The %PANGO_GLYPH_INVALID_INPUT macro represents a #PangoGlyph value that has a -special meaning of invalid input. #PangoLayout produces one such glyph -per invalid input UTF-8 byte and such a glyph is rendered as a crossed -box. + A `PangoGlyph` value for invalid input. + +`PangoLayout` produces one such glyph per invalid input UTF-8 byte and such +a glyph is rendered as a crossed box. Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG -on. +set. - The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to -a #gunichar value of a valid Unicode character, to produce a #PangoGlyph -value, representing an unknown-character glyph for the respective #gunichar. + Flag used in `PangoGlyph` to turn a `gunichar` value of a valid Unicode +character into an unknown-character glyph for that `gunichar`. + +Such unknown-character glyphs may be rendered as a 'hex box'. - Whether a #PangoGravity represents a gravity that results in reversal of text direction. + Whether a `PangoGravity` represents a gravity that results in reversal +of text direction. - the #PangoGravity to check + the `PangoGravity` to check - Whether a #PangoGravity represents vertical writing directions. + Whether a `PangoGravity` represents vertical writing directions. - the #PangoGravity to check + the `PangoGravity` to check - The #PangoGlyphGeometry structure contains width and positioning + The `PangoGlyphGeometry` structure contains width and positioning information for a single glyph. the logical width to use for the the character. @@ -5514,9 +5207,8 @@ information for a single glyph. - The #PangoGlyphInfo structure represents a single glyph together with -positioning information and visual attributes. -It contains the following fields. + A `PangoGlyphInfo` structure represents a single glyph with +positioning information and visual attributes. the glyph itself. @@ -5531,32 +5223,34 @@ It contains the following fields. - A #PangoGlyphItem is a pair of a #PangoItem and the glyphs -resulting from shaping the text corresponding to an item. -As an example of the usage of #PangoGlyphItem, the results -of shaping text with #PangoLayout is a list of #PangoLayoutLine, -each of which contains a list of #PangoGlyphItem. + A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs +resulting from shaping the items text. + +As an example of the usage of `PangoGlyphItem`, the results +of shaping text with `PangoLayout` is a list of `PangoLayoutLine`, +each of which contains a list of `PangoGlyphItem`. - corresponding #PangoItem. + corresponding `PangoItem` - corresponding #PangoGlyphString. + corresponding `PangoGlyphString` - Splits a shaped item (PangoGlyphItem) into multiple items based -on an attribute list. The idea is that if you have attributes -that don't affect shaping, such as color or underline, to avoid -affecting shaping, you filter them out (pango_attr_list_filter()), -apply the shaping process and then reapply them to the result using -this function. + Splits a shaped item (`PangoGlyphItem`) into multiple items based +on an attribute list. + +The idea is that if you have attributes that don't affect shaping, +such as color or underline, to avoid affecting shaping, you filter +them out ([method@Pango.AttrList.filter]), apply the shaping process +and then reapply them to the result using this function. All attributes that start or end inside a cluster are applied to that cluster; for instance, if half of a cluster is underlined and the other-half strikethrough, then the cluster will end up with both underline and strikethrough attributes. In these -cases, it may happen that item->extra_attrs for some of the +cases, it may happen that @item->extra_attrs for some of the result items can have multiple attributes of the same type. This function takes ownership of @glyph_item; it will be reused @@ -5564,7 +5258,7 @@ as one of the elements in the list. a list of glyph items resulting from splitting @glyph_item. Free - the elements using pango_glyph_item_free(), the list using + the elements using [method@Pango.GlyphItem.free], the list using g_slist_free(). @@ -5580,64 +5274,62 @@ as one of the elements in the list. - a #PangoAttrList + a `PangoAttrList` - Make a deep copy of an existing #PangoGlyphItem structure. + Make a deep copy of an existing `PangoGlyphItem` structure. - the newly allocated #PangoGlyphItem, which should - be freed with pango_glyph_item_free(), or %NULL - if @orig was %NULL. + the newly allocated `PangoGlyphItem` - a #PangoGlyphItem, may be %NULL + a `PangoGlyphItem` - Frees a #PangoGlyphItem and resources to which it points. + Frees a `PangoGlyphItem` and resources to which it points. - a #PangoGlyphItem, may be %NULL + a `PangoGlyphItem` - Given a #PangoGlyphItem and the corresponding -text, determine the screen width corresponding to each character. When -multiple characters compose a single cluster, the width of the entire -cluster is divided equally among the characters. + Given a `PangoGlyphItem` and the corresponding text, determine the +width corresponding to each character. -See also pango_glyph_string_get_logical_widths(). +When multiple characters compose a single cluster, the width of the +entire cluster is divided equally among the characters. + +See also [method@Pango.GlyphString.get_logical_widths]. - a #PangoGlyphItem + a `PangoGlyphItem` text that @glyph_item corresponds to (glyph_item->item->offset is an offset from the - start of @text) + start of @text) an array whose length is the number of - characters in glyph_item (equal to - glyph_item->item->num_chars) to be filled in with - the resulting character widths. + characters in glyph_item (equal to glyph_item->item->num_chars) + to be filled in with the resulting character widths. @@ -5652,13 +5344,13 @@ give the effect of typographic letter spacing. - a #PangoGlyphItem + a `PangoGlyphItem` text that @glyph_item corresponds to (glyph_item->item->offset is an offset from the - start of @text) + start of @text) @@ -5680,23 +5372,24 @@ give the effect of typographic letter spacing. Modifies @orig to cover only the text after @split_index, and returns a new item that covers the text before @split_index that -used to be in @orig. You can think of @split_index as the length of -the returned item. @split_index may not be 0, and it may not be -greater than or equal to the length of @orig (that is, there must -be at least one byte assigned to each item, you can't create a -zero-length item). +used to be in @orig. + +You can think of @split_index as the length of the returned item. +@split_index may not be 0, and it may not be greater than or equal +to the length of @orig (that is, there must be at least one byte +assigned to each item, you can't create a zero-length item). This function is similar in function to pango_item_split() (and uses it internally.) the newly allocated item representing text before - @split_index, which should be freed - with pango_glyph_item_free(). + @split_index, which should be freed + with pango_glyph_item_free(). - a #PangoItem + a `PangoItem` @@ -5704,50 +5397,54 @@ it internally.) - byte index of position to split item, relative to the start of the item + byte index of position to split item, relative to the + start of the item - A #PangoGlyphItemIter is an iterator over the clusters in a -#PangoGlyphItem. The <firstterm>forward direction</firstterm> of the -iterator is the logical direction of text. That is, with increasing -@start_index and @start_char values. If @glyph_item is right-to-left -(that is, if <literal>@glyph_item->item->analysis.level</literal> is odd), + A `PangoGlyphItemIter` is an iterator over the clusters in a +`PangoGlyphItem`. + +The *forward direction* of the iterator is the logical direction of text. +That is, with increasing @start_index and @start_char values. If @glyph_item +is right-to-left (that is, if `glyph_item->item->analysis.level` is odd), then @start_glyph decreases as the iterator moves forward. Moreover, in right-to-left cases, @start_glyph is greater than @end_glyph. -An iterator should be initialized using either of -pango_glyph_item_iter_init_start() and +An iterator should be initialized using either +pango_glyph_item_iter_init_start() or pango_glyph_item_iter_init_end(), for forward and backward iteration respectively, and walked over using any desired mixture of pango_glyph_item_iter_next_cluster() and -pango_glyph_item_iter_prev_cluster(). A common idiom for doing a -forward iteration over the clusters is: -<programlisting> +pango_glyph_item_iter_prev_cluster(). + +A common idiom for doing a forward iteration over the clusters is: + +``` PangoGlyphItemIter cluster_iter; gboolean have_cluster; -for (have_cluster = pango_glyph_item_iter_init_start (&amp;cluster_iter, +for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter, glyph_item, text); have_cluster; - have_cluster = pango_glyph_item_iter_next_cluster (&amp;cluster_iter)) + have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter)) { ... } -</programlisting> +``` Note that @text is the start of the text for layout, which is then -indexed by <literal>@glyph_item->item->offset</literal> to get to the -text of @glyph_item. The @start_index and @end_index values can directly -index into @text. The @start_glyph, @end_glyph, @start_char, and @end_char -values however are zero-based for the @glyph_item. For each cluster, the -item pointed at by the start variables is included in the cluster while -the one pointed at by end variables is not. +indexed by `glyph_item->item->offset` to get to the text of @glyph_item. +The @start_index and @end_index values can directly index into @text. The +@start_glyph, @end_glyph, @start_char, and @end_char values however are +zero-based for the @glyph_item. For each cluster, the item pointed at by +the start variables is included in the cluster while the one pointed at by +end variables is not. -None of the members of a #PangoGlyphItemIter should be modified manually. +None of the members of a `PangoGlyphItemIter` should be modified manually. @@ -5773,43 +5470,42 @@ None of the members of a #PangoGlyphItemIter should be modified manually. - Make a shallow copy of an existing #PangoGlyphItemIter structure. + Make a shallow copy of an existing `PangoGlyphItemIter` structure. - the newly allocated #PangoGlyphItemIter, which should - be freed with pango_glyph_item_iter_free(), or %NULL - if @orig was %NULL. + the newly allocated `PangoGlyphItemIter` - a #PangoGlyphItemIter, may be %NULL + a `PangoGlyphItem`Iter - Frees a #PangoGlyphItemIter created by pango_glyph_item_iter_copy(). + Frees a `PangoGlyphItem`Iter. - a #PangoGlyphItemIter, may be %NULL + a `PangoGlyphItemIter` - Initializes a #PangoGlyphItemIter structure to point to the + Initializes a `PangoGlyphItemIter` structure to point to the last cluster in a glyph item. -See #PangoGlyphItemIter for details of cluster orders. + +See `PangoGlyphItemIter` for details of cluster orders. %FALSE if there are no clusters in the glyph item - a #PangoGlyphItemIter + a `PangoGlyphItemIter` @@ -5823,16 +5519,17 @@ See #PangoGlyphItemIter for details of cluster orders. - Initializes a #PangoGlyphItemIter structure to point to the + Initializes a `PangoGlyphItemIter` structure to point to the first cluster in a glyph item. -See #PangoGlyphItemIter for details of cluster orders. + +See `PangoGlyphItemIter` for details of cluster orders. %FALSE if there are no clusters in the glyph item - a #PangoGlyphItemIter + a `PangoGlyphItemIter` @@ -5847,86 +5544,87 @@ See #PangoGlyphItemIter for details of cluster orders. Advances the iterator to the next cluster in the glyph item. -See #PangoGlyphItemIter for details of cluster orders. + +See `PangoGlyphItemIter` for details of cluster orders. - %TRUE if the iterator was advanced, %FALSE if we were already on the - last cluster. + %TRUE if the iterator was advanced, + %FALSE if we were already on the last cluster. - a #PangoGlyphItemIter + a `PangoGlyphItemIter` Moves the iterator to the preceding cluster in the glyph item. -See #PangoGlyphItemIter for details of cluster orders. +See `PangoGlyphItemIter` for details of cluster orders. - %TRUE if the iterator was moved, %FALSE if we were already on the - first cluster. + %TRUE if the iterator was moved, + %FALSE if we were already on the first cluster. - a #PangoGlyphItemIter + a `PangoGlyphItemIter` - The #PangoGlyphString structure is used to store strings -of glyphs with geometry and visual attribute information. -The storage for the glyph information is owned -by the structure which simplifies memory management. + A `PangoGlyphString` is used to store strings of glyphs with geometry +and visual attribute information. + +The storage for the glyph information is owned by the structure +which simplifies memory management. number of the glyphs in this glyph string. array of glyph information - for the glyph string. + for the glyph string. logical cluster info, indexed by the byte index - within the text corresponding to the glyph string. + within the text corresponding to the glyph string. - Create a new #PangoGlyphString. + Create a new `PangoGlyphString`. - the newly allocated #PangoGlyphString, which - should be freed with pango_glyph_string_free(). + the newly allocated `PangoGlyphString`, which + should be freed with [method@Pango.GlyphString.free]. Copy a glyph string and associated storage. - the newly allocated #PangoGlyphString, - which should be freed with pango_glyph_string_free(), - or %NULL if @string was %NULL. + the newly allocated `PangoGlyphString` - a #PangoGlyphString, may be %NULL + a `PangoGlyphString` - Compute the logical and ink extents of a glyph string. See the documentation -for pango_font_get_glyph_extents() for details about the interpretation -of the rectangles. + Compute the logical and ink extents of a glyph string. + +See the documentation for [method@Pango.Font.get_glyph_extents] for details +about the interpretation of the rectangles. Examples of logical (red) and ink (green) rects: @@ -5936,36 +5634,35 @@ Examples of logical (red) and ink (green) rects: - a #PangoGlyphString + a `PangoGlyphString` - a #PangoFont + a `PangoFont` - rectangle used to store the extents of the glyph string - as drawn or %NULL to indicate that the result is not needed. + rectangle used to store the extents of the glyph string as drawn - rectangle used to store the logical extents of the - glyph string or %NULL to indicate that the result is not needed. + rectangle used to store the logical extents of the glyph string - Computes the extents of a sub-portion of a glyph string. The extents are -relative to the start of the glyph string range (the origin of their -coordinate system is at the start of the range, not at the start of the entire -glyph string). + Computes the extents of a sub-portion of a glyph string. + +The extents are relative to the start of the glyph string range +(the origin of their coordinate system is at the start of the range, +not at the start of the entire glyph string). - a #PangoGlyphString + a `PangoGlyphString` @@ -5974,23 +5671,21 @@ glyph string). end index (the range is the set of bytes with - indices such that start <= index < end) + indices such that start <= index < end) - a #PangoFont + a `PangoFont` rectangle used to - store the extents of the glyph string range as drawn or - %NULL to indicate that the result is not needed. + store the extents of the glyph string range as drawn rectangle used to - store the logical extents of the glyph string range or - %NULL to indicate that the result is not needed. + store the logical extents of the glyph string range @@ -6002,24 +5697,25 @@ glyph string). - a #PangoGlyphString, may be %NULL + a `PangoGlyphString`, may be %NULL - Given a #PangoGlyphString resulting from pango_shape() and the corresponding -text, determine the screen width corresponding to each character. When -multiple characters compose a single cluster, the width of the entire -cluster is divided equally among the characters. + Given a `PangoGlyphString` and corresponding text, determine the width +corresponding to each character. -See also pango_glyph_item_get_logical_widths(). +When multiple characters compose a single cluster, the width of the +entire cluster is divided equally among the characters. + +See also [method@Pango.GlyphItem.get_logical_widths]. - a #PangoGlyphString + a `PangoGlyphString` @@ -6036,9 +5732,8 @@ See also pango_glyph_item_get_logical_widths(). an array whose length is the number of - characters in text (equal to g_utf8_strlen (text, - length) unless text has NUL bytes) to be filled in - with the resulting character widths. + characters in text (equal to `g_utf8_strlen (text, length)` unless + text has `NUL` bytes) to be filled in with the resulting character widths. @@ -6046,31 +5741,35 @@ See also pango_glyph_item_get_logical_widths(). - Computes the logical width of the glyph string as can also be computed -using pango_glyph_string_extents(). However, since this only computes the -width, it's much faster. This is in fact only a convenience function that -computes the sum of geometry.width for each glyph in the @glyphs. + Computes the logical width of the glyph string. + +This can also be computed using [method@Pango.GlyphString.extents]. +However, since this only computes the width, it's much faster. This +is in fact only a convenience function that computes the sum of +@geometry.width for each glyph in the @glyphs. the logical width of the glyph string. - a #PangoGlyphString + a `PangoGlyphString` - Converts from character position to x position. (X position -is measured from the left edge of the run). Character positions -are computed by dividing up each cluster into equal portions. + Converts from character position to x position. + +The X position is measured from the left edge of the run. +Character positions are computed by dividing up each cluster +into equal portions. - the glyphs return from pango_shape() + the glyphs return from [func@shape] @@ -6082,7 +5781,7 @@ are computed by dividing up each cluster into equal portions. - the analysis information return from pango_itemize() + the analysis information return from [func@itemize] @@ -6091,7 +5790,7 @@ are computed by dividing up each cluster into equal portions. whether we should compute the result for the beginning (%FALSE) - or end (%TRUE) of the character. + or end (%TRUE) of the character. @@ -6107,28 +5806,29 @@ are computed by dividing up each cluster into equal portions. - a #PangoGlyphString. + a `PangoGlyphString`. - the new length of the string. + the new length of the string - Convert from x offset to character position. Character positions -are computed by dividing up each cluster into equal portions. -In scripts where positioning within a cluster is not allowed -(such as Thai), the returned value may not be a valid cursor -position; the caller must combine the result with the logical + Convert from x offset to character position. + +Character positions are computed by dividing up each cluster into +equal portions. In scripts where positioning within a cluster is +not allowed (such as Thai), the returned value may not be a valid +cursor position; the caller must combine the result with the logical attributes for the text to compute the valid cursor position. - the glyphs returned from pango_shape() + the glyphs returned from [func@shape] @@ -6140,7 +5840,7 @@ attributes for the text to compute the valid cursor position. - the analysis information return from pango_itemize() + the analysis information return from [func@itemize] @@ -6152,38 +5852,42 @@ attributes for the text to compute the valid cursor position. - location to store a boolean indicating - whether the user clicked on the leading or trailing - edge of the character. + location to store a boolean indicating whether the + user clicked on the leading or trailing edge of the character - The PangoGlyphVisAttr is used to communicate information between -the shaping phase and the rendering phase. More attributes may be -added in the future. + A `PangoGlyphVisAttr` structure communicates information between +the shaping and rendering phases. + +Currently, it contains only cluster start information. More attributes +may be added in the future. - set for the first logical glyph in each cluster. (Clusters -are stored in visual order, within the cluster, glyphs -are always ordered in logical order, since visual -order is meaningless; that is, in Arabic text, accent glyphs -follow the glyphs for the base character.) + set for the first logical glyph in each cluster. + (Clusters are stored in visual order, within the cluster, glyphs + are always ordered in logical order, since visual order is meaningless; + that is, in Arabic text, accent glyphs follow the glyphs for the + base character.) - The #PangoGravity type represents the orientation of glyphs in a segment -of text. This is useful when rendering vertical text layouts. In -those situations, the layout is rotated using a non-identity PangoMatrix, -and then glyph orientation is controlled using #PangoGravity. -Not every value in this enumeration makes sense for every usage of -#PangoGravity; for example, %PANGO_GRAVITY_AUTO only can be passed to -pango_context_set_base_gravity() and can only be returned by -pango_context_get_base_gravity(). + `PangoGravity` represents the orientation of glyphs in a segment +of text. -See also: #PangoGravityHint +This is useful when rendering vertical text layouts. In those situations, +the layout is rotated using a non-identity [struct@Pango.Matrix], and then +glyph orientation is controlled using `PangoGravity`. + +Not every value in this enumeration makes sense for every usage of +`PangoGravity`; for example, %PANGO_GRAVITY_AUTO only can be passed to +[method@Pango.Context.set_base_gravity] and can only be returned by +[method@Pango.Context.get_base_gravity]. + +See also: [enum@Pango.GravityHint] Glyphs stand upright (default) @@ -6201,7 +5905,7 @@ See also: #PangoGravityHint Finds the gravity that best matches the rotation component -in a #PangoMatrix. +in a `PangoMatrix`. the gravity of @matrix, which will never be %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if @matrix is %NULL @@ -6209,26 +5913,27 @@ in a #PangoMatrix. - a #PangoMatrix + a `PangoMatrix` - Based on the script, base gravity, and hint, returns actual gravity -to use in laying out a single #PangoItem. + Returns the gravity to use in laying out a `PangoItem`. + +The gravity is determined based on the script, base gravity, and hint. If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the preferred gravity of @script. To get the preferred gravity of a script, pass %PANGO_GRAVITY_AUTO and %PANGO_GRAVITY_HINT_STRONG in. resolved gravity suitable to use for a run of text -with @script. +with @script - #PangoScript to query + `PangoScript` to query @@ -6242,14 +5947,16 @@ with @script. - Based on the script, East Asian width, base gravity, and hint, -returns actual gravity to use in laying out a single character -or #PangoItem. + Returns the gravity to use in laying out a single character +or `PangoItem`. -This function is similar to pango_gravity_get_for_script() except +The gravity is determined based on the script, East Asian width, +base gravity, and hint, + +This function is similar to [func@Pango.Gravity.get_for_script] except that this function makes a distinction between narrow/half-width and -wide/full-width characters also. Wide/full-width characters always -stand <emphasis>upright</emphasis>, that is, they always take the base gravity, +wide/full-width characters also. Wide/full-width characters always +stand *upright*, that is, they always take the base gravity, whereas narrow/full-width characters are always rotated in vertical context. @@ -6262,7 +5969,7 @@ with @script and @wide. - #PangoScript to query + `PangoScript` to query @@ -6280,11 +5987,10 @@ with @script and @wide. - Converts a #PangoGravity value to its natural rotation in radians. -@gravity should not be %PANGO_GRAVITY_AUTO. + Converts a `PangoGravity` value to its natural rotation in radians. -Note that pango_matrix_rotate() takes angle in degrees, not radians. -So, to call pango_matrix_rotate() with the output of this function +Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians. +So, to call [method@Pango.Matrix,rotate] with the output of this function you should multiply it by (180. / G_PI). the rotation value corresponding to @gravity. @@ -6292,31 +5998,32 @@ you should multiply it by (180. / G_PI). - gravity to query + gravity to query, should not be %PANGO_GRAVITY_AUTO - The #PangoGravityHint defines how horizontal scripts should behave in a -vertical context. That is, English excerpt in a vertical paragraph for -example. + `PangoGravityHint` defines how horizontal scripts should behave in a +vertical context. -See #PangoGravity. +That is, English excerpts in a vertical paragraph for example. + +See also [enum@Pango.Gravity] scripts will take their natural gravity based -on the base gravity and the script. This is the default. + on the base gravity and the script. This is the default. always use the base gravity set, regardless of -the script. + the script. for scripts not in their natural direction (eg. -Latin in East gravity), choose per-script gravity such that every script -respects the line progression. This means, Latin and Arabic will take -opposite gravities and both flow top-to-bottom for example. + Latin in East gravity), choose per-script gravity such that every script + respects the line progression. This means, Latin and Arabic will take + opposite gravities and both flow top-to-bottom for example. @@ -6331,46 +6038,9 @@ opposite gravities and both flow top-to-bottom for example. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - a #GObject. @@ -6401,7 +6071,6 @@ opposite gravities and both flow top-to-bottom for example. - a #GObject. @@ -6414,7 +6083,6 @@ opposite gravities and both flow top-to-bottom for example. - a #GObject. @@ -6427,7 +6095,6 @@ opposite gravities and both flow top-to-bottom for example. - a #GObject. @@ -6461,59 +6128,11 @@ opposite gravities and both flow top-to-bottom for example. - - The #PangoIncludedModule structure for a statically linked module -contains the functions that would otherwise be loaded from a dynamically -loaded module. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - The #PangoItem structure stores information about a segment of text. + The `PangoItem` structure stores information about a segment of text. + +You typically obtain `PangoItems` by itemizing a piece of text +with [func@itemize]. byte offset of the start of this item in text. @@ -6531,19 +6150,20 @@ loaded module. - Creates a new #PangoItem structure initialized to default values. + Creates a new `PangoItem` structure initialized to default values. - the newly allocated #PangoItem, which should - be freed with pango_item_free(). + the newly allocated `PangoItem`, which should + be freed with [method@Pango.Item.free]. - Add attributes to a PangoItem. The idea is that you have -attributes that don't affect itemization, such as font features, -so you filter them out using pango_attr_list_filter(), itemize -your text, then reapply the attributes to the resulting items -using this function. + Add attributes to a `PangoItem`. + +The idea is that you have attributes that don't affect itemization, +such as font features, so you filter them out using +[method@Pango.AttrList.filter], itemize your text, then reapply the +attributes to the resulting items using this function. The @iter should be positioned before the range of the item, and will be advanced past it. This function is meant to be called @@ -6554,38 +6174,36 @@ the iter to each call. - a #PangoItem + a `PangoItem` - a #PangoAttrIterator + a `PangoAttrIterator` - Copy an existing #PangoItem structure. + Copy an existing `PangoItem` structure. - the newly allocated #PangoItem, which - should be freed with pango_item_free(), or %NULL if - @item was %NULL. + the newly allocated `PangoItem` - a #PangoItem, may be %NULL + a `PangoItem` - Free a #PangoItem and all associated memory. + Free a `PangoItem` and all associated memory. - a #PangoItem, may be %NULL + a `PangoItem`, may be %NULL @@ -6593,26 +6211,29 @@ the iter to each call. Modifies @orig to cover only the text after @split_index, and returns a new item that covers the text before @split_index that -used to be in @orig. You can think of @split_index as the length of -the returned item. @split_index may not be 0, and it may not be -greater than or equal to the length of @orig (that is, there must -be at least one byte assigned to each item, you can't create a -zero-length item). @split_offset is the length of the first item in -chars, and must be provided because the text used to generate the -item isn't available, so pango_item_split() can't count the char -length of the split items itself. +used to be in @orig. + +You can think of @split_index as the length of the returned item. +@split_index may not be 0, and it may not be greater than or equal +to the length of @orig (that is, there must be at least one byte +assigned to each item, you can't create a zero-length item). +@split_offset is the length of the first item in chars, and must be +provided because the text used to generate the item isn't available, +so `pango_item_split()` can't count the char length of the split items +itself. new item representing text before @split_index, which - should be freed with pango_item_free(). + should be freed with [method@Pango.Item.free]. - a #PangoItem + a `PangoItem` - byte index of position to split item, relative to the start of the item + byte index of position to split item, relative to the + start of the item @@ -6641,56 +6262,59 @@ length of the split items itself. - Extracts the <firstterm>left bearing</firstterm> from a #PangoRectangle -representing glyph extents. The left bearing is the distance from the -horizontal origin to the farthest left point of the character. -This is positive for characters drawn completely to the right of the -glyph origin. + Extracts the *left bearing* from a `PangoRectangle` +representing glyph extents. + +The left bearing is the distance from the horizontal +origin to the farthest left point of the character. +This is positive for characters drawn completely to +the right of the glyph origin. - a #PangoRectangle + a `PangoRectangle` - The #PangoLanguage structure is used to + The `PangoLanguage` structure is used to represent a language. -#PangoLanguage pointers can be efficiently +`PangoLanguage` pointers can be efficiently copied and compared with each other. Get a string that is representative of the characters needed to render a particular language. -The sample text may be a pangram, but is not necessarily. It is chosen to -be demonstrative of normal text in the language, as well as exposing font -feature requirements unique to the language. It is suitable for use +The sample text may be a pangram, but is not necessarily. It is chosen +to be demonstrative of normal text in the language, as well as exposing +font feature requirements unique to the language. It is suitable for use as sample text in a font selection dialog. If @language is %NULL, the default language as found by -pango_language_get_default() is used. +[func@Pango.Language.get_default] is used. If Pango does not have a sample string for @language, the classic "The quick brown fox..." is returned. This can be detected by comparing the returned pointer value to that returned for (non-existent) language code "xx". That is, compare to: -<informalexample><programlisting> + +``` pango_language_get_sample_string (pango_language_from_string ("xx")) -</programlisting></informalexample> +``` - the sample string. This value is owned by Pango - and should not be freed. + the sample string - a #PangoLanguage, or %NULL + a `PangoLanguage` Determines the scripts used to to write @language. + If nothing is known about the language tag @language, or if @language is %NULL, then %NULL is returned. The list of scripts returned starts with the script that the @@ -6701,101 +6325,101 @@ of scripts in the returned array (or zero if %NULL is returned). Most languages use only one script for writing, but there are some that use two (Latin and Cyrillic for example), and a few -use three (Japanese for example). Applications should not make +use three (Japanese for example). Applications should not make any assumptions on the maximum number of scripts returned though, except that it is positive if the return value is not %NULL, and it is a small number. -The pango_language_includes_script() function uses this function -internally. +The [method@Pango.Language.includes_script] function uses this +function internally. -Note: while the return value is declared as PangoScript, the -returned values are from the GUnicodeScript enumeration, which +Note: while the return value is declared as `PangoScript`, the +returned values are from the `GUnicodeScript` enumeration, which may have more values. Callers need to handle unknown values. - An array of -#PangoScript values, with the number of entries in the array stored -in @num_scripts, or %NULL if Pango does not have any information -about this particular language tag (also the case if @language is -%NULL). The returned array is owned by Pango and should not be -modified or freed. + + An array of `PangoScript` values, with the number of entries in + the array stored in @num_scripts, or %NULL if Pango does not have + any information about this particular language tag (also the case + if @language is %NULL). - a #PangoLanguage, or %NULL + a `PangoLanguage` - location to return number of scripts, - or %NULL + location to + return number of scripts Determines if @script is one of the scripts used to -write @language. The returned value is conservative; -if nothing is known about the language tag @language, -%TRUE will be returned, since, as far as Pango knows, -@script might be used to write @language. +write @language. + +The returned value is conservative; if nothing is known about +the language tag @language, %TRUE will be returned, since, as +far as Pango knows, @script might be used to write @language. This routine is used in Pango's itemization process when determining if a supplied language tag is relevant to -a particular section of text. It probably is not useful for -applications in most circumstances. +a particular section of text. It probably is not useful +for applications in most circumstances. -This function uses pango_language_get_scripts() internally. +This function uses [method@Pango.Language.get_scripts] internally. %TRUE if @script is one of the scripts used -to write @language or if nothing is known about @language -(including the case that @language is %NULL), -%FALSE otherwise. + to write @language or if nothing is known about @language + (including the case that @language is %NULL), %FALSE otherwise. - a #PangoLanguage, or %NULL + a `PangoLanguage` - a #PangoScript + a `PangoScript` Checks if a language tag matches one of the elements in a list of -language ranges. A language tag is considered to match a range -in the list if the range is '*', the range is exactly the tag, -or the range is a prefix of the tag, and the character after it -in the tag is '-'. +language ranges. + +A language tag is considered to match a range in the list if the +range is '*', the range is exactly the tag, or the range is a prefix +of the tag, and the character after it in the tag is '-'. - %TRUE if a match was found. + %TRUE if a match was found - a language tag (see pango_language_from_string()), - %NULL is allowed and matches nothing but '*' + a language tag (see [func@Pango.Language.from_string]), + %NULL is allowed and matches nothing but '*' a list of language ranges, separated by ';', ':', ',', or space characters. Each element must either be '*', or a RFC 3066 language range - canonicalized as by pango_language_from_string() + canonicalized as by [func@Pango.Language.from_string] - Gets the RFC-3066 format string representing the given language tag. + Gets the RFC-3066 format string representing the given language tag. + +Returns (transfer none): a string representing the language tag - a string representing the language tag. This is owned by - Pango and should not be freed. @@ -6806,37 +6430,34 @@ in the tag is '-'. - Take a RFC-3066 format language tag as a string and convert it to a -#PangoLanguage pointer that can be efficiently copied (copy the -pointer) and compared with other language tags (compare the -pointer.) + Convert a language tag to a `PangoLanguage`. + +The language tag must be in a RFC-3066 format. `PangoLanguage` pointers +can be efficiently copied (copy the pointer) and compared with other +language tags (compare the pointer.) This function first canonicalizes the string by converting it to lowercase, mapping '_' to '-', and stripping all characters other than letters and '-'. -Use pango_language_get_default() if you want to get the #PangoLanguage for -the current locale of the process. +Use [func@Pango.Language.get_default] if you want to get the +`PangoLanguage` for the current locale of the process. - an opaque pointer to a - #PangoLanguage structure, or %NULL if @language was - %NULL. The returned pointer will be valid forever - after, and should not be freed. + a `PangoLanguage` - a string representing a language tag, or %NULL + a string representing a language tag - Returns the #PangoLanguage for the current locale of the process. -Note that this can change over the life of an application. + Returns the `PangoLanguage` for the current locale of the process. On Unix systems, this is the return value is derived from -<literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can +`setlocale (LC_CTYPE, NULL)`, and the user can affect this through the environment variables LC_ALL, LC_CTYPE or LANG (checked in that order). The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and @@ -6854,82 +6475,104 @@ However, this function does check the above environment variables, and does return a Unix-style locale string based on either said environment variables or the thread's current locale. -Your application should call <literal>setlocale(LC_ALL, "");</literal> -for the user settings to take effect. Gtk+ does this in its initialization +Your application should call `setlocale(LC_ALL, "")` for the user +settings to take effect. GTK does this in its initialization functions automatically (by calling gtk_set_locale()). -See <literal>man setlocale</literal> for more details. +See the setlocale() manpage for more details. + +Note that the default language can change over the life of an application. - the default language as a - #PangoLanguage, must not be freed. + the default language as a `PangoLanguage` + + Returns the list of languages that the user prefers. + +The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE` +environment variables, in order of preference. Note that this +list does not necessarily include the language returned by +[func@Pango.Language.get_default]. + +When choosing language-specific resources, such as the sample +text returned by [method@Pango.Language.get_sample_string], +you should first try the default language, followed by the +languages returned by this function. + + a %NULL-terminated array + of `PangoLanguage`* + + + - The #PangoLayout structure represents an entire paragraph -of text. It is initialized with a #PangoContext, UTF-8 string -and set of attributes for that string. Once that is done, the -set of formatted lines can be extracted from the object, -the layout can be rendered, and conversion between logical -character positions within the layout's text, and the physical -position of the resulting glyphs can be made. + A `PangoLayout` structure represents an entire paragraph of text. -There are also a number of parameters to adjust the formatting -of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>. -It is possible, as well, to ignore the 2-D setup, and simply -treat the results of a #PangoLayout as a list of lines. +While complete access to the layout capabilities of Pango is provided +using the detailed interfaces for itemization and shaping, using +that functionality directly involves writing a fairly large amount +of code. `PangoLayout` provides a high-level driver for formatting +entire paragraphs of text at once. This includes paragraph-level +functionality such as line breaking, justification, alignment and +ellipsization. -<figure id="parameters"> -<title>Adjustable parameters (on the left) and font metrics (on the right) for a PangoLayout</title> -<graphic fileref="layout.png" format="PNG"></graphic> -</figure> +A `PangoLayout` is initialized with a `PangoContext`, UTF-8 string +and set of attributes for that string. Once that is done, the set of +formatted lines can be extracted from the object, the layout can be +rendered, and conversion between logical character positions within +the layout's text, and the physical position of the resulting glyphs +can be made. -The #PangoLayout structure is opaque, and has no user-visible -fields. +There are a number of parameters to adjust the formatting of a +`PangoLayout`. The following image shows adjustable parameters +(on the left) and font metrics (on the right): + +![Pango Layout Parameters](layout.png) + +It is possible, as well, to ignore the 2-D setup, +and simply treat the results of a `PangoLayout` as a list of lines. - Create a new #PangoLayout object with attributes initialized to -default values for a particular #PangoContext. + Create a new `PangoLayout` object with attributes initialized to +default values for a particular `PangoContext`. - the newly allocated #PangoLayout, with a reference - count of one, which should be freed with - g_object_unref(). + the newly allocated `PangoLayout` - a #PangoContext + a `PangoContext` - Forces recomputation of any state in the #PangoLayout that -might depend on the layout's context. This function should -be called if you make changes to the context subsequent -to creating the layout. + Forces recomputation of any state in the `PangoLayout` that +might depend on the layout's context. + +This function should be called if you make changes to the context +subsequent to creating the layout. - a #PangoLayout + a `PangoLayout` - Does a deep copy-by-value of the @src layout. The attribute list, -tab array, and text from the original layout are all copied by -value. + Creates a deep copy-by-value of the layout. + +The attribute list, tab array, and text from the original layout +are all copied by value. - the newly allocated #PangoLayout, - with a reference count of one, which should be freed - with g_object_unref(). + the newly allocated `PangoLayout` - a #PangoLayout + a `PangoLayout` @@ -6938,12 +6581,12 @@ value. Gets the alignment for the layout: how partial lines are positioned within the horizontal space available. - the alignment. + the alignment - a #PangoLayout + a `PangoLayout` @@ -6951,29 +6594,29 @@ positioned within the horizontal space available. Gets the attribute list for the layout, if any. - a #PangoAttrList or %NULL - if none was set. + a `PangoAttrList` - a #PangoLayout + a `PangoLayout` - Gets whether to calculate the bidirectional base direction -for the layout according to the contents of the layout. -See pango_layout_set_auto_dir(). + Gets whether to calculate the base direction for the layout +according to its contents. + +See [method@Pango.Layout.set_auto_dir]. %TRUE if the bidirectional base direction - is computed from the layout's contents, %FALSE otherwise. + is computed from the layout's contents, %FALSE otherwise - a #PangoLayout + a `PangoLayout` @@ -6981,12 +6624,12 @@ See pango_layout_set_auto_dir(). Gets the Y position of baseline of the first line in @layout. - baseline of first line, from top of @layout. + baseline of first line, from top of @layout - a #PangoLayout + a `PangoLayout` @@ -6996,46 +6639,44 @@ See pango_layout_set_auto_dir(). the text of @layout. the number of Unicode characters - in the text of @layout + in the text of @layout - a #PangoLayout + a `PangoLayout` - Retrieves the #PangoContext used for this layout. + Retrieves the `PangoContext` used for this layout. - the #PangoContext for the layout. -This does not have an additional refcount added, so if you want to -keep a copy of this around, you must reference it yourself. + the `PangoContext` for the layout - a #PangoLayout + a `PangoLayout` Given an index within a layout, determines the positions that of the -strong and weak cursors if the insertion point is at that -index. The position of each cursor is stored as a zero-width -rectangle. The strong cursor location is the location where -characters of the directionality equal to the base direction of the -layout are inserted. The weak cursor location is the location -where characters of the directionality opposite to the base -direction of the layout are inserted. +strong and weak cursors if the insertion point is at that index. + +The position of each cursor is stored as a zero-width rectangle. +The strong cursor location is the location where characters of the +directionality equal to the base direction of the layout are inserted. +The weak cursor location is the location where characters of the +directionality opposite to the base direction of the layout are inserted. - a #PangoLayout + a `PangoLayout` @@ -7043,26 +6684,24 @@ direction of the layout are inserted. - location to store the strong cursor position - (may be %NULL) + location to store the strong cursor position - location to store the weak cursor position (may be %NULL) + location to store the weak cursor position - Gets the text direction at the given character -position in @layout. + Gets the text direction at the given character position in @layout. the text direction at @index - a #PangoLayout + a `PangoLayout` @@ -7073,28 +6712,30 @@ position in @layout. Gets the type of ellipsization being performed for @layout. -See pango_layout_set_ellipsize() - - the current ellipsization mode for @layout. -Use pango_layout_is_ellipsized() to query whether any paragraphs -were actually ellipsized. +See [method@Pango.Layout.set_ellipsize]. + +Use [method@Pango.Layout.is_ellipsized] to query whether any +paragraphs were actually ellipsized. + + the current ellipsization mode for @layout - a #PangoLayout + a `PangoLayout` - Computes the logical and ink extents of @layout. Logical extents -are usually what you want for positioning things. Note that both extents -may have non-zero x and y. You may want to use those to offset where you -render the layout. Not doing that is a very typical bug that shows up as -right-to-left layouts not being correctly positioned in a layout with -a set width. + Computes the logical and ink extents of @layout. + +Logical extents are usually what you want for positioning things. Note +that both extents may have non-zero x and y. You may want to use those +to offset where you render the layout. Not doing that is a very typical +bug that shows up as right-to-left layouts not being correctly positioned +in a layout with a set width. The extents are given in layout coordinates and in Pango units; layout coordinates begin at the top left corner of the layout. @@ -7103,19 +6744,17 @@ coordinates begin at the top left corner of the layout. - a #PangoLayout + a `PangoLayout` rectangle used to store the extents of the - layout as drawn or %NULL to indicate that the result is - not needed. + layout as drawn rectangle used to store the logical - extents of the layout or %NULL to indicate that the - result is not needed. + extents of the layout @@ -7123,44 +6762,45 @@ coordinates begin at the top left corner of the layout. Gets the font description for the layout, if any. - a pointer to the layout's font - description, or %NULL if the font description from the layout's - context is inherited. This value is owned by the layout and must - not be modified or freed. + a pointer to the + layout's font description, or %NULL if the font description + from the layout's context is inherited. - a #PangoLayout + a `PangoLayout` - Gets the height of layout used for ellipsization. See -pango_layout_set_height() for details. + Gets the height of layout used for ellipsization. + +See [method@Pango.Layout.set_height] for details. - the height, in Pango units if positive, or -number of lines if negative. + the height, in Pango units if positive, + or number of lines if negative. - a #PangoLayout + a `PangoLayout` - Gets the paragraph indent width in Pango units. A negative value -indicates a hanging indentation. + Gets the paragraph indent width in Pango units. + +A negative value indicates a hanging indentation. - the indent in Pango units. + the indent in Pango units - a #PangoLayout + a `PangoLayout` @@ -7168,13 +6808,12 @@ indicates a hanging indentation. Returns an iterator to iterate over the visual extents of the layout. - the new #PangoLayoutIter that should be freed using - pango_layout_iter_free(). + the new `PangoLayoutIter` - a #PangoLayout + a `PangoLayout` @@ -7183,37 +6822,36 @@ indicates a hanging indentation. Gets whether each complete line should be stretched to fill the entire width of the layout. - the justify. + the justify value - a #PangoLayout + a `PangoLayout` - Retrieves a particular line from a #PangoLayout. + Retrieves a particular line from a `PangoLayout`. -Use the faster pango_layout_get_line_readonly() if you do not plan -to modify the contents of the line (glyphs, glyph widths, etc.). +Use the faster [method@Pango.Layout.get_line_readonly] if you do not +plan to modify the contents of the line (glyphs, glyph widths, etc.). - the requested - #PangoLayoutLine, or %NULL if the index is out of - range. This layout line can be ref'ed and retained, - but will become invalid if changes are made to the - #PangoLayout. + the requested `PangoLayoutLine`, + or %NULL if the index is out of range. This layout line can be ref'ed + and retained, but will become invalid if changes are made to the + `PangoLayout`. - a #PangoLayout + a `PangoLayout` the index of a line, which must be between 0 and - <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive. + `pango_layout_get_line_count(layout) - 1`, inclusive. @@ -7221,51 +6859,51 @@ to modify the contents of the line (glyphs, glyph widths, etc.). Retrieves the count of lines for the @layout. - the line count. + the line count - #PangoLayout + `PangoLayout` - Retrieves a particular line from a #PangoLayout. + Retrieves a particular line from a `PangoLayout`. -This is a faster alternative to pango_layout_get_line(), -but the user is not expected -to modify the contents of the line (glyphs, glyph widths, etc.). +This is a faster alternative to [method@Pango.Layout.get_line], +but the user is not expected to modify the contents of the line +(glyphs, glyph widths, etc.). - the requested - #PangoLayoutLine, or %NULL if the index is out of - range. This layout line can be ref'ed and retained, - but will become invalid if changes are made to the - #PangoLayout. No changes should be made to the line. + the requested `PangoLayoutLine`, + or %NULL if the index is out of range. This layout line can be ref'ed + and retained, but will become invalid if changes are made to the + `PangoLayout`. No changes should be made to the line. - a #PangoLayout + a `PangoLayout` the index of a line, which must be between 0 and - <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive. + `pango_layout_get_line_count(layout) - 1`, inclusive. - Gets the value that has been -set with pango_layout_set_line_spacing(). + Gets the line spacing factor of @layout. + +See [method@Pango.Layout.set_line_spacing]. - a #PangoLayout + a `PangoLayout` @@ -7273,20 +6911,20 @@ set with pango_layout_set_line_spacing(). Returns the lines of the @layout as a list. -Use the faster pango_layout_get_lines_readonly() if you do not plan -to modify the contents of the lines (glyphs, glyph widths, etc.). +Use the faster [method@Pango.Layout.get_lines_readonly] if you do not +plan to modify the contents of the lines (glyphs, glyph widths, etc.). - a #GSList containing -the lines in the layout. This points to internal data of the #PangoLayout -and must be used with care. It will become invalid on any change to the layout's -text or properties. + a `GSList` + containing the lines in the layout. This points to internal data of the + `PangoLayout` and must be used with care. It will become invalid on any + change to the layout's text or properties. - a #PangoLayout + a `PangoLayout` @@ -7294,21 +6932,22 @@ text or properties. Returns the lines of the @layout as a list. -This is a faster alternative to pango_layout_get_lines(), -but the user is not expected -to modify the contents of the lines (glyphs, glyph widths, etc.). +This is a faster alternative to [method@Pango.Layout.get_lines], +but the user is not expected to modify the contents of the lines +(glyphs, glyph widths, etc.). - a #GSList containing -the lines in the layout. This points to internal data of the #PangoLayout and -must be used with care. It will become invalid on any change to the layout's -text or properties. No changes should be made to the lines. + a `GSList` + containing the lines in the layout. This points to internal data of the + `PangoLayout` and must be used with care. It will become invalid on any + change to the layout's text or properties. No changes should be made to + the lines. - a #PangoLayout + a `PangoLayout` @@ -7321,23 +6960,23 @@ the @layout. - a #PangoLayout + a `PangoLayout` - location to store a pointer to an array of logical attributes - This value must be freed with g_free(). + location to store a pointer to an array of logical attributes. + This value must be freed with g_free(). location to store the number of the attributes in the - array. (The stored value will be one more than the total number - of characters in the layout, since there need to be attributes - corresponding to both the position before the first character - and the position after the last character.) + array. (The stored value will be one more than the total number + of characters in the layout, since there need to be attributes + corresponding to both the position before the first character + and the position after the last character.) @@ -7346,7 +6985,7 @@ the @layout. Retrieves an array of logical attributes for each character in the @layout. -This is a faster alternative to pango_layout_get_log_attrs(). +This is a faster alternative to [method@Pango.Layout.get_log_attrs]. The returned array is part of @layout and must not be modified. Modifying the layout will invalidate the returned array. @@ -7362,7 +7001,7 @@ the first character and the position after the last character. - a #PangoLayout + a `PangoLayout` @@ -7374,110 +7013,115 @@ the first character and the position after the last character. Computes the logical and ink extents of @layout in device units. -This function just calls pango_layout_get_extents() followed by -two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect + +This function just calls [method@Pango.Layout.get_extents] followed by +two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect such that the rounded rectangles fully contain the unrounded one (that is, -passes them as first argument to pango_extents_to_pixels()). +passes them as first argument to [func@Pango.extents_to_pixels]). - a #PangoLayout + a `PangoLayout` rectangle used to store the extents of the - layout as drawn or %NULL to indicate that the result is - not needed. + layout as drawn rectangle used to store the logical - extents of the layout or %NULL to indicate that the - result is not needed. + extents of the layout - Determines the logical width and height of a #PangoLayout -in device units. (pango_layout_get_size() returns the width -and height scaled by %PANGO_SCALE.) This -is simply a convenience function around -pango_layout_get_pixel_extents(). + Determines the logical width and height of a `PangoLayout` in device +units. + +[method@Pango.Layout.get_size] returns the width and height +scaled by %PANGO_SCALE. This is simply a convenience function +around [method@Pango.Layout.get_pixel_extents]. - a #PangoLayout + a `PangoLayout` - location to store the logical width, or %NULL + location to store the logical width - location to store the logical height, or %NULL + location to store the logical height - Returns the current serial number of @layout. The serial number is -initialized to an small number larger than zero when a new layout -is created and is increased whenever the layout is changed using any -of the setter functions, or the #PangoContext it uses has changed. -The serial may wrap, but will never have the value 0. Since it -can wrap, never compare it with "less than", always use "not equals". + Returns the current serial number of @layout. -This can be used to automatically detect changes to a #PangoLayout, and -is useful for example to decide whether a layout needs redrawing. -To force the serial to be increased, use pango_layout_context_changed(). +The serial number is initialized to an small number larger than zero +when a new layout is created and is increased whenever the layout is +changed using any of the setter functions, or the `PangoContext` it +uses has changed. The serial may wrap, but will never have the value 0. +Since it can wrap, never compare it with "less than", always use "not equals". + +This can be used to automatically detect changes to a `PangoLayout`, +and is useful for example to decide whether a layout needs redrawing. +To force the serial to be increased, use +[method@Pango.Layout.context_changed]. The current serial number of @layout. - a #PangoLayout + a `PangoLayout` - Obtains the value set by pango_layout_set_single_paragraph_mode(). + Obtains whether @layout is in single paragraph mode. + +See [method@Pango.Layout.set_single_paragraph_mode]. - %TRUE if the layout does not break paragraphs at -paragraph separator characters, %FALSE otherwise. + %TRUE if the layout does not break paragraphs + at paragraph separator characters, %FALSE otherwise - a #PangoLayout + a `PangoLayout` - Determines the logical width and height of a #PangoLayout -in Pango units (device units scaled by %PANGO_SCALE). This -is simply a convenience function around pango_layout_get_extents(). + Determines the logical width and height of a `PangoLayout` in Pango +units. + +This is simply a convenience function around [method@Pango.Layout.get_extents]. - a #PangoLayout + a `PangoLayout` - location to store the logical width, or %NULL + location to store the logical width - location to store the logical height, or %NULL + location to store the logical height @@ -7485,76 +7129,76 @@ is simply a convenience function around pango_layout_get_extents(). Gets the amount of spacing between the lines of the layout. - the spacing in Pango units. + the spacing in Pango units - a #PangoLayout + a `PangoLayout` - Gets the current #PangoTabArray used by this layout. If no -#PangoTabArray has been set, then the default tabs are in use -and %NULL is returned. Default tabs are every 8 spaces. -The return value should be freed with pango_tab_array_free(). + Gets the current `PangoTabArray` used by this layout. + +If no `PangoTabArray` has been set, then the default tabs are +in use and %NULL is returned. Default tabs are every 8 spaces. + +The return value should be freed with [method@Pango.TabArray.free]. - a copy of the tabs for this layout, or -%NULL. + a copy of the tabs for this layout - a #PangoLayout + a `PangoLayout` - Gets the text in the layout. The returned text should not -be freed or modified. + Gets the text in the layout. + +The returned text should not be freed or modified. - the text in the @layout. + the text in the @layout - a #PangoLayout + a `PangoLayout` - Counts the number unknown glyphs in @layout. That is, zero if -glyphs for all characters in the layout text were found, or more -than zero otherwise. + Counts the number of unknown glyphs in @layout. This function can be used to determine if there are any fonts available to render all characters in a certain string, or when used in combination with %PANGO_ATTR_FALLBACK, to check if a certain font supports all the characters in the string. - The number of unknown glyphs in @layout. + The number of unknown glyphs in @layout - a #PangoLayout + a `PangoLayout` - Gets the width to which the lines of the #PangoLayout should wrap. + Gets the width to which the lines of the `PangoLayout` should wrap. the width in Pango units, or -1 if no width set. - a #PangoLayout + a `PangoLayout` @@ -7562,65 +7206,67 @@ certain font supports all the characters in the string. Gets the wrap mode for the layout. -Use pango_layout_is_wrapped() to query whether any paragraphs -were actually wrapped. +Use [method@Pango.Layout.is_wrapped] to query whether +any paragraphs were actually wrapped. active wrap mode. - a #PangoLayout + a `PangoLayout` Converts from byte @index_ within the @layout to line and X position. -(X position is measured from the left edge of the line) + +The X position is measured from the left edge of the line. - a #PangoLayout + a `PangoLayout` - the byte index of a grapheme within the layout. + the byte index of a grapheme within the layout an integer indicating the edge of the grapheme to retrieve the - position of. If > 0, the trailing edge of the grapheme, if 0, - the leading of the grapheme. + position of. If > 0, the trailing edge of the grapheme, if 0, + the leading of the grapheme location to store resulting line index. (which will - between 0 and pango_layout_get_line_count(layout) - 1), or %NULL + between 0 and pango_layout_get_line_count(layout) - 1) location to store resulting position within line - (%PANGO_SCALE units per device unit), or %NULL + (%PANGO_SCALE units per device unit) - Converts from an index within a #PangoLayout to the onscreen position -corresponding to the grapheme at that index, which is represented -as rectangle. Note that <literal>pos->x</literal> is always the leading -edge of the grapheme and <literal>pos->x + pos->width</literal> the trailing -edge of the grapheme. If the directionality of the grapheme is right-to-left, -then <literal>pos->width</literal> will be negative. + Converts from an index within a `PangoLayout` to the onscreen position +corresponding to the grapheme at that index. + +The return value is represented as rectangle. Note that `pos->x` is +always the leading edge of the grapheme and `pos->x + pos->width` the +trailing edge of the grapheme. If the directionality of the grapheme +is right-to-left, then `pos->width` will be negative. - a #PangoLayout + a `PangoLayout` @@ -7641,13 +7287,13 @@ is not %PANGO_ELLIPSIZE_NONE, a positive width is set on @layout, and there are paragraphs exceeding that width that have to be ellipsized. - %TRUE if any paragraphs had to be ellipsized, %FALSE -otherwise. + %TRUE if any paragraphs had to be ellipsized, + %FALSE otherwise - a #PangoLayout + a `PangoLayout` @@ -7661,45 +7307,46 @@ and there are paragraphs exceeding the layout width that have to be wrapped. %TRUE if any paragraphs had to be wrapped, %FALSE -otherwise. + otherwise - a #PangoLayout + a `PangoLayout` - Computes a new cursor position from an old position and -a count of positions to move visually. If @direction is positive, -then the new strong cursor position will be one position -to the right of the old cursor position. If @direction is negative, -then the new strong cursor position will be one position -to the left of the old cursor position. + Computes a new cursor position from an old position and a count of +positions to move visually. -In the presence of bidirectional text, the correspondence -between logical and visual order will depend on the direction -of the current run, and there may be jumps when the cursor -is moved off of the end of a run. +If @direction is positive, then the new strong cursor position will be +one position to the right of the old cursor position. If @direction is +negative, then the new strong cursor position will be one position to +the left of the old cursor position. -Motion here is in cursor positions, not in characters, so a -single call to pango_layout_move_cursor_visually() may move the -cursor over multiple characters when multiple characters combine -to form a single grapheme. +In the presence of bidirectional text, the correspondence between +logical and visual order will depend on the direction of the current +run, and there may be jumps when the cursor is moved off of the end +of a run. + +Motion here is in cursor positions, not in characters, so a single +call to [method@Pango.Layout.move_cursor_visually] may move the cursor +over multiple characters when multiple characters combine to form a +single grapheme. - a #PangoLayout. + a `PangoLayout` whether the moving cursor is the strong cursor or the - weak cursor. The strong cursor is the cursor corresponding - to text insertion in the base direction for the layout. + weak cursor. The strong cursor is the cursor corresponding + to text insertion in the base direction for the layout. @@ -7708,43 +7355,44 @@ to form a single grapheme. if 0, the cursor was at the leading edge of the - grapheme indicated by @old_index, if > 0, the cursor - was at the trailing edge. + grapheme indicated by @old_index, if > 0, the cursor + was at the trailing edge. direction to move cursor. A negative - value indicates motion to the left. + value indicates motion to the left - location to store the new cursor byte index. A value of -1 - indicates that the cursor has been moved off the beginning - of the layout. A value of %G_MAXINT indicates that - the cursor has been moved off the end of the layout. + location to store the new cursor byte index. + A value of -1 indicates that the cursor has been moved off the + beginning of the layout. A value of %G_MAXINT indicates that + the cursor has been moved off the end of the layout. - number of characters to move forward from the - location returned for @new_index to get the position - where the cursor should be displayed. This allows - distinguishing the position at the beginning of one - line from the position at the end of the preceding - line. @new_index is always on the line where the - cursor should be displayed. + number of characters to move forward from + the location returned for @new_index to get the position where + the cursor should be displayed. This allows distinguishing the + position at the beginning of one line from the position at the + end of the preceding line. @new_index is always on the line where + the cursor should be displayed. Sets the alignment for the layout: how partial lines are -positioned within the horizontal space available. +positioned within the horizontal space available. + +The default alignment is %PANGO_ALIGN_LEFT. - a #PangoLayout + a `PangoLayout` @@ -7755,34 +7403,35 @@ positioned within the horizontal space available. Sets the text attributes for a layout object. + References @attrs, so the caller can unref its reference. - a #PangoLayout + a `PangoLayout` - a #PangoAttrList, can be %NULL + a `PangoAttrList` - Sets whether to calculate the bidirectional base direction -for the layout according to the contents of the layout; -when this flag is on (the default), then paragraphs in - @layout that begin with strong right-to-left characters -(Arabic and Hebrew principally), will have right-to-left -layout, paragraphs with letters from other scripts will -have left-to-right layout. Paragraphs with only neutral -characters get their direction from the surrounding paragraphs. + Sets whether to calculate the base direction +for the layout according to its contents. -When %FALSE, the choice between left-to-right and -right-to-left layout is done according to the base direction -of the layout's #PangoContext. (See pango_context_set_base_dir()). +When this flag is on (the default), then paragraphs in @layout that +begin with strong right-to-left characters (Arabic and Hebrew principally), +will have right-to-left layout, paragraphs with letters from other scripts +will have left-to-right layout. Paragraphs with only neutral characters +get their direction from the surrounding paragraphs. + +When %FALSE, the choice between left-to-right and right-to-left +layout is done according to the base direction of the layout's +`PangoContext`. (See [method@Pango.Context.set_base_dir]). When the auto-computed direction of a paragraph differs from the base direction of the context, the interpretation of @@ -7792,34 +7441,38 @@ base direction of the context, the interpretation of - a #PangoLayout + a `PangoLayout` if %TRUE, compute the bidirectional base direction - from the layout's contents. + from the layout's contents Sets the type of ellipsization being performed for @layout. + Depending on the ellipsization mode @ellipsize text is removed from the start, middle, or end of text so they fit within the width and height of layout set with -pango_layout_set_width() and pango_layout_set_height(). +[method@Pango.Layout.set_width] and [method@Pango.Layout.set_height]. If the layout contains characters such as newlines that force it to be layed out in multiple paragraphs, then whether each paragraph is ellipsized separately or the entire layout is ellipsized as a whole depends on the set height of the layout. -See pango_layout_set_height() for details. + +The default value is %PANGO_ELLIPSIZE_NONE. + +See [method@Pango.Layout.set_height] for details. - a #PangoLayout + a `PangoLayout` @@ -7829,43 +7482,45 @@ See pango_layout_set_height() for details. - Sets the default font description for the layout. If no font -description is set on the layout, the font description from -the layout's context is used. + Sets the default font description for the layout. + +If no font description is set on the layout, the +font description from the layout's context is used. - a #PangoLayout + a `PangoLayout` - the new #PangoFontDescription, or %NULL to unset the - current font description + the new `PangoFontDescription` + to unset the current font description - Sets the height to which the #PangoLayout should be ellipsized at. There -are two different behaviors, based on whether @height is positive or -negative. + Sets the height to which the `PangoLayout` should be ellipsized at. -If @height is positive, it will be the maximum height of the layout. Only +There are two different behaviors, based on whether @height is positive +or negative. + +If @height is positive, it will be the maximum height of the layout. Only lines would be shown that would fit, and if there is any text omitted, -an ellipsis added. At least one line is included in each paragraph regardless -of how small the height value is. A value of zero will render exactly one +an ellipsis added. At least one line is included in each paragraph regardless +of how small the height value is. A value of zero will render exactly one line for the entire layout. -If @height is negative, it will be the (negative of) maximum number of lines per -paragraph. That is, the total number of lines shown may well be more than +If @height is negative, it will be the (negative of) maximum number of lines +per paragraph. That is, the total number of lines shown may well be more than this value if the layout contains multiple paragraphs of text. -The default value of -1 means that first line of each paragraph is ellipsized. -This behvaior may be changed in the future to act per layout instead of per -paragraph. File a bug against pango at <ulink -url="http://bugzilla.gnome.org/">http://bugzilla.gnome.org/</ulink> if your -code relies on this behavior. +The default value of -1 means that the first line of each paragraph is ellipsized. +This behavior may be changed in the future to act per layout instead of per +paragraph. File a bug against pango at +[https://gitlab.gnome.org/gnome/pango](https://gitlab.gnome.org/gnome/pango) +if your code relies on this behavior. Height setting only has effect if a positive width is set on @layout and ellipsization mode of @layout is not %PANGO_ELLIPSIZE_NONE. @@ -7877,84 +7532,87 @@ future. - a #PangoLayout. + a `PangoLayout`. the desired height of the layout in Pango units if positive, - or desired number of lines if negative. + or desired number of lines if negative. - Sets the width in Pango units to indent each paragraph. A negative value -of @indent will produce a hanging indentation. That is, the first line will -have the full width, and subsequent lines will be indented by the -absolute value of @indent. + Sets the width in Pango units to indent each paragraph. + +A negative value of @indent will produce a hanging indentation. +That is, the first line will have the full width, and subsequent +lines will be indented by the absolute value of @indent. The indent setting is ignored if layout alignment is set to -%PANGO_ALIGN_CENTER. +%PANGO_ALIGN_CENTER. + +The default value is 0. - a #PangoLayout. + a `PangoLayout` - the amount by which to indent. + the amount by which to indent - Sets whether each complete line should be stretched to -fill the entire width of the layout. This stretching is typically -done by adding whitespace, but for some scripts (such as Arabic), -the justification may be done in more complex ways, like extending -the characters. + Sets whether each complete line should be stretched to fill the +entire width of the layout. -Note that this setting is not implemented and so is ignored in Pango -older than 1.18. +Stretching is typically done by adding whitespace, but for some scripts +(such as Arabic), the justification may be done in more complex ways, +like extending the characters. + +Note that this setting is not implemented and so is ignored in +Pango older than 1.18. + +The default value is %FALSE. - a #PangoLayout + a `PangoLayout` - whether the lines in the layout should be justified. + whether the lines in the layout should be justified Sets a factor for line spacing. -Typical values are: 0, 1, 1.5, 2. -The default values is 0. -If @factor is non-zero, lines are placed -so that +Typical values are: 0, 1, 1.5, 2. The default values is 0. -baseline2 = baseline1 + factor * height2 +If @factor is non-zero, lines are placed so that -where height2 is the line height of the -second line (as determined by the font(s)). -In this case, the spacing set with -pango_layout_set_spacing() is ignored. + baseline2 = baseline1 + factor * height2 -If @factor is zero, spacing is applied as -before. +where height2 is the line height of the second line +(as determined by the font(s)). In this case, the spacing +set with [method@Pango.Layout.set_spacing] is ignored. + +If @factor is zero (the default), spacing is applied as before. - a #PangoLayout + a `PangoLayout` @@ -7964,14 +7622,20 @@ before. - Same as pango_layout_set_markup_with_accel(), but -the markup text isn't scanned for accelerators. + Sets the layout text and attribute list from marked-up text. + +See [Pango Markup](pango_markup.html)). + +Replaces the current text and attribute list. + +This is the same as [method@Pango.Layout.set_markup_with_accel], +but the markup text isn't scanned for accelerators. - a #PangoLayout + a `PangoLayout` @@ -7980,15 +7644,17 @@ the markup text isn't scanned for accelerators. length of marked-up text in bytes, or -1 if @markup is - null-terminated + `NUL`-terminated - Sets the layout text and attribute list from marked-up text (see -<link linkend="PangoMarkupFormat">markup format</link>). Replaces -the current text and attribute list. + Sets the layout text and attribute list from marked-up text. + +See [Pango Markup](pango_markup.html)). + +Replaces the current text and attribute list. If @accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, @accel_marker @@ -8002,17 +7668,16 @@ literal @accel_marker character. - a #PangoLayout + a `PangoLayout` - marked-up text -(see <link linkend="PangoMarkupFormat">markup format</link>) + marked-up text (see [Pango Markup](pango_markup.html)) length of marked-up text in bytes, or -1 if @markup is - null-terminated + `NUL`-terminated @@ -8021,22 +7686,26 @@ literal @accel_marker character. return location - for first located accelerator, or %NULL + for first located accelerator - If @setting is %TRUE, do not treat newlines and similar characters + Sets the single paragraph mode of @layout. + +If @setting is %TRUE, do not treat newlines and similar characters as paragraph separators; instead, keep all text in a single paragraph, and display a glyph for paragraph separator characters. Used when -you want to allow editing of newlines on a single text line. +you want to allow editing of newlines on a single text line. + +The default value is %FALSE. - a #PangoLayout + a `PangoLayout` @@ -8046,23 +7715,25 @@ you want to allow editing of newlines on a single text line. - Sets the amount of spacing in Pango unit between -the lines of the layout. When placing lines with -spacing, Pango arranges things so that + Sets the amount of spacing in Pango units between +the lines of the layout. -line2.top = line1.bottom + spacing +When placing lines with spacing, Pango arranges things so that -Note: Since 1.44, Pango defaults to using the -line height (as determined by the font) for placing -lines. The @spacing set with this function is only -taken into account when the line-height factor is -set to zero with pango_layout_set_line_spacing(). + line2.top = line1.bottom + spacing + +The default value is 0. + +Note: Since 1.44, Pango is using the line height (as determined +by the font) for placing lines when the line height factor is set +to a non-zero value with [method@Pango.Layout.set_line_spacing]. +In that case, the @spacing set with this function is ignored. - a #PangoLayout. + a `PangoLayout` @@ -8072,20 +7743,21 @@ set to zero with pango_layout_set_line_spacing(). - Sets the tabs to use for @layout, overriding the default tabs -(by default, tabs are every 8 spaces). If @tabs is %NULL, the default -tabs are reinstated. @tabs is copied into the layout; you must -free your copy of @tabs yourself. + Sets the tabs to use for @layout, overriding the default tabs. + +By default, tabs are every 8 spaces. If @tabs is %NULL, the +default tabs are reinstated. @tabs is copied into the layout; +you must free your copy of @tabs yourself. - a #PangoLayout + a `PangoLayout` - a #PangoTabArray, or %NULL + a `PangoTabArray` @@ -8096,17 +7768,17 @@ free your copy of @tabs yourself. This function validates @text and renders invalid UTF-8 with a placeholder glyph. -Note that if you have used pango_layout_set_markup() or -pango_layout_set_markup_with_accel() on @layout before, you may -want to call pango_layout_set_attributes() to clear the attributes -set on the layout from the markup as this function does not clear -attributes. +Note that if you have used [method@Pango.Layout.set_markup] or +[method@Pango.Layout.set_markup_with_accel] on @layout before, you +may want to call [method@Pango.Layout.set_attributes] to clear the +attributes set on the layout from the markup as this function does +not clear attributes. - a #PangoLayout + a `PangoLayout` @@ -8115,42 +7787,47 @@ attributes. maximum length of @text, in bytes. -1 indicates that - the string is nul-terminated and the length should be - calculated. The text will also be truncated on - encountering a nul-termination even when @length is - positive. + the string is nul-terminated and the length should be calculated. + The text will also be truncated on encountering a nul-termination + even when @length is positive. - Sets the width to which the lines of the #PangoLayout should wrap or -ellipsized. The default value is -1: no width set. + Sets the width to which the lines of the `PangoLayout` should wrap or +ellipsized. + +The default value is -1: no width set. - a #PangoLayout. + a `PangoLayout`. the desired width in Pango units, or -1 to indicate that no - wrapping or ellipsization should be performed. + wrapping or ellipsization should be performed. - Sets the wrap mode; the wrap mode only has effect if a width -is set on the layout with pango_layout_set_width(). -To turn off wrapping, set the width to -1. + Sets the wrap mode. + +The wrap mode only has effect if a width is set on the layout +with [method@Pango.Layout.set_width]. To turn off wrapping, +set the width to -1. + +The default value is %PANGO_WRAP_WORD. - a #PangoLayout + a `PangoLayout` @@ -8160,31 +7837,30 @@ To turn off wrapping, set the width to -1. - Converts from X and Y position within a layout to the byte -index to the character at that logical position. If the -Y position is not inside the layout, the closest position is chosen -(the position will be clamped inside the layout). If the -X position is not within the layout, then the start or the -end of the line is chosen as described for pango_layout_line_x_to_index(). -If either the X or Y positions were not inside the layout, then the -function returns %FALSE; on an exact hit, it returns %TRUE. + Converts from X and Y position within a layout to the byte index to the +character at that logical position. + +If the Y position is not inside the layout, the closest position is +chosen (the position will be clamped inside the layout). If the X position +is not within the layout, then the start or the end of the line is +chosen as described for [method@Pango.LayoutLine.x_to_index]. If either +the X or Y positions were not inside the layout, then the function returns +%FALSE; on an exact hit, it returns %TRUE. - %TRUE if the coordinates were inside text, %FALSE otherwise. + %TRUE if the coordinates were inside text, %FALSE otherwise - a #PangoLayout + a `PangoLayout` - the X offset (in Pango units) - from the left edge of the layout. + the X offset (in Pango units) from the left edge of the layout - the Y offset (in Pango units) - from the top edge of the layout + the Y offset (in Pango units) from the top edge of the layout @@ -8193,9 +7869,9 @@ function returns %FALSE; on an exact hit, it returns %TRUE. location to store a integer indicating where - in the grapheme the user clicked. It will either - be zero, or the number of characters in the - grapheme. 0 represents the leading edge of the grapheme. + in the grapheme the user clicked. It will either be zero, or the + number of characters in the grapheme. 0 represents the leading edge + of the grapheme. @@ -8203,35 +7879,34 @@ function returns %FALSE; on an exact hit, it returns %TRUE. - A #PangoLayoutIter structure can be used to -iterate over the visual extents of a #PangoLayout. + A `PangoLayoutIter` can be used to iterate over the visual +extents of a `PangoLayout`. -The #PangoLayoutIter structure is opaque, and -has no user-visible fields. +To obtain a `PangoLayoutIter`, use [method@Pango.Layout.get_iter]. + +The `PangoLayoutIter` structure is opaque, and has no user-visible fields. Determines whether @iter is on the last line of the layout. - %TRUE if @iter is on the last line. + %TRUE if @iter is on the last line - a #PangoLayoutIter + a `PangoLayoutIter` - Copies a #PangoLayoutIter. + Copies a `PangoLayoutIter`. - the newly allocated #PangoLayoutIter, - which should be freed with pango_layout_iter_free(), - or %NULL if @iter was %NULL. + the newly allocated `PangoLayoutIter` - a #PangoLayoutIter, may be %NULL + a `PangoLayoutIter` @@ -8243,36 +7918,40 @@ has no user-visible fields. - a #PangoLayoutIter, may be %NULL + a `PangoLayoutIter`, may be %NULL Gets the Y position of the current line's baseline, in layout -coordinates (origin at top left of the entire layout). +coordinates. + +Layout coordinates have the origin at the top left of the entire layout. - baseline of current line. + baseline of current line - a #PangoLayoutIter + a `PangoLayoutIter` - Gets the extents of the current character, in layout coordinates -(origin is the top left of the entire layout). Only logical extents -can sensibly be obtained for characters; ink extents make sense only -down to the level of clusters. + Gets the extents of the current character, in layout coordinates. + +Layout coordinates have the origin at the top left of the entire layout. + +Only logical extents can sensibly be obtained for characters; +ink extents make sense only down to the level of clusters. - a #PangoLayoutIter + a `PangoLayoutIter` @@ -8283,75 +7962,74 @@ down to the level of clusters. - Gets the extents of the current cluster, in layout coordinates -(origin is the top left of the entire layout). + Gets the extents of the current cluster, in layout coordinates. + +Layout coordinates have the origin at the top left of the entire layout. - a #PangoLayoutIter + a `PangoLayoutIter` - rectangle to fill with ink extents, or %NULL + rectangle to fill with ink extents - rectangle to fill with logical extents, or %NULL + rectangle to fill with logical extents - Gets the current byte index. Note that iterating forward by char -moves in visual order, not logical order, so indexes may not be -sequential. Also, the index may be equal to the length of the text -in the layout, if on the %NULL run (see pango_layout_iter_get_run()). + Gets the current byte index. + +Note that iterating forward by char moves in visual order, +not logical order, so indexes may not be sequential. Also, +the index may be equal to the length of the text in the +layout, if on the %NULL run (see [method@Pango.LayoutIter.get_run]). - current byte index. + current byte index - a #PangoLayoutIter + a `PangoLayoutIter` - Gets the layout associated with a #PangoLayoutIter. + Gets the layout associated with a `PangoLayoutIter`. - the layout associated with @iter. + the layout associated with @iter - a #PangoLayoutIter + a `PangoLayoutIter` - Obtains the extents of the #PangoLayout being iterated -over. @ink_rect or @logical_rect can be %NULL if you -aren't interested in them. + Obtains the extents of the `PangoLayout` being iterated over. - a #PangoLayoutIter + a `PangoLayoutIter` - rectangle to fill with ink extents, - or %NULL + rectangle to fill with ink extents - rectangle to fill with logical - extents, or %NULL + rectangle to fill with logical extents @@ -8359,40 +8037,41 @@ aren't interested in them. Gets the current line. -Use the faster pango_layout_iter_get_line_readonly() if you do not plan -to modify the contents of the line (glyphs, glyph widths, etc.). +Use the faster [method@Pango.LayoutIter.get_line_readonly] if +you do not plan to modify the contents of the line (glyphs, +glyph widths, etc.). - the current line. + the current line - a #PangoLayoutIter + a `PangoLayoutIter` - Obtains the extents of the current line. @ink_rect or @logical_rect -can be %NULL if you aren't interested in them. Extents are in layout -coordinates (origin is the top-left corner of the entire -#PangoLayout). Thus the extents returned by this function will be -the same width/height but not at the same x/y as the extents -returned from pango_layout_line_get_extents(). + Obtains the extents of the current line. + +Extents are in layout coordinates (origin is the top-left corner +of the entire `PangoLayout`). Thus the extents returned by this +function will be the same width/height but not at the same x/y +as the extents returned from [method@Pango.LayoutLine.get_extents]. - a #PangoLayoutIter + a `PangoLayoutIter` - rectangle to fill with ink extents, or %NULL + rectangle to fill with ink extents - rectangle to fill with logical extents, or %NULL + rectangle to fill with logical extents @@ -8400,178 +8079,185 @@ returned from pango_layout_line_get_extents(). Gets the current line for read-only access. -This is a faster alternative to pango_layout_iter_get_line(), -but the user is not expected -to modify the contents of the line (glyphs, glyph widths, etc.). +This is a faster alternative to [method@Pango.LayoutIter.get_line], +but the user is not expected to modify the contents of the line +(glyphs, glyph widths, etc.). the current line, that should not be -modified. + modified - a #PangoLayoutIter + a `PangoLayoutIter` - Divides the vertical space in the #PangoLayout being iterated over + Divides the vertical space in the `PangoLayout` being iterated over between the lines in the layout, and returns the space belonging to -the current line. A line's range includes the line's logical -extents, plus half of the spacing above and below the line, if -pango_layout_set_spacing() has been called to set layout spacing. -The Y positions are in layout coordinates (origin at top left of the -entire layout). +the current line. -Note: Since 1.44, Pango uses line heights for placing lines, -and there may be gaps between the ranges returned by this -function. +A line's range includes the line's logical extents. plus half of the +spacing above and below the line, if [method@Pango.Layout.set_spacing] +has been called to set layout spacing. The Y positions are in layout +coordinates (origin at top left of the entire layout). + +Note: Since 1.44, Pango uses line heights for placing lines, and there +may be gaps between the ranges returned by this function. - a #PangoLayoutIter + a `PangoLayoutIter` - start of line, or %NULL + start of line - end of line, or %NULL + end of line - Gets the current run. When iterating by run, at the end of each -line, there's a position with a %NULL run, so this function can return -%NULL. The %NULL run at the end of each line ensures that all lines have -at least one run, even lines consisting of only a newline. + Gets the current run. -Use the faster pango_layout_iter_get_run_readonly() if you do not plan -to modify the contents of the run (glyphs, glyph widths, etc.). +When iterating by run, at the end of each line, there's a position +with a %NULL run, so this function can return %NULL. The %NULL run +at the end of each line ensures that all lines have at least one run, +even lines consisting of only a newline. + +Use the faster [method@Pango.LayoutIter.get_run_readonly] if you do not +plan to modify the contents of the run (glyphs, glyph widths, etc.). - the current run. + the current run - a #PangoLayoutIter + a `PangoLayoutIter` - Gets the extents of the current run in layout coordinates -(origin is the top left of the entire layout). + Gets the extents of the current run in layout coordinates. + +Layout coordinates have the origin at the top left of the entire layout. - a #PangoLayoutIter + a `PangoLayoutIter` - rectangle to fill with ink extents, or %NULL + rectangle to fill with ink extents - rectangle to fill with logical extents, or %NULL + rectangle to fill with logical extents - Gets the current run. When iterating by run, at the end of each -line, there's a position with a %NULL run, so this function can return -%NULL. The %NULL run at the end of each line ensures that all lines have -at least one run, even lines consisting of only a newline. + Gets the current run for read-only access. -This is a faster alternative to pango_layout_iter_get_run(), -but the user is not expected -to modify the contents of the run (glyphs, glyph widths, etc.). +When iterating by run, at the end of each line, there's a position +with a %NULL run, so this function can return %NULL. The %NULL run +at the end of each line ensures that all lines have at least one run, +even lines consisting of only a newline. + +This is a faster alternative to [method@Pango.LayoutIter.get_run], +but the user is not expected to modify the contents of the run (glyphs, +glyph widths, etc.). the current run, that -should not be modified. + should not be modified - a #PangoLayoutIter + a `PangoLayoutIter` - Moves @iter forward to the next character in visual order. If @iter was already at -the end of the layout, returns %FALSE. + Moves @iter forward to the next character in visual order. + +If @iter was already at the end of the layout, returns %FALSE. - whether motion was possible. + whether motion was possible - a #PangoLayoutIter + a `PangoLayoutIter` - Moves @iter forward to the next cluster in visual order. If @iter -was already at the end of the layout, returns %FALSE. + Moves @iter forward to the next cluster in visual order. + +If @iter was already at the end of the layout, returns %FALSE. - whether motion was possible. + whether motion was possible - a #PangoLayoutIter + a `PangoLayoutIter` - Moves @iter forward to the start of the next line. If @iter is -already on the last line, returns %FALSE. + Moves @iter forward to the start of the next line. + +If @iter is already on the last line, returns %FALSE. - whether motion was possible. + whether motion was possible - a #PangoLayoutIter + a `PangoLayoutIter` - Moves @iter forward to the next run in visual order. If @iter was -already at the end of the layout, returns %FALSE. + Moves @iter forward to the next run in visual order. + +If @iter was already at the end of the layout, returns %FALSE. - whether motion was possible. + whether motion was possible - a #PangoLayoutIter + a `PangoLayoutIter` - The #PangoLayoutLine structure represents one of the lines resulting -from laying out a paragraph via #PangoLayout. #PangoLayoutLine -structures are obtained by calling pango_layout_get_line() and -are only valid until the text, attributes, or settings of the -parent #PangoLayout are modified. + A `PangoLayoutLine` represents one of the lines resulting from laying +out a paragraph via `PangoLayout`. -Routines for rendering PangoLayout objects are provided in -code specific to each rendering system. +`PangoLayoutLine` structures are obtained by calling +[method@Pango.Layout.get_line] and are only valid until the text, +attributes, or settings of the parent `PangoLayout` are modified. the layout this line belongs to, might be %NULL @@ -8586,7 +8272,7 @@ code specific to each rendering system. list of runs in the - line, from left to right + line, from left to right @@ -8600,38 +8286,39 @@ code specific to each rendering system. - Computes the logical and ink extents of a layout line. See -pango_font_get_glyph_extents() for details about the interpretation -of the rectangles. + Computes the logical and ink extents of a layout line. + +See [method@Pango.Font.get_glyph_extents] for details +about the interpretation of the rectangles. - a #PangoLayoutLine + a `PangoLayoutLine` rectangle used to store the extents of - the glyph string as drawn, or %NULL + the glyph string as drawn rectangle used to store the logical - extents of the glyph string, or %NULL + extents of the glyph string - Computes the height of the line, ie the distance between + Computes the height of the line, i.e. the distance between this and the previous lines baseline. - a #PangoLayoutLine + a `PangoLayoutLine` @@ -8642,32 +8329,34 @@ this and the previous lines baseline. Computes the logical and ink extents of @layout_line in device units. -This function just calls pango_layout_line_get_extents() followed by -two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect + +This function just calls [method@Pango.LayoutLine.get_extents] followed by +two [func@extents_to_pixels] calls, rounding @ink_rect and @logical_rect such that the rounded rectangles fully contain the unrounded one (that is, -passes them as first argument to pango_extents_to_pixels()). +passes them as first argument to [func@extents_to_pixels]). - a #PangoLayoutLine + a `PangoLayoutLine` rectangle used to store the extents of - the glyph string as drawn, or %NULL + the glyph string as drawn rectangle used to store the logical - extents of the glyph string, or %NULL + extents of the glyph string Gets a list of visual ranges corresponding to a given logical range. + This list is not necessarily minimal - there may be consecutive ranges which are adjacent. The ranges will be sorted from left to right. The ranges are with respect to the left edge of the entire @@ -8677,39 +8366,36 @@ layout, not with respect to the line. - a #PangoLayoutLine + a `PangoLayoutLine` Start byte index of the logical range. If this value - is less than the start index for the line, then - the first range will extend all the way to the leading - edge of the layout. Otherwise it will start at the - leading edge of the first character. + is less than the start index for the line, then the first range + will extend all the way to the leading edge of the layout. Otherwise, + it will start at the leading edge of the first character. - Ending byte index of the logical range. If this value - is greater than the end index for the line, then - the last range will extend all the way to the trailing - edge of the layout. Otherwise, it will end at the - trailing edge of the last character. + Ending byte index of the logical range. If this value is + greater than the end index for the line, then the last range will + extend all the way to the trailing edge of the layout. Otherwise, + it will end at the trailing edge of the last character. - - location to store a pointer to an array of ranges. - The array will be of length <literal>2*n_ranges</literal>, - with each range starting at <literal>(*ranges)[2*n]</literal> - and of width <literal>(*ranges)[2*n + 1] - (*ranges)[2*n]</literal>. - This array must be freed with g_free(). The coordinates are relative - to the layout and are in Pango units. + location to + store a pointer to an array of ranges. The array will be of length + `2*n_ranges`, with each range starting at `(*ranges)[2*n]` and of + width `(*ranges)[2*n + 1] - (*ranges)[2*n]`. This array must be freed + with g_free(). The coordinates are relative to the layout and are in + Pango units. - The number of ranges stored in @ranges. + The number of ranges stored in @ranges @@ -8721,7 +8407,7 @@ layout, not with respect to the line. - a #PangoLayoutLine + a `PangoLayoutLine` @@ -8730,31 +8416,32 @@ layout, not with respect to the line. an integer indicating the edge of the grapheme to retrieve - the position of. If > 0, the trailing edge of the grapheme, - if 0, the leading of the grapheme. + the position of. If > 0, the trailing edge of the grapheme, + if 0, the leading of the grapheme - location to store the x_offset (in Pango unit) + location to store the x_offset (in Pango units) - Increase the reference count of a #PangoLayoutLine by one. + Increase the reference count of a `PangoLayoutLine` by one. the line passed in. - a #PangoLayoutLine, may be %NULL + a `PangoLayoutLine` - Decrease the reference count of a #PangoLayoutLine by one. + Decrease the reference count of a `PangoLayoutLine` by one. + If the result is zero, the line and all associated memory will be freed. @@ -8762,54 +8449,53 @@ will be freed. - a #PangoLayoutLine + a `PangoLayoutLine` - Converts from x offset to the byte index of the corresponding -character within the text of the layout. If @x_pos is outside the line, -@index_ and @trailing will point to the very first or very last position -in the line. This determination is based on the resolved direction -of the paragraph; for example, if the resolved direction is -right-to-left, then an X position to the right of the line (after it) + Converts from x offset to the byte index of the corresponding character +within the text of the layout. + +If @x_pos is outside the line, @index_ and @trailing will point to the very +first or very last position in the line. This determination is based on the +resolved direction of the paragraph; for example, if the resolved direction +is right-to-left, then an X position to the right of the line (after it) results in 0 being stored in @index_ and @trailing. An X position to the -left of the line results in @index_ pointing to the (logical) last -grapheme in the line and @trailing being set to the number of characters -in that grapheme. The reverse is true for a left-to-right line. +left of the line results in @index_ pointing to the (logical) last grapheme +in the line and @trailing being set to the number of characters in that +grapheme. The reverse is true for a left-to-right line. %FALSE if @x_pos was outside the line, %TRUE if inside - a #PangoLayoutLine + a `PangoLayoutLine` - the X offset (in Pango units) - from the left edge of the line. + the X offset (in Pango units) from the left edge of the line. - location to store calculated byte index for - the grapheme in which the user clicked. + location to store calculated byte index for the grapheme + in which the user clicked - location to store an integer indicating where - in the grapheme the user clicked. It will either - be zero, or the number of characters in the - grapheme. 0 represents the leading edge of the grapheme. + location to store an integer indicating where in the + grapheme the user clicked. It will either be zero, or the number of + characters in the grapheme. 0 represents the leading edge of the grapheme. - The #PangoLogAttr structure stores information -about the attributes of a single character. + The `PangoLogAttr` structure stores information about the attributes of a +single character. if set, can break line in front of character @@ -8828,11 +8514,10 @@ about the attributes of a single character. if set, cursor can appear in front of character. -i.e. this is a grapheme boundary, or the first character -in the text. -This flag implements Unicode's -<ulink url="http://www.unicode.org/reports/tr29/">Grapheme -Cluster Boundaries</ulink> semantics. + i.e. this is a grapheme boundary, or the first character in the text. + This flag implements Unicode's + [Grapheme Cluster Boundaries](http://www.unicode.org/reports/tr29/) + semantics. @@ -8841,18 +8526,18 @@ Cluster Boundaries</ulink> semantics. is first non-word char after a word -Note that in degenerate cases, you could have both @is_word_start -and @is_word_end set for some character. + Note that in degenerate cases, you could have both @is_word_start + and @is_word_end set for some character. is a sentence boundary. -There are two ways to divide sentences. The first assigns all -inter-sentence whitespace/control/format chars to some sentence, -so all chars are in some sentence; @is_sentence_boundary denotes -the boundaries there. The second way doesn't assign -between-sentence spaces, etc. to any sentence, so -@is_sentence_start/@is_sentence_end mark the boundaries of those sentences. + There are two ways to divide sentences. The first assigns all + inter-sentence whitespace/control/format chars to some sentence, + so all chars are in some sentence; @is_sentence_boundary denotes + the boundaries there. The second way doesn't assign + between-sentence spaces, etc. to any sentence, so + @is_sentence_start/@is_sentence_end mark the boundaries of those sentences. @@ -8861,101 +8546,46 @@ between-sentence spaces, etc. to any sentence, so is first char after a sentence. -Note that in degenerate cases, you could have both @is_sentence_start -and @is_sentence_end set for some character. (e.g. no space after a -period, so the next sentence starts right away) + Note that in degenerate cases, you could have both @is_sentence_start + and @is_sentence_end set for some character. (e.g. no space after a + period, so the next sentence starts right away) if set, backspace deletes one character -rather than the entire grapheme cluster. This -field is only meaningful on grapheme -boundaries (where @is_cursor_position is -set). In some languages, the full grapheme -(e.g. letter + diacritics) is considered a -unit, while in others, each decomposed -character in the grapheme is a unit. In the -default implementation of pango_break(), this -bit is set on all grapheme boundaries except -those following Latin, Cyrillic or Greek base characters. + rather than the entire grapheme cluster. This field is only meaningful + on grapheme boundaries (where @is_cursor_position is set). In some languages, + the full grapheme (e.g. letter + diacritics) is considered a unit, while in + others, each decomposed character in the grapheme is a unit. In the default + implementation of [func@break], this bit is set on all grapheme boundaries + except those following Latin, Cyrillic or Greek base characters. is a whitespace character that can possibly be -expanded for justification purposes. (Since: 1.18) + expanded for justification purposes. (Since: 1.18) is a word boundary, as defined by UAX#29. -More specifically, means that this is not a position in the middle -of a word. For example, both sides of a punctuation mark are -considered word boundaries. This flag is particularly useful when -selecting text word-by-word. -This flag implements Unicode's -<ulink url="http://www.unicode.org/reports/tr29/">Word -Boundaries</ulink> semantics. (Since: 1.22) + More specifically, means that this is not a position in the middle of a word. + For example, both sides of a punctuation mark are considered word boundaries. + This flag is particularly useful when selecting text word-by-word. This flag + implements Unicode's [Word Boundaries](http://www.unicode.org/reports/tr29/) + semantics. (Since: 1.22) - - - Do not use. Does not do anything. - - %NULL. - - - - - a #PangoMap - - - - a #PangoScript - - - - - - Do not use. Does not do anything. - - - - - - a #PangoMap - - - - a #PangoScript - - - - location to store list of engines that exactly - handle this script. - - - - - - location to store list of engines that - approximately handle this script. - - - - - - - - - A structure specifying a transformation between user-space -coordinates and device coordinates. The transformation -is given by + A `PangoMatrix` specifies a transformation between user-space +and device coordinates. -<programlisting> +The transformation is given by + +``` x_device = x_user * matrix->xx + y_user * matrix->xy + matrix->x0; y_device = x_user * matrix->yx + y_user * matrix->yy + matrix->y0; -</programlisting> +``` 1st component of the transformation matrix @@ -8989,61 +8619,61 @@ given by @new_matrix then applying the original transformation. - a #PangoMatrix + a `PangoMatrix` - a #PangoMatrix + a `PangoMatrix` - Copies a #PangoMatrix. + Copies a `PangoMatrix`. - the newly allocated #PangoMatrix, which - should be freed with pango_matrix_free(), or %NULL if - @matrix was %NULL. + the newly allocated `PangoMatrix` - a #PangoMatrix, may be %NULL + a `PangoMatrix` - Free a #PangoMatrix created with pango_matrix_copy(). + Free a `PangoMatrix`. - a #PangoMatrix, may be %NULL + a `PangoMatrix`, may be %NULL Returns the scale factor of a matrix on the height of the font. + That is, the scale factor in the direction perpendicular to the vector that the X coordinate is mapped to. If the scale in the X -coordinate is needed as well, use pango_matrix_get_font_scale_factors(). +coordinate is needed as well, use [method@Pango.Matrix.get_font_scale_factors]. the scale factor of @matrix on the height of the font, -or 1.0 if @matrix is %NULL. + or 1.0 if @matrix is %NULL. - a #PangoMatrix, may be %NULL + a `PangoMatrix`, may be %NULL Calculates the scale factor of a matrix on the width and height of the font. + That is, @xscale is the scale factor in the direction of the X coordinate, and @yscale is the scale factor in the direction perpendicular to the vector that the X coordinate is mapped to. @@ -9054,15 +8684,15 @@ Note that output numbers will always be non-negative. - a #PangoMatrix, or %NULL + a `PangoMatrix` - output scale factor in the x direction, or %NULL + output scale factor in the x direction - output scale factor perpendicular to the x direction, or %NULL + output scale factor perpendicular to the x direction @@ -9076,7 +8706,7 @@ counter-clockwise then applying the original transformation. - a #PangoMatrix + a `PangoMatrix` @@ -9095,7 +8725,7 @@ transformation. - a #PangoMatrix + a `PangoMatrix` @@ -9109,15 +8739,16 @@ transformation. - Transforms the distance vector (@dx,@dy) by @matrix. This is -similar to pango_matrix_transform_point() except that the translation -components of the transformation are ignored. The calculation of -the returned vector is as follows: + Transforms the distance vector (@dx,@dy) by @matrix. -<programlisting> +This is similar to [method@Pango.Matrix.transform_point], +except that the translation components of the transformation +are ignored. The calculation of the returned vector is as follows: + +``` dx2 = dx1 * xx + dy1 * xy; dy2 = dx1 * yx + dy1 * yy; -</programlisting> +``` Affine transformations are position invariant, so the same vector always transforms to the same vector. If (@x1,@y1) transforms @@ -9128,7 +8759,7 @@ to (@x2,@y2) then (@x1+@dx1,@y1+@dy1) will transform to - a #PangoMatrix, or %NULL + a `PangoMatrix` @@ -9143,26 +8774,25 @@ to (@x2,@y2) then (@x1+@dx1,@y1+@dy1) will transform to First transforms the @rect using @matrix, then calculates the bounding box -of the transformed rectangle. The rectangle should be in device units -(pixels). +of the transformed rectangle. This function is useful for example when you want to draw a rotated @PangoLayout to an image buffer, and want to know how large the image should be and how much you should shift the layout when rendering. -For better accuracy, you should use pango_matrix_transform_rectangle() on -original rectangle in Pango units and convert to pixels afterward -using pango_extents_to_pixels()'s first argument. +For better accuracy, you should use [method@Pango.Matrix.transform_rectangle] +on original rectangle in Pango units and convert to pixels afterward +using [func@extents_to_pixels]'s first argument. - a #PangoMatrix, or %NULL + a `PangoMatrix` - - in/out bounding box in device units, or %NULL + + in/out bounding box in device units @@ -9174,7 +8804,7 @@ using pango_extents_to_pixels()'s first argument. - a #PangoMatrix, or %NULL + a `PangoMatrix` @@ -9189,14 +8819,14 @@ using pango_extents_to_pixels()'s first argument. First transforms @rect using @matrix, then calculates the bounding box -of the transformed rectangle. The rectangle should be in Pango units. +of the transformed rectangle. This function is useful for example when you want to draw a rotated @PangoLayout to an image buffer, and want to know how large the image should be and how much you should shift the layout when rendering. If you have a rectangle in device units (pixels), use -pango_matrix_transform_pixel_rectangle(). +[method@Pango.Matrix.transform_pixel_rectangle]. If you have the rectangle in Pango units and want to convert to transformed pixel bounding box, it is more accurate to transform it first @@ -9211,11 +8841,11 @@ example). - a #PangoMatrix, or %NULL + a `PangoMatrix` - - in/out bounding box in Pango units, or %NULL + + in/out bounding box in Pango units @@ -9229,7 +8859,7 @@ then applying the original transformation. - a #PangoMatrix + a `PangoMatrix` @@ -9244,15 +8874,14 @@ then applying the original transformation. - The #PangoOverline enumeration is used to specify -whether text should be overlined, and if so, the type -of line. + The `PangoOverline` enumeration is used to specify whether text +should be overlined, and if so, the type of line. no overline should be drawn Draw a single line above the ink - extents of the text being underlined. + extents of the text being underlined. @@ -9280,14 +8909,16 @@ of line. - Extracts the <firstterm>right bearing</firstterm> from a #PangoRectangle -representing glyph extents. The right bearing is the distance from the -horizontal origin to the farthest right point of the character. -This is positive except for characters drawn completely to the left of the -horizontal origin. + Extracts the *right bearing* from a `PangoRectangle` +representing glyph extents. + +The right bearing is the distance from the horizontal +origin to the farthest right point of the character. +This is positive except for characters drawn completely +to the left of the horizontal origin. - a #PangoRectangle + a `PangoRectangle` @@ -9309,15 +8940,12 @@ horizontal origin. - - A string constant defining the render type -for engines that are not rendering-system specific. - - - The #PangoRectangle structure represents a rectangle. It is frequently -used to represent the logical or ink extents of a single glyph or section -of text. (See, for instance, pango_font_get_glyph_extents()) + The `PangoRectangle` structure represents a rectangle. + +`PangoRectangle` is frequently used to represent the logical or ink +extents of a single glyph or section of text. (See, for instance, +[method@Pango.Font.get_glyph_extents].) X coordinate of the left side of the rectangle. @@ -9336,7 +8964,7 @@ of text. (See, for instance, pango_font_get_glyph_extents()) - #PangoRenderPart defines different items to render for such + `PangoRenderPart` defines different items to render for such purposes as setting colors. the text itself @@ -9355,9 +8983,12 @@ purposes as setting colors. - #PangoRenderer is a base class for objects that are used to -render Pango objects such as #PangoGlyphString and -#PangoLayout. + `PangoRenderer` is a base class for objects that can render text +provided as `PangoGlyphString` or `PangoLayout`. + +By subclassing `PangoRenderer` and overriding operations such as +@draw_glyphs and @draw_rectangle, renderers for particular font +backends and destinations can be created. @@ -9371,18 +9002,19 @@ render Pango objects such as #PangoGlyphString and Draw a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. -(The width of the underline is rounded to an integer number -of up/down segments and the resulting rectangle is centered -in the original rectangle) -This should be called while @renderer is already active. Use -pango_renderer_activate() to activate a renderer. +The width of the underline is rounded to an integer number +of up/down segments and the resulting rectangle is centered +in the original rectangle. + +This should be called while @renderer is already active. +Use [method@Pango.Renderer.activate] to activate a renderer. - a #PangoRenderer + a `PangoRenderer` @@ -9410,11 +9042,11 @@ pango_renderer_activate() to activate a renderer. - a #PangoRenderer + a `PangoRenderer` - a #PangoFont + a `PangoFont` @@ -9432,61 +9064,68 @@ pango_renderer_activate() to activate a renderer. - Draws the glyphs in @glyph_item with the specified #PangoRenderer, + Draws the glyphs in @glyph_item with the specified `PangoRenderer`, embedding the text associated with the glyphs in the output if the -output format supports it (PDF for example). +output format supports it. + +This is useful for rendering text in PDF. + +Note that this method does not handle attributes in @glyph_item. +If you want colors, shapes and lines handled automatically according +to those attributes, you need to use pango_renderer_draw_layout_line() +or pango_renderer_draw_layout(). Note that @text is the start of the text for layout, which is then -indexed by <literal>@glyph_item->item->offset</literal>. +indexed by `glyph_item->item->offset`. -If @text is %NULL, this simply calls pango_renderer_draw_glyphs(). +If @text is %NULL, this simply calls [method@Pango.Renderer.draw_glyphs]. The default implementation of this method simply falls back to -pango_renderer_draw_glyphs(). +[method@Pango.Renderer.draw_glyphs]. - a #PangoRenderer + a `PangoRenderer` - the UTF-8 text that @glyph_item refers to, or %NULL + the UTF-8 text that @glyph_item refers to - a #PangoGlyphItem + a `PangoGlyphItem` X position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units Y position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units - Draws the glyphs in @glyphs with the specified #PangoRenderer. + Draws the glyphs in @glyphs with the specified `PangoRenderer`. - a #PangoRenderer + a `PangoRenderer` - a #PangoFont + a `PangoFont` - a #PangoGlyphString + a `PangoGlyphString` @@ -9496,23 +9135,23 @@ pango_renderer_draw_glyphs(). Y position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units. Draws an axis-aligned rectangle in user space coordinates with the -specified #PangoRenderer. +specified `PangoRenderer`. -This should be called while @renderer is already active. Use -pango_renderer_activate() to activate a renderer. +This should be called while @renderer is already active. +Use [method@Pango.Renderer.activate] to activate a renderer. - a #PangoRenderer + a `PangoRenderer` @@ -9520,19 +9159,21 @@ pango_renderer_activate() to activate a renderer. - X position at which to draw rectangle, in user space coordinates in Pango units + X position at which to draw rectangle, in user space coordinates + in Pango units - Y position at which to draw rectangle, in user space coordinates in Pango units + Y position at which to draw rectangle, in user space coordinates + in Pango units - width of rectangle in Pango units in user space coordinates + width of rectangle in Pango units - height of rectangle in Pango units in user space coordinates + height of rectangle in Pango units @@ -9558,13 +9199,13 @@ pango_renderer_activate() to activate a renderer. Draws a trapezoid with the parallel sides aligned with the X axis -using the given #PangoRenderer; coordinates are in device space. +using the given `PangoRenderer`; coordinates are in device space. - a #PangoRenderer + a `PangoRenderer` @@ -9609,24 +9250,26 @@ using the given #PangoRenderer; coordinates are in device space. Informs Pango that the way that the rendering is done -for @part has changed in a way that would prevent multiple -pieces being joined together into one drawing call. For -instance, if a subclass of #PangoRenderer was to add a stipple +for @part has changed. + +This should be called if the rendering changes in a way that would +prevent multiple pieces being joined together into one drawing call. +For instance, if a subclass of `PangoRenderer` was to add a stipple option for drawing underlines, it needs to call -<informalexample><programlisting> +``` pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); -</programlisting></informalexample> +``` When the stipple changes or underlines with different stipples might be joined together. Pango automatically calls this for -changes to colors. (See pango_renderer_set_color()) +changes to colors. (See [method@Pango.Renderer.set_color]) - a #PangoRenderer + a `PangoRenderer` @@ -9650,31 +9293,34 @@ changes to colors. (See pango_renderer_set_color()) Does initial setup before rendering operations on @renderer. -pango_renderer_deactivate() should be called when done drawing. -Calls such as pango_renderer_draw_layout() automatically -activate the layout before drawing on it. Calls to -pango_renderer_activate() and pango_renderer_deactivate() can -be nested and the renderer will only be initialized and -deinitialized once. + +[method@Pango.Renderer.deactivate] should be called when done drawing. +Calls such as [method@Pango.Renderer.draw_layout] automatically +activate the layout before drawing on it. + +Calls to [method@Pango.Renderer.activate] and +[method@Pango.Renderer.deactivate] can be nested and the +renderer will only be initialized and deinitialized once. - a #PangoRenderer + a `PangoRenderer` - Cleans up after rendering operations on @renderer. See -docs for pango_renderer_activate(). + Cleans up after rendering operations on @renderer. + +See docs for [method@Pango.Renderer.activate]. - a #PangoRenderer + a `PangoRenderer` @@ -9682,18 +9328,19 @@ docs for pango_renderer_activate(). Draw a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. -(The width of the underline is rounded to an integer number -of up/down segments and the resulting rectangle is centered -in the original rectangle) -This should be called while @renderer is already active. Use -pango_renderer_activate() to activate a renderer. +The width of the underline is rounded to an integer number +of up/down segments and the resulting rectangle is centered +in the original rectangle. + +This should be called while @renderer is already active. +Use [method@Pango.Renderer.activate] to activate a renderer. - a #PangoRenderer + a `PangoRenderer` @@ -9721,11 +9368,11 @@ pango_renderer_activate() to activate a renderer. - a #PangoRenderer + a `PangoRenderer` - a #PangoFont + a `PangoFont` @@ -9743,61 +9390,68 @@ pango_renderer_activate() to activate a renderer. - Draws the glyphs in @glyph_item with the specified #PangoRenderer, + Draws the glyphs in @glyph_item with the specified `PangoRenderer`, embedding the text associated with the glyphs in the output if the -output format supports it (PDF for example). +output format supports it. + +This is useful for rendering text in PDF. + +Note that this method does not handle attributes in @glyph_item. +If you want colors, shapes and lines handled automatically according +to those attributes, you need to use pango_renderer_draw_layout_line() +or pango_renderer_draw_layout(). Note that @text is the start of the text for layout, which is then -indexed by <literal>@glyph_item->item->offset</literal>. +indexed by `glyph_item->item->offset`. -If @text is %NULL, this simply calls pango_renderer_draw_glyphs(). +If @text is %NULL, this simply calls [method@Pango.Renderer.draw_glyphs]. The default implementation of this method simply falls back to -pango_renderer_draw_glyphs(). +[method@Pango.Renderer.draw_glyphs]. - a #PangoRenderer + a `PangoRenderer` - the UTF-8 text that @glyph_item refers to, or %NULL + the UTF-8 text that @glyph_item refers to - a #PangoGlyphItem + a `PangoGlyphItem` X position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units Y position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units - Draws the glyphs in @glyphs with the specified #PangoRenderer. + Draws the glyphs in @glyphs with the specified `PangoRenderer`. - a #PangoRenderer + a `PangoRenderer` - a #PangoFont + a `PangoFont` - a #PangoGlyphString + a `PangoGlyphString` @@ -9807,23 +9461,26 @@ pango_renderer_draw_glyphs(). Y position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units. - Draws @layout with the specified #PangoRenderer. + Draws @layout with the specified `PangoRenderer`. + +This is equivalent to drawing the lines of the layout, at their +respective positions relative to @x, @y. - a #PangoRenderer + a `PangoRenderer` - a #PangoLayout + a `PangoLayout` @@ -9833,23 +9490,27 @@ pango_renderer_draw_glyphs(). Y position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units. - Draws @line with the specified #PangoRenderer. + Draws @line with the specified `PangoRenderer`. + +This draws the glyph items that make up the line, as well as +shapes, backgrounds and lines that are specified by the attributes +of those items. - a #PangoRenderer + a `PangoRenderer` - a #PangoLayoutLine + a `PangoLayoutLine` @@ -9859,23 +9520,23 @@ pango_renderer_draw_glyphs(). Y position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units. Draws an axis-aligned rectangle in user space coordinates with the -specified #PangoRenderer. +specified `PangoRenderer`. -This should be called while @renderer is already active. Use -pango_renderer_activate() to activate a renderer. +This should be called while @renderer is already active. +Use [method@Pango.Renderer.activate] to activate a renderer. - a #PangoRenderer + a `PangoRenderer` @@ -9883,32 +9544,34 @@ pango_renderer_activate() to activate a renderer. - X position at which to draw rectangle, in user space coordinates in Pango units + X position at which to draw rectangle, in user space coordinates + in Pango units - Y position at which to draw rectangle, in user space coordinates in Pango units + Y position at which to draw rectangle, in user space coordinates + in Pango units - width of rectangle in Pango units in user space coordinates + width of rectangle in Pango units - height of rectangle in Pango units in user space coordinates + height of rectangle in Pango units Draws a trapezoid with the parallel sides aligned with the X axis -using the given #PangoRenderer; coordinates are in device space. +using the given `PangoRenderer`; coordinates are in device space. - a #PangoRenderer + a `PangoRenderer` @@ -9951,7 +9614,7 @@ using the given #PangoRenderer; coordinates are in device space. - a #PangoRenderer + a `PangoRenderer` @@ -9970,7 +9633,7 @@ using the given #PangoRenderer; coordinates are in device space. - a #PangoRenderer + a `PangoRenderer` @@ -9981,6 +9644,7 @@ using the given #PangoRenderer; coordinates are in device space. Gets the layout currently being rendered using @renderer. + Calling this function only makes sense from inside a subclass's methods, like in its draw_shape vfunc, for example. @@ -9988,18 +9652,19 @@ The returned layout should not be modified while still being rendered. the layout, or %NULL if - no layout is being rendered using @renderer at this time. + no layout is being rendered using @renderer at this time. - a #PangoRenderer + a `PangoRenderer` Gets the layout line currently being rendered using @renderer. + Calling this function only makes sense from inside a subclass's methods, like in its draw_shape vfunc, for example. @@ -10012,47 +9677,51 @@ rendered. - a #PangoRenderer + a `PangoRenderer` Gets the transformation matrix that will be applied when -rendering. See pango_renderer_set_matrix(). +rendering. + +See [method@Pango.Renderer.set_matrix]. the matrix, or %NULL if no matrix has - been set (which is the same as the identity matrix). The returned - matrix is owned by Pango and must not be modified or freed. + been set (which is the same as the identity matrix). The returned + matrix is owned by Pango and must not be modified or freed. - a #PangoRenderer + a `PangoRenderer` Informs Pango that the way that the rendering is done -for @part has changed in a way that would prevent multiple -pieces being joined together into one drawing call. For -instance, if a subclass of #PangoRenderer was to add a stipple +for @part has changed. + +This should be called if the rendering changes in a way that would +prevent multiple pieces being joined together into one drawing call. +For instance, if a subclass of `PangoRenderer` was to add a stipple option for drawing underlines, it needs to call -<informalexample><programlisting> +``` pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); -</programlisting></informalexample> +``` When the stipple changes or underlines with different stipples might be joined together. Pango automatically calls this for -changes to colors. (See pango_renderer_set_color()) +changes to colors. (See [method@Pango.Renderer.set_color]) - a #PangoRenderer + a `PangoRenderer` @@ -10063,6 +9732,7 @@ changes to colors. (See pango_renderer_set_color()) Sets the alpha for part of the rendering. + Note that the alpha may only be used if a color is specified for @part as well. @@ -10070,7 +9740,7 @@ specified for @part as well. - a #PangoRenderer + a `PangoRenderer` @@ -10085,13 +9755,14 @@ specified for @part as well. Sets the color for part of the rendering. -Also see pango_renderer_set_alpha(). + +Also see [method@Pango.Renderer.set_alpha]. - a #PangoRenderer + a `PangoRenderer` @@ -10111,11 +9782,11 @@ Also see pango_renderer_set_alpha(). - a #PangoRenderer + a `PangoRenderer` - a #PangoMatrix, or %NULL to unset any existing matrix. + a `PangoMatrix`, or %NULL to unset any existing matrix (No matrix set is the same as setting the identity matrix.) @@ -10135,8 +9806,8 @@ Also see pango_renderer_set_alpha(). the current transformation matrix for - the Renderer; may be %NULL, which should be treated the - same as the identity matrix. + the Renderer; may be %NULL, which should be treated the + same as the identity matrix. @@ -10144,7 +9815,7 @@ Also see pango_renderer_set_alpha(). - Class structure for #PangoRenderer. + Class structure for `PangoRenderer`. The following vfuncs take user space coordinates in Pango units and have default implementations: @@ -10170,15 +9841,15 @@ and must be implemented: - a #PangoRenderer + a `PangoRenderer` - a #PangoFont + a `PangoFont` - a #PangoGlyphString + a `PangoGlyphString` @@ -10188,7 +9859,7 @@ and must be implemented: Y position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units. @@ -10201,7 +9872,7 @@ and must be implemented: - a #PangoRenderer + a `PangoRenderer` @@ -10209,19 +9880,21 @@ and must be implemented: - X position at which to draw rectangle, in user space coordinates in Pango units + X position at which to draw rectangle, in user space coordinates + in Pango units - Y position at which to draw rectangle, in user space coordinates in Pango units + Y position at which to draw rectangle, in user space coordinates + in Pango units - width of rectangle in Pango units in user space coordinates + width of rectangle in Pango units - height of rectangle in Pango units in user space coordinates + height of rectangle in Pango units @@ -10234,7 +9907,7 @@ and must be implemented: - a #PangoRenderer + a `PangoRenderer` @@ -10284,7 +9957,7 @@ and must be implemented: - a #PangoRenderer + a `PangoRenderer` @@ -10325,11 +9998,11 @@ and must be implemented: - a #PangoRenderer + a `PangoRenderer` - a #PangoFont + a `PangoFont` @@ -10354,7 +10027,7 @@ and must be implemented: - a #PangoRenderer + a `PangoRenderer` @@ -10410,25 +10083,25 @@ and must be implemented: - a #PangoRenderer + a `PangoRenderer` - the UTF-8 text that @glyph_item refers to, or %NULL + the UTF-8 text that @glyph_item refers to - a #PangoGlyphItem + a `PangoGlyphItem` X position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units Y position of left edge of baseline, in user space coordinates - in Pango units. + in Pango units @@ -10458,27 +10131,27 @@ and must be implemented: - The %PANGO_SCALE macro represents the scale between dimensions used -for Pango distances and device units. (The definition of device -units is dependent on the output device; it will typically be pixels -for a screen, and points for a printer.) %PANGO_SCALE is currently -1024, but this may be changed in the future. + The scale between dimensions used for Pango distances and device units. + +The definition of device units is dependent on the output device; it will +typically be pixels for a screen, and points for a printer. %PANGO_SCALE is +currently 1024, but this may be changed in the future. When setting font sizes, device units are always considered to be points (as in "12 point font"), rather than pixels. - The #PangoScript enumeration identifies different writing -systems. The values correspond to the names as defined in the -Unicode standard. See <ulink -url="http://www.unicode.org/reports/tr24/">Unicode Standard Annex -#24: Script names</ulink>. + The `PangoScript` enumeration identifies different writing +systems. + +The values correspond to the names as defined in the Unicode standard. See +[Unicode Standard Annex 24: Script names](http://www.unicode.org/reports/tr24/) Note that this enumeration is deprecated and will not be updated to include values in newer versions of the Unicode standard. -Applications should use the GUnicodeScript enumeration instead, -whose values are interchangeable with PangoScript. +Applications should use the `GUnicodeScript` enumeration instead, +whose values are interchangeable with `PangoScript`. a value never returned from pango_script_for_unichar() @@ -10835,18 +10508,19 @@ base glyph to which it is attached Signwriting. Since: 1.40 - Looks up the script for a particular character (as defined by -Unicode Standard Annex \#24). No check is made for @ch being a -valid Unicode character; if you pass in invalid character, the -result is undefined. + Looks up the script for a particular character. + +The script of a character is defined by Unicode Standard Annex \#24. +No check is made for @ch being a valid Unicode character; if you pass +in invalid character, the result is undefined. Note that while the return type of this function is declared -as PangoScript, as of Pango 1.18, this function simply returns +as `PangoScript`, as of Pango 1.18, this function simply returns the return value of g_unichar_get_script(). Callers must be prepared to handle unknown values. Use g_unichar_get_script() - the #PangoScript for the character. + the `PangoScript` for the character. @@ -10857,61 +10531,62 @@ prepared to handle unknown values. - Given a script, finds a language tag that is reasonably -representative of that script. This will usually be the -most widely spoken or used language written in that script: -for instance, the sample language for %PANGO_SCRIPT_CYRILLIC -is <literal>ru</literal> (Russian), the sample language -for %PANGO_SCRIPT_ARABIC is <literal>ar</literal>. + Finds a language tag that is reasonably representative of @script. -For some -scripts, no sample language will be returned because there -is no language that is sufficiently representative. The best -example of this is %PANGO_SCRIPT_HAN, where various different +The language will usually be the most widely spoken or used language +written in that script: for instance, the sample language for +%PANGO_SCRIPT_CYRILLIC is ru (Russian), the sample language for +%PANGO_SCRIPT_ARABIC is ar. + +For some scripts, no sample language will be returned because +there is no language that is sufficiently representative. The +best example of this is %PANGO_SCRIPT_HAN, where various different variants of written Chinese, Japanese, and Korean all use significantly different sets of Han characters and forms of shared characters. No sample language can be provided for many historical scripts as well. As of 1.18, this function checks the environment variables -PANGO_LANGUAGE and LANGUAGE (checked in that order) first. +`PANGO_LANGUAGE` and `LANGUAGE` (checked in that order) first. If one of them is set, it is parsed as a list of language tags -separated by colons or other separators. This function +separated by colons or other separators. This function will return the first language in the parsed list that Pango -believes may use @script for writing. This last predicate -is tested using pango_language_includes_script(). This can +believes may use @script for writing. This last predicate +is tested using [method@Pango.Language.includes_script]. This can be used to control Pango's font selection for non-primary -languages. For example, a PANGO_LANGUAGE enviroment variable +languages. For example, a `PANGO_LANGUAGE` enviroment variable set to "en:fa" makes Pango choose fonts suitable for Persian (fa) instead of Arabic (ar) when a segment of Arabic text is found -in an otherwise non-Arabic text. The same trick can be used to +in an otherwise non-Arabic text. The same trick can be used to choose a default language for %PANGO_SCRIPT_HAN when setting context language is not feasible. - a #PangoLanguage that is representative -of the script, or %NULL if no such language exists. + a `PangoLanguage` that is representative + of the script - a #PangoScript + a `PangoScript` - A #PangoScriptIter is used to iterate through a string + A `PangoScriptIter` is used to iterate through a string and identify ranges in different scripts. - Create a new #PangoScriptIter, used to break a string of -Unicode text into runs by Unicode script. No copy is made of -@text, so the caller needs to make sure it remains valid until -the iterator is freed with pango_script_iter_free(). + Create a new `PangoScriptIter`, used to break a string of +Unicode text into runs by Unicode script. + +No copy is made of @text, so the caller needs to make +sure it remains valid until the iterator is freed with +[method@Pango.ScriptIter.free]. the new script iterator, initialized to point at the first range in the text, which should be - freed with pango_script_iter_free(). If the string is + freed with [method@Pango.ScriptIter.free]. If the string is empty, it will point at an empty range. @@ -10927,13 +10602,13 @@ the iterator is freed with pango_script_iter_free(). - Frees a #PangoScriptIter created with pango_script_iter_new(). + Frees a `PangoScriptIter`. - a #PangoScriptIter + a `PangoScriptIter` @@ -10944,7 +10619,7 @@ The range is the set of locations p where *start <= p < *end. (That is, it doesn't include the character stored at *end) Note that while the type of the @script argument is declared -as PangoScript, as of Pango 1.18, this function simply returns +as `PangoScript`, as of Pango 1.18, this function simply returns GUnicodeScript values. Callers must be prepared to handle unknown values. @@ -10952,34 +10627,35 @@ values. - a #PangoScriptIter + a `PangoScriptIter` - location to store start position of the range, or %NULL + location to store start position of the range - location to store end position of the range, or %NULL + location to store end position of the range - location to store script for range, or %NULL + location to store script for range - Advances a #PangoScriptIter to the next range. If @iter -is already at the end, it is left unchanged and %FALSE -is returned. + Advances a `PangoScriptIter` to the next range. + +If @iter is already at the end, it is left unchanged +and %FALSE is returned. - %TRUE if @iter was successfully advanced. + %TRUE if @iter was successfully advanced - a #PangoScriptIter + a `PangoScriptIter` @@ -10987,15 +10663,16 @@ is returned. Flags influencing the shaping process. -These can be passed to pango_shape_with_flags(). + +`PangoShapeFlags` can be passed to [func@Pango.shape_with_flags]. Default value. Round glyph positions - and widths to whole device units. This option should - be set if the target renderer can't do subpixel - positioning of glyphs. + and widths to whole device units. This option should + be set if the target renderer can't do subpixel + positioning of glyphs. @@ -11012,7 +10689,7 @@ not visible in the output. Render default-ignorable Unicode - characters visibly + characters visibly @@ -11059,21 +10736,24 @@ within a family. - A #PangoTabAlign specifies where a tab stop appears relative to the text. + `PangoTabAlign` specifies where a tab stop appears relative to the text. the tab stop appears to the left of the text. - A #PangoTabArray struct contains an array -of tab stops. Each tab stop has an alignment and a position. + A `PangoTabArray` contains an array of tab stops. + +`PangoTabArray` can be used to set tab stops in a `PangoLayout`. +Each tab stop has an alignment and a position. - Creates an array of @initial_size tab stops. Tab stops are specified in -pixel units if @positions_in_pixels is %TRUE, otherwise in Pango -units. All stops are initially at position 0. + Creates an array of @initial_size tab stops. + +Tab stops are specified in pixel units if @positions_in_pixels is %TRUE, +otherwise in Pango units. All stops are initially at position 0. - the newly allocated #PangoTabArray, which should - be freed with pango_tab_array_free(). + the newly allocated `PangoTabArray`, which should + be freed with [method@Pango.TabArray.free]. @@ -11088,13 +10768,13 @@ units. All stops are initially at position 0. - This is a convenience function that creates a #PangoTabArray -and allows you to specify the alignment and position of each -tab stop. You <emphasis>must</emphasis> provide an alignment -and position for @size tab stops. + Creates a `PangoTabArray` and allows you to specify the alignment +and position of each tab stop. + +You **must** provide an alignment and position for @size tab stops. - the newly allocated #PangoTabArray, which should - be freed with pango_tab_array_free(). + the newly allocated `PangoTabArray`, which should + be freed with [method@Pango.TabArray.free]. @@ -11121,15 +10801,15 @@ and position for @size tab stops. - Copies a #PangoTabArray + Copies a `PangoTabArray`. - the newly allocated #PangoTabArray, which should - be freed with pango_tab_array_free(). + the newly allocated `PangoTabArray`, which should + be freed with [method@Pango.TabArray.free]. - #PangoTabArray to copy + `PangoTabArray` to copy @@ -11141,21 +10821,21 @@ and position for @size tab stops. - a #PangoTabArray + a `PangoTabArray` - Returns %TRUE if the tab positions are in pixels, %FALSE if they are -in Pango units. + Returns %TRUE if the tab positions are in pixels, +%FALSE if they are in Pango units. whether positions are in pixels. - a #PangoTabArray + a `PangoTabArray` @@ -11168,7 +10848,7 @@ in Pango units. - a #PangoTabArray + a `PangoTabArray` @@ -11180,7 +10860,7 @@ in Pango units. - a #PangoTabArray + a `PangoTabArray` @@ -11188,35 +10868,37 @@ in Pango units. - location to store alignment, or %NULL + location to store alignment - location to store tab position, or %NULL + location to store tab position If non-%NULL, @alignments and @locations are filled with allocated -arrays of length pango_tab_array_get_size(). You must free the -returned array. +arrays. + +The arrays are of length [method@Pango.TabArray.get_size]. +You must free the returned array. - a #PangoTabArray + a `PangoTabArray` location to store an array of tab - stop alignments, or %NULL + stop alignments location to store an array - of tab positions, or %NULL + of tab positions @@ -11224,14 +10906,16 @@ returned array. - Resizes a tab array. You must subsequently initialize any tabs that -were added as a result of growing the array. + Resizes a tab array. + +You must subsequently initialize any tabs +that were added as a result of growing the array. - a #PangoTabArray + a `PangoTabArray` @@ -11242,14 +10926,15 @@ were added as a result of growing the array. Sets the alignment and location of a tab stop. -@alignment must always be #PANGO_TAB_LEFT in the current + +@alignment must always be %PANGO_TAB_LEFT in the current implementation. - a #PangoTabArray + a `PangoTabArray` @@ -11267,14 +10952,6 @@ implementation. - - - - - - - - Rounds a dimension to whole device units, but does not convert it to device units. @@ -11284,16 +10961,9 @@ convert it to device units. - - - - - - - The #PangoUnderline enumeration is used to specify -whether text should be underlined, and if so, the type -of underlining. + The `PangoUnderline` enumeration is used to specify whether text +should be underlined, and if so, the type of underlining. no underline should be drawn @@ -11305,33 +10975,36 @@ of underlining. a single underline should be drawn at a - position beneath the ink extents of the text being - underlined. This should be used only for underlining - single characters, such as for keyboard accelerators. - %PANGO_UNDERLINE_SINGLE should be used for extended - portions of text. + position beneath the ink extents of the text being + underlined. This should be used only for underlining + single characters, such as for keyboard accelerators. + %PANGO_UNDERLINE_SINGLE should be used for extended + portions of text. - a wavy underline should be drawn below. - This underline is typically used to indicate an error such - as a possible mispelling; in some cases a contrasting color - may automatically be used. This type of underlining is - available since Pango 1.4. + an underline indicating an error should + be drawn below. The exact style of rendering is up to the + `PangoRenderer` in use, but typical styles include wavy + or dotted lines. + This underline is typically used to indicate an error such + as a possible mispelling; in some cases a contrasting color + may automatically be used. This type of underlining is + available since Pango 1.4. Like @PANGO_UNDERLINE_SINGLE, but - drawn continuously across multiple runs. This type - of underlining is available since Pango 1.46. + drawn continuously across multiple runs. This type + of underlining is available since Pango 1.46. Like @PANGO_UNDERLINE_DOUBLE, but - drawn continuously across multiple runs. This type - of underlining is available since Pango 1.46. + drawn continuously across multiple runs. This type + of underlining is available since Pango 1.46. Like @PANGO_UNDERLINE_ERROR, but - drawn continuously across multiple runs. This type - of underlining is available since Pango 1.46. + drawn continuously across multiple runs. This type + of underlining is available since Pango 1.46. @@ -11365,21 +11038,22 @@ Two encoded version numbers can be compared as integers. - - A macro that should be defined by the user prior to including -the pango.h header. -The definition should be one of the predefined Pango version -macros: %PANGO_VERSION_1_2, %PANGO_VERSION_1_4,... - -This macro defines the earliest version of Pango that the package is -required to be able to compile against. - -If the compiler is configured to warn about the use of deprecated -functions, then using functions that were deprecated in version -%PANGO_VERSION_MIN_REQUIRED or earlier will cause warnings (but -using functions deprecated in later releases will not). + + The major component of the version of Pango available at compile-time. + + The micro component of the version of Pango available at compile-time. + + + + The minor component of the version of Pango available at compile-time. + + + + A string literal containing the version of Pango available at compile-time. + + An enumeration specifying capitalization variant of the font. @@ -11391,8 +11065,10 @@ replaced by smaller variants of the capital characters. - An enumeration specifying the weight (boldness) of a font. This is a numerical -value ranging from 100 to 1000, but there are some predefined values: + An enumeration specifying the weight (boldness) of a font. + +This is a numerical value ranging from 100 to 1000, but there +are some predefined values. the thin weight (= 100; Since: 1.24) @@ -11431,7 +11107,13 @@ value ranging from 100 to 1000, but there are some predefined values: - A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width. + `PangoWrapMode` describes how to wrap the lines of a `PangoLayout` +to the desired width. + +For @PANGO_WRAP_WORD, Pango uses break opportunities that are determined +by the Unicode line breaking algorithm. For @PANGO_WRAP_CHAR, Pango allows +breaking at grapheme boundaries that are determined by the Unicode text +segmentation algorithm. wrap lines at word boundaries. @@ -11439,8 +11121,8 @@ value ranging from 100 to 1000, but there are some predefined values: wrap lines at character boundaries. - wrap lines at word boundaries, but fall back to character boundaries if there is not -enough space for a full word. + wrap lines at word boundaries, but fall back to + character boundaries if there is not enough space for a full word. @@ -11449,8 +11131,9 @@ enough space for a full word. If breaks are disabled, the range will be kept in a single run, as far as possible. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy() + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11463,8 +11146,9 @@ single run, as far as possible. Create a new background alpha attribute. - the new allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11477,8 +11161,9 @@ single run, as far as possible. Create a new background color attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11499,19 +11184,20 @@ single run, as far as possible. Create a new font fallback attribute. -If fallback is disabled, characters will only be used from the -closest matching font on the system. No fallback will be done to -other fonts on the system that might contain the characters in the -text. +If fallback is disabled, characters will only be +used from the closest matching font on the system. +No fallback will be done to other fonts on the system +that might contain the characters in the text. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] %TRUE if we should fall back on other fonts - for characters the active font is missing. + for characters the active font is missing @@ -11519,24 +11205,27 @@ text. Create a new font family attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - the family or comma separated list of families + the family or comma-separated list of families - Create a new font description attribute. This attribute -allows setting family, style, weight, variant, stretch, -and size simultaneously. + Create a new font description attribute. + +This attribute allows setting family, style, weight, variant, +stretch, and size simultaneously. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11547,15 +11236,20 @@ and size simultaneously. - Create a new font features tag attribute. + Create a new font features tag attribute. + +You can use this attribute to select OpenType font features like small-caps, +alternative glyphs, ligatures, etc. for fonts that support them. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - a string with OpenType font features, in CSS syntax + a string with OpenType font features, with the syntax of the [CSS +font-feature-settings property](https://www.w3.org/TR/css-fonts-4/#font-rend-desc) @@ -11563,8 +11257,9 @@ and size simultaneously. Create a new foreground alpha attribute. - the new allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11577,8 +11272,9 @@ and size simultaneously. Create a new foreground color attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11599,13 +11295,14 @@ and size simultaneously. Create a new gravity hint attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - the gravity hint value. + the gravity hint value @@ -11613,13 +11310,14 @@ and size simultaneously. Create a new gravity attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - the gravity value; should not be %PANGO_GRAVITY_AUTO. + the gravity value; should not be %PANGO_GRAVITY_AUTO @@ -11627,11 +11325,13 @@ and size simultaneously. Create a new insert-hyphens attribute. -Pango will insert hyphens when breaking lines in the middle -of a word. This attribute can be used to suppress the hyphen. +Pango will insert hyphens when breaking lines in +the middle of a word. This attribute can be used +to suppress the hyphen. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy() + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11644,8 +11344,9 @@ of a word. This attribute can be used to suppress the hyphen. Create a new language tag attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11658,25 +11359,28 @@ of a word. This attribute can be used to suppress the hyphen. Create a new letter-spacing attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - amount of extra space to add between graphemes - of the text, in Pango units. + amount of extra space to add between + graphemes of the text, in Pango units - Create a new overline color attribute. This attribute -modifies the color of overlines. If not set, overlines -will use the foreground color. + Create a new overline color attribute. + +This attribute modifies the color of overlines. +If not set, overlines will use the foreground color. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11697,8 +11401,9 @@ will use the foreground color. Create a new overline-style attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11711,24 +11416,28 @@ will use the foreground color. Create a new baseline displacement attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] the amount that the text should be displaced vertically, - in Pango units. Positive values displace the text upwards. + in Pango units. Positive values displace the text upwards. - Create a new font size scale attribute. The base font for the -affected text will have its size multiplied by @scale_factor. + Create a new font size scale attribute. + +The base font for the affected text will have +its size multiplied by @scale_factor. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11739,13 +11448,16 @@ affected text will have its size multiplied by @scale_factor. - Create a new shape attribute. A shape is used to impose a -particular ink and logical rectangle on the result of shaping a -particular glyph. This might be used, for instance, for -embedding a picture or a widget inside a #PangoLayout. + Create a new shape attribute. + +A shape is used to impose a particular ink and logical +rectangle on the result of shaping a particular glyph. +This might be used, for instance, for embedding a picture +or a widget inside a `PangoLayout`. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11760,12 +11472,15 @@ embedding a picture or a widget inside a #PangoLayout. - Like pango_attr_shape_new(), but a user data pointer is also -provided; this pointer can be accessed when later + Creates a new shape attribute. + +Like [func@Pango.AttrShape.new], but a user data pointer +is also provided; this pointer can be accessed when later rendering the glyph. - the newly allocated #PangoAttribute, which should be - freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11783,13 +11498,13 @@ rendering the glyph. function to copy @data when the - attribute is copied. If %NULL, @data is simply - copied as a pointer. + attribute is copied. If %NULL, @data is simply copied + as a pointer function to free @data when the - attribute is freed, or %NULL + attribute is freed @@ -11798,13 +11513,14 @@ rendering the glyph. Create a new attribute that influences how invisible characters are rendered. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - #PangoShowFlags to apply + `PangoShowFlags` to apply @@ -11812,13 +11528,14 @@ characters are rendered. Create a new font-size attribute in fractional points. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - the font size, in %PANGO_SCALEths of a point. + the font size, in %PANGO_SCALE-ths of a point @@ -11826,22 +11543,24 @@ characters are rendered. Create a new font-size attribute in device units. - the newly allocated #PangoAttribute, which should be - freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - the font size, in %PANGO_SCALEths of a device unit. + the font size, in %PANGO_SCALE-ths of a device unit - Create a new font stretch attribute + Create a new font stretch attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11852,12 +11571,14 @@ characters are rendered. - Create a new strikethrough color attribute. This attribute -modifies the color of strikethrough lines. If not set, strikethrough -lines will use the foreground color. + Create a new strikethrough color attribute. + +This attribute modifies the color of strikethrough lines. +If not set, strikethrough lines will use the foreground color. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11878,13 +11599,14 @@ lines will use the foreground color. Create a new strike-through attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - %TRUE if the text should be struck-through. + %TRUE if the text should be struck-through @@ -11892,8 +11614,9 @@ lines will use the foreground color. Create a new font slant style attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11904,14 +11627,19 @@ lines will use the foreground color. - Fetches the attribute type name passed in when registering the type using -pango_attr_type_register(). + Fetches the attribute type name. -The returned value is an interned string (see g_intern_string() for what -that means) that should not be modified or freed. +The attribute type name is the string passed in +when registering the type using +[func@Pango.AttrType.register]. + +The returned value is an interned string (see +g_intern_string() for what that means) that should +not be modified or freed. - the type ID name (which may be %NULL), or -%NULL if @type is a built-in Pango attribute type or invalid. + the type ID name (which + may be %NULL), or %NULL if @type is a built-in Pango + attribute type or invalid. @@ -11922,8 +11650,10 @@ that means) that should not be modified or freed. - Allocate a new attribute type ID. The attribute type name can be accessed -later by using pango_attr_type_get_name(). + Allocate a new attribute type ID. + +The attribute type name can be accessed later +by using [func@Pango.AttrType.get_name]. the new type ID. @@ -11936,12 +11666,14 @@ later by using pango_attr_type_get_name(). - Create a new underline color attribute. This attribute -modifies the color of underlines. If not set, underlines -will use the foreground color. + Create a new underline color attribute. + +This attribute modifies the color of underlines. +If not set, underlines will use the foreground color. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -11962,22 +11694,23 @@ will use the foreground color. Create a new underline-style attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] - the underline style. + the underline style - Create a new font variant attribute (normal or small caps) + Create a new font variant attribute (normal or small caps). - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated `PangoAttribute`, + which should be freed with [method@Pango.Attribute.destroy]. @@ -11990,8 +11723,9 @@ will use the foreground color. Create a new font weight attribute. - the newly allocated #PangoAttribute, - which should be freed with pango_attribute_destroy(). + the newly allocated + `PangoAttribute`, which should be freed with + [method@Pango.Attribute.destroy] @@ -12001,22 +11735,12 @@ will use the foreground color. - - Pango supports bidirectional text (like Arabic and Hebrew) automatically. -Some applications however, need some help to correctly handle bidirectional text. - -The #PangoDirection type can be used with pango_context_set_base_dir() to -instruct Pango about direction of text, though in most cases Pango detects -that correctly and automatically. The rest of the facilities in this section -are used internally by Pango already, and are provided to help applications -that need more direct control over bidirectional setting of text. - - Determines the normative bidirectional character type of a -character, as specified in the Unicode Character Database. + Determines the bidirectional type of a character. -A simplified version of this function is available as -pango_unichar_direction(). +The bidirectional type is specified in the Unicode Character Database. + +A simplified version of this function is available as [func@unichar_direction]. the bidirectional character type, as used in the Unicode bidirectional algorithm. @@ -12032,8 +11756,11 @@ Unicode bidirectional algorithm. Determines possible line, word, and character breaks for a string of Unicode text with a single analysis. -For most purposes you may want to use pango_get_log_attrs(). - Use pango_default_break() and pango_tailor_break() + +For most purposes you may want to use +[func@Pango.get_log_attrs]. + Use [func@Pango.default_break] and + [func@Pango.tailor_break] @@ -12047,12 +11774,11 @@ For most purposes you may want to use pango_get_log_attrs(). - #PangoAnalysis structure from pango_itemize() + `PangoAnalysis` structure for @text - an array to store character - information in + an array to store character information in @@ -12063,24 +11789,14 @@ For most purposes you may want to use pango_get_log_attrs(). - - The #PangoContext structure stores global information -influencing Pango's operation, such as the fontmap used -to look up fonts, and default values such as the default -language, default gravity, or default font. - - - It is often necessary in Pango to determine if a particular font can -represent a particular character, and also how well it can represent -that character. The #PangoCoverage is a data structure that is used -to represent that information. - - This is the default break algorithm. It applies Unicode -rules without language-specific tailoring, therefore -the @analyis argument is unused and can be %NULL. + This is the default break algorithm. -See pango_tailor_break() for language-specific breaks. +It applies Unicode rules without language-specific +tailoring, therefore the @analyis argument is unused +and can be %NULL. + +See [func@Pango.tailor_break] for language-specific breaks. @@ -12094,7 +11810,7 @@ See pango_tailor_break() for language-specific breaks. - a #PangoAnalysis for the @text + a `PangoAnalysis` structure for the @text @@ -12107,28 +11823,22 @@ See pango_tailor_break() for language-specific breaks. - - Pango used to have a module architecture in which the language-specific -and render-system-specific components are provided by loadable -modules. - -This is no longer the case, and all the APIs related -to modules and engines should not be used anymore. - - Converts extents from Pango units to device units, dividing by the -%PANGO_SCALE factor and performing rounding. + Converts extents from Pango units to device units. -The @inclusive rectangle is converted by flooring the x/y coordinates and extending -width/height, such that the final rectangle completely includes the original -rectangle. +The conversion is done by dividing by the %PANGO_SCALE factor and +performing rounding. + +The @inclusive rectangle is converted by flooring the x/y coordinates +and extending width/height, such that the final rectangle completely +includes the original rectangle. The @nearest rectangle is converted by rounding the coordinates of the rectangle to the nearest device unit (pixel). The rule to which argument to use is: if you want the resulting device-space -rectangle to completely contain the original rectangle, pass it in as @inclusive. -If you want two touching-but-not-overlapping rectangles stay +rectangle to completely contain the original rectangle, pass it in as +@inclusive. If you want two touching-but-not-overlapping rectangles stay touching-but-not-overlapping after rounding to device units, pass them in as @nearest. @@ -12136,11 +11846,11 @@ as @nearest. - rectangle to round to pixels inclusively, or %NULL. + rectangle to round to pixels inclusively - rectangle to round to nearest pixels, or %NULL. + rectangle to round to nearest pixels @@ -12150,7 +11860,7 @@ as @nearest. direction, according to the Unicode bidirectional algorithm. The direction corresponding to the first strong character. -If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned. + If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned. @@ -12164,38 +11874,21 @@ If no such character is found, then %PANGO_DIRECTION_NEUTRAL is returned. - - Do not use. Does not do anything. - - %NULL. - - - - - the language tag for which to find the map - - - - the engine type for the map to find - - - - the render type for the map to find - - - - - Locates a paragraph boundary in @text. A boundary is caused by -delimiter characters, such as a newline, carriage return, carriage -return-newline pair, or Unicode paragraph separator character. The -index of the run of delimiters is returned in -@paragraph_delimiter_index. The index of the start of the paragraph -(index after all delimiters) is stored in @next_paragraph_start. + Locates a paragraph boundary in @text. -If no delimiters are found, both @paragraph_delimiter_index and -@next_paragraph_start are filled with the length of @text (an index one -off the end). +A boundary is caused by delimiter characters, such as +a newline, carriage return, carriage return-newline pair, +or Unicode paragraph separator character. + +The index of the run of delimiters is returned in +@paragraph_delimiter_index. The index of the start +of the paragrap (index after all delimiters) is stored +in @next_paragraph_start. + +If no delimiters are found, both @paragraph_delimiter_index +and @next_paragraph_start are filled with the length of @text +(an index one off the end). @@ -12221,10 +11914,11 @@ off the end). - Creates a new font description from a string representation in the -form + Creates a new font description from a string representation. -"\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", +The string must have the form + + "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", where FAMILY-LIST is a comma-separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace-separated list @@ -12262,9 +11956,9 @@ size in the resulting font description will be set to 0. A typical example: -"Cantarell Italic Light 15 \@wght=200" + "Cantarell Italic Light 15 \@wght=200" - a new #PangoFontDescription. + a new `PangoFontDescription`. @@ -12274,22 +11968,16 @@ A typical example: - - Pango supports a flexible architecture where a -particular rendering architecture can supply an -implementation of fonts. The #PangoFont structure -represents an abstract rendering-system-independent font. -Pango provides routines to list available fonts, and -to load a font matching a given description. - - Computes a #PangoLogAttr for each character in @text. The @log_attrs -array must have one #PangoLogAttr for each position in @text; if -@text contains N characters, it has N+1 positions, including the -last position at the end of the text. @text should be an entire -paragraph; logical attributes can't be computed without context -(for example you need to see spaces on either side of a word to know -the word is a word). + Computes a `PangoLogAttr` for each character in @text. + +The @log_attrs array must have one `PangoLogAttr` for +each position in @text; if @text contains N characters, +it has N+1 positions, including the last position at the +end of the text. @text should be an entire paragraph; +logical attributes can't be computed without context +(for example you need to see spaces on either side of +a word to know the word is a word). @@ -12311,7 +11999,7 @@ the word is a word). - array with one #PangoLogAttr + array with one `PangoLogAttr` per character in @text, plus one extra, to be filled in @@ -12323,13 +12011,12 @@ the word is a word). - - If @ch has the Unicode mirrored property and there is another Unicode -character that typically has a glyph that is the mirror image of @ch's -glyph, puts that character in the address pointed to by @mirrored_ch. + + Returns the mirrored character of a Unicode character. -Use g_unichar_get_mirror_char() instead; the docs for that function -provide full details. +Mirror characters are determined by the Unicode mirrored property. + Use g_unichar_get_mirror_char() instead; the docs for that function +provide full details. %TRUE if @ch has a mirrored character and @mirrored_ch is filled in, %FALSE otherwise @@ -12346,15 +12033,9 @@ filled in, %FALSE otherwise - - pango_shape() produces a string of glyphs which -can be measured or drawn to the screen. The following -structures are used to store information about -glyphs. - Finds the gravity that best matches the rotation component -in a #PangoMatrix. +in a `PangoMatrix`. the gravity of @matrix, which will never be %PANGO_GRAVITY_AUTO, or %PANGO_GRAVITY_SOUTH if @matrix is %NULL @@ -12362,26 +12043,27 @@ in a #PangoMatrix. - a #PangoMatrix + a `PangoMatrix` - Based on the script, base gravity, and hint, returns actual gravity -to use in laying out a single #PangoItem. + Returns the gravity to use in laying out a `PangoItem`. + +The gravity is determined based on the script, base gravity, and hint. If @base_gravity is %PANGO_GRAVITY_AUTO, it is first replaced with the preferred gravity of @script. To get the preferred gravity of a script, pass %PANGO_GRAVITY_AUTO and %PANGO_GRAVITY_HINT_STRONG in. resolved gravity suitable to use for a run of text -with @script. +with @script - #PangoScript to query + `PangoScript` to query @@ -12395,14 +12077,16 @@ with @script. - Based on the script, East Asian width, base gravity, and hint, -returns actual gravity to use in laying out a single character -or #PangoItem. + Returns the gravity to use in laying out a single character +or `PangoItem`. -This function is similar to pango_gravity_get_for_script() except +The gravity is determined based on the script, East Asian width, +base gravity, and hint, + +This function is similar to [func@Pango.Gravity.get_for_script] except that this function makes a distinction between narrow/half-width and -wide/full-width characters also. Wide/full-width characters always -stand <emphasis>upright</emphasis>, that is, they always take the base gravity, +wide/full-width characters also. Wide/full-width characters always +stand *upright*, that is, they always take the base gravity, whereas narrow/full-width characters are always rotated in vertical context. @@ -12415,7 +12099,7 @@ with @script and @wide. - #PangoScript to query + `PangoScript` to query @@ -12433,11 +12117,10 @@ with @script and @wide. - Converts a #PangoGravity value to its natural rotation in radians. -@gravity should not be %PANGO_GRAVITY_AUTO. + Converts a `PangoGravity` value to its natural rotation in radians. -Note that pango_matrix_rotate() takes angle in degrees, not radians. -So, to call pango_matrix_rotate() with the output of this function +Note that [method@Pango.Matrix.rotate] takes angle in degrees, not radians. +So, to call [method@Pango.Matrix,rotate] with the output of this function you should multiply it by (180. / G_PI). the rotation value corresponding to @gravity. @@ -12445,17 +12128,17 @@ you should multiply it by (180. / G_PI). - gravity to query + gravity to query, should not be %PANGO_GRAVITY_AUTO - Checks @ch to see if it is a character that should not be -normally rendered on the screen. This includes all Unicode characters -with "ZERO WIDTH" in their name, as well as <firstterm>bidi</firstterm> formatting characters, and -a few other ones. This is totally different from g_unichar_iszerowidth() -and is at best misnamed. + Checks if a character that should not be normally rendered. + +This includes all Unicode characters with "ZERO WIDTH" in their name, +as well as *bidi* formatting characters, and a few other ones. This is +totally different from g_unichar_iszerowidth() and is at best misnamed. %TRUE if @ch is a zero-width character, %FALSE otherwise @@ -12468,21 +12151,22 @@ and is at best misnamed. - Breaks a piece of text into segments with consistent -directional level and shaping engine. Each byte of @text will -be contained in exactly one of the items in the returned list; -the generated list of items will be in logical order (the start -offsets of the items are ascending). + Breaks a piece of text into segments with consistent directional +level and font. -@cached_iter should be an iterator over @attrs currently positioned at a -range before or containing @start_index; @cached_iter will be advanced to -the range covering the position just after @start_index + @length. -(i.e. if itemizing in a loop, just keep passing in the same @cached_iter). +Each byte of @text will be contained in exactly one of the items in the +returned list; the generated list of items will be in logical order (the +start offsets of the items are ascending). + +@cached_iter should be an iterator over @attrs currently positioned +at a range before or containing @start_index; @cached_iter will be +advanced to the range covering the position just after +@start_index + @length. (i.e. if itemizing in a loop, just keep passing +in the same @cached_iter). - a #GList of #PangoItem - structures. The items should be freed using pango_item_free() - probably in combination with g_list_foreach(), and the list itself - using g_list_free(). + a `GList` of + [struct@Pango.Item] structures. The items should be freed using + [method@Pango.Item.free] probably in combination with g_list_free_full(). @@ -12490,7 +12174,7 @@ the range covering the position just after @start_index + @length. a structure holding information that affects - the itemization process. + the itemization process. @@ -12503,8 +12187,7 @@ the range covering the position just after @start_index + @length. the number of bytes (not characters) to process - after @start_index. - This must be >= 0. + after @start_index. This must be >= 0. @@ -12512,20 +12195,21 @@ the range covering the position just after @start_index + @length. - Cached attribute iterator, or %NULL + Cached attribute iterator - Like pango_itemize(), but the base direction to use when -computing bidirectional levels (see pango_context_set_base_dir ()), -is specified explicitly rather than gotten from the #PangoContext. + Like `pango_itemize()`, but with an explicitly specified base direction. + +The base direction is used when computing bidirectional levels. +(see [method@Pango.Context.set_base_dir]). [func@itemize] gets the +base direction from the `PangoContext`. - a #GList of - #PangoItem structures. The items should be freed using - pango_item_free() probably in combination with - g_list_foreach(), and the list itself using g_list_free(). + a `GList` of + [struct@Pango.Item] structures. The items should be freed using + [method@Pango.Item.free] probably in combination with g_list_free_full(). @@ -12533,7 +12217,7 @@ is specified explicitly rather than gotten from the #PangoContext. a structure holding information that affects - the itemization process. + the itemization process. @@ -12550,7 +12234,7 @@ is specified explicitly rather than gotten from the #PangoContext. the number of bytes (not characters) to process - after @start_index. This must be >= 0. + after @start_index. This must be >= 0. @@ -12558,43 +12242,40 @@ is specified explicitly rather than gotten from the #PangoContext. - Cached attribute iterator, or %NULL + Cached attribute iterator - Take a RFC-3066 format language tag as a string and convert it to a -#PangoLanguage pointer that can be efficiently copied (copy the -pointer) and compared with other language tags (compare the -pointer.) + Convert a language tag to a `PangoLanguage`. + +The language tag must be in a RFC-3066 format. `PangoLanguage` pointers +can be efficiently copied (copy the pointer) and compared with other +language tags (compare the pointer.) This function first canonicalizes the string by converting it to lowercase, mapping '_' to '-', and stripping all characters other than letters and '-'. -Use pango_language_get_default() if you want to get the #PangoLanguage for -the current locale of the process. +Use [func@Pango.Language.get_default] if you want to get the +`PangoLanguage` for the current locale of the process. - an opaque pointer to a - #PangoLanguage structure, or %NULL if @language was - %NULL. The returned pointer will be valid forever - after, and should not be freed. + a `PangoLanguage` - a string representing a language tag, or %NULL + a string representing a language tag - Returns the #PangoLanguage for the current locale of the process. -Note that this can change over the life of an application. + Returns the `PangoLanguage` for the current locale of the process. On Unix systems, this is the return value is derived from -<literal>setlocale(LC_CTYPE, NULL)</literal>, and the user can +`setlocale (LC_CTYPE, NULL)`, and the user can affect this through the environment variables LC_ALL, LC_CTYPE or LANG (checked in that order). The locale string typically is in the form lang_COUNTRY, where lang is an ISO-639 language code, and @@ -12612,28 +12293,40 @@ However, this function does check the above environment variables, and does return a Unix-style locale string based on either said environment variables or the thread's current locale. -Your application should call <literal>setlocale(LC_ALL, "");</literal> -for the user settings to take effect. Gtk+ does this in its initialization +Your application should call `setlocale(LC_ALL, "")` for the user +settings to take effect. GTK does this in its initialization functions automatically (by calling gtk_set_locale()). -See <literal>man setlocale</literal> for more details. +See the setlocale() manpage for more details. + +Note that the default language can change over the life of an application. - the default language as a - #PangoLanguage, must not be freed. + the default language as a `PangoLanguage` - - While complete access to the layout capabilities of Pango is provided -using the detailed interfaces for itemization and shaping, using -that functionality directly involves writing a fairly large amount -of code. The objects and functions in this section provide a -high-level driver for formatting entire paragraphs of text -at once. This includes paragraph-level functionality such as -line-breaking, justification, alignment and ellipsization. - + + Returns the list of languages that the user prefers. + +The list is specified by the `PANGO_LANGUAGE` or `LANGUAGE` +environment variables, in order of preference. Note that this +list does not necessarily include the language returned by +[func@Pango.Language.get_default]. + +When choosing language-specific resources, such as the sample +text returned by [method@Pango.Language.get_sample_string], +you should first try the default language, followed by the +languages returned by this function. + + a %NULL-terminated array + of `PangoLanguage`* + + + - This will return the bidirectional embedding levels of the input paragraph -as defined by the Unicode Bidirectional Algorithm available at: + Return the bidirectional embedding levels of the input paragraph. + +The bidirectional embedding levels are defined by the Unicode Bidirectional +Algorithm available at: http://www.unicode.org/reports/tr9/ @@ -12641,7 +12334,7 @@ If the input base direction is a weak direction, the direction of the characters in the text will determine the final resolved direction. a newly allocated array of embedding levels, one item per - character (not byte), that should be freed using g_free. + character (not byte), that should be freed using g_free(). @@ -12651,7 +12344,7 @@ characters in the text will determine the final resolved direction. the number of bytes (not characters) to process, or -1 - if @text is nul-terminated and the length should be calculated. + if @text is nul-terminated and the length should be calculated. @@ -12660,203 +12353,11 @@ characters in the text will determine the final resolved direction. - - The Pango rendering pipeline takes a string of -Unicode characters and converts it into glyphs. -The functions described in this section accomplish -various steps of this process. - -![](pipeline.png) - - - Frequently, you want to display some text to the user with attributes -applied to part of the text (for example, you might want bold or -italicized words). With the base Pango interfaces, you could create a -#PangoAttrList and apply it to the text; the problem is that you'd -need to apply attributes to some numeric range of characters, for -example "characters 12-17." This is broken from an internationalization -standpoint; once the text is translated, the word you wanted to -italicize could be in a different position. - -The solution is to include the text attributes in the string to be -translated. Pango provides this feature with a small markup language. -You can parse a marked-up string into the string text plus a -#PangoAttrList using either of pango_parse_markup() or -pango_markup_parser_new(). - -A simple example of a marked-up string might be: -|[ -<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>! -]| - -Pango uses #GMarkup to parse this language, which means that XML -features such as numeric character entities such as `&#169;` for -© can be used too. - -The root tag of a marked-up document is `<markup>`, but -pango_parse_markup() allows you to omit this tag, so you will most -likely never need to use it. The most general markup tag is `<span>`, -then there are some convenience tags. - -## Span attributes - -`<span>` has the following attributes: - -* `font_desc`: - A font description string, such as "Sans Italic 12". - See pango_font_description_from_string() for a description of the - format of the string representation . Note that any other span - attributes will override this description. So if you have "Sans Italic" - and also a `style="normal"` attribute, you will get Sans normal, - not italic. - -* `font_family`: - A font family name - -* `font_size`, `size`: - Font size in 1024ths of a point, or one of the absolute - sizes `xx-small`, `x-small`, `small`, `medium`, `large`, - `x-large`, `xx-large`, or one of the relative sizes `smaller` - or `larger`. If you want to specify a absolute size, it's usually - easier to take advantage of the ability to specify a partial - font description using `font`; you can use `font='12.5'` - rather than `size='12800'`. - -* `font_style`: - One of `normal`, `oblique`, `italic` - -* `font_weight`: - One of `ultralight`, `light`, `normal`, `bold`, - `ultrabold`, `heavy`, or a numeric weight - -* `font_variant`: - One of `normal` or `smallcaps` - -* `font_stretch`, `stretch`: - One of `ultracondensed`, `extracondensed`, `condensed`, - `semicondensed`, `normal`, `semiexpanded`, `expanded`, - `extraexpanded`, `ultraexpanded` - -* `font_features`: - A comma-separated list of OpenType font feature - settings, in the same syntax as accepted by CSS. E.g: - `font_features='dlig=1, -kern, afrc on'` - -* `foreground`, `fgcolor`: - An RGB color specification such as `#00FF00` or a color - name such as `red`. Since 1.38, an RGBA color specification such - as `#00FF007F` will be interpreted as specifying both a foreground - color and foreground alpha. - -* `background`, `bgcolor`: - An RGB color specification such as `#00FF00` or a color - name such as `red`. - Since 1.38, an RGBA color specification such as `#00FF007F` will - be interpreted as specifying both a background color and - background alpha. - -* `alpha`, `fgalpha`: - An alpha value for the foreground color, either a plain - integer between 1 and 65536 or a percentage value like `50%`. - -* `background_alpha`, `bgalpha`: - An alpha value for the background color, either a plain - integer between 1 and 65536 or a percentage value like `50%`. - -* `underline`: - One of `none`, `single`, `double`, `low`, `error`, - `single-line`, `double-line` or `error-line`. - -* `underline_color`: - The color of underlines; an RGB color - specification such as `#00FF00` or a color name such as `red` - -* `overline`: - One of `none` or `single` - -* `overline_color`: - The color of overlines; an RGB color - specification such as `#00FF00` or a color name such as `red` - -* `rise`: - Vertical displacement, in Pango units. Can be negative for - subscript, positive for superscript. - -* `strikethrough` - `true` or `false` whether to strike through the text - -* `strikethrough_color`: - The color of strikethrough lines; an RGB - color specification such as `#00FF00` or a color name such as `red` - -* `fallback`: - `true` or `false` whether to enable fallback. If - disabled, then characters will only be used from the closest - matching font on the system. No fallback will be done to other - fonts on the system that might contain the characters in the text. - Fallback is enabled by default. Most applications should not - disable fallback. - -* `allow_breaks`: - `true` or `false` whether to allow line breaks or not. If - not allowed, the range will be kept in a single run as far - as possible. Breaks are allowed by default. - -* `insert_hyphens`:` - `true` or `false` whether to insert hyphens when breaking - lines in the middle of a word. Hyphens are inserted by default. - -* `show`: - A value determining how invisible characters are treated. - Possible values are `spaces`, `line-breaks`, `ignorables` - or combinations, such as `spaces|line-breaks`. - -* `lang`: - A language code, indicating the text language - -* `letter_spacing`: - Inter-letter spacing in 1024ths of a point. - -* `gravity`: - One of `south`, `east`, `north`, `west`, `auto`. - -* `gravity_hint`: - One of `natural`, `strong`, `line`. - -## Convenience tags - -The following convenience tags are provided: - -* `<b>`: - Bold - -* `<big>`: - Makes font relatively larger, equivalent to `<span size="larger">` - -* `<i>`: - Italic - -* `<s>`: - Strikethrough - -* `<sub>`: - Subscript - -* `<sup>`: - Superscript - -* `<small>`: - Makes font relatively smaller, equivalent to `<span size="smaller">` - -* `<tt>`: - Monospace - -* `<u>`: - Underline - - After feeding a pango markup parser some data with g_markup_parse_context_parse(), -use this function to get the list of pango attributes and text out of the + Finishes parsing markup. + +After feeding a Pango markup parser some data with g_markup_parse_context_parse(), +use this function to get the list of attributes and text out of the markup. This function will not free @context, use g_markup_parse_context_free() to do so. @@ -12865,46 +12366,48 @@ to do so. - A valid parse context that was returned from pango_markup_parser_new() + A valid parse context that was returned from [func@markup_parser_new] - address of return location for a #PangoAttrList, or %NULL + address of return location for a `PangoAttrList` - address of return location for text with tags stripped, or %NULL + address of return location for text with tags stripped - address of return location for accelerator char, or %NULL + address of return location for accelerator char - Parses marked-up text (see -<link linkend="PangoMarkupFormat">markup format</link>) to create -a plain-text string and an attribute list. + Incrementally parses marked-up text to create a plain-text string +and an attribute list. + +See the [Pango Markup](pango_markup.html) docs for details about the +supported markup. If @accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, @accel_marker might be an ampersand or underscore. All characters marked as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute, and the first character so marked will be returned in @accel_char, -when calling finish(). Two @accel_marker characters following each -other produce a single literal @accel_marker character. +when calling [func@markup_parser_finish]. Two @accel_marker characters +following each other produce a single literal @accel_marker character. To feed markup to the parser, use g_markup_parse_context_parse() -on the returned #GMarkupParseContext. When done with feeding markup -to the parser, use pango_markup_parser_finish() to get the data out +on the returned `GMarkupParseContext`. When done with feeding markup +to the parser, use [func@markup_parser_finish] to get the data out of it, and then use g_markup_parse_context_free() to free it. -This function is designed for applications that read pango markup -from streams. To simply parse a string containing pango markup, -the simpler pango_parse_markup() API is recommended instead. +This function is designed for applications that read Pango markup +from streams. To simply parse a string containing Pango markup, +the [func@parse_markup] API is recommended instead. - a #GMarkupParseContext that should be + a `GMarkupParseContext` that should be destroyed with g_markup_parse_context_free(). @@ -12915,72 +12418,50 @@ destroyed with g_markup_parse_context_free(). - - Do not use. Does not do anything. - - - - - - a #PangoIncludedModule - - - - - - Functions and macros in this section were used to support -loading dynamic modules that add engines to Pango at run time. - -That is no longer the case, and these APIs should not be -used anymore. - - - The capital-letter macros defined here can be used to check the version of Pango -at compile-time, and to <firstterm>encode</firstterm> Pango versions into integers. - -The functions can be used to check the version of the linked Pango library at run-time. - Parses an enum type and stores the result in @value. -If @str does not match the nick name of any of the possible values for the -enum and is not an integer, %FALSE is returned, a warning is issued -if @warn is %TRUE, and a -string representing the list of possible values is stored in -@possible_values. The list is slash-separated, eg. -"none/start/middle/end". If failed and @possible_values is not %NULL, -returned string should be freed using g_free(). +If @str does not match the nick name of any of the possible values +for the enum and is not an integer, %FALSE is returned, a warning +is issued if @warn is %TRUE, and a string representing the list of +possible values is stored in @possible_values. The list is +slash-separated, eg. "none/start/middle/end". + +If failed and @possible_values is not %NULL, returned string should +be freed using g_free(). - %TRUE if @str was successfully parsed. + %TRUE if @str was successfully parsed - enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE. + enum type to parse, eg. %PANGO_TYPE_ELLIPSIZE_MODE - string to parse. May be %NULL. + string to parse - integer to store the result in, or %NULL. + integer to store the result in - if %TRUE, issue a g_warning() on bad input. + if %TRUE, issue a g_warning() on bad input - place to store list of possible values on failure, or %NULL. + place to store list of possible + values on failure - Parses marked-up text (see -<link linkend="PangoMarkupFormat">markup format</link>) to create -a plain-text string and an attribute list. + Parses marked-up text to create a plain-text string and an attribute list. + +See the [Pango Markup](pango_markup.html) docs for details about the +supported markup. If @accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, @accel_marker @@ -12990,7 +12471,7 @@ and the first character so marked will be returned in @accel_char. Two @accel_marker characters following each other produce a single literal @accel_marker character. -To parse a stream of pango markup incrementally, use pango_markup_parser_new(). +To parse a stream of pango markup incrementally, use [func@markup_parser_new]. If any error happens, none of the output arguments are touched except for @error. @@ -13000,7 +12481,7 @@ for @error. - markup to parse (see <link linkend="PangoMarkupFormat">markup format</link>) + markup to parse (see the Pango Markup docs) @@ -13012,21 +12493,23 @@ for @error. - address of return location for a #PangoAttrList, or %NULL + address of return location for a `PangoAttrList` - address of return location for text with tags stripped, or %NULL + address of return location for text with tags stripped - address of return location for accelerator char, or %NULL + address of return location for accelerator char - Parses a font stretch. The allowed values are + Parses a font stretch. + +The allowed values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" and "ultra_expanded". Case variations are @@ -13041,8 +12524,7 @@ ignored and the '_' characters may be omitted. - a #PangoStretch to store the - result in. + a `PangoStretch` to store the result in. @@ -13052,8 +12534,10 @@ ignored and the '_' characters may be omitted. - Parses a font style. The allowed values are "normal", -"italic" and "oblique", case variations being + Parses a font style. + +The allowed values are "normal", "italic" and "oblique", case +variations being ignored. %TRUE if @str was successfully parsed. @@ -13065,8 +12549,7 @@ ignored. - a #PangoStyle to store the result - in. + a `PangoStyle` to store the result in. @@ -13076,9 +12559,10 @@ ignored. - Parses a font variant. The allowed values are "normal" -and "smallcaps" or "small_caps", case variations being -ignored. + Parses a font variant. + +The allowed values are "normal" and "smallcaps" or "small_caps", +case variations being ignored. %TRUE if @str was successfully parsed. @@ -13089,8 +12573,7 @@ ignored. - a #PangoVariant to store the - result in. + a `PangoVariant` to store the result in. @@ -13100,7 +12583,9 @@ ignored. - Parses a font weight. The allowed values are "heavy", + Parses a font weight. + +The allowed values are "heavy", "ultrabold", "bold", "normal", "light", "ultraleight" and integers. Case variations are ignored. @@ -13113,8 +12598,7 @@ and integers. Case variations are ignored. - a #PangoWeight to store the result - in. + a `PangoWeight` to store the result in. @@ -13124,10 +12608,10 @@ and integers. Case variations are ignored. - Quantizes the thickness and position of a line, typically an -underline or strikethrough, to whole device pixels, that is integer -multiples of %PANGO_SCALE. The purpose of this function is to avoid -such lines looking blurry. + Quantizes the thickness and position of a line to whole device pixels. + +This is typically used for underline or strikethrough. The purpose of +this function is to avoid such lines looking blurry. Care is taken to make sure @thickness is at least one pixel when this function returns, but returned @position may become zero as a result @@ -13147,17 +12631,18 @@ of rounding. - Reads an entire line from a file into a buffer. Lines may -be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter + Reads an entire line from a file into a buffer. + +Lines may be delimited with '\n', '\r', '\n\r', or '\r\n'. The delimiter is not written into the buffer. Text after a '#' character is treated as a comment and skipped. '\' can be used to escape a # character. '\' proceeding a line delimiter combines adjacent lines. A '\' proceeding any other character is ignored and written into the output buffer unmodified. - 0 if the stream was already at an %EOF character, otherwise - the number of lines read (this is useful for maintaining - a line number counter which doesn't combine lines with '\') + 0 if the stream was already at an %EOF character, + otherwise the number of lines read (this is useful for maintaining + a line number counter which doesn't combine lines with '\') @@ -13166,29 +12651,31 @@ unmodified. - #GString buffer into which to write the result + `GString` buffer into which to write the result - From a list of items in logical order and the associated -directional levels, produce a list in visual order. -The original list is unmodified. - - a #GList - of #PangoItem structures in visual order. + Reorder items from logical order to visual order. + +The visual order is determined from the associated directional +levels of the items. The original list is unmodified. (Please open a bug if you use this function. It is not a particularly convenient interface, and the code is duplicated elsewhere in Pango for that reason.) + + a `GList` + of `PangoItem` structures in visual order. - a #GList of #PangoItem in logical order. + a `GList` of `PangoItem` + in logical order. @@ -13197,9 +12684,10 @@ The original list is unmodified. Scans an integer. + Leading white space is skipped. - %FALSE if a parse error occurred. + %FALSE if a parse error occurred @@ -13214,12 +12702,13 @@ Leading white space is skipped. - Scans a string into a #GString buffer. The string may either -be a sequence of non-white-space characters, or a quoted -string with '"'. Instead a quoted string, '\"' represents + Scans a string into a `GString` buffer. + +The string may either be a sequence of non-white-space characters, +or a quoted string with '"'. Instead a quoted string, '\"' represents a literal quote. Leading white space outside of quotes is skipped. - %FALSE if a parse error occurred. + %FALSE if a parse error occurred @@ -13228,17 +12717,18 @@ a literal quote. Leading white space outside of quotes is skipped. - a #GString into which to write the result + a `GString` into which to write the result - Scans a word into a #GString buffer. A word consists -of [A-Za-z_] followed by zero or more [A-Za-z_0-9] -Leading white space is skipped. + Scans a word into a `GString` buffer. + +A word consists of [A-Za-z_] followed by zero or more +[A-Za-z_0-9]. Leading white space is skipped. - %FALSE if a parse error occurred. + %FALSE if a parse error occurred @@ -13247,24 +12737,25 @@ Leading white space is skipped. - a #GString into which to write the result + a `GString` into which to write the result - Looks up the script for a particular character (as defined by -Unicode Standard Annex \#24). No check is made for @ch being a -valid Unicode character; if you pass in invalid character, the -result is undefined. + Looks up the script for a particular character. + +The script of a character is defined by Unicode Standard Annex \#24. +No check is made for @ch being a valid Unicode character; if you pass +in invalid character, the result is undefined. Note that while the return type of this function is declared -as PangoScript, as of Pango 1.18, this function simply returns +as `PangoScript`, as of Pango 1.18, this function simply returns the return value of g_unichar_get_script(). Callers must be prepared to handle unknown values. Use g_unichar_get_script() - the #PangoScript for the character. + the `PangoScript` for the character. @@ -13275,62 +12766,62 @@ prepared to handle unknown values. - Given a script, finds a language tag that is reasonably -representative of that script. This will usually be the -most widely spoken or used language written in that script: -for instance, the sample language for %PANGO_SCRIPT_CYRILLIC -is <literal>ru</literal> (Russian), the sample language -for %PANGO_SCRIPT_ARABIC is <literal>ar</literal>. + Finds a language tag that is reasonably representative of @script. -For some -scripts, no sample language will be returned because there -is no language that is sufficiently representative. The best -example of this is %PANGO_SCRIPT_HAN, where various different +The language will usually be the most widely spoken or used language +written in that script: for instance, the sample language for +%PANGO_SCRIPT_CYRILLIC is ru (Russian), the sample language for +%PANGO_SCRIPT_ARABIC is ar. + +For some scripts, no sample language will be returned because +there is no language that is sufficiently representative. The +best example of this is %PANGO_SCRIPT_HAN, where various different variants of written Chinese, Japanese, and Korean all use significantly different sets of Han characters and forms of shared characters. No sample language can be provided for many historical scripts as well. As of 1.18, this function checks the environment variables -PANGO_LANGUAGE and LANGUAGE (checked in that order) first. +`PANGO_LANGUAGE` and `LANGUAGE` (checked in that order) first. If one of them is set, it is parsed as a list of language tags -separated by colons or other separators. This function +separated by colons or other separators. This function will return the first language in the parsed list that Pango -believes may use @script for writing. This last predicate -is tested using pango_language_includes_script(). This can +believes may use @script for writing. This last predicate +is tested using [method@Pango.Language.includes_script]. This can be used to control Pango's font selection for non-primary -languages. For example, a PANGO_LANGUAGE enviroment variable +languages. For example, a `PANGO_LANGUAGE` enviroment variable set to "en:fa" makes Pango choose fonts suitable for Persian (fa) instead of Arabic (ar) when a segment of Arabic text is found -in an otherwise non-Arabic text. The same trick can be used to +in an otherwise non-Arabic text. The same trick can be used to choose a default language for %PANGO_SCRIPT_HAN when setting context language is not feasible. - a #PangoLanguage that is representative -of the script, or %NULL if no such language exists. + a `PangoLanguage` that is representative + of the script - a #PangoScript + a `PangoScript` - - The functions in this section are used to identify the writing -system, or <firstterm>script</firstterm> of individual characters -and of ranges within a larger text string. - - Given a segment of text and the corresponding -#PangoAnalysis structure returned from pango_itemize(), -convert the characters into glyphs. You may also pass -in only a substring of the item from pango_itemize(). + Convert the characters in @text into glyphs. -It is recommended that you use pango_shape_full() instead, since +Given a segment of text and the corresponding `PangoAnalysis` structure +returned from [func@itemize], convert the characters into glyphs. You +may also pass in only a substring of the item from [func@itemize]. + +It is recommended that you use [func@shape_full] instead, since that API allows for shaping interaction happening across text item -boundaries. +boundaries. + +Note that the extra attributes in the @analyis that is returned from +[func@itemize] have indices that are relative to the entire paragraph, +so you need to subtract the item offset from their indices before +calling [func@shape]. @@ -13344,7 +12835,7 @@ boundaries. - #PangoAnalysis structure from pango_itemize() + `PangoAnalysis` structure from [func@itemize] @@ -13354,16 +12845,22 @@ boundaries. - Given a segment of text and the corresponding -#PangoAnalysis structure returned from pango_itemize(), -convert the characters into glyphs. You may also pass -in only a substring of the item from pango_itemize(). + Convert the characters in @text into glyphs. -This is similar to pango_shape(), except it also can optionally take +Given a segment of text and the corresponding `PangoAnalysis` structure +returned from [func@itemize], convert the characters into glyphs. You may +also pass in only a substring of the item from [func@itemize]. + +This is similar to [func@shape], except it also can optionally take the full paragraph text as input, which will then be used to perform -certain cross-item shaping interactions. If you have access to the broader +certain cross-item shaping interactions. If you have access to the broader text of which @item_text is part of, provide the broader text as -@paragraph_text. If @paragraph_text is %NULL, item text is used instead. +@paragraph_text. If @paragraph_text is %NULL, item text is used instead. + +Note that the extra attributes in the @analyis that is returned from +[func@itemize] have indices that are relative to the entire paragraph, +so you do not pass the full paragraph text as @paragraph_text, you need +to subtract the item offset from their indices before calling [func@shape_full]. @@ -13385,7 +12882,7 @@ text of which @item_text is part of, provide the broader text as - #PangoAnalysis structure from pango_itemize(). + `PangoAnalysis` structure from [func@itemize]. @@ -13395,13 +12892,20 @@ text of which @item_text is part of, provide the broader text as - Given a segment of text and the corresponding -#PangoAnalysis structure returned from pango_itemize(), -convert the characters into glyphs. You may also pass -in only a substring of the item from pango_itemize(). + Convert the characters in @text into glyphs. -This is similar to pango_shape_full(), except it also takes -flags that can influence the shaping process. +Given a segment of text and the corresponding `PangoAnalysis` structure +returned from [func@itemize], convert the characters into glyphs. You may +also pass in only a substring of the item from [func@itemize]. + +This is similar to [func@shape_full], except it also takes flags that can +influence the shaping process. + +Note that the extra attributes in the @analyis that is returned from +[func@itemize] have indices that are relative to the entire paragraph, +so you do not pass the full paragraph text as @paragraph_text, you need +to subtract the item offset from their indices before calling +[func@shape_with_flags]. @@ -13426,7 +12930,7 @@ flags that can influence the shaping process. - #PangoAnalysis structure from pango_itemize() + `PangoAnalysis` structure from [func@itemize] @@ -13443,7 +12947,7 @@ flags that can influence the shaping process. Skips 0 or more characters of white space. %FALSE if skipping the white space leaves -the position at a '\0' character. + the position at a '\0' character. @@ -13458,7 +12962,7 @@ the position at a '\0' character. white space and substituting ~/ with $HOME/. a list of -strings to be freed with g_strfreev() + strings to be freed with g_strfreev() @@ -13470,14 +12974,12 @@ strings to be freed with g_strfreev() - - Functions in this section are used to deal with #PangoTabArray objects -that can be used to set tab stop positions in a #PangoLayout. - - Apply language-specific tailoring to the breaks in -@log_attrs, which are assumed to have been produced -by pango_default_break(). + Apply language-specific tailoring to the breaks +in @log_attrs. + +The line breaks are assumed to have been produced +by [func@Pango.default_break]. If @offset is not -1, it is used to apply attributes from @analysis that are relevant to line breaking. @@ -13494,16 +12996,16 @@ from @analysis that are relevant to line breaking. - #PangoAnalysis structure from pango_itemize() for @text + `PangoAnalysis` for @text Byte offset of @text from the beginning of the - paragraph, or -1 to ignore attributes from @analysis + paragraph, or -1 to ignore attributes from @analysis - array with one #PangoLogAttr + array with one `PangoLogAttr` per character in @text, plus one extra, to be filled in @@ -13515,13 +13017,6 @@ from @analysis that are relevant to line breaking. - - Attributed text is used in a number of places in Pango. It -is used as the input to the itemization process and also when -creating a #PangoLayout. The data types and functions in -this section are used to represent and manipulate sets -of attributes applied to a portion of text. - Trims leading and trailing whitespace from a string. @@ -13536,14 +13031,15 @@ of attributes applied to a portion of text. - Determines the inherent direction of a character; either -%PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL, or -%PANGO_DIRECTION_NEUTRAL. + Determines the inherent direction of a character. + +The inherent direction is either %PANGO_DIRECTION_LTR, %PANGO_DIRECTION_RTL, +or %PANGO_DIRECTION_NEUTRAL. This function is useful to categorize characters into left-to-right -letters, right-to-left letters, and everything else. If full -Unicode bidirectional type of a character is needed, -pango_bidi_type_for_unichar() can be used instead. +letters, right-to-left letters, and everything else. If full Unicode +bidirectional type of a character is needed, +[func@Pango.BidiType.for_unichar] can be used instead. the direction of the character. @@ -13556,8 +13052,10 @@ pango_bidi_type_for_unichar() can be used instead. - Converts a floating-point number to Pango units: multiplies -it by %PANGO_SCALE and rounds to nearest integer. + Converts a floating-point number to Pango units. + +The conversion is done by multiplying @d by %PANGO_SCALE and +rounding the result to nearest integer. the value in Pango units. @@ -13570,8 +13068,9 @@ it by %PANGO_SCALE and rounds to nearest integer. - Converts a number in Pango units to floating-point: divides -it by %PANGO_SCALE. + Converts a number in Pango units to floating-point. + +The conversion is done by dividing @i by %PANGO_SCALE. the double value. @@ -13583,30 +13082,26 @@ it by %PANGO_SCALE. - - The functions and utilities in this section are mostly used from Pango -backends and modules, but may be useful for other purposes too. - - This is similar to the macro %PANGO_VERSION except that -it returns the encoded version of Pango available at run-time, -as opposed to the version available at compile-time. + Returns the encoded version of Pango available at run-time. -A version number can be encoded into an integer using -PANGO_VERSION_ENCODE(). +This is similar to the macro %PANGO_VERSION except that the macro +returns the encoded version available at compile-time. A version +number can be encoded into an integer using PANGO_VERSION_ENCODE(). - The encoded version of Pango library - available at run time. + The encoded version of Pango library available at run time. Checks that the Pango library in use is compatible with the -given version. Generally you would pass in the constants -%PANGO_VERSION_MAJOR, %PANGO_VERSION_MINOR, %PANGO_VERSION_MICRO -as the three arguments to this function; that produces -a check that the library in use at run-time is compatible with -the version of Pango the application or module was compiled against. +given version. + +Generally you would pass in the constants %PANGO_VERSION_MAJOR, +%PANGO_VERSION_MINOR, %PANGO_VERSION_MICRO as the three arguments +to this function; that produces a check that the library in use at +run-time is compatible with the version of Pango the application or +module was compiled against. Compatibility is defined by two things: first the version of the running library is newer than the version @@ -13625,75 +13120,30 @@ For compile-time version checking use PANGO_VERSION_CHECK(). - the required major version. + the required major version - the required minor version. + the required minor version - the required major version. + the required major version - This is similar to the macro %PANGO_VERSION_STRING except that -it returns the version of Pango available at run-time, as opposed to -the version available at compile-time. + Returns the version of Pango available at run-time. + +This is similar to the macro %PANGO_VERSION_STRING except that the +macro returns the version available at compile-time. - A string containing the version of Pango library - available at run time. - The returned string is owned by Pango and should not be modified - or freed. + A string containing the version of Pango library available + at run time. The returned string is owned by Pango and should not + be modified or freed. - - Since 1.16, Pango is able to correctly lay vertical text out. In fact, it can -set layouts of mixed vertical and non-vertical text. This section describes -the types used for setting vertical text parameters. - -The way this is implemented is through the concept of -<firstterm>gravity</firstterm>. Gravity of normal Latin text is south. A -gravity value of east means that glyphs will be rotated ninety degrees -counterclockwise. So, to render vertical text one needs to set the gravity -and rotate the layout using the matrix machinery already in place. This has -the huge advantage that most algorithms working on a #PangoLayout do not need -any change as the assumption that lines run in the X direction and stack in -the Y direction holds even for vertical text layouts. - -Applications should only need to set base gravity on #PangoContext in use, and -let Pango decide the gravity assigned to each run of text. This automatically -handles text with mixed scripts. A very common use is to set the context base -gravity to auto using pango_context_set_base_gravity() -and rotate the layout normally. Pango will make sure that -Asian languages take the right form, while other scripts are rotated normally. - -The correct way to set gravity on a layout is to set it on the context -associated with it using pango_context_set_base_gravity(). The context -of a layout can be accessed using pango_layout_get_context(). The currently -set base gravity of the context can be accessed using -pango_context_get_base_gravity() and the <firstterm>resolved</firstterm> -gravity of it using pango_context_get_gravity(). The resolved gravity is -the same as the base gravity for the most part, except that if the base -gravity is set to %PANGO_GRAVITY_AUTO, the resolved gravity will depend -on the current matrix set on context, and is derived using -pango_gravity_get_for_matrix(). - -The next thing an application may want to set on the context is the -<firstterm>gravity hint</firstterm>. A #PangoGravityHint instructs how -different scripts should react to the set base gravity. - -Font descriptions have a gravity property too, that can be set using -pango_font_description_set_gravity() and accessed using -pango_font_description_get_gravity(). However, those are rarely useful -from application code and are mainly used by #PangoLayout internally. - -Last but not least, one can create #PangoAttribute<!---->s for gravity -and gravity hint using pango_attr_gravity_new() and -pango_attr_gravity_hint_new(). - diff --git a/PangoCairo-1.0.gir b/PangoCairo-1.0.gir index 9250503..7ef90a9 100644 --- a/PangoCairo-1.0.gir +++ b/PangoCairo-1.0.gir @@ -22,90 +22,95 @@ and/or use gtk-doc annotations. --> - #PangoCairoFont is an interface exported by fonts for -use with Cairo. The actual type of the font will depend -on the particular font technology Cairo was compiled to use. + `PangoCairoFont` is an interface exported by fonts for +use with Cairo. + +The actual type of the font will depend on the particular +font technology Cairo was compiled to use. - Gets the #cairo_scaled_font_t used by @font. + Gets the `cairo_scaled_font_t` used by @font. The scaled font can be referenced and kept using cairo_scaled_font_reference(). - the #cairo_scaled_font_t used by @font, - or %NULL if @font is %NULL. + the `cairo_scaled_font_t` + used by @font - - a #PangoFont from a #PangoCairoFontMap + + a `PangoFont` from a `PangoCairoFontMap` - #PangoCairoFontMap is an interface exported by font maps for -use with Cairo. The actual type of the font map will depend -on the particular font technology Cairo was compiled to use. + `PangoCairoFontMap` is an interface exported by font maps for +use with Cairo. + +The actual type of the font map will depend on the particular +font technology Cairo was compiled to use. - Gets a default #PangoCairoFontMap to use with Cairo. + Gets a default `PangoCairoFontMap` to use with Cairo. -Note that the type of the returned object will depend -on the particular font backend Cairo was compiled to use; -You generally should only use the #PangoFontMap and -#PangoCairoFontMap interfaces on the returned object. +Note that the type of the returned object will depend on the +particular font backend Cairo was compiled to use; you generally +should only use the `PangoFontMap` and `PangoCairoFontMap` +interfaces on the returned object. The default Cairo fontmap can be changed by using -pango_cairo_font_map_set_default(). This can be used to -change the Cairo font backend that the default fontmap -uses for example. +[method@PangoCairo.FontMap.set_default]. This can be used to +change the Cairo font backend that the default fontmap uses +for example. Note that since Pango 1.32.6, the default fontmap is per-thread. -Each thread gets its own default fontmap. In this way, -PangoCairo can be used safely from multiple threads. +Each thread gets its own default fontmap. In this way, PangoCairo +can be used safely from multiple threads. the default PangoCairo fontmap - for the current thread. This object is owned by Pango and must not be freed. + for the current thread. This object is owned by Pango and must + not be freed. - Creates a new #PangoCairoFontMap object; a fontmap is used -to cache information about available fonts, and holds -certain global parameters such as the resolution. -In most cases, you can use pango_cairo_font_map_get_default() + Creates a new `PangoCairoFontMap` object. + +A fontmap is used to cache information about available fonts, +and holds certain global parameters such as the resolution. +In most cases, you can use `func@PangoCairo.font_map_get_default] instead. Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; -You generally should only use the #PangoFontMap and -#PangoCairoFontMap interfaces on the returned object. +You generally should only use the `PangoFontMap` and +`PangoCairoFontMap` interfaces on the returned object. You can override the type of backend returned by using an -environment variable %PANGOCAIRO_BACKEND. Supported types, +environment variable %PANGOCAIRO_BACKEND. Supported types, based on your build, are fc (fontconfig), win32, and coretext. If requested type is not available, NULL is returned. Ie. this is only useful for testing, when at least two backends are compiled in. - the newly allocated #PangoFontMap, - which should be freed with g_object_unref(). + the newly allocated `PangoFontMap`, + which should be freed with g_object_unref(). - Creates a new #PangoCairoFontMap object of the type suitable + Creates a new `PangoCairoFontMap` object of the type suitable to be used with cairo font backend of type @fonttype. -In most cases one should simply use @pango_cairo_font_map_new(), -or in fact in most of those cases, just use -@pango_cairo_font_map_get_default(). +In most cases one should simply use [func@PangoCairo.FontMap.new], or +in fact in most of those cases, just use [func@PangoCairo.FontMap.get_default]. the newly allocated - #PangoFontMap of suitable type which should be freed - with g_object_unref(), or %NULL if the requested - cairo font backend is not supported / compiled in. + `PangoFontMap` of suitable type which should be freed with + g_object_unref(), or %NULL if the requested cairo font backend + is not supported / compiled in. @@ -116,7 +121,7 @@ or in fact in most of those cases, just use - Create a #PangoContext for the given fontmap. + Create a `PangoContext` for the given fontmap. Use pango_font_map_create_context() instead. the newly created context; free with g_object_unref(). @@ -124,7 +129,7 @@ or in fact in most of those cases, just use - a #PangoCairoFontMap + a `PangoCairoFontMap` @@ -132,58 +137,62 @@ or in fact in most of those cases, just use Gets the type of Cairo font backend that @fontmap uses. - the #cairo_font_type_t cairo font backend type + the `cairo_font_type_t` cairo font backend type - a #PangoCairoFontMap + a `PangoCairoFontMap` - Gets the resolution for the fontmap. See pango_cairo_font_map_set_resolution() + Gets the resolution for the fontmap. + +See [method@PangoCairo.FontMap.set_resolution]. the resolution in "dots per inch" - a #PangoCairoFontMap + a `PangoCairoFontMap` - Sets a default #PangoCairoFontMap to use with Cairo. + Sets a default `PangoCairoFontMap` to use with Cairo. This can be used to change the Cairo font backend that the -default fontmap uses for example. The old default font map +default fontmap uses for example. The old default font map is unreffed and the new font map referenced. Note that since Pango 1.32.6, the default fontmap is per-thread. This function only changes the default fontmap for -the current thread. Default fontmaps of existing threads +the current thread. Default fontmaps of existing threads are not changed. Default fontmaps of any new threads will -still be created using pango_cairo_font_map_new(). +still be created using [func@PangoCairo.FontMap.new]. A value of %NULL for @fontmap will cause the current default -font map to be released and a new default font -map to be created on demand, using pango_cairo_font_map_new(). +font map to be released and a new default font map to be created +on demand, using [func@PangoCairo.FontMap.new]. - The new default font map, or %NULL + The new default font map - Sets the resolution for the fontmap. This is a scale factor between -points specified in a #PangoFontDescription and Cairo units. The + Sets the resolution for the fontmap. + +This is a scale factor between +points specified in a `PangoFontDescription` and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10 * 96. / 72. = 13.3). @@ -191,7 +200,7 @@ units high. (10 * 96. / 72. = 13.3). - a #PangoCairoFontMap + a `PangoCairoFontMap` @@ -245,8 +254,10 @@ pango_cairo_layout_line_path() rendering functions. Retrieves any font rendering options previously set with -pango_cairo_context_set_font_options(). This function does not report options -that are derived from the target surface by pango_cairo_update_context() +[func@PangoCairo.context_set_font_options]. + +This function does not report options that are derived from +the target surface by [func@update_context]. the font options previously set on the context, or %NULL if no options have been set. This value is @@ -255,80 +266,85 @@ that are derived from the target surface by pango_cairo_update_context() - a #PangoContext, from a pangocairo font map + a `PangoContext`, from a pangocairo font map - Gets the resolution for the context. See pango_cairo_context_set_resolution() + Gets the resolution for the context. + +See [func@PangoCairo.context_set_resolution] the resolution in "dots per inch". A negative value will - be returned if no resolution has previously been set. + be returned if no resolution has previously been set. - a #PangoContext, from a pangocairo font map + a `PangoContext`, from a pangocairo font map Sets callback function for context to use for rendering attributes -of type %PANGO_ATTR_SHAPE. See #PangoCairoShapeRendererFunc for -details. +of type %PANGO_ATTR_SHAPE. + +See `PangoCairoShapeRendererFunc` for details. Retrieves callback function and associated user data for rendering attributes of type %PANGO_ATTR_SHAPE as set by -pango_cairo_context_set_shape_renderer(), if any. +[func@PangoCairo.context_set_shape_renderer], if any. - the shape rendering callback previously - set on the context, or %NULL if no shape rendering callback have - been set. + the shape rendering callback + previously set on the context, or %NULL if no shape rendering callback + have been set. - a #PangoContext, from a pangocairo font map + a `PangoContext`, from a pangocairo font map - Pointer to #gpointer to return user data + Pointer to `gpointer` to return user data Sets the font options used when rendering text with this context. -These options override any options that pango_cairo_update_context() + +These options override any options that [func@update_context] derives from the target surface. - a #PangoContext, from a pangocairo font map + a `PangoContext`, from a pangocairo font map - a #cairo_font_options_t, or %NULL to unset - any previously set options. A copy is made. + a `cairo_font_options_t`, or %NULL to unset + any previously set options. A copy is made. - Sets the resolution for the context. This is a scale factor between -points specified in a #PangoFontDescription and Cairo units. The -default value is 96, meaning that a 10 point font will be 13 -units high. (10 * 96. / 72. = 13.3). + Sets the resolution for the context. + +This is a scale factor between points specified in a `PangoFontDescription` +and Cairo units. The default value is 96, meaning that a 10 point font will +be 13 units high. (10 * 96. / 72. = 13.3). - a #PangoContext, from a pangocairo font map + a `PangoContext`, from a pangocairo font map @@ -341,44 +357,46 @@ units high. (10 * 96. / 72. = 13.3). Sets callback function for context to use for rendering attributes -of type %PANGO_ATTR_SHAPE. See #PangoCairoShapeRendererFunc for -details. +of type %PANGO_ATTR_SHAPE. + +See `PangoCairoShapeRendererFunc` for details. - a #PangoContext, from a pangocairo font map + a `PangoContext`, from a pangocairo font map Callback function for rendering attributes of - type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering. + type %PANGO_ATTR_SHAPE, or %NULL to disable shape rendering. User data that will be passed to @func. - + Callback that will be called when the - context is freed to release @data, or %NULL. + context is freed to release @data Creates a context object set up to match the current transformation -and target surface of the Cairo context. This context can then be -used to create a layout using pango_layout_new(). +and target surface of the Cairo context. + +This context can then be +used to create a layout using [ctor@Pango.Layout.new]. This function is a convenience function that creates a context using -the default font map, then updates it to @cr. If you just need to -create a layout for use with @cr and do not need to access #PangoContext -directly, you can use pango_cairo_create_layout() instead. +the default font map, then updates it to @cr. If you just need to +create a layout for use with @cr and do not need to access `PangoContext` +directly, you can use [func@create_layout] instead. - the newly created #PangoContext. Free with - g_object_unref(). + the newly created `PangoContext` @@ -390,19 +408,19 @@ directly, you can use pango_cairo_create_layout() instead. Creates a layout object set up to match the current transformation -and target surface of the Cairo context. This layout can then be -used for text measurement with functions like -pango_layout_get_size() or drawing with functions like -pango_cairo_show_layout(). If you change the transformation -or target surface for @cr, you need to call pango_cairo_update_layout() +and target surface of the Cairo context. + +This layout can then be used for text measurement with functions +like [method@Pango.Layout.get_size] or drawing with functions like +[func@show_layout]. If you change the transformation or target +surface for @cr, you need to call [func@update_layout]. This function is the most convenient way to use Cairo with Pango, however it is slightly inefficient since it creates a separate -#PangoContext object for each layout. This might matter in an +`PangoContext` object for each layout. This might matter in an application that was laying out large amounts of text. - the newly created #PangoLayout. Free with - g_object_unref(). + the newly created `PangoLayout` @@ -415,9 +433,10 @@ application that was laying out large amounts of text. Add a squiggly line to the current path in the specified cairo context that approximately covers the given rectangle in the style of an underline used -to indicate a spelling error. (The width of the underline is rounded to an -integer number of up/down segments and the resulting rectangle is centered -in the original rectangle) +to indicate a spelling error. + +The width of the underline is rounded to an integer number of up/down +segments and the resulting rectangle is centered in the original rectangle. @@ -445,63 +464,64 @@ in the original rectangle) - Gets a default #PangoCairoFontMap to use with Cairo. + Gets a default `PangoCairoFontMap` to use with Cairo. -Note that the type of the returned object will depend -on the particular font backend Cairo was compiled to use; -You generally should only use the #PangoFontMap and -#PangoCairoFontMap interfaces on the returned object. +Note that the type of the returned object will depend on the +particular font backend Cairo was compiled to use; you generally +should only use the `PangoFontMap` and `PangoCairoFontMap` +interfaces on the returned object. The default Cairo fontmap can be changed by using -pango_cairo_font_map_set_default(). This can be used to -change the Cairo font backend that the default fontmap -uses for example. +[method@PangoCairo.FontMap.set_default]. This can be used to +change the Cairo font backend that the default fontmap uses +for example. Note that since Pango 1.32.6, the default fontmap is per-thread. -Each thread gets its own default fontmap. In this way, -PangoCairo can be used safely from multiple threads. +Each thread gets its own default fontmap. In this way, PangoCairo +can be used safely from multiple threads. the default PangoCairo fontmap - for the current thread. This object is owned by Pango and must not be freed. + for the current thread. This object is owned by Pango and must + not be freed. - Creates a new #PangoCairoFontMap object; a fontmap is used -to cache information about available fonts, and holds -certain global parameters such as the resolution. -In most cases, you can use pango_cairo_font_map_get_default() + Creates a new `PangoCairoFontMap` object. + +A fontmap is used to cache information about available fonts, +and holds certain global parameters such as the resolution. +In most cases, you can use `func@PangoCairo.font_map_get_default] instead. Note that the type of the returned object will depend on the particular font backend Cairo was compiled to use; -You generally should only use the #PangoFontMap and -#PangoCairoFontMap interfaces on the returned object. +You generally should only use the `PangoFontMap` and +`PangoCairoFontMap` interfaces on the returned object. You can override the type of backend returned by using an -environment variable %PANGOCAIRO_BACKEND. Supported types, +environment variable %PANGOCAIRO_BACKEND. Supported types, based on your build, are fc (fontconfig), win32, and coretext. If requested type is not available, NULL is returned. Ie. this is only useful for testing, when at least two backends are compiled in. - the newly allocated #PangoFontMap, - which should be freed with g_object_unref(). + the newly allocated `PangoFontMap`, + which should be freed with g_object_unref(). - Creates a new #PangoCairoFontMap object of the type suitable + Creates a new `PangoCairoFontMap` object of the type suitable to be used with cairo font backend of type @fonttype. -In most cases one should simply use @pango_cairo_font_map_new(), -or in fact in most of those cases, just use -@pango_cairo_font_map_get_default(). +In most cases one should simply use [func@PangoCairo.FontMap.new], or +in fact in most of those cases, just use [func@PangoCairo.FontMap.get_default]. the newly allocated - #PangoFontMap of suitable type which should be freed - with g_object_unref(), or %NULL if the requested - cairo font backend is not supported / compiled in. + `PangoFontMap` of suitable type which should be freed with + g_object_unref(), or %NULL if the requested cairo font backend + is not supported / compiled in. @@ -513,7 +533,9 @@ or in fact in most of those cases, just use Adds the glyphs in @glyphs to the current path in the specified -cairo context. The origin of the glyphs (the left edge of the baseline) +cairo context. + +The origin of the glyphs (the left edge of the baseline) will be at the current point of the cairo context. @@ -524,19 +546,21 @@ will be at the current point of the cairo context. - a #PangoFont from a #PangoCairoFontMap + a `PangoFont` from a `PangoCairoFontMap` - a #PangoGlyphString + a `PangoGlyphString` - Adds the text in #PangoLayoutLine to the current path in the -specified cairo context. The origin of the glyphs (the left edge -of the line) will be at the current point of the cairo context. + Adds the text in `PangoLayoutLine` to the current path in the +specified cairo context. + +The origin of the glyphs (the left edge of the line) will be +at the current point of the cairo context. @@ -546,15 +570,17 @@ of the line) will be at the current point of the cairo context. - a #PangoLayoutLine + a `PangoLayoutLine` - Adds the text in a #PangoLayout to the current path in the -specified cairo context. The top-left corner of the #PangoLayout -will be at the current point of the cairo context. + Adds the text in a `PangoLayout` to the current path in the +specified cairo context. + +The top-left corner of the `PangoLayout` will be at the +current point of the cairo context. @@ -569,141 +595,14 @@ will be at the current point of the cairo context. - - The <ulink url="http://cairographics.org">Cairo library</ulink> is a -vector graphics library with a powerful rendering model. It has such -features as anti-aliased primitives, alpha-compositing, and -gradients. Multiple backends for Cairo are available, to allow -rendering to images, to PDF files, and to the screen on X and on other -windowing systems. The functions in this section allow using Pango -to render to Cairo surfaces. - -Using Pango with Cairo is straightforward. A #PangoContext created -with pango_cairo_font_map_create_context() can be used on any -Cairo context (cairo_t), but needs to be updated to match the -current transformation matrix and target surface of the Cairo context -using pango_cairo_update_context(). The convenience functions -pango_cairo_create_layout() and pango_cairo_update_layout() handle -the common case where the program doesn't need to manipulate the -properties of the #PangoContext. - -When you get the metrics of a layout or of a piece of a layout using -functions such as pango_layout_get_extents(), the reported metrics -are in user-space coordinates. If a piece of text is 10 units long, -and you call cairo_scale (cr, 2.0), it still is more-or-less 10 -units long. However, the results will be affected by hinting -(that is, the process of adjusting the text to look good on the -pixel grid), so you shouldn't assume they are completely independent -of the current transformation matrix. Note that the basic metrics -functions in Pango report results in integer Pango units. To get -to the floating point units used in Cairo divide by %PANGO_SCALE. - -## Using Pango with Cairo ## {#rotated-example} - -|[<!-- language="C" --> -#include <math.h> -#include <pango/pangocairo.h> - -static void -draw_text (cairo_t *cr) -{ -#define RADIUS 150 -#define N_WORDS 10 -#define FONT "Sans Bold 27" - - PangoLayout *layout; - PangoFontDescription *desc; - int i; - - /&ast; Center coordinates on the middle of the region we are drawing - &ast;/ - cairo_translate (cr, RADIUS, RADIUS); - - /&ast; Create a PangoLayout, set the font and text &ast;/ - layout = pango_cairo_create_layout (cr); - - pango_layout_set_text (layout, "Text", -1); - desc = pango_font_description_from_string (FONT); - pango_layout_set_font_description (layout, desc); - pango_font_description_free (desc); - - /&ast; Draw the layout N_WORDS times in a circle &ast;/ - for (i = 0; i &lt; N_WORDS; i++) - { - int width, height; - double angle = (360. * i) / N_WORDS; - double red; - - cairo_save (cr); - - /&ast; Gradient from red at angle == 60 to blue at angle == 240 &ast;/ - red = (1 + cos ((angle - 60) * G_PI / 180.)) / 2; - cairo_set_source_rgb (cr, red, 0, 1.0 - red); - - cairo_rotate (cr, angle * G_PI / 180.); - - /&ast; Inform Pango to re-layout the text with the new transformation &ast;/ - pango_cairo_update_layout (cr, layout); - - pango_layout_get_size (layout, &amp;width, &amp;height); - cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS); - pango_cairo_show_layout (cr, layout); - - cairo_restore (cr); - } - - /&ast; free the layout object &ast;/ - g_object_unref (layout); -} - -int main (int argc, char **argv) -{ - cairo_t *cr; - char *filename; - cairo_status_t status; - cairo_surface_t *surface; - - if (argc != 2) - { - g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n"); - return 1; - } - - filename = argv[1]; - - surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32, - 2 * RADIUS, 2 * RADIUS); - cr = cairo_create (surface); - - cairo_set_source_rgb (cr, 1.0, 1.0, 1.0); - cairo_paint (cr); - draw_text (cr); - cairo_destroy (cr); - - status = cairo_surface_write_to_png (surface, filename); - cairo_surface_destroy (surface); - - if (status != CAIRO_STATUS_SUCCESS) - { - g_printerr ("Could not save png to '%s'\n", filename); - return 1; - } - - return 0; -} -]| - -Once you build and run the example code above, you should see the -following result: - -![Output of rotated-example](rotated-text.png) - Draw a squiggly line in the specified cairo context that approximately covers the given rectangle in the style of an underline used to indicate a -spelling error. (The width of the underline is rounded to an integer +spelling error. + +The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the -original rectangle) +original rectangle. @@ -732,15 +631,16 @@ original rectangle) Draws the glyphs in @glyph_item in the specified cairo context, + embedding the text associated with the glyphs in the output if the output format supports it (PDF for example), otherwise it acts -similar to pango_cairo_show_glyph_string(). +similar to [func@show_glyph_string]. The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context. Note that @text is the start of the text for layout, which is then -indexed by <literal>@glyph_item->item->offset</literal>. +indexed by `glyph_item->item->offset`. @@ -754,13 +654,14 @@ indexed by <literal>@glyph_item->item->offset</literal>. - a #PangoGlyphItem + a `PangoGlyphItem` Draws the glyphs in @glyphs in the specified cairo context. + The origin of the glyphs (the left edge of the baseline) will be drawn at the current point of the cairo context. @@ -772,18 +673,19 @@ be drawn at the current point of the cairo context. - a #PangoFont from a #PangoCairoFontMap + a `PangoFont` from a `PangoCairoFontMap` - a #PangoGlyphString + a `PangoGlyphString` - Draws a #PangoLayout in the specified cairo context. -The top-left corner of the #PangoLayout will be drawn + Draws a `PangoLayout` in the specified cairo context. + +The top-left corner of the `PangoLayout` will be drawn at the current point of the cairo context. @@ -800,7 +702,8 @@ at the current point of the cairo context. - Draws a #PangoLayoutLine in the specified cairo context. + Draws a `PangoLayoutLine` in the specified cairo context. + The origin of the glyphs (the left edge of the line) will be drawn at the current point of the cairo context. @@ -812,17 +715,18 @@ be drawn at the current point of the cairo context. - a #PangoLayoutLine + a `PangoLayoutLine` - Updates a #PangoContext previously created for use with Cairo to + Updates a `PangoContext` previously created for use with Cairo to match the current transformation and target surface of a Cairo -context. If any layouts have been created for the context, -it's necessary to call pango_layout_context_changed() on those -layouts. +context. + +If any layouts have been created for the context, it's necessary +to call [method@Pango.Layout.context_changed] on those layouts. @@ -832,15 +736,15 @@ layouts. - a #PangoContext, from a pangocairo font map + a `PangoContext`, from a pangocairo font map - Updates the private #PangoContext of a #PangoLayout created with -pango_cairo_create_layout() to match the current transformation -and target surface of a Cairo context. + Updates the private `PangoContext` of a `PangoLayout` created with +[func@create_layout] to match the current transformation and target +surface of a Cairo context. @@ -850,7 +754,7 @@ and target surface of a Cairo context. - a #PangoLayout, from pango_cairo_create_layout() + a `PangoLayout`, from [func@create_layout] diff --git a/PangoFT2-1.0.gir b/PangoFT2-1.0.gir index 5066424..d4b4ec8 100644 --- a/PangoFT2-1.0.gir +++ b/PangoFT2-1.0.gir @@ -15,13 +15,14 @@ and/or use gtk-doc annotations. --> - The #PangoFT2FontMap is the #PangoFontMap implementation for FreeType fonts. + The `PangoFT2FontMap` is the `PangoFontMap` implementation for FreeType fonts. - Create a new #PangoFT2FontMap object; a fontmap is used -to cache information about available fonts, and holds -certain global parameters such as the resolution and + Create a new `PangoFT2FontMap` object. + +A fontmap is used to cache information about available fonts, +and holds certain global parameters such as the resolution and the default substitute function (see -pango_ft2_font_map_set_default_substitute()). +[method@PangoFT2.FontMap.set_default_substitute]). the newly created fontmap object. Unref with g_object_unref() when you are finished with it. @@ -29,19 +30,21 @@ with g_object_unref() when you are finished with it. - Returns a #PangoFT2FontMap. This font map is cached and should + Returns a `PangoFT2FontMap`. + +This font map is cached and should not be freed. If the font map is no longer needed, it can be released with pango_ft2_shutdown_display(). Use of the global PangoFT2 fontmap is deprecated; use pango_ft2_font_map_new() instead. - a #PangoFT2FontMap. + a `PangoFT2FontMap`. - Create a #PangoContext for the given fontmap. - Use pango_font_map_create_context() instead. + Create a `PangoContext` for the given fontmap. + Use [method@Pango.FontMap.create_context] instead. the newly created context; free with g_object_unref(). @@ -49,22 +52,26 @@ instead. - a #PangoFT2FontMap + a `PangoFT2FontMap` - + Sets a function that will be called to do final configuration -substitution on a #FcPattern before it is used to load -the font. This function can be used to do things like set +substitution on a `FcPattern` before it is used to load +the font. + +This function can be used to do things like set hinting and antialiasing options. + Use [method@PangoFc.FontMap.set_default_substitute] +instead. - a #PangoFT2FontMap + a `PangoFT2FontMap` @@ -89,7 +96,7 @@ hinting and antialiasing options. - a #PangoFT2FontMap + a `PangoFT2FontMap` @@ -102,18 +109,21 @@ hinting and antialiasing options. - + Call this function any time the results of the default substitution function set with pango_ft2_font_map_set_default_substitute() change. + That is, if your substitution function will return different results for the same input pattern, you must call this function. + Use [method@PangoFc.FontMap.substitute_changed] +instead. - a #PangoFT2FontMap + a `PangoFT2FontMap` @@ -132,7 +142,7 @@ results for the same input pattern, you must call this function. - the <type>FcPattern</type> to tweak. + the FcPattern to tweak. @@ -142,10 +152,11 @@ results for the same input pattern, you must call this function. - Gets the #PangoCoverage for a `PangoFT2Font`. Use -pango_font_get_coverage() instead. + Gets the `PangoCoverage` for a `PangoFT2Font`. + +Use [method@Pango.Font.get_coverage] instead. - a #PangoCoverage. + a `PangoCoverage` @@ -160,20 +171,23 @@ pango_font_get_coverage() instead. - Returns the native FreeType2 `FT_Face` structure used for this #PangoFont. -This may be useful if you want to use FreeType2 functions directly. + Returns the native FreeType2 `FT_Face` structure +used for this `PangoFont`. -Use pango_fc_font_lock_face() instead; when you are done with a -face from pango_fc_font_lock_face() you must call -pango_fc_font_unlock_face(). +This may be useful if you want to use FreeType2 +functions directly. + +Use [method@PangoFc.Font.lock_face] instead; when you are +done with a face from [method@PangoFc.Font.lock_face], you +must call [method@PangoFc.Font.unlock_face]. - a pointer to a `FT_Face` structure, with the - size set correctly, or %NULL if @font is %NULL. + a pointer to a `FT_Face` structure, + with the size set correctly - a #PangoFont + a `PangoFont` @@ -183,36 +197,32 @@ pango_fc_font_unlock_face(). Use pango_fc_font_kern_glyphs() instead. - The amount of kerning (in Pango units) to apply for -the given combination of glyphs. + The amount of kerning (in Pango units) to + apply for the given combination of glyphs. - a #PangoFont + a `PangoFont` - the left #PangoGlyph + the left `PangoGlyph` - the right #PangoGlyph + the right `PangoGlyph` - - The macros and functions in this section are used to access fonts and render -text to bitmaps using the FreeType 2 library. - - Retrieves a #PangoContext for the default PangoFT2 fontmap + Retrieves a `PangoContext` for the default PangoFT2 fontmap (see pango_ft2_font_map_for_display()) and sets the resolution for the default fontmap to @dpi_x by @dpi_y. - Use pango_font_map_create_context() instead. + Use [method@Pango.FontMap.create_context] instead. - the new #PangoContext + the new `PangoContext` @@ -227,32 +237,26 @@ for the default fontmap to @dpi_x by @dpi_y. - Return the index of a glyph suitable for drawing unknown characters with -@font, or %PANGO_GLYPH_EMPTY if no suitable glyph found. + Return the index of a glyph suitable for drawing unknown +characters with @font, or %PANGO_GLYPH_EMPTY if no suitable +glyph found. -If you want to draw an unknown-box for a character that is not covered -by the font, -use PANGO_GET_UNKNOWN_GLYPH() instead. +If you want to draw an unknown-box for a character that +is not covered by the font, use PANGO_GET_UNKNOWN_GLYPH() +instead. a glyph index into @font, or %PANGO_GLYPH_EMPTY - a #PangoFont + a `PangoFont` - - #PangoRenderer is a base class that contains the necessary logic for -rendering a #PangoLayout or #PangoLayoutLine. By subclassing -#PangoRenderer and overriding operations such as @draw_glyphs and -@draw_rectangle, renderers for particular font backends and -destinations can be created. - - Renders a #PangoGlyphString onto a FreeType2 bitmap. + Renders a `PangoGlyphString` onto a FreeType2 bitmap. @@ -280,17 +284,17 @@ destinations can be created. - Render a #PangoLayout onto a FreeType2 bitmap + Render a `PangoLayout` onto a FreeType2 bitmap - a <type>FT_Bitmap</type> to render the layout onto + a FT_Bitmap to render the layout onto - a #PangoLayout + a `PangoLayout` @@ -304,17 +308,17 @@ destinations can be created. - Render a #PangoLayoutLine onto a FreeType2 bitmap + Render a `PangoLayoutLine` onto a FreeType2 bitmap - a <type>FT_Bitmap</type> to render the line onto + a FT_Bitmap to render the line onto - a #PangoLayoutLine + a `PangoLayoutLine` @@ -328,21 +332,23 @@ destinations can be created. - Render a #PangoLayoutLine onto a FreeType2 bitmap, with he + Render a `PangoLayoutLine` onto a FreeType2 bitmap, with he location specified in fixed-point Pango units rather than -pixels. (Using this will avoid extra inaccuracies from -rounding to integer pixels multiple times, even if the -final glyph positions are integers.) +pixels. + +(Using this will avoid extra inaccuracies from rounding +to integer pixels multiple times, even if the final glyph +positions are integers.) - a <type>FT_Bitmap</type> to render the line onto + a FT_Bitmap to render the line onto - a #PangoLayoutLine + a `PangoLayoutLine` @@ -356,21 +362,23 @@ final glyph positions are integers.) - Render a #PangoLayout onto a FreeType2 bitmap, with he + Render a `PangoLayout` onto a FreeType2 bitmap, with he location specified in fixed-point Pango units rather than -pixels. (Using this will avoid extra inaccuracies from -rounding to integer pixels multiple times, even if the -final glyph positions are integers.) +pixels. + +(Using this will avoid extra inaccuracies from rounding +to integer pixels multiple times, even if the final glyph +positions are integers.) - a <type>FT_Bitmap</type> to render the layout onto + a FT_Bitmap to render the layout onto - a #PangoLayout + a `PangoLayout` @@ -384,11 +392,13 @@ final glyph positions are integers.) - Renders a #PangoGlyphString onto a FreeType2 bitmap, possibly + Renders a `PangoGlyphString` onto a FreeType2 bitmap, possibly transforming the layed-out coordinates through a transformation -matrix. Note that the transformation matrix for @font is not +matrix. + +Note that the transformation matrix for @font is not changed, so to produce correct rendering results, the @font -must have been loaded using a #PangoContext with an identical +must have been loaded using a `PangoContext` with an identical transformation matrix to that passed in to this function. @@ -399,8 +409,7 @@ transformation matrix to that passed in to this function. - a #PangoMatrix, or %NULL to use an identity - transformation + a `PangoMatrix` @@ -413,12 +422,12 @@ transformation matrix to that passed in to this function. the x position of the start of the string (in Pango - units in user space coordinates) + units in user space coordinates) the y position of the baseline (in Pango units - in user space coordinates) + in user space coordinates) diff --git a/PangoFc-1.0.gir b/PangoFc-1.0.gir index 1de3060..190843d 100644 --- a/PangoFc-1.0.gir +++ b/PangoFc-1.0.gir @@ -27,32 +27,44 @@ and/or use gtk-doc annotations. --> - PangoFcDecoder represents a decoder that an application provides -for handling a font that is encoded in a custom way. + `PangoFcDecoder` is a virtual base class that implementations will +inherit from. + +It's the interface that is used to define a custom encoding for a font. +These objects are created in your code from a function callback that was +originally registered with [method@PangoFc.FontMap.add_decoder_find_func]. +Pango requires information about the supported charset for a font as well +as the individual character to glyph conversions. Pango gets that +information via the #get_charset and #get_glyph callbacks into your +object implementation. - Generates an #FcCharSet of supported characters for the fcfont -given. The returned #FcCharSet will be a reference to an -internal value stored by the #PangoFcDecoder and must not + Generates an `FcCharSet` of supported characters for the @fcfont +given. + +The returned `FcCharSet` will be a reference to an +internal value stored by the `PangoFcDecoder` and must not be modified or freed. - the #FcCharset for @fcfont; must not + the `FcCharset` for @fcfont; must not be modified or freed. - a #PangoFcDecoder + a `PangoFcDecoder` - the #PangoFcFont to query. + the `PangoFcFont` to query. - Generates a #PangoGlyph for the given Unicode point using the -custom decoder. For complex scripts where there can be multiple + Generates a `PangoGlyph` for the given Unicode point using the +custom decoder. + +For complex scripts where there can be multiple glyphs for a single character, the decoder will return whatever glyph is most convenient for it. (Usually whatever glyph is directly in the fonts character map table.) @@ -63,43 +75,47 @@ covered by the font. - a #PangoFcDecoder + a `PangoFcDecoder` - a #PangoFcFont to query. + a `PangoFcFont` to query. - the Unicode code point to convert to a single #PangoGlyph. + the Unicode code point to convert to a single `PangoGlyph`. - Generates an #FcCharSet of supported characters for the fcfont -given. The returned #FcCharSet will be a reference to an -internal value stored by the #PangoFcDecoder and must not + Generates an `FcCharSet` of supported characters for the @fcfont +given. + +The returned `FcCharSet` will be a reference to an +internal value stored by the `PangoFcDecoder` and must not be modified or freed. - the #FcCharset for @fcfont; must not + the `FcCharset` for @fcfont; must not be modified or freed. - a #PangoFcDecoder + a `PangoFcDecoder` - the #PangoFcFont to query. + the `PangoFcFont` to query. - Generates a #PangoGlyph for the given Unicode point using the -custom decoder. For complex scripts where there can be multiple + Generates a `PangoGlyph` for the given Unicode point using the +custom decoder. + +For complex scripts where there can be multiple glyphs for a single character, the decoder will return whatever glyph is most convenient for it. (Usually whatever glyph is directly in the fonts character map table.) @@ -110,15 +126,15 @@ covered by the font. - a #PangoFcDecoder + a `PangoFcDecoder` - a #PangoFcFont to query. + a `PangoFcFont` to query. - the Unicode code point to convert to a single #PangoGlyph. + the Unicode code point to convert to a single `PangoGlyph`. @@ -128,24 +144,24 @@ covered by the font. - Class structure for #PangoFcDecoder. + Class structure for `PangoFcDecoder`. - the #FcCharset for @fcfont; must not + the `FcCharset` for @fcfont; must not be modified or freed. - a #PangoFcDecoder + a `PangoFcDecoder` - the #PangoFcFont to query. + the `PangoFcFont` to query. @@ -160,15 +176,15 @@ covered by the font. - a #PangoFcDecoder + a `PangoFcDecoder` - a #PangoFcFont to query. + a `PangoFcFont` to query. - the Unicode code point to convert to a single #PangoGlyph. + the Unicode code point to convert to a single `PangoGlyph`. @@ -204,7 +220,7 @@ covered by the font. - Callback function passed to pango_fc_font_map_add_decoder_find_func(). + Callback function passed to [method@PangoFc.FontMap.add_decoder_find_func]. a new reference to a custom decoder for this pattern, or %NULL if the default decoder handling should be used. @@ -212,11 +228,12 @@ covered by the font. - a fully resolved #FcPattern specifying the font on the system + a fully resolved `FcPattern` specifying the font on the system - user data passed to pango_fc_font_map_add_decoder_find_func() + user data passed to + [method@PangoFc.FontMap.add_decoder_find_func] @@ -228,14 +245,16 @@ covered by the font. - String representing a fontconfig property name that Pango reads from font -patterns to populate list of OpenType features to be enabled for the font -by default. + Fontconfig property that Pango reads from font +patterns to populate list of OpenType features +to be enabled for the font by default. -The property will have a number of string elements, each of which is the -OpenType feature tag of one feature to enable. +The property will have a number of string elements, +each of which is the OpenType feature tag of one feature +to enable. -This is equivalent to FC_FONT_FEATURES in versions of fontconfig that have that. +This is equivalent to FC_FONT_FEATURES in versions of +fontconfig that have that. @@ -245,35 +264,38 @@ This is equivalent to FC_FONT_FEATURES in versions of fontconfig that have that. - String representing a fontconfig property name that Pango reads from font -patterns to populate list of OpenType font variations to be used for a font. + Fontconfig property that Pango reads from font +patterns to populate list of OpenType font variations +to be used for a font. -The property will have a string elements, each of which a comma-separated -list of OpenType axis setting of the form AXIS=VALUE. +The property will have a string elements, each of which +a comma-separated list of OpenType axis setting of the +form AXIS=VALUE. - #PangoFcFont is a base class for font implementation using the -Fontconfig and FreeType libraries. It is used in the -<link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and -<link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link> -backends shipped with Pango, but can also be used when creating -new backends. Any backend deriving from this base class will -take advantage of the wide range of shapers implemented using -FreeType that come with Pango. + `PangoFcFont` is a base class for font implementations +using the Fontconfig and FreeType libraries. + +It is used in onjunction with [class@PangoFc.FontMap]. +When deriving from this class, you need to implement all +of its virtual functions other than shutdown() along with +the get_glyph_extents() virtual function from `PangoFont`. - Creates a #PangoFontDescription that matches the specified -Fontconfig pattern as closely as possible. Many possible Fontconfig -pattern values, such as %FC_RASTERIZER or %FC_DPI, don't make sense in -the context of #PangoFontDescription, so will be ignored. + Creates a `PangoFontDescription` that matches the specified +Fontconfig pattern as closely as possible. + +Many possible Fontconfig pattern values, such as %FC_RASTERIZER +or %FC_DPI, don't make sense in the context of `PangoFontDescription`, +so will be ignored. - a new #PangoFontDescription. Free with - pango_font_description_free(). + a new `PangoFontDescription`. Free with + pango_font_description_free(). - a #FcPattern + a `FcPattern` @@ -286,8 +308,10 @@ the context of #PangoFontDescription, so will be ignored. Gets the glyph index for a given Unicode character -for @font. If you only want to determine -whether the font has the glyph, use pango_fc_font_has_char(). +for @font. + +If you only want to determine whether the font has +the glyph, use [method@PangoFc.Font.has_char]. the glyph index, or 0, if the Unicode character doesn't exist in the font. @@ -295,7 +319,7 @@ whether the font has the glyph, use pango_fc_font_has_char(). - a #PangoFcFont + a `PangoFcFont` @@ -304,9 +328,41 @@ whether the font has the glyph, use pango_fc_font_has_char(). + + Returns the languages that are supported by @font. + +This corresponds to the FC_LANG member of the FcPattern. + +The returned array is only valid as long as the font +and its fontmap are valid. + + a %NULL-terminated + array of `PangoLanguage`* + + + + + a `PangoFcFont` + + + + + + Returns the FcPattern that @font is based on. + + the fontconfig pattern for this font + + + + + a `PangoFcFont` + + + + - Returns the index of a glyph suitable for drawing @wc as an -unknown character. + Returns the index of a glyph suitable for drawing @wc +as an unknown character. Use PANGO_GET_UNKNOWN_GLYPH() instead. @@ -315,7 +371,7 @@ Use PANGO_GET_UNKNOWN_GLYPH() instead. - a #PangoFcFont + a `PangoFcFont` @@ -326,14 +382,14 @@ Use PANGO_GET_UNKNOWN_GLYPH() instead. Determines whether @font has a glyph for the codepoint @wc. - Use pango_font_has_char() + Use [method@Pango.Font.has_char] %TRUE if @font has the requested codepoint. - a #PangoFcFont + a `PangoFcFont` @@ -352,19 +408,20 @@ Since 1.44, it does nothing. - a #PangoFcFont + a `PangoFcFont` - a #PangoGlyphString + a `PangoGlyphString` - Gets the FreeType `FT_Face` associated with a font, + Gets the FreeType `FT_Face` associated with a font. + This face will be kept around until you call -pango_fc_font_unlock_face(). +[method@PangoFc.Font.unlock_face]. Use pango_font_get_hb_font() instead the FreeType `FT_Face` associated with @font. @@ -372,29 +429,31 @@ pango_fc_font_unlock_face(). - a #PangoFcFont. + a `PangoFcFont`. Releases a font previously obtained with -pango_fc_font_lock_face(). +[method@PangoFc.Font.lock_face]. Use pango_font_get_hb_font() instead - a #PangoFcFont. + a `PangoFcFont`. + The PangoFc font map this font is associated with. + The fontconfig pattern for this font. @@ -429,31 +488,31 @@ pango_fc_font_lock_face(). - PangoFcFontMap is a base class for font map implementations using the -Fontconfig and FreeType libraries. It is used in the -<link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and -<link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link> -backends shipped with Pango, but can also be used when creating -new backends. Any backend deriving from this base class will -take advantage of the wide range of shapers implemented using -FreeType that come with Pango. + `PangoFcFontMap` is a base class for font map implementations using the +Fontconfig and FreeType libraries. + +It is used in the Xft and FreeType backends shipped with Pango, +but can also be used when creating new backends. Any backend +deriving from this base class will take advantage of the wide +range of shapers implemented using FreeType that come with Pango. - This function saves a callback method in the #PangoFcFontMap that -will be called whenever new fonts are created. If the -function returns a #PangoFcDecoder, that decoder will be used to -determine both coverage via a #FcCharSet and a one-to-one mapping of -characters to glyphs. This will allow applications to have + This function saves a callback method in the `PangoFcFontMap` that +will be called whenever new fonts are created. + +If the function returns a `PangoFcDecoder`, that decoder will be used +to determine both coverage via a `FcCharSet` and a one-to-one mapping +of characters to glyphs. This will allow applications to have application-specific encodings for various fonts. - The #PangoFcFontMap to add this method to. + The `PangoFcFontMap` to add this method to. - The #PangoFcDecoderFindFunc callback function + The `PangoFcDecoderFindFunc` callback function @@ -461,15 +520,16 @@ application-specific encodings for various fonts. - A #GDestroyNotify callback that will be called when the - fontmap is finalized and the decoder is released. + A `GDestroyNotify` callback that will be called when the + fontmap is finalized and the decoder is released. - Clear all cached information and fontsets for this font map; -this should be called whenever there is a change in the + Clear all cached information and fontsets for this font map. + +This should be called whenever there is a change in the output of the default_substitute() virtual function of the font map, or if fontconfig has been reinitialized to new configuration. @@ -478,59 +538,64 @@ configuration. - a #PangoFcFontMap + a `PangoFcFontMap` - Informs font map that the fontconfig configuration (ie, FcConfig object) -used by this font map has changed. This currently calls -pango_fc_font_map_cache_clear() which ensures that list of fonts, etc -will be regenerated using the updated configuration. + Informs font map that the fontconfig configuration (i.e., FcConfig +object) used by this font map has changed. + +This currently calls [method@PangoFc.FontMap.cache_clear] which +ensures that list of fonts, etc will be regenerated using the +updated configuration. - a #PangoFcFontMap + a `PangoFcFontMap` - Creates a new context for this fontmap. This function is intended -only for backend implementations deriving from #PangoFcFontMap; -it is possible that a backend will store additional information -needed for correct operation on the #PangoContext after calling -this function. + Creates a new context for this fontmap. + +This function is intended only for backend implementations deriving +from `PangoFcFontMap`; it is possible that a backend will store +additional information needed for correct operation on the `PangoContext` +after calling this function. Use pango_font_map_create_context() instead. - a new #PangoContext + a new `PangoContext` - a #PangoFcFontMap + a `PangoFcFontMap` - Finds the decoder to use for @pattern. Decoders can be added to -a font map using pango_fc_font_map_add_decoder_find_func(). + Finds the decoder to use for @pattern. + +Decoders can be added to a font map using +[method@PangoFc.FontMap.add_decoder_find_func]. - a newly created #PangoFcDecoder + a newly created `PangoFcDecoder` object or %NULL if no decoder is set for @pattern. - The #PangoFcFontMap to use. + The `PangoFcFontMap` to use. - The #FcPattern to find the decoder for. + The `FcPattern` to find the decoder for. @@ -538,78 +603,131 @@ a font map using pango_fc_font_map_add_decoder_find_func(). Fetches the `FcConfig` attached to a font map. -See also: pango_fc_font_map_set_config() +See also: [method@PangoFc.FontMap.set_config]. - the `FcConfig` object attached to @fcfontmap, which - might be %NULL. + the `FcConfig` object attached to + @fcfontmap, which might be %NULL. The return value is + owned by Pango and should not be freed. - a #PangoFcFontMap + a `PangoFcFontMap` - Retrieves the `hb_face_t` for the given #PangoFcFont. + Retrieves the `hb_face_t` for the given `PangoFcFont`. - the `hb_face_t` for the given Pango font + the `hb_face_t` + for the given font - a #PangoFcFontMap + a `PangoFcFontMap` - a #PangoFcFont + a `PangoFcFont` - Set the FcConfig for this font map to use. The default value + Set the `FcConfig` for this font map to use. + +The default value is %NULL, which causes Fontconfig to use its global "current config". -You can create a new FcConfig object and use this API to attach it +You can create a new `FcConfig` object and use this API to attach it to a font map. This is particularly useful for example, if you want to use application -fonts with Pango. For that, you would create a fresh FcConfig, add your +fonts with Pango. For that, you would create a fresh `FcConfig`, add your app fonts to it, and attach it to a new Pango font map. If @fcconfig is different from the previous config attached to the font map, -pango_fc_font_map_config_changed() is called. +[method@PangoFc.FontMap.config_changed] is called. -This function acquires a reference to the FcConfig object; the caller -does NOT need to retain a reference. +This function acquires a reference to the `FcConfig` object; the caller +does **not** need to retain a reference. - a #PangoFcFontMap + a `PangoFcFontMap` - a `FcConfig`, or %NULL + a `FcConfig` + + Sets a function that will be called to do final configuration +substitution on a `FcPattern` before it is used to load +the font. + +This function can be used to do things like set +hinting and antialiasing options. + + + + + + a `PangoFcFontMap` + + + + function to call to to do final config tweaking on `FcPattern` objects + + + + data to pass to @func + + + + function to call when @data is no longer used + + + + Clears all cached information for the fontmap and marks -all fonts open for the fontmap as dead. (See the shutdown() -virtual function of #PangoFcFont.) This function might be used -by a backend when the underlying windowing system for the font -map exits. This function is only intended to be called -only for backend implementations deriving from #PangoFcFontMap. +all fonts open for the fontmap as dead. + +See the shutdown() virtual function of `PangoFcFont`. + +This function might be used by a backend when the underlying +windowing system for the font map exits. This function is only +intended to be called only for backend implementations deriving +from `PangoFcFontMap`. - a #PangoFcFontMap + a `PangoFcFontMap` + + + + + + Call this function any time the results of the default +substitution function set with +[method@PangoFc.FontMap.set_default_substitute] change. + +That is, if your substitution function will return different +results for the same input pattern, you must call this function. + + + + + + a `PangoFcFontMap` @@ -618,13 +736,15 @@ only for backend implementations deriving from #PangoFcFontMap. - String representing a fontconfig property name that Pango sets on any -fontconfig pattern it passes to fontconfig if a #PangoGravity other -than %PANGO_GRAVITY_SOUTH is desired. + Fontconfig property that Pango sets on any +fontconfig pattern it passes to fontconfig +if a `PangoGravity` other than %PANGO_GRAVITY_SOUTH +is desired. -The property will have a #PangoGravity value as a string, like "east". -This can be used to write fontconfig configuration rules to choose -different fonts for horizontal and vertical writing directions. +The property will have a `PangoGravity` value as a string, +like "east". This can be used to write fontconfig configuration +rules to choose different fonts for horizontal and vertical +writing directions. @@ -652,25 +772,42 @@ different fonts for horizontal and vertical writing directions. - String representing a fontconfig property name that Pango sets on any + Fontconfig property that Pango sets on any fontconfig pattern it passes to fontconfig. The property will have a string equal to what -g_get_prgname() returns. -This can be used to write fontconfig configuration rules that only affect +g_get_prgname() returns. This can be used to write +fontconfig configuration rules that only affect certain applications. -This is equivalent to FC_PRGNAME in versions of fontconfig that have that. +This is equivalent to FC_PRGNAME in versions of +fontconfig that have that. + + Function type for doing final config tweaking on prepared `FcPattern`s. + + + + + + the FcPattern to tweak. + + + + user data. + + + + - String representing a fontconfig property name that Pango sets on any + Fontconfig property that Pango sets on any fontconfig pattern it passes to fontconfig. The property will have an integer value equal to what -pango_version() returns. -This can be used to write fontconfig configuration rules that only affect -certain pango versions (or only pango-using applications, or only +[func@Pango.version] returns. This can be used to write +fontconfig configuration rules that only affect certain +pango versions (or only pango-using applications, or only non-pango-using applications). diff --git a/PangoOT-1.0.gir b/PangoOT-1.0.gir index 1496959..60ceec2 100644 --- a/PangoOT-1.0.gir +++ b/PangoOT-1.0.gir @@ -9,9 +9,9 @@ and/or use gtk-doc annotations. --> - The #PangoOTTag typedef is used to represent TrueType and OpenType + The `PangoOTTag` typedef is used to represent TrueType and OpenType four letter tags inside Pango. Use PANGO_OT_TAG_MAKE() -or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create <type>PangoOTTag</type>s manually. +or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create PangoOTTags manually. @@ -21,32 +21,34 @@ feature should be applied to all glyphs. - Creates a new #PangoOTBuffer for the given OpenType font. + Creates a new `PangoOTBuffer` for the given OpenType font. - the newly allocated #PangoOTBuffer, which should - be freed with pango_ot_buffer_destroy(). + the newly allocated `PangoOTBuffer`, which should + be freed with [method@PangoOT.Buffer.destroy]. - a #PangoFcFont + a `PangoFcFont` - Appends a glyph to a #PangoOTBuffer, with @properties identifying which -features should be applied on this glyph. See pango_ot_ruleset_add_feature(). + Appends a glyph to a `PangoOTBuffer`, with @properties identifying which +features should be applied on this glyph. + +See [method@PangoOT.Ruleset.add_feature]. - a #PangoOTBuffer + a `PangoOTBuffer` - the glyph index to add, like a #PangoGlyph + the glyph index to add, like a `PangoGlyph` @@ -60,82 +62,86 @@ features should be applied on this glyph. See pango_ot_ruleset_add_feature(). - Empties a #PangoOTBuffer, make it ready to add glyphs to. + Empties a `PangoOTBuffer`, make it ready to add glyphs to. - a #PangoOTBuffer + a `PangoOTBuffer` - Destroys a #PangoOTBuffer and free all associated memory. + Destroys a `PangoOTBuffer` and free all associated memory. - a #PangoOTBuffer + a `PangoOTBuffer` - Gets the glyph array contained in a #PangoOTBuffer. The glyphs are -owned by the buffer and should not be freed, and are only valid as long -as buffer is not modified. + Gets the glyph array contained in a `PangoOTBuffer`. + +The glyphs are owned by the buffer and should not be freed, +and are only valid as long as buffer is not modified. - a #PangoOTBuffer + a `PangoOTBuffer` location to - store the array of glyphs, or %NULL + store the array of glyphs - location to store the number of - glyphs, or %NULL + location to store the number of glyphs - Exports the glyphs in a #PangoOTBuffer into a #PangoGlyphString. This is -typically used after the OpenType layout processing is over, to convert the -resulting glyphs into a generic Pango glyph string. + Exports the glyphs in a `PangoOTBuffer` into a `PangoGlyphString`. + +This is typically used after the OpenType layout processing +is over, to convert the resulting glyphs into a generic Pango +glyph string. - a #PangoOTBuffer + a `PangoOTBuffer` - a #PangoGlyphString + a `PangoGlyphString` - Sets whether glyphs will be rendered right-to-left. This setting -is needed for proper horizontal positioning of right-to-left scripts. + Sets whether glyphs will be rendered right-to-left. + +This setting is needed for proper horizontal positioning +of right-to-left scripts. - a #PangoOTBuffer + a `PangoOTBuffer` @@ -146,6 +152,7 @@ is needed for proper horizontal positioning of right-to-left scripts. Sets whether characters with a mark class should be forced to zero width. + This setting is needed for proper positioning of Arabic accents, but will produce incorrect results with standard OpenType Indic fonts. @@ -154,12 +161,12 @@ fonts. - a #PangoOTBuffer + a `PangoOTBuffer` %TRUE if characters with a mark class should - be forced to zero width. + be forced to zero width @@ -178,9 +185,9 @@ default language system explicitly. - The #PangoOTFeatureMap typedef is used to represent an OpenType + The `PangoOTFeatureMap` typedef is used to represent an OpenType feature with the property bit associated with it. The feature tag is -represented as a char array instead of a #PangoOTTag for convenience. +represented as a char array instead of a `PangoOTTag` for convenience. feature tag in represented as four-letter ASCII string. @@ -194,7 +201,7 @@ pango_ot_ruleset_add_feature() for details. - The #PangoOTGlyph structure represents a single glyph together with + The `PangoOTGlyph` structure represents a single glyph together with information used for OpenType layout processing of the glyph. It contains the following fields. @@ -243,134 +250,136 @@ applied on this glyph. See pango_ot_ruleset_add_feature(). - Returns the #PangoOTInfo structure for the given FreeType font face. + Returns the `PangoOTInfo` structure for the given FreeType font face. - the #PangoOTInfo for @face. This object - will have the same lifetime as @face. + the `PangoOTInfo` for @face. + This object will have the same lifetime as @face. - a <type>FT_Face</type>. + a `FT_Face` - Finds the index of a feature. If the feature is not found, sets -@feature_index to PANGO_OT_NO_FEATURE, which is safe to pass to -pango_ot_ruleset_add_feature() and similar functions. + Finds the index of a feature. -In the future, this may set @feature_index to an special value that if used -in pango_ot_ruleset_add_feature() will ask Pango to synthesize the -requested feature based on Unicode properties and data. However, this -function will still return %FALSE in those cases. So, users may want to +If the feature is not found, sets @feature_index to PANGO_OT_NO_FEATURE, +which is safe to pass to [method@PangoOT.Ruleset.add_feature] and similar +functions. + +In the future, this may set @feature_index to an special value that if +used in [method@PangoOT.Ruleset.add_feature] will ask Pango to synthesize +the requested feature based on Unicode properties and data. However, this +function will still return %FALSE in those cases. So, users may want to ignore the return value of this function in certain cases. - %TRUE if the feature was found. + %TRUE if the feature was found - a #PangoOTInfo. + a `PangoOTInfo` - the table type to obtain information about. + the table type to obtain information about - the tag of the feature to find. + the tag of the feature to find - the index of the script. + the index of the script the index of the language whose features are searched, - or %PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script. + or %PANGO_OT_DEFAULT_LANGUAGE to use the default language of the script location to store the index of - the feature, or %NULL. + the feature Finds the index of a language and its required feature index. -If the language is not found, sets @language_index to -PANGO_OT_DEFAULT_LANGUAGE and the required feature of the default language -system is returned in required_feature_index. For best compatibility with -some fonts, also searches the language system tag 'dflt' before falling -back to the default language system, but that is transparent to the user. -The user can simply ignore the return value of this function to -automatically fall back to the default language system. + +If the language is not found, sets @language_index to %PANGO_OT_DEFAULT_LANGUAGE +and the required feature of the default language system is returned in +required_feature_index. For best compatibility with some fonts, also +searches the language system tag 'dflt' before falling back to the default +language system, but that is transparent to the user. The user can simply +ignore the return value of this function to automatically fall back to the +default language system. - %TRUE if the language was found. + %TRUE if the language was found - a #PangoOTInfo. + a `PangoOTInfo` - the table type to obtain information about. + the table type to obtain information about - the index of the script whose languages are searched. + the index of the script whose languages are searched - the tag of the language to find. + the tag of the language to find - location to store the index of - the language, or %NULL. + location to store the index of the language location to store the - required feature index of the language, or %NULL. + required feature index of the language - Finds the index of a script. If not found, tries to find the 'DFLT' -and then 'dflt' scripts and return the index of that in @script_index. -If none of those is found either, %PANGO_OT_NO_SCRIPT is placed in -@script_index. + Finds the index of a script. + +If not found, tries to find the 'DFLT' and then 'dflt' scripts and +return the index of that in @script_index. If none of those is found +either, %PANGO_OT_NO_SCRIPT is placed in @script_index. All other functions taking an input script_index parameter know how to handle %PANGO_OT_NO_SCRIPT, so one can ignore the return value of this function completely and proceed, to enjoy the automatic fallback to the 'DFLT'/'dflt' script. - %TRUE if the script was found. + %TRUE if the script was found - a #PangoOTInfo. + a `PangoOTInfo` - the table type to obtain information about. + the table type to obtain information about - the tag of the script to find. + the tag of the script to find - location to store the index of the - script, or %NULL. + location to store the index of the script @@ -378,31 +387,31 @@ fallback to the 'DFLT'/'dflt' script. Obtains the list of features for the given language of the given script. - a newly-allocated zero-terminated array containing the tags of the -available features. Should be freed using g_free(). + a newly-allocated zero-terminated + array containing the tags of the available features - a #PangoOTInfo. + a `PangoOTInfo` - the table type to obtain information about. + the table type to obtain information about - unused parameter. + unused parameter - the index of the script to obtain information about. + the index of the script to obtain information about the index of the language to list features for, or - %PANGO_OT_DEFAULT_LANGUAGE, to list features for the default - language of the script. + %PANGO_OT_DEFAULT_LANGUAGE, to list features for the default + language of the script @@ -410,25 +419,25 @@ available features. Should be freed using g_free(). Obtains the list of available languages for a given script. - a newly-allocated zero-terminated array containing the tags of the - available languages. Should be freed using g_free(). + a newly-allocated zero-terminated + array containing the tags of the available languages - a #PangoOTInfo. + a `PangoOTInfo` - the table type to obtain information about. + the table type to obtain information about - the index of the script to list languages for. + the index of the script to list languages for - unused parameter. + unused parameter @@ -436,17 +445,17 @@ available features. Should be freed using g_free(). Obtains the list of available scripts. - a newly-allocated zero-terminated array containing the tags of the - available scripts. Should be freed using g_free(). + a newly-allocated zero-terminated + array containing the tags of the available scripts - a #PangoOTInfo. + a `PangoOTInfo` - the table type to obtain information about. + the table type to obtain information about @@ -475,133 +484,128 @@ this value, so no special handling is required by the user. - The #PangoOTRuleset structure holds a -set of features selected from the tables in an OpenType font. -(A feature is an operation such as adjusting glyph positioning + The `PangoOTRuleset` structure holds a set of features selected +from the tables in an OpenType font. + +A feature is an operation such as adjusting glyph positioning that should be applied to a text feature such as a certain -type of accent.) A #PangoOTRuleset -is created with pango_ot_ruleset_new(), features are added -to it with pango_ot_ruleset_add_feature(), then it is -applied to a #PangoGlyphString with pango_ot_ruleset_shape(). +type of accent. + +A `PangoOTRuleset` is created with [ctor@PangoOT.Ruleset.new], +features are added to it with [method@PangoOT.Ruleset.add_feature], +then it is applied to a `PangoGlyphString` with +[method@PangoOT.Ruleset.position]. - Creates a new #PangoOTRuleset for the given OpenType info. + Creates a new `PangoOTRuleset` for the given OpenType info. - the newly allocated #PangoOTRuleset, which - should be freed with g_object_unref(). + the newly allocated `PangoOTRuleset` - a #PangoOTInfo. + a `PangoOTInfo` - Creates a new #PangoOTRuleset for the given OpenType info, script, and + Creates a new `PangoOTRuleset` for the given OpenType info, script, and language. This function is part of a convenience scheme that highly simplifies -using a #PangoOTRuleset to represent features for a specific pair of script +using a `PangoOTRuleset` to represent features for a specific pair of script and language. So one can use this function passing in the script and language of interest, and later try to add features to the ruleset by just specifying the feature name or tag, without having to deal with finding script, language, or feature indices manually. -In excess to what pango_ot_ruleset_new() does, this function will: -<itemizedlist> - <listitem> - Find the #PangoOTTag script and language tags associated with - @script and @language using pango_ot_tag_from_script() and - pango_ot_tag_from_language(), - </listitem> - <listitem> - For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS, +In addition to what [ctor@PangoOT.Ruleset.new] does, this function will: + +* Find the `PangoOTTag` script and language tags associated with + @script and @language using [func@PangoOT.tag_from_script] and + [func@PangoOT.tag_from_language], + +* For each of table types %PANGO_OT_TABLE_GSUB and %PANGO_OT_TABLE_GPOS, find the script index of the script tag found and the language system index of the language tag found in that script system, using - pango_ot_info_find_script() and pango_ot_info_find_language(), - </listitem> - <listitem> - For found language-systems, if they have required feature - index, add that feature to the ruleset using - pango_ot_ruleset_add_feature(), - </listitem> - <listitem> - Remember found script and language indices for both table types, - and use them in future pango_ot_ruleset_maybe_add_feature() and - pango_ot_ruleset_maybe_add_features(). - </listitem> -</itemizedlist> + [method@PangoOT.Info.find_script] and [method@PangoOT.Info.find_language], -Because of the way return values of pango_ot_info_find_script() and -pango_ot_info_find_language() are ignored, this function automatically +* For found language-systems, if they have required feature index, + add that feature to the ruleset using [method@PangoOT.Ruleset.add_feature], + +* Remember found script and language indices for both table types, + and use them in future [method@PangoOT.Ruleset.maybe_add_feature] and + [method@PangoOT.Ruleset.maybe_add_features]. + +Because of the way return values of [method@PangoOT.Info.find_script] and +[method@PangoOT.Info.find_language] are ignored, this function automatically finds and uses the 'DFLT' script and the default language-system. - the newly allocated #PangoOTRuleset, which - should be freed with g_object_unref(). + the newly allocated `PangoOTRuleset` - a #PangoOTInfo. + a `PangoOTInfo` - a #PangoScript. + a `PangoScript` - a #PangoLanguage. + a `PangoLanguage` - Creates a new #PangoOTRuleset for the given OpenType infor and + Creates a new `PangoOTRuleset` for the given OpenType info and matching the given ruleset description. -This is a convenience function that calls pango_ot_ruleset_new_for() and -adds the static GSUB/GPOS features to the resulting ruleset, followed by -adding other features to both GSUB and GPOS. +This is a convenience function that calls [ctor@PangoOT.Ruleset.new_for] +and adds the static GSUB/GPOS features to the resulting ruleset, +followed by adding other features to both GSUB and GPOS. The static feature map members of @desc should be alive as long as @info is. - the newly allocated #PangoOTRuleset, which - should be freed with g_object_unref(). + the newly allocated `PangoOTRuleset` - a #PangoOTInfo. + a `PangoOTInfo` - a #PangoOTRulesetDescription. + a `PangoOTRulesetDescription` Returns a ruleset for the given OpenType info and ruleset -description. Rulesets are created on demand using -pango_ot_ruleset_new_from_description(). +description. + +Rulesets are created on demand using +[ctor@PangoOT.Ruleset.new_from_description]. The returned ruleset should not be modified or destroyed. The static feature map members of @desc should be alive as long as @info is. - the #PangoOTRuleset for @desc. This object will have -the same lifetime as @info. + the `PangoOTRuleset` for @desc. This object will have + the same lifetime as @info. - a #PangoOTInfo. + a `PangoOTInfo` - a #PangoOTRulesetDescription. + a `PangoOTRulesetDescription` @@ -613,21 +617,21 @@ the same lifetime as @info. - a #PangoOTRuleset. + a `PangoOTRuleset` - the table type to add a feature to. + the table type to add a feature to - the index of the feature to add. + the index of the feature to add - the property bit to use for this feature. Used to identify - the glyphs that this feature should be applied to, or - %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs. + the property bit to use for this feature. Used to + identify the glyphs that this feature should be applied to, or + %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs. @@ -635,142 +639,139 @@ the same lifetime as @info. Gets the number of GSUB and GPOS features in the ruleset. - Total number of features in the @ruleset. + Total number of features in the @ruleset - a #PangoOTRuleset. + a `PangoOTRuleset` - location to store number of - GSUB features, or %NULL. + location to store number of GSUB features - location to store number of - GPOS features, or %NULL. + location to store number of GPOS features This is a convenience function that first tries to find the feature -using pango_ot_info_find_feature() and the ruleset script and language -passed to pango_ot_ruleset_new_for(), -and if the feature is found, adds it to the ruleset. +using [method@PangoOT.Info.find_feature] and the ruleset script and +language passed to [ctor@PangoOT.Ruleset.new_for] and if the feature +is found, adds it to the ruleset. -If @ruleset was not created using pango_ot_ruleset_new_for(), this function -does nothing. +If @ruleset was not created using [ctor@PangoOT.Ruleset.new_for], +this function does nothing. %TRUE if the feature was found and added to ruleset, - %FALSE otherwise. + %FALSE otherwise - a #PangoOTRuleset. + a `PangoOTRuleset` - the table type to add a feature to. + the table type to add a feature to - the tag of the feature to add. + the tag of the feature to add - the property bit to use for this feature. Used to identify - the glyphs that this feature should be applied to, or - %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs. + the property bit to use for this feature. Used to + identify the glyphs that this feature should be applied to, or + %PANGO_OT_ALL_GLYPHS if it should be applied to all glyphs. - This is a convenience function that -for each feature in the feature map array @features -converts the feature name to a #PangoOTTag feature tag using PANGO_OT_TAG_MAKE() -and calls pango_ot_ruleset_maybe_add_feature() on it. + This is a convenience function that for each feature in the feature map +array @features converts the feature name to a `PangoOTTag` feature tag +using PANGO_OT_TAG_MAKE() and calls [method@PangoOT.Ruleset.maybe_add_feature] +on it. The number of features in @features that were found - and added to @ruleset. + and added to @ruleset - a #PangoOTRuleset. + a `PangoOTRuleset` - the table type to add features to. + the table type to add features to - array of feature name and property bits to add. + array of feature name and property bits to add - number of feature records in @features array. + number of feature records in @features array - Performs the OpenType GPOS positioning on @buffer using the features -in @ruleset + Performs the OpenType GPOS positioning on @buffer using +the features in @ruleset. - a #PangoOTRuleset. + a `PangoOTRuleset` - a #PangoOTBuffer. + a `PangoOTBuffer` - Performs the OpenType GSUB substitution on @buffer using the features -in @ruleset + Performs the OpenType GSUB substitution on @buffer using +the features in @ruleset. - a #PangoOTRuleset. + a `PangoOTRuleset` - a #PangoOTBuffer. + a `PangoOTBuffer` - The #PangoOTRuleset structure holds all the information needed -to build a complete #PangoOTRuleset from an OpenType font. + The `PangoOTRuleset` structure holds all the information needed +to build a complete `PangoOTRuleset` from an OpenType font. The main use of this struct is to act as the key for a per-font hash of rulesets. The user populates a ruleset description and gets the ruleset using pango_ot_ruleset_get_for_description() or create a new one using pango_ot_ruleset_new_from_description(). - a #PangoScript. + a `PangoScript` - a #PangoLanguage. + a `PangoLanguage` - static map of GSUB features, -or %NULL. + static map of GSUB features @@ -778,8 +779,7 @@ or %NULL. - static map of GPOS features, -or %NULL. + static map of GPOS features @@ -788,9 +788,8 @@ or %NULL. map of extra features to add to both -GSUB and GPOS, or %NULL. Unlike the static maps, this pointer -need not live beyond the life of function calls taking this -struct. + GSUB and GPOS. Unlike the static maps, this pointer need not + live beyond the life of function calls taking this struct. @@ -799,12 +798,12 @@ struct. Creates a copy of @desc, which should be freed with -pango_ot_ruleset_description_free(). Primarily used internally -by pango_ot_ruleset_get_for_description() to cache rulesets for -ruleset descriptions. +[method@PangoOT.RulesetDescription.free]. + +Primarily used internally by [func@PangoOT.Ruleset.get_for_description] +to cache rulesets for ruleset descriptions. - the newly allocated #PangoOTRulesetDescription, which - should be freed with pango_ot_ruleset_description_free(). + the newly allocated `PangoOTRulesetDescription` @@ -816,16 +815,18 @@ ruleset descriptions. Compares two ruleset descriptions for equality. + Two ruleset descriptions are considered equal if the rulesets -they describe are provably identical. This means that their -script, language, and all feature sets should be equal. For static feature -sets, the array addresses are compared directly, while for other -features, the list of features is compared one by one. -(Two ruleset descriptions may result in identical rulesets +they describe are provably identical. This means that their +script, language, and all feature sets should be equal. + +For static feature sets, the array addresses are compared directly, +while for other features, the list of features is compared one by +one.(Two ruleset descriptions may result in identical rulesets being created, but still compare %FALSE.) %TRUE if two ruleset descriptions are identical, - %FALSE otherwise. + %FALSE otherwise @@ -847,16 +848,16 @@ pango_ot_ruleset_description_copy(). - an allocated #PangoOTRulesetDescription + an allocated `PangoOTRulesetDescription` - Computes a hash of a #PangoOTRulesetDescription structure suitable + Computes a hash of a `PangoOTRulesetDescription` structure suitable to be used, for example, as an argument to g_hash_table_new(). - the hash value. + the hash value @@ -868,8 +869,8 @@ to be used, for example, as an argument to g_hash_table_new(). - Creates a #PangoOTTag from four characters. This is similar and -compatible with the <function>FT_MAKE_TAG()</function> macro from FreeType. + Creates a `PangoOTTag` from four characters. This is similar and +compatible with the FT_MAKE_TAG() macro from FreeType. First character. @@ -886,7 +887,7 @@ compatible with the <function>FT_MAKE_TAG()</function> macro from Fr - Creates a #PangoOTTag from a string. The string should be at least + Creates a `PangoOTTag` from a string. The string should be at least four characters long (pad with space characters if needed), and need not be nul-terminated. This is a convenience wrapper around PANGO_OT_TAG_MAKE(), but cannot be used in certain situations, for @@ -898,9 +899,9 @@ example, as a switch expression, as it dereferences pointers. - The <type>PangoOTTableType</type> enumeration values are used to + The PangoOTTableType enumeration values are used to identify the various OpenType tables in the -<function>pango_ot_info_*</function> functions. +pango_ot_info_… functions. The GSUB table. @@ -908,24 +909,17 @@ identify the various OpenType tables in the The GPOS table. - - Functions and macros in this section are used to implement -the OpenType Layout features and algorithms. - -They have been superseded by the harfbuzz library, and should -not be used anymore. - Finds the OpenType language-system tag best describing @language. - #PangoOTTag best matching @language or + `PangoOTTag` best matching @language or %PANGO_OT_TAG_DEFAULT_LANGUAGE if none found or if @language is %NULL. - A #PangoLanguage, or %NULL + A `PangoLanguage` @@ -938,55 +932,55 @@ The %PANGO_SCRIPT_COMMON, %PANGO_SCRIPT_INHERITED, and 'DFLT' script tag that is also defined as %PANGO_OT_TAG_DEFAULT_SCRIPT. -Note that multiple #PangoScript values may map to the same +Note that multiple `PangoScript` values may map to the same OpenType script tag. In particular, %PANGO_SCRIPT_HIRAGANA and %PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'. - #PangoOTTag corresponding to @script or + `PangoOTTag` corresponding to @script or %PANGO_OT_TAG_DEFAULT_SCRIPT if none found. - A #PangoScript + A `PangoScript` - Finds a #PangoLanguage corresponding to @language_tag. + Finds a `PangoLanguage` corresponding to @language_tag. - #PangoLanguage best matching @language_tag or -#PangoLanguage corresponding to the string "xx" if none found. + `PangoLanguage` best matching @language_tag or +`PangoLanguage` corresponding to the string "xx" if none found. - A #PangoOTTag OpenType language-system tag + A `PangoOTTag` OpenType language-system tag - Finds the #PangoScript corresponding to @script_tag. + Finds the `PangoScript` corresponding to @script_tag. The 'DFLT' script tag is mapped to %PANGO_SCRIPT_COMMON. Note that an OpenType script tag may correspond to multiple -#PangoScript values. In such cases, the #PangoScript value +`PangoScript` values. In such cases, the `PangoScript` value with the smallest value is returned. In particular, %PANGO_SCRIPT_HIRAGANA and %PANGO_SCRIPT_KATAKANA both map to the OT tag 'kana'. This function will return %PANGO_SCRIPT_HIRAGANA for 'kana'. - #PangoScript corresponding to @script_tag or + `PangoScript` corresponding to @script_tag or %PANGO_SCRIPT_UNKNOWN if none found. - A #PangoOTTag OpenType script tag + A `PangoOTTag` OpenType script tag diff --git a/PangoXft-1.0.gir b/PangoXft-1.0.gir index e7eaf4e..5cec93d 100644 --- a/PangoXft-1.0.gir +++ b/PangoXft-1.0.gir @@ -25,18 +25,17 @@ and/or use gtk-doc annotations. --> - #PangoXftFont is an implementation of #PangoFcFont using the Xft -library for rendering. It is used in conjunction with #PangoXftFontMap. + `PangoXftFont` is an implementation of `PangoFcFont` using the Xft +library for rendering. It is used in conjunction with `PangoXftFontMap`. Returns the `XftFont` of a font. - the `XftFont` associated to @font, - or %NULL if @font is %NULL. + the `XftFont` associated to @font - a #PangoFont. + a `PangoFont` @@ -49,15 +48,17 @@ library for rendering. It is used in conjunction with #PangoXftFontMap. - a #PangoFont. + a `PangoFont` Gets the glyph index for a given Unicode character -for @font. If you only want to determine -whether the font has the glyph, use pango_xft_font_has_char(). +for @font. + +If you only want to determine whether the font has +the glyph, use pango_xft_font_has_char(). Use pango_fc_font_get_glyph() instead. @@ -67,7 +68,7 @@ Use pango_fc_font_get_glyph() instead. - a #PangoFont for the Xft backend + a `PangoFont` for the Xft backend @@ -87,7 +88,7 @@ Use PANGO_GET_UNKNOWN_GLYPH() instead. - a #PangoFont. + a `PangoFont` @@ -106,7 +107,7 @@ Use pango_fc_font_has_char() instead. - a #PangoFont for the Xft backend + a `PangoFont` for the Xft backend @@ -127,7 +128,7 @@ Use pango_fc_font_lock_face() instead. - a #PangoFont. + a `PangoFont` @@ -142,16 +143,16 @@ Use pango_fc_font_unlock_face() instead. - a #PangoFont. + a `PangoFont` - #PangoXftFontMap is an implementation of #PangoFcFontMap suitable for + `PangoXftFontMap` is an implementation of `PangoFcFontMap` suitable for the Xft library as the renderer. It is used in to create fonts of -type #PangoXftFont. +type `PangoXftFont`. @@ -196,17 +197,18 @@ type #PangoXftFont. - #PangoXftRenderer is a subclass of #PangoRenderer used for rendering + `PangoXftRenderer` is a subclass of `PangoRenderer` used for rendering with Pango's Xft backend. It can be used directly, or it can be further subclassed to modify exactly how drawing of individual elements occurs. - Create a new #PangoXftRenderer to allow rendering Pango objects -with the Xft library. You must call pango_xft_renderer_set_draw() before + Create a new `PangoXftRenderer` to allow rendering Pango objects +with the Xft library. + +You must call pango_xft_renderer_set_draw() before using the renderer. - the newly created #PangoXftRenderer, which should - be freed with g_object_unref(). + the newly created `PangoXftRenderer` @@ -259,13 +261,13 @@ using the renderer. - Sets the default foreground color for a #XftRenderer. + Sets the default foreground color for a XftRenderer. - a #XftRenderer + a XftRenderer @@ -275,18 +277,18 @@ using the renderer. - Sets the #XftDraw object that the renderer is drawing to. + Sets the XftDraw object that the renderer is drawing to. The renderer must not be currently active. - a #PangoXftRenderer + a `PangoXftRenderer` - a #XftDraw + a XftDraw @@ -314,7 +316,7 @@ The renderer must not be currently active. - The class structure for #PangoXftRenderer + The class structure for `PangoXftRenderer` @@ -379,12 +381,12 @@ The renderer must not be currently active. - Retrieves a #PangoContext appropriate for rendering with + Retrieves a `PangoContext` appropriate for rendering with Xft fonts on the given screen of the given display. Use pango_xft_get_font_map() followed by pango_font_map_create_context() instead. - the new #PangoContext. + the new `PangoContext`. @@ -399,11 +401,11 @@ pango_font_map_create_context() instead. - Returns the #PangoXftFontMap for the given display and screen. + Returns the `PangoXftFontMap` for the given display and screen. The fontmap is owned by Pango and will be valid until the display is closed. - a #PangoFontMap object, owned by Pango. + a `PangoFontMap` object, owned by Pango. @@ -418,7 +420,7 @@ the display is closed. - Renders a #PangoGlyphString onto an Xrender <type>Picture</type> object. + Renders a `PangoGlyphString` onto an Xrender Picture object. @@ -454,13 +456,13 @@ the display is closed. - Renders a #PangoGlyphString onto an <type>XftDraw</type> object wrapping an X drawable. + Renders a `PangoGlyphString` onto an XftDraw object wrapping an X drawable. - the <type>XftDraw</type> object. + the XftDraw object. @@ -486,22 +488,22 @@ the display is closed. - Render a #PangoLayout onto a #XftDraw + Render a `PangoLayout` onto a XftDraw - an #XftDraw + an XftDraw the foreground color in which to draw the layout - (may be overridden by color attributes) + (may be overridden by color attributes) - a #PangoLayout + a `PangoLayout` @@ -515,22 +517,22 @@ the display is closed. - Render a #PangoLayoutLine onto a #XftDraw + Render a `PangoLayoutLine` onto a XftDraw - an #XftDraw + an XftDraw the foreground color in which to draw the layout line - (may be overridden by color attributes) + (may be overridden by color attributes) - a #PangoLayoutLine + a `PangoLayoutLine` @@ -544,18 +546,20 @@ the display is closed. - Renders a #PangoGlyphString onto a #XftDraw, possibly + Renders a `PangoGlyphString` onto a XftDraw, possibly transforming the layed-out coordinates through a transformation -matrix. Note that the transformation matrix for @font is not +matrix. + +Note that the transformation matrix for @font is not changed, so to produce correct rendering results, the @font -must have been loaded using a #PangoContext with an identical +must have been loaded using a `PangoContext` with an identical transformation matrix to that passed in to this function. - an #XftDraw + an XftDraw @@ -563,8 +567,7 @@ transformation matrix to that passed in to this function. - a #PangoMatrix, or %NULL to use an identity - transformation + a `PangoMatrix` @@ -577,21 +580,23 @@ transformation matrix to that passed in to this function. the x position of the start of the string (in Pango - units in user space coordinates) + units in user space coordinates) the y position of the baseline (in Pango units - in user space coordinates) + in user space coordinates) - + Sets a function that will be called to do final configuration substitution on a #FcPattern before it is used to load the font. This function can be used to do things like set hinting and antialiasing options. + Use pango_fc_font_map_set_default_substitute() +instead. @@ -638,12 +643,14 @@ without needing to call this function. - + Call this function any time the results of the default substitution function set with pango_xft_set_default_substitute() change. That is, if your substitution function will return different results for the same input pattern, you must call this function. + Use pango_fc_font_map_substitute_changed() +instead. @@ -658,31 +665,5 @@ results for the same input pattern, you must call this function. - - The Xft library is a library for displaying fonts on the X window -system; internally it uses the fontconfig library to locate font -files, and the FreeType library to load and render fonts. The -Xft backend is the recommended Pango font backend for screen -display with X. (The <link linkend="pango-Cairo-Rendering">Cairo back end</link> is another possibility.) - -Using the Xft backend is generally straightforward; -pango_xft_get_context() creates a context for a specified display -and screen. You can then create a #PangoLayout with that context -and render it with pango_xft_render_layout(). At a more advanced -level, the low-level fontconfig options used for rendering fonts -can be affected using pango_xft_set_default_substitute(), and -pango_xft_substitute_changed(). - -A range of functions for drawing pieces of a layout, such as -individual layout lines and glyphs strings are provided. You can also -directly create a #PangoXftRenderer. Finally, in some advanced cases, it -is useful to derive from #PangoXftRenderer. Deriving from -#PangoXftRenderer is useful for two reasons. One reason is be to -support custom attributes by overriding #PangoRendererClass virtual -functions like 'prepare_run' or 'draw_shape'. The reason is to -customize exactly how the final bits are drawn to the destination by -overriding the #PangoXftRendererClass virtual functions -'composite_glyphs' and 'composite_trapezoids'. - diff --git a/dl.sh b/dl.sh index 98e543f..887c3d3 100755 --- a/dl.sh +++ b/dl.sh @@ -1,22 +1,14 @@ #!/bin/bash set -e -VER="groovy" - -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libatk1.0-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libgirepository1.0-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libpango1.0-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libgdk-pixbuf2.0-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libgtk-3-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libgtksourceview-3.0-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libsecret-1-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libvte-2.91-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libjavascriptcoregtk-4.0-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libsoup2.4-dev/download -./gir-dl.sh https://packages.ubuntu.com/$VER/amd64/libwebkit2gtk-4.0-dev/download - -# version 4 -./gir-dl.sh https://packages.debian.org/experimental/amd64/libgtk-4-dev/download http.us.debian.org +./gir-dl.sh https://packages.debian.org/unstable/amd64/libatk1.0-dev/download http.us.debian.org +./gir-dl.sh https://packages.debian.org/unstable/amd64/libgirepository1.0-dev/download http.us.debian.org +./gir-dl.sh https://packages.debian.org/unstable/amd64/libgraphene-1.0-dev/download http.us.debian.org +./gir-dl.sh https://packages.debian.org/unstable/amd64/libgdk-pixbuf-2.0-dev/download http.us.debian.org +./gir-dl.sh https://packages.debian.org/unstable/amd64/libgtk-3-dev/download http.us.debian.org +./gir-dl.sh https://packages.debian.org/unstable/amd64/libgtk-4-dev/download http.us.debian.org +./gir-dl.sh https://packages.debian.org/unstable/amd64/libharfbuzz-dev/download http.us.debian.org +./gir-dl.sh https://packages.debian.org/unstable/amd64/libpango1.0-dev/download http.us.debian.org ./reformat.sh ./fix.sh