diff options
author | Rico Tzschichholz <ricotz@ubuntu.com> | 2015-02-05 22:40:15 +0100 |
---|---|---|
committer | Rico Tzschichholz <ricotz@ubuntu.com> | 2015-02-05 22:40:15 +0100 |
commit | 2b15e2ffa4ecb4d3bce009c7c91d946f9d136bdb (patch) | |
tree | a486e82a4d23b37d958655e9389d41da4bac97d5 /gir | |
parent | 63f974a49fa4fe2fda839e20193ca96518496b70 (diff) | |
download | gobject-introspection-2b15e2ffa4ecb4d3bce009c7c91d946f9d136bdb.tar.gz |
Update glib annotations from git master
Diffstat (limited to 'gir')
-rw-r--r-- | gir/gio-2.0.c | 645 | ||||
-rw-r--r-- | gir/glib-2.0.c | 235 | ||||
-rw-r--r-- | gir/gobject-2.0.c | 974 |
3 files changed, 1645 insertions, 209 deletions
diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c index b4626165..bf3e229d 100644 --- a/gir/gio-2.0.c +++ b/gir/gio-2.0.c @@ -3,6 +3,14 @@ /************************************************************/ /** + * GAction: + * + * #GAction is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GAction:enabled: * * If @action is currently enabled. @@ -90,6 +98,14 @@ /** + * GActionGroup: + * + * #GActionGroup is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GActionGroup::action-added: * @action_group: the #GActionGroup that changed * @action_name: the name of the action in @action_group @@ -181,6 +197,14 @@ /** + * GActionMap: + * + * #GActionMap is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GActionMapInterface: * @lookup_action: the virtual function pointer for g_action_map_lookup_action() * @add_action: the virtual function pointer for g_action_map_add_action() @@ -203,6 +227,53 @@ /** + * GAppInfoMonitor::changed: + * + * Signal emitted when the app info database for changes (ie: newly installed + * or removed applications). + */ + + +/** + * GAppLaunchContext::launch-failed: + * @context: the object emitting the signal + * @startup_notify_id: the startup notification id for the failed launch + * + * The ::launch-failed signal is emitted when a #GAppInfo launch + * fails. The startup notification id is provided, so that the launcher + * can cancel the startup notification. + * + * Since: 2.36 + */ + + +/** + * GAppLaunchContext::launched: + * @context: the object emitting the signal + * @info: the #GAppInfo that was just launched + * @platform_data: additional platform-specific data for this launch + * + * The ::launched signal is emitted when a #GAppInfo is successfully + * launched. The @platform_data is an GVariant dictionary mapping + * strings to variants (ie a{sv}), which contains additional, + * platform-specific data about this launch. On UNIX, at least the + * "pid" and "startup-notification-id" keys will be present. + * + * Since: 2.36 + */ + + +/** + * GApplication: + * + * #GApplication is an opaque data structure and can only be accessed + * using the following functions. + * + * Since: 2.28 + */ + + +/** * GApplication::activate: * @application: the application * @@ -350,6 +421,8 @@ * @dbus_unregister: invoked locally during unregistration, if the application * is using its D-Bus backend. Use this to undo anything done by the * @dbus_register vfunc. Since: 2.34 + * @handle_local_options: invoked locally after the parsing of the commandline + * options has occurred. * * Virtual function table for #GApplication. * @@ -358,6 +431,14 @@ /** + * GApplicationCommandLine: + * + * #GApplicationCommandLine is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GApplicationCommandLineClass: * * The #GApplicationCommandLineClass-struct @@ -459,6 +540,14 @@ /** + * GDBusActionGroup: + * + * #GDBusActionGroup is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GDBusAuthMechanism:credentials: * * If authenticating as a server, this property contains the @@ -734,6 +823,14 @@ /** + * GDBusMenuModel: + * + * #GDBusMenuModel is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GDBusMessage: * * The #GDBusMessage structure contains only private data and should @@ -772,6 +869,14 @@ /** + * GDBusObject: + * + * #GDBusObject is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GDBusObject::interface-added: * @object: The #GDBusObject emitting the signal. * @interface: The #GDBusInterface that was added. @@ -794,6 +899,14 @@ /** + * GDBusObjectManager: + * + * #GDBusObjectManager is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GDBusObjectManager::interface-added: * @manager: The #GDBusObjectManager emitting the signal. * @object: The #GDBusObject on which an interface was added. @@ -1342,6 +1455,14 @@ /** + * GDesktopAppInfoLookup: + * + * #GDesktopAppInfoLookup is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GDrive::changed: * @drive: a #GDrive. * @@ -1412,6 +1533,22 @@ /** + * GIOExtension: + * + * #GIOExtension is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** + * GIOExtensionPoint: + * + * #GIOExtensionPoint is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GIOModuleScope: * * Represents a scope for loading IO modules. A scope can be used for blocking @@ -1568,6 +1705,60 @@ /** + * GListModel: + * + * #GListModel is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** + * GListModel::items-changed: + * @list: the #GListModel that changed + * @position: the position at which @list changed + * @removed: the number of items removed + * @added: the number of items added + * + * This signal is emitted whenever items were added or removed to + * @list. At @position, @removed items were removed and @added items + * were added in their place. + * + * Since: 2.44 + */ + + +/** + * GListModelInterface: + * @g_iface: parent #GTypeInterface + * @get_item_type: the virtual function pointer for g_list_model_get_item_type() + * @get_n_items: the virtual function pointer for g_list_model_get_n_items() + * @get_item: the virtual function pointer for g_list_model_get_item() + * + * The virtual function table for #GListModel. + * + * Since: 2.44 + */ + + +/** + * GListStore: + * + * #GListStore is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** + * GListStore:item-type: + * + * The type of items contained in this list store. Items must be + * subclasses of #GObject. + * + * Since: 2.44 + */ + + +/** * GMemoryOutputStream:data: * * Pointer to buffer where data will be written. @@ -1946,6 +2137,23 @@ /** + * GNetworkMonitorInterface: + * @g_iface: The parent interface. + * @network_changed: the virtual function pointer for the + * GNetworkMonitor::network-changed signal. + * @can_reach: the virtual function pointer for g_network_monitor_can_reach() + * @can_reach_async: the virtual function pointer for + * g_network_monitor_can_reach_async() + * @can_reach_finish: the virtual function pointer for + * g_network_monitor_can_reach_finish() + * + * The virtual function table for #GNetworkMonitor. + * + * Since: 2.32 + */ + + +/** * GNetworkService: * * A #GSocketConnectable for resolving a SRV record and connecting to @@ -2108,6 +2316,15 @@ /** + * GProxyAddressClass: + * + * Class structure for #GProxyAddress. + * + * Since: 2.26 + */ + + +/** * GProxyAddressEnumerator:default-port: * * The default port to use if #GProxyAddressEnumerator:uri does not @@ -2127,6 +2344,28 @@ /** + * GProxyResolverInterface: + * @g_iface: The parent interface. + * @is_supported: the virtual function pointer for g_proxy_resolver_is_supported() + * @lookup: the virtual function pointer for g_proxy_resolver_lookup() + * @lookup_async: the virtual function pointer for + * g_proxy_resolver_lookup_async() + * @lookup_finish: the virtual function pointer for + * g_proxy_resolver_lookup_finish() + * + * The virtual function table for #GProxyResolver. + */ + + +/** + * GRemoteActionGroup: + * + * #GRemoteActionGroup is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GRemoteActionGroupInterface: * @activate_action_full: the virtual function pointer for g_remote_action_group_activate_action_full() * @change_action_state_full: the virtual function pointer for g_remote_action_group_change_action_state_full() @@ -2155,6 +2394,14 @@ /** + * GSettings: + * + * #GSettings is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GSettings::change-event: * @settings: the object on which the signal was emitted * @keys: (array length=n_keys) (element-type GQuark) (allow-none): @@ -2322,6 +2569,14 @@ /** + * GSettingsSchemaKey: + * + * #GSettingsSchemaKey is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GSettingsSchemaSource: * * This is an opaque structure type. You may not access it directly. @@ -2331,6 +2586,14 @@ /** + * GSimpleAction: + * + * #GSimpleAction is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GSimpleAction::activate: * @simple: the #GSimpleAction * @parameter: (allow-none): the parameter to the activation @@ -2656,6 +2919,14 @@ /** + * GStaticResource: + * + * #GStaticResource is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GTask: * * The opaque object representing a synchronous or asynchronous task @@ -2691,6 +2962,14 @@ /** + * GTcpWrapperConnection: + * + * #GTcpWrapperConnection is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GTestDBus: * * The #GTestDBus structure contains only private data and @@ -3178,6 +3457,14 @@ /** + * GUnixConnection: + * + * #GUnixConnection is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GUnixCredentialsMessage:credentials: * * The credentials stored in the message. @@ -3187,6 +3474,22 @@ /** + * GUnixFDList: + * + * #GUnixFDList is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** + * GUnixFDMessage: + * + * #GUnixFDMessage is an opaque data structure and can only be accessed + * using the following functions. + */ + + +/** * GUnixInputStream:close-fd: * * Whether to close the file descriptor when the stream is closed. @@ -5698,6 +6001,77 @@ /** + * SECTION:glistmodel + * @title: GListModel + * @short_description: An interface describing a dynamic list of objects + * @include: gio/gio.h + * @see_also: #GListStore + * + * #GListModel is an interface that represents a mutable list of + * #GObjects. Its main intention is as a model for various widgets in + * user interfaces, such as list views, but it can also be used as a + * convenient method of returning lists of data, with support for + * updates. + * + * Each object in the list may also report changes in itself via some + * mechanism (normally the #GObject::notify signal). Taken together + * with the #GListModel::items-changed signal, this provides for a list + * that can change its membership, and in which the members can change + * their individual properties. + * + * A good example would be the list of visible wireless network access + * points, where each access point can report dynamic properties such as + * signal strength. + * + * It is important to note that the #GListModel itself does not report + * changes to the individual items. It only reports changes to the list + * membership. If you want to observe changes to the objects themselves + * then you need to connect signals to the objects that you are + * interested in. + * + * All items in a #GListModel are of (or derived from) the same type. + * g_list_model_get_item_type() returns that type. The type may be an + * interface, in which case all objects in the list must implement it. + * + * The semantics are close to that of an array: + * g_list_model_get_length() returns the number of items in the list and + * g_list_model_get_item() returns an item at a (0-based) position. In + * order to allow implementations to calculate the list length lazily, + * you can also iterate over items: starting from 0, repeatedly call + * g_list_model_get_item() until it returns %NULL. + * + * An implementation may create objects lazily, but must take care to + * return the same object for a given position until all references to + * it are gone. + * + * On the other side, a consumer is expected only to hold references on + * objects that are currently "user visible", in order to faciliate the + * maximum level of laziness in the implementation of the list and to + * reduce the required number of signal connections at a given time. + * + * This interface is intended only to be used from a single thread. The + * thread in which it is appropriate to use it depends on the particular + * implementation, but typically it will be from the thread that owns + * the [thread-default main context][g-main-context-push-thread-default] + * in effect at the time that the model was created. + */ + + +/** + * SECTION:gliststore + * @title: GListStore + * @short_description: A simple implementation of #GListModel + * @include: gio/gio.h + * + * #GListStore is a simple implementation of #GListModel that stores all + * items in memory. + * + * It provides insertions, deletions, and lookups in logarithmic time + * with a fast path for the common case of iterating the list linearly. + */ + + +/** * SECTION:gloadableicon * @short_description: Loadable Icons * @include: gio/gio.h @@ -8023,6 +8397,10 @@ * @title: GTlsBackend * @short_description: TLS backend implementation * @include: gio/gio.h + * + * TLS (Transport Layer Security, aka SSL) backend + * + * Since: 2.28 */ @@ -10138,16 +10516,6 @@ /** - * _g_win32_mount_new: - * @volume_monitor: a #GVolumeMonitor. - * @path: a win32 path. - * @volume: usually NULL - * - * Returns: a #GWin32Mount for the given win32 path. - */ - - -/** * g_action_activate: * @action: a #GAction * @parameter: (allow-none): the parameter to the activation @@ -25367,6 +25735,218 @@ /** + * g_list_model_get_item: (skip) + * @list: a #GListModel + * @position: the position of the item to fetch + * + * Get the item at @position. If @position is greater than the number of + * items in @list, %NULL is returned. + * + * %NULL is never returned for an index that is smaller than the length + * of the list. See g_list_model_get_n_items(). + * + * Returns: (transfer full) (nullable) (type GObject): the item at @position. + * Since: 2.44 + */ + + +/** + * g_list_model_get_item_type: + * @list: a #GListModel + * + * Gets the type of the items in @list. All items returned from + * g_list_model_get_type() are of that type or a subtype, or are an + * implementation of that interface. + * + * The item type of a #GListModel can not change during the life of the + * model. + * + * Returns: the #GType of the items contained in @list. + * Since: 2.44 + */ + + +/** + * g_list_model_get_n_items: + * @list: a #GListModel + * + * Gets the number of items in @list. + * + * Depending on the model implementation, calling this function may be + * less efficient than iterating the list with increasing values for + * @position until g_list_model_get_item() returns %NULL. + * + * Returns: the number of items in @list. + * Since: 2.44 + */ + + +/** + * g_list_model_get_object: (rename-to g_list_model_get_item) + * @list: a #GListModel + * @position: the position of the item to fetch + * + * Get the item at @position. If @position is greater than the number of + * items in @list, %NULL is returned. + * + * %NULL is never returned for an index that is smaller than the length + * of the list. See g_list_model_get_n_items(). + * + * Returns: (transfer full) (nullable): the object at @position. + * Since: 2.44 + */ + + +/** + * g_list_model_items_changed: + * @list: a #GListModel + * @position: the position at which @list changed + * @removed: the number of items removed + * @added: the number of items added + * + * Emits the #GListModel::items-changed signal on @list. + * + * This function should only be called by classes implementing + * #GListModel. It has to be called after the internal representation + * of @list has been updated, because handlers connected to this signal + * might query the new state of the list. + * + * Implementations must only make changes to the model (as visible to + * its consumer) in places that will not cause problems for that + * consumer. For models that are driven directly by a write API (such + * as #GListStore), changes can be reported in response to uses of that + * API. For models that represent remote data, changes should only be + * made from a fresh mainloop dispatch. It is particularly not + * permitted to make changes in response to a call to the #GListModel + * consumer API. + * + * Stated another way: in general, it is assumed that code making a + * series of accesses to the model via the API, without returning to the + * mainloop, and without calling other code, will continue to view the + * same contents of the model. + * + * Since: 2.44 + */ + + +/** + * g_list_store_append: + * @store: a #GListStore + * @item: the new item + * + * Appends @item to @store. @item must be of type #GListStore:item-type. + * + * This function takes a ref on @item. + * + * Use g_list_store_splice() to append multiple items at the same time + * efficiently. + * + * Since: 2.44 + */ + + +/** + * g_list_store_insert: + * @store: a #GListStore + * @position: the position at which to insert the new item + * @item: the new item + * + * Inserts @item into @store at @position. @item must be of type + * #GListStore:item-type or derived from it. @position must be smaller + * than the length of the list, or equal to it to append. + * + * This function takes a ref on @item. + * + * Use g_list_store_splice() to insert multiple items at the same time + * efficiently. + * + * Since: 2.44 + */ + + +/** + * g_list_store_insert_sorted: + * @store: a #GListStore + * @item: the new item + * + * Inserts @item into @store at a position to be determined by the + * @compare_func. + * + * The list must already be sorted before calling this function or the + * result is undefined. Usually you would approach this by only ever + * inserting items by way of this function. + * + * This function takes a ref on @item. + * + * Returns: the position at which @item was inserted + * Since: 2.44 + */ + + +/** + * g_list_store_new: + * @item_type: the #GType of items in the list + * + * Creates a new #GListStore with items of type @item_type. @item_type + * must be a subclass of #GObject. + * + * Returns: a new #GListStore + * Since: 2.44 + */ + + +/** + * g_list_store_remove: + * @store: a #GListStore + * @position: the position of the item that is to be removed + * + * Removes the item from @store that is at @position. @position must be + * smaller than the current length of the list. + * + * Use g_list_store_splice() to remove multiple items at the same time + * efficiently. + * + * Since: 2.44 + */ + + +/** + * g_list_store_remove_all: + * @store: a #GListStore + * + * Removes all items from @store. + * + * Since: 2.44 + */ + + +/** + * g_list_store_splice: + * @store: a #GListStore + * @position: the position at which to make the change + * @n_removals: the number of items to remove + * @additions: (array length=n_additions): the items to add + * @n_additions: the number of items to add + * + * Changes @store by removing @n_removals items and adding @n_additions + * items to it. @additions must contain @n_additions items of type + * #GListStore:item-type. %NULL is not permitted. + * + * This function is more efficient than g_list_store_insert() and + * g_list_store_remove(), because it only emits + * #GListModel::items-changed once for the change. + * + * This function takes a ref on each item in @additions. + * + * The parameters @position and @n_removals must be correct (ie: + * @position + @n_removals must be less than or equal to the length of + * the list at the time this function is called). + * + * Since: 2.44 + */ + + +/** * g_loadable_icon_load: * @icon: a #GLoadableIcon. * @size: an integer. @@ -30466,6 +31046,8 @@ /** * g_settings_list_relocatable_schemas: * + * <!-- --> + * * Returns: (element-type utf8) (transfer none): a list of relocatable * #GSettings schemas that are available. The list must not be * modified or freed. @@ -30477,6 +31059,8 @@ /** * g_settings_list_schemas: * + * <!-- --> + * * Returns: (element-type utf8) (transfer none): a list of #GSettings * schemas that are available. The list must not be modified or * freed. @@ -30524,7 +31108,7 @@ * backend, and a #GMainContext to which signals are dispatched. * * This constructor therefore gives you full control over constructing - * #GSettings instances. The first 4 parameters are given directly as + * #GSettings instances. The first 3 parameters are given directly as * @schema, @backend and @path, and the main context is taken from the * thread-default (as per g_settings_new()). * @@ -30736,6 +31320,17 @@ /** + * g_settings_schema_key_get_name: + * @key: a #GSettingsSchemaKey + * + * Gets the name of @key. + * + * Returns: the name of @key. + * Since: 2.44 + */ + + +/** * g_settings_schema_key_get_range: * @key: a #GSettingsSchemaKey * @@ -30853,6 +31448,20 @@ /** + * g_settings_schema_list_children: + * @schema: a #GSettingsSchema + * + * Gets the list of children in @schema. + * + * You should free the return value with g_strfreev() when you are done + * with it. + * + * Returns: (transfer full) (element-type utf8): a list of the children on @settings + * Since: 2.44 + */ + + +/** * g_settings_schema_ref: * @schema: a #GSettingsSchema * @@ -31379,6 +31988,20 @@ /** + * g_simple_action_set_state_hint: + * @simple: a #GSimpleAction + * @state_hint: (allow-none): a #GVariant representing the state hint + * + * Sets the state hint for the action. + * + * See g_action_get_state_hint() for more information about + * action state hints. + * + * Since: 2.44 + */ + + +/** * g_simple_async_report_error_in_idle: (skip) * @object: (allow-none): a #GObject, or %NULL. * @callback: a #GAsyncReadyCallback. diff --git a/gir/glib-2.0.c b/gir/glib-2.0.c index d2d0e45d..95c2f118 100644 --- a/gir/glib-2.0.c +++ b/gir/glib-2.0.c @@ -2855,6 +2855,87 @@ /** + * G_DEFINE_AUTOPTR_CLEANUP_FUNC: + * @TypeName: a type name to define a g_autoptr() cleanup function for + * @func: the cleanup function + * + * Defines the appropriate cleanup function for a pointer type. + * + * The function will not be called if the variable to be cleaned up + * contains %NULL. + * + * This will typically be the _free() or _unref() function for the given + * type. + * + * With this definition, it will be possible to use g_autoptr() with + * @TypeName. + * + * |[ + * G_DEFINE_AUTOPTR_CLEANUP_FUNC(GObject, g_object_unref) + * ]| + * + * This macro should be used unconditionally; it is a no-op on compilers + * where cleanup is not supported. + * + * Since: 2.44 + */ + + +/** + * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC: + * @TypeName: a type name to define a g_auto() cleanup function for + * @func: the clear function + * + * Defines the appropriate cleanup function for a type. + * + * This will typically be the _clear() function for the given type. + * + * With this definition, it will be possible to use g_auto() with + * @TypeName. + * + * |[ + * G_DEFINE_AUTO_CLEANUP_CLEAR_FUNC(GQueue, g_queue_clear) + * ]| + * + * This macro should be used unconditionally; it is a no-op on compilers + * where cleanup is not supported. + * + * Since: 2.44 + */ + + +/** + * G_DEFINE_AUTO_CLEANUP_FREE_FUNC: + * @TypeName: a type name to define a g_auto() cleanup function for + * @func: the free function + * @none: the "none" value for the type + * + * Defines the appropriate cleanup function for a type. + * + * With this definition, it will be possible to use g_auto() with + * @TypeName. + * + * This function will be rarely used. It is used with pointer-based + * typedefs and non-pointer types where the value of the variable + * represents a resource that must be freed. Two examples are #GStrv + * and file descriptors. + * + * @none specifies the "none" value for the type in question. It is + * probably something like %NULL or -1. If the variable is found to + * contain this value then the free function will not be called. + * + * |[ + * G_DEFINE_AUTO_CLEANUP_FREE_FUNC(GStrv, g_strfreev, NULL) + * ]| + * + * This macro should be used unconditionally; it is a no-op on compilers + * where cleanup is not supported. + * + * Since: 2.44 + */ + + +/** * G_DEFINE_QUARK: * @QN: the name to return a #GQuark for * @q_n: prefix for the function name @@ -8410,7 +8491,8 @@ * the string back using g_ascii_strtod() gives the same machine-number * (on machines with IEEE compatible 64bit doubles). It is * guaranteed that the size of the resulting string will never - * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes. + * be larger than @G_ASCII_DTOSTR_BUF_SIZE bytes, including the terminating + * nul character, which is always added. * * Returns: The pointer to the buffer with the converted string. */ @@ -8429,6 +8511,8 @@ * a printf()-style format string. Allowed conversion * specifiers are 'e', 'E', 'f', 'F', 'g' and 'G'. * + * The returned buffer is guaranteed to be nul-terminated. + * * If you just want to want to serialize the value into a * string, use g_ascii_dtostr(). * @@ -9770,6 +9854,118 @@ /** + * g_auto: + * @TypeName: a supported variable type + * + * Helper to declare a variable with automatic cleanup. + * + * The variable is cleaned up in a way appropriate to its type when the + * variable goes out of scope. The type must support this. + * + * This feature is only supported on GCC and clang. This macro is not + * defined on other compilers and should not be used in programs that + * are intended to be portable to those compilers. + * + * This is meant to be used with stack-allocated structures and + * non-pointer types. For the (more commonly used) pointer version, see + * g_autoptr(). + * + * This macro can be used to avoid having to do explicit cleanups of + * local variables when exiting functions. It often vastly simplifies + * handling of error conditions, removing the need for various tricks + * such as 'goto out' or repeating of cleanup code. It is also helpful + * for non-error cases. + * + * Consider the following example: + * + * |[ + * GVariant * + * my_func(void) + * { + * g_auto(GQueue) queue = G_QUEUE_INIT; + * g_auto(GVariantBuilder) builder; + * + * g_variant_builder_init (&builder, G_VARIANT_TYPE_VARDICT); + * + * ... + * + * if (error_condition) + * return NULL; + * + * ... + * + * return g_variant_builder_end (&builder); + * } + * ]| + * + * You must initialise the variable in some way -- either by use of an + * initialiser or by ensuring that an _init function will be called on + * it unconditionally before it goes out of scope. + * + * Since: 2.44 + */ + + +/** + * g_autoptr: + * @TypeName: a supported variable type + * + * Helper to declare a pointer variable with automatic cleanup. + * + * The variable is cleaned up in a way appropriate to its type when the + * variable goes out of scope. The type must support this. + * + * This feature is only supported on GCC and clang. This macro is not + * defined on other compilers and should not be used in programs that + * are intended to be portable to those compilers. + * + * This is meant to be used to declare pointers to types with cleanup + * functions. The type of the variable is a pointer to @TypeName. You + * must not add your own '*'. + * + * This macro can be used to avoid having to do explicit cleanups of + * local variables when exiting functions. It often vastly simplifies + * handling of error conditions, removing the need for various tricks + * such as 'goto out' or repeating of cleanup code. It is also helpful + * for non-error cases. + * + * Consider the following example: + * + * |[ + * gboolean + * check_exists(GVariant *dict) + * { + * g_autoptr(GVariant) dirname; + * g_autoptr(GVariant) basename = NULL; + * g_autoptr(gchar) path = NULL; + * + * dirname = g_variant_lookup_value (dict, "dirname", G_VARIANT_TYPE_STRING); + * + * if (dirname == NULL) + * return FALSE; + * + * basename = g_variant_lookup_value (dict, "basename", G_VARIANT_TYPE_STRING); + * + * if (basename == NULL) + * return FALSE; + * + * path = g_build_filename (g_variant_get_string (dirname, NULL), + * g_variant_get_string (basename, NULL), + * NULL); + * + * return g_access (path, R_OK) == 0; + * } + * ]| + * + * You must initialise the variable in some way -- either by use of an + * initialiser or by ensuring that it is assigned to unconditionally + * before it goes out of scope. + * + * Since: 2.44 + */ + + +/** * g_base64_decode: * @text: zero-terminated string with base64 text to decode * @out_len: (out): The length of the decoded data is written here @@ -29710,7 +29906,7 @@ /** * g_thread_self: * - * This functions returns the #GThread corresponding to the + * This function returns the #GThread corresponding to the * current thread. Note that this function does not increase * the reference count of the returned struct. * @@ -35382,6 +35578,32 @@ /** + * g_win32_check_windows_version: + * @major: major version of Windows + * @minor: minor version of Windows + * @spver: Windows Service Pack Level, 0 if none + * @os_type: Type of Windows OS + * + * Returns whether the version of the Windows operating system the + * code is running on is at least the specified major, minor and + * service pack versions. See MSDN documentation for the Operating + * System Version. Software that needs even more detailed version and + * feature information should use the Win32 API VerifyVersionInfo() + * directly. + * + * Successive calls of this function can be used for enabling or + * disabling features at run-time for a range of Windows versions, + * as per the VerifyVersionInfo() API documentation. + * + * Returns: %TRUE if the Windows Version is the same or greater than + * the specified major, minor and service pack versions, and + * whether the running Windows is a workstation or server edition + * of Windows, if specifically specified. + * Since: 2.44 + */ + + +/** * g_win32_error_message: * @error: error code. * @@ -35560,6 +35782,9 @@ /** * g_win32_get_windows_version: * + * This function is deprecated. Use + * g_win32_check_windows_version() instead. + * * Returns version information for the Windows operating system the * code is running on. See MSDN documentation for the GetVersion() * function. To summarize, the most significant bit is one on Win9x, @@ -35571,7 +35796,11 @@ * GetVersionEx() and VerifyVersionInfo(). * * Returns: The version information. - * Since: 2.6 + * Deprecated: 2.44: Be aware that for Windows 8.1 and Windows Server + * 2012 R2 and later, this will return 62 unless the application is + * manifested for Windows 8.1/Windows Server 2012 R2, for example. + * MSDN stated that GetVersion(), which is used here, is subject to + * further change or removal after Windows 8.1. */ diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index c07d98a4..676c4060 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -815,18 +815,82 @@ /** + * g_cclosure_marshal_BOOLEAN__BOXED_BOXED: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with handlers that + * take two boxed pointers as arguments and return a boolean. If you + * have such a signal, you will probably also need to use an + * accumulator, such as g_signal_accumulator_true_handled(). + */ + + +/** + * g_cclosure_marshal_BOOLEAN__BOXED_BOXEDv: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. + * + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). + */ + + +/** * g_cclosure_marshal_BOOLEAN__FLAGS: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with handlers that + * take a flags type as an argument and return a boolean. If you have + * such a signal, you will probably also need to use an accumulator, + * such as g_signal_accumulator_true_handled(). + */ + + +/** + * g_cclosure_marshal_BOOLEAN__FLAGSv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue which can store the returned #gboolean - * @n_param_values: 2 - * @param_values: a #GValue array holding instance and arg1 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter - * denotes a flags type. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS(). */ @@ -848,311 +912,802 @@ /** + * g_cclosure_marshal_BOOL__BOXED_BOXED: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * An old alias for g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). + */ + + +/** * g_cclosure_marshal_BOOL__FLAGS: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). + * An old alias for g_cclosure_marshal_BOOLEAN__FLAGS(). */ /** * g_cclosure_marshal_STRING__OBJECT_POINTER: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with handlers that + * take a #GObject and a pointer and produce a string. It is highly + * unlikely that your signal handler fits this description. + */ + + +/** + * g_cclosure_marshal_STRING__OBJECT_POINTERv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: a #GValue, which can store the returned string - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER(). */ /** * g_cclosure_marshal_VOID__BOOLEAN: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * boolean argument. + */ + + +/** + * g_cclosure_marshal_VOID__BOOLEANv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gboolean parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN(). */ /** * g_cclosure_marshal_VOID__BOXED: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * argument which is any boxed pointer type. + */ + + +/** + * g_cclosure_marshal_VOID__BOXEDv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GBoxed* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED(). */ /** * g_cclosure_marshal_VOID__CHAR: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * character argument. + */ + + +/** + * g_cclosure_marshal_VOID__CHARv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gchar parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR(). */ /** * g_cclosure_marshal_VOID__DOUBLE: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with one + * double-precision floating point argument. + */ + + +/** + * g_cclosure_marshal_VOID__DOUBLEv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gdouble parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE(). */ /** * g_cclosure_marshal_VOID__ENUM: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * argument with an enumerated type. + */ + + +/** + * g_cclosure_marshal_VOID__ENUMv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the enumeration parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM(). */ /** * g_cclosure_marshal_VOID__FLAGS: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * argument with a flags types. + */ + + +/** + * g_cclosure_marshal_VOID__FLAGSv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the flags parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS(). */ /** * g_cclosure_marshal_VOID__FLOAT: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with one + * single-precision floating point argument. + */ + + +/** + * g_cclosure_marshal_VOID__FLOATv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gfloat parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT(). */ /** * g_cclosure_marshal_VOID__INT: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * integer argument. + */ + + +/** + * g_cclosure_marshal_VOID__INTv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gint parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT(). */ /** * g_cclosure_marshal_VOID__LONG: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with with a single + * long integer argument. + */ + + +/** + * g_cclosure_marshal_VOID__LONGv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #glong parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG(). */ /** * g_cclosure_marshal_VOID__OBJECT: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * #GObject argument. + */ + + +/** + * g_cclosure_marshal_VOID__OBJECTv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GObject* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT(). */ /** * g_cclosure_marshal_VOID__PARAM: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * argument of type #GParamSpec. + */ + + +/** + * g_cclosure_marshal_VOID__PARAMv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GParamSpec* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM(). */ /** * g_cclosure_marshal_VOID__POINTER: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single raw + * pointer argument type. + * + * If it is possible, it is better to use one of the more specific + * functions such as g_cclosure_marshal_VOID__OBJECT() or + * g_cclosure_marshal_VOID__OBJECT(). + */ + + +/** + * g_cclosure_marshal_VOID__POINTERv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gpointer parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER(). */ /** * g_cclosure_marshal_VOID__STRING: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single string + * argument. + */ + + +/** + * g_cclosure_marshal_VOID__STRINGv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gchar* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING(). */ /** * g_cclosure_marshal_VOID__UCHAR: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * unsigned character argument. + */ + + +/** + * g_cclosure_marshal_VOID__UCHARv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #guchar parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR(). */ /** * g_cclosure_marshal_VOID__UINT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #guint parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with with a single + * unsigned integer argument. */ /** * g_cclosure_marshal_VOID__UINT_POINTER: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a unsigned int + * and a pointer as arguments. + */ + + +/** + * g_cclosure_marshal_VOID__UINT_POINTERv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 3 - * @param_values: a #GValue array holding instance, arg1 and arg2 - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER(). + */ + + +/** + * g_cclosure_marshal_VOID__UINTv: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. + * + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT(). */ /** * g_cclosure_marshal_VOID__ULONG: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with a single + * unsigned long integer argument. + */ + + +/** + * g_cclosure_marshal_VOID__ULONGv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #gulong parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG(). */ /** * g_cclosure_marshal_VOID__VARIANT: - * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 2 - * @param_values: a #GValue array holding the instance and the #GVariant* parameter - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. + * A #GClosureMarshal function for use with signals with a single + * #GVariant argument. + */ + + +/** + * g_cclosure_marshal_VOID__VARIANTv: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * Since: 2.26 + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT(). */ /** * g_cclosure_marshal_VOID__VOID: + * @closure: A #GClosure. + * @return_value: A #GValue to store the return value. May be %NULL + * if the callback of closure doesn't return a value. + * @n_param_values: The length of the @param_values array. + * @param_values: An array of #GValues holding the arguments + * on which to invoke the callback of closure. + * @invocation_hint: The invocation hint given as the last argument to + * g_closure_invoke(). + * @marshal_data: Additional data specified when registering the + * marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * + * A #GClosureMarshal function for use with signals with no arguments. + */ + + +/** + * g_cclosure_marshal_VOID__VOIDv: * @closure: the #GClosure to which the marshaller belongs - * @return_value: ignored - * @n_param_values: 1 - * @param_values: a #GValue array holding only the instance - * @invocation_hint: the invocation hint given as the last argument - * to g_closure_invoke() - * @marshal_data: additional data specified when registering the marshaller + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args. * - * A marshaller for a #GCClosure with a callback of type - * `void (*callback) (gpointer instance, gpointer user_data)`. + * The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID(). */ @@ -1181,6 +1736,28 @@ /** + * g_cclosure_marshal_generic_va: + * @closure: the #GClosure to which the marshaller belongs + * @return_value: (allow-none): a #GValue to store the return + * value. May be %NULL if the callback of @closure doesn't return a + * value. + * @instance: the instance on which the closure is invoked. + * @args_list: va_list of arguments to be passed to the closure. + * @marshal_data: (allow-none): additional data specified when + * registering the marshaller, see g_closure_set_marshal() and + * g_closure_set_meta_marshal() + * @n_params: the length of the @param_types array + * @param_types: (array length=n_params): the #GType of each argument from + * @args_list. + * + * A generic #GVaClosureMarshal function implemented via + * [libffi](http://sourceware.org/libffi/). + * + * Since: 2.30 + */ + + +/** * g_cclosure_new: (skip) * @callback_func: the function to invoke * @user_data: user data to pass to @callback_func @@ -2539,7 +3116,7 @@ * Releases all references to other objects. This can be used to break * reference cycles. * - * This functions should only be called from object system implementations. + * This function should only be called from object system implementations. */ @@ -2770,19 +3347,6 @@ /** - * g_param_get_default_value: - * @param: a #GParamSpec - * - * Gets the default value of @param as a pointer to a #GValue. - * - * The #GValue will remain value for the life of @param. - * - * Returns: a pointer to a #GValue which must not be modified - * Since: 2.38 - */ - - -/** * g_param_spec_boolean: * @name: canonical name of the property specified * @nick: nick name for the property specified @@ -2916,6 +3480,19 @@ /** + * g_param_spec_get_default_value: + * @param: a #GParamSpec + * + * Gets the default value of @param as a pointer to a #GValue. + * + * The #GValue will remain value for the life of @param. + * + * Returns: a pointer to a #GValue which must not be modified + * Since: 2.38 + */ + + +/** * g_param_spec_get_name: * @pspec: a valid #GParamSpec * @@ -4228,6 +4805,21 @@ /** + * g_signal_set_va_marshaller: + * @signal_id: the signal id + * @instance_type: the instance type on which to set the marshaller. + * @va_marshaller: the marshaller to set. + * + * Change the #GSignalCVaMarshaller used for a given signal. This is a + * specialised form of the marshaller that can often be used for the + * common case of a single connected signal handler and avoids the + * overhead of #GValue. Its use is optional. + * + * Since: 2.32 + */ + + +/** * g_signal_stop_emission: * @instance: (type GObject.Object): the object whose signal handlers you wish to stop. * @signal_id: the signal identifier, as returned by g_signal_lookup(). @@ -6198,14 +6790,6 @@ /** - * g_variant_get_gtype: - * - * Since: 2.24 - * Deprecated: 2.26 - */ - - -/** * g_weak_ref_clear: (skip) * @weak_ref: (inout): location of a weak reference, which * may be empty |