diff options
Diffstat (limited to 'gir/gobject-2.0.c')
| -rw-r--r-- | gir/gobject-2.0.c | 12233 |
1 files changed, 6147 insertions, 6086 deletions
diff --git a/gir/gobject-2.0.c b/gir/gobject-2.0.c index 554d70da..e6d50caf 100644 --- a/gir/gobject-2.0.c +++ b/gir/gobject-2.0.c @@ -3,1965 +3,2015 @@ /************************************************************/ /** - * G_NODE_IS_ROOT: - * @node: a #GNode - * - * Returns %TRUE if a #GNode is the root of a tree. - * (i.e. it has no parent or siblings) + * GBaseFinalizeFunc: + * @g_class: The #GTypeClass structure to finalize. * - * Returns: %TRUE if the #GNode is the root of a tree + * 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 intialization is performed. + * See GClassInitFunc() for a discussion of the class intialization process. */ /** - * G_PARAM_SPEC_GET_CLASS: - * @pspec: a valid #GParamSpec + * GBaseInitFunc: + * @g_class: The #GTypeClass structure to initialize. * - * Retrieves the #GParamSpecClass of a #GParamSpec. + * 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. + * 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 + * intialization process. */ /** - * g_type_remove_class_cache_func: (skip) - * @cache_data: data that was given when adding @cache_func - * @cache_func: a #GTypeClassCacheFunc + * GBinding: * - * Removes a previously installed #GTypeClassCacheFunc. The cache - * maintained by @cache_func has to be empty when calling - * g_type_remove_class_cache_func() to avoid leaks. + * <structname>GBinding</structname> is an opaque structure whose members + * cannot be accessed directly. + * + * Since: 2.26 */ /** - * g_value_get_ulong: - * @value: a valid #GValue of type %G_TYPE_ULONG + * GBinding:flags: * - * Get the contents of a %G_TYPE_ULONG #GValue. + * Flags to be used to control the #GBinding * - * Returns: unsigned long integer contents of @value + * Since: 2.26 */ /** - * g_value_array_sort_with_data: - * @value_array: #GValueArray to sort - * @compare_func: (scope call): function to compare elements - * @user_data: (closure): extra data argument provided for @compare_func + * GBinding:source: * - * Sort @value_array using @compare_func to compare the elements accoring - * to the semantics of #GCompareDataFunc. - * The current implementation uses Quick-Sort as sorting algorithm. + * The #GObject that should be used as the source of the binding * - * Rename to: g_value_array_sort - * Returns: (transfer none): the #GValueArray passed in as @value_array + * Since: 2.26 */ /** - * g_signal_connect_closure_by_id: - * @instance: the instance to connect to. - * @signal_id: the id of the signal. - * @detail: the detail. - * @closure: the closure to connect. - * @after: whether the handler should be called before or after the default handler of the signal. + * GBinding:source-property: * - * Connects a closure to a signal for a particular object. + * The name of the property of #GBinding:source that should be used + * as the source of the binding * - * Returns: the handler id + * Since: 2.26 */ /** - * G_PRIORITY_DEFAULT_IDLE: + * GBinding:target: * - * Use this for default priority idle functions. - * In GLib this priority is used when adding idle functions with - * g_idle_add(). + * The #GObject that should be used as the target of the binding + * + * Since: 2.26 */ /** - * G_VALUE_HOLDS_CHAR: - * @value: a valid #GValue structure + * GBinding:target-property: * - * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. + * The name of the property of #GBinding:target that should be used + * as the target of the binding * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * G_TYPE_IS_FUNDAMENTAL: - * @type: A #GType value. + * GBindingFlags: + * @G_BINDING_DEFAULT: The default binding; if the source property changes, the target property is updated with its value. + * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. + * @G_BINDING_SYNC_CREATE: 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. + * @G_BINDING_INVERT_BOOLEAN: 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 boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full(). * - * Checks if @type is a fundamental type. + * Flags to be passed to g_object_bind_property() or + * g_object_bind_property_full(). + * This enumeration can be extended at later date. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * g_main_run: - * @loop: a #GMainLoop + * GBindingTransformFunc: + * @binding: a #GBinding + * @source_value: the value of the source property + * @target_value: the value of the target property + * @user_data: data passed to the transform function * - * Runs a main loop until it stops running. + * A function to be called to transform the source property of @source + * from @source_value into the target property of @target + * using @target_value. + * otherwise * - * Deprecated: 2.2: Use g_main_loop_run() instead + * Returns: %TRUE if the transformation was successful, and %FALSE + * Since: 2.26 */ /** - * g_param_values_cmp: - * @pspec: a valid #GParamSpec - * @value1: a #GValue of correct type for @pspec - * @value2: a #GValue of correct type for @pspec - * - * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, - * if @value1 is found to be less than, equal to or greater than @value2, - * respectively. + * GBookmarkFile: * - * Returns: -1, 0 or +1, for a less than, equal to or greater than result + * The <structname>GBookmarkFile</structname> struct contains only + * private data and should not be directly accessed. */ /** - * g_source_set_closure: - * @source: the source - * @closure: a #GClosure + * GBookmarkFileError: + * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed + * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found + * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not register a bookmark + * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found + * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed + * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding + * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing + * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found * - * Set the callback for a source as a #GClosure. - * If the source is not one of the standard GLib types, the @closure_callback - * and @closure_marshal fields of the #GSourceFuncs structure must have been - * filled in with pointers to appropriate functions. + * Error codes returned by bookmark file parsing. */ /** - * g_type_add_class_private: - * @class_type: GType of an classed type. - * @private_size: size of private structure. + * GBoxedCopyFunc: + * @boxed: The boxed structure to be copied. * - * Registers a private class structure for a classed type; - * when the class is allocated, the private structures for - * the class and all of its parent types are allocated - * sequentially in the same memory block as the public - * structures. This function should be called in the - * type's get_type() function after the type is registered. - * The private structure can be retrieved using the - * G_TYPE_CLASS_GET_PRIVATE() macro. + * This function is provided by the user and should produce a copy of the passed + * in boxed structure. * - * Since: 2.24 + * Returns: The newly created copy of the boxed structure. */ /** - * SECTION:object: - * @short_description: The base object type - * @see_also: #GParamSpecObject, g_param_spec_object() - * @title: The Base Object Type + * GBoxedFreeFunc: + * @boxed: The boxed structure to be freed. * - * GObject is the fundamental type providing the common attributes and - * methods for all object types in GTK+, Pango and other libraries - * based on GObject. The GObject class provides methods for object - * construction and destruction, property access methods, and signal - * support. Signals are described in detail in <xref - * linkend="gobject-Signals"/>. - * <para id="floating-ref"> - * #GInitiallyUnowned is derived from #GObject. The only difference between - * the two is that the initial reference of a #GInitiallyUnowned is flagged - * as a <firstterm>floating</firstterm> 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: - * |[ - * container = create_container(); - * container_add_child (container, create_child()); - * ]| - * If <function>container_add_child()</function> will g_object_ref_sink() the - * passed in child, no reference of the newly created child is leaked. - * Without floating references, <function>container_add_child()</function> - * can only g_object_ref() the new child, so to implement this code without - * reference leaks, it would have to be written as: - * |[ - * Child *child; - * container = create_container(); - * 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 to g_object_ref() and returns - * a new reference. - * Since floating references are useful almost exclusively for C convenience, - * language bindings that provide automated reference and memory ownership - * maintenance (such as smart pointers or garbage collection) therefore don't - * need to expose floating references in their API. - * </para> - * Some object implementations may need to save an objects floating state - * across certain code portions (an example is #GtkMenu), to achive this, the - * following sequence can be used: - * |[ - * // save floating state - * gboolean was_floating = g_object_is_floating (object); - * g_object_ref_sink (object); - * // protected code portion - * ...; - * // restore floating state - * if (was_floating) - * g_object_force_floating (object); - * g_obejct_unref (object); // release previously acquired reference - * ]| + * This function is provided by the user and should free the boxed + * structure passed. */ /** - * g_cclosure_new: (skip) - * @callback_func: the function to invoke - * @user_data: user data to pass to @callback_func - * @destroy_data: destroy notify to be called when @user_data is no longer used - * - * Creates a new closure which invokes @callback_func with @user_data as - * the last parameter. + * GCClosure: + * @closure: the #GClosure + * @callback: the callback function * - * Returns: a new #GCClosure + * A #GCClosure is a specialization of #GClosure for C function callbacks. */ /** - * G_IS_PARAM_SPEC_CLASS: - * @pclass: a #GParamSpecClass + * GCallback: * - * Checks whether @pclass "is a" valid #GParamSpecClass structure of type - * %G_TYPE_PARAM or derived. + * 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. */ /** - * GBookmarkFile: + * GChecksum: * - * The <structname>GBookmarkFile</structname> struct contains only - * private data and should not be directly accessed. + * An opaque structure representing a checksumming operation. + * To create a new GChecksum, use g_checksum_new(). To free + * a GChecksum, use g_checksum_free(). + * + * Since: 2.16 */ /** - * g_cclosure_marshal_VOID__CHAR: - * @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 + * GChecksumType: + * @G_CHECKSUM_MD5: Use the MD5 hashing algorithm + * @G_CHECKSUM_SHA1: Use the SHA-1 hashing algorithm + * @G_CHECKSUM_SHA256: Use the SHA-256 hashing algorithm * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>. + * The hashing algorithm to be used by #GChecksum when performing the + * digest of some data. + * Note that the #GChecksumType enumeration may be extended at a later + * date to include new hashing algorithm types. + * + * Since: 2.16 */ /** - * g_param_spec_sink: - * @pspec: a valid #GParamSpec + * GChildWatchFunc: + * @pid: the process id of the child process + * @status: Status information about the child process, see waitpid(2) for more information about this field + * @data: user data passed to g_child_watch_add() * - * The initial reference count of a newly created #GParamSpec is 1, - * even though no one has explicitly called g_param_spec_ref() on it - * yet. So the initial reference count is flagged as "floating", until - * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink - * (pspec);</literal> in sequence on it, taking over the initial - * reference count (thus ending up with a @pspec that has a reference - * count of 1 still, but is not flagged "floating" anymore). + * The type of functions to be called when a child exists. */ /** - * G_TYPE_VARIANT_TYPE: - * - * The #GType for a boxed type holding a #GVariantType. + * GClassFinalizeFunc: + * @g_class: The #GTypeClass structure to finalize. + * @class_data: The @class_data member supplied via the #GTypeInfo structure. * - * Since: 2.24 + * 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 + * reference count drops to zero). */ /** - * GObjectClass: - * @g_type_class: the parent class - * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons. - * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system. - * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties. - * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. - * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. - * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. - * @notify: the class closure for the notify signal - * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. + * GClassInitFunc: + * @g_class: The #GTypeClass structure to initialize. + * @class_data: The @class_data member supplied via the #GTypeInfo structure. * - * The class structure for the <structname>GObject</structname> type. - * <example> - * <title>Implementing singletons using a constructor</title> - * <programlisting> - * static MySingleton *the_singleton = NULL; - * static GObject* - * my_singleton_constructor (GType type, - * guint n_construct_params, - * GObjectConstructParam *construct_params) + * A callback function used by the type system to initialize the class + * of a specific type. This function should initialize all static class + * members. + * The initialization process of a class involves: + * <itemizedlist> + * <listitem><para> + * 1 - Copying common members from the parent class over to the + * derived class structure. + * </para></listitem> + * <listitem><para> + * 2 - Zero initialization of the remaining members not copied + * over from the parent class. + * </para></listitem> + * <listitem><para> + * 3 - Invocation of the GBaseInitFunc() initializers of all parent + * types and the class' type. + * </para></listitem> + * <listitem><para> + * 4 - Invocation of the class' GClassInitFunc() initializer. + * </para></listitem> + * </itemizedlist> + * Since derived classes are partially initialized through a memory copy + * of the parent class, the general rule is that GBaseInitFunc() and + * GBaseFinalizeFunc() should take care of necessary reinitialization + * and release of those class members that were introduced by the type + * that specified these GBaseInitFunc()/GBaseFinalizeFunc(). + * GClassInitFunc() should only care about initializing static + * class members, while dynamic class members (such as allocated strings + * or reference counted resources) are better handled by a GBaseInitFunc() + * for this type, so proper initialization of the dynamic class members + * is performed for class initialization of derived types as well. + * An example may help to correspond the intend of the different class + * initializers: + * |[ + * typedef struct { + * GObjectClass parent_class; + * gint static_integer; + * gchar *dynamic_string; + * } TypeAClass; + * static void + * type_a_base_class_init (TypeAClass *class) * { - * GObject *object; - * if (!the_singleton) + * class->dynamic_string = g_strdup ("some string"); + * } + * static void + * type_a_base_class_finalize (TypeAClass *class) * { - * object = G_OBJECT_CLASS (parent_class)->constructor (type, - * n_construct_params, - * construct_params); - * the_singleton = MY_SINGLETON (object); + * g_free (class->dynamic_string); * } - * else - * object = g_object_ref (G_OBJECT (the_singleton)); - * return object; + * static void + * type_a_class_init (TypeAClass *class) + * { + * class->static_integer = 42; * } - * </programlisting></example> + * typedef struct { + * TypeAClass parent_class; + * gfloat static_float; + * GString *dynamic_gstring; + * } TypeBClass; + * static void + * type_b_base_class_init (TypeBClass *class) + * { + * class->dynamic_gstring = g_string_new ("some other string"); + * } + * static void + * type_b_base_class_finalize (TypeBClass *class) + * { + * g_string_free (class->dynamic_gstring); + * } + * static void + * 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). + * Initialization of TypeAClass roughly involves zero-initializing its fields, + * then calling its GBaseInitFunc() type_a_base_class_init() to allocate + * its dynamic members (dynamic_string), and finally calling its GClassInitFunc() + * type_a_class_init() to initialize its static members (static_integer). + * The first step in the initialization process of TypeBClass is then + * a plain memory copy of the contents of TypeAClass into TypeBClass and + * zero-initialization of the remaining fields in TypeBClass. + * The dynamic members of TypeAClass within TypeBClass now need + * reinitialization which is performed by calling type_a_base_class_init() + * with an argument of TypeBClass. + * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() + * is called to allocate the dynamic members of TypeBClass (dynamic_gstring), + * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), + * is called to complete the initialization process with the static members + * (static_float). + * Corresponding finalization counter parts to the GBaseInitFunc() functions + * have to be provided to release allocated resources at class finalization + * time. */ /** - * g_type_create_instance: (skip) - * @type: An instantiatable type to create an instance for. - * - * Creates and initializes an instance of @type if @type is valid and - * can be instantiated. The type system only performs basic allocation - * happen through functions supplied by the type's fundamental type - * implementation. So use of g_type_create_instance() is reserved for - * implementators of fundamental types only. E.g. instances of the - * #GObject hierarchy should be created via g_object_new() and - * <emphasis>never</emphasis> directly through - * g_type_create_instance() which doesn't handle things like singleton - * use this function, unless you're implementing a fundamental - * type. Also language bindings should <emphasis>not</emphasis> use - * this function but g_object_new() instead. - * treatment by the fundamental type implementation. + * GClosure: + * @in_marshal: Indicates whether the closure is currently being invoked with g_closure_invoke() + * @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate() * - * And structure setups for instances: actual instance creation should - * Objects or object construction. note: Do <emphasis>not</emphasis> - * Returns: An allocated and initialized instance, subject to further + * A #GClosure represents a callback supplied by the programmer. */ /** - * g_type_interface_prerequisites: - * @interface_type: an interface type - * @n_prerequisites: (out) (allow-none): location to return the number of prerequisites, or %NULL - * - * Returns the prerequisites of an interfaces type. - * newly-allocated zero-terminated array of #GType containing - * the prerequisites of @interface_type + * GClosureMarshal: + * @closure: the #GClosure to which the marshaller belongs + * @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 #GValue<!-- -->s 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() * - * Since: 2.2 - * Returns: (array length=n_prerequisites) (transfer full): a + * The type used for marshaller functions. */ /** - * GTypeFlags: - * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type. - * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init(). + * GClosureNotify: + * @data: data specified when registering the notification callback + * @closure: the #GClosure on which the notification is emitted * - * Bit masks used to check or determine characteristics of a type. + * The type used for the various notification callbacks which can be registered + * on closures. */ /** - * g_main_set_poll_func: - * @func: the function to call to poll all file descriptors - * - * Sets the function to use for the handle polling of file descriptors - * for the default main context. + * GConnectFlags: + * @G_CONNECT_AFTER: whether the handler should be called before or after the default handler of the signal. + * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when calling the handler. * - * Deprecated: 2.2: Use g_main_context_set_poll_func() again + * The connection flags are used to specify the behaviour of a signal's + * connection. */ /** - * g_signal_add_emission_hook: - * @signal_id: the signal identifier, as returned by g_signal_lookup(). - * @detail: the detail on which to call the hook. - * @hook_func: a #GSignalEmissionHook function. - * @hook_data: user data for @hook_func. - * @data_destroy: a #GDestroyNotify for @hook_data. - * - * Adds an emission hook for a signal, which will get called for any emission - * of that signal, independent of the instance. This is possible only - * for signals which don't have #G_SIGNAL_NO_HOOKS flag set. + * GConvertError: + * @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets is not supported. + * @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input. + * @G_CONVERT_ERROR_FAILED: Conversion failed for some reason. + * @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input. + * @G_CONVERT_ERROR_BAD_URI: URI is invalid. + * @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path. * - * Returns: the hook id, for later use with g_signal_remove_emission_hook(). + * Error codes returned by character set conversion routines. */ /** - * GRegexEvalCallback: - * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string. - * @result: a #GString containing the new string - * @user_data: user data passed to g_regex_replace_eval() + * GCopyFunc: + * @src: A pointer to the data which should be copied + * @data: Additional data * - * Specifies the type of the function passed to g_regex_replace_eval(). - * It is called for each occurance of the pattern in the string passed - * to g_regex_replace_eval(), and it should append the replacement to + * A function of this signature is used to copy the node data + * when doing a deep-copy of a tree. * - * Returns: %FALSE to continue the replacement process, %TRUE to stop it - * Since: 2.14 + * Returns: A pointer to the copy + * Since: 2.4 */ /** - * G_PARAM_SPEC_INT64: - * @pspec: a valid #GParamSpec instance + * GDateTime: * - * Cast a #GParamSpec instance into a #GParamSpecInt64. + * <structname>GDateTime</structname> is an opaque structure whose members + * cannot be accessed directly. + * + * Since: 2.26 */ /** - * g_node_insert_data_before: - * @parent: the #GNode to place the new #GNode under - * @sibling: the sibling #GNode to place the new #GNode before - * @data: the data for the new #GNode - * - * Inserts a new #GNode before the given sibling. + * GEnumClass: + * @g_type_class: the parent class + * @minimum: the smallest possible value. + * @maximum: the largest possible value. + * @n_values: the number of possible values. + * @values: an array of #GEnumValue structs describing the individual values. * - * Returns: the new #GNode + * The class of an enumeration type holds information about its + * possible values. */ /** - * G_TYPE_UCHAR: + * GEnumValue: + * @value: the enum value + * @value_name: the name of the value + * @value_nick: the nickname of the value * - * The fundamental type corresponding to #guchar. + * A structure which contains a single enum value, its name, and its + * nickname. */ /** - * GObjectGetPropertyFunc: - * @object: a #GObject - * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). - * @value: a #GValue to return the property value in - * @pspec: the #GParamSpec describing the property + * GFlagsClass: + * @g_type_class: the parent class + * @mask: a mask covering all possible values. + * @n_values: the number of possible values. + * @values: an array of #GFlagsValue structs describing the individual values. * - * The type of the @get_property function of #GObjectClass. + * The class of a flags type holds information about its + * possible values. */ /** - * g_value_type_transformable: - * @src_type: Source type. - * @dest_type: Target type. - * - * Check whether g_value_transform() is able to transform values - * of type @src_type into values of type @dest_type. + * GFlagsValue: + * @value: the flags value + * @value_name: the name of the value + * @value_nick: the nickname of the value * - * Returns: %TRUE if the transformation is possible, %FALSE otherwise. + * A structure which contains a single flags value, its name, and its + * nickname. */ /** - * GInterfaceInfo: - * @interface_init: location of the interface initialization function - * @interface_finalize: location of the interface finalization function - * @interface_data: user-supplied data passed to the interface init/finalize functions + * GIconv: * - * A structure that provides information to the type system which is - * used specifically for managing interface types. + * The <structname>GIConv</structname> struct wraps an + * iconv() conversion descriptor. It contains private data + * and should only be accessed using the following functions. */ /** - * G_IS_PARAM_SPEC_FLAGS: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. + * GInitiallyUnowned: * - * Returns: %TRUE on success. + * All the fields in the <structname>GInitiallyUnowned</structname> structure + * are private to the #GInitiallyUnowned implementation and should never be + * accessed directly. */ /** - * GMemVTable: - * @malloc: function to use for allocating memory. - * @realloc: function to use for reallocating memory. - * @free: function to use to free memory. - * @calloc: function to use for allocating zero-filled memory. - * @try_malloc: function to use for allocating memory without a default error handler. - * @try_realloc: function to use for reallocating memory without a default error handler. + * GInitiallyUnownedClass: * - * A set of functions used to perform memory allocation. The same #GMemVTable must - * be used for all allocations in the same program; a call to g_mem_set_vtable(), - * if it exists, should be prior to any use of GLib. + * The class structure for the <structname>GInitiallyUnowned</structname> type. */ /** - * GTypePluginCompleteInterfaceInfo: - * @plugin: the #GTypePlugin - * @instance_type: the #GType of an instantiable type to which the interface is added - * @interface_type: the #GType of the interface whose info is completed - * @info: the #GInterfaceInfo to fill in + * GInstanceInitFunc: + * @instance: The instance to initialize. + * @g_class: The class of the type the instance is created for. * - * The type of the @complete_interface_info function of #GTypePluginClass. + * 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. + * Initialization of a derived instance involves calling all its parent + * types instance initializers, so the class member of the instance + * is altered during its initialization to always point to the class that + * belongs to the type the current initializer was introduced for. */ /** - * g_try_renew: - * @struct_type: the type of the elements to allocate - * @mem: the currently allocated memory - * @n_structs: the number of elements to allocate - * - * Attempts to reallocate the memory pointed to by @mem, so that it now has - * space for @n_structs elements of type @struct_type, and returns %NULL on - * failure. Contrast with g_renew(), which aborts the program on failure. - * It returns the new address of the memory, which may have been moved. - * The function returns %NULL if an overflow occurs. + * GInterfaceFinalizeFunc: + * @g_iface: The interface structure to finalize. + * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. * - * Since: 2.8 - * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type + * 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. */ /** - * g_value_set_pointer: - * @value: a valid #GValue of %G_TYPE_POINTER - * @v_pointer: pointer value to be set + * GInterfaceInfo: + * @interface_init: location of the interface initialization function + * @interface_finalize: location of the interface finalization function + * @interface_data: user-supplied data passed to the interface init/finalize functions * - * Set the contents of a pointer #GValue to @v_pointer. + * A structure that provides information to the type system which is + * used specifically for managing interface types. */ /** - * g_closure_sink: - * @closure: #GClosure to decrement the initial reference count on, if it's still being held + * GInterfaceInitFunc: + * @g_iface: The interface structure to initialize. + * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. * - * Takes over the initial ownership of a closure. Each closure is - * initially created in a <firstterm>floating</firstterm> 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 existance of the floating state is to - * prevent cumbersome code sequences like: - * |[ - * closure = g_cclosure_new (cb_func, cb_data); - * g_source_set_closure (source, closure); - * g_closure_unref (closure); // XXX 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: - * |[ - * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); - * ]| - * Generally, this function is used together with g_closure_ref(). Ane example - * of storing a closure for later notification looks like: - * |[ - * static GClosure *notify_closure = NULL; - * void - * foo_notify_set_closure (GClosure *closure) - * { - * if (notify_closure) - * g_closure_unref (notify_closure); - * notify_closure = closure; - * if (notify_closure) - * { - * g_closure_ref (notify_closure); - * g_closure_sink (notify_closure); - * } - * } - * ]| - * Because g_closure_sink() may decrement the reference count of a closure - * (if it hasn't been called on @closure yet) just like g_closure_unref(), - * g_closure_ref() should be called prior to this function. + * 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. */ /** - * g_type_depth: - * @type: A #GType value. - * - * Returns the length of the ancestry of the passed in type. This - * includes the type itself, so that e.g. a fundamental type has depth 1. + * GMainContext: * - * Returns: The depth of @type. + * The <structname>GMainContext</structname> struct is an opaque data + * type representing a set of sources to be handled in a main loop. */ /** - * GObjectSetPropertyFunc: - * @object: a #GObject - * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). - * @value: the new value for the property - * @pspec: the #GParamSpec describing the property + * GMainLoop: * - * The type of the @set_property function of #GObjectClass. + * The <structname>GMainLoop</structname> struct is an opaque data type + * representing the main event loop of a GLib or GTK+ application. */ /** - * G_IS_VALUE: - * @value: A #GValue structure. + * GMarkupError: + * @G_MARKUP_ERROR_BAD_UTF8: text being parsed was not valid UTF-8 + * @G_MARKUP_ERROR_EMPTY: document contained nothing, or only whitespace + * @G_MARKUP_ERROR_PARSE: document was ill-formed + * @G_MARKUP_ERROR_UNKNOWN_ELEMENT: error should be set by #GMarkupParser functions; element wasn't known + * @G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE: error should be set by #GMarkupParser functions; attribute wasn't known + * @G_MARKUP_ERROR_INVALID_CONTENT: error should be set by #GMarkupParser functions; content was invalid + * @G_MARKUP_ERROR_MISSING_ATTRIBUTE: error should be set by #GMarkupParser functions; a required attribute was missing * - * Checks if @value is a valid and initialized #GValue structure. - * - * Returns: %TRUE on success. + * Error codes returned by markup parsing. */ /** - * G_TYPE_PARAM_CHAR: + * GMarkupParseContext: * - * The #GType of #GParamSpecChar. + * A parse context is used to parse a stream of bytes that + * you expect to contain marked-up text. + * See g_markup_parse_context_new(), #GMarkupParser, and so + * on for more details. */ /** - * GParamSpecUnichar: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified + * GMarkupParseFlags: + * @G_MARKUP_DO_NOT_USE_THIS_UNSUPPORTED_FLAG: flag you should not use + * @G_MARKUP_TREAT_CDATA_AS_TEXT: When this flag is set, CDATA marked sections are not passed literally to the @passthrough function of the parser. Instead, the content of the section (without the <literal><![CDATA[</literal> and <literal>]]></literal>) is passed to the @text function. This flag was added in GLib 2.12 + * @G_MARKUP_PREFIX_ERROR_POSITION: Normally errors caught by GMarkup itself have line/column information prefixed to them to let the caller know the location of the error. When this flag is set the location information is also prefixed to errors generated by the #GMarkupParser implementation functions * - * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. + * Flags that affect the behaviour of the parser. */ /** - * G_VARIANT_TYPE_BYTESTRING_ARRAY: + * GMarkupParser: + * @start_element: Callback to invoke when the opening tag of an element is seen. + * @end_element: Callback to invoke when the closing tag of an element is seen. Note that this is also called for empty tags like <literal><empty/></literal>. + * @text: Callback to invoke when some text is seen (text is always inside an element). Note that the text of an element may be spread over multiple calls of this function. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is set, this function is also called for the content of CDATA marked sections. + * @passthrough: Callback to invoke for comments, processing instructions and doctype declarations; if you're re-writing the parsed document, write the passthrough text back out in the same position. If the %G_MARKUP_TREAT_CDATA_AS_TEXT flag is not set, this function is also called for CDATA marked sections. + * @error: Callback to invoke when an error occurs. * - * The type of an array of byte strings (an array of arrays of bytes). + * Any of the fields in #GMarkupParser can be %NULL, in which case they + * will be ignored. Except for the @error function, any of these callbacks + * can set an error; in particular the %G_MARKUP_ERROR_UNKNOWN_ELEMENT, + * %G_MARKUP_ERROR_UNKNOWN_ATTRIBUTE, and %G_MARKUP_ERROR_INVALID_CONTENT + * errors are intended to be set from these callbacks. If you set an error + * from a callback, g_markup_parse_context_parse() will report that error + * back to its caller. */ /** - * G_DEFINE_TYPE_EXTENDED: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_f_: #GTypeFlags to pass to g_type_register_static() - * @_C_: Custom code that gets inserted in the *_get_type() function. - * - * The most general convenience macro for type implementations, on which - * G_DEFINE_TYPE(), etc are based. - * |[ - * G_DEFINE_TYPE_EXTENDED (GtkGadget, - * gtk_gadget, - * GTK_TYPE_WIDGET, - * 0, - * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, - * gtk_gadget_gizmo_init)); - * ]| - * expands to - * |[ - * static void gtk_gadget_init (GtkGadget *self); - * static void gtk_gadget_class_init (GtkGadgetClass *klass); - * static gpointer gtk_gadget_parent_class = NULL; - * static void gtk_gadget_class_intern_init (gpointer klass) - * { - * gtk_gadget_parent_class = g_type_class_peek_parent (klass); - * gtk_gadget_class_init ((GtkGadgetClass*) klass); - * } - * 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)) - * { - * GType g_define_type_id = - * g_type_register_static_simple (GTK_TYPE_WIDGET, - * g_intern_static_string ("GtkGadget"), - * sizeof (GtkGadgetClass), - * (GClassInitFunc) gtk_gadget_class_intern_init, - * sizeof (GtkGadget), - * (GInstanceInitFunc) gtk_gadget_init, - * (GTypeFlags) flags); - * { - * static const GInterfaceInfo g_implement_interface_info = { - * (GInterfaceInitFunc) gtk_gadget_gizmo_init - * }; - * 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); - * } - * return g_define_type_id__volatile; - * } - * ]| - * 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. + * GMemVTable: + * @malloc: function to use for allocating memory. + * @realloc: function to use for reallocating memory. + * @free: function to use to free memory. + * @calloc: function to use for allocating zero-filled memory. + * @try_malloc: function to use for allocating memory without a default error handler. + * @try_realloc: function to use for reallocating memory without a default error handler. * - * Since: 2.4 + * A set of functions used to perform memory allocation. The same #GMemVTable must + * be used for all allocations in the same program; a call to g_mem_set_vtable(), + * if it exists, should be prior to any use of GLib. */ /** - * g_object_set_data_full: (skip) - * @object: #GObject containing the associations - * @key: name of the key - * @data: data to associate with that key - * @destroy: function to call when the association is destroyed + * GObject: * - * Like g_object_set_data() except it adds notification - * for when the association is destroyed, either by setting it - * to a different value or when the object is destroyed. - * Note that the @destroy callback is not called if @data is %NULL. + * All the fields in the <structname>GObject</structname> structure are private + * to the #GObject implementation and should never be accessed directly. */ /** - * GBinding:source: - * - * The #GObject that should be used as the source of the binding + * GObject::notify: + * @gobject: the object which received the signal. + * @pspec: the #GParamSpec of the property which changed. * - * Since: 2.26 + * The notify signal is emitted on an object when one of its + * properties has been changed. Note that getting this signal + * doesn't guarantee that the value of the property has actually + * changed, it may also be emitted when the setter for the property + * is called to reinstate the previous value. + * 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: + * |[ + * 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 + * <link linkend="canonical-parameter-name">canonical</link> parameter names as + * detail strings for the notify signal. */ /** - * G_PARAM_SPEC_GTYPE: - * @pspec: a #GParamSpec - * - * Casts a #GParamSpec into a #GParamSpecGType. + * GObjectClass: + * @g_type_class: the parent class + * @constructor: the @constructor function is called by g_object_new () to complete the object initialization after all the construction properties are set. The first thing a @constructor implementation must do is chain up to the needed, e.g. to handle construct properties, or to implement singletons. + * @set_property: the generic setter for all properties of this type. Should be overridden for every type with properties. Implementations of @set_property don't need to emit property change notification explicitly, this is handled by the type system. + * @get_property: the generic getter for all properties of this type. Should be overridden for every type with properties. + * @dispose: the @dispose function is supposed to drop all references to other objects, but keep the instance otherwise intact, so that client method invocations still work. It may be run multiple times (due to reference loops). Before returning, @dispose should chain up to the @dispose method of the parent class. + * @finalize: instance finalization function, should finish the finalization of the instance begun in @dispose and chain up to the @finalize method of the parent class. + * @dispatch_properties_changed: emits property change notification for a bunch of properties. Overriding @dispatch_properties_changed should be rarely needed. + * @notify: the class closure for the notify signal + * @constructed: the @constructed function is called by g_object_new() as the final step of the object creation process. At the point of the call, all construction properties have been set on the object. The purpose of this call is to allow for object initialisation steps that can only be performed after construction properties have been set. @constructed implementors should chain up to the @constructed call of their parent class to allow it to complete its initialisation. * - * Since: 2.10 + * The class structure for the <structname>GObject</structname> type. + * <example> + * <title>Implementing singletons using a constructor</title> + * <programlisting> + * static MySingleton *the_singleton = NULL; + * static GObject* + * my_singleton_constructor (GType type, + * guint n_construct_params, + * GObjectConstructParam *construct_params) + * { + * GObject *object; + * if (!the_singleton) + * { + * object = G_OBJECT_CLASS (parent_class)->constructor (type, + * n_construct_params, + * construct_params); + * the_singleton = MY_SINGLETON (object); + * } + * else + * object = g_object_ref (G_OBJECT (the_singleton)); + * return object; + * } + * </programlisting></example> */ /** - * g_value_get_param: - * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM - * - * Get the contents of a %G_TYPE_PARAM #GValue. + * GObjectConstructParam: + * @pspec: the #GParamSpec of the construct parameter + * @value: the value to set the parameter to * - * Returns: (transfer none): #GParamSpec content of @value + * The <structname>GObjectConstructParam</structname> struct is an auxiliary + * structure used to hand #GParamSpec/#GValue pairs to the @constructor of + * a #GObjectClass. */ /** - * G_TYPE_ERROR: - * - * The #GType for a boxed type holding a #GError. + * GObjectFinalizeFunc: + * @object: the #GObject being finalized * - * Since: 2.26 + * The type of the @finalize function of #GObjectClass. */ /** - * G_PARAM_SPEC_LONG: - * @pspec: a valid #GParamSpec instance + * GObjectGetPropertyFunc: + * @object: a #GObject + * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). + * @value: a #GValue to return the property value in + * @pspec: the #GParamSpec describing the property * - * Cast a #GParamSpec instance into a #GParamSpecLong. + * The type of the @get_property function of #GObjectClass. */ /** - * g_signal_lookup: - * @name: the signal's name. - * @itype: the type that the signal operates on. - * - * Given the name of the signal and the type of object it connects to, gets - * the signal's identifying integer. Emitting the signal by number is - * somewhat faster than using the name each time. - * Also tries the ancestors of the given type. - * See g_signal_new() for details on allowed signal names. + * GObjectSetPropertyFunc: + * @object: a #GObject + * @property_id: the numeric id under which the property was registered with g_object_class_install_property(). + * @value: the new value for the property + * @pspec: the #GParamSpec describing the property * - * Returns: the signal's identifying number, or 0 if no signal was found. + * The type of the @set_property function of #GObjectClass. */ /** - * g_value_dup_object: - * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT + * GOptionArg: + * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags. + * @G_OPTION_ARG_STRING: The option takes a string argument. + * @G_OPTION_ARG_INT: The option takes an integer argument. + * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument. + * @G_OPTION_ARG_FILENAME: The option takes a filename as argument. + * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings. + * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings. + * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12 + * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12 * - * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing - * its reference count. - * should be unreferenced when no longer needed. + * The #GOptionArg enum values determine which type of extra argument the + * options expect to find. If an option expects an extra argument, it + * can be specified in several ways; with a short option: + * <option>-x arg</option>, with a long option: <option>--name arg</option> * - * Returns: (type GObject.Object) (transfer full): object content of @value, + * Or combined in a single argument: <option>--name=arg</option>. */ /** - * g_signal_emit_valist: - * @instance: the instance the signal is being emitted on. - * @signal_id: the signal id - * @detail: the detail - * @var_args: a list of 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. + * GOptionArgFunc: + * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. + * @value: The value to be parsed. + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks. * - * Emits a signal. - * Note that g_signal_emit_valist() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). + * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK + * options. + * occurred, in which case @error should be set with g_set_error() + * + * Returns: %TRUE if the option was successfully parsed, %FALSE if an error */ /** - * g_variant_get_gtype: - * - * + * GOptionContext: * - * Since: 2.24 - * Deprecated: 2.26 + * A <structname>GOptionContext</structname> struct defines which options + * are accepted by the commandline option parser. The struct has only private + * fields and should not be directly accessed. */ /** - * G_VALUE_HOLDS_ULONG: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. + * GOptionEntry: + * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>. + * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name. + * @flags: Flags from #GOptionFlags. + * @arg: The type of the option, as a #GOptionArg. + * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). + * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). + * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). * - * Returns: %TRUE on success. + * A <structname>GOptionEntry</structname> defines a single option. + * To have an effect, they must be added to a #GOptionGroup with + * g_option_context_add_main_entries() or g_option_group_add_entries(). */ /** - * g_object_get_valist: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to get - * @var_args: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + * GOptionError: + * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options(). + * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed. + * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. * - * Gets properties of an object. - * In general, a copy is made of the property contents and the caller - * is responsible for freeing the memory in the appropriate manner for - * the type, for instance by calling g_free() or g_object_unref(). - * See g_object_get(). + * Error codes returned by option parsing. */ /** - * g_value_get_uint64: - * @value: a valid #GValue of type %G_TYPE_UINT64 - * - * Get the contents of a %G_TYPE_UINT64 #GValue. + * GOptionErrorFunc: + * @context: The active #GOptionContext + * @group: The group to which the function belongs + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: The #GError containing details about the parse error * - * Returns: unsigned 64bit integer contents of @value + * The type of function to be used as callback when a parse error occurs. */ /** - * G_TYPE_NONE: + * GOptionFlags: + * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output. + * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group. + * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed. + * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8 + * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8 + * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 + * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8. * - * A fundamental type which is used as a replacement for the C - * <literal>void</literal> return type. + * Flags which modify individual options. */ /** - * G_VARIANT_TYPE_BASIC: + * GOptionGroup: * - * An indefinite type that is a supertype of every basic (ie: - * non-container) type. + * A <structname>GOptionGroup</structname> struct defines the options in a single + * group. The struct has only private fields and should not be directly accessed. + * All options in a group share the same translation function. Libraries which + * need to parse commandline options are expected to provide a function for + * getting a <structname>GOptionGroup</structname> holding their options, which + * the application can then add to its #GOptionContext. */ /** - * G_OBJECT_TYPE: - * @object: Object to return the type id for. + * GOptionParseFunc: + * @context: The active #GOptionContext + * @group: The group to which the function belongs + * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() + * @error: A return location for error details * - * Get the type id of an object. + * The type of function that can be called before and after parsing. + * occurred, in which case @error should be set with g_set_error() * - * Returns: Type id of @object. + * Returns: %TRUE if the function completed successfully, %FALSE if an error */ /** - * g_clear_object: (skip) - * @object_ptr: a pointer to a #GObject reference - * - * Clears a reference to a #GObject. - * If the reference is %NULL then this function does nothing. - * Otherwise, the reference count of the object is decreased and the - * pointer is set to %NULL. - * This function is threadsafe and modifies the pointer atomically, - * using memory barriers where needed. - * A macro is also included that allows this function to be used without - * pointer casts. + * GParamFlags: + * @G_PARAM_READABLE: the parameter is readable + * @G_PARAM_WRITABLE: the parameter is writable + * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction + * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction + * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required + * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 + * @G_PARAM_PRIVATE: internal + * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26 * - * Since: 2.28 + * Through the #GParamFlags flag values, certain aspects of parameters + * can be configured. */ /** - * G_IS_OBJECT_CLASS: - * @class: a #GObjectClass + * GParamSpec: + * @g_type_instance: private #GTypeInstance portion + * @name: name of this parameter + * @flags: #GParamFlags flags for this parameter + * @value_type: the #GValue type for this parameter + * @owner_type: #GType type that uses (introduces) this parameter * - * Checks whether @class "is a" valid #GObjectClass structure of type - * %G_TYPE_OBJECT or derived. + * All other fields of the <structname>GParamSpec</structname> struct are private and + * should not be used directly. */ /** - * GInitiallyUnowned: + * GParamSpecBoolean: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified * - * All the fields in the <structname>GInitiallyUnowned</structname> structure - * are private to the #GInitiallyUnowned implementation and should never be - * accessed directly. + * A #GParamSpec derived structure that contains the meta data for boolean properties. */ /** - * g_object_set: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to set - * @...: value for the first property, followed optionally by more name/value pairs, followed by %NULL + * GParamSpecBoxed: + * @parent_instance: private #GParamSpec portion * - * Sets properties on an object. + * A #GParamSpec derived structure that contains the meta data for boxed properties. */ /** - * G_VALUE_HOLDS_PARAM: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. + * GParamSpecChar: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: %TRUE on success. + * A #GParamSpec derived structure that contains the meta data for character properties. */ /** - * g_object_is_floating: - * @object: (type GObject.Object): a #GObject - * - * Checks wether @object has a <link linkend="floating-ref">floating</link> - * reference. + * GParamSpecClass: + * @g_type_class: the parent class + * @value_type: the #GValue type for this parameter + * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class. + * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default(). + * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_set_validate(). + * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp(). * - * Since: 2.10 - * Returns: %TRUE if @object has a floating reference + * The class structure for the <structname>GParamSpec</structname> type. + * Normally, <structname>GParamSpec</structname> classes are filled by + * g_param_type_register_static(). */ /** - * GOptionErrorFunc: - * @context: The active #GOptionContext - * @group: The group to which the function belongs - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: The #GError containing details about the parse error + * GParamSpecDouble: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. * - * The type of function to be used as callback when a parse error occurs. + * A #GParamSpec derived structure that contains the meta data for double properties. */ /** - * G_TYPE_PARAM_FLOAT: + * GParamSpecEnum: + * @parent_instance: private #GParamSpec portion + * @enum_class: the #GEnumClass for the enum + * @default_value: default value for the property specified * - * The #GType of #GParamSpecFloat. + * A #GParamSpec derived structure that contains the meta data for enum + * properties. */ /** - * G_TYPE_FUNDAMENTAL: - * @type: A #GType value. + * GParamSpecFlags: + * @parent_instance: private #GParamSpec portion + * @flags_class: the #GFlagsClass for the flags + * @default_value: default value for the property specified * - * 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. + * A #GParamSpec derived structure that contains the meta data for flags + * properties. */ /** - * g_type_class_ref: - * @type: Type ID of a classed type. - * - * Increments the reference count of the class structure belonging to - * exist already. - * structure for the given type ID. + * GParamSpecFloat: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass + * A #GParamSpec derived structure that contains the meta data for float properties. */ /** - * GInitiallyUnownedClass: + * GParamSpecGType: + * @parent_instance: private #GParamSpec portion + * @is_a_type: a #GType whose subtypes can occur as values * - * The class structure for the <structname>GInitiallyUnowned</structname> type. + * A #GParamSpec derived structure that contains the meta data for #GType properties. + * + * Since: 2.10 */ /** - * GConvertError: - * @G_CONVERT_ERROR_NO_CONVERSION: Conversion between the requested character sets is not supported. - * @G_CONVERT_ERROR_ILLEGAL_SEQUENCE: Invalid byte sequence in conversion input. - * @G_CONVERT_ERROR_FAILED: Conversion failed for some reason. - * @G_CONVERT_ERROR_PARTIAL_INPUT: Partial character sequence at end of input. - * @G_CONVERT_ERROR_BAD_URI: URI is invalid. - * @G_CONVERT_ERROR_NOT_ABSOLUTE_PATH: Pathname is not an absolute path. + * GParamSpecInt: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Error codes returned by character set conversion routines. + * A #GParamSpec derived structure that contains the meta data for integer properties. */ /** - * G_PARAM_SPEC_TYPE_NAME: - * @pspec: a valid #GParamSpec + * GParamSpecInt64: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Retrieves the #GType name of this @pspec. + * A #GParamSpec derived structure that contains the meta data for 64bit integer properties. */ /** - * G_IS_PARAM_SPEC_OBJECT: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. + * GParamSpecLong: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: %TRUE on success. + * A #GParamSpec derived structure that contains the meta data for long integer properties. */ /** - * g_type_interface_peek_parent: - * @g_iface: (type GObject.TypeInterface): A #GTypeInterface structure. - * - * Returns the corresponding #GTypeInterface structure of the parent type - * of the instance type to which @g_iface belongs. This is useful when - * deriving the implementation of an interface from the parent type and - * then possibly overriding some methods. - * corresponding #GTypeInterface structure of the parent type of the - * instance type to which @g_iface belongs, or %NULL if the parent - * type doesn't conform to the interface. + * GParamSpecObject: + * @parent_instance: private #GParamSpec portion * - * Returns: (transfer none) (type GObject.TypeInterface): The + * A #GParamSpec derived structure that contains the meta data for object properties. */ /** - * G_IS_PARAM_SPEC_VALUE_ARRAY: - * @pspec: a valid #GParamSpec instance + * GParamSpecOverride: * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. + * 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 overidden + * 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. * - * Returns: %TRUE on success. + * Since: 2.4 */ /** - * G_TYPE_ENUM: + * GParamSpecParam: + * @parent_instance: private #GParamSpec portion * - * The fundamental type from which all enumeration types are derived. + * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM + * properties. */ /** - * G_IS_PARAM_SPEC_BOXED: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. + * GParamSpecPointer: + * @parent_instance: private #GParamSpec portion * - * Returns: %TRUE on success. + * A #GParamSpec derived structure that contains the meta data for pointer properties. */ /** - * g_type_set_qdata: - * @type: a #GType - * @quark: a #GQuark id to identify the data - * @data: the data + * GParamSpecPool: * - * Attaches arbitrary data to a type. + * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s 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. */ /** - * GOptionParseFunc: - * @context: The active #GOptionContext - * @group: The group to which the function belongs - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: A return location for error details - * - * The type of function that can be called before and after parsing. - * occurred, in which case @error should be set with g_set_error() + * GParamSpecString: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified + * @cset_first: a string containing the allowed values for the first byte + * @cset_nth: a string containing the allowed values for the subsequent bytes + * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth. + * @null_fold_if_empty: replace empty string by %NULL + * @ensure_non_null: replace %NULL strings by an empty string * - * Returns: %TRUE if the function completed successfully, %FALSE if an error + * A #GParamSpec derived structure that contains the meta data for string + * properties. */ /** - * G_ENUM_CLASS: - * @class: a valid #GEnumClass + * GParamSpecTypeInfo: + * @instance_size: Size of the instance (object) structure. + * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. + * @instance_init: Location of the instance initialization function (optional). + * @value_type: The #GType of values conforming to this #GParamSpec + * @finalize: The instance finalization function (optional). + * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default(). + * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_set_validate(). + * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp(). * - * Casts a derived #GEnumClass structure into a #GEnumClass structure. + * 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 + * g_param_type_register_static(). */ /** - * G_TYPE_CLASS_GET_PRIVATE: - * @klass: the class of a type deriving from @private_type. - * @g_type: the type identifying which private data to retrieve. - * @c_type: The C type for the private structure. - * - * 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(). - * This macro should only be used in type implementations. + * GParamSpecUChar: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Since: 2.24 - * Returns: a pointer to the private data structure. + * A #GParamSpec derived structure that contains the meta data for unsigned character properties. */ /** - * GChecksumType: - * @G_CHECKSUM_MD5: Use the MD5 hashing algorithm - * @G_CHECKSUM_SHA1: Use the SHA-1 hashing algorithm - * @G_CHECKSUM_SHA256: Use the SHA-256 hashing algorithm - * - * The hashing algorithm to be used by #GChecksum when performing the - * digest of some data. - * Note that the #GChecksumType enumeration may be extended at a later - * date to include new hashing algorithm types. + * GParamSpecUInt: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Since: 2.16 + * A #GParamSpec derived structure that contains the meta data for unsigned integer properties. */ /** - * G_VALUE_COLLECT_FORMAT_MAX_LENGTH: + * GParamSpecUInt64: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * The maximal number of #GTypeCValue<!-- -->s which can be collected for a - * single #GValue. + * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. */ /** - * g_object_new: (skip) - * @object_type: the type id of the #GObject subtype to instantiate - * @first_property_name: the name of the first property - * @...: the value of the first property, followed optionally by more name/value pairs, followed by %NULL - * - * Creates a new instance of a #GObject subtype and sets its properties. - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. + * GParamSpecULong: + * @parent_instance: private #GParamSpec portion + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified * - * Returns: (transfer full): a new instance of @object_type + * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. */ /** - * G_PARAM_SPEC_POINTER: - * @pspec: a valid #GParamSpec instance + * GParamSpecUnichar: + * @parent_instance: private #GParamSpec portion + * @default_value: default value for the property specified * - * Casts a #GParamSpec instance into a #GParamSpecPointer. + * A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. */ /** - * g_value_set_int64: - * @value: a valid #GValue of type %G_TYPE_INT64 - * @v_int64: 64bit integer value to be set + * GParamSpecValueArray: + * @parent_instance: private #GParamSpec portion + * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements * - * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. + * A #GParamSpec derived structure that contains the meta data for #GValueArray properties. */ /** - * G_VALUE_HOLDS_INT: - * @value: a valid #GValue structure + * GParamSpecVariant: + * @parent_instance: private #GParamSpec portion + * @type: a #GVariantType, or %NULL + * @default_value: a #GVariant, or %NULL * - * Checks whether the given #GValue can hold values of type %G_TYPE_INT. + * A #GParamSpec derived structure that contains the meta data for #GVariant properties. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * G_NODE_IS_LEAF: - * @node: a #GNode - * - * Returns %TRUE if a #GNode is a leaf node. - * (i.e. it has no children) + * GParameter: + * @name: the parameter name + * @value: the parameter value * - * Returns: %TRUE if the #GNode is a leaf node + * The <structname>GParameter</structname> struct is an auxiliary structure used + * to hand parameter name/value pairs to g_object_newv(). */ /** - * g_type_children: - * @type: The parent type. - * @n_children: (out) (allow-none): Optional #guint pointer to contain the number of child types. - * - * Return a newly allocated and 0-terminated array of type IDs, listing the - * child types of @type. The return value has to be g_free()ed after use. - * and 0-terminated array of child types. + * GPid: * - * Returns: (array length=n_children) (transfer full): Newly allocated + * A type which is used to hold a process identification. + * On UNIX, processes are identified by a process id (an integer), + * while Windows uses process handles (which are pointers). */ /** - * G_TYPE_PARAM_BOOLEAN: + * GPollFD: + * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32) + * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR. + * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred. + * * - * The #GType of #GParamSpecBoolean. */ /** - * G_TYPE_ARRAY: + * GPollFunc: + * @ufds: an array of #GPollFD elements + * @nfsd: the number of elements in @ufds + * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout. * - * The #GType for a boxed type holding a #GArray reference. + * Specifies the type of function passed to g_main_context_set_poll_func(). + * The semantics of the function should match those of the poll() system call. + * reported, or -1 if an error occurred. * - * Since: 2.22 + * Returns: the number of #GPollFD elements which have events or errors */ /** - * g_flags_get_value_by_nick: - * @flags_class: a #GFlagsClass - * @nick: the nickname to look up + * GRegex: * - * Looks up a #GFlagsValue by nickname. - * no flag with that nickname + * A GRegex is the "compiled" form of a regular expression pattern. This + * structure is opaque and its fields cannot be accessed directly. * - * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is + * Since: 2.14 */ /** - * g_type_default_interface_unref: - * @g_iface: (type GObject.TypeInterface): the default vtable structure for a interface, as returned by g_type_default_interface_ref() + * GRegexCompileFlags: + * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting. + * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting. + * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting. + * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting. + * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. + * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set. + * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern. + * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. + * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way). + * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches. + * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched. + * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'. + * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'. + * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'. * - * Decrements the reference count for the type corresponding to the - * interface default vtable @g_iface. If the type is dynamic, then - * when no one is using the interface and all references have - * been released, the finalize function for the interface's default - * vtable (the <structfield>class_finalize</structfield> member of - * #GTypeInfo) will be called. + * Flags specifying compile-time options. * - * Since: 2.4 + * Since: 2.14 */ /** - * g_type_module_set_name: - * @module: a #GTypeModule. - * @name: a human-readable name to use in error messages. + * GRegexError: + * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed. + * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed. + * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string. + * @G_REGEX_ERROR_MATCH: The match process failed. + * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16 + * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16 + * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16 + * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16 + * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16 + * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16 + * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16 + * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16 + * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16 + * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16 + * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16 + * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16 + * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16 + * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16 + * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16 + * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16 + * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16 + * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16 + * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16 + * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16 + * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16 + * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16 + * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16 + * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16 + * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16 + * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16 + * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16 + * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16 + * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16 + * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16 + * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16 + * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16 + * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16 + * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16 + * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16 + * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16 * - * Sets the name for a #GTypeModule + * Error codes returned by regular expressions functions. + * + * Since: 2.14 */ /** - * g_param_spec_int64: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * GRegexEvalCallback: + * @match_info: the #GMatchInfo generated by the match. Use g_match_info_get_regex() and g_match_info_get_string() if you need the #GRegex or the matched string. + * @result: a #GString containing the new string + * @user_data: user data passed to g_regex_replace_eval() * - * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. - * See g_param_spec_internal() for details on property names. + * Specifies the type of the function passed to g_regex_replace_eval(). + * It is called for each occurance of the pattern in the string passed + * to g_regex_replace_eval(), and it should append the replacement to * - * Returns: a newly created parameter specification + * Returns: %FALSE to continue the replacement process, %TRUE to stop it + * Since: 2.14 */ /** - * g_enum_get_value_by_nick: - * @enum_class: a #GEnumClass - * @nick: the nickname to look up + * GRegexMatchFlags: + * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. + * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A". + * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z". + * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b". + * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match(). + * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator. + * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator. + * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator. + * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized. * - * Looks up a #GEnumValue by nickname. - * enumeration doesn't have a member with that nickname + * Flags specifying match-time options. * - * Returns: the #GEnumValue with nickname @nick, or %NULL if the + * Since: 2.14 */ /** - * g_value_set_double: - * @value: a valid #GValue of type %G_TYPE_DOUBLE - * @v_double: double value to be set + * GSignalAccumulator: + * @ihint: Signal invocation hint, see #GSignalInvocationHint. + * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission. + * @handler_return: A #GValue holding the return value of the signal handler. + * @data: Callback data that was specified when creating the signal. * - * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. + * 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. + * should be aborted. Returning %FALSE means to abort the + * current emission and %TRUE is returned for continuation. + * + * Returns: The accumulator function returns whether the signal emission */ /** - * SECTION:generic_value: - * @short_description: A polymorphic type that can hold values of any other type - * @see_also: The fundamental types which all support #GValue operations and thus can be used as a type initializer for g_value_init() are defined by a separate interface. See the <link linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values API</link> for details. - * @title: Generic values + * GSignalCMarshaller: * - * 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 a 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. - * 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 - * provided by this interface. - * The code in the example program below demonstrates #GValue's - * features. - * |[ - * #include <glib-object.h> - * static void - * int2string (const GValue *src_value, - * GValue *dest_value) - * { - * if (g_value_get_int (src_value) == 42) - * g_value_set_static_string (dest_value, "An important number"); - * else - * g_value_set_static_string (dest_value, "What's that?"); - * } - * int - * main (int argc, - * char *argv[]) - * { - * /* GValues must start zero-filled */ - * GValue a = {0}; - * GValue b = {0}; - * const gchar *message; - * g_type_init (); - * /* The GValue starts empty */ - * g_assert (!G_VALUE_HOLDS_STRING (&a)); - * /* Put a string in it */ - * g_value_init (&a, G_TYPE_STRING); - * g_assert (G_VALUE_HOLDS_STRING (&a)); - * g_value_set_static_string (&a, "Hello, world!"); - * g_printf ("%s\n", g_value_get_string (&a)); - * /* Reset it to its pristine state */ - * g_value_unset (&a); - * /* It can then be reused for another type */ - * g_value_init (&a, G_TYPE_INT); - * g_value_set_int (&a, 42); - * /* Attempt to transform it into a GValue of type STRING */ - * g_value_init (&b, G_TYPE_STRING); - * /* An INT is transformable to a STRING */ - * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); - * /* Attempt to transform it again using a custom transform function */ - * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); - * g_value_transform (&a, &b); - * g_printf ("%s\n", g_value_get_string (&b)); - * return 0; - * } - * ]| + * 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. */ /** - * G_TYPE_CHECK_VALUE: - * @value: a #GValue + * GSignalEmissionHook: + * @ihint: Signal invocation hint, see #GSignalInvocationHint. + * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. + * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. + * @data: user data associated with the hook. * - * Checks if @value has been initialized to hold values - * of a value type. - * This macro should only be used in type implementations. + * 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. + * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. + * hook is disconnected (and destroyed). * - * Returns: %TRUE on success. + * Returns: whether it wants to stay connected. If it returns %FALSE, the signal */ /** - * G_DEFINE_POINTER_TYPE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * - * A convenience macro for pointer type implementations, which defines a - * type_name_get_type() function registering the pointer type. + * GSignalFlags: + * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. + * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. + * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. + * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. + * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions. + * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code. + * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. * - * Since: 2.26 + * 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. */ /** - * g_value_set_instance: - * @value: An initialized #GValue structure. - * @instance: the instance + * GSignalInvocationHint: + * @signal_id: The signal id of the signal invoking the callback + * @detail: The detail passed on for this emission + * @run_type: 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. * - * Sets @value from an instantiatable type via the - * value_table's collect_value() function. + * The #GSignalInvocationHint structure is used to pass on additional information + * to callbacks during a signal emission. */ /** - * g_type_free_instance: - * @instance: an instance of a type. + * GSignalMatchType: + * @G_SIGNAL_MATCH_ID: The signal id must be equal. + * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal. + * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same. + * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. + * @G_SIGNAL_MATCH_DATA: The closure data must be the same. + * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. * - * Frees an instance of a type, returning it to the instance pool for - * the type, if there is one. - * Like g_type_create_instance(), this function is reserved for - * implementors of fundamental types. + * The match types specify what g_signal_handlers_block_matched(), + * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() + * match signals by. */ /** - * GChecksum: - * - * An opaque structure representing a checksumming operation. - * To create a new GChecksum, use g_checksum_new(). To free - * a GChecksum, use g_checksum_free(). + * GSignalQuery: + * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown. + * @signal_name: The signal name. + * @itype: The interface/instance type that this signal can be emitted for. + * @signal_flags: The signal flags as passed in to g_signal_new(). + * @return_type: The return type for user callbacks. + * @n_params: The number of parameters that user callbacks take. + * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting> * - * Since: 2.16 + * A structure holding in-depth information for a specific signal. It is + * filled in by the g_signal_query() function. */ /** - * g_type_plugin_complete_interface_info: - * @plugin: the #GTypePlugin - * @instance_type: the #GType of an instantiable type to which the interface is added - * @interface_type: the #GType of the interface whose info is completed - * @info: the #GInterfaceInfo to fill in + * GSource: * - * Calls the @complete_interface_info function from the - * #GTypePluginClass of @plugin. There should be no need to use this - * function outside of the GObject type system itself. + * The <structname>GSource</structname> struct is an opaque data type + * representing an event source. */ /** - * G_CALLBACK: - * @f: a function pointer. + * GSourceCallbackFuncs: + * @ref: Called when a reference is added to the callback object + * @unref: Called when a reference to the callback object is dropped + * @get: Called to extract the callback function and data from the callback object. * - * Cast a function pointer to a #GCallback. + * The <structname>GSourceCallbackFuncs</structname> struct contains + * functions for managing callback objects. */ /** - * g_signal_chain_from_overridden: - * @instance_and_params: the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. - * @return_value: Location for the return value. + * GSourceFuncs: + * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the + * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here. + * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source. + * @finalize: Called when the source is finalized. * - * Calls the original class closure of a signal. This function should only - * be called from an overridden class closure; see - * g_signal_override_class_closure() and - * g_signal_override_class_handler(). + * The <structname>GSourceFuncs</structname> struct contains a table of + * functions used to handle event sources in a generic manner. + * For idle sources, the prepare and check functions always return %TRUE + * to indicate that the source is always ready to be processed. The prepare + * function also returns a timeout value of 0 to ensure that the poll() call + * doesn't block (since that would be time wasted which could have been spent + * running the idle function). + * For timeout sources, the prepare and check functions both return %TRUE + * if the timeout interval has expired. The prepare function also returns + * a timeout value to ensure that the poll() call doesn't block too long + * and miss the next timeout. + * For file descriptor sources, the prepare function typically returns %FALSE, + * since it must wait until poll() has been called before it knows whether + * any events need to be processed. It sets the returned timeout to -1 to + * indicate that it doesn't mind how long the poll() call blocks. In the + * check function, it tests the results of the poll() call to see if the + * required condition has been met, and returns %TRUE if so. */ /** - * G_TYPE_INT: + * GStrv: * - * The fundamental type corresponding to #gint. + * A C representable type name for #G_TYPE_STRV. */ /** - * g_source_set_dummy_callback: - * @source: the source + * GTestLogFatalFunc: + * @log_domain: the log domain of the message + * @log_level: the log level of the message (including the fatal and recursion flags) + * @message: the message to process + * @user_data: user data, set in g_test_log_set_fatal_handler() * - * Sets a dummy callback for @source. The callback will do nothing, and - * if the source expects a #gboolean return value, it will return %TRUE. - * (If the source expects any other type of return value, it will return - * a 0/%NULL value; whatever g_value_init() initializes a #GValue to for - * that type.) - * If the source is not one of the standard GLib types, the - * structure must have been filled in with pointers to appropriate - * functions. + * Specifies the prototype of fatal log handler functions. + * + * Returns: %TRUE if the program should abort, %FALSE otherwise + * Since: 2.22 */ /** - * g_value_set_gtype: - * @value: a valid #GValue of type %G_TYPE_GTYPE - * @v_gtype: #GType to be set + * GTimeSpan: * - * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. + * A value representing an interval of time, in microseconds. * - * Since: 2.12 + * Since: 2.26 */ /** - * g_value_fits_pointer: - * @value: An initialized #GValue structure. - * - * Determines if @value will fit inside the size of a pointer value. - * This is an internal function introduced mainly for C marshallers. + * GTimeType: + * @G_TIME_TYPE_STANDARD: the time is in local standard time + * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time + * @G_TIME_TYPE_UNIVERSAL: the time is in UTC * - * Returns: %TRUE if @value will fit inside a pointer value. + * Disambiguates a given time in two ways. + * First, specifies if the given time is in universal or local time. + * Second, if the time is in local time, specifies if it is local + * standard time or local daylight time. This is important for the case + * where the same local time occurs twice (during daylight savings time + * transitions, for example). */ /** - * G_VALUE_HOLDS_OBJECT: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. + * GToggleNotify: + * @data: Callback data passed to g_object_add_toggle_ref() + * @object: The object on which g_object_add_toggle_ref() was called. + * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references. * - * Returns: %TRUE on success. + * A callback function used for notification when the state + * of a toggle reference changes. See g_object_add_toggle_ref(). */ /** - * G_IS_PARAM_SPEC_UINT64: - * @pspec: a valid #GParamSpec instance + * GTranslateFunc: + * @str: the untranslated string + * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func() * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. + * The type of functions which are used to translate user-visible + * strings, for <option>--help</option> output. + * The returned string is owned by GLib and must not be freed. * - * Returns: %TRUE on success. + * Returns: a translation of the string for the current locale. */ /** - * G_TYPE_PARAM_POINTER: + * GType: * - * The #GType of #GParamSpecPointer. + * A numerical value which represents the unique identifier of a registered + * type. */ /** - * g_node_prepend_data: - * @parent: the #GNode to place the new #GNode under - * @data: the data for the new #GNode - * - * Inserts a new #GNode as the first child of the given parent. + * GTypeCValue: + * @v_int: the field for holding integer values + * @v_long: the field for holding long integer values + * @v_int64: the field for holding 64 bit integer values + * @v_double: the field for holding floating point values + * @v_pointer: the field for holding pointers * - * Returns: the new #GNode + * A union holding one collected value. */ /** - * G_VARIANT_TYPE_INT64: + * GTypeClass: * - * The type of an integer value that can range from - * -9223372036854775808 to 9223372036854775807. + * An opaque structure used as the base of all classes. */ /** - * G_TYPE_HASH_TABLE: + * GTypeClassCacheFunc: + * @cache_data: data that was given to the g_type_add_class_cache_func() call + * @g_class: The #GTypeClass structure which is unreferenced * - * The #GType for a boxed type holding a #GHashTable reference. + * 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. + * 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 + * classes are routed through the same #GTypeClassCacheFunc chain. + * called, %FALSE to continue. * - * Since: 2.10 + * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being */ /** - * G_PARAM_SPEC_PARAM: - * @pspec: a valid #GParamSpec instance + * GTypeDebugFlags: + * @G_TYPE_DEBUG_NONE: Print no messages. + * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping. + * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions. + * @G_TYPE_DEBUG_MASK: Mask covering all debug flags. * - * Casts a #GParamSpec instance into a #GParamSpecParam. + * The <type>GTypeDebugFlags</type> enumeration values can be passed to + * g_type_init_with_debug_flags() to trigger debugging messages during runtime. + * Note that the messages can also be triggered by setting the + * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of + * "objects" and "signals". */ /** - * G_IS_PARAM_SPEC_ENUM: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. + * GTypeFlags: + * @G_TYPE_FLAG_ABSTRACT: Indicates an abstract type. No instances can be created for an abstract type. + * @G_TYPE_FLAG_VALUE_ABSTRACT: Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init(). * - * Returns: %TRUE on success. + * Bit masks used to check or determine characteristics of a type. */ /** - * g_type_module_use: - * @module: a #GTypeModule - * - * Increases the use count of a #GTypeModule by one. If the - * use count was zero before, the plugin will be loaded. - * If loading the plugin fails, the use count is reset to - * its prior value. - * loading the plugin failed. + * GTypeFundamentalFlags: + * @G_TYPE_FLAG_CLASSED: Indicates a classed type. + * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). + * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. + * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). * - * Returns: %FALSE if the plugin needed to be loaded and + * Bit masks used to check or determine specific characteristics of a + * fundamental type. */ /** - * GMainLoop: + * GTypeFundamentalInfo: + * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type * - * The <structname>GMainLoop</structname> struct is an opaque data type - * representing the main event loop of a GLib or GTK+ application. + * A structure that provides information to the type system which is + * used specifically for managing fundamental types. */ /** - * G_VARIANT_TYPE_OBJECT_PATH: + * GTypeInfo: + * @class_size: Size of the class structure (required for interface, classed and instantiatable types). + * @base_init: Location of the base initialization function (optional). + * @base_finalize: Location of the base finalization function (optional). + * @class_init: Location of the class initialization function for classed and instantiatable types. Location of the default vtable inititalization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties. + * @class_finalize: Location of the class finalization function for classed and instantiatable types. Location fo the default vtable finalization function for interface types. (optional) + * @class_data: User-supplied data passed to the class init/finalize functions. + * @instance_size: Size of the instance (object) structure (required for instantiatable types only). + * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. + * @instance_init: Location of the instance initialization function (optional, for instantiatable types only). + * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types). * - * The type of a DBus object reference. These are strings of a - * specific format used to identify objects at a given destination on - * the bus. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. If you are, then the DBus specification contains a - * precise description of valid object paths. + * This structure is used to provide the type system with the information + * required to initialize and destruct (finalize) a type's class and + * its instances. + * The initialized structure is passed to the g_type_register_static() function + * (or is copied into the provided #GTypeInfo structure in the + * g_type_plugin_complete_type_info()). The type system will perform a deep + * copy of this structure, so its memory does not need to be persistent + * across invocation of g_type_register_static(). */ /** - * g_closure_new_object: - * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> - * @object: a #GObject pointer to store in the @data field of the newly allocated #GClosure - * - * A variant of g_closure_new_simple() which stores @object in the - * when implementing new types of closures. + * GTypeInstance: * - * Returns: (transfer full): a newly allocated #GClosure + * An opaque structure used as the base of all type instances. */ /** - * g_object_class_install_property: - * @oclass: a #GObjectClass - * @property_id: the id for the new property - * @pspec: the #GParamSpec for the new property + * GTypeInterface: * - * Installs a new property. This is usually done in the class initializer. - * Note that it is possible to redefine a property in a derived class, - * by installing a property with the same name. This can be useful at times, - * e.g. to change the range of allowed values or the default value. + * An opaque structure used as the base of all interface types. */ /** - * G_TYPE_INTERFACE: + * GTypeInterfaceCheckFunc: + * @check_data: data passed to g_type_add_interface_check(). + * @g_iface: the interface that has been initialized * - * The fundamental type from which all interfaces are derived. + * A callback called after an interface vtable is initialized. + * See g_type_add_interface_check(). + * + * Since: 2.4 */ /** - * GObject: + * GTypeModule: + * @name: the name of the module * - * All the fields in the <structname>GObject</structname> structure are private - * to the #GObject implementation and should never be accessed directly. + * The members of the <structname>GTypeModule</structname> structure should not + * be accessed directly, except for the @name field. */ /** - * GType: + * GTypeModuleClass: + * @parent_class: the parent class + * @load: loads the module and registers one or more types using g_type_module_register_type(). + * @unload: unloads the module * - * A numerical value which represents the unique identifier of a registered - * type. + * In order to implement dynamic loading of types based on #GTypeModule, + * the @load and @unload functions in #GTypeModuleClass must be implemented. */ /** - * g_signal_name: - * @signal_id: the signal's identifying number. - * - * Given the signal's identifier, finds its name. - * Two different signals may have the same name, if they have differing types. + * GTypePlugin: * - * Returns: the signal name, or %NULL if the signal number was invalid. + * The <structname>GTypePlugin</structname> typedef is used as a placeholder + * for objects that implement the <structname>GTypePlugin</structname> + * interface. */ /** - * g_value_take_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: duplicated unowned boxed value to be set - * - * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed - * and takes over the ownership of the callers reference to @v_boxed; - * the caller doesn't have to unref it any more. + * GTypePluginClass: + * @use_plugin: Increases the use count of the plugin. + * @unuse_plugin: Decreases the use count of the plugin. + * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. + * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. * - * Since: 2.4 + * The #GTypePlugin interface is used by the type system in order to handle + * the lifecycle of dynamically loaded types. */ /** - * SECTION:value_array: - * @short_description: A container structure to maintain an array of generic values - * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array() - * @title: Value arrays + * GTypePluginCompleteInterfaceInfo: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in * - * The prime purpose of a #GValueArray is for it to be used as an - * object property that holds an array of values. A #GValueArray wraps - * an array of #GValue elements in order for it to be used as a boxed - * type through %G_TYPE_VALUE_ARRAY. + * The type of the @complete_interface_info function of #GTypePluginClass. */ /** - * G_VALUE_HOLDS_LONG: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_LONG. + * GTypePluginCompleteTypeInfo: + * @plugin: the #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in * - * Returns: %TRUE on success. + * The type of the @complete_type_info function of #GTypePluginClass. */ /** - * g_value_set_uint: - * @value: a valid #GValue of type %G_TYPE_UINT - * @v_uint: unsigned integer value to be set + * GTypePluginUnuse: + * @plugin: the #GTypePlugin whose use count should be decreased * - * Set the contents of a %G_TYPE_UINT #GValue to @v_uint. + * The type of the @unuse_plugin function of #GTypePluginClass. */ /** - * G_IMPLEMENT_INTERFACE: - * @TYPE_IFACE: The #GType of the interface to add - * @iface_init: The interface init function - * - * A convenience macro to ease interface addition in the @_C_ section - * 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_* - * macros, since it depends on variable names from those macros. + * GTypePluginUse: + * @plugin: the #GTypePlugin whose use count should be increased * - * Since: 2.4 + * The type of the @use_plugin function of #GTypePluginClass, which gets called + * to increase the use count of @plugin. */ /** - * G_PARAM_SPEC_UNICHAR: - * @pspec: a valid #GParamSpec instance + * GTypeQuery: + * @type: the #GType value of the type. + * @type_name: the name of the type. + * @class_size: the size of the class structure. + * @instance_size: the size of the instance structure. * - * Cast a #GParamSpec instance into a #GParamSpecUnichar. + * A structure holding information for a specific type. It is + * filled in by the g_type_query() function. */ /** - * GParamSpecString: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified - * @cset_first: a string containing the allowed values for the first byte - * @cset_nth: a string containing the allowed values for the subsequent bytes - * @substitutor: the replacement byte for bytes which don't match @cset_first or @cset_nth. - * @null_fold_if_empty: replace empty string by %NULL - * @ensure_non_null: replace %NULL strings by an empty string + * GTypeValueTable: + * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]| + * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| + * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| + * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]| + * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'. + * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined. + * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations. + * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]| * - * A #GParamSpec derived structure that contains the meta data for string - * properties. + * The #GTypeValueTable provides the functions required by the #GValue implementation, + * to serve as a container for values of a type. */ /** - * g_cclosure_marshal_VOID__PARAM: - * @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 + * GUserDirectory: + * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory + * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory + * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory + * @G_USER_DIRECTORY_MUSIC: the user's Music directory + * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory + * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory + * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory + * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory + * @G_USER_N_DIRECTORIES: the number of enum values * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>. + * These are logical ids for special directories which are defined + * depending on the platform used. You should use g_get_user_special_dir() + * to retrieve the full path associated to the logical id. + * The #GUserDirectory enumeration can be extended at later date. Not + * every platform has a directory for every logical id in this + * enumeration. + * + * Since: 2.14 */ /** - * g_param_spec_param: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @param_type: a #GType derived from %G_TYPE_PARAM - * @flags: flags for the property specified + * GValue: * - * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM - * property. - * See g_param_spec_internal() for details on property names. + * An opaque structure used to hold different types of values. + * to functions within a #GTypeValueTable structure, or implementations of + * the g_value_*() API. That is, code portions which implement new fundamental + * types. + * #GValue users can not 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. * - * Returns: a newly created parameter specification + * The data within the structure has protected scope: it is accessible only */ /** - * g_param_spec_ulong: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG - * property. - * See g_param_spec_internal() for details on property names. + * GValueArray: + * @n_values: number of values contained in the array + * @values: array of values * - * Returns: a newly created parameter specification + * A #GValueArray contains an array of #GValue elements. */ /** - * G_TYPE_FROM_CLASS: - * @g_class: Location of a valid #GTypeClass structure. - * - * Get the type identifier from a given @class structure. - * This macro should only be used in type implementations. + * GValueTransform: + * @src_value: Source value. + * @dest_value: Target value. * - * Returns: the #GType + * The type of value transformation functions which can be registered with + * g_value_register_transform_func(). */ /** - * g_main_new: - * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_run() will set this to %TRUE anyway. - * - * Creates a new #GMainLoop for th default main context. + * GVariantType: * - * Returns: a new #GMainLoop - * Deprecated: 2.2: Use g_main_loop_new() instead + * A type in the GVariant type system. + * Two types may not be compared by value; use g_variant_type_equal() or + * g_variant_type_is_subtype(). May be copied using + * g_variant_type_copy() and freed using g_variant_type_free(). */ /** - * GPollFD: - * @fd: the file descriptor to poll (or a <type>HANDLE</type> on Win32) - * @events: a bitwise combination from #GIOCondition, specifying which events should be polled for. Typically for reading from a file descriptor you would use %G_IO_IN | %G_IO_HUP | %G_IO_ERR, and for writing you would use %G_IO_OUT | %G_IO_ERR. - * @revents: a bitwise combination of flags from #GIOCondition, returned from the poll() function to indicate which events occurred. - * + * GWeakNotify: + * @data: data that was provided when the weak reference was established + * @where_the_object_was: the object being finalized * + * 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 adress as hash-index or the like. */ /** - * GParamSpecChar: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_BOOKMARK_FILE_ERROR: * - * A #GParamSpec derived structure that contains the meta data for character properties. + * Error domain for bookmark file parsing. + * Errors in this domain will be from the #GBookmarkFileError + * enumeration. See #GError for information on error domains. */ /** - * G_TYPE_IS_FLAGS: - * @type: a #GType ID. - * - * Checks whether @type "is a" %G_TYPE_FLAGS. + * G_CALLBACK: + * @f: a function pointer. * - * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS. + * Cast a function pointer to a #GCallback. */ /** - * g_flags_register_static: - * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. + * G_CCLOSURE_SWAP_DATA: + * @cclosure: a #GCClosure * - * Registers a new static flags type with the name @name. - * It is normally more convenient to let <link - * linkend="glib-mkenums">glib-mkenums</link> generate a - * my_flags_get_type() function from a usual C enumeration definition - * than to write one yourself using g_flags_register_static(). + * Checks whether the user data of the #GCClosure should be passed as the + * first parameter to the callback. See g_cclosure_new_swap(). * - * Returns: The new type identifier. + * Returns: %TRUE if data has to be swapped. */ /** - * g_type_init_with_debug_flags: - * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. + * G_CLOSURE_NEEDS_MARSHAL: + * @closure: a #GClosure * - * Similar to g_type_init(), but additionally sets debug flags. + * Check if the closure still needs a marshaller. See g_closure_set_marshal(). + * + * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on */ /** - * g_value_get_char: - * @value: a valid #GValue of type %G_TYPE_CHAR + * G_CLOSURE_N_NOTIFIERS: + * @cl: a #GClosure * - * Get the contents of a %G_TYPE_CHAR #GValue. + * 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(), + * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). * - * Returns: character contents of @value + * Returns: number of notifiers */ /** - * g_type_class_add_private: - * @g_class: class structure for an instantiatable type - * @private_size: size of private structure. - * - * Registers a private structure for an instantiatable type. - * When an object is allocated, the private structures for - * the type and all of its parent types are allocated - * sequentially in the same memory block as the public - * structures. - * Note that the accumulated size of the private structures of - * a type and all its parent types cannot excced 64kB. - * This function should be called in the type's class_init() function. - * The private structure can be retrieved using the - * G_TYPE_INSTANCE_GET_PRIVATE() macro. - * The following example shows attaching a private structure - * <structname>MyObjectPrivate</structname> to an object - * <structname>MyObject</structname> defined in the standard GObject - * fashion. - * type's class_init() function. - * |[ - * typedef struct _MyObject MyObject; - * typedef struct _MyObjectPrivate MyObjectPrivate; - * struct _MyObject { - * GObject parent; - * MyObjectPrivate *priv; - * }; - * struct _MyObjectPrivate { - * int some_field; - * }; - * static void - * my_object_class_init (MyObjectClass *klass) - * { - * g_type_class_add_private (klass, sizeof (MyObjectPrivate)); - * } - * static void - * my_object_init (MyObject *my_object) - * { - * my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, - * MY_TYPE_OBJECT, - * MyObjectPrivate); - * } - * static int - * my_object_get_some_field (MyObject *my_object) - * { - * MyObjectPrivate *priv = my_object->priv; - * return priv->some_field; - * } - * ]| + * G_CONVERT_ERROR: * - * Since: 2.4 + * Error domain for character set conversions. Errors in this domain will + * be from the #GConvertError enumeration. See #GError for information on + * error domains. */ /** - * G_TYPE_PARAM_INT: + * G_DATALIST_FLAGS_MASK: * - * The #GType of #GParamSpecInt. + * A bitmask that restricts the possible flags passed to + * g_datalist_set_flags(). Passing a flags value where + * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. */ /** - * G_REGEX_ERROR: + * G_DEFINE_ABSTRACT_TYPE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. * - * Error domain for regular expressions. Errors in this domain will be - * from the #GRegexError enumeration. See #GError for information on - * error domains. + * A convenience macro for type implementations. + * Similar to G_DEFINE_TYPE(), but defines an abstract type. + * See G_DEFINE_TYPE_EXTENDED() for an example. * - * Since: 2.14 + * Since: 2.4 */ /** - * G_TYPE_IS_VALUE_TYPE: - * @type: A #GType value. + * G_DEFINE_ABSTRACT_TYPE_WITH_CODE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_C_: Custom code that gets inserted in the @type_name_get_type() function. * - * Checks if @type is a value type and can be used with g_value_init(). + * 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. interface implementations + * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. * - * Returns: %TRUE on success. + * Since: 2.4 */ /** - * GObjectConstructParam: - * @pspec: the #GParamSpec of the construct parameter - * @value: the value to set the parameter to + * G_DEFINE_BOXED_TYPE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @copy_func: the #GBoxedCopyFunc for the new type + * @free_func: the #GBoxedFreeFunc for the new type * - * The <structname>GObjectConstructParam</structname> struct is an auxiliary - * structure used to hand #GParamSpec/#GValue pairs to the @constructor of - * a #GObjectClass. + * A convenience macro for boxed type implementations, which defines a + * type_name_get_type() function registering the boxed type. + * + * Since: 2.26 */ /** - * g_type_get_qdata: - * @type: a #GType - * @quark: a #GQuark id to identify the data + * G_DEFINE_BOXED_TYPE_WITH_CODE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @copy_func: the #GBoxedCopyFunc for the new type + * @free_func: the #GBoxedFreeFunc for the new type + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Obtains data which has previously been attached to @type - * with g_type_set_qdata(). + * 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 + * g_value_register_transform_func(). * - * Returns: (transfer none): the data, or %NULL if no data was found + * Since: 2.26 */ @@ -1984,1537 +2034,1160 @@ /** - * gchararray: - * - * A C representable type name for #G_TYPE_STRING. - */ - - -/** - * G_PARAM_SPEC_UINT: - * @pspec: a valid #GParamSpec instance - * - * Cast a #GParamSpec instance into a #GParamSpecUInt. - */ - - -/** - * GPollFunc: - * @ufds: an array of #GPollFD elements - * @nfsd: the number of elements in @ufds - * @timeout_: the maximum time to wait for an event of the file descriptors. A negative value indicates an infinite timeout. + * G_DEFINE_DYNAMIC_TYPE_EXTENDED: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @TYPE_PARENT: The #GType of the parent type. + * @flags: #GTypeFlags to pass to g_type_module_register_type() + * @CODE: Custom code that gets inserted in the *_get_type() function. * - * Specifies the type of function passed to g_main_context_set_poll_func(). - * The semantics of the function should match those of the poll() system call. - * reported, or -1 if an error occurred. + * A more general version of G_DEFINE_DYNAMIC_TYPE() which + * allows to specify #GTypeFlags and custom code. + * |[ + * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, + * gtk_gadget, + * GTK_TYPE_THING, + * 0, + * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, + * gtk_gadget_gizmo_init)); + * ]| + * expands to + * |[ + * static void gtk_gadget_init (GtkGadget *self); + * static void gtk_gadget_class_init (GtkGadgetClass *klass); + * static void gtk_gadget_class_finalize (GtkGadgetClass *klass); + * static gpointer gtk_gadget_parent_class = NULL; + * static GType gtk_gadget_type_id = 0; + * static void gtk_gadget_class_intern_init (gpointer klass) + * { + * gtk_gadget_parent_class = g_type_class_peek_parent (klass); + * gtk_gadget_class_init ((GtkGadgetClass*) klass); + * } + * GType + * gtk_gadget_get_type (void) + * { + * return gtk_gadget_type_id; + * } + * static void + * gtk_gadget_register_type (GTypeModule *type_module) + * { + * const GTypeInfo g_define_type_info = { + * sizeof (GtkGadgetClass), + * (GBaseInitFunc) NULL, + * (GBaseFinalizeFunc) NULL, + * (GClassInitFunc) gtk_gadget_class_intern_init, + * (GClassFinalizeFunc) gtk_gadget_class_finalize, + * NULL, // class_data + * sizeof (GtkGadget), + * 0, // n_preallocs + * (GInstanceInitFunc) gtk_gadget_init, + * NULL // value_table + * }; + * gtk_gadget_type_id = g_type_module_register_type (type_module, + * GTK_TYPE_THING, + * GtkGadget, + * &g_define_type_info, + * (GTypeFlags) flags); + * { + * const GInterfaceInfo g_implement_interface_info = { + * (GInterfaceInitFunc) gtk_gadget_gizmo_init + * }; + * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); + * } + * } + * ]| * - * Returns: the number of #GPollFD elements which have events or errors + * Since: 2.14 */ /** - * G_IS_PARAM_SPEC_FLOAT: - * @pspec: a valid #GParamSpec instance + * G_DEFINE_INTERFACE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. + * A convenience macro for #GTypeInterface definitions, which declares + * a default vtable initialization function and defines a *_get_type() + * function. + * The macro expects the interface initialization function to have the + * name <literal>t_n ## _default_init</literal>, and the interface + * structure to have the name <literal>TN ## Interface</literal>. * - * Returns: %TRUE on success. + * Since: 2.24 */ /** - * G_DEFINE_ABSTRACT_TYPE: + * G_DEFINE_INTERFACE_WITH_CODE: * @TN: The name of the new type, in Camel case. * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. + * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * A convenience macro for type implementations. - * Similar to G_DEFINE_TYPE(), but defines an abstract type. - * See G_DEFINE_TYPE_EXTENDED() for an example. + * 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(). * - * Since: 2.4 + * Since: 2.24 */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO: + * G_DEFINE_POINTER_TYPE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. * - * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:". - */ - - -/** - * G_TYPE_PARAM_FLAGS: + * A convenience macro for pointer type implementations, which defines a + * type_name_get_type() function registering the pointer type. * - * The #GType of #GParamSpecFlags. + * Since: 2.26 */ /** - * g_binding_get_flags: - * @binding: a #GBinding + * G_DEFINE_POINTER_TYPE_WITH_CODE: + * @TypeName: The name of the new type, in Camel case. + * @type_name: The name of the new type, in lowercase, with words separated by '_'. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Retrieves the flags passed when constructing the #GBinding + * 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. * - * Returns: the #GBindingFlags used by the #GBinding * Since: 2.26 */ /** - * g_param_spec_gtype: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @is_a_type: a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) - * @flags: flags for the property specified - * - * Creates a new #GParamSpecGType instance specifying a - * %G_TYPE_GTYPE property. - * See g_param_spec_internal() for details on property names. + * G_DEFINE_TYPE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. * - * Since: 2.10 - * Returns: a newly created parameter specification - */ - - -/** - * G_TYPE_PARAM_UCHAR: + * 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. See G_DEFINE_TYPE_EXTENDED() for an example. * - * The #GType of #GParamSpecUChar. + * Since: 2.4 */ /** - * g_signal_new_class_handler: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_handler: a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. - * @n_params: the number of parameter types to follow. - * @...: a list of types, one for each parameter. + * G_DEFINE_TYPE_EXTENDED: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type, in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_f_: #GTypeFlags to pass to g_type_register_static() + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Creates a new signal. (This is usually done in the class initializer.) - * This is a variant of g_signal_new() that takes a C callback instead - * off a class offset for the signal's class handler. This function - * doesn't need a function pointer exposed in the class structure of - * an object definition, instead the function pointer is passed - * directly and can be overriden by derived classes with - * g_signal_override_class_closure() or - * g_signal_override_class_handler()and chained to with - * g_signal_chain_from_overridden() or - * g_signal_chain_from_overridden_handler(). - * See g_signal_new() for information about signal names. + * The most general convenience macro for type implementations, on which + * G_DEFINE_TYPE(), etc are based. + * |[ + * G_DEFINE_TYPE_EXTENDED (GtkGadget, + * gtk_gadget, + * GTK_TYPE_WIDGET, + * 0, + * G_IMPLEMENT_INTERFACE (TYPE_GIZMO, + * gtk_gadget_gizmo_init)); + * ]| + * expands to + * |[ + * static void gtk_gadget_init (GtkGadget *self); + * static void gtk_gadget_class_init (GtkGadgetClass *klass); + * static gpointer gtk_gadget_parent_class = NULL; + * static void gtk_gadget_class_intern_init (gpointer klass) + * { + * gtk_gadget_parent_class = g_type_class_peek_parent (klass); + * gtk_gadget_class_init ((GtkGadgetClass*) klass); + * } + * 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)) + * { + * GType g_define_type_id = + * g_type_register_static_simple (GTK_TYPE_WIDGET, + * g_intern_static_string ("GtkGadget"), + * sizeof (GtkGadgetClass), + * (GClassInitFunc) gtk_gadget_class_intern_init, + * sizeof (GtkGadget), + * (GInstanceInitFunc) gtk_gadget_init, + * (GTypeFlags) flags); + * { + * static const GInterfaceInfo g_implement_interface_info = { + * (GInterfaceInitFunc) gtk_gadget_gizmo_init + * }; + * 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); + * } + * return g_define_type_id__volatile; + * } + * ]| + * 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. * - * Returns: the signal id - * Since: 2.18 + * Since: 2.4 */ /** - * G_PARAM_SPEC_FLOAT: - * @pspec: a valid #GParamSpec instance + * G_DEFINE_TYPE_WITH_CODE: + * @TN: The name of the new type, in Camel case. + * @t_n: The name of the new type in lowercase, with words separated by '_'. + * @T_P: The #GType of the parent type. + * @_C_: Custom code that gets inserted in the *_get_type() function. * - * Cast a #GParamSpec instance into a #GParamSpecFloat. + * 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(). + * See G_DEFINE_TYPE_EXTENDED() for an example. + * + * Since: 2.4 */ /** - * G_IS_INITIALLY_UNOWNED: - * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. + * G_ENUM_CLASS: + * @class: a valid #GEnumClass * - * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. + * Casts a derived #GEnumClass structure into a #GEnumClass structure. */ /** - * g_param_value_validate: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec + * G_ENUM_CLASS_TYPE: + * @class: a #GEnumClass * - * Ensures that the contents of @value comply with the specifications - * set out by @pspec. For example, a #GParamSpecInt might require - * that integers stored in @value may not be smaller than -42 and not be - * greater than +42. If @value contains an integer outside of this range, - * it is modified accordingly, so the resulting value will fit into the - * range -42 .. +42. + * Get the type identifier from a given #GEnumClass structure. * - * Returns: whether modifying @value was necessary to ensure validity + * Returns: the #GType */ /** - * g_signal_handlers_unblock_matched: - * @instance: The instance to unblock handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * G_ENUM_CLASS_TYPE_NAME: + * @class: a #GEnumClass * - * Unblocks all handlers on an instance that match a certain selection - * criteria. The criteria mask is passed as an OR-ed combination of - * #GSignalMatchType flags, and the criteria values are passed as arguments. - * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC - * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. - * If no handlers were found, 0 is returned, the number of unblocked handlers - * otherwise. The match criteria should not apply to any handlers that are - * not currently blocked. + * Get the static type name from a given #GEnumClass structure. * - * Returns: The number of handlers that matched. + * Returns: the type name. */ /** - * g_signal_handler_find: - * @instance: The instance owning the signal handler to be found. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. - * @signal_id: Signal the handler has to be connected to. - * @detail: Signal detail the handler has to be connected to. - * @closure: The closure the handler will invoke. - * @func: The C closure callback of the handler (useless for non-C closures). - * @data: The closure data of the handler's closure. - * - * Finds the first signal handler that matches certain selection criteria. - * The criteria mask is passed as an OR-ed combination of #GSignalMatchType - * flags, and the criteria values are passed as arguments. - * The match @mask has to be non-0 for successful matches. - * If no handler was found, 0 is returned. + * G_FLAGS_CLASS: + * @class: a valid #GFlagsClass * - * Returns: A valid non-0 signal handler id for a successful match. + * Casts a derived #GFlagsClass structure into a #GFlagsClass structure. */ /** - * G_TYPE_INITIALLY_UNOWNED: + * G_FLAGS_CLASS_TYPE: + * @class: a #GFlagsClass * - * The type for #GInitiallyUnowned. + * Get the type identifier from a given #GFlagsClass structure. + * + * Returns: the #GType */ /** - * g_value_init: - * @value: A zero-filled (uninitialized) #GValue structure. - * @g_type: Type the #GValue should hold values of. + * G_FLAGS_CLASS_TYPE_NAME: + * @class: a #GFlagsClass * - * Initializes @value with the default value of @type. + * Get the static type name from a given #GFlagsClass structure. * - * Returns: (transfer none): the #GValue structure that has been passed in + * Returns: the type name. */ /** - * G_TYPE_DATE_TIME: + * G_IMPLEMENT_INTERFACE: + * @TYPE_IFACE: The #GType of the interface to add + * @iface_init: The interface init function * - * The #GType for a boxed type holding a #GDateTime. + * A convenience macro to ease interface addition in the @_C_ section + * 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_* + * macros, since it depends on variable names from those macros. * - * Since: 2.26 + * Since: 2.4 */ /** - * g_object_class_list_properties: - * @oclass: a #GObjectClass - * @n_properties: (out): return location for the length of the returned array + * G_IMPLEMENT_INTERFACE_DYNAMIC: + * @TYPE_IFACE: The #GType of the interface to add + * @iface_init: The interface init function * - * Get an array of #GParamSpec* for all properties of a class. - * #GParamSpec* which should be freed after use + * 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. + * Note that this macro can only be used together with the + * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable + * names from that macro. * - * Returns: (array length=n_properties) (transfer container): an array of + * Since: 2.24 */ /** - * GParamSpecLong: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_INITIALLY_UNOWNED: + * @object: Object which is subject to casting. * - * A #GParamSpec derived structure that contains the meta data for long integer properties. + * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) + * pointer. Depending on the current debugging level, this function may invoke + * certain runtime checks to identify invalid casts. */ /** - * g_cclosure_marshal_VOID__BOXED: - * @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 + * G_INITIALLY_UNOWNED_CLASS: + * @class: a valid #GInitiallyUnownedClass * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>. + * Casts a derived #GInitiallyUnownedClass structure into a + * #GInitiallyUnownedClass structure. */ /** - * g_param_spec_pool_lookup: - * @pool: a #GParamSpecPool - * @param_name: the name to look for - * @owner_type: the owner to look for - * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. + * G_INITIALLY_UNOWNED_GET_CLASS: + * @object: a #GInitiallyUnowned instance. * - * Looks up a #GParamSpec in the pool. - * matching #GParamSpec was found. + * Get the class structure associated to a #GInitiallyUnowned instance. * - * Returns: (transfer none): The found #GParamSpec, or %NULL if no + * Returns: pointer to object class structure. */ /** - * G_IS_INITIALLY_UNOWNED_CLASS: - * @class: a #GInitiallyUnownedClass + * G_IS_ENUM_CLASS: + * @class: a #GEnumClass * - * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type - * %G_TYPE_INITIALLY_UNOWNED or derived. + * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM + * or derived. */ /** - * g_type_check_instance: - * @instance: A valid #GTypeInstance structure. - * @Returns: #TRUE if @instance is valid, #FALSE otherwise. + * G_IS_FLAGS_CLASS: + * @class: a #GFlagsClass * - * Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() - * macro. + * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS + * or derived. */ /** - * g_closure_invalidate: - * @closure: GClosure to invalidate + * G_IS_INITIALLY_UNOWNED: + * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. * - * 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 - * 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 - * access the closure after calling g_closure_invalidate(), make sure - * that you've previously called g_closure_ref(). - * Note that g_closure_invalidate() will also be called when the - * reference count of a closure drops to zero (unless it has already - * been invalidated before). + * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. */ /** - * G_DEFINE_INTERFACE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. - * @_C_: Custom code that gets inserted in the *_get_type() function. - * - * 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(). + * G_IS_INITIALLY_UNOWNED_CLASS: + * @class: a #GInitiallyUnownedClass * - * Since: 2.24 + * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type + * %G_TYPE_INITIALLY_UNOWNED or derived. */ /** - * GWeakNotify: - * @data: data that was provided when the weak reference was established - * @where_the_object_was: the object being finalized + * G_IS_OBJECT: + * @object: Instance to check for being a %G_TYPE_OBJECT. * - * 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 adress as hash-index or the like. + * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. */ /** - * g_signal_query: - * @signal_id: The signal id of the signal to query information for. - * @query: A user provided structure that is filled in with constant values upon success. + * G_IS_OBJECT_CLASS: + * @class: a #GObjectClass * - * Queries the signal system for in-depth information about a - * specific signal. This function will fill in a user-provided - * structure to hold signal-specific information. If an invalid - * signal id is passed in, the @signal_id member of the #GSignalQuery - * is 0. All members filled into the #GSignalQuery structure should - * be considered constant and have to be left untouched. + * Checks whether @class "is a" valid #GObjectClass structure of type + * %G_TYPE_OBJECT or derived. */ /** - * g_signal_has_handler_pending: - * @instance: the object whose signal handlers are sought. - * @signal_id: the signal id. - * @detail: the detail. - * @may_be_blocked: whether blocked handlers should count as match. - * - * Returns whether there are any handlers connected to @instance for the - * given signal id and detail. - * One example of when you might use this is when the arguments to the - * signal are difficult to compute. A class implementor may opt to not - * emit the signal if no one is attached anyway, thus saving the cost - * of building the arguments. - * otherwise. + * G_IS_PARAM_SPEC: + * @pspec: a #GParamSpec * - * Returns: %TRUE if a handler is connected to the signal, %FALSE + * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM + * or derived. */ /** - * G_PARAM_READWRITE: + * G_IS_PARAM_SPEC_BOOLEAN: + * @pspec: a valid #GParamSpec instance * - * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. + * + * Returns: %TRUE on success. */ /** - * g_param_spec_enum: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @enum_type: a #GType derived from %G_TYPE_ENUM - * @default_value: default value for the property specified - * @flags: flags for the property specified + * G_IS_PARAM_SPEC_BOXED: + * @pspec: a valid #GParamSpec instance * - * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM - * property. - * See g_param_spec_internal() for details on property names. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. * - * Returns: a newly created parameter specification + * Returns: %TRUE on success. */ /** - * G_VALUE_HOLDS_POINTER: - * @value: a valid #GValue structure + * G_IS_PARAM_SPEC_CHAR: + * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. * * Returns: %TRUE on success. */ /** - * g_value_set_long: - * @value: a valid #GValue of type %G_TYPE_LONG - * @v_long: long integer value to be set + * G_IS_PARAM_SPEC_CLASS: + * @pclass: a #GParamSpecClass * - * Set the contents of a %G_TYPE_LONG #GValue to @v_long. + * Checks whether @pclass "is a" valid #GParamSpecClass structure of type + * %G_TYPE_PARAM or derived. */ /** - * G_VALUE_HOLDS_STRING: - * @value: a valid #GValue structure + * G_IS_PARAM_SPEC_DOUBLE: + * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GValue can hold values of type %G_TYPE_STRING. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. * * Returns: %TRUE on success. */ /** - * g_cclosure_marshal_VOID__DOUBLE: - * @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 + * G_IS_PARAM_SPEC_ENUM: + * @pspec: a valid #GParamSpec instance * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>. - */ - - -/** - * g_object_set_valist: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to set - * @var_args: value for the first property, followed optionally by more name/value pairs, followed by %NULL + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. * - * Sets properties on an object. + * Returns: %TRUE on success. */ /** - * G_TYPE_UINT64: + * G_IS_PARAM_SPEC_FLAGS: + * @pspec: a valid #GParamSpec instance * - * The fundamental type corresponding to #guint64. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. + * + * Returns: %TRUE on success. */ /** - * G_FLAGS_CLASS_TYPE_NAME: - * @class: a #GFlagsClass + * G_IS_PARAM_SPEC_FLOAT: + * @pspec: a valid #GParamSpec instance * - * Get the static type name from a given #GFlagsClass structure. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. * - * Returns: the type name. + * Returns: %TRUE on success. */ /** - * G_OPTION_ERROR: + * G_IS_PARAM_SPEC_GTYPE: + * @pspec: a #GParamSpec * - * Error domain for option parsing. Errors in this domain will - * be from the #GOptionError enumeration. See #GError for information on - * error domains. - */ - - -/** - * g_type_plugin_unuse: - * @plugin: a #GTypePlugin + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. * - * Calls the @unuse_plugin function from the #GTypePluginClass of - * the GObject type system itself. + * Since: 2.10 + * Returns: %TRUE on success. */ /** - * g_param_spec_set_qdata: - * @pspec: the #GParamSpec to set store a user data pointer - * @quark: a #GQuark, naming the user data pointer - * @data: an opaque user data pointer + * G_IS_PARAM_SPEC_INT: + * @pspec: a valid #GParamSpec instance * - * Sets an opaque, named pointer on a #GParamSpec. The name is - * specified through a #GQuark (retrieved e.g. via - * g_quark_from_static_string()), and the pointer can be gotten back - * from the @pspec with g_param_spec_get_qdata(). Setting a - * previously set user data pointer, overrides (frees) the old pointer - * set, using %NULL as pointer essentially removes the data stored. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. + * + * Returns: %TRUE on success. */ /** - * g_value_get_int: - * @value: a valid #GValue of type %G_TYPE_INT + * G_IS_PARAM_SPEC_INT64: + * @pspec: a valid #GParamSpec instance * - * Get the contents of a %G_TYPE_INT #GValue. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. * - * Returns: integer contents of @value + * Returns: %TRUE on success. */ /** - * g_type_register_fundamental: - * @type_id: A predefined type identifier. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @finfo: The #GTypeFundamentalInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. + * G_IS_PARAM_SPEC_LONG: + * @pspec: a valid #GParamSpec instance * - * Registers @type_id as the predefined identifier and @type_name as the - * name of a fundamental type. The type system uses the information - * contained in the #GTypeInfo structure pointed to by @info and the - * #GTypeFundamentalInfo structure pointed to by @finfo to manage the - * type and its instances. The value of @flags determines additional - * characteristics of the fundamental type. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. * - * Returns: The predefined type identifier. + * Returns: %TRUE on success. */ /** - * GParamSpecBoolean: - * @parent_instance: private #GParamSpec portion - * @default_value: default value for the property specified + * G_IS_PARAM_SPEC_OBJECT: + * @pspec: a valid #GParamSpec instance * - * A #GParamSpec derived structure that contains the meta data for boolean properties. - */ - - -/** - * GParamSpecUInt: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. * - * A #GParamSpec derived structure that contains the meta data for unsigned integer properties. + * Returns: %TRUE on success. */ /** - * g_param_spec_ref_sink: (skip) - * @pspec: a valid #GParamSpec + * G_IS_PARAM_SPEC_OVERRIDE: + * @pspec: a #GParamSpec * - * Convenience function to ref and sink a #GParamSpec. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. * - * Since: 2.10 - * Returns: the #GParamSpec that was passed into this function + * Since: 2.4 + * Returns: %TRUE on success. */ /** - * g_type_qname: - * @type: Type to return quark of type name for. + * G_IS_PARAM_SPEC_PARAM: + * @pspec: a valid #GParamSpec instance * - * Get the corresponding quark of the type IDs name. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. * - * Returns: The type names quark or 0. + * Returns: %TRUE on success. */ /** - * g_binding_get_target_property: - * @binding: a #GBinding + * G_IS_PARAM_SPEC_POINTER: + * @pspec: a valid #GParamSpec instance * - * Retrieves the name of the property of #GBinding:target used as the target - * of the binding + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. * - * Returns: the name of the target property - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * G_VALUE_HOLDS_ENUM: - * @value: a valid #GValue structure + * G_IS_PARAM_SPEC_STRING: + * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. * * Returns: %TRUE on success. */ /** - * g_param_spec_uint64: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * G_IS_PARAM_SPEC_UCHAR: + * @pspec: a valid #GParamSpec instance * - * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 - * property. - * See g_param_spec_internal() for details on property names. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. * - * Returns: a newly created parameter specification + * Returns: %TRUE on success. */ /** - * g_object_remove_weak_pointer: (skip) - * @object: The object that is weak referenced. - * @weak_pointer_location: (inout): The memory address of a pointer. + * G_IS_PARAM_SPEC_UINT: + * @pspec: a valid #GParamSpec instance * - * Removes a weak reference from @object that was previously added - * using g_object_add_weak_pointer(). The @weak_pointer_location has - * to match the one used with g_object_add_weak_pointer(). - */ - - -/** - * g_value_set_boolean: - * @value: a valid #GValue of type %G_TYPE_BOOLEAN - * @v_boolean: boolean value to be set + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. * - * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. + * Returns: %TRUE on success. */ /** - * g_param_spec_boxed: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @boxed_type: %G_TYPE_BOXED derived type of this property - * @flags: flags for the property specified + * G_IS_PARAM_SPEC_UINT64: + * @pspec: a valid #GParamSpec instance * - * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED - * derived property. - * See g_param_spec_internal() for details on property names. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. * - * Returns: a newly created parameter specification + * Returns: %TRUE on success. */ /** - * G_IS_PARAM_SPEC_INT: + * G_IS_PARAM_SPEC_ULONG: * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. * * Returns: %TRUE on success. */ /** - * g_value_get_enum: - * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM + * G_IS_PARAM_SPEC_UNICHAR: + * @pspec: a valid #GParamSpec instance * - * Get the contents of a %G_TYPE_ENUM #GValue. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. * - * Returns: enum contents of @value + * Returns: %TRUE on success. */ /** - * g_signal_connect_data: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. - * @destroy_data: a #GClosureNotify for @data. - * @connect_flags: a combination of #GConnectFlags. + * G_IS_PARAM_SPEC_VALUE_ARRAY: + * @pspec: a valid #GParamSpec instance * - * Connects a #GCallback function to a signal for a particular object. Similar - * to g_signal_connect(), but allows to provide a #GClosureNotify for the data - * which will be called when the signal handler is disconnected and no longer - * used. Specify @connect_flags if you need <literal>..._after()</literal> or - * <literal>..._swapped()</literal> variants of this function. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. * - * Returns: the handler id + * Returns: %TRUE on success. */ /** - * GBinding: + * G_IS_PARAM_SPEC_VARIANT: + * @pspec: a #GParamSpec * - * <structname>GBinding</structname> is an opaque structure whose members - * cannot be accessed directly. + * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. * + * Returns: %TRUE on success * Since: 2.26 */ /** - * g_param_spec_pointer: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @flags: flags for the property specified + * G_IS_VALUE: + * @value: A #GValue structure. * - * Creates a new #GParamSpecPoiner instance specifying a pointer property. - * See g_param_spec_internal() for details on property names. + * Checks if @value is a valid and initialized #GValue structure. * - * Returns: a newly created parameter specification + * Returns: %TRUE on success. */ /** - * G_PARAM_SPEC_FLAGS: - * @pspec: a valid #GParamSpec instance + * G_MARKUP_ERROR: * - * Cast a #GParamSpec instance into a #GParamSpecFlags. + * Error domain for markup parsing. + * Errors in this domain will be from the #GMarkupError enumeration. + * See #GError for information on error domains. */ /** - * g_signal_connect_after: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. - * - * Connects a #GCallback function to a signal for a particular object. - * The handler will be called after the default handler of the signal. + * G_NODE_IS_LEAF: + * @node: a #GNode * - * Returns: the handler id - */ - - -/** - * g_value_set_char: - * @value: a valid #GValue of type %G_TYPE_CHAR - * @v_char: character value to be set + * Returns %TRUE if a #GNode is a leaf node. + * (i.e. it has no children) * - * Set the contents of a %G_TYPE_CHAR #GValue to @v_char. + * Returns: %TRUE if the #GNode is a leaf node */ /** - * GRegexError: - * @G_REGEX_ERROR_COMPILE: Compilation of the regular expression failed. - * @G_REGEX_ERROR_OPTIMIZE: Optimization of the regular expression failed. - * @G_REGEX_ERROR_REPLACE: Replacement failed due to an ill-formed replacement string. - * @G_REGEX_ERROR_MATCH: The match process failed. - * @G_REGEX_ERROR_INTERNAL: Internal error of the regular expression engine. Since 2.16 - * @G_REGEX_ERROR_STRAY_BACKSLASH: "\\" at end of pattern. Since 2.16 - * @G_REGEX_ERROR_MISSING_CONTROL_CHAR: "\\c" at end of pattern. Since 2.16 - * @G_REGEX_ERROR_UNRECOGNIZED_ESCAPE: Unrecognized character follows "\\". Since 2.16 - * @G_REGEX_ERROR_QUANTIFIERS_OUT_OF_ORDER: Numbers out of order in "{}" quantifier. Since 2.16 - * @G_REGEX_ERROR_QUANTIFIER_TOO_BIG: Number too big in "{}" quantifier. Since 2.16 - * @G_REGEX_ERROR_UNTERMINATED_CHARACTER_CLASS: Missing terminating "]" for character class. Since 2.16 - * @G_REGEX_ERROR_INVALID_ESCAPE_IN_CHARACTER_CLASS: Invalid escape sequence in character class. Since 2.16 - * @G_REGEX_ERROR_RANGE_OUT_OF_ORDER: Range out of order in character class. Since 2.16 - * @G_REGEX_ERROR_NOTHING_TO_REPEAT: Nothing to repeat. Since 2.16 - * @G_REGEX_ERROR_UNRECOGNIZED_CHARACTER: Unrecognized character after "(?", "(?<" or "(?P". Since 2.16 - * @G_REGEX_ERROR_POSIX_NAMED_CLASS_OUTSIDE_CLASS: POSIX named classes are supported only within a class. Since 2.16 - * @G_REGEX_ERROR_UNMATCHED_PARENTHESIS: Missing terminating ")" or ")" without opening "(". Since 2.16 - * @G_REGEX_ERROR_INEXISTENT_SUBPATTERN_REFERENCE: Reference to non-existent subpattern. Since 2.16 - * @G_REGEX_ERROR_UNTERMINATED_COMMENT: Missing terminating ")" after comment. Since 2.16 - * @G_REGEX_ERROR_EXPRESSION_TOO_LARGE: Regular expression too large. Since 2.16 - * @G_REGEX_ERROR_MEMORY_ERROR: Failed to get memory. Since 2.16 - * @G_REGEX_ERROR_VARIABLE_LENGTH_LOOKBEHIND: Lookbehind assertion is not fixed length. Since 2.16 - * @G_REGEX_ERROR_MALFORMED_CONDITION: Malformed number or name after "(?(". Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_CONDITIONAL_BRANCHES: Conditional group contains more than two branches. Since 2.16 - * @G_REGEX_ERROR_ASSERTION_EXPECTED: Assertion expected after "(?(". Since 2.16 - * @G_REGEX_ERROR_UNKNOWN_POSIX_CLASS_NAME: Unknown POSIX class name. Since 2.16 - * @G_REGEX_ERROR_POSIX_COLLATING_ELEMENTS_NOT_SUPPORTED: POSIX collating elements are not supported. Since 2.16 - * @G_REGEX_ERROR_HEX_CODE_TOO_LARGE: Character value in "\\x{...}" sequence is too large. Since 2.16 - * @G_REGEX_ERROR_INVALID_CONDITION: Invalid condition "(?(0)". Since 2.16 - * @G_REGEX_ERROR_SINGLE_BYTE_MATCH_IN_LOOKBEHIND: \\C not allowed in lookbehind assertion. Since 2.16 - * @G_REGEX_ERROR_INFINITE_LOOP: Recursive call could loop indefinitely. Since 2.16 - * @G_REGEX_ERROR_MISSING_SUBPATTERN_NAME_TERMINATOR: Missing terminator in subpattern name. Since 2.16 - * @G_REGEX_ERROR_DUPLICATE_SUBPATTERN_NAME: Two named subpatterns have the same name. Since 2.16 - * @G_REGEX_ERROR_MALFORMED_PROPERTY: Malformed "\\P" or "\\p" sequence. Since 2.16 - * @G_REGEX_ERROR_UNKNOWN_PROPERTY: Unknown property name after "\\P" or "\\p". Since 2.16 - * @G_REGEX_ERROR_SUBPATTERN_NAME_TOO_LONG: Subpattern name is too long (maximum 32 characters). Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_SUBPATTERNS: Too many named subpatterns (maximum 10,000). Since 2.16 - * @G_REGEX_ERROR_INVALID_OCTAL_VALUE: Octal value is greater than "\\377". Since 2.16 - * @G_REGEX_ERROR_TOO_MANY_BRANCHES_IN_DEFINE: "DEFINE" group contains more than one branch. Since 2.16 - * @G_REGEX_ERROR_DEFINE_REPETION: Repeating a "DEFINE" group is not allowed. Since 2.16 - * @G_REGEX_ERROR_INCONSISTENT_NEWLINE_OPTIONS: Inconsistent newline options. Since 2.16 - * @G_REGEX_ERROR_MISSING_BACK_REFERENCE: "\\g" is not followed by a braced name or an optionally braced non-zero number. Since 2.16 + * G_NODE_IS_ROOT: + * @node: a #GNode * - * Error codes returned by regular expressions functions. + * Returns %TRUE if a #GNode is the root of a tree. + * (i.e. it has no parent or siblings) * - * Since: 2.14 + * Returns: %TRUE if the #GNode is the root of a tree */ /** - * G_BOOKMARK_FILE_ERROR: + * G_OBJECT: + * @object: Object which is subject to casting. * - * Error domain for bookmark file parsing. - * Errors in this domain will be from the #GBookmarkFileError - * enumeration. See #GError for information on error domains. + * 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. */ /** - * GEnumClass: - * @g_type_class: the parent class - * @minimum: the smallest possible value. - * @maximum: the largest possible value. - * @n_values: the number of possible values. - * @values: an array of #GEnumValue structs describing the individual values. + * G_OBJECT_CLASS: + * @class: a valid #GObjectClass * - * The class of an enumeration type holds information about its - * possible values. + * Casts a derived #GObjectClass structure into a #GObjectClass structure. */ /** - * GBinding:target: + * G_OBJECT_CLASS_NAME: + * @class: a valid #GObjectClass * - * The #GObject that should be used as the target of the binding + * Return the name of a class structure's type. + * should not be freed. * - * Since: 2.26 + * Returns: Type name of @class. The string is owned by the type system and */ /** - * G_TYPE_FUNDAMENTAL_MAX: + * G_OBJECT_CLASS_TYPE: + * @class: a valid #GObjectClass * - * An integer constant that represents the number of identifiers reserved - * for types that are assigned at compile-time. + * Get the type id of a class structure. + * + * Returns: Type id of @class. */ /** - * GBoxedCopyFunc: - * @boxed: The boxed structure to be copied. + * G_OBJECT_GET_CLASS: + * @object: a #GObject instance. * - * This function is provided by the user and should produce a copy of the passed - * in boxed structure. + * Get the class structure associated to a #GObject instance. * - * Returns: The newly created copy of the boxed structure. + * Returns: pointer to object class structure. */ /** - * g_object_interface_install_property: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface. - * @pspec: the #GParamSpec for the new property + * G_OBJECT_TYPE: + * @object: Object to return the type id for. * - * Add a property to an interface; this is only useful for interfaces - * that are added to GObject-derived types. Adding a property to an - * interface forces all objects classes with that interface to have a - * compatible property. The compatible property could be a newly - * created #GParamSpec, but normally - * g_object_class_override_property() will be used so that the object - * class only needs to provide an implementation and inherits the - * property description, default value, bounds, and so forth from the - * interface property. - * This function is meant to be called from the interface's default - * vtable initialization function (the @class_init member of - * #GTypeInfo.) It must not be called after after @class_init has - * been called for any object types implementing this interface. + * Get the type id of an object. * - * Since: 2.4 + * Returns: Type id of @object. */ /** - * GOptionEntry: - * @long_name: The long name of an option can be used to specify it in a commandline as --<replaceable>long_name</replaceable>. Every option must have a long name. To resolve conflicts if multiple option groups contain the same long name, it is also possible to specify the option as --<replaceable>groupname</replaceable>-<replaceable>long_name</replaceable>. - * @short_name: If an option has a short name, it can be specified -<replaceable>short_name</replaceable> in a commandline. @short_name must be a printable ASCII character different from '-', or zero if the option has no short name. - * @flags: Flags from #GOptionFlags. - * @arg: The type of the option, as a #GOptionArg. - * @arg_data: If the @arg type is %G_OPTION_ARG_CALLBACK, then @arg_data must point to a #GOptionArgFunc callback function, which will be called to handle the extra argument. Otherwise, @arg_data is a pointer to a location to store the value, the required type of the location depends on the @arg type: <variablelist> <varlistentry> <term>%G_OPTION_ARG_NONE</term> <listitem><para>%gboolean</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_INT</term> <listitem><para>%gint</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME</term> <listitem><para>%gchar*</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_STRING_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_FILENAME_ARRAY</term> <listitem><para>%gchar**</para></listitem> </varlistentry> <varlistentry> <term>%G_OPTION_ARG_DOUBLE</term> <listitem><para>%gdouble</para></listitem> </varlistentry> </variablelist> If @arg type is %G_OPTION_ARG_STRING or %G_OPTION_ARG_FILENAME the location will contain a newly allocated string if the option was given. That string needs to be freed by the callee using g_free(). Likewise if @arg type is %G_OPTION_ARG_STRING_ARRAY or %G_OPTION_ARG_FILENAME_ARRAY, the data should be freed using g_strfreev(). - * @description: the description for the option in <option>--help</option> output. The @description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). - * @arg_description: The placeholder to use for the extra argument parsed by the option in <option>--help</option> output. The @arg_description is translated using the @translate_func of the group, see g_option_group_set_translation_domain(). + * G_OBJECT_TYPE_NAME: + * @object: Object to return the type name for. * - * A <structname>GOptionEntry</structname> defines a single option. - * To have an effect, they must be added to a #GOptionGroup with - * g_option_context_add_main_entries() or g_option_group_add_entries(). + * Get the name of an object's type. + * should not be freed. + * + * Returns: Type name of @object. The string is owned by the type system and */ /** - * g_type_class_peek_parent: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to retrieve the parent class for. - * - * This is a convenience function often needed in class initializers. - * It returns the class structure of the immediate parent type of the - * class passed in. Since derived classes hold a reference count on - * their parent classes as long as they are instantiated, the returned - * class will always exist. This function is essentially equivalent - * to: - * <programlisting> - * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); - * </programlisting> - * of @g_class. + * G_OBJECT_WARN_INVALID_PROPERTY_ID: + * @object: the #GObject on which set_property() or get_property() was called + * @property_id: the numeric id of the property + * @pspec: the #GParamSpec of the property * - * Returns: (type GObject.TypeClass) (transfer none): The parent class + * This macro should be used to emit a standard warning about unexpected + * properties in set_property() and get_property() implementations. */ /** - * G_PARAM_SPEC_CHAR: - * @pspec: a valid #GParamSpec instance + * G_OPTION_ERROR: * - * Cast a #GParamSpec instance into a #GParamSpecChar. + * Error domain for option parsing. Errors in this domain will + * be from the #GOptionError enumeration. See #GError for information on + * error domains. */ /** - * G_VALUE_HOLDS_BOOLEAN: - * @value: a valid #GValue structure + * G_OPTION_REMAINING: * - * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. + * If a long option in the main group has this name, it is not treated as a + * regular option. Instead it collects all non-option arguments which would + * otherwise be left in <literal>argv</literal>. The option must be of type + * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY + * or %G_OPTION_ARG_FILENAME_ARRAY. + * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal> + * for leftover arguments has the advantage that GOption takes care of + * necessary encoding conversions for strings or filenames. * - * Returns: %TRUE on success. + * Since: 2.6 */ /** - * g_cclosure_marshal_VOID__POINTER: - * @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 + * G_PARAM_MASK: * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>. + * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. */ /** - * G_PARAM_SPEC_UCHAR: - * @pspec: a valid #GParamSpec instance + * G_PARAM_READWRITE: * - * Cast a #GParamSpec instance into a #GParamSpecUChar. + * #GParamFlags value alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE. */ /** - * G_TYPE_BOOLEAN: + * G_PARAM_SPEC: + * @pspec: a valid #GParamSpec * - * The fundamental type corresponding to #gboolean. + * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into + * a #GParamSpec object. */ /** - * GValue: - * - * An opaque structure used to hold different types of values. - * to functions within a #GTypeValueTable structure, or implementations of - * the g_value_*() API. That is, code portions which implement new fundamental - * types. - * #GValue users can not 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. + * G_PARAM_SPEC_BOOLEAN: + * @pspec: a valid #GParamSpec instance * - * The data within the structure has protected scope: it is accessible only + * Cast a #GParamSpec instance into a #GParamSpecBoolean. */ /** - * g_cclosure_marshal_VOID__STRING: - * @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 + * G_PARAM_SPEC_BOXED: + * @pspec: a valid #GParamSpec instance * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>. + * Cast a #GParamSpec instance into a #GParamSpecBoxed. */ /** - * SECTION:gtypemodul: - * @short_description: Type loading modules <varlistentry> <term>#GTypePlugin</term> <listitem><para>The abstract type loader interface.</para></listitem> </varlistentry> <varlistentry> <term>#GModule</term> <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> </varlistentry> </variablelist> - * @title: GTypeModule + * G_PARAM_SPEC_CHAR: + * @pspec: a valid #GParamSpec instance * - * #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. 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 can not happen in 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 - * zero, the module is loaded. The use count is maintained internally by - * the type system, but also can be explicitly controlled by - * g_type_module_use() and g_type_module_unuse(). Typically, when loading - * a module for the first type, g_type_module_use() will be used to load - * it so that it can initialize its types. At some later point, when the - * module no longer needs to be loaded except for the type - * implementations it contains, g_type_module_unuse() is called. - * #GTypeModule does not actually provide any implementation of module - * loading and unloading. To create a particular module type you must - * derive from #GTypeModule and implement the load and unload functions - * in #GTypeModuleClass. + * Cast a #GParamSpec instance into a #GParamSpecChar. */ /** - * G_VARIANT_TYPE_SIGNATURE: + * G_PARAM_SPEC_CLASS: + * @pclass: a valid #GParamSpecClass * - * The type of a DBus type signature. These are strings of a specific - * format used as type signatures for DBus methods and messages. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. If you are, then the DBus specification contains a - * precise description of valid signature strings. + * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. */ /** - * GBaseInitFunc: - * @g_class: The #GTypeClass structure to initialize. + * G_PARAM_SPEC_DOUBLE: + * @pspec: a valid #GParamSpec instance * - * 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. - * 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 - * intialization process. + * Cast a #GParamSpec instance into a #GParamSpecDouble. */ /** - * g_param_spec_set_qdata_full: (skip) - * @pspec: the #GParamSpec to set store a user data pointer - * @quark: a #GQuark, naming the user data pointer - * @data: an opaque user data pointer - * @destroy: function to invoke with @data as argument, when @data needs to be freed + * G_PARAM_SPEC_ENUM: + * @pspec: a valid #GParamSpec instance * - * This function works like g_param_spec_set_qdata(), but in addition, - * a <literal>void (*destroy) (gpointer)</literal> function may be - * specified which is called with @data as argument when the @pspec is - * finalized, or the data is being overwritten by a call to - * g_param_spec_set_qdata() with the same @quark. + * Cast a #GParamSpec instance into a #GParamSpecEnum. */ /** - * g_value_take_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * @variant: a #GVariant, or %NULL - * - * Set the contents of a variant #GValue to @variant, and takes over - * the ownership of the caller's reference to @variant; - * the caller doesn't have to unref it any more (i.e. the reference - * count of the variant is not increased). - * It is a programmer error to pass a floating variant to this function. - * In particular this means that callbacks in closures, and signal handlers - * for signals of return type %G_TYPE_VARIANT, must never return floating - * variants. - * If you want the #GValue to hold its own reference to @variant, use - * g_value_set_variant() instead. - * This is an internal function introduced mainly for C marshallers. + * G_PARAM_SPEC_FLAGS: + * @pspec: a valid #GParamSpec instance * - * Since: 2.26 + * Cast a #GParamSpec instance into a #GParamSpecFlags. */ /** - * G_TYPE_PARAM_VALUE_ARRAY: + * G_PARAM_SPEC_FLOAT: + * @pspec: a valid #GParamSpec instance * - * The #GType of #GParamSpecValueArray. + * Cast a #GParamSpec instance into a #GParamSpecFloat. */ /** - * G_TYPE_PTR_ARRAY: - * - * The #GType for a boxed type holding a #GPtrArray reference. + * G_PARAM_SPEC_GET_CLASS: + * @pspec: a valid #GParamSpec * - * Since: 2.22 + * Retrieves the #GParamSpecClass of a #GParamSpec. */ /** - * G_VALUE_HOLDS_DOUBLE: - * @value: a valid #GValue structure + * G_PARAM_SPEC_GTYPE: + * @pspec: a #GParamSpec * - * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. + * Casts a #GParamSpec into a #GParamSpecGType. * - * Returns: %TRUE on success. + * Since: 2.10 */ /** - * g_node_insert_data: - * @parent: the #GNode to place the new #GNode under - * @position: the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent - * @data: the data for the new #GNode - * - * Inserts a new #GNode at the given position. + * G_PARAM_SPEC_INT: + * @pspec: a valid #GParamSpec instance * - * Returns: the new #GNode + * Cast a #GParamSpec instance into a #GParamSpecInt. */ /** - * g_flags_get_first_value: - * @flags_class: a #GFlagsClass - * @value: the value - * - * Returns the first #GFlagsValue which is set in @value. - * none is set + * G_PARAM_SPEC_INT64: + * @pspec: a valid #GParamSpec instance * - * Returns: the first #GFlagsValue which is set in @value, or %NULL if + * Cast a #GParamSpec instance into a #GParamSpecInt64. */ /** - * GMainContext: + * G_PARAM_SPEC_LONG: + * @pspec: a valid #GParamSpec instance * - * The <structname>GMainContext</structname> struct is an opaque data - * type representing a set of sources to be handled in a main loop. + * Cast a #GParamSpec instance into a #GParamSpecLong. */ /** - * SECTION:gboxe: - * @short_description: A mechanism to wrap opaque C structures registered by the type system - * @see_also: #GParamSpecBoxed, g_param_spec_boxed() - * @title: Boxed Types + * G_PARAM_SPEC_OBJECT: + * @pspec: a valid #GParamSpec instance * - * 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 and - * free them, 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 - * based libraries. + * Casts a #GParamSpec instance into a #GParamSpecObject. */ /** - * G_TYPE_INSTANCE_GET_INTERFACE: - * @instance: Location of the #GTypeInstance structure. - * @g_type: The #GType of the interface to be returned. - * @c_type: The C type of the interface structure. + * G_PARAM_SPEC_OVERRIDE: + * @pspec: a #GParamSpec * - * Get the interface structure for interface @g_type of a given @instance. - * This macro should only be used in type implementations. + * Casts a #GParamSpec into a #GParamSpecOverride. * - * Returns: a pointer to the interface structure + * Since: 2.4 */ /** - * g_hash_table_thaw: - * @hash_table: a #GHashTable + * G_PARAM_SPEC_PARAM: + * @pspec: a valid #GParamSpec instance * - * This function is deprecated and will be removed in the next major - * release of GLib. It does nothing. + * Casts a #GParamSpec instance into a #GParamSpecParam. */ /** - * GChildWatchFunc: - * @pid: the process id of the child process - * @status: Status information about the child process, see waitpid(2) for more information about this field - * @data: user data passed to g_child_watch_add() + * G_PARAM_SPEC_POINTER: + * @pspec: a valid #GParamSpec instance * - * The type of functions to be called when a child exists. + * Casts a #GParamSpec instance into a #GParamSpecPointer. */ /** - * GParamSpecInt64: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_PARAM_SPEC_STRING: + * @pspec: a valid #GParamSpec instance * - * A #GParamSpec derived structure that contains the meta data for 64bit integer properties. + * Casts a #GParamSpec instance into a #GParamSpecString. */ /** - * GTypeDebugFlags: - * @G_TYPE_DEBUG_NONE: Print no messages. - * @G_TYPE_DEBUG_OBJECTS: Print messages about object bookkeeping. - * @G_TYPE_DEBUG_SIGNALS: Print messages about signal emissions. - * @G_TYPE_DEBUG_MASK: Mask covering all debug flags. + * G_PARAM_SPEC_TYPE: + * @pspec: a valid #GParamSpec * - * The <type>GTypeDebugFlags</type> enumeration values can be passed to - * g_type_init_with_debug_flags() to trigger debugging messages during runtime. - * Note that the messages can also be triggered by setting the - * <envar>GOBJECT_DEBUG</envar> environment variable to a ':'-separated list of - * "objects" and "signals". + * Retrieves the #GType of this @pspec. */ /** - * g_param_value_convert: + * G_PARAM_SPEC_TYPE_NAME: * @pspec: a valid #GParamSpec - * @src_value: souce #GValue - * @dest_value: destination #GValue of correct type for @pspec - * @strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications - * - * Transforms @src_value into @dest_value if possible, and then - * validates @dest_value, in order for it to conform to @pspec. If - * transformed @dest_value complied to @pspec without modifications. - * See also g_value_type_transformable(), g_value_transform() and - * g_param_value_validate(). - * %FALSE otherwise and @dest_value is left untouched. * - * Returns: %TRUE if transformation and validation were successful, + * Retrieves the #GType name of this @pspec. */ /** - * G_PARAM_SPEC_BOOLEAN: + * G_PARAM_SPEC_UCHAR: * @pspec: a valid #GParamSpec instance * - * Cast a #GParamSpec instance into a #GParamSpecBoolean. + * Cast a #GParamSpec instance into a #GParamSpecUChar. */ /** - * g_type_module_register_type: - * @module: a #GTypeModule - * @parent_type: the type for the parent class - * @type_name: name for the type - * @type_info: type information structure - * @flags: flags field providing details about the type - * - * Looks up or registers a type that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * When reregistering a type (typically because a module is unloaded - * then reloaded, and reinitialized), @module and @parent_type must - * be the same as they were previously. - * As long as any instances of the type exist, the type plugin will - * not be unloaded. + * G_PARAM_SPEC_UINT: + * @pspec: a valid #GParamSpec instance * - * Returns: the new or existing type ID + * Cast a #GParamSpec instance into a #GParamSpecUInt. */ /** - * G_IS_PARAM_SPEC_OVERRIDE: - * @pspec: a #GParamSpec - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. + * G_PARAM_SPEC_UINT64: + * @pspec: a valid #GParamSpec instance * - * Since: 2.4 - * Returns: %TRUE on success. + * Cast a #GParamSpec instance into a #GParamSpecUInt64. */ /** - * G_IS_PARAM_SPEC_STRING: + * G_PARAM_SPEC_ULONG: * @pspec: a valid #GParamSpec instance * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. - * - * Returns: %TRUE on success. + * Cast a #GParamSpec instance into a #GParamSpecULong. */ /** - * g_value_get_pointer: - * @value: a valid #GValue of %G_TYPE_POINTER - * - * Get the contents of a pointer #GValue. + * G_PARAM_SPEC_UNICHAR: + * @pspec: a valid #GParamSpec instance * - * Returns: (transfer none): pointer contents of @value + * Cast a #GParamSpec instance into a #GParamSpecUnichar. */ /** - * g_object_class_find_property: - * @oclass: a #GObjectClass - * @property_name: the name of the property to look up - * - * Looks up the #GParamSpec for a property of a class. - * %NULL if the class doesn't have a property of that name + * G_PARAM_SPEC_VALUE_ARRAY: + * @pspec: a valid #GParamSpec instance * - * Returns: (transfer none): the #GParamSpec for the property, or + * Cast a #GParamSpec instance into a #GParamSpecValueArray. */ /** - * g_value_take_param: (skip) - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: the #GParamSpec to be set - * - * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes - * over the ownership of the callers reference to @param; the caller - * doesn't have to unref it any more. + * G_PARAM_SPEC_VALUE_TYPE: + * @pspec: a valid #GParamSpec * - * Since: 2.4 + * Retrieves the #GType to initialize a #GValue for this parameter. */ /** - * g_closure_new_simple: - * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> - * @data: data to store in the @data field of the newly allocated #GClosure + * G_PARAM_SPEC_VARIANT: + * @pspec: a #GParamSpec * - * 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. - * |[ - * typedef struct _MyClosure MyClosure; - * struct _MyClosure - * { - * GClosure closure; - * // extra data goes here - * }; - * static void - * my_closure_finalize (gpointer notify_data, - * GClosure *closure) - * { - * MyClosure *my_closure = (MyClosure *)closure; - * // free extra data here - * } - * MyClosure *my_closure_new (gpointer data) - * { - * GClosure *closure; - * MyClosure *my_closure; - * closure = g_closure_new_simple (sizeof (MyClosure), data); - * my_closure = (MyClosure *) closure; - * // initialize extra data here - * g_closure_add_finalize_notifier (closure, notify_data, - * my_closure_finalize); - * return my_closure; - * } - * ]| + * Casts a #GParamSpec into a #GParamSpecVariant. * - * Returns: (transfer full): a newly allocated #GClosure + * Since: 2.26 */ /** - * GTypeModule: - * @name: the name of the module + * G_PARAM_STATIC_STRINGS: * - * The members of the <structname>GTypeModule</structname> structure should not - * be accessed directly, except for the @name field. + * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. + * Since 2.13.0 */ /** - * g_closure_ref: - * @closure: #GClosure to increment the reference count on - * - * Increments the reference count on a closure to force it staying - * alive while the caller holds a pointer to it. + * G_PARAM_USER_SHIFT: * - * Returns: (transfer none): The @closure passed in, for convenience + * Minimum shift count to be used for user defined flags, to be stored in + * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT. */ /** - * G_VARIANT_TYPE_UNIT: + * G_PRIORITY_DEFAULT: * - * The empty tuple type. Has only one instance. Known also as "triv" - * or "void". + * Use this for default priority event sources. + * In GLib this priority is used when adding timeout functions + * with g_timeout_add(). In GDK this priority is used for events + * from the X server. */ /** - * SECTION:gtypeplugi: - * @short_description: An interface for dynamically loadable types - * @see_also: #GTypeModule and g_type_register_dynamic(). - * @title: GTypePlugin + * G_PRIORITY_DEFAULT_IDLE: * - * 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: - * <orderedlist> - * <listitem><para> - * The type is initially introduced (usually upon loading the module - * the first time, or by your main application that knows what modules - * introduces what types), like this: - * |[ - * new_type_id = g_type_register_dynamic (parent_type_id, - * "TypeName", - * new_type_plugin, - * type_flags); - * ]| - * where <literal>new_type_plugin</literal> is an implementation of the - * #GTypePlugin interface. - * </para></listitem> - * <listitem><para> - * The type's implementation is referenced, e.g. through - * g_type_class_ref() or through g_type_create_instance() (this is - * being called by g_object_new()) or through one of the above done on - * a type derived from <literal>new_type_id</literal>. - * </para></listitem> - * <listitem><para> - * This causes the type system to load the type's implementation by calling - * g_type_plugin_use() and g_type_plugin_complete_type_info() on - * <literal>new_type_plugin</literal>. - * </para></listitem> - * <listitem><para> - * At some point the type's implementation isn't required anymore, e.g. after - * g_type_class_unref() or g_type_free_instance() (called when the reference - * count of an instance drops to zero). - * </para></listitem> - * <listitem><para> - * This causes the type system to throw away the information retrieved from - * g_type_plugin_complete_type_info() and then it calls - * g_type_plugin_unuse() on <literal>new_type_plugin</literal>. - * </para></listitem> - * <listitem><para> - * Things may repeat from the second step. - * </para></listitem> - * </orderedlist> - * So basically, you need to implement a #GTypePlugin type that - * carries a use_count, once use_count goes from zero to one, you need - * to load the implementation to successfully handle the upcoming - * g_type_plugin_complete_type_info() call. Later, maybe after - * succeeding use/unuse calls, once use_count drops to zero, you can - * unload the implementation again. The type system makes sure to call - * g_type_plugin_use() and g_type_plugin_complete_type_info() again - * when the type is needed again. - * #GTypeModule is an implementation of #GTypePlugin that already - * implements most of this except for the actual module loading and - * unloading. It even handles multiple registered types per module. + * Use this for default priority idle functions. + * In GLib this priority is used when adding idle functions with + * g_idle_add(). */ /** - * g_type_interfaces: - * @type: The type to list interface types for. - * @n_interfaces: (out) (allow-none): Optional #guint pointer to contain the number of interface types. - * - * Return a newly allocated and 0-terminated array of type IDs, listing the - * interface types that @type conforms to. The return value has to be - * g_free()ed after use. - * allocated and 0-terminated array of interface types. + * G_PRIORITY_HIGH: * - * Returns: (array length=n_interfaces) (transfer full): Newly + * Use this for high priority event sources. + * It is not used within GLib or GTK+. */ /** - * GOptionArgFunc: - * @option_name: The name of the option being parsed. This will be either a single dash followed by a single letter (for a short name) or two dashes followed by a long option name. - * @value: The value to be parsed. - * @data: User data added to the #GOptionGroup containing the option when it was created with g_option_group_new() - * @error: A return location for errors. The error code %G_OPTION_ERROR_FAILED is intended to be used for errors in #GOptionArgFunc callbacks. - * - * The type of function to be passed as callback for %G_OPTION_ARG_CALLBACK - * options. - * occurred, in which case @error should be set with g_set_error() + * G_PRIORITY_HIGH_IDLE: * - * Returns: %TRUE if the option was successfully parsed, %FALSE if an error + * Use this for high priority idle functions. + * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, + * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is + * done to ensure that any pending resizes are processed before any + * pending redraws, so that widgets are not redrawn twice unnecessarily.) */ /** - * g_binding_get_target: - * @binding: a #GBinding - * - * Retrieves the #GObject instance used as the target of the binding + * G_PRIORITY_LOW: * - * Returns: (transfer none): the target #GObject - * Since: 2.26 + * Use this for very low priority background tasks. + * It is not used within GLib or GTK+. */ /** - * GTypePluginClass: - * @use_plugin: Increases the use count of the plugin. - * @unuse_plugin: Decreases the use count of the plugin. - * @complete_type_info: Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. - * @complete_interface_info: Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with <literal>memset(s, 0, sizeof (s))</literal> before calling this function. + * G_REGEX_ERROR: * - * The #GTypePlugin interface is used by the type system in order to handle - * the lifecycle of dynamically loaded types. + * Error domain for regular expressions. Errors in this domain will be + * from the #GRegexError enumeration. See #GError for information on + * error domains. + * + * Since: 2.14 */ /** - * G_PARAM_SPEC_VALUE_TYPE: - * @pspec: a valid #GParamSpec + * G_SIGNAL_FLAGS_MASK: * - * Retrieves the #GType to initialize a #GValue for this parameter. + * A mask for all #GSignalFlags bits. */ /** - * GTypeInstance: + * G_SIGNAL_MATCH_MASK: * - * An opaque structure used as the base of all type instances. + * A mask for all #GSignalMatchType bits. */ /** - * G_TYPE_GTYPE: + * G_SIGNAL_TYPE_STATIC_SCOPE: * - * The type for #GType. + * This macro flags signal argument types for which the signal system may + * assume that instances thereof remain persistent across all signal emissions + * they are used in. This is only useful for non ref-counted, value-copy types. + * To flag a signal argument in this way, add + * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument + * of g_signal_new(). + * |[ + * g_signal_new ("size_request", + * G_TYPE_FROM_CLASS (gobject_class), + * G_SIGNAL_RUN_FIRST, + * G_STRUCT_OFFSET (GtkWidgetClass, size_request), + * NULL, NULL, + * _gtk_marshal_VOID__BOXED, + * G_TYPE_NONE, 1, + * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); + * ]| */ /** - * g_boxed_type_register_static: - * @name: Name of the new boxed type. - * @boxed_copy: Boxed structure copy function. - * @boxed_free: Boxed structure free function. + * G_TIME_SPAN_DAY: * - * 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. + * Evaluates to a time span of one day. * - * Returns: New %G_TYPE_BOXED derived type id for @name. + * Since: 2.26 */ @@ -3528,2454 +3201,1532 @@ /** - * G_VARIANT_TYPE: - * @type_string: a well-formed #GVariantType type string - * - * Converts a string to a const #GVariantType. Depending on the - * current debugging level, this function may perform a runtime check - * to ensure that @string is a valid GVariant type string. - * It is always a programmer error to use this macro with an invalid - * type string. - * Since 2.24 - */ - - -/** - * G_TYPE_STRV: - * - * The #GType for a boxed type holding a %NULL-terminated array of strings. - * The code fragments in the following example show the use of a property of - * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set() - * and g_object_get(). - * |[ - * g_object_class_install_property (object_class, - * PROP_AUTHORS, - * g_param_spec_boxed ("authors", - * _("Authors"), - * _("List of authors"), - * G_TYPE_STRV, - * G_PARAM_READWRITE)); - * gchar *authors[] = { "Owen", "Tim", NULL }; - * g_object_set (obj, "authors", authors, NULL); - * gchar *writers[]; - * g_object_get (obj, "authors", &writers, NULL); - * // do something with writers - * g_strfreev (writers); - * ]| - * - * Since: 2.4 - */ - - -/** - * G_TYPE_REGEX: - * - * The #GType for a boxed type holding a #GRegex reference. + * G_TIME_SPAN_MILLISECOND: * - * Since: 2.14 - */ - - -/** - * g_object_set_property: - * @object: a #GObject - * @property_name: the name of the property to set - * @value: the value + * Evaluates to a time span of one millisecond. * - * Sets a property on an object. + * Since: 2.26 */ /** - * GTypeFundamentalFlags: - * @G_TYPE_FLAG_CLASSED: Indicates a classed type. - * @G_TYPE_FLAG_INSTANTIATABLE: Indicates an instantiable type (implies classed). - * @G_TYPE_FLAG_DERIVABLE: Indicates a flat derivable type. - * @G_TYPE_FLAG_DEEP_DERIVABLE: Indicates a deep derivable type (implies derivable). + * G_TIME_SPAN_MINUTE: * - * Bit masks used to check or determine specific characteristics of a - * fundamental type. - */ - - -/** - * g_signal_emit: - * @instance: the instance the signal is being emitted on. - * @signal_id: the signal id - * @detail: the detail - * @...: 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. + * Evaluates to a time span of one minute. * - * Emits a signal. - * Note that g_signal_emit() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). + * Since: 2.26 */ /** - * g_value_get_uchar: - * @value: a valid #GValue of type %G_TYPE_UCHAR + * G_TIME_SPAN_SECOND: * - * Get the contents of a %G_TYPE_UCHAR #GValue. + * Evaluates to a time span of one second. * - * Returns: unsigned character contents of @value + * Since: 2.26 */ /** - * g_param_spec_pool_list: - * @pool: a #GParamSpecPool - * @owner_type: the owner to look for - * @n_pspecs_p: (out): return location for the length of the returned array + * G_TYPE_ARRAY: * - * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in - * the pool. - * allocated array containing pointers to all #GParamSpecs - * owned by @owner_type in the pool + * The #GType for a boxed type holding a #GArray reference. * - * Returns: (array length=n_pspecs_p) (transfer container): a newly + * Since: 2.22 */ /** - * g_closure_set_meta_marshal: (skip) - * @closure: a #GClosure - * @marshal_data: context-dependent data to pass to @meta_marshal - * @meta_marshal: a #GClosureMarshal function + * G_TYPE_BOOLEAN: * - * Sets the meta marshaller of @closure. A meta marshaller wraps - * fashion. The most common use of this facility is for C callbacks. - * The same marshallers (generated by <link - * linkend="glib-genmarshal">glib-genmarshal</link>) are used - * everywhere, but the way that we get the callback function - * differs. In most cases we want to use @closure->callback, but in - * other cases we want to use some different technique to retrieve the - * callback function. - * For example, class closures for signals (see - * g_signal_type_cclosure_new()) retrieve the callback function from a - * fixed offset in the class structure. The meta marshaller retrieves - * the right callback and passes it to the marshaller as the + * The fundamental type corresponding to #gboolean. */ /** - * G_TYPE_INT64: + * G_TYPE_BOXED: * - * The fundamental type corresponding to #gint64. + * The fundamental type from which all boxed types are derived. */ /** - * G_TIME_SPAN_MILLISECOND: + * G_TYPE_BYTE_ARRAY: * - * Evaluates to a time span of one millisecond. + * The #GType for a boxed type holding a #GByteArray reference. * - * Since: 2.26 + * Since: 2.22 */ /** - * G_TYPE_CLOSURE: + * G_TYPE_CHAR: * - * The #GType for #GClosure. + * The fundamental type corresponding to #gchar. + * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. + * This may or may not be the same type a the C type "gchar". */ /** - * GParamSpecULong: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * G_TYPE_CHECK_CLASS_CAST: + * @g_class: Location of a #GTypeClass structure. + * @g_type: The type to be returned. + * @c_type: The corresponding C type of class structure of @g_type. * - * A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. + * Checks that @g_class is a class structure of the type identified by @g_type + * and issues a warning if this is not the case. Returns @g_class casted + * to a pointer to @c_type. + * This macro should only be used in type implementations. */ /** - * G_PARAM_SPEC_ULONG: - * @pspec: a valid #GParamSpec instance + * G_TYPE_CHECK_CLASS_TYPE: + * @g_class: Location of a #GTypeClass structure. + * @g_type: The type to be checked. * - * Cast a #GParamSpec instance into a #GParamSpecULong. + * Checks if @g_class is a class structure of the type identified by + * This macro should only be used in type implementations. + * + * Returns: %TRUE on success. */ /** - * G_PARAM_SPEC_VARIANT: - * @pspec: a #GParamSpec + * G_TYPE_CHECK_INSTANCE: + * @instance: Location of a #GTypeInstance structure. * - * Casts a #GParamSpec into a #GParamSpecVariant. + * Checks if @instance is a valid #GTypeInstance structure, + * otherwise issues a warning and returns %FALSE. + * This macro should only be used in type implementations. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * SECTION:gtyp: - * @short_description: The GLib Runtime type identification and management system - * - * 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. Before using any GType - * or GObject functions, g_type_init() must be called to initialize the - * type system. - * For type creation and registration purposes, all types fall into one of - * unloaded at run-time as dynamic types may be. Static types are created - * with g_type_register_static() that gets type specific information passed - * in via a #GTypeInfo structure. - * Dynamic types are created with g_type_register_dynamic() which takes a - * #GTypePlugin structure instead. The remaining type information (the - * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin - * and the g_type_plugin_*() API. - * These registration functions are usually called only once from a - * function whose only purpose is to return the type identifier for a - * specific class. Once the type (or class or interface) is registered, - * it may be instantiated, inherited, or implemented depending on exactly - * what sort of type it is. - * There is also a third registration function for registering fundamental - * types called g_type_register_fundamental() which requires both a #GTypeInfo - * structure and a #GTypeFundamentalInfo structure but it is seldom used - * since most fundamental types are predefined rather than user-defined. - * A final word about type names. - * Such an identifier needs to be at least three characters long. There is no - * upper length limit. The first character needs to be a letter (a-z or A-Z) - * or an underscore '_'. Subsequent characters can be letters, numbers or - * any of '-_+'. + * G_TYPE_CHECK_INSTANCE_CAST: + * @instance: Location of a #GTypeInstance structure. + * @g_type: The type to be returned. + * @c_type: The corresponding C type of @g_type. * - * Two categories: static or dynamic. Static types are never loaded or + * Checks that @instance is an instance of the type identified by @g_type + * and issues a warning if this is not the case. Returns @instance casted + * to a pointer to @c_type. + * This macro should only be used in type implementations. */ /** - * G_VALUE_HOLDS_INT64: - * @value: a valid #GValue structure + * G_TYPE_CHECK_INSTANCE_TYPE: + * @instance: Location of a #GTypeInstance structure. + * @g_type: The type to be checked * - * Checks whether the given #GValue can hold values of type %G_TYPE_INT64. + * Checks if @instance is an instance of the type identified by @g_type. + * This macro should only be used in type implementations. * * Returns: %TRUE on success. */ /** - * GTypeInterface: + * G_TYPE_CHECK_VALUE: + * @value: a #GValue * - * An opaque structure used as the base of all interface types. - */ - - -/** - * g_signal_handler_block: - * @instance: The instance to block the signal handler of. - * @handler_id: Handler id of the handler to be blocked. + * Checks if @value has been initialized to hold values + * of a value type. + * This macro should only be used in type implementations. * - * Blocks a handler of an instance so it will not be called during any - * signal emissions unless it is unblocked again. Thus "blocking" a - * signal handler means to temporarily deactive it, a signal handler - * has to be unblocked exactly the same amount of times it has been - * blocked before to become active again. - * The @handler_id has to be a valid signal handler id, connected to a - * signal of @instance. + * Returns: %TRUE on success. */ /** - * GOptionArg: - * @G_OPTION_ARG_NONE: No extra argument. This is useful for simple flags. - * @G_OPTION_ARG_STRING: The option takes a string argument. - * @G_OPTION_ARG_INT: The option takes an integer argument. - * @G_OPTION_ARG_CALLBACK: The option provides a callback to parse the extra argument. - * @G_OPTION_ARG_FILENAME: The option takes a filename as argument. - * @G_OPTION_ARG_STRING_ARRAY: The option takes a string argument, multiple uses of the option are collected into an array of strings. - * @G_OPTION_ARG_FILENAME_ARRAY: The option takes a filename as argument, multiple uses of the option are collected into an array of strings. - * @G_OPTION_ARG_DOUBLE: The option takes a double argument. The argument can be formatted either for the user's locale or for the "C" locale. Since 2.12 - * @G_OPTION_ARG_INT64: The option takes a 64-bit integer. Like %G_OPTION_ARG_INT but for larger numbers. The number can be in decimal base, or in hexadecimal (when prefixed with <literal>0x</literal>, for example, <literal>0xffffffff</literal>). Since 2.12 + * G_TYPE_CHECK_VALUE_TYPE: + * @value: a #GValue + * @g_type: The type to be checked. * - * The #GOptionArg enum values determine which type of extra argument the - * options expect to find. If an option expects an extra argument, it - * can be specified in several ways; with a short option: - * <option>-x arg</option>, with a long option: <option>--name arg</option> + * Checks if @value has been initialized to hold values + * of type @g_type. + * This macro should only be used in type implementations. * - * Or combined in a single argument: <option>--name=arg</option>. + * Returns: %TRUE on success. */ /** - * g_type_is_a: - * @type: Type to check anchestry for. - * @is_a_type: Possible anchestor of @type or interface @type could conform to. + * G_TYPE_CLASS_GET_PRIVATE: + * @klass: the class of a type deriving from @private_type. + * @g_type: the type identifying which private data to retrieve. + * @c_type: The C type for the private structure. * - * If @is_a_type is a derivable type, check whether @type is a - * descendant of @is_a_type. If @is_a_type is an interface, check - * whether @type conforms to it. + * 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(). + * This macro should only be used in type implementations. * - * Returns: %TRUE if @type is_a @is_a_type holds true. + * Since: 2.24 + * Returns: a pointer to the private data structure. */ /** - * g_value_set_float: - * @value: a valid #GValue of type %G_TYPE_FLOAT - * @v_float: float value to be set + * G_TYPE_CLOSURE: * - * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. + * The #GType for #GClosure. */ /** - * g_value_set_param: - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: the #GParamSpec to be set + * G_TYPE_DATE: * - * Set the contents of a %G_TYPE_PARAM #GValue to @param. + * The #GType for #GDate. */ /** - * GTypeClassCacheFunc: - * @cache_data: data that was given to the g_type_add_class_cache_func() call - * @g_class: The #GTypeClass structure which is unreferenced - * - * 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. - * 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 - * classes are routed through the same #GTypeClassCacheFunc chain. - * called, %FALSE to continue. + * G_TYPE_DATE_TIME: * - * Returns: %TRUE to stop further #GTypeClassCacheFunc<!-- -->s from being - */ - - -/** - * GPid: + * The #GType for a boxed type holding a #GDateTime. * - * A type which is used to hold a process identification. - * On UNIX, processes are identified by a process id (an integer), - * while Windows uses process handles (which are pointers). + * Since: 2.26 */ /** - * g_param_spec_uchar: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. + * G_TYPE_DOUBLE: * - * Returns: a newly created parameter specification + * The fundamental type corresponding to #gdouble. */ /** - * g_value_take_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: string to take ownership of - * - * Sets the contents of a %G_TYPE_STRING #GValue to @v_string. + * G_TYPE_ENUM: * - * Since: 2.4 + * The fundamental type from which all enumeration types are derived. */ /** - * G_DEFINE_POINTER_TYPE_WITH_CODE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @_C_: Custom code that gets inserted in the *_get_type() function. + * G_TYPE_ERROR: * - * 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. + * The #GType for a boxed type holding a #GError. * * Since: 2.26 */ /** - * g_signal_new_valist: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_closure: The closure to invoke on signal emission; may be %NULL. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. - * @n_params: the number of parameter types in @args. - * @args: va_list of #GType, one for each parameter. - * - * Creates a new signal. (This is usually done in the class initializer.) - * See g_signal_new() for details on allowed signal names. - * - * Returns: the signal id - */ - - -/** - * GOptionGroup: - * - * A <structname>GOptionGroup</structname> struct defines the options in a single - * group. The struct has only private fields and should not be directly accessed. - * All options in a group share the same translation function. Libraries which - * need to parse commandline options are expected to provide a function for - * getting a <structname>GOptionGroup</structname> holding their options, which - * the application can then add to its #GOptionContext. - */ - - -/** - * g_type_class_peek: - * @type: Type ID of a classed type. - * - * This function is essentially the same as g_type_class_ref(), except that - * the classes reference count isn't incremented. As a consequence, this function - * may return %NULL if the class of the type passed in does not currently - * exist (hasn't been referenced before). - * structure for the given type ID or %NULL if the class does not - * currently exist. + * G_TYPE_FLAGS: * - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass + * The fundamental type from which all flags types are derived. */ /** - * g_param_spec_pool_list_owned: - * @pool: a #GParamSpecPool - * @owner_type: the owner to look for - * - * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in - * the pool. - * #GList of all #GParamSpec<!-- -->s owned by @owner_type in - * the pool#GParamSpec<!-- -->s. + * G_TYPE_FLAG_RESERVED_ID_BIT: * - * Returns: (transfer container) (element-type GObject.ParamSpec): a + * A bit in the type number that's supposed to be left untouched. */ /** - * G_TYPE_INVALID: + * G_TYPE_FLOAT: * - * An invalid #GType used as error return value in some functions which return - * a #GType. + * The fundamental type corresponding to #gfloat. */ /** - * g_try_new0: - * @struct_type: the type of the elements to allocate - * @n_structs: the number of elements to allocate + * G_TYPE_FROM_CLASS: + * @g_class: Location of a valid #GTypeClass structure. * - * Attempts to allocate @n_structs elements of type @struct_type, initialized - * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts - * the program on failure. - * The returned pointer is cast to a pointer to the given type. - * The function returns %NULL when @n_structs is 0 of if an overflow occurs. + * Get the type identifier from a given @class structure. + * This macro should only be used in type implementations. * - * Since: 2.8 - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type + * Returns: the #GType */ /** - * g_binding_get_source_property: - * @binding: a #GBinding + * G_TYPE_FROM_INSTANCE: + * @instance: Location of a valid #GTypeInstance structure. * - * Retrieves the name of the property of #GBinding:source used as the source - * of the binding + * Get the type identifier from a given @instance structure. + * This macro should only be used in type implementations. * - * Returns: the name of the source property - * Since: 2.26 + * Returns: the #GType */ /** - * g_param_spec_uint: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * G_TYPE_FROM_INTERFACE: + * @g_iface: Location of a valid #GTypeInterface structure. * - * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. - * See g_param_spec_internal() for details on property names. + * Get the type identifier from a given @interface structure. + * This macro should only be used in type implementations. * - * Returns: a newly created parameter specification + * Returns: the #GType */ /** - * SECTION:enumerations_flag: - * @short_description: Enumeration and flags types - * @title: Enumeration and Flag Types g_param_spec_flags() + * G_TYPE_FUNDAMENTAL: + * @type: A #GType value. * - * The GLib type system provides fundamental types for enumeration and - * flags types. (Flags types are like enumerations, but allow their - * values to be combined by bitwise or). A registered enumeration or - * flags type associates a name and a nickname with each allowed - * value, and the methods g_enum_get_value_by_name(), - * g_enum_get_value_by_nick(), g_flags_get_value_by_name() and - * g_flags_get_value_by_nick() can look up values by their name or - * nickname. When an enumeration or flags type is registered with the - * GLib type system, it can be used as value type for object - * properties, using g_param_spec_enum() or g_param_spec_flags(). - * GObject ships with a utility called <link - * linkend="glib-mkenums">glib-mkenums</link> that can construct - * suitable type registration functions from C enumeration - * definitions. + * 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. */ /** - * GParamFlags: - * @G_PARAM_READABLE: the parameter is readable - * @G_PARAM_WRITABLE: the parameter is writable - * @G_PARAM_CONSTRUCT: the parameter will be set upon object construction - * @G_PARAM_CONSTRUCT_ONLY: the parameter will only be set upon object construction - * @G_PARAM_LAX_VALIDATION: upon parameter conversion (see g_param_value_convert()) strict validation is not required - * @G_PARAM_STATIC_NAME: the string used as name when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_STATIC_NICK: the string used as nick when constructing the parameter is guaranteed to remain valid and unmmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_STATIC_BLURB: the string used as blurb when constructing the parameter is guaranteed to remain valid and unmodified for the lifetime of the parameter. Since 2.8 - * @G_PARAM_PRIVATE: internal - * @G_PARAM_DEPRECATED: the parameter is deprecated and will be removed in a future version. A warning will be generated if it is used while running with G_ENABLE_DIAGNOSTIC=1. Since: 2.26 + * G_TYPE_FUNDAMENTAL_MAX: * - * Through the #GParamFlags flag values, certain aspects of parameters - * can be configured. + * An integer constant that represents the number of identifiers reserved + * for types that are assigned at compile-time. */ /** - * g_cclosure_marshal_BOOLEAN__FLAGS: - * @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 + * G_TYPE_FUNDAMENTAL_SHIFT: * - * A marshaller for a #GCClosure with a callback of type - * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter - * denotes a flags type. + * Shift value used in converting numbers to type IDs. */ /** - * g_type_module_register_flags: - * @module: a #GTypeModule - * @name: name for the type - * @const_static_values: an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. - * - * Looks up or registers a flags type that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * As long as any instances of the type exist, the type plugin will - * not be unloaded. + * G_TYPE_GSTRING: * - * Since: 2.6 - * Returns: the new or existing type ID + * The #GType for #GString. */ /** - * G_TYPE_PARAM_OBJECT: + * G_TYPE_GTYPE: * - * The #GType of #GParamSpecObject. + * The type for #GType. */ /** - * g_enum_get_value_by_name: - * @enum_class: a #GEnumClass - * @name: the name to look up + * G_TYPE_HASH_TABLE: * - * Looks up a #GEnumValue by name. - * enumeration doesn't have a member with that name + * The #GType for a boxed type holding a #GHashTable reference. * - * Returns: the #GEnumValue with name @name, or %NULL if the + * Since: 2.10 */ /** - * g_signal_override_class_handler: - * @signal_name: the name for the signal - * @instance_type: the instance type on which to override the class handler for the signal. - * @class_handler: the handler. + * G_TYPE_HAS_VALUE_TABLE: + * @type: A #GType value. * - * Overrides the class closure (i.e. the default handler) for the - * given signal for emissions on instances of @instance_type with - * callabck @class_handler. @instance_type must be derived from the - * type to which the signal belongs. - * See g_signal_chain_from_overridden() and - * g_signal_chain_from_overridden_handler() for how to chain up to the - * parent class closure from inside the overridden one. + * Checks if @type has a #GTypeValueTable. * - * Since: 2.18 + * Returns: %TRUE on success. */ /** - * G_VARIANT_TYPE_STRING: + * G_TYPE_INITIALLY_UNOWNED: * - * The type of a string. "" is a string. %NULL is not a string. + * The type for #GInitiallyUnowned. */ /** - * g_signal_connect_closure: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @closure: the closure to connect. - * @after: whether the handler should be called before or after the default handler of the signal. + * G_TYPE_INSTANCE_GET_CLASS: + * @instance: Location of the #GTypeInstance structure. + * @g_type: The #GType of the class to be returned. + * @c_type: The C type of the class structure. * - * Connects a closure to a signal for a particular object. + * Get the class structure of a given @instance, casted + * to a specified ancestor type @g_type of the instance. + * Note that while calling a GInstanceInitFunc(), the class pointer gets + * modified, so it might not always return the expected pointer. + * This macro should only be used in type implementations. * - * Returns: the handler id + * Returns: a pointer to the class structure */ /** - * G_OPTION_REMAINING: + * G_TYPE_INSTANCE_GET_INTERFACE: + * @instance: Location of the #GTypeInstance structure. + * @g_type: The #GType of the interface to be returned. + * @c_type: The C type of the interface structure. * - * If a long option in the main group has this name, it is not treated as a - * regular option. Instead it collects all non-option arguments which would - * otherwise be left in <literal>argv</literal>. The option must be of type - * %G_OPTION_ARG_CALLBACK, %G_OPTION_ARG_STRING_ARRAY - * or %G_OPTION_ARG_FILENAME_ARRAY. - * Using #G_OPTION_REMAINING instead of simply scanning <literal>argv</literal> - * for leftover arguments has the advantage that GOption takes care of - * necessary encoding conversions for strings or filenames. + * Get the interface structure for interface @g_type of a given @instance. + * This macro should only be used in type implementations. * - * Since: 2.6 + * Returns: a pointer to the interface structure */ /** - * g_type_module_add_interface: - * @module: a #GTypeModule - * @instance_type: type to which to add the interface. - * @interface_type: interface type to add - * @interface_info: type information structure + * G_TYPE_INSTANCE_GET_PRIVATE: + * @instance: the instance of a type deriving from @private_type. + * @g_type: the type identifying which private data to retrieve. + * @c_type: The C type for the private structure. * - * Registers an additional interface for a type, whose interface lives - * in the given type plugin. If the interface was already registered - * for the type in this plugin, nothing will be done. - * As long as any instances of the type exist, the type plugin will - * not be unloaded. - */ - - -/** - * g_type_query: - * @type: the #GType value of a static, classed type. - * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. + * 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(). + * This macro should only be used in type implementations. * - * Queries the type system for information about a specific type. - * This function will fill in a user-provided structure to hold - * type-specific information. If an invalid #GType is passed in, the - * #GTypeQuery structure should be considered constant and have to be - * left untouched. + * Since: 2.4 + * Returns: a pointer to the private data structure. */ /** - * GTypePluginCompleteTypeInfo: - * @plugin: the #GTypePlugin - * @g_type: the #GType whose info is completed - * @info: the #GTypeInfo struct to fill in - * @value_table: the #GTypeValueTable to fill in + * G_TYPE_INT: * - * The type of the @complete_type_info function of #GTypePluginClass. + * The fundamental type corresponding to #gint. */ /** - * g_type_register_static: - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @info: The #GTypeInfo structure for this type. - * @flags: Bitwise combination of #GTypeFlags values. - * - * Registers @type_name as the name of a new static type derived from - * #GTypeInfo structure pointed to by @info to manage the type and its - * instances (if not abstract). The value of @flags determines the nature - * (e.g. abstract or not) of the type. + * G_TYPE_INT64: * - * Returns: The new type identifier. + * The fundamental type corresponding to #gint64. */ /** - * G_PARAM_SPEC_ENUM: - * @pspec: a valid #GParamSpec instance + * G_TYPE_INTERFACE: * - * Cast a #GParamSpec instance into a #GParamSpecEnum. + * The fundamental type from which all interfaces are derived. */ /** - * GSignalAccumulator: - * @ihint: Signal invocation hint, see #GSignalInvocationHint. - * @return_accu: Accumulator to collect callback return values in, this is the return value of the current signal emission. - * @handler_return: A #GValue holding the return value of the signal handler. - * @data: Callback data that was specified when creating the signal. - * - * 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. - * should be aborted. Returning %FALSE means to abort the - * current emission and %TRUE is returned for continuation. + * G_TYPE_INVALID: * - * Returns: The accumulator function returns whether the signal emission + * An invalid #GType used as error return value in some functions which return + * a #GType. */ /** - * g_value_array_new: - * @n_prealloced: number of values to preallocate space for - * - * Allocate and initialize a new #GValueArray, optionally preserve space - * for @n_prealloced elements. New arrays always contain 0 elements, - * regardless of the value of @n_prealloced. + * G_TYPE_IO_CHANNEL: * - * Returns: a newly allocated #GValueArray with 0 values + * The #GType for #GIOChannel. */ /** - * g_value_array_remove: - * @value_array: #GValueArray to remove an element from - * @index_: position of value to remove, must be < value_array->n_values - * - * Remove the value at position @index_ from @value_array. + * G_TYPE_IO_CONDITION: * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * The #GType for #GIOCondition. */ /** - * g_object_get_qdata: - * @object: The GObject to get a stored user data pointer from - * @quark: A #GQuark, naming the user data pointer + * G_TYPE_IS_ABSTRACT: + * @type: A #GType value. * - * This function gets back user data pointers stored via - * g_object_set_qdata(). + * Checks if @type is an abstract type. An abstract type can not be + * instantiated and is normally used as an abstract base class for + * derived classes. * - * Returns: (transfer none): The user data pointer set, or %NULL + * Returns: %TRUE on success. */ /** - * GRegex: - * - * A GRegex is the "compiled" form of a regular expression pattern. This - * structure is opaque and its fields cannot be accessed directly. + * G_TYPE_IS_CLASSED: + * @type: A #GType value. * - * Since: 2.14 - */ - - -/** - * GToggleNotify: - * @data: Callback data passed to g_object_add_toggle_ref() - * @object: The object on which g_object_add_toggle_ref() was called. - * @is_last_ref: %TRUE if the toggle reference is now the last reference to the object. %FALSE if the toggle reference was the last reference and there are now other references. + * Checks if @type is a classed type. * - * A callback function used for notification when the state - * of a toggle reference changes. See g_object_add_toggle_ref(). + * Returns: %TRUE on success. */ /** - * g_object_watch_closure: - * @object: GObject restricting lifetime of @closure - * @closure: GClosure to watch + * G_TYPE_IS_DEEP_DERIVABLE: + * @type: A #GType value. * - * This function essentially limits the life time of the @closure to - * the life time of the object. That is, when the object is finalized, - * the @closure is invalidated by calling g_closure_invalidate() on - * it, in order to prevent invocations of the closure with a finalized - * (nonexisting) object. Also, g_object_ref() and g_object_unref() are - * added as marshal guards to the @closure, to ensure that an extra - * reference count is held on @object during invocation of the - * use this @object as closure data. - */ - - -/** - * g_object_weak_ref: (skip) - * @object: #GObject to reference weakly - * @notify: callback to invoke before the object is freed - * @data: extra data to pass to notify + * Checks if @type is a deep derivable type. A deep derivable type + * can be used as the base class of a deep (multi-level) class hierarchy. * - * Adds a weak reference callback to an object. Weak references are - * used for notification when an object is finalized. They are called - * "weak references" because they allow you to safely hold a pointer - * to an object without calling g_object_ref() (g_object_ref() adds a - * strong reference, that is, forces the object to stay alive). + * Returns: %TRUE on success. */ /** - * G_PRIORITY_LOW: + * G_TYPE_IS_DERIVABLE: + * @type: A #GType value. * - * Use this for very low priority background tasks. - * It is not used within GLib or GTK+. - */ - - -/** - * g_object_freeze_notify: - * @object: a #GObject + * Checks if @type is a derivable type. A derivable type can + * be used as the base class of a flat (single-level) class hierarchy. * - * Increases the freeze count on @object. If the freeze count is - * non-zero, the emission of "notify" signals on @object is - * stopped. The signals are queued until the freeze count is decreased - * to zero. - * This is necessary for accessors that modify multiple properties to prevent - * premature notification while the object is still being modified. + * Returns: %TRUE on success. */ /** - * G_TYPE_PARAM_LONG: + * G_TYPE_IS_DERIVED: + * @type: A #GType value. * - * The #GType of #GParamSpecLong. - */ - - -/** - * G_PARAM_SPEC_CLASS: - * @pclass: a valid #GParamSpecClass + * Checks if @type is derived (or in object-oriented terminology: + * inherited) from another type (this holds true for all non-fundamental + * types). * - * Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. + * Returns: %TRUE on success. */ /** - * g_value_get_gtype: - * @value: a valid #GValue of type %G_TYPE_GTYPE + * G_TYPE_IS_ENUM: + * @type: a #GType ID. * - * Get the contents of a %G_TYPE_GTYPE #GValue. + * Checks whether @type "is a" %G_TYPE_ENUM. * - * Since: 2.12 - * Returns: the #GType stored in @value + * Returns: %TRUE if @type "is a" %G_TYPE_ENUM. */ /** - * g_signal_newv: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST - * @class_closure: The closure to invoke on signal emission; may be %NULL - * @accumulator: the accumulator for this signal; may be %NULL - * @accu_data: user data for the @accumulator - * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value - * @n_params: the length of @param_types - * @param_types: an array of types, one for each parameter - * - * Creates a new signal. (This is usually done in the class initializer.) - * See g_signal_new() for details on allowed signal names. + * G_TYPE_IS_FLAGS: + * @type: a #GType ID. * - * Returns: the signal id - */ - - -/** - * G_TYPE_PARAM_STRING: + * Checks whether @type "is a" %G_TYPE_FLAGS. * - * The #GType of #GParamSpecString. + * Returns: %TRUE if @type "is a" %G_TYPE_FLAGS. */ /** - * G_TYPE_IS_ABSTRACT: + * G_TYPE_IS_FUNDAMENTAL: * @type: A #GType value. * - * Checks if @type is an abstract type. An abstract type can not be - * instantiated and is normally used as an abstract base class for - * derived classes. + * Checks if @type is a fundamental type. * * Returns: %TRUE on success. */ /** - * g_param_spec_ref: (skip) - * @pspec: a valid #GParamSpec + * G_TYPE_IS_INSTANTIATABLE: + * @type: A #GType value. * - * Increments the reference count of @pspec. + * Checks if @type can be instantiated. Instantiation is the + * process of creating an instance (object) of this type. * - * Returns: the #GParamSpec that was passed into this function + * Returns: %TRUE on success. */ /** - * g_value_get_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type + * G_TYPE_IS_INTERFACE: + * @type: A #GType value. * - * Get the contents of a %G_TYPE_BOXED derived #GValue. + * 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 + * interfaces and C++ classes containing only pure virtual functions, + * with the difference that GType interfaces are not derivable (but see + * g_type_interface_add_prerequisite() for an alternative). * - * Returns: (transfer none): boxed contents of @value + * Returns: %TRUE on success. */ /** - * g_value_peek_pointer: - * @value: An initialized #GValue structure. + * G_TYPE_IS_OBJECT: + * @type: Type id to check * - * function asserts that g_value_fits_pointer() returned %TRUE for the - * passed in value. This is an internal function introduced mainly - * for C marshallers. + * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. * - * Returns: (transfer none): the value contents as pointer. This + * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. */ /** - * g_main_destroy: - * @loop: a #GMainLoop - * - * Frees the memory allocated for the #GMainLoop. + * G_TYPE_IS_PARAM: + * @type: a #GType ID * - * Deprecated: 2.2: Use g_main_loop_unref() instead + * Checks whether @type "is a" %G_TYPE_PARAM. */ /** - * GTypeInterfaceCheckFunc: - * @check_data: data passed to g_type_add_interface_check(). - * @g_iface: the interface that has been initialized + * G_TYPE_IS_VALUE: + * @type: A #GType value. * - * A callback called after an interface vtable is initialized. - * See g_type_add_interface_check(). + * 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. * - * Since: 2.4 + * Returns: Whether @type is suitable as a #GValue type. */ /** - * G_TYPE_HAS_VALUE_TABLE: + * G_TYPE_IS_VALUE_ABSTRACT: * @type: A #GType value. * - * Checks if @type has a #GTypeValueTable. + * Checks if @type is an abstract value type. An abstract value type introduces + * a value table, but can't be used for g_value_init() and is normally used as + * an abstract base type for derived value types. * * Returns: %TRUE on success. */ /** - * g_type_class_peek_static: - * @type: Type ID of a classed type. - * - * A more efficient version of g_type_class_peek() which works only for - * static types. - * structure for the given type ID or %NULL if the class does not - * currently exist or is dynamically loaded. - * - * Since: 2.4 - * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass - */ - - -/** - * g_signal_handler_is_connected: - * @instance: The instance where a signal handler is sought. - * @handler_id: the handler id. + * G_TYPE_IS_VALUE_TYPE: + * @type: A #GType value. * - * Returns whether @handler_id is the id of a handler connected to @instance. + * Checks if @type is a value type and can be used with g_value_init(). * - * Returns: whether @handler_id identifies a handler connected to @instance. + * Returns: %TRUE on success. */ /** - * g_param_spec_boolean: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN - * property. - * See g_param_spec_internal() for details on property names. + * G_TYPE_LONG: * - * Returns: a newly created parameter specification + * The fundamental type corresponding to #glong. */ /** - * G_DEFINE_DYNAMIC_TYPE_EXTENDED: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @TYPE_PARENT: The #GType of the parent type. - * @flags: #GTypeFlags to pass to g_type_module_register_type() - * @CODE: Custom code that gets inserted in the *_get_type() function. + * G_TYPE_MAKE_FUNDAMENTAL: + * @x: the fundamental type number. * - * A more general version of G_DEFINE_DYNAMIC_TYPE() which - * allows to specify #GTypeFlags and custom code. - * |[ - * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, - * gtk_gadget, - * GTK_TYPE_THING, - * 0, - * G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO, - * gtk_gadget_gizmo_init)); - * ]| - * expands to - * |[ - * static void gtk_gadget_init (GtkGadget *self); - * static void gtk_gadget_class_init (GtkGadgetClass *klass); - * static void gtk_gadget_class_finalize (GtkGadgetClass *klass); - * static gpointer gtk_gadget_parent_class = NULL; - * static GType gtk_gadget_type_id = 0; - * static void gtk_gadget_class_intern_init (gpointer klass) - * { - * gtk_gadget_parent_class = g_type_class_peek_parent (klass); - * gtk_gadget_class_init ((GtkGadgetClass*) klass); - * } - * GType - * gtk_gadget_get_type (void) - * { - * return gtk_gadget_type_id; - * } - * static void - * gtk_gadget_register_type (GTypeModule *type_module) - * { - * const GTypeInfo g_define_type_info = { - * sizeof (GtkGadgetClass), - * (GBaseInitFunc) NULL, - * (GBaseFinalizeFunc) NULL, - * (GClassInitFunc) gtk_gadget_class_intern_init, - * (GClassFinalizeFunc) gtk_gadget_class_finalize, - * NULL, // class_data - * sizeof (GtkGadget), - * 0, // n_preallocs - * (GInstanceInitFunc) gtk_gadget_init, - * NULL // value_table - * }; - * gtk_gadget_type_id = g_type_module_register_type (type_module, - * GTK_TYPE_THING, - * GtkGadget, - * &g_define_type_info, - * (GTypeFlags) flags); - * { - * const GInterfaceInfo g_implement_interface_info = { - * (GInterfaceInitFunc) gtk_gadget_gizmo_init - * }; - * g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); - * } - * } - * ]| + * Get the type ID for the fundamental type number @x. + * Use g_type_fundamental_next() instead of this macro to create new fundamental + * types. * - * Since: 2.14 + * Returns: the GType */ /** - * GSignalInvocationHint: - * @signal_id: The signal id of the signal invoking the callback - * @detail: The detail passed on for this emission - * @run_type: 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_TYPE_NONE: * - * The #GSignalInvocationHint structure is used to pass on additional information - * to callbacks during a signal emission. + * A fundamental type which is used as a replacement for the C + * <literal>void</literal> return type. */ /** - * GTypeFundamentalInfo: - * @type_flags: #GTypeFundamentalFlags describing the characteristics of the fundamental type + * G_TYPE_OBJECT: * - * A structure that provides information to the type system which is - * used specifically for managing fundamental types. + * The fundamental type for #GObject. */ /** - * g_param_value_set_default: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec + * G_TYPE_PARAM: * - * Sets @value to its default value as specified in @pspec. + * The fundamental type from which all #GParamSpec types are derived. */ /** - * G_TYPE_VARIANT: - * - * The fundamental type corresponding to #GVariant. - * All floating #GVariant instances passed through the #GType system are - * consumed. - * Note that callbacks in closures, and signal handlers - * for signals of return type %G_TYPE_VARIANT, must never return floating - * variants. - * with this fundamental type in 2.26. + * G_TYPE_PARAM_BOOLEAN: * - * Note: GLib 2.24 did include a boxed type with this name. It was replaced - * Since: 2.26 + * The #GType of #GParamSpecBoolean. */ /** - * G_DEFINE_TYPE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * - * 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. See G_DEFINE_TYPE_EXTENDED() for an example. + * G_TYPE_PARAM_BOXED: * - * Since: 2.4 + * The #GType of #GParamSpecBoxed. */ /** - * g_signal_handlers_unblock_by_func: - * @instance: The instance to unblock handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. - * - * Unblocks all handlers on an instance that match @func and @data. + * G_TYPE_PARAM_CHAR: * - * Returns: The number of handlers that matched. + * The #GType of #GParamSpecChar. */ /** - * g_value_set_enum: - * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM - * @v_enum: enum value to be set + * G_TYPE_PARAM_DOUBLE: * - * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. + * The #GType of #GParamSpecDouble. */ /** - * g_param_spec_steal_qdata: - * @pspec: the #GParamSpec to get a stored user data pointer from - * @quark: a #GQuark, naming the user data pointer - * - * Gets back user data pointers stored via g_param_spec_set_qdata() - * and removes the @data from @pspec without invoking its destroy() - * function (if any was set). Usually, calling this function is only - * required to update user data pointers with a destroy notifier. + * G_TYPE_PARAM_ENUM: * - * Returns: (transfer none): the user data pointer set, or %NULL + * The #GType of #GParamSpecEnum. */ /** - * G_VARIANT_TYPE_ANY: + * G_TYPE_PARAM_FLAGS: * - * An indefinite type that is a supertype of every type (including - * itself). + * The #GType of #GParamSpecFlags. */ /** - * GInterfaceInitFunc: - * @g_iface: The interface structure to initialize. - * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. + * G_TYPE_PARAM_FLOAT: * - * 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. + * The #GType of #GParamSpecFloat. */ /** - * GBinding:target-property: + * G_TYPE_PARAM_GTYPE: * - * The name of the property of #GBinding:target that should be used - * as the target of the binding + * The #GType of #GParamSpecGType. * - * Since: 2.26 + * Since: 2.10 */ /** - * g_object_weak_unref: (skip) - * @object: #GObject to remove a weak reference from - * @notify: callback to search for - * @data: data to search for + * G_TYPE_PARAM_INT: * - * Removes a weak reference callback to an object. + * The #GType of #GParamSpecInt. */ /** - * g_node_append_data: - * @parent: the #GNode to place the new #GNode under - * @data: the data for the new #GNode - * - * Inserts a new #GNode as the last child of the given parent. + * G_TYPE_PARAM_INT64: * - * Returns: the new #GNode + * The #GType of #GParamSpecInt64. */ /** - * G_VARIANT_TYPE_DICTIONARY: + * G_TYPE_PARAM_LONG: * - * An indefinite type that is a supertype of every dictionary type -- - * that is, any array type that has an element type equal to any - * dictionary entry type. + * The #GType of #GParamSpecLong. */ /** - * g_type_name: - * @type: Type to return name for. - * - * Get the unique name that is assigned to a type ID. Note that this - * function (like all other GType API) cannot cope with invalid type - * IDs. %G_TYPE_INVALID may be passed to this function, as may be any - * other validly registered type ID, but randomized type IDs should - * not be passed in and will most likely lead to a crash. + * G_TYPE_PARAM_OBJECT: * - * Returns: Static type name or %NULL. + * The #GType of #GParamSpecObject. */ /** - * g_atomic_int_dec_and_test: - * @atomic: a pointer to an integer + * G_TYPE_PARAM_OVERRIDE: * - * Atomically decrements the integer pointed to by @atomic by 1. - * after decrementing it + * The #GType of #GParamSpecOverride. * - * Returns: %TRUE if the integer pointed to by @atomic is 0 * Since: 2.4 */ /** - * g_cclosure_marshal_VOID__INT: - * @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 + * G_TYPE_PARAM_PARAM: * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>. + * The #GType of #GParamSpecParam. */ /** - * g_value_dup_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * - * Get the contents of a variant #GValue, increasing its refcount. - * g_variant_unref() when no longer needed + * G_TYPE_PARAM_POINTER: * - * Returns: variant contents of @value, should be unrefed using - * Since: 2.26 + * The #GType of #GParamSpecPointer. */ /** - * G_TYPE_BOXED: + * G_TYPE_PARAM_STRING: * - * The fundamental type from which all boxed types are derived. + * The #GType of #GParamSpecString. */ /** - * g_value_get_long: - * @value: a valid #GValue of type %G_TYPE_LONG - * - * Get the contents of a %G_TYPE_LONG #GValue. + * G_TYPE_PARAM_UCHAR: * - * Returns: long integer contents of @value + * The #GType of #GParamSpecUChar. */ /** - * G_PARAM_SPEC_UINT64: - * @pspec: a valid #GParamSpec instance + * G_TYPE_PARAM_UINT: * - * Cast a #GParamSpec instance into a #GParamSpecUInt64. + * The #GType of #GParamSpecUInt. */ /** - * G_FLAGS_CLASS_TYPE: - * @class: a #GFlagsClass - * - * Get the type identifier from a given #GFlagsClass structure. + * G_TYPE_PARAM_UINT64: * - * Returns: the #GType + * The #GType of #GParamSpecUInt64. */ /** - * g_value_get_boolean: - * @value: a valid #GValue of type %G_TYPE_BOOLEAN - * - * Get the contents of a %G_TYPE_BOOLEAN #GValue. + * G_TYPE_PARAM_ULONG: * - * Returns: boolean contents of @value + * The #GType of #GParamSpecULong. */ /** - * 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 - * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)</literal>. + * G_TYPE_PARAM_UNICHAR: * - * Since: 2.26 + * The #GType of #GParamSpecUnichar. */ /** - * G_PRIORITY_HIGH_IDLE: + * G_TYPE_PARAM_VALUE_ARRAY: * - * Use this for high priority idle functions. - * GTK+ uses #G_PRIORITY_HIGH_IDLE + 10 for resizing operations, - * and #G_PRIORITY_HIGH_IDLE + 20 for redrawing operations. (This is - * done to ensure that any pending resizes are processed before any - * pending redraws, so that widgets are not redrawn twice unnecessarily.) + * The #GType of #GParamSpecValueArray. */ /** - * G_TYPE_IS_DEEP_DERIVABLE: - * @type: A #GType value. + * G_TYPE_PARAM_VARIANT: * - * Checks if @type is a deep derivable type. A deep derivable type - * can be used as the base class of a deep (multi-level) class hierarchy. + * The #GType of #GParamSpecVariant. * - * Returns: %TRUE on success. + * Since: 2.26 */ /** - * G_TYPE_FUNDAMENTAL_SHIFT: + * G_TYPE_POINTER: * - * Shift value used in converting numbers to type IDs. + * The fundamental type corresponding to #gpointer. */ /** - * GSignalFlags: - * @G_SIGNAL_RUN_FIRST: Invoke the object method handler in the first emission stage. - * @G_SIGNAL_RUN_LAST: Invoke the object method handler in the third emission stage. - * @G_SIGNAL_RUN_CLEANUP: Invoke the object method handler in the last emission stage. - * @G_SIGNAL_NO_RECURSE: Signals being emitted for an object while currently being in emission for this very object will not be emitted recursively, but instead cause the first emission to be restarted. - * @G_SIGNAL_DETAILED: This signal supports "::detail" appendices to the signal name upon handler connections and emissions. - * @G_SIGNAL_ACTION: Action signals are signals that may freely be emitted on alive objects from user code via g_signal_emit() and friends, without the need of being embedded into extra code that performs pre or post emission adjustments on the object. They can also be thought of as object methods which can be called generically by third-party code. - * @G_SIGNAL_NO_HOOKS: No emissions hooks are supported for this signal. + * G_TYPE_PTR_ARRAY: * - * 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 #GType for a boxed type holding a #GPtrArray reference. + * + * Since: 2.22 */ /** - * GParamSpecGType: - * @parent_instance: private #GParamSpec portion - * @is_a_type: a #GType whose subtypes can occur as values + * G_TYPE_REGEX: * - * A #GParamSpec derived structure that contains the meta data for #GType properties. + * The #GType for a boxed type holding a #GRegex reference. * - * Since: 2.10 + * Since: 2.14 */ /** - * g_value_array_prepend: - * @value_array: #GValueArray to add an element to - * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL - * - * Insert a copy of @value as first element of @value_array. If @value is - * %NULL, an uninitialized value is prepended. + * G_TYPE_RESERVED_BSE_FIRST: * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * First fundamental type number to create a new fundamental type id with + * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. */ /** - * G_TYPE_DATE: + * G_TYPE_RESERVED_BSE_LAST: * - * The #GType for #GDate. + * Last fundamental type number reserved for BSE. */ /** - * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITER: + * G_TYPE_RESERVED_GLIB_FIRST: * - * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". + * First fundamental type number to create a new fundamental type id with + * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. */ /** - * GEnumValue: - * @value: the enum value - * @value_name: the name of the value - * @value_nick: the nickname of the value + * G_TYPE_RESERVED_GLIB_LAST: * - * A structure which contains a single enum value, its name, and its - * nickname. + * Last fundamental type number reserved for GLib. */ /** - * GParamSpecFloat: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. + * G_TYPE_RESERVED_USER_FIRST: * - * A #GParamSpec derived structure that contains the meta data for float properties. + * First available fundamental type number to create new fundamental + * type id with G_TYPE_MAKE_FUNDAMENTAL(). */ /** - * g_value_array_insert: - * @value_array: #GValueArray to add an element to - * @index_: insertion position, must be <= value_array->n_values - * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL - * - * Insert a copy of @value at specified position into @value_array. If @value - * is %NULL, an uninitialized value is inserted. + * G_TYPE_STRING: * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * The fundamental type corresponding to nul-terminated C strings. */ /** - * g_value_get_float: - * @value: a valid #GValue of type %G_TYPE_FLOAT + * G_TYPE_STRV: * - * Get the contents of a %G_TYPE_FLOAT #GValue. + * The #GType for a boxed type holding a %NULL-terminated array of strings. + * The code fragments in the following example show the use of a property of + * type #G_TYPE_STRV with g_object_class_install_property(), g_object_set() + * and g_object_get(). + * |[ + * g_object_class_install_property (object_class, + * PROP_AUTHORS, + * g_param_spec_boxed ("authors", + * _("Authors"), + * _("List of authors"), + * G_TYPE_STRV, + * G_PARAM_READWRITE)); + * gchar *authors[] = { "Owen", "Tim", NULL }; + * g_object_set (obj, "authors", authors, NULL); + * gchar *writers[]; + * g_object_get (obj, "authors", &writers, NULL); + * // do something with writers + * g_strfreev (writers); + * ]| * - * Returns: float contents of @value + * Since: 2.4 */ /** - * SECTION:signal: - * @short_description: A means for customization of object behaviour and a general purpose notification mechanism - * @title: Signals + * G_TYPE_UCHAR: * - * The basic concept of the signal system is that of the - * <emphasis>emission</emphasis> of a signal. Signals are introduced - * per-type and are identified through strings. Signals introduced - * for a parent type are available in derived types as well, so - * basically they are a per-type facility that is inherited. A signal - * emission mainly involves invocation of a certain set of callbacks - * in precisely defined manner. There are two main categories of such - * callbacks, per-object - * <footnote><para>Although signals can deal with any kind of instantiatable - * type, i'm referring to those types as "object types" in the following, - * simply because that is the context most users will encounter signals in. - * </para></footnote> - * ones and user provided ones. - * The per-object callbacks are most often referred to as "object method - * handler" or "default (signal) handler", while user provided callbacks are - * usually just called "signal handler". - * The object method handler is provided at signal creation time (this most - * frequently happens at the end of an object class' creation), while user - * provided handlers are frequently connected and disconnected to/from a certain - * signal on certain object instances. - * A signal emission consists of five stages, unless prematurely stopped: - * <variablelist> - * <varlistentry><term></term><listitem><para> - * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * </para></listitem></varlistentry> - * </variablelist> - * The user-provided signal handlers are called in the order they were - * connected in. - * All handlers may prematurely stop a signal emission, and any number of - * handlers may be connected, disconnected, blocked or unblocked during - * a signal emission. - * There are certain criteria for skipping user handlers in stages 2 and 4 - * of a signal emission. - * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted - * during callback invocation, to return from the "blocked" state, a - * handler has to get unblocked exactly the same amount of times - * it has been blocked before. - * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional - * "detail" argument passed in to g_signal_emit() has to match the detail - * argument of the signal handler currently subject to invocation. - * Specification of no detail argument for signal handlers (omission of the - * detail part of the signal specification upon connection) serves as a - * wildcard and matches any detail argument passed in to emission. + * The fundamental type corresponding to #guchar. */ /** - * SECTION:value_collectio: - * @Short_description: Converting varargs to generic values - * @Title: Varargs Value Collection + * G_TYPE_UINT: * - * The macros in this section provide the varargs parsing support needed - * in variadic GObject functions such as g_object_new() or g_object_set(). - * They currently support the collection of integral types, floating point - * types and pointers. + * The fundamental type corresponding to #guint. */ /** - * G_TYPE_STRING: + * G_TYPE_UINT64: * - * The fundamental type corresponding to nul-terminated C strings. + * The fundamental type corresponding to #guint64. */ /** - * G_VARIANT_TYPE_UINT32: + * G_TYPE_ULONG: * - * The type of an integer value that can range from 0 to 4294967295. - * That's one number for everyone who was around in the late 1970s. + * The fundamental type corresponding to #gulong. */ /** - * g_type_init: + * G_TYPE_VALUE: * - * Prior to any use of the type system, g_type_init() has to be called - * to initialize the type system and assorted other code portions - * (such as the various fundamental type implementations or the signal - * system). - * Since version 2.24 this also initializes the thread system + * The type ID of the "GValue" type which is a boxed type, + * used to pass around pointers to GValues. */ /** - * g_renew: - * @struct_type: the type of the elements to allocate - * @mem: the currently allocated memory - * @n_structs: the number of elements to allocate - * - * Reallocates the memory pointed to by @mem, so that it now has space for - * the memory, which may have been moved. - * Care is taken to avoid overflow when calculating the size of the allocated block. + * G_TYPE_VALUE_ARRAY: * - * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type + * The type ID of the "GValueArray" type which is a boxed type, + * used to pass around pointers to GValueArrays. */ /** - * g_param_spec_get_qdata: - * @pspec: a valid #GParamSpec - * @quark: a #GQuark, naming the user data pointer + * G_TYPE_VARIANT: * - * Gets back user data pointers stored via g_param_spec_set_qdata(). + * The fundamental type corresponding to #GVariant. + * All floating #GVariant instances passed through the #GType system are + * consumed. + * Note that callbacks in closures, and signal handlers + * for signals of return type %G_TYPE_VARIANT, must never return floating + * variants. + * with this fundamental type in 2.26. * - * Returns: (transfer none): the user data pointer set, or %NULL + * Note: GLib 2.24 did include a boxed type with this name. It was replaced + * Since: 2.26 */ /** - * G_OBJECT_TYPE_NAME: - * @object: Object to return the type name for. + * G_TYPE_VARIANT_TYPE: * - * Get the name of an object's type. - * should not be freed. + * The #GType for a boxed type holding a #GVariantType. * - * Returns: Type name of @object. The string is owned by the type system and + * Since: 2.24 */ /** - * g_param_type_register_static: - * @name: 0-terminated string used as the name of the new #GParamSpec type. - * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. - * - * 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. + * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH: * - * Returns: The new type identifier. + * Allowed characters in a path. Includes "!$&'()*+,;=:@/". */ /** - * G_ENUM_CLASS_TYPE: - * @class: a #GEnumClass - * - * Get the type identifier from a given #GEnumClass structure. + * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT: * - * Returns: the #GType + * Allowed characters in path elements. Includes "!$&'()*+,;=:@". */ /** - * GCopyFunc: - * @src: A pointer to the data which should be copied - * @data: Additional data - * - * A function of this signature is used to copy the node data - * when doing a deep-copy of a tree. + * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO: * - * Returns: A pointer to the copy - * Since: 2.4 + * Allowed characters in userinfo as defined in RFC 3986. Includes "!$&'()*+,;=:". */ /** - * G_TYPE_FLOAT: + * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS: * - * The fundamental type corresponding to #gfloat. + * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". */ /** - * G_VALUE_HOLDS_UCHAR: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. + * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITER: * - * Returns: %TRUE on success. + * Subcomponent delimiter characters as defined in RFC 3986. Includes "!$&'()*+,;=". */ /** - * G_TYPE_IS_INSTANTIATABLE: - * @type: A #GType value. + * G_VALUE_COLLECT: + * @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected + * @var_args: the va_list variable; it may be evaluated multiple times + * @flags: flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. + * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails * - * Checks if @type can be instantiated. Instantiation is the - * process of creating an instance (object) of this type. + * Collects a variable argument value from a va_list. We have to + * implement the varargs collection as a macro, because on some systems + * va_list variables cannot be passed by reference. + * you should use the #G_VALUE_COLLECT_INIT variant and pass the unitialized + * #GValue. That variant is faster than #G_VALUE_COLLECT. * - * Returns: %TRUE on success. + * Note: If you are creating the @value argument just before calling this macro, */ /** - * GSignalEmissionHook: - * @ihint: Signal invocation hint, see #GSignalInvocationHint. - * @n_param_values: the number of parameters to the function, including the instance on which the signal was emitted. - * @param_values: the instance on which the signal was emitted, followed by the parameters of the emission. - * @data: user data associated with the hook. - * - * 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. - * You may not attach these to signals created with the #G_SIGNAL_NO_HOOKS flag. - * hook is disconnected (and destroyed). + * G_VALUE_COLLECT_FORMAT_MAX_LENGTH: * - * Returns: whether it wants to stay connected. If it returns %FALSE, the signal + * The maximal number of #GTypeCValue<!-- -->s which can be collected for a + * single #GValue. */ /** - * G_CLOSURE_NEEDS_MARSHAL: - * @closure: a #GClosure + * G_VALUE_COLLECT_INIT: + * @value: a #GValue return location. @value must contain only 0 bytes. + * @_value_type: the #GType to use for @value. + * @var_args: the va_list variable; it may be evaluated multiple times + * @flags: flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. + * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails * - * Check if the closure still needs a marshaller. See g_closure_set_marshal(). + * Collects a variable argument value from a va_list. We have to + * implement the varargs collection as a macro, because on some systems + * va_list variables cannot be passed by reference. * - * Returns: %TRUE if a #GClosureMarshal marshaller has not yet been set on + * Since: 2.24 */ /** - * g_type_plugin_use: - * @plugin: a #GTypePlugin + * G_VALUE_HOLDS: + * @value: A #GValue structure. + * @type: A #GType value. * - * Calls the @use_plugin function from the #GTypePluginClass of - * the GObject type system itself. + * Checks if @value holds (or contains) a value of @type. + * This macro will also check for @value != %NULL and issue a + * warning if the check fails. + * + * Returns: %TRUE if @value holds the @type. */ /** - * G_TYPE_INSTANCE_GET_CLASS: - * @instance: Location of the #GTypeInstance structure. - * @g_type: The #GType of the class to be returned. - * @c_type: The C type of the class structure. + * G_VALUE_HOLDS_BOOLEAN: + * @value: a valid #GValue structure * - * Get the class structure of a given @instance, casted - * to a specified ancestor type @g_type of the instance. - * Note that while calling a GInstanceInitFunc(), the class pointer gets - * modified, so it might not always return the expected pointer. - * This macro should only be used in type implementations. + * Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. * - * Returns: a pointer to the class structure + * Returns: %TRUE on success. */ /** - * g_object_class_install_properties: - * @oclass: a #GObjectClass - * @n_pspecs: the length of the #GParamSpec<!-- -->s array - * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array defining the new properties + * G_VALUE_HOLDS_BOXED: + * @value: a valid #GValue structure * - * Installs new properties from an array of #GParamSpec<!-- -->s. This is - * usually done in the class initializer. - * The property id of each property is the index of each #GParamSpec in - * the @pspecs array. - * The property id of 0 is treated specially by #GObject and it should not - * be used to store a #GParamSpec. - * This function should be used if you plan to use a static array of - * #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this - * class initialization: - * |[ - * enum { - * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES - * }; - * static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; - * static void - * my_object_class_init (MyObjectClass *klass) - * { - * GObjectClass *gobject_class = G_OBJECT_CLASS (klass); - * obj_properties[PROP_FOO] = - * g_param_spec_int ("foo", "Foo", "Foo", - * -1, G_MAXINT, - * 0, - * G_PARAM_READWRITE); - * obj_properties[PROP_BAR] = - * g_param_spec_string ("bar", "Bar", "Bar", - * NULL, - * G_PARAM_READWRITE); - * gobject_class->set_property = my_object_set_property; - * gobject_class->get_property = my_object_get_property; - * g_object_class_install_properties (gobject_class, - * N_PROPERTIES, - * obj_properties); - * } - * ]| - * allows calling g_object_notify_by_pspec() to notify of property changes: - * |[ - * void - * my_object_set_foo (MyObject *self, gint foo) - * { - * if (self->foo != foo) - * { - * self->foo = foo; - * g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]); - * } - * } - * ]| + * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_value_set_object: - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: (type GObject.Object): object value to be set + * G_VALUE_HOLDS_CHAR: + * @value: a valid #GValue structure * - * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. - * g_value_set_object() increases the reference count of @v_object - * (the #GValue holds a reference to @v_object). If you do not wish - * to increase the reference count of the object (i.e. you wish to - * pass your current reference to the #GValue because you no longer - * need it), use g_value_take_object() instead. - * It is important that your #GValue holds a reference to @v_object (either its - * own, or one it has taken) to ensure that the object won't be destroyed while - * the #GValue still exists). - */ - - -/** - * G_VARIANT_TYPE_ARRAY: + * Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. * - * An indefinite type that is a supertype of every array type. + * Returns: %TRUE on success. */ /** - * GTypePluginUse: - * @plugin: the #GTypePlugin whose use count should be increased + * G_VALUE_HOLDS_DOUBLE: + * @value: a valid #GValue structure * - * The type of the @use_plugin function of #GTypePluginClass, which gets called - * to increase the use count of @plugin. - */ - - -/** - * G_VARIANT_TYPE_DOUBLE: + * Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. * - * The type of a double precision IEEE754 floating point number. - * These guys go up to about 1.80e308 (plus and minus) but miss out on - * some numbers in between. In any case, that's far greater than the - * estimated number of fundamental particles in the observable - * universe. + * Returns: %TRUE on success. */ /** - * g_closure_add_invalidate_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data to pass to @notify_func - * @notify_func: the callback function to register + * G_VALUE_HOLDS_ENUM: + * @value: a valid #GValue structure * - * Registers an invalidation notifier which will be called when the - * notifiers are invoked before finalization notifiers, in an - * unspecified order. - */ - - -/** - * G_TYPE_FLAGS: + * Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. * - * The fundamental type from which all flags types are derived. + * Returns: %TRUE on success. */ /** - * G_PARAM_STATIC_STRINGS: + * G_VALUE_HOLDS_FLAGS: + * @value: a valid #GValue structure * - * #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. - * Since 2.13.0 + * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. + * + * Returns: %TRUE on success. */ /** - * g_enum_register_static: - * @name: A nul-terminated string used as the name of the new type. - * @const_static_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. + * G_VALUE_HOLDS_FLOAT: + * @value: a valid #GValue structure * - * Registers a new static enumeration type with the name @name. - * It is normally more convenient to let <link - * linkend="glib-mkenums">glib-mkenums</link> generate a - * my_enum_get_type() function from a usual C enumeration definition - * than to write one yourself using g_enum_register_static(). + * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. * - * Returns: The new type identifier. + * Returns: %TRUE on success. */ /** - * GFlagsClass: - * @g_type_class: the parent class - * @mask: a mask covering all possible values. - * @n_values: the number of possible values. - * @values: an array of #GFlagsValue structs describing the individual values. + * G_VALUE_HOLDS_GTYPE: + * @value: a valid #GValue structure * - * The class of a flags type holds information about its - * possible values. - */ - - -/** - * g_object_set_data: - * @object: #GObject containing the associations. - * @key: name of the key - * @data: data to associate with that key + * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. * - * Each object carries around a table of associations from - * strings to pointers. This function lets you set an association. - * If the object already had an association with that name, - * the old association will be destroyed. + * Since: 2.12 + * Returns: %TRUE on success. */ /** - * G_TYPE_VALUE: + * G_VALUE_HOLDS_INT: + * @value: a valid #GValue structure * - * The type ID of the "GValue" type which is a boxed type, - * used to pass around pointers to GValues. - */ - - -/** - * G_TYPE_DOUBLE: + * Checks whether the given #GValue can hold values of type %G_TYPE_INT. * - * The fundamental type corresponding to #gdouble. + * Returns: %TRUE on success. */ /** - * GTypeValueTable: - * @value_init: Default initialize @values contents by poking values directly into the value->data array. The data array of the #GValue passed into this function was zero-filled with <function>memset()</function>, so no care has to be taken to free any old contents. E.g. for the implementation of a string value that may never be %NULL, the implementation might look like: |[ value->data[0].v_pointer = g_strdup (""); ]| - * @value_free: Free any old contents that might be left in the data array of the passed in @value. No resources may remain allocated through the #GValue contents after this function returns. E.g. for our above string type: |[ // only free strings without a specific flag for static storage if (!(value->data[1].v_uint & G_VALUE_NOCOPY_CONTENTS)) g_free (value->data[0].v_pointer); ]| - * @value_copy: @dest_value is a #GValue with zero-filled data section and @src_value is a properly setup #GValue of same or derived type. The purpose of this function is to copy the contents of remain valid. String type example: |[ dest_value->data[0].v_pointer = g_strdup (src_value->data[0].v_pointer); ]| - * @value_peek_pointer: If the value contents fit into a pointer, such as objects or strings, return this pointer, so the caller can peek at the current contents. To extend on our above string example: |[ return value->data[0].v_pointer; ]| - * @collect_format: A string format describing how to collect the contents of this value bit-by-bit. Each character in the format represents an argument to be collected, and the characters themselves indicate the type of the argument. Currently supported arguments are: <variablelist> <varlistentry><term /><listitem><para> 'i' - Integers. passed as collect_values[].v_int. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'l' - Longs. passed as collect_values[].v_long. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'd' - Doubles. passed as collect_values[].v_double. </para></listitem></varlistentry> <varlistentry><term /><listitem><para> 'p' - Pointers. passed as collect_values[].v_pointer. </para></listitem></varlistentry> </variablelist> It should be noted that for variable argument list construction, ANSI C promotes every type smaller than an integer to an int, and floats to doubles. So for collection of short int or char, 'i' needs to be used, and for collection of floats 'd'. - * @collect_value: The collect_value() function is responsible for converting the values collected from a variable argument list into contents suitable for storage in a GValue. This function should setup does not allow %NULL pointers, it needs to either spew an error, or do an implicit conversion by storing an empty string. The @value passed in to this function has a zero-filled data array, so just like for value_init() it is guaranteed to not contain any old contents that might need freeing. and @collect_values is an array of unions #GTypeCValue with length @n_collect_values, containing the collected values according to @collect_format. It may contain the flag %G_VALUE_NOCOPY_CONTENTS indicating, that the collected value contents may be considered "static" for the duration of the @value lifetime. Thus an extra copy of the contents stored in @collect_values is not required for assignment to @value. For our above string example, we continue with: |[ if (!collect_values[0].v_pointer) value->data[0].v_pointer = g_strdup (""); else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) { value->data[0].v_pointer = collect_values[0].v_pointer; // keep a flag for the value_free() implementation to not free this string value->data[1].v_uint = G_VALUE_NOCOPY_CONTENTS; } else value->data[0].v_pointer = g_strdup (collect_values[0].v_pointer); return NULL; ]| It should be noted, that it is generally a bad idea to follow the #G_VALUE_NOCOPY_CONTENTS hint for reference counted types. Due to reentrancy requirements and reference count assertions performed by the #GSignal code, reference counts should always be incremented for reference counted contents stored in the value->data array. To deviate from our string example for a moment, and taking a look at an exemplary implementation for collect_value() of #GObject: |[ if (collect_values[0].v_pointer) { GObject *object = G_OBJECT (collect_values[0].v_pointer); // never honour G_VALUE_NOCOPY_CONTENTS for ref-counted types value->data[0].v_pointer = g_object_ref (object); return NULL; } else return g_strdup_printf ("Object passed as invalid NULL pointer"); } ]| The reference count for valid objects is always incremented, regardless of @collect_flags. For invalid objects, the example returns a newly allocated string without altering @value. Upon success, collect_value() needs to return %NULL. If, however, an error condition occurred, collect_value() may spew an error by returning a newly allocated non-%NULL string, giving a suitable description of the error condition. The calling code makes no assumptions about the @value contents being valid upon error returns, @value is simply thrown away without further freeing. As such, it is a good idea to not allocate #GValue contents, prior to returning an error, however, collect_values() is not obliged to return a correctly setup @value for error returns, simply because any non-%NULL return is considered a fatal condition so further program behaviour is undefined. - * @lcopy_format: Format description of the arguments to collect for @lcopy_value, analogous to @collect_format. Usually, @lcopy_format string consists only of 'p's to provide lcopy_value() with pointers to storage locations. - * @lcopy_value: This function is responsible for storing the @value contents into arguments passed through a variable argument list which got collected into @collect_values according to @lcopy_format. and @collect_flags may contain %G_VALUE_NOCOPY_CONTENTS. In contrast to collect_value(), lcopy_value() is obliged to always properly support %G_VALUE_NOCOPY_CONTENTS. Similar to collect_value() the function may prematurely abort by returning a newly allocated string describing an error condition. To complete the string example: |[ gchar **string_p = collect_values[0].v_pointer; if (!string_p) return g_strdup_printf ("string location passed as NULL"); if (collect_flags & G_VALUE_NOCOPY_CONTENTS) *string_p = value->data[0].v_pointer; else *string_p = g_strdup (value->data[0].v_pointer); ]| And an illustrative version of lcopy_value() for reference-counted types: |[ GObject **object_p = collect_values[0].v_pointer; if (!object_p) return g_strdup_printf ("object location passed as NULL"); if (!value->data[0].v_pointer) *object_p = NULL; else if (collect_flags & G_VALUE_NOCOPY_CONTENTS) // always honour *object_p = value->data[0].v_pointer; else *object_p = g_object_ref (value->data[0].v_pointer); return NULL; ]| + * G_VALUE_HOLDS_INT64: + * @value: a valid #GValue structure * - * The #GTypeValueTable provides the functions required by the #GValue implementation, - * to serve as a container for values of a type. - */ - - -/** - * g_cclosure_marshal_VOID__ENUM: - * @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 + * Checks whether the given #GValue can hold values of type %G_TYPE_INT64. * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type.. + * Returns: %TRUE on success. */ /** - * G_VARIANT_TYPE_BOOLEAN: + * G_VALUE_HOLDS_LONG: + * @value: a valid #GValue structure * - * The type of a value that can be either %TRUE or %FALSE. - */ - - -/** - * G_PARAM_SPEC_STRING: - * @pspec: a valid #GParamSpec instance + * Checks whether the given #GValue can hold values of type %G_TYPE_LONG. * - * Casts a #GParamSpec instance into a #GParamSpecString. + * Returns: %TRUE on success. */ /** - * G_PARAM_SPEC_TYPE: - * @pspec: a valid #GParamSpec + * G_VALUE_HOLDS_OBJECT: + * @value: a valid #GValue structure * - * Retrieves the #GType of this @pspec. - */ - - -/** - * GClosureNotify: - * @data: data specified when registering the notification callback - * @closure: the #GClosure on which the notification is emitted + * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. * - * The type used for the various notification callbacks which can be registered - * on closures. + * Returns: %TRUE on success. */ /** - * G_VARIANT_TYPE_VARIANT: + * G_VALUE_HOLDS_PARAM: + * @value: a valid #GValue structure * - * The type of a box that contains any other value (including another - * variant). - */ - - -/** - * G_VARIANT_TYPE_BYTESTRING: + * Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. * - * The type of an array of bytes. This type is commonly used to pass - * around strings that may not be valid utf8. In that case, the - * convention is that the nul terminator character should be included as - * the last character in the array. + * Returns: %TRUE on success. */ /** - * GParamSpecVariant: - * @parent_instance: private #GParamSpec portion - * @type: a #GVariantType, or %NULL - * @default_value: a #GVariant, or %NULL + * G_VALUE_HOLDS_POINTER: + * @value: a valid #GValue structure * - * A #GParamSpec derived structure that contains the meta data for #GVariant properties. + * Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * G_TYPE_MAKE_FUNDAMENTAL: - * @x: the fundamental type number. + * G_VALUE_HOLDS_STRING: + * @value: a valid #GValue structure * - * Get the type ID for the fundamental type number @x. - * Use g_type_fundamental_next() instead of this macro to create new fundamental - * types. + * Checks whether the given #GValue can hold values of type %G_TYPE_STRING. * - * Returns: the GType + * Returns: %TRUE on success. */ /** - * g_object_add_toggle_ref: (skip) - * @object: a #GObject - * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. - * @data: data to pass to @notify + * G_VALUE_HOLDS_UCHAR: + * @value: a valid #GValue structure * - * Increases the reference count of the object by one and sets a - * callback to be called when all other references to the object are - * dropped, or when this is already the last reference to the object - * and another reference is established. - * This functionality is intended for binding @object to a proxy - * object managed by another memory manager. This is done with two - * g_object_add_toggle_ref() and a reverse reference to the proxy - * object which is either a strong reference or weak reference. - * The setup is that when there are no other references to @object, - * only a weak reference is held in the reverse direction from @object - * to the proxy object, but when there are other references held to - * when the reference from @object to the proxy object should be - * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref - * true) or weak to strong (@is_last_ref false). - * Since a (normal) reference must be held to the object before - * calling g_object_toggle_ref(), the initial state of the reverse - * link is always strong. - * Multiple toggle references may be added to the same gobject, - * however if there are multiple toggle references to an object, none - * of them will ever be notified until all but one are removed. For - * this reason, you should only ever use a toggle reference if there - * is important state in the proxy object. + * Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. * - * Paired references: the strong reference added by - * Since: 2.8 + * Returns: %TRUE on success. */ /** - * g_signal_handler_unblock: - * @instance: The instance to unblock the signal handler of. - * @handler_id: Handler id of the handler to be unblocked. + * G_VALUE_HOLDS_UINT: + * @value: a valid #GValue structure * - * Undoes the effect of a previous g_signal_handler_block() call. A - * blocked handler is skipped during signal emissions and will not be - * invoked, unblocking it (for exactly the amount of times it has been - * blocked before) reverts its "blocked" state, so the handler will be - * recognized by the signal system and is called upon future or - * currently ongoing signal emissions (since the order in which - * handlers are called during signal emissions is deterministic, - * whether the unblocked handler in question is called as part of a - * currently ongoing emission depends on how far that emission has - * proceeded yet). - * The @handler_id has to be a valid id of a signal handler that is - * connected to a signal of @instance and is currently blocked. + * Checks whether the given #GValue can hold values of type %G_TYPE_UINT. + * + * Returns: %TRUE on success. */ /** - * G_TIME_SPAN_DAY: + * G_VALUE_HOLDS_UINT64: + * @value: a valid #GValue structure * - * Evaluates to a time span of one day. + * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. * - * Since: 2.26 + * Returns: %TRUE on success. */ /** - * g_signal_chain_from_overridden_handler: - * @instance: the instance the signal is being emitted on. - * @...: parameters to be passed to the parent class closure, 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. + * G_VALUE_HOLDS_ULONG: + * @value: a valid #GValue structure * - * Calls the original class closure of a signal. This function should - * only be called from an overridden class closure; see - * g_signal_override_class_closure() and - * g_signal_override_class_handler(). + * Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. * - * Since: 2.18 + * Returns: %TRUE on success. */ /** - * g_param_spec_pool_insert: - * @pool: a #GParamSpecPool. - * @pspec: the #GParamSpec to insert - * @owner_type: a #GType identifying the owner of @pspec + * G_VALUE_HOLDS_VARIANT: + * @value: a valid #GValue structure * - * Inserts a #GParamSpec in the pool. + * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. + * + * Returns: %TRUE on success. + * Since: 2.26 */ /** - * g_type_register_static_simple: (skip) - * @parent_type: Type from which this type will be derived. - * @type_name: 0-terminated string used as the name of the new type. - * @class_size: Size of the class structure (see #GTypeInfo) - * @class_init: Location of the class initialization function (see #GTypeInfo) - * @instance_size: Size of the instance structure (see #GTypeInfo) - * @instance_init: Location of the instance initialization function (see #GTypeInfo) - * @flags: Bitwise combination of #GTypeFlags values. - * - * Registers @type_name as the name of a new static type derived from - * abstract or not) of the type. It works by filling a #GTypeInfo - * struct and calling g_type_register_static(). + * G_VALUE_LCOPY: + * @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected + * @var_args: the va_list variable; it may be evaluated multiple times + * @flags: flags which are passed on to the lcopy_value() function of the #GTypeValueTable of @value. + * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails * - * Since: 2.12 - * Returns: The new type identifier. + * Collects a value's variable argument locations from a va_list. Usage is + * analogous to G_VALUE_COLLECT(). */ /** - * G_TYPE_CHECK_INSTANCE: - * @instance: Location of a #GTypeInstance structure. + * G_VALUE_TYPE: + * @value: A #GValue structure. * - * Checks if @instance is a valid #GTypeInstance structure, - * otherwise issues a warning and returns %FALSE. - * This macro should only be used in type implementations. + * Get the type identifier of @value. * - * Returns: %TRUE on success. + * Returns: the #GType. */ /** - * g_param_spec_float: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * G_VALUE_TYPE_NAME: + * @value: A #GValue structure. * - * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. - * See g_param_spec_internal() for details on property names. + * Gets the the type name of @value. * - * Returns: a newly created parameter specification + * Returns: the type name. */ /** - * GSignalQuery: - * @signal_id: The signal id of the signal being queried, or 0 if the signal to be queried was unknown. - * @signal_name: The signal name. - * @itype: The interface/instance type that this signal can be emitted for. - * @signal_flags: The signal flags as passed in to g_signal_new(). - * @return_type: The return type for user callbacks. - * @n_params: The number of parameters that user callbacks take. - * @param_types: The individual parameter types for user callbacks, note that the effective callback signature is: <programlisting> [#param_types param_names,] #gpointer data2); </programlisting> + * G_VARIANT_TYPE: + * @type_string: a well-formed #GVariantType type string * - * A structure holding in-depth information for a specific signal. It is - * filled in by the g_signal_query() function. + * Converts a string to a const #GVariantType. Depending on the + * current debugging level, this function may perform a runtime check + * to ensure that @string is a valid GVariant type string. + * It is always a programmer error to use this macro with an invalid + * type string. + * Since 2.24 */ /** - * GTestLogFatalFunc: - * @log_domain: the log domain of the message - * @log_level: the log level of the message (including the fatal and recursion flags) - * @message: the message to process - * @user_data: user data, set in g_test_log_set_fatal_handler() - * - * Specifies the prototype of fatal log handler functions. + * G_VARIANT_TYPE_ANY: * - * Returns: %TRUE if the program should abort, %FALSE otherwise - * Since: 2.22 + * An indefinite type that is a supertype of every type (including + * itself). */ /** - * g_cclosure_marshal_VOID__UCHAR: - * @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 + * G_VARIANT_TYPE_ARRAY: * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>. + * An indefinite type that is a supertype of every array type. */ /** - * g_value_get_int64: - * @value: a valid #GValue of type %G_TYPE_INT64 - * - * Get the contents of a %G_TYPE_INT64 #GValue. + * G_VARIANT_TYPE_BASIC: * - * Returns: 64bit integer contents of @value + * An indefinite type that is a supertype of every basic (ie: + * non-container) type. */ /** - * g_cclosure_marshal_VOID__FLOAT: - * @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 + * G_VARIANT_TYPE_BOOLEAN: * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>. + * The type of a value that can be either %TRUE or %FALSE. */ /** - * g_signal_handler_disconnect: - * @instance: The instance to remove the signal handler from. - * @handler_id: Handler id of the handler to be disconnected. + * G_VARIANT_TYPE_BYTE: * - * Disconnects a handler from an instance so it will not be called during - * any future or currently ongoing emissions of the signal it has been - * connected to. The @handler_id becomes invalid and may be reused. - * The @handler_id has to be a valid signal handler id, connected to a - * signal of @instance. + * The type of an integer value that can range from 0 to 255. */ /** - * G_DEFINE_ABSTRACT_TYPE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_C_: Custom code that gets inserted in the @type_name_get_type() function. - * - * 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. interface implementations - * via G_IMPLEMENT_INTERFACE(). See G_DEFINE_TYPE_EXTENDED() for an example. + * G_VARIANT_TYPE_BYTESTRING: * - * Since: 2.4 + * The type of an array of bytes. This type is commonly used to pass + * around strings that may not be valid utf8. In that case, the + * convention is that the nul terminator character should be included as + * the last character in the array. */ /** - * g_signal_handlers_disconnect_by_func: - * @instance: The instance to remove handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. - * - * Disconnects all handlers on an instance that match @func and @data. + * G_VARIANT_TYPE_BYTESTRING_ARRAY: * - * Returns: The number of handlers that matched. + * The type of an array of byte strings (an array of arrays of bytes). */ /** - * GSourceFuncs: - * @prepare: Called before all the file descriptors are polled. If the source can determine that it is ready here (without waiting for the results of the poll() call) it should return %TRUE. It can also return a @timeout_ value which should be the maximum timeout (in milliseconds) which should be passed to the poll() call. The actual timeout used will be -1 if all sources returned -1, or it will be the minimum of all the - * @check: Called after all the file descriptors are polled. The source should return %TRUE if it is ready to be dispatched. Note that some time may have passed since the previous prepare function was called, so the source should be checked again here. - * @dispatch: Called to dispatch the event source, after it has returned %TRUE in either its @prepare or its @check function. The @dispatch function is passed in a callback function and data. The callback function may be %NULL if the source was never connected to a callback using g_source_set_callback(). The @dispatch function should call the callback function with @user_data and whatever additional parameters are needed for this type of event source. - * @finalize: Called when the source is finalized. + * G_VARIANT_TYPE_DICTIONARY: * - * The <structname>GSourceFuncs</structname> struct contains a table of - * functions used to handle event sources in a generic manner. - * For idle sources, the prepare and check functions always return %TRUE - * to indicate that the source is always ready to be processed. The prepare - * function also returns a timeout value of 0 to ensure that the poll() call - * doesn't block (since that would be time wasted which could have been spent - * running the idle function). - * For timeout sources, the prepare and check functions both return %TRUE - * if the timeout interval has expired. The prepare function also returns - * a timeout value to ensure that the poll() call doesn't block too long - * and miss the next timeout. - * For file descriptor sources, the prepare function typically returns %FALSE, - * since it must wait until poll() has been called before it knows whether - * any events need to be processed. It sets the returned timeout to -1 to - * indicate that it doesn't mind how long the poll() call blocks. In the - * check function, it tests the results of the poll() call to see if the - * required condition has been met, and returns %TRUE if so. + * An indefinite type that is a supertype of every dictionary type -- + * that is, any array type that has an element type equal to any + * dictionary entry type. */ /** - * G_TYPE_CHAR: + * G_VARIANT_TYPE_DICT_ENTRY: * - * The fundamental type corresponding to #gchar. - * The type designated by G_TYPE_CHAR is unconditionally an 8-bit signed integer. - * This may or may not be the same type a the C type "gchar". + * An indefinite type that is a supertype of every dictionary entry + * type. */ /** - * g_param_spec_pool_remove: - * @pool: a #GParamSpecPool - * @pspec: the #GParamSpec to remove + * G_VARIANT_TYPE_DOUBLE: * - * Removes a #GParamSpec from the pool. + * The type of a double precision IEEE754 floating point number. + * These guys go up to about 1.80e308 (plus and minus) but miss out on + * some numbers in between. In any case, that's far greater than the + * estimated number of fundamental particles in the observable + * universe. */ /** - * g_param_spec_unref: (skip) - * @pspec: a valid #GParamSpec + * G_VARIANT_TYPE_HANDLE: * - * Decrements the reference count of a @pspec. + * The type of a 32bit signed integer value, that by convention, is used + * as an index into an array of file descriptors that are sent alongside + * a DBus message. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. */ /** - * G_VALUE_HOLDS_GTYPE: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. + * G_VARIANT_TYPE_INT16: * - * Since: 2.12 - * Returns: %TRUE on success. + * The type of an integer value that can range from -32768 to 32767. */ /** - * G_OBJECT_CLASS: - * @class: a valid #GObjectClass + * G_VARIANT_TYPE_INT32: * - * Casts a derived #GObjectClass structure into a #GObjectClass structure. + * The type of an integer value that can range from -2147483648 to + * 2147483647. */ /** - * G_VARIANT_TYPE_INT32: + * G_VARIANT_TYPE_INT64: * - * The type of an integer value that can range from -2147483648 to - * 2147483647. + * The type of an integer value that can range from + * -9223372036854775808 to 9223372036854775807. */ /** - * GBindingFlags: - * @G_BINDING_DEFAULT: The default binding; if the source property changes, the target property is updated with its value. - * @G_BINDING_BIDIRECTIONAL: Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. - * @G_BINDING_SYNC_CREATE: 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. - * @G_BINDING_INVERT_BOOLEAN: 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 boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full(). - * - * Flags to be passed to g_object_bind_property() or - * g_object_bind_property_full(). - * This enumeration can be extended at later date. + * G_VARIANT_TYPE_MAYBE: * - * Since: 2.26 + * An indefinite type that is a supertype of every maybe type. */ /** - * g_type_plugin_complete_type_info: - * @plugin: a #GTypePlugin - * @g_type: the #GType whose info is completed - * @info: the #GTypeInfo struct to fill in - * @value_table: the #GTypeValueTable to fill in + * G_VARIANT_TYPE_OBJECT_PATH: * - * Calls the @complete_type_info function from the #GTypePluginClass of @plugin. - * There should be no need to use this function outside of the GObject - * type system itself. + * The type of a DBus object reference. These are strings of a + * specific format used to identify objects at a given destination on + * the bus. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. If you are, then the DBus specification contains a + * precise description of valid object paths. */ /** - * G_TYPE_PARAM_PARAM: + * G_VARIANT_TYPE_SIGNATURE: * - * The #GType of #GParamSpecParam. + * The type of a DBus type signature. These are strings of a specific + * format used as type signatures for DBus methods and messages. + * If you are not interacting with DBus, then there is no reason to make + * use of this type. If you are, then the DBus specification contains a + * precise description of valid signature strings. */ /** - * g_value_set_flags: - * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS - * @v_flags: flags value to be set + * G_VARIANT_TYPE_STRING: * - * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. + * The type of a string. "" is a string. %NULL is not a string. */ /** - * G_IS_PARAM_SPEC_VARIANT: - * @pspec: a #GParamSpec - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. + * G_VARIANT_TYPE_STRING_ARRAY: * - * Returns: %TRUE on success - * Since: 2.26 + * The type of an array of strings. */ /** - * g_value_array_get_nth: - * @value_array: #GValueArray to get a value from - * @index_: index of the value of interest - * - * Return a pointer to the value at @index_ containd in @value_array. + * G_VARIANT_TYPE_TUPLE: * - * Returns: (transfer none): pointer to a value at @index_ in @value_array + * An indefinite type that is a supertype of every tuple type, + * regardless of the number of items in the tuple. */ /** - * GParamSpecFlags: - * @parent_instance: private #GParamSpec portion - * @flags_class: the #GFlagsClass for the flags - * @default_value: default value for the property specified + * G_VARIANT_TYPE_UINT16: * - * A #GParamSpec derived structure that contains the meta data for flags - * properties. + * The type of an integer value that can range from 0 to 65535. + * There were about this many people living in Toronto in the 1870s. */ /** - * g_object_run_dispose: - * @object: a #GObject + * G_VARIANT_TYPE_UINT32: * - * Releases all references to other objects. This can be used to break - * reference cycles. - * This functions should only be called from object system implementations. + * The type of an integer value that can range from 0 to 4294967295. + * That's one number for everyone who was around in the late 1970s. */ /** - * G_VALUE_TYPE_NAME: - * @value: A #GValue structure. - * - * Gets the the type name of @value. + * G_VARIANT_TYPE_UINT64: * - * Returns: the type name. + * The type of an integer value that can range from 0 to + * 18446744073709551616. That's a really big number, but a Rubik's + * cube can have a bit more than twice as many possible positions. */ /** - * g_type_parent: - * @type: The derived type. - * - * Return the direct parent type of the passed in type. If the passed - * in type has no parent, i.e. is a fundamental type, 0 is returned. + * G_VARIANT_TYPE_UNIT: * - * Returns: The parent type. + * The empty tuple type. Has only one instance. Known also as "triv" + * or "void". */ /** - * SECTION:gparamspe: - * @short_description: Metadata for parameter specifications - * @see_also: g_object_class_install_property(), g_object_set(), g_object_get(), g_object_set_property(), g_object_get_property(), g_value_register_transform_func() - * @title: GParamSpec + * G_VARIANT_TYPE_VARIANT: * - * #GParamSpec is an object structure that encapsulates the metadata - * required to specify parameters, such as e.g. #GObject properties. - * <para id="canonical-parameter-name"> - * 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. - * The result of this replacement is called the canonical name of the - * parameter. - * </para> + * The type of a box that contains any other value (including another + * variant). */ /** - * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS: + * SECTION:enumerations_flag: + * @short_description: Enumeration and flags types + * @title: Enumeration and Flag Types g_param_spec_flags() * - * Generic delimiters characters as defined in RFC 3986. Includes ":/?#[]@". + * The GLib type system provides fundamental types for enumeration and + * flags types. (Flags types are like enumerations, but allow their + * values to be combined by bitwise or). A registered enumeration or + * flags type associates a name and a nickname with each allowed + * value, and the methods g_enum_get_value_by_name(), + * g_enum_get_value_by_nick(), g_flags_get_value_by_name() and + * g_flags_get_value_by_nick() can look up values by their name or + * nickname. When an enumeration or flags type is registered with the + * GLib type system, it can be used as value type for object + * properties, using g_param_spec_enum() or g_param_spec_flags(). + * GObject ships with a utility called <link + * linkend="glib-mkenums">glib-mkenums</link> that can construct + * suitable type registration functions from C enumeration + * definitions. */ @@ -6047,1361 +4798,1670 @@ /** - * GClassInitFunc: - * @g_class: The #GTypeClass structure to initialize. - * @class_data: The @class_data member supplied via the #GTypeInfo structure. + * SECTION:gboxe: + * @short_description: A mechanism to wrap opaque C structures registered by the type system + * @see_also: #GParamSpecBoxed, g_param_spec_boxed() + * @title: Boxed Types * - * A callback function used by the type system to initialize the class - * of a specific type. This function should initialize all static class - * members. - * The initialization process of a class involves: + * 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 and + * free them, 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 + * based libraries. + */ + + +/** + * SECTION:gclosur: + * @short_description: Functions as first-class objects + * @title: Closures + * + * 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 reponsibility of the marshaller to + * convert the arguments for the invocation from #GValue<!-- -->s into + * a suitable form, perform the callback on the converted arguments, + * and transform the return value back into a #GValue. + * In the case of C programs, a closure usually just holds a pointer + * to a function and maybe a data argument, and the marshaller + * converts between #GValue<!-- --> and native C types. The GObject + * library provides the #GCClosure type for this purpose. Bindings for + * other languages need marshallers which convert between #GValue<!-- + * -->s and suitable representations in the runtime of the language in + * order to use functions written in that languages as callbacks. + * Within GObject, closures play an important role in the + * implementation of signals. When a signal is registered, the + * marshaller for any closure which is connected to this + * signal. GObject provides a number of C marshallers for this + * purpose, see the g_cclosure_marshal_*() functions. Additional C + * marshallers can be generated with the <link + * linkend="glib-genmarshal">glib-genmarshal</link> utility. Closures + * can be explicitly connected to signals with + * g_signal_connect_closure(), but it usually more convenient to let + * GObject create a closure automatically by using one of the + * g_signal_connect_*() functions which take a callback function/user + * data pair. + * Using closures has a number of important advantages over a simple + * callback function/data pointer combination: * <itemizedlist> * <listitem><para> - * 1 - Copying common members from the parent class over to the - * derived class structure. - * </para></listitem> - * <listitem><para> - * 2 - Zero initialization of the remaining members not copied - * over from the parent class. + * Closures allow the callee to get the types of the callback parameters, + * which means that language bindings don't have to write individual glue + * for each callback type. * </para></listitem> * <listitem><para> - * 3 - Invocation of the GBaseInitFunc() initializers of all parent - * types and the class' type. + * The reference counting of #GClosure makes it easy to handle reentrancy + * right; if a callback is removed while it is being invoked, the closure + * and its parameters won't be freed until the invocation finishes. * </para></listitem> * <listitem><para> - * 4 - Invocation of the class' GClassInitFunc() initializer. + * g_closure_invalidate() and invalidation notifiers allow callbacks to be + * automatically removed when the objects they point to go away. * </para></listitem> * </itemizedlist> - * Since derived classes are partially initialized through a memory copy - * of the parent class, the general rule is that GBaseInitFunc() and - * GBaseFinalizeFunc() should take care of necessary reinitialization - * and release of those class members that were introduced by the type - * that specified these GBaseInitFunc()/GBaseFinalizeFunc(). - * GClassInitFunc() should only care about initializing static - * class members, while dynamic class members (such as allocated strings - * or reference counted resources) are better handled by a GBaseInitFunc() - * for this type, so proper initialization of the dynamic class members - * is performed for class initialization of derived types as well. - * An example may help to correspond the intend of the different class - * initializers: + */ + + +/** + * SECTION:generic_value: + * @short_description: A polymorphic type that can hold values of any other type + * @see_also: The fundamental types which all support #GValue operations and thus can be used as a type initializer for g_value_init() are defined by a separate interface. See the <link linkend="gobject-Standard-Parameter-and-Value-Types">Standard Values API</link> for details. + * @title: Generic values + * + * 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 a 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. + * 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 + * provided by this interface. + * The code in the example program below demonstrates #GValue's + * features. * |[ - * typedef struct { - * GObjectClass parent_class; - * gint static_integer; - * gchar *dynamic_string; - * } TypeAClass; - * static void - * type_a_base_class_init (TypeAClass *class) - * { - * class->dynamic_string = g_strdup ("some string"); - * } - * static void - * type_a_base_class_finalize (TypeAClass *class) - * { - * g_free (class->dynamic_string); - * } - * static void - * type_a_class_init (TypeAClass *class) - * { - * class->static_integer = 42; - * } - * typedef struct { - * TypeAClass parent_class; - * gfloat static_float; - * GString *dynamic_gstring; - * } TypeBClass; - * static void - * type_b_base_class_init (TypeBClass *class) - * { - * class->dynamic_gstring = g_string_new ("some other string"); - * } + * #include <glib-object.h> * static void - * type_b_base_class_finalize (TypeBClass *class) + * int2string (const GValue *src_value, + * GValue *dest_value) * { - * g_string_free (class->dynamic_gstring); + * if (g_value_get_int (src_value) == 42) + * g_value_set_static_string (dest_value, "An important number"); + * else + * g_value_set_static_string (dest_value, "What's that?"); * } - * static void - * type_b_class_init (TypeBClass *class) + * int + * main (int argc, + * char *argv[]) * { - * class->static_float = 3.14159265358979323846; + * /* GValues must start zero-filled */ + * GValue a = {0}; + * GValue b = {0}; + * const gchar *message; + * g_type_init (); + * /* The GValue starts empty */ + * g_assert (!G_VALUE_HOLDS_STRING (&a)); + * /* Put a string in it */ + * g_value_init (&a, G_TYPE_STRING); + * g_assert (G_VALUE_HOLDS_STRING (&a)); + * g_value_set_static_string (&a, "Hello, world!"); + * g_printf ("%s\n", g_value_get_string (&a)); + * /* Reset it to its pristine state */ + * g_value_unset (&a); + * /* It can then be reused for another type */ + * g_value_init (&a, G_TYPE_INT); + * g_value_set_int (&a, 42); + * /* Attempt to transform it into a GValue of type STRING */ + * g_value_init (&b, G_TYPE_STRING); + * /* An INT is transformable to a STRING */ + * g_assert (g_value_type_transformable (G_TYPE_INT, G_TYPE_STRING)); + * g_value_transform (&a, &b); + * g_printf ("%s\n", g_value_get_string (&b)); + * /* Attempt to transform it again using a custom transform function */ + * g_value_register_transform_func (G_TYPE_INT, G_TYPE_STRING, int2string); + * g_value_transform (&a, &b); + * g_printf ("%s\n", g_value_get_string (&b)); + * return 0; * } * ]| - * Initialization of TypeBClass will first cause initialization of - * TypeAClass (derived classes reference their parent classes, see - * g_type_class_ref() on this). - * Initialization of TypeAClass roughly involves zero-initializing its fields, - * then calling its GBaseInitFunc() type_a_base_class_init() to allocate - * its dynamic members (dynamic_string), and finally calling its GClassInitFunc() - * type_a_class_init() to initialize its static members (static_integer). - * The first step in the initialization process of TypeBClass is then - * a plain memory copy of the contents of TypeAClass into TypeBClass and - * zero-initialization of the remaining fields in TypeBClass. - * The dynamic members of TypeAClass within TypeBClass now need - * reinitialization which is performed by calling type_a_base_class_init() - * with an argument of TypeBClass. - * After that, the GBaseInitFunc() of TypeBClass, type_b_base_class_init() - * is called to allocate the dynamic members of TypeBClass (dynamic_gstring), - * and finally the GClassInitFunc() of TypeBClass, type_b_class_init(), - * is called to complete the initialization process with the static members - * (static_float). - * Corresponding finalization counter parts to the GBaseInitFunc() functions - * have to be provided to release allocated resources at class finalization - * time. */ /** - * GRegexMatchFlags: - * @G_REGEX_MATCH_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. - * @G_REGEX_MATCH_NOTBOL: Specifies that first character of the string is not the beginning of a line, so the circumflex metacharacter should not match before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes circumflex never to match. This option affects only the behaviour of the circumflex metacharacter, it does not affect "\A". - * @G_REGEX_MATCH_NOTEOL: Specifies that the end of the subject string is not the end of a line, so the dollar metacharacter should not match it nor (except in multiline mode) a newline immediately before it. Setting this without #G_REGEX_MULTILINE (at compile time) causes dollar never to match. This option affects only the behaviour of the dollar metacharacter, it does not affect "\Z" or "\z". - * @G_REGEX_MATCH_NOTEMPTY: An empty string is not considered to be a valid match if this option is set. If there are alternatives in the pattern, they are tried. If all the alternatives match the empty string, the entire match fails. For example, if the pattern "a?b?" is applied to a string not beginning with "a" or "b", it matches the empty string at the start of the string. With this flag set, this match is not valid, so GRegex searches further into the string for occurrences of "a" or "b". - * @G_REGEX_MATCH_PARTIAL: Turns on the partial matching feature, for more documentation on partial matching see g_match_info_is_partial_match(). - * @G_REGEX_MATCH_NEWLINE_CR: Overrides the newline definition set when creating a new #GRegex, setting the '\r' character as line terminator. - * @G_REGEX_MATCH_NEWLINE_LF: Overrides the newline definition set when creating a new #GRegex, setting the '\n' character as line terminator. - * @G_REGEX_MATCH_NEWLINE_CRLF: Overrides the newline definition set when creating a new #GRegex, setting the '\r\n' characters as line terminator. - * @G_REGEX_MATCH_NEWLINE_ANY: Overrides the newline definition set when creating a new #GRegex, any newline character or character sequence is recognized. - * - * Flags specifying match-time options. + * SECTION:gparamspe: + * @short_description: Metadata for parameter specifications + * @see_also: g_object_class_install_property(), g_object_set(), g_object_get(), g_object_set_property(), g_object_get_property(), g_value_register_transform_func() + * @title: GParamSpec * - * Since: 2.14 + * #GParamSpec is an object structure that encapsulates the metadata + * required to specify parameters, such as e.g. #GObject properties. + * <para id="canonical-parameter-name"> + * 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. + * The result of this replacement is called the canonical name of the + * parameter. + * </para> */ /** - * g_cclosure_new_object_swap: (skip) - * @callback_func: the function to invoke - * @object: a #GObject pointer to pass to @callback_func + * SECTION:gtyp: + * @short_description: The GLib Runtime type identification and management system * - * A variant of g_cclosure_new_swap() which uses @object as @user_data - * and calls g_object_watch_closure() on @object and the created - * closure. This function is useful when you have a callback closely - * associated with a #GObject, and want the callback to no longer run - * after the object is is freed. + * 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. Before using any GType + * or GObject functions, g_type_init() must be called to initialize the + * type system. + * For type creation and registration purposes, all types fall into one of + * unloaded at run-time as dynamic types may be. Static types are created + * with g_type_register_static() that gets type specific information passed + * in via a #GTypeInfo structure. + * Dynamic types are created with g_type_register_dynamic() which takes a + * #GTypePlugin structure instead. The remaining type information (the + * #GTypeInfo structure) is retrieved during runtime through #GTypePlugin + * and the g_type_plugin_*() API. + * These registration functions are usually called only once from a + * function whose only purpose is to return the type identifier for a + * specific class. Once the type (or class or interface) is registered, + * it may be instantiated, inherited, or implemented depending on exactly + * what sort of type it is. + * There is also a third registration function for registering fundamental + * types called g_type_register_fundamental() which requires both a #GTypeInfo + * structure and a #GTypeFundamentalInfo structure but it is seldom used + * since most fundamental types are predefined rather than user-defined. + * A final word about type names. + * Such an identifier needs to be at least three characters long. There is no + * upper length limit. The first character needs to be a letter (a-z or A-Z) + * or an underscore '_'. Subsequent characters can be letters, numbers or + * any of '-_+'. * - * Returns: a new #GCClosure + * Two categories: static or dynamic. Static types are never loaded or */ /** - * g_param_spec_flags: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @flags_type: a #GType derived from %G_TYPE_FLAGS - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS - * property. - * See g_param_spec_internal() for details on property names. + * SECTION:gtypemodul: + * @short_description: Type loading modules <varlistentry> <term>#GTypePlugin</term> <listitem><para>The abstract type loader interface.</para></listitem> </varlistentry> <varlistentry> <term>#GModule</term> <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> </varlistentry> </variablelist> + * @title: GTypeModule * - * Returns: a newly created parameter specification + * #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. 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 can not happen in 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 + * zero, the module is loaded. The use count is maintained internally by + * the type system, but also can be explicitly controlled by + * g_type_module_use() and g_type_module_unuse(). Typically, when loading + * a module for the first type, g_type_module_use() will be used to load + * it so that it can initialize its types. At some later point, when the + * module no longer needs to be loaded except for the type + * implementations it contains, g_type_module_unuse() is called. + * #GTypeModule does not actually provide any implementation of module + * loading and unloading. To create a particular module type you must + * derive from #GTypeModule and implement the load and unload functions + * in #GTypeModuleClass. */ /** - * G_TYPE_IS_CLASSED: - * @type: A #GType value. - * - * Checks if @type is a classed type. + * SECTION:gtypeplugi: + * @short_description: An interface for dynamically loadable types + * @see_also: #GTypeModule and g_type_register_dynamic(). + * @title: GTypePlugin * - * Returns: %TRUE on success. + * 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: + * <orderedlist> + * <listitem><para> + * The type is initially introduced (usually upon loading the module + * the first time, or by your main application that knows what modules + * introduces what types), like this: + * |[ + * new_type_id = g_type_register_dynamic (parent_type_id, + * "TypeName", + * new_type_plugin, + * type_flags); + * ]| + * where <literal>new_type_plugin</literal> is an implementation of the + * #GTypePlugin interface. + * </para></listitem> + * <listitem><para> + * The type's implementation is referenced, e.g. through + * g_type_class_ref() or through g_type_create_instance() (this is + * being called by g_object_new()) or through one of the above done on + * a type derived from <literal>new_type_id</literal>. + * </para></listitem> + * <listitem><para> + * This causes the type system to load the type's implementation by calling + * g_type_plugin_use() and g_type_plugin_complete_type_info() on + * <literal>new_type_plugin</literal>. + * </para></listitem> + * <listitem><para> + * At some point the type's implementation isn't required anymore, e.g. after + * g_type_class_unref() or g_type_free_instance() (called when the reference + * count of an instance drops to zero). + * </para></listitem> + * <listitem><para> + * This causes the type system to throw away the information retrieved from + * g_type_plugin_complete_type_info() and then it calls + * g_type_plugin_unuse() on <literal>new_type_plugin</literal>. + * </para></listitem> + * <listitem><para> + * Things may repeat from the second step. + * </para></listitem> + * </orderedlist> + * So basically, you need to implement a #GTypePlugin type that + * carries a use_count, once use_count goes from zero to one, you need + * to load the implementation to successfully handle the upcoming + * g_type_plugin_complete_type_info() call. Later, maybe after + * succeeding use/unuse calls, once use_count drops to zero, you can + * unload the implementation again. The type system makes sure to call + * g_type_plugin_use() and g_type_plugin_complete_type_info() again + * when the type is needed again. + * #GTypeModule is an implementation of #GTypePlugin that already + * implements most of this except for the actual module loading and + * unloading. It even handles multiple registered types per module. */ /** - * GParamSpecTypeInfo: - * @instance_size: Size of the instance (object) structure. - * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. - * @instance_init: Location of the instance initialization function (optional). - * @value_type: The #GType of values conforming to this #GParamSpec - * @finalize: The instance finalization function (optional). - * @value_set_default: Resets a @value to the default value for @pspec (recommended, the default is g_value_reset()), see g_param_value_set_default(). - * @value_validate: Ensures that the contents of @value comply with the specifications set out by @pspec (optional), see g_param_value_set_validate(). - * @values_cmp: Compares @value1 with @value2 according to @pspec (recommended, the default is memcmp()), see g_param_values_cmp(). + * SECTION:object: + * @short_description: The base object type + * @see_also: #GParamSpecObject, g_param_spec_object() + * @title: The Base Object Type * - * 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 - * g_param_type_register_static(). + * GObject is the fundamental type providing the common attributes and + * methods for all object types in GTK+, Pango and other libraries + * based on GObject. The GObject class provides methods for object + * construction and destruction, property access methods, and signal + * support. Signals are described in detail in <xref + * linkend="gobject-Signals"/>. + * <para id="floating-ref"> + * #GInitiallyUnowned is derived from #GObject. The only difference between + * the two is that the initial reference of a #GInitiallyUnowned is flagged + * as a <firstterm>floating</firstterm> 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: + * |[ + * container = create_container(); + * container_add_child (container, create_child()); + * ]| + * If <function>container_add_child()</function> will g_object_ref_sink() the + * passed in child, no reference of the newly created child is leaked. + * Without floating references, <function>container_add_child()</function> + * can only g_object_ref() the new child, so to implement this code without + * reference leaks, it would have to be written as: + * |[ + * Child *child; + * container = create_container(); + * 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 to g_object_ref() and returns + * a new reference. + * Since floating references are useful almost exclusively for C convenience, + * language bindings that provide automated reference and memory ownership + * maintenance (such as smart pointers or garbage collection) therefore don't + * need to expose floating references in their API. + * </para> + * Some object implementations may need to save an objects floating state + * across certain code portions (an example is #GtkMenu), to achive this, the + * following sequence can be used: + * |[ + * // save floating state + * gboolean was_floating = g_object_is_floating (object); + * g_object_ref_sink (object); + * // protected code portion + * ...; + * // restore floating state + * if (was_floating) + * g_object_force_floating (object); + * g_obejct_unref (object); // release previously acquired reference + * ]| */ /** - * G_TYPE_IS_VALUE_ABSTRACT: - * @type: A #GType value. - * - * Checks if @type is an abstract value type. An abstract value type introduces - * a value table, but can't be used for g_value_init() and is normally used as - * an abstract base type for derived value types. + * SECTION:param_value_type: + * @short_description: Standard Parameter and Value Types + * @see_also: #GParamSpec, #GValue, g_object_class_install_property(). + * @title: Parameters and Values * - * Returns: %TRUE on success. + * #GValue provides an abstract container structure which can be + * copied, transformed and compared while holding a value of any + * (derived) type, which is registered as a #GType with a + * #GTypeValueTable in its #GTypeInfo structure. Parameter + * specifications for most value types can be created as #GParamSpec + * derived instances, to implement e.g. #GObject properties which + * 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. */ /** - * g_object_add_weak_pointer: (skip) - * @object: The object that should be weak referenced. - * @weak_pointer_location: (inout): The memory address of a pointer. + * SECTION:signal: + * @short_description: A means for customization of object behaviour and a general purpose notification mechanism + * @title: Signals * - * Adds a weak reference from weak_pointer to @object to indicate that - * the pointer located at @weak_pointer_location is only valid during - * the lifetime of @object. When the @object is finalized, + * The basic concept of the signal system is that of the + * <emphasis>emission</emphasis> of a signal. Signals are introduced + * per-type and are identified through strings. Signals introduced + * for a parent type are available in derived types as well, so + * basically they are a per-type facility that is inherited. A signal + * emission mainly involves invocation of a certain set of callbacks + * in precisely defined manner. There are two main categories of such + * callbacks, per-object + * <footnote><para>Although signals can deal with any kind of instantiatable + * type, i'm referring to those types as "object types" in the following, + * simply because that is the context most users will encounter signals in. + * </para></footnote> + * ones and user provided ones. + * The per-object callbacks are most often referred to as "object method + * handler" or "default (signal) handler", while user provided callbacks are + * usually just called "signal handler". + * The object method handler is provided at signal creation time (this most + * frequently happens at the end of an object class' creation), while user + * provided handlers are frequently connected and disconnected to/from a certain + * signal on certain object instances. + * A signal emission consists of five stages, unless prematurely stopped: + * <variablelist> + * <varlistentry><term></term><listitem><para> + * 1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE) + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * 5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals + * </para></listitem></varlistentry> + * </variablelist> + * The user-provided signal handlers are called in the order they were + * connected in. + * All handlers may prematurely stop a signal emission, and any number of + * handlers may be connected, disconnected, blocked or unblocked during + * a signal emission. + * There are certain criteria for skipping user handlers in stages 2 and 4 + * of a signal emission. + * First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted + * during callback invocation, to return from the "blocked" state, a + * handler has to get unblocked exactly the same amount of times + * it has been blocked before. + * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional + * "detail" argument passed in to g_signal_emit() has to match the detail + * argument of the signal handler currently subject to invocation. + * Specification of no detail argument for signal handlers (omission of the + * detail part of the signal specification upon connection) serves as a + * wildcard and matches any detail argument passed in to emission. */ /** - * G_TYPE_PARAM_OVERRIDE: - * - * The #GType of #GParamSpecOverride. + * SECTION:value_array: + * @short_description: A container structure to maintain an array of generic values + * @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array() + * @title: Value arrays * - * Since: 2.4 + * The prime purpose of a #GValueArray is for it to be used as an + * object property that holds an array of values. A #GValueArray wraps + * an array of #GValue elements in order for it to be used as a boxed + * type through %G_TYPE_VALUE_ARRAY. */ /** - * G_VALUE_HOLDS_VARIANT: - * @value: a valid #GValue structure - * - * Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. + * SECTION:value_collectio: + * @Short_description: Converting varargs to generic values + * @Title: Varargs Value Collection * - * Returns: %TRUE on success. - * Since: 2.26 + * The macros in this section provide the varargs parsing support needed + * in variadic GObject functions such as g_object_new() or g_object_set(). + * They currently support the collection of integral types, floating point + * types and pointers. */ /** - * g_param_spec_value_array: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL - * @flags: flags for the property specified + * g_alloca: + * @size: number of bytes to allocate. * - * Creates a new #GParamSpecValueArray instance specifying a - * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a - * %G_TYPE_BOXED type, as such, #GValue structures for this property - * can be accessed with g_value_set_boxed() and g_value_get_boxed(). - * See g_param_spec_internal() for details on property names. + * Allocates @size bytes on the stack; these bytes will be freed when the current + * stack frame is cleaned up. This macro essentially just wraps the alloca() + * function present on most UNIX variants. + * Thus it provides the same advantages and pitfalls as alloca(): + * <variablelist> + * <varlistentry><term></term><listitem><para> + * + alloca() is very fast, as on most systems it's implemented by just adjusting + * the stack pointer register. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * + It doesn't cause any memory fragmentation, within its scope, separate alloca() + * blocks just build up and are released together at function end. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - Allocation sizes have to fit into the current stack frame. For instance in a + * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, + * so be sparse with alloca() uses. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - Allocation failure due to insufficient stack space is not indicated with a %NULL + * return like e.g. with malloc(). Instead, most systems probably handle it the same + * way as out of stack space situations from infinite function recursion, i.e. + * with a segmentation fault. + * </para></listitem></varlistentry> + * <varlistentry><term></term><listitem><para> + * - 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 + * not upon exit of the enclosing function scope. + * </para></listitem></varlistentry> + * </variablelist> * - * Returns: a newly created parameter specification + * Returns: space for @size bytes, allocated on the stack */ /** - * GTypeClass: + * g_atomic_int_dec_and_test: + * @atomic: a pointer to an integer * - * An opaque structure used as the base of all classes. + * Atomically decrements the integer pointed to by @atomic by 1. + * after decrementing it + * + * Returns: %TRUE if the integer pointed to by @atomic is 0 + * Since: 2.4 */ /** - * GBindingTransformFunc: - * @binding: a #GBinding - * @source_value: the value of the source property - * @target_value: the value of the target property - * @user_data: data passed to the transform function + * g_atomic_int_inc: + * @atomic: a pointer to an integer. * - * A function to be called to transform the source property of @source - * from @source_value into the target property of @target - * using @target_value. - * otherwise + * Atomically increments the integer pointed to by @atomic by 1. * - * Returns: %TRUE if the transformation was successful, and %FALSE - * Since: 2.26 + * Since: 2.4 */ /** - * g_param_spec_variant: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @type: a #GVariantType - * @default_value: (allow-none): a #GVariant of type @type to use as the default value, or %NULL - * @flags: flags for the property specified + * g_binding_get_flags: + * @binding: a #GBinding * - * Creates a new #GParamSpecVariant instance specifying a #GVariant - * property. - * If @default_value is floating, it is consumed. - * See g_param_spec_internal() for details on property names. + * Retrieves the flags passed when constructing the #GBinding * - * Returns: the newly created #GParamSpec + * Returns: the #GBindingFlags used by the #GBinding * Since: 2.26 */ /** - * G_TYPE_GSTRING: + * g_binding_get_source: + * @binding: a #GBinding * - * The #GType for #GString. + * Retrieves the #GObject instance used as the source of the binding + * + * Returns: (transfer none): the source #GObject + * Since: 2.26 */ /** - * G_PARAM_SPEC_OVERRIDE: - * @pspec: a #GParamSpec + * g_binding_get_source_property: + * @binding: a #GBinding * - * Casts a #GParamSpec into a #GParamSpecOverride. + * Retrieves the name of the property of #GBinding:source used as the source + * of the binding * - * Since: 2.4 + * Returns: the name of the source property + * Since: 2.26 */ /** - * G_VALUE_HOLDS_UINT64: - * @value: a valid #GValue structure + * g_binding_get_target: + * @binding: a #GBinding * - * Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. + * Retrieves the #GObject instance used as the target of the binding * - * Returns: %TRUE on success. + * Returns: (transfer none): the target #GObject + * Since: 2.26 */ /** - * g_param_spec_get_blurb: - * @pspec: a valid #GParamSpec + * g_binding_get_target_property: + * @binding: a #GBinding * - * Get the short description of a #GParamSpec. + * Retrieves the name of the property of #GBinding:target used as the target + * of the binding * - * Returns: the short description of @pspec. + * Returns: the name of the target property + * Since: 2.26 */ /** - * g_value_get_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT + * g_boxed_copy: + * @boxed_type: The type of @src_boxed. + * @src_boxed: The boxed structure to be copied. * - * Get the contents of a variant #GValue. + * Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. * - * Returns: variant contents of @value - * Since: 2.26 + * Returns: The newly created copy of the boxed structure. */ /** - * g_signal_emit_by_name: - * @instance: the instance the signal is being emitted on. - * @detailed_signal: a string of the form "signal-name::detail". - * @...: 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. + * g_boxed_free: + * @boxed_type: The type of @boxed. + * @boxed: The boxed structure to be freed. * - * Emits a signal. - * Note that g_signal_emit_by_name() resets the return value to the default - * if no handlers are connected, in contrast to g_signal_emitv(). + * Free the boxed structure @boxed which is of type @boxed_type. */ /** - * GTypeModuleClass: - * @parent_class: the parent class - * @load: loads the module and registers one or more types using g_type_module_register_type(). - * @unload: unloads the module + * g_boxed_type_register_static: + * @name: Name of the new boxed type. + * @boxed_copy: Boxed structure copy function. + * @boxed_free: Boxed structure free function. * - * In order to implement dynamic loading of types based on #GTypeModule, - * the @load and @unload functions in #GTypeModuleClass must be implemented. + * 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. + * + * Returns: New %G_TYPE_BOXED derived type id for @name. */ /** - * g_param_spec_unichar: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT - * property. #GValue structures for this property can be accessed with - * g_value_set_uint() and g_value_get_uint(). - * See g_param_spec_internal() for details on property names. + * g_cclosure_marshal_BOOLEAN__FLAGS: + * @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 * - * Returns: a newly created parameter specification + * A marshaller for a #GCClosure with a callback of type + * <literal>gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter + * denotes a flags type. */ /** - * G_IS_PARAM_SPEC: - * @pspec: a #GParamSpec + * g_cclosure_marshal_BOOLEAN__OBJECT_BOXED_BOXED: + * @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 * - * Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM - * or derived. + * A marshaller for a #GCClosure with a callback of type + * <literal>gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)</literal>. + * + * Since: 2.26 */ /** - * g_object_get: (skip) - * @object: a #GObject - * @first_property_name: name of the first property to get - * @...: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL + * g_cclosure_marshal_BOOL__FLAGS: * - * Gets properties of an object. - * In general, a copy is made of the property contents and the caller - * is responsible for freeing the memory in the appropriate manner for - * the type, for instance by calling g_free() or g_object_unref(). - * <example> - * <title>Using g_object_get(<!-- -->)</title> - * An example of using g_object_get() to get the contents - * of three properties - one of type #G_TYPE_INT, - * one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT: - * <programlisting> - * gint intval; - * gchar *strval; - * GObject *objval; - * g_object_get (my_object, - * "int-property", &intval, - * "str-property", &strval, - * "obj-property", &objval, - * NULL); - * // Do something with intval, strval, objval - * g_free (strval); - * g_object_unref (objval); - * </programlisting> - * </example> + * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). */ /** - * g_value_array_free: - * @value_array: #GValueArray to free + * g_cclosure_marshal_STRING__OBJECT_POINTER: + * @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 * - * Free a #GValueArray including its contents. + * A marshaller for a #GCClosure with a callback of type + * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>. */ /** - * G_VALUE_TYPE: - * @value: A #GValue structure. - * - * Get the type identifier of @value. + * g_cclosure_marshal_VOID__BOOLEAN: + * @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 * - * Returns: the #GType. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>. */ /** - * g_object_bind_property_full: - * @source: the source #GObject - * @source_property: the property on @source to bind - * @target: the target #GObject - * @target_property: the property on @target to bind - * @flags: flags to pass to #GBinding - * @transform_to: (scope notified) (allow-none): the transformation function from the @source to the @target, or %NULL to use the default - * @transform_from: (scope notified) (allow-none): the transformation function from the @target to the @source, or %NULL to use the default - * @user_data: custom data to be passed to the transformation functions, or %NULL - * @notify: function to be called when disposing the binding, to free the resources used by the transformation functions - * - * Complete version of g_object_bind_property(). - * Creates a binding between @source_property on @source and @target_property - * on @target, allowing you to set the transformation functions to be used by - * the binding. - * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: - * if @target_property on @target changes then the @source_property on @source - * will be updated as well. The @transform_from function is only used in case - * of bidirectional bindings, otherwise it will be ignored - * The binding will automatically be removed when either the @source or the - * #GBinding instance. - * A #GObject can have multiple bindings. - * <note>The same @user_data parameter will be used for both @transform_to - * and @transform_from transformation functions; the @notify function will - * be called once, when the binding is removed. If you need different data - * for each transformation function, please use - * g_object_bind_property_with_closures() instead.</note> - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * g_cclosure_marshal_VOID__BOXED: + * @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 * - * Returns: (transfer none): the #GBinding instance representing the - * Since: 2.26 + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)</literal>. */ /** - * GInterfaceFinalizeFunc: - * @g_iface: The interface structure to finalize. - * @iface_data: The @interface_data supplied via the #GInterfaceInfo structure. + * g_cclosure_marshal_VOID__CHAR: + * @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 * - * 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. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gchar arg1, gpointer user_data)</literal>. */ /** - * GParamSpecUChar: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_cclosure_marshal_VOID__DOUBLE: + * @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 * - * A #GParamSpec derived structure that contains the meta data for unsigned character properties. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)</literal>. */ /** - * g_object_get_data: - * @object: #GObject containing the associations - * @key: name of the key for that association - * - * Gets a named field from the objects table of associations (see g_object_set_data()). + * g_cclosure_marshal_VOID__ENUM: + * @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 * - * Returns: (transfer none): the data if found, or %NULL if no such data exists. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes an enumeration type.. */ /** - * g_object_get_property: - * @object: a #GObject - * @property_name: the name of the property to get - * @value: return location for the property value + * g_cclosure_marshal_VOID__FLAGS: + * @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 * - * Gets a property of an object. @value must have been initialized to the - * expected type of the property (or a type to which the expected type can be - * transformed) using g_value_init(). - * In general, a copy is made of the property contents and the caller is - * responsible for freeing the memory by calling g_value_unset(). - * Note that g_object_get_property() is really intended for language - * bindings, g_object_get() is much more convenient for C programming. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type. */ /** - * G_IS_OBJECT: - * @object: Instance to check for being a %G_TYPE_OBJECT. + * g_cclosure_marshal_VOID__FLOAT: + * @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 * - * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)</literal>. */ /** - * GFlagsValue: - * @value: the flags value - * @value_name: the name of the value - * @value_nick: the nickname of the value + * g_cclosure_marshal_VOID__INT: + * @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 * - * A structure which contains a single flags value, its name, and its - * nickname. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal>. */ /** - * g_value_set_uchar: - * @value: a valid #GValue of type %G_TYPE_UCHAR - * @v_uchar: unsigned character value to be set + * g_cclosure_marshal_VOID__LONG: + * @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 * - * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>. */ /** - * G_TYPE_PARAM_UINT: + * g_cclosure_marshal_VOID__OBJECT: + * @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 * - * The #GType of #GParamSpecUInt. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)</literal>. */ /** - * G_PARAM_SPEC_VALUE_ARRAY: - * @pspec: a valid #GParamSpec instance + * g_cclosure_marshal_VOID__PARAM: + * @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 * - * Cast a #GParamSpec instance into a #GParamSpecValueArray. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)</literal>. */ /** - * GInstanceInitFunc: - * @instance: The instance to initialize. - * @g_class: The class of the type the instance is created for. + * g_cclosure_marshal_VOID__POINTER: + * @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 * - * 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. - * Initialization of a derived instance involves calling all its parent - * types instance initializers, so the class member of the instance - * is altered during its initialization to always point to the class that - * belongs to the type the current initializer was introduced for. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)</literal>. */ /** - * G_VARIANT_TYPE_MAYBE: + * g_cclosure_marshal_VOID__STRING: + * @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 * - * An indefinite type that is a supertype of every maybe type. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)</literal>. */ /** - * G_CONVERT_ERROR: + * g_cclosure_marshal_VOID__UCHAR: + * @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 * - * Error domain for character set conversions. Errors in this domain will - * be from the #GConvertError enumeration. See #GError for information on - * error domains. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, guchar arg1, gpointer user_data)</literal>. */ /** - * g_object_bind_property_with_closures: - * @source: the source #GObject - * @source_property: the property on @source to bind - * @target: the target #GObject - * @target_property: the property on @target to bind - * @flags: flags to pass to #GBinding - * @transform_to: a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default - * @transform_from: a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default - * - * Creates a binding between @source_property on @source and @target_property - * on @target, allowing you to set the transformation functions to be used by - * the binding. - * This function is the language bindings friendly version of - * g_object_bind_property_full(), using #GClosure<!-- -->s instead of - * function pointers. - * binding between the two #GObject instances. The binding is released - * whenever the #GBinding reference count reaches zero. + * 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 * - * Rename to: g_object_bind_property_full - * Returns: (transfer none): the #GBinding instance representing the - * Since: 2.26 + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>. */ /** - * g_object_new_valist: (skip) - * @object_type: the type id of the #GObject subtype to instantiate - * @first_property_name: the name of the first property - * @var_args: the value of the first property, followed optionally by more name/value pairs, followed by %NULL - * - * Creates a new instance of a #GObject subtype and sets its properties. - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. + * g_cclosure_marshal_VOID__UINT_POINTER: + * @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 * - * Returns: a new instance of @object_type + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>. */ /** - * g_value_unset: - * @value: An initialized #GValue structure. + * g_cclosure_marshal_VOID__ULONG: + * @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 * - * Clears the current value in @value and "unsets" the type, - * this releases all resources associated with this GValue. - * An unset value is the same as an uninitialized (zero-filled) - * #GValue structure. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>. */ /** - * GDateTime: + * 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 * - * <structname>GDateTime</structname> is an opaque structure whose members - * cannot be accessed directly. + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)</literal>. * * Since: 2.26 */ /** - * G_TIME_SPAN_SECOND: - * - * Evaluates to a time span of one second. + * g_cclosure_marshal_VOID__VOID: + * @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 * - * Since: 2.26 + * A marshaller for a #GCClosure with a callback of type + * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>. */ /** - * g_param_spec_get_nick: - * @pspec: a valid #GParamSpec + * g_cclosure_new: (skip) + * @callback_func: the function to invoke + * @user_data: user data to pass to @callback_func + * @destroy_data: destroy notify to be called when @user_data is no longer used * - * Get the nickname of a #GParamSpec. + * Creates a new closure which invokes @callback_func with @user_data as + * the last parameter. * - * Returns: the nickname of @pspec. + * Returns: a new #GCClosure */ /** - * G_TYPE_UINT: + * g_cclosure_new_object: (skip) + * @callback_func: the function to invoke + * @object: a #GObject pointer to pass to @callback_func * - * The fundamental type corresponding to #guint. + * A variant of g_cclosure_new() which uses @object as @user_data and + * calls g_object_watch_closure() on @object and the created + * closure. This function is useful when you have a callback closely + * associated with a #GObject, and want the callback to no longer run + * after the object is is freed. + * + * Returns: a new #GCClosure */ /** - * g_object_force_floating: - * @object: a #GObject + * g_cclosure_new_object_swap: (skip) + * @callback_func: the function to invoke + * @object: a #GObject pointer to pass to @callback_func * - * This function is intended for #GObject implementations to re-enforce a - * <link linkend="floating-ref">floating</link> object reference. - * Doing this is seldomly required, all - * #GInitiallyUnowned<!-- -->s are created with a floating reference which - * usually just needs to be sunken by calling g_object_ref_sink(). + * A variant of g_cclosure_new_swap() which uses @object as @user_data + * and calls g_object_watch_closure() on @object and the created + * closure. This function is useful when you have a callback closely + * associated with a #GObject, and want the callback to no longer run + * after the object is is freed. * - * Since: 2.10 + * Returns: a new #GCClosure */ /** - * g_alloca: - * @size: number of bytes to allocate. + * g_cclosure_new_swap: (skip) + * @callback_func: the function to invoke + * @user_data: user data to pass to @callback_func + * @destroy_data: destroy notify to be called when @user_data is no longer used * - * Allocates @size bytes on the stack; these bytes will be freed when the current - * stack frame is cleaned up. This macro essentially just wraps the alloca() - * function present on most UNIX variants. - * Thus it provides the same advantages and pitfalls as alloca(): - * <variablelist> - * <varlistentry><term></term><listitem><para> - * + alloca() is very fast, as on most systems it's implemented by just adjusting - * the stack pointer register. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * + It doesn't cause any memory fragmentation, within its scope, separate alloca() - * blocks just build up and are released together at function end. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - Allocation sizes have to fit into the current stack frame. For instance in a - * threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes, - * so be sparse with alloca() uses. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - Allocation failure due to insufficient stack space is not indicated with a %NULL - * return like e.g. with malloc(). Instead, most systems probably handle it the same - * way as out of stack space situations from infinite function recursion, i.e. - * with a segmentation fault. - * </para></listitem></varlistentry> - * <varlistentry><term></term><listitem><para> - * - 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 - * not upon exit of the enclosing function scope. - * </para></listitem></varlistentry> - * </variablelist> + * Creates a new closure which invokes @callback_func with @user_data as + * the first parameter. * - * Returns: space for @size bytes, allocated on the stack + * Returns: (transfer full): a new #GCClosure */ /** - * g_pointer_type_register_static: - * @name: the name of the new pointer type. + * g_clear_object: (skip) + * @object_ptr: a pointer to a #GObject reference * - * Creates a new %G_TYPE_POINTER derived type id for a new - * pointer type with name @name. + * Clears a reference to a #GObject. + * If the reference is %NULL then this function does nothing. + * Otherwise, the reference count of the object is decreased and the + * pointer is set to %NULL. + * This function is threadsafe and modifies the pointer atomically, + * using memory barriers where needed. + * A macro is also included that allows this function to be used without + * pointer casts. * - * Returns: a new %G_TYPE_POINTER derived type id for @name. + * Since: 2.28 */ /** - * G_DEFINE_TYPE_WITH_CODE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type in lowercase, with words separated by '_'. - * @T_P: The #GType of the parent type. - * @_C_: 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(). - * See G_DEFINE_TYPE_EXTENDED() for an example. + * g_closure_add_finalize_notifier: (skip) + * @closure: a #GClosure + * @notify_data: data to pass to @notify_func + * @notify_func: the callback function to register * - * Since: 2.4 + * 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. */ /** - * g_cclosure_marshal_STRING__OBJECT_POINTER: - * @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 + * g_closure_add_invalidate_notifier: (skip) + * @closure: a #GClosure + * @notify_data: data to pass to @notify_func + * @notify_func: the callback function to register * - * A marshaller for a #GCClosure with a callback of type - * <literal>gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)</literal>. + * Registers an invalidation notifier which will be called when the + * notifiers are invoked before finalization notifiers, in an + * unspecified order. */ /** - * g_value_set_param_take_ownership: (skip) - * @value: a valid #GValue of type %G_TYPE_PARAM - * @param: the #GParamSpec to be set - * - * This is an internal function introduced mainly for C marshallers. + * g_closure_add_marshal_guards: (skip) + * @closure: a #GClosure + * @pre_marshal_data: data to pass to @pre_marshal_notify + * @pre_marshal_notify: a function to call before the closure callback + * @post_marshal_data: data to pass to @post_marshal_notify + * @post_marshal_notify: a function to call after the closure callback * - * Deprecated: 2.4: Use g_value_take_param() instead. + * 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. */ /** - * G_PRIORITY_DEFAULT: + * g_closure_invalidate: + * @closure: GClosure to invalidate * - * Use this for default priority event sources. - * In GLib this priority is used when adding timeout functions - * with g_timeout_add(). In GDK this priority is used for events - * from the X server. + * 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 + * 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 + * access the closure after calling g_closure_invalidate(), make sure + * that you've previously called g_closure_ref(). + * Note that g_closure_invalidate() will also be called when the + * reference count of a closure drops to zero (unless it has already + * been invalidated before). */ /** - * g_type_class_unref_uncached: (skip) - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. + * g_closure_invoke: + * @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: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure + * @invocation_hint: a context-dependent invocation hint * - * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc - * implementations. It unreferences a class without consulting the chain - * of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur - * otherwise. + * Invokes the closure, i.e. executes the callback represented by the @closure. */ /** - * g_param_spec_pool_new: - * @type_prefixing: Whether the pool will support type-prefixed property names. + * g_closure_new_object: + * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> + * @object: a #GObject pointer to store in the @data field of the newly allocated #GClosure * - * Creates a new #GParamSpecPool. - * If @type_prefixing is %TRUE, lookups in the newly created pool will - * allow to specify the owner as a colon-separated prefix of the - * property name, like "GtkContainer:border-width". This feature is - * deprecated, so you should always set @type_prefixing to %FALSE. + * A variant of g_closure_new_simple() which stores @object in the + * when implementing new types of closures. * - * Returns: (transfer none): a newly allocated #GParamSpecPool. + * Returns: (transfer full): a newly allocated #GClosure */ /** - * g_cclosure_marshal_BOOLEAN__OBJECT_BOXED_BOXED: - * @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 + * g_closure_new_simple: + * @sizeof_closure: the size of the structure to allocate, must be at least <literal>sizeof (GClosure)</literal> + * @data: data to store in the @data field of the newly allocated #GClosure * - * A marshaller for a #GCClosure with a callback of type - * <literal>gboolean (*callback) (gpointer instance, GBoxed *arg1, GBoxed *arg2, gpointer user_data)</literal>. + * 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. + * |[ + * typedef struct _MyClosure MyClosure; + * struct _MyClosure + * { + * GClosure closure; + * // extra data goes here + * }; + * static void + * my_closure_finalize (gpointer notify_data, + * GClosure *closure) + * { + * MyClosure *my_closure = (MyClosure *)closure; + * // free extra data here + * } + * MyClosure *my_closure_new (gpointer data) + * { + * GClosure *closure; + * MyClosure *my_closure; + * closure = g_closure_new_simple (sizeof (MyClosure), data); + * my_closure = (MyClosure *) closure; + * // initialize extra data here + * g_closure_add_finalize_notifier (closure, notify_data, + * my_closure_finalize); + * return my_closure; + * } + * ]| * - * Since: 2.26 + * Returns: (transfer full): a newly allocated #GClosure */ /** - * G_TYPE_IS_PARAM: - * @type: a #GType ID + * g_closure_ref: + * @closure: #GClosure to increment the reference count on * - * Checks whether @type "is a" %G_TYPE_PARAM. + * Increments the reference count on a closure to force it staying + * alive while the caller holds a pointer to it. + * + * Returns: (transfer none): The @closure passed in, for convenience */ /** - * g_flags_get_value_by_name: - * @flags_class: a #GFlagsClass - * @name: the name to look up - * - * Looks up a #GFlagsValue by name. - * flag with that name + * g_closure_remove_finalize_notifier: (skip) + * @closure: a #GClosure + * @notify_data: data which was passed to g_closure_add_finalize_notifier() when registering @notify_func + * @notify_func: the callback function to remove * - * Returns: the #GFlagsValue with name @name, or %NULL if there is no + * Removes a finalization notifier. + * Notice that notifiers are automatically removed after they are run. */ /** - * g_type_add_interface_dynamic: - * @instance_type: the #GType value of an instantiable type. - * @interface_type: the #GType value of an interface type. - * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. + * g_closure_remove_invalidate_notifier: (skip) + * @closure: a #GClosure + * @notify_data: data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func + * @notify_func: the callback function to remove * - * Adds the dynamic @interface_type to @instantiable_type. The information - * contained in the #GTypePlugin structure pointed to by @plugin - * is used to manage the relationship. + * Removes an invalidation notifier. + * Notice that notifiers are automatically removed after they are run. */ /** - * g_value_get_uint: - * @value: a valid #GValue of type %G_TYPE_UINT - * - * Get the contents of a %G_TYPE_UINT #GValue. + * g_closure_set_marshal: (skip) + * @closure: a #GClosure + * @marshal: a #GClosureMarshal function * - * Returns: unsigned integer contents of @value + * Sets the marshaller of @closure. The <literal>marshal_data</literal> + * 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_*() + * functions), what it provides is a callback function to use instead of */ /** - * G_TYPE_CHECK_CLASS_CAST: - * @g_class: Location of a #GTypeClass structure. - * @g_type: The type to be returned. - * @c_type: The corresponding C type of class structure of @g_type. + * g_closure_set_meta_marshal: (skip) + * @closure: a #GClosure + * @marshal_data: context-dependent data to pass to @meta_marshal + * @meta_marshal: a #GClosureMarshal function * - * Checks that @g_class is a class structure of the type identified by @g_type - * and issues a warning if this is not the case. Returns @g_class casted - * to a pointer to @c_type. - * This macro should only be used in type implementations. + * Sets the meta marshaller of @closure. A meta marshaller wraps + * fashion. The most common use of this facility is for C callbacks. + * The same marshallers (generated by <link + * linkend="glib-genmarshal">glib-genmarshal</link>) are used + * everywhere, but the way that we get the callback function + * differs. In most cases we want to use @closure->callback, but in + * other cases we want to use some different technique to retrieve the + * callback function. + * For example, class closures for signals (see + * g_signal_type_cclosure_new()) retrieve the callback function from a + * fixed offset in the class structure. The meta marshaller retrieves + * the right callback and passes it to the marshaller as the */ /** - * G_IS_ENUM_CLASS: - * @class: a #GEnumClass + * g_closure_sink: + * @closure: #GClosure to decrement the initial reference count on, if it's still being held * - * Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM - * or derived. + * Takes over the initial ownership of a closure. Each closure is + * initially created in a <firstterm>floating</firstterm> 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 existance of the floating state is to + * prevent cumbersome code sequences like: + * |[ + * closure = g_cclosure_new (cb_func, cb_data); + * g_source_set_closure (source, closure); + * g_closure_unref (closure); // XXX 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: + * |[ + * g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); + * ]| + * Generally, this function is used together with g_closure_ref(). Ane example + * of storing a closure for later notification looks like: + * |[ + * static GClosure *notify_closure = NULL; + * void + * foo_notify_set_closure (GClosure *closure) + * { + * if (notify_closure) + * g_closure_unref (notify_closure); + * notify_closure = closure; + * if (notify_closure) + * { + * g_closure_ref (notify_closure); + * g_closure_sink (notify_closure); + * } + * } + * ]| + * Because g_closure_sink() may decrement the reference count of a closure + * (if it hasn't been called on @closure yet) just like g_closure_unref(), + * g_closure_ref() should be called prior to this function. */ /** - * g_node_next_sibling: - * @node: a #GNode - * - * Gets the next sibling of a #GNode. - * or %NULL + * g_closure_unref: + * @closure: #GClosure to decrement the reference count on * - * Returns: the next sibling of @node, or %NULL if @node is the last node + * 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. */ /** - * g_object_notify_by_pspec: - * @object: a #GObject - * @pspec: the #GParamSpec of a property installed on the class of @object. + * g_enum_complete_type_info: + * @g_enum_type: the type identifier of the type being completed + * @info: the #GTypeInfo struct to be filled in + * @const_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. * - * Emits a "notify" signal for the property specified by @pspec on @object. - * This function omits the property name lookup, hence it is faster than - * g_object_notify(). - * One way to avoid using g_object_notify() from within the - * class that registered the properties, and using g_object_notify_by_pspec() - * instead, is to store the GParamSpec used with - * g_object_class_install_property() inside a static array, e.g.: + * This function is meant to be called from the complete_type_info() + * function of a #GTypePlugin implementation, as in the following + * example: * |[ - * enum - * { - * PROP_0, - * PROP_FOO, - * PROP_LAST - * }; - * static GParamSpec *properties[PROP_LAST]; * static void - * my_object_class_init (MyObjectClass *klass) + * my_enum_complete_type_info (GTypePlugin *plugin, + * GType g_type, + * GTypeInfo *info, + * GTypeValueTable *value_table) * { - * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", - * 0, 100, - * 50, - * G_PARAM_READWRITE); - * g_object_class_install_property (gobject_class, - * PROP_FOO, - * properties[PROP_FOO]); + * static const GEnumValue values[] = { + * { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, + * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, + * { 0, NULL, NULL } + * }; + * g_enum_complete_type_info (type, info, values); * } * ]| - * and then notify a change on the "foo" property with: - * |[ - * g_object_notify_by_pspec (self, properties[PROP_FOO]); - * ]| + */ + + +/** + * g_enum_get_value: + * @enum_class: a #GEnumClass + * @value: the value to look up * - * Since: 2.26 + * Returns the #GEnumValue for a value. + * member of the enumeration + * + * Returns: the #GEnumValue for @value, or %NULL if @value is not a */ /** - * g_cclosure_new_object: (skip) - * @callback_func: the function to invoke - * @object: a #GObject pointer to pass to @callback_func + * g_enum_get_value_by_name: + * @enum_class: a #GEnumClass + * @name: the name to look up * - * A variant of g_cclosure_new() which uses @object as @user_data and - * calls g_object_watch_closure() on @object and the created - * closure. This function is useful when you have a callback closely - * associated with a #GObject, and want the callback to no longer run - * after the object is is freed. + * Looks up a #GEnumValue by name. + * enumeration doesn't have a member with that name * - * Returns: a new #GCClosure + * Returns: the #GEnumValue with name @name, or %NULL if the */ /** - * g_node_append: - * @parent: the #GNode to place the new #GNode under - * @node: the #GNode to insert + * g_enum_get_value_by_nick: + * @enum_class: a #GEnumClass + * @nick: the nickname to look up * - * Inserts a #GNode as the last child of the given parent. + * Looks up a #GEnumValue by nickname. + * enumeration doesn't have a member with that nickname * - * Returns: the inserted #GNode + * Returns: the #GEnumValue with nickname @nick, or %NULL if the */ /** - * g_object_remove_toggle_ref: (skip) - * @object: a #GObject - * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. - * @data: data to pass to @notify + * g_enum_register_static: + * @name: A nul-terminated string used as the name of the new type. + * @const_static_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. * - * Removes a reference added with g_object_add_toggle_ref(). The - * reference count of the object is decreased by one. + * Registers a new static enumeration type with the name @name. + * It is normally more convenient to let <link + * linkend="glib-mkenums">glib-mkenums</link> generate a + * my_enum_get_type() function from a usual C enumeration definition + * than to write one yourself using g_enum_register_static(). * - * Since: 2.8 + * Returns: The new type identifier. */ /** - * g_object_thaw_notify: - * @object: a #GObject + * g_flags_complete_type_info: + * @g_flags_type: the type identifier of the type being completed + * @info: the #GTypeInfo struct to be filled in + * @const_values: An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. * - * Reverts the effect of a previous call to - * g_object_freeze_notify(). The freeze count is decreased on @object - * and when it reaches zero, all queued "notify" signals are emitted. - * It is an error to call this function when the freeze count is zero. + * This function is meant to be called from the complete_type_info() + * function of a #GTypePlugin implementation, see the example for + * g_enum_complete_type_info() above. */ /** - * g_value_set_uint64: - * @value: a valid #GValue of type %G_TYPE_UINT64 - * @v_uint64: unsigned 64bit integer value to be set + * g_flags_get_first_value: + * @flags_class: a #GFlagsClass + * @value: the value * - * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. + * Returns the first #GFlagsValue which is set in @value. + * none is set + * + * Returns: the first #GFlagsValue which is set in @value, or %NULL if */ /** - * GTimeSpan: + * g_flags_get_value_by_name: + * @flags_class: a #GFlagsClass + * @name: the name to look up * - * A value representing an interval of time, in microseconds. + * Looks up a #GFlagsValue by name. + * flag with that name * - * Since: 2.26 + * Returns: the #GFlagsValue with name @name, or %NULL if there is no */ /** - * GParamSpec: - * @g_type_instance: private #GTypeInstance portion - * @name: name of this parameter - * @flags: #GParamFlags flags for this parameter - * @value_type: the #GValue type for this parameter - * @owner_type: #GType type that uses (introduces) this parameter + * g_flags_get_value_by_nick: + * @flags_class: a #GFlagsClass + * @nick: the nickname to look up * - * All other fields of the <structname>GParamSpec</structname> struct are private and - * should not be used directly. + * Looks up a #GFlagsValue by nickname. + * no flag with that nickname + * + * Returns: the #GFlagsValue with nickname @nick, or %NULL if there is */ /** - * G_TYPE_IS_OBJECT: - * @type: Type id to check + * g_flags_register_static: + * @name: A nul-terminated string used as the name of the new type. + * @const_static_values: An array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. GObject keeps a reference to the data, so it cannot be stack-allocated. * - * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. + * Registers a new static flags type with the name @name. + * It is normally more convenient to let <link + * linkend="glib-mkenums">glib-mkenums</link> generate a + * my_flags_get_type() function from a usual C enumeration definition + * than to write one yourself using g_flags_register_static(). * - * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT. + * Returns: The new type identifier. */ /** - * g_signal_stop_emission: - * @instance: the object whose signal handlers you wish to stop. - * @signal_id: the signal identifier, as returned by g_signal_lookup(). - * @detail: the detail which the signal was emitted with. + * g_hash_table_freeze: + * @hash_table: a #GHashTable * - * Stops a signal's current emission. - * This will prevent the default method from running, if the signal was - * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" - * flag). - * Prints a warning if used on a signal which isn't being emitted. + * This function is deprecated and will be removed in the next major + * release of GLib. It does nothing. */ /** - * g_cclosure_marshal_VOID__UINT_POINTER: - * @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 + * g_hash_table_thaw: + * @hash_table: a #GHashTable * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)</literal>. + * This function is deprecated and will be removed in the next major + * release of GLib. It does nothing. */ /** - * G_VALUE_HOLDS_FLOAT: - * @value: a valid #GValue structure + * g_main_destroy: + * @loop: a #GMainLoop * - * Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. + * Frees the memory allocated for the #GMainLoop. * - * Returns: %TRUE on success. + * Deprecated: 2.2: Use g_main_loop_unref() instead */ /** - * g_type_class_unref: - * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. + * g_main_is_running: + * @loop: a #GMainLoop * - * Decrements the reference count of the class structure being passed in. - * Once the last reference count of a class has been released, classes - * may be finalized by the type system, so further dereferencing of a - * class pointer after g_type_class_unref() are invalid. + * Checks if the main loop is running. + * + * Returns: %TRUE if the main loop is running + * Deprecated: 2.2: Use g_main_loop_is_running() instead */ /** - * g_value_set_int: - * @value: a valid #GValue of type %G_TYPE_INT - * @v_int: integer value to be set + * g_main_iteration: + * @may_block: set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. If set to %FALSE it will return immediately if no event source is ready to be processed. * - * Set the contents of a %G_TYPE_INT #GValue to @v_int. + * Runs a single iteration for the default #GMainContext. + * + * Returns: %TRUE if more events are pending. + * Deprecated: 2.2: Use g_main_context_iteration() instead. */ /** - * g_param_spec_long: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * g_main_new: + * @is_running: set to %TRUE to indicate that the loop is running. This is not very important since calling g_main_run() will set this to %TRUE anyway. * - * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. - * See g_param_spec_internal() for details on property names. + * Creates a new #GMainLoop for th default main context. * - * Returns: a newly created parameter specification + * Returns: a new #GMainLoop + * Deprecated: 2.2: Use g_main_loop_new() instead */ /** - * g_value_dup_string: - * @value: a valid #GValue of type %G_TYPE_STRING + * g_main_pending: * - * Get a copy the contents of a %G_TYPE_STRING #GValue. + * Checks if any events are pending for the default #GMainContext + * (i.e. ready to be processed). * - * Returns: a newly allocated copy of the string content of @value + * Returns: %TRUE if any events are pending. + * Deprected: 2.2: Use g_main_context_pending() instead. */ /** - * G_TYPE_RESERVED_BSE_LAST: + * g_main_quit: + * @loop: a #GMainLoop * - * Last fundamental type number reserved for BSE. + * Stops the #GMainLoop. + * If g_main_run() was called to run the #GMainLoop, it will now return. + * + * Deprecated: 2.2: Use g_main_loop_quit() instead */ /** - * g_value_set_object_take_ownership: (skip) - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: object value to be set + * g_main_run: + * @loop: a #GMainLoop * - * This is an internal function introduced mainly for C marshallers. + * Runs a main loop until it stops running. * - * Deprecated: 2.4: Use g_value_take_object() instead. + * Deprecated: 2.2: Use g_main_loop_run() instead */ /** - * g_value_set_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: boxed value to be set + * g_main_set_poll_func: + * @func: the function to call to poll all file descriptors * - * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. + * Sets the function to use for the handle polling of file descriptors + * for the default main context. + * + * Deprecated: 2.2: Use g_main_context_set_poll_func() again */ /** - * SECTION:gclosur: - * @short_description: Functions as first-class objects - * @title: Closures + * g_new: + * @struct_type: the type of the elements to allocate + * @n_structs: the number of elements to allocate * - * 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 reponsibility of the marshaller to - * convert the arguments for the invocation from #GValue<!-- -->s into - * a suitable form, perform the callback on the converted arguments, - * and transform the return value back into a #GValue. - * In the case of C programs, a closure usually just holds a pointer - * to a function and maybe a data argument, and the marshaller - * converts between #GValue<!-- --> and native C types. The GObject - * library provides the #GCClosure type for this purpose. Bindings for - * other languages need marshallers which convert between #GValue<!-- - * -->s and suitable representations in the runtime of the language in - * order to use functions written in that languages as callbacks. - * Within GObject, closures play an important role in the - * implementation of signals. When a signal is registered, the - * marshaller for any closure which is connected to this - * signal. GObject provides a number of C marshallers for this - * purpose, see the g_cclosure_marshal_*() functions. Additional C - * marshallers can be generated with the <link - * linkend="glib-genmarshal">glib-genmarshal</link> utility. Closures - * can be explicitly connected to signals with - * g_signal_connect_closure(), but it usually more convenient to let - * GObject create a closure automatically by using one of the - * g_signal_connect_*() functions which take a callback function/user - * data pair. - * Using closures has a number of important advantages over a simple - * callback function/data pointer combination: - * <itemizedlist> - * <listitem><para> - * Closures allow the callee to get the types of the callback parameters, - * which means that language bindings don't have to write individual glue - * for each callback type. - * </para></listitem> - * <listitem><para> - * The reference counting of #GClosure makes it easy to handle reentrancy - * right; if a callback is removed while it is being invoked, the closure - * and its parameters won't be freed until the invocation finishes. - * </para></listitem> - * <listitem><para> - * g_closure_invalidate() and invalidation notifiers allow callbacks to be - * automatically removed when the objects they point to go away. - * </para></listitem> - * </itemizedlist> + * Allocates @n_structs elements of type @struct_type. + * The returned pointer is cast to a pointer to the given type. + * If @n_structs is 0 it returns %NULL. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * Since the returned pointer is already casted to the right type, + * it is normally unnecessary to cast it explicitly, and doing + * so might hide memory allocation errors. + * + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * GParamSpecInt: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_new0: + * @struct_type: the type of the elements to allocate. + * @n_structs: the number of elements to allocate. * - * A #GParamSpec derived structure that contains the meta data for integer properties. + * Allocates @n_structs elements of type @struct_type, initialized to 0's. + * The returned pointer is cast to a pointer to the given type. + * If @n_structs is 0 it returns %NULL. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * Since the returned pointer is already casted to the right type, + * it is normally unnecessary to cast it explicitly, and doing + * so might hide memory allocation errors. + * + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. */ /** - * G_VARIANT_TYPE_DICT_ENTRY: + * g_newa: + * @struct_type: Type of memory chunks to be allocated + * @n_structs: Number of chunks to be allocated * - * An indefinite type that is a supertype of every dictionary entry - * type. + * Wraps g_alloca() in a more typesafe manner. + * + * Returns: Pointer to stack space for @n_structs chunks of type @struct_type */ /** - * g_type_add_interface_static: - * @instance_type: #GType value of an instantiable type. - * @interface_type: #GType value of an interface type. - * @info: The #GInterfaceInfo structure for this (@instance_type, @interface_type) combination. + * g_node_append: + * @parent: the #GNode to place the new #GNode under + * @node: the #GNode to insert * - * Adds the static @interface_type to @instantiable_type. The information - * contained in the #GTypeInterfaceInfo structure pointed to by @info - * is used to manage the relationship. + * Inserts a #GNode as the last child of the given parent. + * + * Returns: the inserted #GNode */ /** - * G_SIGNAL_FLAGS_MASK: + * g_node_append_data: + * @parent: the #GNode to place the new #GNode under + * @data: the data for the new #GNode * - * A mask for all #GSignalFlags bits. + * Inserts a new #GNode as the last child of the given parent. + * + * Returns: the new #GNode */ /** - * g_signal_get_invocation_hint: - * @instance: the instance to query + * g_node_first_child: + * @node: a #GNode * - * Returns the invocation hint of the innermost signal emission of instance. + * Gets the first child of a #GNode. + * or has no children * - * Returns: the invocation hint of the innermost signal emission. + * Returns: the first child of @node, or %NULL if @node is %NULL */ /** - * g_type_get_plugin: - * @type: The #GType to retrieve the plugin for. + * g_node_insert_data: + * @parent: the #GNode to place the new #GNode under + * @position: the position to place the new #GNode at. If position is -1, the new #GNode is inserted as the last child of @parent + * @data: the data for the new #GNode * - * Returns the #GTypePlugin structure for @type or - * %NULL if @type does not have a #GTypePlugin structure. - * dynamic type, %NULL otherwise. + * Inserts a new #GNode at the given position. * - * Returns: (transfer none): The corresponding plugin if @type is a + * Returns: the new #GNode */ /** - * g_signal_parse_name: - * @detailed_signal: a string of the form "signal-name::detail". - * @itype: The interface/instance type that introduced "signal-name". - * @signal_id_p: Location to store the signal id. - * @detail_p: Location to store the detail quark. - * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. + * g_node_insert_data_before: + * @parent: the #GNode to place the new #GNode under + * @sibling: the sibling #GNode to place the new #GNode before + * @data: the data for the new #GNode * - * Internal function to parse a signal name into its @signal_id - * and @detail quark. + * Inserts a new #GNode before the given sibling. * - * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. + * Returns: the new #GNode */ /** - * G_IMPLEMENT_INTERFACE_DYNAMIC: - * @TYPE_IFACE: The #GType of the interface to add - * @iface_init: The interface init function + * g_node_next_sibling: + * @node: a #GNode * - * 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. - * Note that this macro can only be used together with the - * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable - * names from that macro. + * Gets the next sibling of a #GNode. + * or %NULL * - * Since: 2.24 + * Returns: the next sibling of @node, or %NULL if @node is the last node */ /** - * g_param_spec_int: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * g_node_prepend_data: + * @parent: the #GNode to place the new #GNode under + * @data: the data for the new #GNode * - * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. - * See g_param_spec_internal() for details on property names. + * Inserts a new #GNode as the first child of the given parent. * - * Returns: a newly created parameter specification + * Returns: the new #GNode */ /** - * g_closure_invoke: - * @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: (array length=n_param_values): an array of #GValue<!-- -->s holding the arguments on which to invoke the callback of @closure - * @invocation_hint: a context-dependent invocation hint + * g_node_prev_sibling: + * @node: a #GNode * - * Invokes the closure, i.e. executes the callback represented by the @closure. + * Gets the previous sibling of a #GNode. + * node or %NULL + * + * Returns: the previous sibling of @node, or %NULL if @node is the first */ /** - * g_cclosure_marshal_VOID__ULONG: - * @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 + * g_object_add_toggle_ref: (skip) + * @object: a #GObject + * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. + * @data: data to pass to @notify * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gulong arg1, gpointer user_data)</literal>. + * Increases the reference count of the object by one and sets a + * callback to be called when all other references to the object are + * dropped, or when this is already the last reference to the object + * and another reference is established. + * This functionality is intended for binding @object to a proxy + * object managed by another memory manager. This is done with two + * g_object_add_toggle_ref() and a reverse reference to the proxy + * object which is either a strong reference or weak reference. + * The setup is that when there are no other references to @object, + * only a weak reference is held in the reverse direction from @object + * to the proxy object, but when there are other references held to + * when the reference from @object to the proxy object should be + * <firstterm>toggled</firstterm> from strong to weak (@is_last_ref + * true) or weak to strong (@is_last_ref false). + * Since a (normal) reference must be held to the object before + * calling g_object_toggle_ref(), the initial state of the reverse + * link is always strong. + * Multiple toggle references may be added to the same gobject, + * however if there are multiple toggle references to an object, none + * of them will ever be notified until all but one are removed. For + * this reason, you should only ever use a toggle reference if there + * is important state in the proxy object. + * + * Paired references: the strong reference added by + * Since: 2.8 */ /** - * G_DEFINE_BOXED_TYPE_WITH_CODE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @copy_func: the #GBoxedCopyFunc for the new type - * @free_func: the #GBoxedFreeFunc for the new type - * @_C_: Custom code that gets inserted in the *_get_type() function. - * - * 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 - * g_value_register_transform_func(). + * g_object_add_weak_pointer: (skip) + * @object: The object that should be weak referenced. + * @weak_pointer_location: (inout): The memory address of a pointer. * - * Since: 2.26 + * Adds a weak reference from weak_pointer to @object to indicate that + * the pointer located at @weak_pointer_location is only valid during + * the lifetime of @object. When the @object is finalized, */ @@ -7437,42 +6497,185 @@ /** - * SECTION:param_value_type: - * @short_description: Standard Parameter and Value Types - * @see_also: #GParamSpec, #GValue, g_object_class_install_property(). - * @title: Parameters and Values + * g_object_bind_property_full: + * @source: the source #GObject + * @source_property: the property on @source to bind + * @target: the target #GObject + * @target_property: the property on @target to bind + * @flags: flags to pass to #GBinding + * @transform_to: (scope notified) (allow-none): the transformation function from the @source to the @target, or %NULL to use the default + * @transform_from: (scope notified) (allow-none): the transformation function from the @target to the @source, or %NULL to use the default + * @user_data: custom data to be passed to the transformation functions, or %NULL + * @notify: function to be called when disposing the binding, to free the resources used by the transformation functions * - * #GValue provides an abstract container structure which can be - * copied, transformed and compared while holding a value of any - * (derived) type, which is registered as a #GType with a - * #GTypeValueTable in its #GTypeInfo structure. Parameter - * specifications for most value types can be created as #GParamSpec - * derived instances, to implement e.g. #GObject properties which - * 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. + * Complete version of g_object_bind_property(). + * Creates a binding between @source_property on @source and @target_property + * on @target, allowing you to set the transformation functions to be used by + * the binding. + * If @flags contains %G_BINDING_BIDIRECTIONAL then the binding will be mutual: + * if @target_property on @target changes then the @source_property on @source + * will be updated as well. The @transform_from function is only used in case + * of bidirectional bindings, otherwise it will be ignored + * The binding will automatically be removed when either the @source or the + * #GBinding instance. + * A #GObject can have multiple bindings. + * <note>The same @user_data parameter will be used for both @transform_to + * and @transform_from transformation functions; the @notify function will + * be called once, when the binding is removed. If you need different data + * for each transformation function, please use + * g_object_bind_property_with_closures() instead.</note> + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. + * + * Returns: (transfer none): the #GBinding instance representing the + * Since: 2.26 */ /** - * g_binding_get_source: - * @binding: a #GBinding + * g_object_bind_property_with_closures: + * @source: the source #GObject + * @source_property: the property on @source to bind + * @target: the target #GObject + * @target_property: the property on @target to bind + * @flags: flags to pass to #GBinding + * @transform_to: a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default + * @transform_from: a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default * - * Retrieves the #GObject instance used as the source of the binding + * Creates a binding between @source_property on @source and @target_property + * on @target, allowing you to set the transformation functions to be used by + * the binding. + * This function is the language bindings friendly version of + * g_object_bind_property_full(), using #GClosure<!-- -->s instead of + * function pointers. + * binding between the two #GObject instances. The binding is released + * whenever the #GBinding reference count reaches zero. * - * Returns: (transfer none): the source #GObject + * Rename to: g_object_bind_property_full + * Returns: (transfer none): the #GBinding instance representing the * Since: 2.26 */ /** - * G_IS_PARAM_SPEC_POINTER: - * @pspec: a valid #GParamSpec instance + * g_object_class_find_property: + * @oclass: a #GObjectClass + * @property_name: the name of the property to look up * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. + * Looks up the #GParamSpec for a property of a class. + * %NULL if the class doesn't have a property of that name * - * Returns: %TRUE on success. + * Returns: (transfer none): the #GParamSpec for the property, or + */ + + +/** + * g_object_class_install_properties: + * @oclass: a #GObjectClass + * @n_pspecs: the length of the #GParamSpec<!-- -->s array + * @pspecs: (array length=n_pspecs): the #GParamSpec<!-- -->s array defining the new properties + * + * Installs new properties from an array of #GParamSpec<!-- -->s. This is + * usually done in the class initializer. + * The property id of each property is the index of each #GParamSpec in + * the @pspecs array. + * The property id of 0 is treated specially by #GObject and it should not + * be used to store a #GParamSpec. + * This function should be used if you plan to use a static array of + * #GParamSpec<!-- -->s and g_object_notify_by_pspec(). For instance, this + * class initialization: + * |[ + * enum { + * PROP_0, PROP_FOO, PROP_BAR, N_PROPERTIES + * }; + * static GParamSpec *obj_properties[N_PROPERTIES] = { NULL, }; + * static void + * my_object_class_init (MyObjectClass *klass) + * { + * GObjectClass *gobject_class = G_OBJECT_CLASS (klass); + * obj_properties[PROP_FOO] = + * g_param_spec_int ("foo", "Foo", "Foo", + * -1, G_MAXINT, + * 0, + * G_PARAM_READWRITE); + * obj_properties[PROP_BAR] = + * g_param_spec_string ("bar", "Bar", "Bar", + * NULL, + * G_PARAM_READWRITE); + * gobject_class->set_property = my_object_set_property; + * gobject_class->get_property = my_object_get_property; + * g_object_class_install_properties (gobject_class, + * N_PROPERTIES, + * obj_properties); + * } + * ]| + * allows calling g_object_notify_by_pspec() to notify of property changes: + * |[ + * void + * my_object_set_foo (MyObject *self, gint foo) + * { + * if (self->foo != foo) + * { + * self->foo = foo; + * g_object_notify_by_pspec (G_OBJECT (self), obj_properties[PROP_FOO]); + * } + * } + * ]| + * + * Since: 2.26 + */ + + +/** + * g_object_class_install_property: + * @oclass: a #GObjectClass + * @property_id: the id for the new property + * @pspec: the #GParamSpec for the new property + * + * Installs a new property. This is usually done in the class initializer. + * Note that it is possible to redefine a property in a derived class, + * by installing a property with the same name. This can be useful at times, + * e.g. to change the range of allowed values or the default value. + */ + + +/** + * g_object_class_list_properties: + * @oclass: a #GObjectClass + * @n_properties: (out): return location for the length of the returned array + * + * Get an array of #GParamSpec* for all properties of a class. + * #GParamSpec* which should be freed after use + * + * Returns: (array length=n_properties) (transfer container): an array of + */ + + +/** + * g_object_class_override_property: + * @oclass: a #GObjectClass + * @property_id: the new property ID + * @name: the name of a property registered in a parent class or in an interface of this class. + * + * Registers @property_id as referring to a property with the + * name @name in a parent class or in an interface implemented + * by @oclass. This allows this class to <firstterm>override</firstterm> + * a property implementation in a parent class or to provide + * the implementation of a property from an interface. + * <note> + * Internally, overriding is implemented by creating a property of type + * #GParamSpecOverride; generally operations that query the properties of + * the object class, such as g_object_class_find_property() or + * g_object_class_list_properties() will return the overridden + * property. However, in one case, the @construct_properties argument of + * the @constructor virtual function, the #GParamSpecOverride is passed + * instead, so that the @param_id field of the #GParamSpec will be + * correct. For virtually all uses, this makes no difference. If you + * need to get the overridden property, you can call + * g_param_spec_get_redirect_target(). + * </note> + * + * Since: 2.4 */ @@ -7558,906 +6761,1322 @@ /** - * g_cclosure_marshal_VOID__FLAGS: - * @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 + * g_object_disconnect: (skip) + * @object: a #GObject + * @signal_spec: the spec for the first signal + * @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gint arg1, gpointer user_data)</literal> where the #gint parameter denotes a flags type. + * A convenience function to disconnect multiple signals at once. + * The signal specs expected by this function have the form + * "any_signal", which means to disconnect any signal with matching + * callback and data, or "any_signal::signal_name", which only + * disconnects the signal named "signal_name". */ /** - * GClosure: - * @in_marshal: Indicates whether the closure is currently being invoked with g_closure_invoke() - * @is_invalid: Indicates whether the closure has been invalidated by g_closure_invalidate() + * g_object_force_floating: + * @object: a #GObject * - * A #GClosure represents a callback supplied by the programmer. + * This function is intended for #GObject implementations to re-enforce a + * <link linkend="floating-ref">floating</link> object reference. + * Doing this is seldomly required, all + * #GInitiallyUnowned<!-- -->s are created with a floating reference which + * usually just needs to be sunken by calling g_object_ref_sink(). + * + * Since: 2.10 */ /** - * G_TIME_SPAN_MINUTE: + * g_object_freeze_notify: + * @object: a #GObject * - * Evaluates to a time span of one minute. + * Increases the freeze count on @object. If the freeze count is + * non-zero, the emission of "notify" signals on @object is + * stopped. The signals are queued until the freeze count is decreased + * to zero. + * This is necessary for accessors that modify multiple properties to prevent + * premature notification while the object is still being modified. + */ + + +/** + * g_object_get: (skip) + * @object: a #GObject + * @first_property_name: name of the first property to get + * @...: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL * - * Since: 2.26 + * Gets properties of an object. + * In general, a copy is made of the property contents and the caller + * is responsible for freeing the memory in the appropriate manner for + * the type, for instance by calling g_free() or g_object_unref(). + * <example> + * <title>Using g_object_get(<!-- -->)</title> + * An example of using g_object_get() to get the contents + * of three properties - one of type #G_TYPE_INT, + * one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT: + * <programlisting> + * gint intval; + * gchar *strval; + * GObject *objval; + * g_object_get (my_object, + * "int-property", &intval, + * "str-property", &strval, + * "obj-property", &objval, + * NULL); + * // Do something with intval, strval, objval + * g_free (strval); + * g_object_unref (objval); + * </programlisting> + * </example> */ /** - * G_DEFINE_BOXED_TYPE: - * @TypeName: The name of the new type, in Camel case. - * @type_name: The name of the new type, in lowercase, with words separated by '_'. - * @copy_func: the #GBoxedCopyFunc for the new type - * @free_func: the #GBoxedFreeFunc for the new type + * g_object_get_data: + * @object: #GObject containing the associations + * @key: name of the key for that association * - * A convenience macro for boxed type implementations, which defines a - * type_name_get_type() function registering the boxed type. + * Gets a named field from the objects table of associations (see g_object_set_data()). * - * Since: 2.26 + * Returns: (transfer none): the data if found, or %NULL if no such data exists. */ /** - * GSignalCMarshaller: + * g_object_get_property: + * @object: a #GObject + * @property_name: the name of the property to get + * @value: return location for the property value * - * 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. + * Gets a property of an object. @value must have been initialized to the + * expected type of the property (or a type to which the expected type can be + * transformed) using g_value_init(). + * In general, a copy is made of the property contents and the caller is + * responsible for freeing the memory by calling g_value_unset(). + * Note that g_object_get_property() is really intended for language + * bindings, g_object_get() is much more convenient for C programming. */ /** - * g_signal_handlers_disconnect_matched: - * @instance: The instance to remove handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * g_object_get_qdata: + * @object: The GObject to get a stored user data pointer from + * @quark: A #GQuark, naming the user data pointer * - * Disconnects all handlers on an instance that match a certain - * selection criteria. The criteria mask is passed as an OR-ed - * combination of #GSignalMatchType flags, and the criteria values are - * passed as arguments. Passing at least one of the - * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or - * %G_SIGNAL_MATCH_DATA match flags is required for successful - * matches. If no handlers were found, 0 is returned, the number of - * disconnected handlers otherwise. + * This function gets back user data pointers stored via + * g_object_set_qdata(). * - * Returns: The number of handlers that matched. + * Returns: (transfer none): The user data pointer set, or %NULL */ /** - * g_cclosure_marshal_VOID__LONG: - * @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 + * g_object_get_valist: (skip) + * @object: a #GObject + * @first_property_name: name of the first property to get + * @var_args: return location for the first property, followed optionally by more name/return location pairs, followed by %NULL * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, glong arg1, gpointer user_data)</literal>. + * Gets properties of an object. + * In general, a copy is made of the property contents and the caller + * is responsible for freeing the memory in the appropriate manner for + * the type, for instance by calling g_free() or g_object_unref(). + * See g_object_get(). */ /** - * G_TYPE_PARAM_UNICHAR: + * g_object_interface_find_property: + * @g_iface: any interface vtable for the interface, or the default vtable for the interface + * @property_name: name of a property to lookup. * - * The #GType of #GParamSpecUnichar. + * Find the #GParamSpec with the given name for an + * interface. Generally, the interface vtable passed in as @g_iface + * will be the default vtable from g_type_default_interface_ref(), or, + * if you know the interface has already been loaded, + * g_type_default_interface_peek(). + * interface with the name @property_name, or %NULL if no + * such property exists. + * + * Since: 2.4 + * Returns: (transfer none): the #GParamSpec for the property of the */ /** - * G_TYPE_VALUE_ARRAY: + * g_object_interface_install_property: + * @g_iface: any interface vtable for the interface, or the default vtable for the interface. + * @pspec: the #GParamSpec for the new property * - * The type ID of the "GValueArray" type which is a boxed type, - * used to pass around pointers to GValueArrays. + * Add a property to an interface; this is only useful for interfaces + * that are added to GObject-derived types. Adding a property to an + * interface forces all objects classes with that interface to have a + * compatible property. The compatible property could be a newly + * created #GParamSpec, but normally + * g_object_class_override_property() will be used so that the object + * class only needs to provide an implementation and inherits the + * property description, default value, bounds, and so forth from the + * interface property. + * This function is meant to be called from the interface's default + * vtable initialization function (the @class_init member of + * #GTypeInfo.) It must not be called after after @class_init has + * been called for any object types implementing this interface. + * + * Since: 2.4 */ /** - * G_IS_PARAM_SPEC_UINT: - * @pspec: a valid #GParamSpec instance + * g_object_interface_list_properties: + * @g_iface: any interface vtable for the interface, or the default vtable for the interface + * @n_properties_p: (out): location to store number of properties returned. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. + * Lists the properties of an interface.Generally, the interface + * vtable passed in as @g_iface will be the default vtable from + * g_type_default_interface_ref(), or, if you know the interface has + * already been loaded, g_type_default_interface_peek(). + * pointer to an array of pointers to #GParamSpec + * structures. The paramspecs are owned by GLib, but the + * array should be freed with g_free() when you are done with + * it. * - * Returns: %TRUE on success. + * Since: 2.4 + * Returns: (array length=n_properties_p) (transfer container): a */ /** - * GParameter: - * @name: the parameter name - * @value: the parameter value + * g_object_is_floating: + * @object: (type GObject.Object): a #GObject * - * The <structname>GParameter</structname> struct is an auxiliary structure used - * to hand parameter name/value pairs to g_object_newv(). + * Checks wether @object has a <link linkend="floating-ref">floating</link> + * reference. + * + * Since: 2.10 + * Returns: %TRUE if @object has a floating reference */ /** - * g_cclosure_new_swap: (skip) - * @callback_func: the function to invoke - * @user_data: user data to pass to @callback_func - * @destroy_data: destroy notify to be called when @user_data is no longer used + * g_object_new: (skip) + * @object_type: the type id of the #GObject subtype to instantiate + * @first_property_name: the name of the first property + * @...: the value of the first property, followed optionally by more name/value pairs, followed by %NULL * - * Creates a new closure which invokes @callback_func with @user_data as - * the first parameter. + * Creates a new instance of a #GObject subtype and sets its properties. + * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) + * which are not explicitly specified are set to their default values. * - * Returns: (transfer full): a new #GCClosure + * Returns: (transfer full): a new instance of @object_type */ /** - * g_type_fundamental: - * @type_id: valid type ID + * g_object_new_valist: (skip) + * @object_type: the type id of the #GObject subtype to instantiate + * @first_property_name: the name of the first property + * @var_args: the value of the first property, followed optionally by more name/value pairs, followed by %NULL * - * Internal function, used to extract the fundamental type ID portion. - * use G_TYPE_FUNDAMENTAL() instead. + * Creates a new instance of a #GObject subtype and sets its properties. + * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) + * which are not explicitly specified are set to their default values. * - * Returns: fundamental type ID + * Returns: a new instance of @object_type */ /** - * g_type_add_class_cache_func: (skip) - * @cache_data: data to be passed to @cache_func - * @cache_func: a #GTypeClassCacheFunc + * g_object_newv: + * @object_type: the type id of the #GObject subtype to instantiate + * @n_parameters: the length of the @parameters array + * @parameters: (array length=n_parameters): an array of #GParameter * - * Adds a #GTypeClassCacheFunc to be called before the reference count of a - * class goes from one to zero. This can be used to prevent premature class - * destruction. All installed #GTypeClassCacheFunc functions will be chained - * until one of them returns %TRUE. 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 classes are routed through the same #GTypeClassCacheFunc - * chain. + * Creates a new instance of a #GObject subtype and sets its properties. + * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) + * which are not explicitly specified are set to their default values. + * + * Rename to: g_object_new + * Returns: (type GObject.Object) (transfer full): a new instance of */ /** - * G_INITIALLY_UNOWNED_GET_CLASS: - * @object: a #GInitiallyUnowned instance. + * g_object_notify: + * @object: a #GObject + * @property_name: the name of a property installed on the class of @object. * - * Get the class structure associated to a #GInitiallyUnowned instance. + * Emits a "notify" signal for the property @property_name on @object. + * When possible, eg. when signaling a property change from within the class + * that registered the property, you should use g_object_notify_by_pspec() + * instead. + */ + + +/** + * g_object_notify_by_pspec: + * @object: a #GObject + * @pspec: the #GParamSpec of a property installed on the class of @object. * - * Returns: pointer to object class structure. + * Emits a "notify" signal for the property specified by @pspec on @object. + * This function omits the property name lookup, hence it is faster than + * g_object_notify(). + * One way to avoid using g_object_notify() from within the + * class that registered the properties, and using g_object_notify_by_pspec() + * instead, is to store the GParamSpec used with + * g_object_class_install_property() inside a static array, e.g.: + * |[ + * enum + * { + * PROP_0, + * PROP_FOO, + * PROP_LAST + * }; + * static GParamSpec *properties[PROP_LAST]; + * static void + * my_object_class_init (MyObjectClass *klass) + * { + * properties[PROP_FOO] = g_param_spec_int ("foo", "Foo", "The foo", + * 0, 100, + * 50, + * G_PARAM_READWRITE); + * g_object_class_install_property (gobject_class, + * PROP_FOO, + * properties[PROP_FOO]); + * } + * ]| + * and then notify a change on the "foo" property with: + * |[ + * g_object_notify_by_pspec (self, properties[PROP_FOO]); + * ]| + * + * Since: 2.26 */ /** - * g_object_interface_find_property: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface - * @property_name: name of a property to lookup. + * g_object_ref: + * @object: (type GObject.Object): a #GObject * - * Find the #GParamSpec with the given name for an - * interface. Generally, the interface vtable passed in as @g_iface - * will be the default vtable from g_type_default_interface_ref(), or, - * if you know the interface has already been loaded, - * g_type_default_interface_peek(). - * interface with the name @property_name, or %NULL if no - * such property exists. + * Increases the reference count of @object. * - * Since: 2.4 - * Returns: (transfer none): the #GParamSpec for the property of the + * Returns: (type GObject.Object) (transfer none): the same @object */ /** - * G_TYPE_PARAM_ENUM: + * g_object_ref_sink: + * @object: (type GObject.Object): a #GObject * - * The #GType of #GParamSpecEnum. + * Increase the reference count of @object, and possibly remove the + * <link linkend="floating-ref">floating</link> reference, if @object + * has a floating reference. + * In other words, if the object is floating, then this call "assumes + * ownership" of the floating reference, converting it to a normal + * reference by clearing the floating flag while leaving the reference + * count unchanged. If the object is not floating, then this call + * adds a new normal reference increasing the reference count by one. + * + * Since: 2.10 + * Returns: (type GObject.Object) (transfer none): @object */ /** - * G_IS_PARAM_SPEC_DOUBLE: - * @pspec: a valid #GParamSpec instance + * g_object_remove_toggle_ref: (skip) + * @object: a #GObject + * @notify: a function to call when this reference is the last reference to the object, or is no longer the last reference. + * @data: data to pass to @notify * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. + * Removes a reference added with g_object_add_toggle_ref(). The + * reference count of the object is decreased by one. * - * Returns: %TRUE on success. + * Since: 2.8 */ /** - * G_TYPE_CHECK_INSTANCE_TYPE: - * @instance: Location of a #GTypeInstance structure. - * @g_type: The type to be checked + * g_object_remove_weak_pointer: (skip) + * @object: The object that is weak referenced. + * @weak_pointer_location: (inout): The memory address of a pointer. * - * Checks if @instance is an instance of the type identified by @g_type. - * This macro should only be used in type implementations. + * Removes a weak reference from @object that was previously added + * using g_object_add_weak_pointer(). The @weak_pointer_location has + * to match the one used with g_object_add_weak_pointer(). + */ + + +/** + * g_object_run_dispose: + * @object: a #GObject * - * Returns: %TRUE on success. + * Releases all references to other objects. This can be used to break + * reference cycles. + * This functions should only be called from object system implementations. */ /** - * g_value_transform: - * @src_value: Source value. - * @dest_value: Target value. + * g_object_set: (skip) + * @object: a #GObject + * @first_property_name: name of the first property to set + * @...: value for the first property, followed optionally by more name/value pairs, followed by %NULL * - * Tries to cast the contents of @src_value into a type appropriate - * to store in @dest_value, e.g. to transform a %G_TYPE_INT value - * into a %G_TYPE_FLOAT value. Performing transformations between - * value types might incur precision lossage. Especially - * transformations into strings might reveal seemingly arbitrary - * results and shouldn't be relied upon for production code (such - * as rcfile value or object property serialization). - * Upon failing transformations, @dest_value is left untouched. + * Sets properties on an object. + */ + + +/** + * g_object_set_data: + * @object: #GObject containing the associations. + * @key: name of the key + * @data: data to associate with that key * - * Returns: Whether a transformation rule was found and could be applied. + * Each object carries around a table of associations from + * strings to pointers. This function lets you set an association. + * If the object already had an association with that name, + * the old association will be destroyed. */ /** - * G_TYPE_IO_CONDITION: + * g_object_set_data_full: (skip) + * @object: #GObject containing the associations + * @key: name of the key + * @data: data to associate with that key + * @destroy: function to call when the association is destroyed * - * The #GType for #GIOCondition. + * Like g_object_set_data() except it adds notification + * for when the association is destroyed, either by setting it + * to a different value or when the object is destroyed. + * Note that the @destroy callback is not called if @data is %NULL. */ /** - * g_atomic_int_inc: - * @atomic: a pointer to an integer. + * g_object_set_property: + * @object: a #GObject + * @property_name: the name of the property to set + * @value: the value * - * Atomically increments the integer pointed to by @atomic by 1. + * Sets a property on an object. + */ + + +/** + * g_object_set_qdata: (skip) + * @object: The GObject to set store a user data pointer + * @quark: A #GQuark, naming the user data pointer + * @data: An opaque user data pointer * - * Since: 2.4 + * This sets an opaque, named pointer on an object. + * The name is specified through a #GQuark (retrived e.g. via + * g_quark_from_static_string()), and the pointer + * can be gotten back from the @object with g_object_get_qdata() + * until the @object is finalized. + * Setting a previously set user data pointer, overrides (frees) + * the old pointer set, using #NULL as pointer essentially + * removes the data stored. */ /** - * G_TYPE_PARAM_ULONG: + * g_object_set_qdata_full: (skip) + * @object: The GObject to set store a user data pointer + * @quark: A #GQuark, naming the user data pointer + * @data: An opaque user data pointer + * @destroy: Function to invoke with @data as argument, when @data needs to be freed * - * The #GType of #GParamSpecULong. + * This function works like g_object_set_qdata(), but in addition, + * a void (*destroy) (gpointer) function may be specified which is + * called with @data as argument when the @object is finalized, or + * the data is being overwritten by a call to g_object_set_qdata() + * with the same @quark. */ /** - * GUserDirectory: - * @G_USER_DIRECTORY_DESKTOP: the user's Desktop directory - * @G_USER_DIRECTORY_DOCUMENTS: the user's Documents directory - * @G_USER_DIRECTORY_DOWNLOAD: the user's Downloads directory - * @G_USER_DIRECTORY_MUSIC: the user's Music directory - * @G_USER_DIRECTORY_PICTURES: the user's Pictures directory - * @G_USER_DIRECTORY_PUBLIC_SHARE: the user's shared directory - * @G_USER_DIRECTORY_TEMPLATES: the user's Templates directory - * @G_USER_DIRECTORY_VIDEOS: the user's Movies directory - * @G_USER_N_DIRECTORIES: the number of enum values + * g_object_set_valist: (skip) + * @object: a #GObject + * @first_property_name: name of the first property to set + * @var_args: value for the first property, followed optionally by more name/value pairs, followed by %NULL * - * These are logical ids for special directories which are defined - * depending on the platform used. You should use g_get_user_special_dir() - * to retrieve the full path associated to the logical id. - * The #GUserDirectory enumeration can be extended at later date. Not - * every platform has a directory for every logical id in this - * enumeration. + * Sets properties on an object. + */ + + +/** + * g_object_steal_data: + * @object: #GObject containing the associations + * @key: name of the key * - * Since: 2.14 + * Remove a specified datum from the object's data associations, + * without invoking the association's destroy handler. + * + * Returns: (transfer full): the data if found, or %NULL if no such data exists. */ /** - * g_value_get_object: - * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * g_object_steal_qdata: + * @object: The GObject to get a stored user data pointer from + * @quark: A #GQuark, naming the user data pointer * - * Get the contents of a %G_TYPE_OBJECT derived #GValue. + * This function gets back user data pointers stored via + * g_object_set_qdata() and removes the @data from object + * without invoking its destroy() function (if any was + * set). + * Usually, calling this function is only required to update + * user data pointers with a destroy notifier, for example: + * |[ + * void + * object_add_to_user_list (GObject *object, + * const gchar *new_string) + * { + * // the quark, naming the object data + * GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); + * // retrive the old string list + * GList *list = g_object_steal_qdata (object, quark_string_list); + * // prepend new string + * list = g_list_prepend (list, g_strdup (new_string)); + * // this changed 'list', so we need to set it again + * g_object_set_qdata_full (object, quark_string_list, list, free_string_list); + * } + * static void + * free_string_list (gpointer data) + * { + * GList *node, *list = data; + * for (node = list; node; node = node->next) + * g_free (node->data); + * g_list_free (list); + * } + * ]| + * Using g_object_get_qdata() in the above example, instead of + * g_object_steal_qdata() would have left the destroy function set, + * and thus the partial string list would have been freed upon + * g_object_set_qdata_full(). * - * Returns: (type GObject.Object) (transfer none): object contents of @value + * Returns: (transfer full): The user data pointer set, or %NULL */ /** - * G_TYPE_RESERVED_GLIB_LAST: + * g_object_thaw_notify: + * @object: a #GObject * - * Last fundamental type number reserved for GLib. + * Reverts the effect of a previous call to + * g_object_freeze_notify(). The freeze count is decreased on @object + * and when it reaches zero, all queued "notify" signals are emitted. + * It is an error to call this function when the freeze count is zero. */ /** - * G_PARAM_SPEC_OBJECT: - * @pspec: a valid #GParamSpec instance + * g_object_unref: + * @object: (type GObject.Object): a #GObject * - * Casts a #GParamSpec instance into a #GParamSpecObject. + * Decreases the reference count of @object. When its reference count + * drops to 0, the object is finalized (i.e. its memory is freed). */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH: + * g_object_watch_closure: + * @object: GObject restricting lifetime of @closure + * @closure: GClosure to watch * - * Allowed characters in a path. Includes "!$&'()*+,;=:@/". + * This function essentially limits the life time of the @closure to + * the life time of the object. That is, when the object is finalized, + * the @closure is invalidated by calling g_closure_invalidate() on + * it, in order to prevent invocations of the closure with a finalized + * (nonexisting) object. Also, g_object_ref() and g_object_unref() are + * added as marshal guards to the @closure, to ensure that an extra + * reference count is held on @object during invocation of the + * use this @object as closure data. */ /** - * GParamSpecObject: - * @parent_instance: private #GParamSpec portion + * g_object_weak_ref: (skip) + * @object: #GObject to reference weakly + * @notify: callback to invoke before the object is freed + * @data: extra data to pass to notify * - * A #GParamSpec derived structure that contains the meta data for object properties. + * Adds a weak reference callback to an object. Weak references are + * used for notification when an object is finalized. They are called + * "weak references" because they allow you to safely hold a pointer + * to an object without calling g_object_ref() (g_object_ref() adds a + * strong reference, that is, forces the object to stay alive). */ /** - * GTimeType: - * @G_TIME_TYPE_STANDARD: the time is in local standard time - * @G_TIME_TYPE_DAYLIGHT: the time is in local daylight time - * @G_TIME_TYPE_UNIVERSAL: the time is in UTC + * g_object_weak_unref: (skip) + * @object: #GObject to remove a weak reference from + * @notify: callback to search for + * @data: data to search for * - * Disambiguates a given time in two ways. - * First, specifies if the given time is in universal or local time. - * Second, if the time is in local time, specifies if it is local - * standard time or local daylight time. This is important for the case - * where the same local time occurs twice (during daylight savings time - * transitions, for example). + * Removes a weak reference callback to an object. */ /** - * G_PARAM_MASK: + * g_param_spec_boolean: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Mask containing the bits of #GParamSpec.flags which are reserved for GLib. + * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN + * property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * GTypeInfo: - * @class_size: Size of the class structure (required for interface, classed and instantiatable types). - * @base_init: Location of the base initialization function (optional). - * @base_finalize: Location of the base finalization function (optional). - * @class_init: Location of the class initialization function for classed and instantiatable types. Location of the default vtable inititalization function for interface types. (optional) This function is used both to fill in virtual functions in the class or default vtable, and to do type-specific setup such as registering signals and object properties. - * @class_finalize: Location of the class finalization function for classed and instantiatable types. Location fo the default vtable finalization function for interface types. (optional) - * @class_data: User-supplied data passed to the class init/finalize functions. - * @instance_size: Size of the instance (object) structure (required for instantiatable types only). - * @n_preallocs: Prior to GLib 2.10, it specified the number of pre-allocated (cached) instances to reserve memory for (0 indicates no caching). Since GLib 2.10, it is ignored, since instances are allocated with the <link linkend="glib-Memory-Slices">slice allocator</link> now. - * @instance_init: Location of the instance initialization function (optional, for instantiatable types only). - * @value_table: A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types). + * g_param_spec_boxed: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @boxed_type: %G_TYPE_BOXED derived type of this property + * @flags: flags for the property specified * - * This structure is used to provide the type system with the information - * required to initialize and destruct (finalize) a type's class and - * its instances. - * The initialized structure is passed to the g_type_register_static() function - * (or is copied into the provided #GTypeInfo structure in the - * g_type_plugin_complete_type_info()). The type system will perform a deep - * copy of this structure, so its memory does not need to be persistent - * across invocation of g_type_register_static(). + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED + * derived property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * GClassFinalizeFunc: - * @g_class: The #GTypeClass structure to finalize. - * @class_data: The @class_data member supplied via the #GTypeInfo structure. + * g_param_spec_char: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * 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 - * reference count drops to zero). + * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. + * + * Returns: a newly created parameter specification */ /** - * G_TYPE_PARAM_UINT64: + * g_param_spec_double: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * The #GType of #GParamSpecUInt64. + * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE + * property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * G_VARIANT_TYPE_INT16: + * g_param_spec_enum: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @enum_type: a #GType derived from %G_TYPE_ENUM + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * The type of an integer value that can range from -32768 to 32767. + * Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM + * property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_value_get_double: - * @value: a valid #GValue of type %G_TYPE_DOUBLE + * g_param_spec_flags: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @flags_type: a #GType derived from %G_TYPE_FLAGS + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Get the contents of a %G_TYPE_DOUBLE #GValue. + * Creates a new #GParamSpecFlags instance specifying a %G_TYPE_FLAGS + * property. + * See g_param_spec_internal() for details on property names. * - * Returns: double contents of @value + * Returns: a newly created parameter specification */ /** - * g_cclosure_marshal_BOOL__FLAGS: + * g_param_spec_float: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Another name for g_cclosure_marshal_BOOLEAN__FLAGS(). + * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_cclosure_marshal_VOID__OBJECT: - * @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 + * g_param_spec_get_blurb: + * @pspec: a valid #GParamSpec * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)</literal>. + * Get the short description of a #GParamSpec. + * + * Returns: the short description of @pspec. */ /** - * GValueArray: - * @n_values: number of values contained in the array - * @values: array of values + * g_param_spec_get_name: + * @pspec: a valid #GParamSpec * - * A #GValueArray contains an array of #GValue elements. + * Get the name of a #GParamSpec. + * + * Returns: the name of @pspec. */ /** - * g_object_set_qdata_full: (skip) - * @object: The GObject to set store a user data pointer - * @quark: A #GQuark, naming the user data pointer - * @data: An opaque user data pointer - * @destroy: Function to invoke with @data as argument, when @data needs to be freed + * g_param_spec_get_nick: + * @pspec: a valid #GParamSpec * - * This function works like g_object_set_qdata(), but in addition, - * a void (*destroy) (gpointer) function may be specified which is - * called with @data as argument when the @object is finalized, or - * the data is being overwritten by a call to g_object_set_qdata() - * with the same @quark. + * Get the nickname of a #GParamSpec. + * + * Returns: the nickname of @pspec. */ /** - * g_type_from_name: - * @name: Type name to lookup. + * g_param_spec_get_qdata: + * @pspec: a valid #GParamSpec + * @quark: a #GQuark, naming the user data pointer * - * Lookup the type ID from a given type name, returning 0 if no type - * has been registered under this name (this is the preferred method - * to find out by name whether a specific type has been registered - * yet). + * Gets back user data pointers stored via g_param_spec_set_qdata(). * - * Returns: Corresponding type ID or 0. + * Returns: (transfer none): the user data pointer set, or %NULL */ /** - * g_object_newv: - * @object_type: the type id of the #GObject subtype to instantiate - * @n_parameters: the length of the @parameters array - * @parameters: (array length=n_parameters): an array of #GParameter + * g_param_spec_get_redirect_target: + * @pspec: a #GParamSpec * - * Creates a new instance of a #GObject subtype and sets its properties. - * Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY) - * which are not explicitly specified are set to their default values. + * If the paramspec redirects operations to another paramspec, + * returns that paramspec. Redirect is used typically for + * providing a new implementation of a property in a derived + * type while preserving all the properties from the parent + * type. Redirection is established by creating a property + * of type #GParamSpecOverride. See g_object_class_override_property() + * for an example of the use of this capability. + * paramspec should be redirected, or %NULL if none. * - * Rename to: g_object_new - * Returns: (type GObject.Object) (transfer full): a new instance of + * Since: 2.4 + * Returns: (transfer none): paramspec to which requests on this */ /** - * g_type_interface_get_plugin: - * @instance_type: the #GType value of an instantiatable type. - * @interface_type: the #GType value of an interface type. + * g_param_spec_gtype: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @is_a_type: a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) + * @flags: flags for the property specified * - * Returns the #GTypePlugin structure for the dynamic interface - * have a #GTypePlugin structure. See g_type_add_interface_dynamic(). - * interface @interface_type of @instance_type. + * Creates a new #GParamSpecGType instance specifying a + * %G_TYPE_GTYPE property. + * See g_param_spec_internal() for details on property names. * - * Returns: (transfer none): the #GTypePlugin for the dynamic + * Since: 2.10 + * Returns: a newly created parameter specification */ /** - * G_TYPE_CHECK_VALUE_TYPE: - * @value: a #GValue - * @g_type: The type to be checked. + * g_param_spec_int: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Checks if @value has been initialized to hold values - * of type @g_type. - * This macro should only be used in type implementations. + * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. + * See g_param_spec_internal() for details on property names. * - * Returns: %TRUE on success. + * Returns: a newly created parameter specification */ /** - * G_CLOSURE_N_NOTIFIERS: - * @cl: a #GClosure + * g_param_spec_int64: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * 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(), - * g_closure_add_invalidate_notifier() and g_closure_add_marshal_guards(). + * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. + * See g_param_spec_internal() for details on property names. * - * Returns: number of notifiers + * Returns: a newly created parameter specification */ /** - * G_PARAM_SPEC_BOXED: - * @pspec: a valid #GParamSpec instance + * g_param_spec_internal: (skip) + * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM + * @name: the canonical name of the property + * @nick: the nickname of the property + * @blurb: a short description of the property + * @flags: a combination of #GParamFlags * - * Cast a #GParamSpec instance into a #GParamSpecBoxed. + * Creates a new #GParamSpec instance. + * A property name consists of segments consisting of ASCII letters and + * digits, separated by either the '-' or '_' character. The first + * character of a property name must be a letter. Names which violate these + * rules lead to undefined behaviour. + * When creating and looking up a #GParamSpec, either separator can be + * used, but they cannot be mixed. Using '-' is considerably more + * efficient and in fact required when using property names as detail + * strings for signals. + * Beyond the name, #GParamSpec<!-- -->s have two more descriptive + * strings associated with them, the @nick, which should be suitable + * for use as a label for the property in a property editor, and the + * e.g. a tooltip. The @nick and @blurb should ideally be localized. + * + * Returns: a newly allocated #GParamSpec instance */ /** - * g_object_steal_qdata: - * @object: The GObject to get a stored user data pointer from - * @quark: A #GQuark, naming the user data pointer + * g_param_spec_long: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * This function gets back user data pointers stored via - * g_object_set_qdata() and removes the @data from object - * without invoking its destroy() function (if any was - * set). - * Usually, calling this function is only required to update - * user data pointers with a destroy notifier, for example: - * |[ - * void - * object_add_to_user_list (GObject *object, - * const gchar *new_string) - * { - * // the quark, naming the object data - * GQuark quark_string_list = g_quark_from_static_string ("my-string-list"); - * // retrive the old string list - * GList *list = g_object_steal_qdata (object, quark_string_list); - * // prepend new string - * list = g_list_prepend (list, g_strdup (new_string)); - * // this changed 'list', so we need to set it again - * g_object_set_qdata_full (object, quark_string_list, list, free_string_list); - * } - * static void - * free_string_list (gpointer data) - * { - * GList *node, *list = data; - * for (node = list; node; node = node->next) - * g_free (node->data); - * g_list_free (list); - * } - * ]| - * Using g_object_get_qdata() in the above example, instead of - * g_object_steal_qdata() would have left the destroy function set, - * and thus the partial string list would have been freed upon - * g_object_set_qdata_full(). + * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. + * See g_param_spec_internal() for details on property names. * - * Returns: (transfer full): The user data pointer set, or %NULL + * Returns: a newly created parameter specification */ /** - * g_object_set_qdata: (skip) - * @object: The GObject to set store a user data pointer - * @quark: A #GQuark, naming the user data pointer - * @data: An opaque user data pointer + * g_param_spec_object: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @object_type: %G_TYPE_OBJECT derived type of this property + * @flags: flags for the property specified * - * This sets an opaque, named pointer on an object. - * The name is specified through a #GQuark (retrived e.g. via - * g_quark_from_static_string()), and the pointer - * can be gotten back from the @object with g_object_get_qdata() - * until the @object is finalized. - * Setting a previously set user data pointer, overrides (frees) - * the old pointer set, using #NULL as pointer essentially - * removes the data stored. + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT + * derived property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_type_add_interface_check: (skip) - * @check_data: data to pass to @check_func - * @check_func: function to be called after each interface is initialized. + * g_param_spec_override: (skip) + * @name: the name of the property. + * @overridden: The property that is being overridden * - * Adds a function to be called after an interface vtable is - * initialized for any class (i.e. after the @interface_init member of - * #GInterfaceInfo has been called). - * This function is useful when you want to check an invariant that - * depends on the interfaces of a class. For instance, the - * implementation of #GObject uses this facility to check that an - * object implements all of the properties that are defined on its - * interfaces. + * Creates a new property of type #GParamSpecOverride. This is used + * to direct operations to another paramspec, and will not be directly + * useful unless you are implementing a new base type similar to GObject. * * Since: 2.4 + * Returns: the newly created #GParamSpec */ /** - * G_IS_PARAM_SPEC_ULONG: - * @pspec: a valid #GParamSpec instance + * g_param_spec_param: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @param_type: a #GType derived from %G_TYPE_PARAM + * @flags: flags for the property specified * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. + * Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM + * property. + * See g_param_spec_internal() for details on property names. * - * Returns: %TRUE on success. + * Returns: a newly created parameter specification */ /** - * GBinding:flags: + * g_param_spec_pointer: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @flags: flags for the property specified * - * Flags to be used to control the #GBinding + * Creates a new #GParamSpecPoiner instance specifying a pointer property. + * See g_param_spec_internal() for details on property names. * - * Since: 2.26 + * Returns: a newly created parameter specification */ /** - * GParamSpecClass: - * @g_type_class: the parent class - * @value_type: the #GValue type for this parameter - * @finalize: The instance finalization function (optional), should chain up to the finalize method of the parent class. - * @value_set_default: Resets a @value to the default value for this type (recommended, the default is g_value_reset()), see g_param_value_set_default(). - * @value_validate: Ensures that the contents of @value comply with the specifications set out by this type (optional), see g_param_value_set_validate(). - * @values_cmp: Compares @value1 with @value2 according to this type (recommended, the default is memcmp()), see g_param_values_cmp(). + * g_param_spec_pool_insert: + * @pool: a #GParamSpecPool. + * @pspec: the #GParamSpec to insert + * @owner_type: a #GType identifying the owner of @pspec * - * The class structure for the <structname>GParamSpec</structname> type. - * Normally, <structname>GParamSpec</structname> classes are filled by - * g_param_type_register_static(). + * Inserts a #GParamSpec in the pool. */ /** - * g_value_array_copy: - * @value_array: #GValueArray to copy + * g_param_spec_pool_list: + * @pool: a #GParamSpecPool + * @owner_type: the owner to look for + * @n_pspecs_p: (out): return location for the length of the returned array * - * Construct an exact copy of a #GValueArray by duplicating all its - * contents. + * Gets an array of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool. + * allocated array containing pointers to all #GParamSpecs + * owned by @owner_type in the pool * - * Returns: (transfer full): Newly allocated copy of #GValueArray + * Returns: (array length=n_pspecs_p) (transfer container): a newly */ /** - * g_enum_get_value: - * @enum_class: a #GEnumClass - * @value: the value to look up + * g_param_spec_pool_list_owned: + * @pool: a #GParamSpecPool + * @owner_type: the owner to look for * - * Returns the #GEnumValue for a value. - * member of the enumeration + * Gets an #GList of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool. + * #GList of all #GParamSpec<!-- -->s owned by @owner_type in + * the pool#GParamSpec<!-- -->s. * - * Returns: the #GEnumValue for @value, or %NULL if @value is not a + * Returns: (transfer container) (element-type GObject.ParamSpec): a */ /** - * G_IS_PARAM_SPEC_LONG: - * @pspec: a valid #GParamSpec instance + * g_param_spec_pool_lookup: + * @pool: a #GParamSpecPool + * @param_name: the name to look for + * @owner_type: the owner to look for + * @walk_ancestors: If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. + * Looks up a #GParamSpec in the pool. + * matching #GParamSpec was found. * - * Returns: %TRUE on success. + * Returns: (transfer none): The found #GParamSpec, or %NULL if no */ /** - * g_value_register_transform_func: (skip) - * @src_type: Source type. - * @dest_type: Target type. - * @transform_func: a function which transforms values of type @src_type into value of type @dest_type + * g_param_spec_pool_new: + * @type_prefixing: Whether the pool will support type-prefixed property names. * - * Registers a value transformation function for use in g_value_transform(). - * A previously registered transformation function for @src_type and @dest_type - * will be replaced. + * Creates a new #GParamSpecPool. + * If @type_prefixing is %TRUE, lookups in the newly created pool will + * allow to specify the owner as a colon-separated prefix of the + * property name, like "GtkContainer:border-width". This feature is + * deprecated, so you should always set @type_prefixing to %FALSE. + * + * Returns: (transfer none): a newly allocated #GParamSpecPool. */ /** - * g_object_ref: - * @object: (type GObject.Object): a #GObject + * g_param_spec_pool_remove: + * @pool: a #GParamSpecPool + * @pspec: the #GParamSpec to remove * - * Increases the reference count of @object. + * Removes a #GParamSpec from the pool. + */ + + +/** + * g_param_spec_ref: (skip) + * @pspec: a valid #GParamSpec * - * Returns: (type GObject.Object) (transfer none): the same @object + * Increments the reference count of @pspec. + * + * Returns: the #GParamSpec that was passed into this function */ /** - * G_IS_FLAGS_CLASS: - * @class: a #GFlagsClass + * g_param_spec_ref_sink: (skip) + * @pspec: a valid #GParamSpec * - * Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS - * or derived. + * Convenience function to ref and sink a #GParamSpec. + * + * Since: 2.10 + * Returns: the #GParamSpec that was passed into this function */ /** - * g_newa: - * @struct_type: Type of memory chunks to be allocated - * @n_structs: Number of chunks to be allocated + * g_param_spec_set_qdata: + * @pspec: the #GParamSpec to set store a user data pointer + * @quark: a #GQuark, naming the user data pointer + * @data: an opaque user data pointer * - * Wraps g_alloca() in a more typesafe manner. + * Sets an opaque, named pointer on a #GParamSpec. The name is + * specified through a #GQuark (retrieved e.g. via + * g_quark_from_static_string()), and the pointer can be gotten back + * from the @pspec with g_param_spec_get_qdata(). Setting a + * previously set user data pointer, overrides (frees) the old pointer + * set, using %NULL as pointer essentially removes the data stored. + */ + + +/** + * g_param_spec_set_qdata_full: (skip) + * @pspec: the #GParamSpec to set store a user data pointer + * @quark: a #GQuark, naming the user data pointer + * @data: an opaque user data pointer + * @destroy: function to invoke with @data as argument, when @data needs to be freed * - * Returns: Pointer to stack space for @n_structs chunks of type @struct_type + * This function works like g_param_spec_set_qdata(), but in addition, + * a <literal>void (*destroy) (gpointer)</literal> function may be + * specified which is called with @data as argument when the @pspec is + * finalized, or the data is being overwritten by a call to + * g_param_spec_set_qdata() with the same @quark. */ /** - * g_cclosure_marshal_VOID__BOOLEAN: - * @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 + * g_param_spec_sink: + * @pspec: a valid #GParamSpec * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)</literal>. + * The initial reference count of a newly created #GParamSpec is 1, + * even though no one has explicitly called g_param_spec_ref() on it + * yet. So the initial reference count is flagged as "floating", until + * someone calls <literal>g_param_spec_ref (pspec); g_param_spec_sink + * (pspec);</literal> in sequence on it, taking over the initial + * reference count (thus ending up with a @pspec that has a reference + * count of 1 still, but is not flagged "floating" anymore). */ /** - * g_type_remove_interface_check: (skip) - * @check_data: callback data passed to g_type_add_interface_check() - * @check_func: callback function passed to g_type_add_interface_check() + * g_param_spec_steal_qdata: + * @pspec: the #GParamSpec to get a stored user data pointer from + * @quark: a #GQuark, naming the user data pointer * - * Removes an interface check function added with - * g_type_add_interface_check(). + * Gets back user data pointers stored via g_param_spec_set_qdata() + * and removes the @data from @pspec without invoking its destroy() + * function (if any was set). Usually, calling this function is only + * required to update user data pointers with a destroy notifier. * - * Since: 2.4 + * Returns: (transfer none): the user data pointer set, or %NULL */ /** - * g_cclosure_marshal_VOID__VOID: - * @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 + * g_param_spec_string: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, gpointer user_data)</literal>. + * Creates a new #GParamSpecString instance. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_value_array_sort: - * @value_array: #GValueArray to sort - * @compare_func: (scope call): function to compare elements + * g_param_spec_uchar: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Sort @value_array using @compare_func to compare the elements accoring to - * the semantics of #GCompareFunc. - * The current implementation uses Quick-Sort as sorting algorithm. + * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * Returns: a newly created parameter specification */ /** - * G_TYPE_CHECK_INSTANCE_CAST: - * @instance: Location of a #GTypeInstance structure. - * @g_type: The type to be returned. - * @c_type: The corresponding C type of @g_type. + * g_param_spec_uint: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Checks that @instance is an instance of the type identified by @g_type - * and issues a warning if this is not the case. Returns @instance casted - * to a pointer to @c_type. - * This macro should only be used in type implementations. + * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_value_set_static_boxed: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: static boxed value to be set + * g_param_spec_uint64: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * 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. + * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 + * property. + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * g_type_default_interface_ref: - * @g_type: an interface type + * g_param_spec_ulong: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @minimum: minimum value for the property specified + * @maximum: maximum value for the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Increments the reference count for the interface type @g_type, - * and returns the default interface vtable for the type. - * If the type is not currently in use, then the default vtable - * for the type will be created and initalized by calling - * the base interface init and default vtable init functions for - * the type (the @<structfield>base_init</structfield> - * and <structfield>class_init</structfield> members of #GTypeInfo). - * Calling g_type_default_interface_ref() is useful when you - * want to make sure that signals and properties for an interface - * have been installed. - * vtable for the interface; call g_type_default_interface_unref() - * when you are done using the interface. + * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG + * property. + * See g_param_spec_internal() for details on property names. * - * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default + * Returns: a newly created parameter specification */ /** - * G_IS_PARAM_SPEC_PARAM: - * @pspec: a valid #GParamSpec instance + * g_param_spec_unichar: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @default_value: default value for the property specified + * @flags: flags for the property specified * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. + * Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT + * property. #GValue structures for this property can be accessed with + * g_value_set_uint() and g_value_get_uint(). + * See g_param_spec_internal() for details on property names. * - * Returns: %TRUE on success. + * Returns: a newly created parameter specification */ /** - * g_object_unref: - * @object: (type GObject.Object): a #GObject + * g_param_spec_unref: (skip) + * @pspec: a valid #GParamSpec * - * Decreases the reference count of @object. When its reference count - * drops to 0, the object is finalized (i.e. its memory is freed). + * Decrements the reference count of a @pspec. */ /** - * GBoxedFreeFunc: - * @boxed: The boxed structure to be freed. + * g_param_spec_value_array: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL + * @flags: flags for the property specified * - * This function is provided by the user and should free the boxed - * structure passed. + * Creates a new #GParamSpecValueArray instance specifying a + * %G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a + * %G_TYPE_BOXED type, as such, #GValue structures for this property + * can be accessed with g_value_set_boxed() and g_value_get_boxed(). + * See g_param_spec_internal() for details on property names. + * + * Returns: a newly created parameter specification */ /** - * G_CCLOSURE_SWAP_DATA: - * @cclosure: a #GCClosure + * g_param_spec_variant: (skip) + * @name: canonical name of the property specified + * @nick: nick name for the property specified + * @blurb: description of the property specified + * @type: a #GVariantType + * @default_value: (allow-none): a #GVariant of type @type to use as the default value, or %NULL + * @flags: flags for the property specified * - * Checks whether the user data of the #GCClosure should be passed as the - * first parameter to the callback. See g_cclosure_new_swap(). + * Creates a new #GParamSpecVariant instance specifying a #GVariant + * property. + * If @default_value is floating, it is consumed. + * See g_param_spec_internal() for details on property names. * - * Returns: %TRUE if data has to be swapped. + * Returns: the newly created #GParamSpec + * Since: 2.26 */ /** - * g_value_take_object: (skip) - * @value: a valid #GValue of %G_TYPE_OBJECT derived type - * @v_object: object value to be set + * g_param_type_register_static: + * @name: 0-terminated string used as the name of the new #GParamSpec type. + * @pspec_info: The #GParamSpecTypeInfo for this #GParamSpec type. * - * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object - * and takes over the ownership of the callers reference to @v_object; - * the caller doesn't have to unref it any more (i.e. the reference - * count of the object is not increased). - * If you want the #GValue to hold its own reference to @v_object, use - * g_value_set_object() instead. + * 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. * - * Since: 2.4 + * Returns: The new type identifier. */ /** - * G_ENUM_CLASS_TYPE_NAME: - * @class: a #GEnumClass + * g_param_value_convert: + * @pspec: a valid #GParamSpec + * @src_value: souce #GValue + * @dest_value: destination #GValue of correct type for @pspec + * @strict_validation: %TRUE requires @dest_value to conform to @pspec without modifications * - * Get the static type name from a given #GEnumClass structure. + * Transforms @src_value into @dest_value if possible, and then + * validates @dest_value, in order for it to conform to @pspec. If + * transformed @dest_value complied to @pspec without modifications. + * See also g_value_type_transformable(), g_value_transform() and + * g_param_value_validate(). + * %FALSE otherwise and @dest_value is left untouched. * - * Returns: the type name. + * Returns: %TRUE if transformation and validation were successful, */ /** - * G_VALUE_COLLECT: - * @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected - * @var_args: the va_list variable; it may be evaluated multiple times - * @flags: flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. - * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails + * g_param_value_defaults: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec * - * Collects a variable argument value from a va_list. We have to - * implement the varargs collection as a macro, because on some systems - * va_list variables cannot be passed by reference. - * you should use the #G_VALUE_COLLECT_INIT variant and pass the unitialized - * #GValue. That variant is faster than #G_VALUE_COLLECT. + * Checks whether @value contains the default value as specified in @pspec. * - * Note: If you are creating the @value argument just before calling this macro, + * Returns: whether @value contains the canonical default for this @pspec + */ + + +/** + * g_param_value_set_default: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec + * + * Sets @value to its default value as specified in @pspec. + */ + + +/** + * g_param_value_validate: + * @pspec: a valid #GParamSpec + * @value: a #GValue of correct type for @pspec + * + * Ensures that the contents of @value comply with the specifications + * set out by @pspec. For example, a #GParamSpecInt might require + * that integers stored in @value may not be smaller than -42 and not be + * greater than +42. If @value contains an integer outside of this range, + * it is modified accordingly, so the resulting value will fit into the + * range -42 .. +42. + * + * Returns: whether modifying @value was necessary to ensure validity + */ + + +/** + * g_param_values_cmp: + * @pspec: a valid #GParamSpec + * @value1: a #GValue of correct type for @pspec + * @value2: a #GValue of correct type for @pspec + * + * Compares @value1 with @value2 according to @pspec, and return -1, 0 or +1, + * if @value1 is found to be less than, equal to or greater than @value2, + * respectively. + * + * Returns: -1, 0 or +1, for a less than, equal to or greater than result + */ + + +/** + * g_pointer_type_register_static: + * @name: the name of the new pointer type. + * + * Creates a new %G_TYPE_POINTER derived type id for a new + * pointer type with name @name. + * + * Returns: a new %G_TYPE_POINTER derived type id for @name. + */ + + +/** + * g_renew: + * @struct_type: the type of the elements to allocate + * @mem: the currently allocated memory + * @n_structs: the number of elements to allocate + * + * Reallocates the memory pointed to by @mem, so that it now has space for + * the memory, which may have been moved. + * Care is taken to avoid overflow when calculating the size of the allocated block. + * + * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type + */ + + +/** + * g_signal_accumulator_first_wins: + * @ihint: standard #GSignalAccumulator parameter + * @return_accu: standard #GSignalAccumulator parameter + * @handler_return: standard #GSignalAccumulator parameter + * @dummy: standard #GSignalAccumulator parameter + * + * A predefined #GSignalAccumulator for signals intended to be used as a + * hook for application code to provide a particular value. Usually + * only one such value is desired and multiple handlers for the same + * signal don't make much sense (except for the case of the default + * handler defined in the class structure, in which case you will + * usually want the signal connection to override the class handler). + * This accumulator will use the return value from the first signal + * handler that is run as the return value for the signal and not run + * + * Any further handlers (ie: the first handler "wins"). + * Returns: standard #GSignalAccumulator result + * Since: 2.28 */ @@ -8482,373 +8101,651 @@ /** - * GTypePlugin: + * g_signal_add_emission_hook: + * @signal_id: the signal identifier, as returned by g_signal_lookup(). + * @detail: the detail on which to call the hook. + * @hook_func: a #GSignalEmissionHook function. + * @hook_data: user data for @hook_func. + * @data_destroy: a #GDestroyNotify for @hook_data. * - * The <structname>GTypePlugin</structname> typedef is used as a placeholder - * for objects that implement the <structname>GTypePlugin</structname> - * interface. + * Adds an emission hook for a signal, which will get called for any emission + * of that signal, independent of the instance. This is possible only + * for signals which don't have #G_SIGNAL_NO_HOOKS flag set. + * + * Returns: the hook id, for later use with g_signal_remove_emission_hook(). */ /** - * g_new0: - * @struct_type: the type of the elements to allocate. - * @n_structs: the number of elements to allocate. + * g_signal_chain_from_overridden: + * @instance_and_params: the argument list of the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. + * @return_value: Location for the return value. * - * Allocates @n_structs elements of type @struct_type, initialized to 0's. - * The returned pointer is cast to a pointer to the given type. - * If @n_structs is 0 it returns %NULL. - * Care is taken to avoid overflow when calculating the size of the allocated block. - * Since the returned pointer is already casted to the right type, - * it is normally unnecessary to cast it explicitly, and doing - * so might hide memory allocation errors. + * Calls the original class closure of a signal. This function should only + * be called from an overridden class closure; see + * g_signal_override_class_closure() and + * g_signal_override_class_handler(). + */ + + +/** + * g_signal_chain_from_overridden_handler: + * @instance: the instance the signal is being emitted on. + * @...: parameters to be passed to the parent class closure, 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. * - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type. + * Calls the original class closure of a signal. This function should + * only be called from an overridden class closure; see + * g_signal_override_class_closure() and + * g_signal_override_class_handler(). + * + * Since: 2.18 */ /** - * g_value_dup_boxed: (skip) - * @value: a valid #GValue of %G_TYPE_BOXED derived type + * g_signal_connect: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, - * the boxed value is duplicated and needs to be later freed with - * return_value); + * Connects a #GCallback function to a signal for a particular object. + * The handler will be called before the default handler of the signal. * - * G_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), - * Returns: boxed contents of @value + * Returns: the handler id */ /** - * g_value_dup_param: (skip) - * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM + * g_signal_connect_after: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * Get the contents of a %G_TYPE_PARAM #GValue, increasing its - * reference count. - * no longer needed. + * Connects a #GCallback function to a signal for a particular object. + * The handler will be called after the default handler of the signal. * - * Returns: #GParamSpec content of @value, should be unreferenced when + * Returns: the handler id */ /** - * GOptionFlags: - * @G_OPTION_FLAG_HIDDEN: The option doesn't appear in <option>--help</option> output. - * @G_OPTION_FLAG_IN_MAIN: The option appears in the main section of the <option>--help</option> output, even if it is defined in a group. - * @G_OPTION_FLAG_REVERSE: For options of the %G_OPTION_ARG_NONE kind, this flag indicates that the sense of the option is reversed. - * @G_OPTION_FLAG_NO_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the callback does not take any argument (like a %G_OPTION_ARG_NONE option). Since 2.8 - * @G_OPTION_FLAG_FILENAME: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument should be passed to the callback in the GLib filename encoding rather than UTF-8. Since 2.8 - * @G_OPTION_FLAG_OPTIONAL_ARG: For options of the %G_OPTION_ARG_CALLBACK kind, this flag indicates that the argument supply is optional. If no argument is given then data of %GOptionParseFunc will be set to NULL. Since 2.8 - * @G_OPTION_FLAG_NOALIAS: This flag turns off the automatic conflict resolution which prefixes long option names with <literal>groupname-</literal> if there is a conflict. This option should only be used in situations where aliasing is necessary to model some legacy commandline interface. It is not safe to use this option, unless all option groups are under your direct control. Since 2.8. + * g_signal_connect_closure: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @closure: the closure to connect. + * @after: whether the handler should be called before or after the default handler of the signal. * - * Flags which modify individual options. + * Connects a closure to a signal for a particular object. + * + * Returns: the handler id */ /** - * G_TYPE_INSTANCE_GET_PRIVATE: - * @instance: the instance of a type deriving from @private_type. - * @g_type: the type identifying which private data to retrieve. - * @c_type: The C type for the private structure. + * g_signal_connect_closure_by_id: + * @instance: the instance to connect to. + * @signal_id: the id of the signal. + * @detail: the detail. + * @closure: the closure to connect. + * @after: whether the handler should be called before or after the default handler of the signal. * - * 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(). - * This macro should only be used in type implementations. + * Connects a closure to a signal for a particular object. * - * Since: 2.4 - * Returns: a pointer to the private data structure. + * Returns: the handler id */ /** - * G_VALUE_HOLDS: - * @value: A #GValue structure. - * @type: A #GType value. + * g_signal_connect_data: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. + * @destroy_data: a #GClosureNotify for @data. + * @connect_flags: a combination of #GConnectFlags. * - * Checks if @value holds (or contains) a value of @type. - * This macro will also check for @value != %NULL and issue a - * warning if the check fails. + * Connects a #GCallback function to a signal for a particular object. Similar + * to g_signal_connect(), but allows to provide a #GClosureNotify for the data + * which will be called when the signal handler is disconnected and no longer + * used. Specify @connect_flags if you need <literal>..._after()</literal> or + * <literal>..._swapped()</literal> variants of this function. * - * Returns: %TRUE if @value holds the @type. + * Returns: the handler id */ /** - * G_PARAM_SPEC: - * @pspec: a valid #GParamSpec + * g_signal_connect_object: (skip) + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @gobject: the object to pass as data to @c_handler. + * @connect_flags: a combination of #GConnnectFlags. * - * Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into - * a #GParamSpec object. + * This is similar to g_signal_connect_data(), but uses a closure which + * ensures that the @gobject stays alive during the call to @c_handler + * by temporarily adding a reference count to @gobject. + * Note that there is a bug in GObject that makes this function + * much less useful than it might seem otherwise. Once @gobject is + * disposed, the callback will no longer be called, but, the signal + * handler is <emphasis>not</emphasis> currently disconnected. If the + * matter, since the signal will automatically be removed, but + * if @instance persists, then the signal handler will leak. You + * should not remove the signal yourself because in a future versions of + * GObject, the handler <emphasis>will</emphasis> automatically + * be disconnected. + * It's possible to work around this problem in a way that will + * continue to work with future versions of GObject by checking + * that the signal handler is still connected before disconnected it: + * <informalexample><programlisting> + * if (g_signal_handler_is_connected (instance, id)) + * g_signal_handler_disconnect (instance, id); + * </programlisting></informalexample> + * + * Returns: the handler id. */ /** - * g_flags_complete_type_info: - * @g_flags_type: the type identifier of the type being completed - * @info: the #GTypeInfo struct to be filled in - * @const_values: An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * g_signal_connect_swapped: + * @instance: the instance to connect to. + * @detailed_signal: a string of the form "signal-name::detail". + * @c_handler: the #GCallback to connect. + * @data: data to pass to @c_handler calls. * - * This function is meant to be called from the complete_type_info() - * function of a #GTypePlugin implementation, see the example for - * g_enum_complete_type_info() above. + * Connects a #GCallback function to a signal for a particular object. + * The instance on which the signal is emitted and @data will be swapped when + * calling the handler. + * + * Returns: the handler id */ /** - * G_TYPE_PARAM: + * g_signal_emit: + * @instance: the instance the signal is being emitted on. + * @signal_id: the signal id + * @detail: the detail + * @...: 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. * - * The fundamental type from which all #GParamSpec types are derived. + * Emits a signal. + * Note that g_signal_emit() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). */ /** - * g_object_steal_data: - * @object: #GObject containing the associations - * @key: name of the key + * g_signal_emit_by_name: + * @instance: the instance the signal is being emitted on. + * @detailed_signal: a string of the form "signal-name::detail". + * @...: 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. * - * Remove a specified datum from the object's data associations, - * without invoking the association's destroy handler. + * Emits a signal. + * Note that g_signal_emit_by_name() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). + */ + + +/** + * g_signal_emit_valist: + * @instance: the instance the signal is being emitted on. + * @signal_id: the signal id + * @detail: the detail + * @var_args: a list of 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. * - * Returns: (transfer full): the data if found, or %NULL if no such data exists. + * Emits a signal. + * Note that g_signal_emit_valist() resets the return value to the default + * if no handlers are connected, in contrast to g_signal_emitv(). */ /** - * GParamSpecPool: + * g_signal_emitv: + * @instance_and_params: argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. + * @signal_id: the signal id + * @detail: the detail + * @return_value: Location to store the return value of the signal emission. * - * A #GParamSpecPool maintains a collection of #GParamSpec<!-- -->s 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. + * Emits a signal. + * Note that g_signal_emitv() doesn't change @return_value if no handlers are + * connected, in contrast to g_signal_emit() and g_signal_emit_valist(). */ /** - * G_OBJECT_CLASS_NAME: - * @class: a valid #GObjectClass + * g_signal_get_invocation_hint: + * @instance: the instance to query * - * Return the name of a class structure's type. - * should not be freed. + * Returns the invocation hint of the innermost signal emission of instance. * - * Returns: Type name of @class. The string is owned by the type system and + * Returns: the invocation hint of the innermost signal emission. */ /** - * g_object_ref_sink: - * @object: (type GObject.Object): a #GObject + * g_signal_handler_block: + * @instance: The instance to block the signal handler of. + * @handler_id: Handler id of the handler to be blocked. * - * Increase the reference count of @object, and possibly remove the - * <link linkend="floating-ref">floating</link> reference, if @object - * has a floating reference. - * In other words, if the object is floating, then this call "assumes - * ownership" of the floating reference, converting it to a normal - * reference by clearing the floating flag while leaving the reference - * count unchanged. If the object is not floating, then this call - * adds a new normal reference increasing the reference count by one. + * Blocks a handler of an instance so it will not be called during any + * signal emissions unless it is unblocked again. Thus "blocking" a + * signal handler means to temporarily deactive it, a signal handler + * has to be unblocked exactly the same amount of times it has been + * blocked before to become active again. + * The @handler_id has to be a valid signal handler id, connected to a + * signal of @instance. + */ + + +/** + * g_signal_handler_disconnect: + * @instance: The instance to remove the signal handler from. + * @handler_id: Handler id of the handler to be disconnected. * - * Since: 2.10 - * Returns: (type GObject.Object) (transfer none): @object + * Disconnects a handler from an instance so it will not be called during + * any future or currently ongoing emissions of the signal it has been + * connected to. The @handler_id becomes invalid and may be reused. + * The @handler_id has to be a valid signal handler id, connected to a + * signal of @instance. */ /** - * g_signal_list_ids: - * @itype: Instance or interface type. - * @n_ids: Location to store the number of signal ids for @itype. + * g_signal_handler_find: + * @instance: The instance owning the signal handler to be found. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. + * @signal_id: Signal the handler has to be connected to. + * @detail: Signal detail the handler has to be connected to. + * @closure: The closure the handler will invoke. + * @func: The C closure callback of the handler (useless for non-C closures). + * @data: The closure data of the handler's closure. * - * Lists the signals by id that a certain instance or interface type - * created. Further information about the signals can be acquired through - * g_signal_query(). + * Finds the first signal handler that matches certain selection criteria. + * The criteria mask is passed as an OR-ed combination of #GSignalMatchType + * flags, and the criteria values are passed as arguments. + * The match @mask has to be non-0 for successful matches. + * If no handler was found, 0 is returned. * - * Returns: Newly allocated array of signal IDs. + * Returns: A valid non-0 signal handler id for a successful match. */ /** - * GTypeCValue: - * @v_int: the field for holding integer values - * @v_long: the field for holding long integer values - * @v_int64: the field for holding 64 bit integer values - * @v_double: the field for holding floating point values - * @v_pointer: the field for holding pointers + * g_signal_handler_is_connected: + * @instance: The instance where a signal handler is sought. + * @handler_id: the handler id. * - * A union holding one collected value. + * Returns whether @handler_id is the id of a handler connected to @instance. + * + * Returns: whether @handler_id identifies a handler connected to @instance. */ /** - * g_object_notify: - * @object: a #GObject - * @property_name: the name of a property installed on the class of @object. + * g_signal_handler_unblock: + * @instance: The instance to unblock the signal handler of. + * @handler_id: Handler id of the handler to be unblocked. * - * Emits a "notify" signal for the property @property_name on @object. - * When possible, eg. when signaling a property change from within the class - * that registered the property, you should use g_object_notify_by_pspec() - * instead. + * Undoes the effect of a previous g_signal_handler_block() call. A + * blocked handler is skipped during signal emissions and will not be + * invoked, unblocking it (for exactly the amount of times it has been + * blocked before) reverts its "blocked" state, so the handler will be + * recognized by the signal system and is called upon future or + * currently ongoing signal emissions (since the order in which + * handlers are called during signal emissions is deterministic, + * whether the unblocked handler in question is called as part of a + * currently ongoing emission depends on how far that emission has + * proceeded yet). + * The @handler_id has to be a valid id of a signal handler that is + * connected to a signal of @instance and is currently blocked. */ /** - * G_VARIANT_TYPE_TUPLE: + * g_signal_handlers_block_by_func: + * @instance: The instance to block handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * An indefinite type that is a supertype of every tuple type, - * regardless of the number of items in the tuple. + * Blocks all handlers on an instance that match @func and @data. + * + * Returns: The number of handlers that matched. */ /** - * G_TYPE_FLAG_RESERVED_ID_BIT: + * g_signal_handlers_block_matched: + * @instance: The instance to block handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * A bit in the type number that's supposed to be left untouched. + * Blocks all handlers on an instance that match a certain selection criteria. + * The criteria mask is passed as an OR-ed combination of #GSignalMatchType + * flags, and the criteria values are passed as arguments. + * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC + * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. + * If no handlers were found, 0 is returned, the number of blocked handlers + * otherwise. + * + * Returns: The number of handlers that matched. */ /** - * g_type_next_base: - * @leaf_type: Descendant of @root_type and the type to be returned. - * @root_type: Immediate parent of the returned type. + * g_signal_handlers_disconnect_by_func: + * @instance: The instance to remove handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Given a @leaf_type and a @root_type which is contained in its - * anchestry, return the type that @root_type is the immediate parent - * of. In other words, this function determines the type that is - * derived directly from @root_type which is also a base class of - * be used to determine the types and order in which the leaf type is - * descended from the root type. + * Disconnects all handlers on an instance that match @func and @data. * - * Returns: Immediate child of @root_type and anchestor of @leaf_type. + * Returns: The number of handlers that matched. */ /** - * g_param_spec_char: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified + * g_signal_handlers_disconnect_matched: + * @instance: The instance to remove handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. + * Disconnects all handlers on an instance that match a certain + * selection criteria. The criteria mask is passed as an OR-ed + * combination of #GSignalMatchType flags, and the criteria values are + * passed as arguments. Passing at least one of the + * %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or + * %G_SIGNAL_MATCH_DATA match flags is required for successful + * matches. If no handlers were found, 0 is returned, the number of + * disconnected handlers otherwise. * - * Returns: a newly created parameter specification + * Returns: The number of handlers that matched. */ /** - * GConnectFlags: - * @G_CONNECT_AFTER: whether the handler should be called before or after the default handler of the signal. - * @G_CONNECT_SWAPPED: whether the instance and data should be swapped when calling the handler. + * g_signal_handlers_unblock_by_func: + * @instance: The instance to unblock handlers from. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * The connection flags are used to specify the behaviour of a signal's - * connection. + * Unblocks all handlers on an instance that match @func and @data. + * + * Returns: The number of handlers that matched. */ /** - * g_node_prev_sibling: - * @node: a #GNode + * g_signal_handlers_unblock_matched: + * @instance: The instance to unblock handlers from. + * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. + * @signal_id: Signal the handlers have to be connected to. + * @detail: Signal detail the handlers have to be connected to. + * @closure: The closure the handlers will invoke. + * @func: The C closure callback of the handlers (useless for non-C closures). + * @data: The closure data of the handlers' closures. * - * Gets the previous sibling of a #GNode. - * node or %NULL + * Unblocks all handlers on an instance that match a certain selection + * criteria. The criteria mask is passed as an OR-ed combination of + * #GSignalMatchType flags, and the criteria values are passed as arguments. + * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC + * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. + * If no handlers were found, 0 is returned, the number of unblocked handlers + * otherwise. The match criteria should not apply to any handlers that are + * not currently blocked. * - * Returns: the previous sibling of @node, or %NULL if @node is the first + * Returns: The number of handlers that matched. */ /** - * G_IS_PARAM_SPEC_BOOLEAN: - * @pspec: a valid #GParamSpec instance + * g_signal_has_handler_pending: + * @instance: the object whose signal handlers are sought. + * @signal_id: the signal id. + * @detail: the detail. + * @may_be_blocked: whether blocked handlers should count as match. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. + * Returns whether there are any handlers connected to @instance for the + * given signal id and detail. + * One example of when you might use this is when the arguments to the + * signal are difficult to compute. A class implementor may opt to not + * emit the signal if no one is attached anyway, thus saving the cost + * of building the arguments. + * otherwise. * - * Returns: %TRUE on success. + * Returns: %TRUE if a handler is connected to the signal, %FALSE */ /** - * GTranslateFunc: - * @str: the untranslated string - * @data: user data specified when installing the function, e.g. in g_option_group_set_translate_func() + * g_signal_list_ids: + * @itype: Instance or interface type. + * @n_ids: Location to store the number of signal ids for @itype. * - * The type of functions which are used to translate user-visible - * strings, for <option>--help</option> output. - * The returned string is owned by GLib and must not be freed. + * Lists the signals by id that a certain instance or interface type + * created. Further information about the signals can be acquired through + * g_signal_query(). * - * Returns: a translation of the string for the current locale. + * Returns: Newly allocated array of signal IDs. */ /** - * G_TYPE_CHECK_CLASS_TYPE: - * @g_class: Location of a #GTypeClass structure. - * @g_type: The type to be checked. + * g_signal_lookup: + * @name: the signal's name. + * @itype: the type that the signal operates on. * - * Checks if @g_class is a class structure of the type identified by - * This macro should only be used in type implementations. + * Given the name of the signal and the type of object it connects to, gets + * the signal's identifying integer. Emitting the signal by number is + * somewhat faster than using the name each time. + * Also tries the ancestors of the given type. + * See g_signal_new() for details on allowed signal names. * - * Returns: %TRUE on success. + * Returns: the signal's identifying number, or 0 if no signal was found. */ /** - * G_VARIANT_TYPE_BYTE: + * g_signal_name: + * @signal_id: the signal's identifying number. * - * The type of an integer value that can range from 0 to 255. + * Given the signal's identifier, finds its name. + * Two different signals may have the same name, if they have differing types. + * + * Returns: the signal name, or %NULL if the signal number was invalid. */ /** - * g_value_reset: - * @value: An initialized #GValue structure. + * g_signal_new: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_offset: The offset of the function pointer in the class structure for this type. Used to invoke a class method generically. Pass 0 to not associate a class method slot with this signal. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @n_params: the number of parameter types to follow. + * @...: a list of types, one for each parameter. * - * Clears the current value in @value and resets it to the default value - * (as if the value had just been initialized). + * Creates a new signal. (This is usually done in the class initializer.) + * A signal name consists of segments consisting of ASCII letters and + * digits, separated by either the '-' or '_' character. The first + * character of a signal name must be a letter. Names which violate these + * rules lead to undefined behaviour of the GSignal system. + * When registering a signal and looking up a signal, either separator can + * be used, but they cannot be mixed. + * If 0 is used for @class_offset subclasses cannot override the class handler + * in their <code>class_init</code> method by doing + * <code>super_class->signal_handler = my_signal_handler</code>. Instead they + * will have to use g_signal_override_class_handler(). * - * Returns: the #GValue structure that has been passed in + * Returns: the signal id */ /** - * g_type_module_register_enum: - * @module: a #GTypeModule - * @name: name for the type - * @const_static_values: an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * g_signal_new_class_handler: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_handler: a #GCallback which acts as class implementation of this signal. Used to invoke a class method generically. Pass %NULL to not associate a class method with this signal. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @n_params: the number of parameter types to follow. + * @...: a list of types, one for each parameter. * - * Looks up or registers an enumeration that is implemented with a particular - * type plugin. If a type with name @type_name was previously registered, - * the #GType identifier for the type is returned, otherwise the type - * is newly registered, and the resulting #GType identifier returned. - * As long as any instances of the type exist, the type plugin will - * not be unloaded. + * Creates a new signal. (This is usually done in the class initializer.) + * This is a variant of g_signal_new() that takes a C callback instead + * off a class offset for the signal's class handler. This function + * doesn't need a function pointer exposed in the class structure of + * an object definition, instead the function pointer is passed + * directly and can be overriden by derived classes with + * g_signal_override_class_closure() or + * g_signal_override_class_handler()and chained to with + * g_signal_chain_from_overridden() or + * g_signal_chain_from_overridden_handler(). + * See g_signal_new() for information about signal names. * - * Since: 2.6 - * Returns: the new or existing type ID + * Returns: the signal id + * Since: 2.18 */ /** - * G_IS_PARAM_SPEC_UCHAR: - * @pspec: a valid #GParamSpec instance + * g_signal_new_valist: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. + * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. + * @class_closure: The closure to invoke on signal emission; may be %NULL. + * @accumulator: the accumulator for this signal; may be %NULL. + * @accu_data: user data for the @accumulator. + * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. + * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. + * @n_params: the number of parameter types in @args. + * @args: va_list of #GType, one for each parameter. * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. + * Creates a new signal. (This is usually done in the class initializer.) + * See g_signal_new() for details on allowed signal names. * - * Returns: %TRUE on success. + * Returns: the signal id */ /** - * GTypeQuery: - * @type: the #GType value of the type. - * @type_name: the name of the type. - * @class_size: the size of the class structure. - * @instance_size: the size of the instance structure. + * g_signal_newv: + * @signal_name: the name for the signal + * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type + * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST + * @class_closure: The closure to invoke on signal emission; may be %NULL + * @accumulator: the accumulator for this signal; may be %NULL + * @accu_data: user data for the @accumulator + * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations + * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value + * @n_params: the length of @param_types + * @param_types: an array of types, one for each parameter * - * A structure holding information for a specific type. It is - * filled in by the g_type_query() function. + * Creates a new signal. (This is usually done in the class initializer.) + * See g_signal_new() for details on allowed signal names. + * + * Returns: the signal id + */ + + +/** + * g_signal_override_class_closure: + * @signal_id: the signal id + * @instance_type: the instance type on which to override the class closure for the signal. + * @class_closure: the closure. + * + * Overrides the class closure (i.e. the default handler) for the given signal + * for emissions on instances of @instance_type. @instance_type must be derived + * from the type to which the signal belongs. + * See g_signal_chain_from_overridden() and + * g_signal_chain_from_overridden_handler() for how to chain up to the + * parent class closure from inside the overridden one. + */ + + +/** + * g_signal_override_class_handler: + * @signal_name: the name for the signal + * @instance_type: the instance type on which to override the class handler for the signal. + * @class_handler: the handler. + * + * Overrides the class closure (i.e. the default handler) for the + * given signal for emissions on instances of @instance_type with + * callabck @class_handler. @instance_type must be derived from the + * type to which the signal belongs. + * See g_signal_chain_from_overridden() and + * g_signal_chain_from_overridden_handler() for how to chain up to the + * parent class closure from inside the overridden one. + * + * Since: 2.18 + */ + + +/** + * g_signal_parse_name: + * @detailed_signal: a string of the form "signal-name::detail". + * @itype: The interface/instance type that introduced "signal-name". + * @signal_id_p: Location to store the signal id. + * @detail_p: Location to store the detail quark. + * @force_detail_quark: %TRUE forces creation of a #GQuark for the detail. + * + * Internal function to parse a signal name into its @signal_id + * and @detail quark. + * + * Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. + */ + + +/** + * g_signal_query: + * @signal_id: The signal id of the signal to query information for. + * @query: A user provided structure that is filled in with constant values upon success. + * + * Queries the signal system for in-depth information about a + * specific signal. This function will fill in a user-provided + * structure to hold signal-specific information. If an invalid + * signal id is passed in, the @signal_id member of the #GSignalQuery + * is 0. All members filled into the #GSignalQuery structure should + * be considered constant and have to be left untouched. + */ + + +/** + * g_signal_remove_emission_hook: + * @signal_id: the id of the signal + * @hook_id: the id of the emission hook, as returned by g_signal_add_emission_hook() + * + * Deletes an emission hook. + */ + + +/** + * g_signal_stop_emission: + * @instance: the object whose signal handlers you wish to stop. + * @signal_id: the signal identifier, as returned by g_signal_lookup(). + * @detail: the detail which the signal was emitted with. + * + * Stops a signal's current emission. + * This will prevent the default method from running, if the signal was + * %G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" + * flag). + * Prints a warning if used on a signal which isn't being emitted. */ @@ -8876,410 +8773,500 @@ /** - * g_object_interface_list_properties: - * @g_iface: any interface vtable for the interface, or the default vtable for the interface - * @n_properties_p: (out): location to store number of properties returned. + * g_source_set_closure: + * @source: the source + * @closure: a #GClosure * - * Lists the properties of an interface.Generally, the interface - * vtable passed in as @g_iface will be the default vtable from - * g_type_default_interface_ref(), or, if you know the interface has - * already been loaded, g_type_default_interface_peek(). - * pointer to an array of pointers to #GParamSpec - * structures. The paramspecs are owned by GLib, but the - * array should be freed with g_free() when you are done with - * it. + * Set the callback for a source as a #GClosure. + * If the source is not one of the standard GLib types, the @closure_callback + * and @closure_marshal fields of the #GSourceFuncs structure must have been + * filled in with pointers to appropriate functions. + */ + + +/** + * g_source_set_dummy_callback: + * @source: the source * - * Since: 2.4 - * Returns: (array length=n_properties_p) (transfer container): a + * Sets a dummy callback for @source. The callback will do nothing, and + * if the source expects a #gboolean return value, it will return %TRUE. + * (If the source expects any other type of return value, it will return + * a 0/%NULL value; whatever g_value_init() initializes a #GValue to for + * that type.) + * If the source is not one of the standard GLib types, the + * structure must have been filled in with pointers to appropriate + * functions. */ /** - * g_signal_connect_object: (skip) - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @gobject: the object to pass as data to @c_handler. - * @connect_flags: a combination of #GConnnectFlags. + * g_strdup_value_contents: + * @value: #GValue which contents are to be described. * - * This is similar to g_signal_connect_data(), but uses a closure which - * ensures that the @gobject stays alive during the call to @c_handler - * by temporarily adding a reference count to @gobject. - * Note that there is a bug in GObject that makes this function - * much less useful than it might seem otherwise. Once @gobject is - * disposed, the callback will no longer be called, but, the signal - * handler is <emphasis>not</emphasis> currently disconnected. If the - * matter, since the signal will automatically be removed, but - * if @instance persists, then the signal handler will leak. You - * should not remove the signal yourself because in a future versions of - * GObject, the handler <emphasis>will</emphasis> automatically - * be disconnected. - * It's possible to work around this problem in a way that will - * continue to work with future versions of GObject by checking - * that the signal handler is still connected before disconnected it: - * <informalexample><programlisting> - * if (g_signal_handler_is_connected (instance, id)) - * g_signal_handler_disconnect (instance, id); - * </programlisting></informalexample> + * Return a newly allocated string, which describes the contents of a + * #GValue. The main purpose of this function is to describe #GValue + * contents for debugging output, the way in which the contents are + * described may change between different GLib versions. * - * Returns: the handler id. + * Returns: Newly allocated string. */ /** - * g_signal_accumulator_first_wins: - * @ihint: standard #GSignalAccumulator parameter - * @return_accu: standard #GSignalAccumulator parameter - * @handler_return: standard #GSignalAccumulator parameter - * @dummy: standard #GSignalAccumulator parameter + * g_try_new: + * @struct_type: the type of the elements to allocate + * @n_structs: the number of elements to allocate * - * A predefined #GSignalAccumulator for signals intended to be used as a - * hook for application code to provide a particular value. Usually - * only one such value is desired and multiple handlers for the same - * signal don't make much sense (except for the case of the default - * handler defined in the class structure, in which case you will - * usually want the signal connection to override the class handler). - * This accumulator will use the return value from the first signal - * handler that is run as the return value for the signal and not run + * Attempts to allocate @n_structs elements of type @struct_type, and returns + * %NULL on failure. Contrast with g_new(), which aborts the program on failure. + * The returned pointer is cast to a pointer to the given type. + * The function returns %NULL when @n_structs is 0 of if an overflow occurs. * - * Any further handlers (ie: the first handler "wins"). - * Returns: standard #GSignalAccumulator result - * Since: 2.28 + * Since: 2.8 + * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * g_new: + * g_try_new0: * @struct_type: the type of the elements to allocate * @n_structs: the number of elements to allocate * - * Allocates @n_structs elements of type @struct_type. + * Attempts to allocate @n_structs elements of type @struct_type, initialized + * to 0's, and returns %NULL on failure. Contrast with g_new0(), which aborts + * the program on failure. * The returned pointer is cast to a pointer to the given type. - * If @n_structs is 0 it returns %NULL. - * Care is taken to avoid overflow when calculating the size of the allocated block. - * Since the returned pointer is already casted to the right type, - * it is normally unnecessary to cast it explicitly, and doing - * so might hide memory allocation errors. + * The function returns %NULL when @n_structs is 0 of if an overflow occurs. * + * Since: 2.8 * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type */ /** - * G_IS_PARAM_SPEC_GTYPE: - * @pspec: a #GParamSpec + * g_try_renew: + * @struct_type: the type of the elements to allocate + * @mem: the currently allocated memory + * @n_structs: the number of elements to allocate * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. + * Attempts to reallocate the memory pointed to by @mem, so that it now has + * space for @n_structs elements of type @struct_type, and returns %NULL on + * failure. Contrast with g_renew(), which aborts the program on failure. + * It returns the new address of the memory, which may have been moved. + * The function returns %NULL if an overflow occurs. * - * Since: 2.10 - * Returns: %TRUE on success. + * Since: 2.8 + * Returns: a pointer to the new allocated memory, cast to a pointer to @struct_type */ /** - * G_IS_PARAM_SPEC_CHAR: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. + * g_type_add_class_cache_func: (skip) + * @cache_data: data to be passed to @cache_func + * @cache_func: a #GTypeClassCacheFunc * - * Returns: %TRUE on success. + * Adds a #GTypeClassCacheFunc to be called before the reference count of a + * class goes from one to zero. This can be used to prevent premature class + * destruction. All installed #GTypeClassCacheFunc functions will be chained + * until one of them returns %TRUE. 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 classes are routed through the same #GTypeClassCacheFunc + * chain. */ /** - * G_TYPE_BYTE_ARRAY: + * g_type_add_class_private: + * @class_type: GType of an classed type. + * @private_size: size of private structure. * - * The #GType for a boxed type holding a #GByteArray reference. + * Registers a private class structure for a classed type; + * when the class is allocated, the private structures for + * the class and all of its parent types are allocated + * sequentially in the same memory block as the public + * structures. This function should be called in the + * type's get_type() function after the type is registered. + * The private structure can be retrieved using the + * G_TYPE_CLASS_GET_PRIVATE() macro. * - * Since: 2.22 + * Since: 2.24 */ /** - * GValueTransform: - * @src_value: Source value. - * @dest_value: Target value. + * g_type_add_interface_check: (skip) + * @check_data: data to pass to @check_func + * @check_func: function to be called after each interface is initialized. * - * The type of value transformation functions which can be registered with - * g_value_register_transform_func(). + * Adds a function to be called after an interface vtable is + * initialized for any class (i.e. after the @interface_init member of + * #GInterfaceInfo has been called). + * This function is useful when you want to check an invariant that + * depends on the interfaces of a class. For instance, the + * implementation of #GObject uses this facility to check that an + * object implements all of the properties that are defined on its + * interfaces. + * + * Since: 2.4 */ /** - * 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 + * g_type_add_interface_dynamic: + * @instance_type: the #GType value of an instantiable type. + * @interface_type: the #GType value of an interface type. + * @plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from. * - * A marshaller for a #GCClosure with a callback of type - * <literal>void (*callback) (gpointer instance, guint arg1, gpointer user_data)</literal>. + * Adds the dynamic @interface_type to @instantiable_type. The information + * contained in the #GTypePlugin structure pointed to by @plugin + * is used to manage the relationship. */ /** - * G_IS_PARAM_SPEC_UNICHAR: - * @pspec: a valid #GParamSpec instance - * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. + * g_type_add_interface_static: + * @instance_type: #GType value of an instantiable type. + * @interface_type: #GType value of an interface type. + * @info: The #GInterfaceInfo structure for this (@instance_type, @interface_type) combination. * - * Returns: %TRUE on success. + * Adds the static @interface_type to @instantiable_type. The information + * contained in the #GTypeInterfaceInfo structure pointed to by @info + * is used to manage the relationship. */ /** - * GIconv: + * g_type_check_instance: + * @instance: A valid #GTypeInstance structure. + * @Returns: #TRUE if @instance is valid, #FALSE otherwise. * - * The <structname>GIConv</structname> struct wraps an - * iconv() conversion descriptor. It contains private data - * and should only be accessed using the following functions. + * Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() + * macro. */ /** - * G_SIGNAL_TYPE_STATIC_SCOPE: + * g_type_children: + * @type: The parent type. + * @n_children: (out) (allow-none): Optional #guint pointer to contain the number of child types. * - * This macro flags signal argument types for which the signal system may - * assume that instances thereof remain persistent across all signal emissions - * they are used in. This is only useful for non ref-counted, value-copy types. - * To flag a signal argument in this way, add - * <literal>| G_SIGNAL_TYPE_STATIC_SCOPE</literal> to the corresponding argument - * of g_signal_new(). - * |[ - * g_signal_new ("size_request", - * G_TYPE_FROM_CLASS (gobject_class), - * G_SIGNAL_RUN_FIRST, - * G_STRUCT_OFFSET (GtkWidgetClass, size_request), - * NULL, NULL, - * _gtk_marshal_VOID__BOXED, - * G_TYPE_NONE, 1, - * GTK_TYPE_REQUISITION | G_SIGNAL_TYPE_STATIC_SCOPE); - * ]| + * Return a newly allocated and 0-terminated array of type IDs, listing the + * child types of @type. The return value has to be g_free()ed after use. + * and 0-terminated array of child types. + * + * Returns: (array length=n_children) (transfer full): Newly allocated */ /** - * g_enum_complete_type_info: - * @g_enum_type: the type identifier of the type being completed - * @info: the #GTypeInfo struct to be filled in - * @const_values: An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. + * g_type_class_add_private: + * @g_class: class structure for an instantiatable type + * @private_size: size of private structure. * - * This function is meant to be called from the complete_type_info() - * function of a #GTypePlugin implementation, as in the following - * example: + * Registers a private structure for an instantiatable type. + * When an object is allocated, the private structures for + * the type and all of its parent types are allocated + * sequentially in the same memory block as the public + * structures. + * Note that the accumulated size of the private structures of + * a type and all its parent types cannot excced 64kB. + * This function should be called in the type's class_init() function. + * The private structure can be retrieved using the + * G_TYPE_INSTANCE_GET_PRIVATE() macro. + * The following example shows attaching a private structure + * <structname>MyObjectPrivate</structname> to an object + * <structname>MyObject</structname> defined in the standard GObject + * fashion. + * type's class_init() function. * |[ + * typedef struct _MyObject MyObject; + * typedef struct _MyObjectPrivate MyObjectPrivate; + * struct _MyObject { + * GObject parent; + * MyObjectPrivate *priv; + * }; + * struct _MyObjectPrivate { + * int some_field; + * }; * static void - * my_enum_complete_type_info (GTypePlugin *plugin, - * GType g_type, - * GTypeInfo *info, - * GTypeValueTable *value_table) + * my_object_class_init (MyObjectClass *klass) * { - * static const GEnumValue values[] = { - * { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" }, - * { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }, - * { 0, NULL, NULL } - * }; - * g_enum_complete_type_info (type, info, values); + * g_type_class_add_private (klass, sizeof (MyObjectPrivate)); + * } + * static void + * my_object_init (MyObject *my_object) + * { + * my_object->priv = G_TYPE_INSTANCE_GET_PRIVATE (my_object, + * MY_TYPE_OBJECT, + * MyObjectPrivate); + * } + * static int + * my_object_get_some_field (MyObject *my_object) + * { + * MyObjectPrivate *priv = my_object->priv; + * return priv->some_field; * } * ]| + * + * Since: 2.4 */ /** - * G_TYPE_ULONG: + * g_type_class_peek: + * @type: Type ID of a classed type. * - * The fundamental type corresponding to #gulong. + * This function is essentially the same as g_type_class_ref(), except that + * the classes reference count isn't incremented. As a consequence, this function + * may return %NULL if the class of the type passed in does not currently + * exist (hasn't been referenced before). + * structure for the given type ID or %NULL if the class does not + * currently exist. + * + * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass */ /** - * G_TYPE_IS_VALUE: - * @type: A #GType value. + * g_type_class_peek_parent: + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to retrieve the parent class for. * - * 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. + * This is a convenience function often needed in class initializers. + * It returns the class structure of the immediate parent type of the + * class passed in. Since derived classes hold a reference count on + * their parent classes as long as they are instantiated, the returned + * class will always exist. This function is essentially equivalent + * to: + * <programlisting> + * g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))); + * </programlisting> + * of @g_class. * - * Returns: Whether @type is suitable as a #GValue type. + * Returns: (type GObject.TypeClass) (transfer none): The parent class */ /** - * GParamSpecEnum: - * @parent_instance: private #GParamSpec portion - * @enum_class: the #GEnumClass for the enum - * @default_value: default value for the property specified + * g_type_class_peek_static: + * @type: Type ID of a classed type. * - * A #GParamSpec derived structure that contains the meta data for enum - * properties. + * A more efficient version of g_type_class_peek() which works only for + * static types. + * structure for the given type ID or %NULL if the class does not + * currently exist or is dynamically loaded. + * + * Since: 2.4 + * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass */ /** - * G_VALUE_COLLECT_INIT: - * @value: a #GValue return location. @value must contain only 0 bytes. - * @_value_type: the #GType to use for @value. - * @var_args: the va_list variable; it may be evaluated multiple times - * @flags: flags which are passed on to the collect_value() function of the #GTypeValueTable of @value. - * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails + * g_type_class_ref: + * @type: Type ID of a classed type. * - * Collects a variable argument value from a va_list. We have to - * implement the varargs collection as a macro, because on some systems - * va_list variables cannot be passed by reference. + * Increments the reference count of the class structure belonging to + * exist already. + * structure for the given type ID. * - * Since: 2.24 + * Returns: (type GObject.TypeClass) (transfer none): The #GTypeClass */ /** - * g_type_fundamental_next: + * g_type_class_unref: + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. * - * Returns the next free fundamental type id which can be used to - * register a new fundamental type with g_type_register_fundamental(). - * The returned type ID represents the highest currently registered - * fundamental type identifier. - * or 0 if the type system ran out of fundamental type IDs. + * Decrements the reference count of the class structure being passed in. + * Once the last reference count of a class has been released, classes + * may be finalized by the type system, so further dereferencing of a + * class pointer after g_type_class_unref() are invalid. + */ + + +/** + * g_type_class_unref_uncached: (skip) + * @g_class: (type GObject.TypeClass): The #GTypeClass structure to unreference. * - * Returns: The nextmost fundamental type ID to be registered, + * A variant of g_type_class_unref() for use in #GTypeClassCacheFunc + * implementations. It unreferences a class without consulting the chain + * of #GTypeClassCacheFunc<!-- -->s, avoiding the recursion which would occur + * otherwise. */ /** - * g_value_array_append: - * @value_array: #GValueArray to add an element to - * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL + * g_type_create_instance: (skip) + * @type: An instantiatable type to create an instance for. * - * Insert a copy of @value as last element of @value_array. If @value is - * %NULL, an uninitialized value is appended. + * Creates and initializes an instance of @type if @type is valid and + * can be instantiated. The type system only performs basic allocation + * happen through functions supplied by the type's fundamental type + * implementation. So use of g_type_create_instance() is reserved for + * implementators of fundamental types only. E.g. instances of the + * #GObject hierarchy should be created via g_object_new() and + * <emphasis>never</emphasis> directly through + * g_type_create_instance() which doesn't handle things like singleton + * use this function, unless you're implementing a fundamental + * type. Also language bindings should <emphasis>not</emphasis> use + * this function but g_object_new() instead. + * treatment by the fundamental type implementation. * - * Returns: (transfer none): the #GValueArray passed in as @value_array + * And structure setups for instances: actual instance creation should + * Objects or object construction. note: Do <emphasis>not</emphasis> + * Returns: An allocated and initialized instance, subject to further */ /** - * GStrv: + * g_type_default_interface_peek: + * @g_type: an interface type * - * A C representable type name for #G_TYPE_STRV. + * If the interface type @g_type is currently in use, returns its + * default interface vtable. + * vtable for the interface, or %NULL if the type is not currently in + * use. + * + * Since: 2.4 + * Returns: (type GObject.TypeInterface) (transfer none): the default */ /** - * G_TYPE_FROM_INTERFACE: - * @g_iface: Location of a valid #GTypeInterface structure. + * g_type_default_interface_ref: + * @g_type: an interface type * - * Get the type identifier from a given @interface structure. - * This macro should only be used in type implementations. + * Increments the reference count for the interface type @g_type, + * and returns the default interface vtable for the type. + * If the type is not currently in use, then the default vtable + * for the type will be created and initalized by calling + * the base interface init and default vtable init functions for + * the type (the @<structfield>base_init</structfield> + * and <structfield>class_init</structfield> members of #GTypeInfo). + * Calling g_type_default_interface_ref() is useful when you + * want to make sure that signals and properties for an interface + * have been installed. + * vtable for the interface; call g_type_default_interface_unref() + * when you are done using the interface. * - * Returns: the #GType + * Since: 2.4 + * Returns: (type GObject.TypeInterface) (transfer none): the default */ /** - * G_VALUE_HOLDS_BOXED: - * @value: a valid #GValue structure + * g_type_default_interface_unref: + * @g_iface: (type GObject.TypeInterface): the default vtable structure for a interface, as returned by g_type_default_interface_ref() * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. + * Decrements the reference count for the type corresponding to the + * interface default vtable @g_iface. If the type is dynamic, then + * when no one is using the interface and all references have + * been released, the finalize function for the interface's default + * vtable (the <structfield>class_finalize</structfield> member of + * #GTypeInfo) will be called. * - * Returns: %TRUE on success. + * Since: 2.4 */ /** - * G_TYPE_PARAM_BOXED: + * g_type_depth: + * @type: A #GType value. * - * The #GType of #GParamSpecBoxed. + * Returns the length of the ancestry of the passed in type. This + * includes the type itself, so that e.g. a fundamental type has depth 1. + * + * Returns: The depth of @type. */ /** - * g_closure_remove_invalidate_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func - * @notify_func: the callback function to remove + * g_type_free_instance: + * @instance: an instance of a type. * - * Removes an invalidation notifier. - * Notice that notifiers are automatically removed after they are run. + * Frees an instance of a type, returning it to the instance pool for + * the type, if there is one. + * Like g_type_create_instance(), this function is reserved for + * implementors of fundamental types. */ /** - * g_value_get_string: - * @value: a valid #GValue of type %G_TYPE_STRING + * g_type_from_name: + * @name: Type name to lookup. * - * Get the contents of a %G_TYPE_STRING #GValue. + * Lookup the type ID from a given type name, returning 0 if no type + * has been registered under this name (this is the preferred method + * to find out by name whether a specific type has been registered + * yet). * - * Returns: string content of @value + * Returns: Corresponding type ID or 0. */ /** - * G_FLAGS_CLASS: - * @class: a valid #GFlagsClass + * g_type_fundamental: + * @type_id: valid type ID * - * Casts a derived #GFlagsClass structure into a #GFlagsClass structure. + * Internal function, used to extract the fundamental type ID portion. + * use G_TYPE_FUNDAMENTAL() instead. + * + * Returns: fundamental type ID */ /** - * g_closure_add_marshal_guards: (skip) - * @closure: a #GClosure - * @pre_marshal_data: data to pass to @pre_marshal_notify - * @pre_marshal_notify: a function to call before the closure callback - * @post_marshal_data: data to pass to @post_marshal_notify - * @post_marshal_notify: a function to call after the closure callback + * g_type_fundamental_next: * - * 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. + * Returns the next free fundamental type id which can be used to + * register a new fundamental type with g_type_register_fundamental(). + * The returned type ID represents the highest currently registered + * fundamental type identifier. + * or 0 if the type system ran out of fundamental type IDs. + * + * Returns: The nextmost fundamental type ID to be registered, */ /** - * g_value_set_string_take_ownership: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: duplicated unowned string to be set + * g_type_get_plugin: + * @type: The #GType to retrieve the plugin for. * - * This is an internal function introduced mainly for C marshallers. + * Returns the #GTypePlugin structure for @type or + * %NULL if @type does not have a #GTypePlugin structure. + * dynamic type, %NULL otherwise. * - * Deprecated: 2.4: Use g_value_take_string() instead. + * Returns: (transfer none): The corresponding plugin if @type is a */ /** - * g_main_quit: - * @loop: a #GMainLoop + * g_type_get_qdata: + * @type: a #GType + * @quark: a #GQuark id to identify the data * - * Stops the #GMainLoop. - * If g_main_run() was called to run the #GMainLoop, it will now return. + * Obtains data which has previously been attached to @type + * with g_type_set_qdata(). * - * Deprecated: 2.2: Use g_main_loop_quit() instead + * Returns: (transfer none): the data, or %NULL if no data was found */ /** - * GOptionError: - * @G_OPTION_ERROR_UNKNOWN_OPTION: An option was not known to the parser. This error will only be reported, if the parser hasn't been instructed to ignore unknown options, see g_option_context_set_ignore_unknown_options(). - * @G_OPTION_ERROR_BAD_VALUE: A value couldn't be parsed. - * @G_OPTION_ERROR_FAILED: A #GOptionArgFunc callback failed. + * g_type_init: * - * Error codes returned by option parsing. + * Prior to any use of the type system, g_type_init() has to be called + * to initialize the type system and assorted other code portions + * (such as the various fundamental type implementations or the signal + * system). + * Since version 2.24 this also initializes the thread system */ /** - * g_type_interface_peek: - * @instance_class: (type GObject.TypeClass): A #GTypeClass structure. - * @iface_type: An interface ID which this class conforms to. - * - * Returns the #GTypeInterface structure of an interface to which the - * passed in class conforms. - * structure of iface_type if implemented by @instance_class, %NULL - * otherwise + * g_type_init_with_debug_flags: + * @debug_flags: Bitwise combination of #GTypeDebugFlags values for debugging purposes. * - * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface + * Similar to g_type_init(), but additionally sets debug flags. */ @@ -9296,252 +9283,302 @@ /** - * GClosureMarshal: - * @closure: the #GClosure to which the marshaller belongs - * @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 #GValue<!-- -->s 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() + * g_type_interface_get_plugin: + * @instance_type: the #GType value of an instantiatable type. + * @interface_type: the #GType value of an interface type. * - * The type used for marshaller functions. - */ - - -/** - * g_signal_override_class_closure: - * @signal_id: the signal id - * @instance_type: the instance type on which to override the class closure for the signal. - * @class_closure: the closure. + * Returns the #GTypePlugin structure for the dynamic interface + * have a #GTypePlugin structure. See g_type_add_interface_dynamic(). + * interface @interface_type of @instance_type. * - * Overrides the class closure (i.e. the default handler) for the given signal - * for emissions on instances of @instance_type. @instance_type must be derived - * from the type to which the signal belongs. - * See g_signal_chain_from_overridden() and - * g_signal_chain_from_overridden_handler() for how to chain up to the - * parent class closure from inside the overridden one. + * Returns: (transfer none): the #GTypePlugin for the dynamic */ /** - * G_TYPE_POINTER: + * g_type_interface_peek: + * @instance_class: (type GObject.TypeClass): A #GTypeClass structure. + * @iface_type: An interface ID which this class conforms to. * - * The fundamental type corresponding to #gpointer. + * Returns the #GTypeInterface structure of an interface to which the + * passed in class conforms. + * structure of iface_type if implemented by @instance_class, %NULL + * otherwise + * + * Returns: (type GObject.TypeInterface) (transfer none): The GTypeInterface */ /** - * g_value_set_boxed_take_ownership: - * @value: a valid #GValue of %G_TYPE_BOXED derived type - * @v_boxed: duplicated unowned boxed value to be set + * g_type_interface_peek_parent: + * @g_iface: (type GObject.TypeInterface): A #GTypeInterface structure. * - * This is an internal function introduced mainly for C marshallers. + * Returns the corresponding #GTypeInterface structure of the parent type + * of the instance type to which @g_iface belongs. This is useful when + * deriving the implementation of an interface from the parent type and + * then possibly overriding some methods. + * corresponding #GTypeInterface structure of the parent type of the + * instance type to which @g_iface belongs, or %NULL if the parent + * type doesn't conform to the interface. * - * Deprecated: 2.4: Use g_value_take_boxed() instead. + * Returns: (transfer none) (type GObject.TypeInterface): The */ /** - * GSource: + * g_type_interface_prerequisites: + * @interface_type: an interface type + * @n_prerequisites: (out) (allow-none): location to return the number of prerequisites, or %NULL * - * The <structname>GSource</structname> struct is an opaque data type - * representing an event source. + * Returns the prerequisites of an interfaces type. + * newly-allocated zero-terminated array of #GType containing + * the prerequisites of @interface_type + * + * Since: 2.2 + * Returns: (array length=n_prerequisites) (transfer full): a */ /** - * g_hash_table_freeze: - * @hash_table: a #GHashTable + * g_type_interfaces: + * @type: The type to list interface types for. + * @n_interfaces: (out) (allow-none): Optional #guint pointer to contain the number of interface types. * - * This function is deprecated and will be removed in the next major - * release of GLib. It does nothing. + * Return a newly allocated and 0-terminated array of type IDs, listing the + * interface types that @type conforms to. The return value has to be + * g_free()ed after use. + * allocated and 0-terminated array of interface types. + * + * Returns: (array length=n_interfaces) (transfer full): Newly */ /** - * G_OBJECT_CLASS_TYPE: - * @class: a valid #GObjectClass + * g_type_is_a: + * @type: Type to check anchestry for. + * @is_a_type: Possible anchestor of @type or interface @type could conform to. * - * Get the type id of a class structure. + * If @is_a_type is a derivable type, check whether @type is a + * descendant of @is_a_type. If @is_a_type is an interface, check + * whether @type conforms to it. * - * Returns: Type id of @class. + * Returns: %TRUE if @type is_a @is_a_type holds true. */ /** - * G_PRIORITY_HIGH: + * g_type_module_add_interface: + * @module: a #GTypeModule + * @instance_type: type to which to add the interface. + * @interface_type: interface type to add + * @interface_info: type information structure * - * Use this for high priority event sources. - * It is not used within GLib or GTK+. + * Registers an additional interface for a type, whose interface lives + * in the given type plugin. If the interface was already registered + * for the type in this plugin, nothing will be done. + * As long as any instances of the type exist, the type plugin will + * not be unloaded. */ /** - * G_TYPE_RESERVED_USER_FIRST: + * g_type_module_register_enum: + * @module: a #GTypeModule + * @name: name for the type + * @const_static_values: an array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. * - * First available fundamental type number to create new fundamental - * type id with G_TYPE_MAKE_FUNDAMENTAL(). + * Looks up or registers an enumeration that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * As long as any instances of the type exist, the type plugin will + * not be unloaded. + * + * Since: 2.6 + * Returns: the new or existing type ID */ /** - * G_TYPE_IO_CHANNEL: + * g_type_module_register_flags: + * @module: a #GTypeModule + * @name: name for the type + * @const_static_values: an array of #GFlagsValue structs for the possible flags values. The array is terminated by a struct with all members being 0. * - * The #GType for #GIOChannel. + * Looks up or registers a flags type that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * As long as any instances of the type exist, the type plugin will + * not be unloaded. + * + * Since: 2.6 + * Returns: the new or existing type ID */ /** - * GRegexCompileFlags: - * @G_REGEX_CASELESS: Letters in the pattern match both upper- and lowercase letters. This option can be changed within a pattern by a "(?i)" option setting. - * @G_REGEX_MULTILINE: By default, GRegex treats the strings as consisting of a single line of characters (even if it actually contains newlines). The "start of line" metacharacter ("^") matches only at the start of the string, while the "end of line" metacharacter ("$") matches only at the end of the string, or before a terminating newline (unless #G_REGEX_DOLLAR_ENDONLY is set). When #G_REGEX_MULTILINE is set, the "start of line" and "end of line" constructs match immediately following or immediately before any newline in the string, respectively, as well as at the very start and end. This can be changed within a pattern by a "(?m)" option setting. - * @G_REGEX_DOTALL: A dot metacharater (".") in the pattern matches all characters, including newlines. Without it, newlines are excluded. This option can be changed within a pattern by a ("?s") option setting. - * @G_REGEX_EXTENDED: Whitespace data characters in the pattern are totally ignored except when escaped or inside a character class. Whitespace does not include the VT character (code 11). In addition, characters between an unescaped "#" outside a character class and the next newline character, inclusive, are also ignored. This can be changed within a pattern by a "(?x)" option setting. - * @G_REGEX_ANCHORED: The pattern is forced to be "anchored", that is, it is constrained to match only at the first matching point in the string that is being searched. This effect can also be achieved by appropriate constructs in the pattern itself such as the "^" metacharater. - * @G_REGEX_DOLLAR_ENDONLY: A dollar metacharacter ("$") in the pattern matches only at the end of the string. Without this option, a dollar also matches immediately before the final character if it is a newline (but not before any other newlines). This option is ignored if #G_REGEX_MULTILINE is set. - * @G_REGEX_UNGREEDY: Inverts the "greediness" of the quantifiers so that they are not greedy by default, but become greedy if followed by "?". It can also be set by a "(?U)" option setting within the pattern. - * @G_REGEX_RAW: Usually strings must be valid UTF-8 strings, using this flag they are considered as a raw sequence of bytes. - * @G_REGEX_NO_AUTO_CAPTURE: Disables the use of numbered capturing parentheses in the pattern. Any opening parenthesis that is not followed by "?" behaves as if it were followed by "?:" but named parentheses can still be used for capturing (and they acquire numbers in the usual way). - * @G_REGEX_OPTIMIZE: Optimize the regular expression. If the pattern will be used many times, then it may be worth the effort to optimize it to improve the speed of matches. - * @G_REGEX_DUPNAMES: Names used to identify capturing subpatterns need not be unique. This can be helpful for certain types of pattern when it is known that only one instance of the named subpattern can ever be matched. - * @G_REGEX_NEWLINE_CR: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\r'. - * @G_REGEX_NEWLINE_LF: Usually any newline character is recognized, if this option is set, the only recognized newline character is '\n'. - * @G_REGEX_NEWLINE_CRLF: Usually any newline character is recognized, if this option is set, the only recognized newline character sequence is '\r\n'. + * g_type_module_register_type: + * @module: a #GTypeModule + * @parent_type: the type for the parent class + * @type_name: name for the type + * @type_info: type information structure + * @flags: flags field providing details about the type * - * Flags specifying compile-time options. + * Looks up or registers a type that is implemented with a particular + * type plugin. If a type with name @type_name was previously registered, + * the #GType identifier for the type is returned, otherwise the type + * is newly registered, and the resulting #GType identifier returned. + * When reregistering a type (typically because a module is unloaded + * then reloaded, and reinitialized), @module and @parent_type must + * be the same as they were previously. + * As long as any instances of the type exist, the type plugin will + * not be unloaded. * - * Since: 2.14 + * Returns: the new or existing type ID */ /** - * GParamSpecValueArray: - * @parent_instance: private #GParamSpec portion - * @element_spec: a #GParamSpec describing the elements contained in arrays of this property, may be %NULL - * @fixed_n_elements: if greater than 0, arrays of this property will always have this many elements + * g_type_module_set_name: + * @module: a #GTypeModule. + * @name: a human-readable name to use in error messages. * - * A #GParamSpec derived structure that contains the meta data for #GValueArray properties. + * Sets the name for a #GTypeModule */ /** - * G_PARAM_SPEC_DOUBLE: - * @pspec: a valid #GParamSpec instance + * g_type_module_unuse: + * @module: a #GTypeModule * - * Cast a #GParamSpec instance into a #GParamSpecDouble. + * Decreases the use count of a #GTypeModule by one. If the + * result is zero, the module will be unloaded. (However, the + * #GTypeModule will not be freed, and types associated with the + * #GTypeModule are not unregistered. Once a #GTypeModule is + * initialized, it must exist forever.) */ /** - * G_TYPE_LONG: + * g_type_module_use: + * @module: a #GTypeModule * - * The fundamental type corresponding to #glong. + * Increases the use count of a #GTypeModule by one. If the + * use count was zero before, the plugin will be loaded. + * If loading the plugin fails, the use count is reset to + * its prior value. + * loading the plugin failed. + * + * Returns: %FALSE if the plugin needed to be loaded and */ /** - * G_VARIANT_TYPE_UINT16: + * g_type_name: + * @type: Type to return name for. * - * The type of an integer value that can range from 0 to 65535. - * There were about this many people living in Toronto in the 1870s. + * Get the unique name that is assigned to a type ID. Note that this + * function (like all other GType API) cannot cope with invalid type + * IDs. %G_TYPE_INVALID may be passed to this function, as may be any + * other validly registered type ID, but randomized type IDs should + * not be passed in and will most likely lead to a crash. + * + * Returns: Static type name or %NULL. */ /** - * g_param_spec_internal: (skip) - * @param_type: the #GType for the property; must be derived from #G_TYPE_PARAM - * @name: the canonical name of the property - * @nick: the nickname of the property - * @blurb: a short description of the property - * @flags: a combination of #GParamFlags + * g_type_next_base: + * @leaf_type: Descendant of @root_type and the type to be returned. + * @root_type: Immediate parent of the returned type. * - * Creates a new #GParamSpec instance. - * A property name consists of segments consisting of ASCII letters and - * digits, separated by either the '-' or '_' character. The first - * character of a property name must be a letter. Names which violate these - * rules lead to undefined behaviour. - * When creating and looking up a #GParamSpec, either separator can be - * used, but they cannot be mixed. Using '-' is considerably more - * efficient and in fact required when using property names as detail - * strings for signals. - * Beyond the name, #GParamSpec<!-- -->s have two more descriptive - * strings associated with them, the @nick, which should be suitable - * for use as a label for the property in a property editor, and the - * e.g. a tooltip. The @nick and @blurb should ideally be localized. + * Given a @leaf_type and a @root_type which is contained in its + * anchestry, return the type that @root_type is the immediate parent + * of. In other words, this function determines the type that is + * derived directly from @root_type which is also a base class of + * be used to determine the types and order in which the leaf type is + * descended from the root type. * - * Returns: a newly allocated #GParamSpec instance + * Returns: Immediate child of @root_type and anchestor of @leaf_type. */ /** - * g_value_set_ulong: - * @value: a valid #GValue of type %G_TYPE_ULONG - * @v_ulong: unsigned long integer value to be set + * g_type_parent: + * @type: The derived type. * - * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. + * Return the direct parent type of the passed in type. If the passed + * in type has no parent, i.e. is a fundamental type, 0 is returned. + * + * Returns: The parent type. */ /** - * GParamSpecBoxed: - * @parent_instance: private #GParamSpec portion + * g_type_plugin_complete_interface_info: + * @plugin: the #GTypePlugin + * @instance_type: the #GType of an instantiable type to which the interface is added + * @interface_type: the #GType of the interface whose info is completed + * @info: the #GInterfaceInfo to fill in * - * A #GParamSpec derived structure that contains the meta data for boxed properties. + * Calls the @complete_interface_info function from the + * #GTypePluginClass of @plugin. There should be no need to use this + * function outside of the GObject type system itself. */ /** - * G_OBJECT_GET_CLASS: - * @object: a #GObject instance. - * - * Get the class structure associated to a #GObject instance. + * g_type_plugin_complete_type_info: + * @plugin: a #GTypePlugin + * @g_type: the #GType whose info is completed + * @info: the #GTypeInfo struct to fill in + * @value_table: the #GTypeValueTable to fill in * - * Returns: pointer to object class structure. + * Calls the @complete_type_info function from the #GTypePluginClass of @plugin. + * There should be no need to use this function outside of the GObject + * type system itself. */ /** - * g_param_spec_get_redirect_target: - * @pspec: a #GParamSpec - * - * If the paramspec redirects operations to another paramspec, - * returns that paramspec. Redirect is used typically for - * providing a new implementation of a property in a derived - * type while preserving all the properties from the parent - * type. Redirection is established by creating a property - * of type #GParamSpecOverride. See g_object_class_override_property() - * for an example of the use of this capability. - * paramspec should be redirected, or %NULL if none. + * g_type_plugin_unuse: + * @plugin: a #GTypePlugin * - * Since: 2.4 - * Returns: (transfer none): paramspec to which requests on this + * Calls the @unuse_plugin function from the #GTypePluginClass of + * the GObject type system itself. */ /** - * g_main_is_running: - * @loop: a #GMainLoop - * - * Checks if the main loop is running. + * g_type_plugin_use: + * @plugin: a #GTypePlugin * - * Returns: %TRUE if the main loop is running - * Deprecated: 2.2: Use g_main_loop_is_running() instead + * Calls the @use_plugin function from the #GTypePluginClass of + * the GObject type system itself. */ /** - * g_boxed_free: - * @boxed_type: The type of @boxed. - * @boxed: The boxed structure to be freed. + * g_type_qname: + * @type: Type to return quark of type name for. * - * Free the boxed structure @boxed which is of type @boxed_type. + * Get the corresponding quark of the type IDs name. + * + * Returns: The type names quark or 0. */ /** - * G_TYPE_OBJECT: + * g_type_query: + * @type: the #GType value of a static, classed type. + * @query: (out caller-allocates): A user provided structure that is filled in with constant values upon success. * - * The fundamental type for #GObject. + * Queries the type system for information about a specific type. + * This function will fill in a user-provided structure to hold + * type-specific information. If an invalid #GType is passed in, the + * #GTypeQuery structure should be considered constant and have to be + * left untouched. */ @@ -9562,936 +9599,960 @@ /** - * GParamSpecPointer: - * @parent_instance: private #GParamSpec portion + * g_type_register_fundamental: + * @type_id: A predefined type identifier. + * @type_name: 0-terminated string used as the name of the new type. + * @info: The #GTypeInfo structure for this type. + * @finfo: The #GTypeFundamentalInfo structure for this type. + * @flags: Bitwise combination of #GTypeFlags values. * - * A #GParamSpec derived structure that contains the meta data for pointer properties. + * Registers @type_id as the predefined identifier and @type_name as the + * name of a fundamental type. The type system uses the information + * contained in the #GTypeInfo structure pointed to by @info and the + * #GTypeFundamentalInfo structure pointed to by @finfo to manage the + * type and its instances. The value of @flags determines additional + * characteristics of the fundamental type. + * + * Returns: The predefined type identifier. */ /** - * g_main_iteration: - * @may_block: set to %TRUE if it should block (i.e. wait) until an event source becomes ready. It will return after an event source has been processed. If set to %FALSE it will return immediately if no event source is ready to be processed. + * g_type_register_static: + * @parent_type: Type from which this type will be derived. + * @type_name: 0-terminated string used as the name of the new type. + * @info: The #GTypeInfo structure for this type. + * @flags: Bitwise combination of #GTypeFlags values. * - * Runs a single iteration for the default #GMainContext. + * Registers @type_name as the name of a new static type derived from + * #GTypeInfo structure pointed to by @info to manage the type and its + * instances (if not abstract). The value of @flags determines the nature + * (e.g. abstract or not) of the type. * - * Returns: %TRUE if more events are pending. - * Deprecated: 2.2: Use g_main_context_iteration() instead. + * Returns: The new type identifier. */ /** - * g_signal_connect_swapped: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. + * g_type_register_static_simple: (skip) + * @parent_type: Type from which this type will be derived. + * @type_name: 0-terminated string used as the name of the new type. + * @class_size: Size of the class structure (see #GTypeInfo) + * @class_init: Location of the class initialization function (see #GTypeInfo) + * @instance_size: Size of the instance structure (see #GTypeInfo) + * @instance_init: Location of the instance initialization function (see #GTypeInfo) + * @flags: Bitwise combination of #GTypeFlags values. * - * Connects a #GCallback function to a signal for a particular object. - * The instance on which the signal is emitted and @data will be swapped when - * calling the handler. + * Registers @type_name as the name of a new static type derived from + * abstract or not) of the type. It works by filling a #GTypeInfo + * struct and calling g_type_register_static(). * - * Returns: the handler id + * Since: 2.12 + * Returns: The new type identifier. */ /** - * g_value_copy: - * @src_value: An initialized #GValue structure. - * @dest_value: An initialized #GValue structure of the same type as @src_value. + * g_type_remove_class_cache_func: (skip) + * @cache_data: data that was given when adding @cache_func + * @cache_func: a #GTypeClassCacheFunc * - * Copies the value of @src_value into @dest_value. + * Removes a previously installed #GTypeClassCacheFunc. The cache + * maintained by @cache_func has to be empty when calling + * g_type_remove_class_cache_func() to avoid leaks. */ /** - * G_VARIANT_TYPE_UINT64: + * g_type_remove_interface_check: (skip) + * @check_data: callback data passed to g_type_add_interface_check() + * @check_func: callback function passed to g_type_add_interface_check() * - * The type of an integer value that can range from 0 to - * 18446744073709551616. That's a really big number, but a Rubik's - * cube can have a bit more than twice as many possible positions. + * Removes an interface check function added with + * g_type_add_interface_check(). + * + * Since: 2.4 */ /** - * G_TYPE_PARAM_GTYPE: + * g_type_set_qdata: + * @type: a #GType + * @quark: a #GQuark id to identify the data + * @data: the data * - * The #GType of #GParamSpecGType. + * Attaches arbitrary data to a type. + */ + + +/** + * g_type_value_table_peek: (skip) + * @type: A #GType value. * - * Since: 2.10 + * Returns the location of the #GTypeValueTable associated with @type. + * <emphasis>Note that this function should only be used from source code + * that implements or has internal knowledge of the implementation of + * %NULL if there is no #GTypeValueTable associated with @type. + * + * Returns: Location of the #GTypeValueTable associated with @type or */ /** - * G_OBJECT: - * @object: Object which is subject to casting. + * g_value_array_append: + * @value_array: #GValueArray to add an element to + * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL * - * 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. + * Insert a copy of @value as last element of @value_array. If @value is + * %NULL, an uninitialized value is appended. + * + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * GVariantType: + * g_value_array_copy: + * @value_array: #GValueArray to copy * - * A type in the GVariant type system. - * Two types may not be compared by value; use g_variant_type_equal() or - * g_variant_type_is_subtype(). May be copied using - * g_variant_type_copy() and freed using g_variant_type_free(). + * Construct an exact copy of a #GValueArray by duplicating all its + * contents. + * + * Returns: (transfer full): Newly allocated copy of #GValueArray */ /** - * G_DATALIST_FLAGS_MASK: + * g_value_array_free: + * @value_array: #GValueArray to free * - * A bitmask that restricts the possible flags passed to - * g_datalist_set_flags(). Passing a flags value where - * flags & ~G_DATALIST_FLAGS_MASK != 0 is an error. + * Free a #GValueArray including its contents. */ /** - * GOptionContext: + * g_value_array_get_nth: + * @value_array: #GValueArray to get a value from + * @index_: index of the value of interest * - * A <structname>GOptionContext</structname> struct defines which options - * are accepted by the commandline option parser. The struct has only private - * fields and should not be directly accessed. + * Return a pointer to the value at @index_ containd in @value_array. + * + * Returns: (transfer none): pointer to a value at @index_ in @value_array */ /** - * g_type_module_unuse: - * @module: a #GTypeModule + * g_value_array_insert: + * @value_array: #GValueArray to add an element to + * @index_: insertion position, must be <= value_array->n_values + * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL * - * Decreases the use count of a #GTypeModule by one. If the - * result is zero, the module will be unloaded. (However, the - * #GTypeModule will not be freed, and types associated with the - * #GTypeModule are not unregistered. Once a #GTypeModule is - * initialized, it must exist forever.) + * Insert a copy of @value at specified position into @value_array. If @value + * is %NULL, an uninitialized value is inserted. + * + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * G_TYPE_IS_ENUM: - * @type: a #GType ID. + * g_value_array_new: + * @n_prealloced: number of values to preallocate space for * - * Checks whether @type "is a" %G_TYPE_ENUM. + * Allocate and initialize a new #GValueArray, optionally preserve space + * for @n_prealloced elements. New arrays always contain 0 elements, + * regardless of the value of @n_prealloced. * - * Returns: %TRUE if @type "is a" %G_TYPE_ENUM. + * Returns: a newly allocated #GValueArray with 0 values */ /** - * G_TYPE_RESERVED_GLIB_FIRST: + * g_value_array_prepend: + * @value_array: #GValueArray to add an element to + * @value: (allow-none): #GValue to copy into #GValueArray, or %NULL * - * First fundamental type number to create a new fundamental type id with - * G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. + * Insert a copy of @value as first element of @value_array. If @value is + * %NULL, an uninitialized value is prepended. + * + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * G_INITIALLY_UNOWNED_CLASS: - * @class: a valid #GInitiallyUnownedClass + * g_value_array_remove: + * @value_array: #GValueArray to remove an element from + * @index_: position of value to remove, must be < value_array->n_values * - * Casts a derived #GInitiallyUnownedClass structure into a - * #GInitiallyUnownedClass structure. + * Remove the value at position @index_ from @value_array. + * + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * g_main_pending: + * g_value_array_sort: + * @value_array: #GValueArray to sort + * @compare_func: (scope call): function to compare elements * - * Checks if any events are pending for the default #GMainContext - * (i.e. ready to be processed). + * Sort @value_array using @compare_func to compare the elements accoring to + * the semantics of #GCompareFunc. + * The current implementation uses Quick-Sort as sorting algorithm. * - * Returns: %TRUE if any events are pending. - * Deprected: 2.2: Use g_main_context_pending() instead. + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * G_TYPE_IS_INTERFACE: - * @type: A #GType value. + * g_value_array_sort_with_data: + * @value_array: #GValueArray to sort + * @compare_func: (scope call): function to compare elements + * @user_data: (closure): extra data argument provided for @compare_func * - * 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 - * interfaces and C++ classes containing only pure virtual functions, - * with the difference that GType interfaces are not derivable (but see - * g_type_interface_add_prerequisite() for an alternative). + * Sort @value_array using @compare_func to compare the elements accoring + * to the semantics of #GCompareDataFunc. + * The current implementation uses Quick-Sort as sorting algorithm. * - * Returns: %TRUE on success. + * Rename to: g_value_array_sort + * Returns: (transfer none): the #GValueArray passed in as @value_array */ /** - * g_value_set_static_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: static string to be set + * g_value_copy: + * @src_value: An initialized #GValue structure. + * @dest_value: An initialized #GValue structure of the same type as @src_value. * - * Set the contents of a %G_TYPE_STRING #GValue to @v_string. - * The string is assumed to be static, and is thus not duplicated - * when setting the #GValue. + * Copies the value of @src_value into @dest_value. */ /** - * g_param_value_defaults: - * @pspec: a valid #GParamSpec - * @value: a #GValue of correct type for @pspec + * g_value_dup_boxed: (skip) + * @value: a valid #GValue of %G_TYPE_BOXED derived type * - * Checks whether @value contains the default value as specified in @pspec. + * Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, + * the boxed value is duplicated and needs to be later freed with + * return_value); * - * Returns: whether @value contains the canonical default for this @pspec + * G_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), + * Returns: boxed contents of @value */ /** - * G_OBJECT_WARN_INVALID_PROPERTY_ID: - * @object: the #GObject on which set_property() or get_property() was called - * @property_id: the numeric id of the property - * @pspec: the #GParamSpec of the property + * g_value_dup_object: + * @value: a valid #GValue whose type is derived from %G_TYPE_OBJECT * - * This macro should be used to emit a standard warning about unexpected - * properties in set_property() and get_property() implementations. + * Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing + * its reference count. + * should be unreferenced when no longer needed. + * + * Returns: (type GObject.Object) (transfer full): object content of @value, */ /** - * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT: + * g_value_dup_param: (skip) + * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM * - * Allowed characters in path elements. Includes "!$&'()*+,;=:@". + * Get the contents of a %G_TYPE_PARAM #GValue, increasing its + * reference count. + * no longer needed. + * + * Returns: #GParamSpec content of @value, should be unreferenced when */ /** - * g_param_spec_override: (skip) - * @name: the name of the property. - * @overridden: The property that is being overridden + * g_value_dup_string: + * @value: a valid #GValue of type %G_TYPE_STRING * - * Creates a new property of type #GParamSpecOverride. This is used - * to direct operations to another paramspec, and will not be directly - * useful unless you are implementing a new base type similar to GObject. + * Get a copy the contents of a %G_TYPE_STRING #GValue. * - * Since: 2.4 - * Returns: the newly created #GParamSpec + * Returns: a newly allocated copy of the string content of @value */ /** - * g_type_value_table_peek: (skip) - * @type: A #GType value. + * g_value_dup_variant: + * @value: a valid #GValue of type %G_TYPE_VARIANT * - * Returns the location of the #GTypeValueTable associated with @type. - * <emphasis>Note that this function should only be used from source code - * that implements or has internal knowledge of the implementation of - * %NULL if there is no #GTypeValueTable associated with @type. + * Get the contents of a variant #GValue, increasing its refcount. + * g_variant_unref() when no longer needed * - * Returns: Location of the #GTypeValueTable associated with @type or + * Returns: variant contents of @value, should be unrefed using + * Since: 2.26 */ /** - * g_type_default_interface_peek: - * @g_type: an interface type + * g_value_fits_pointer: + * @value: An initialized #GValue structure. * - * If the interface type @g_type is currently in use, returns its - * default interface vtable. - * vtable for the interface, or %NULL if the type is not currently in - * use. + * Determines if @value will fit inside the size of a pointer value. + * This is an internal function introduced mainly for C marshallers. * - * Since: 2.4 - * Returns: (type GObject.TypeInterface) (transfer none): the default + * Returns: %TRUE if @value will fit inside a pointer value. */ /** - * g_strdup_value_contents: - * @value: #GValue which contents are to be described. + * g_value_get_boolean: + * @value: a valid #GValue of type %G_TYPE_BOOLEAN * - * Return a newly allocated string, which describes the contents of a - * #GValue. The main purpose of this function is to describe #GValue - * contents for debugging output, the way in which the contents are - * described may change between different GLib versions. + * Get the contents of a %G_TYPE_BOOLEAN #GValue. * - * Returns: Newly allocated string. + * Returns: boolean contents of @value */ /** - * G_TYPE_PARAM_VARIANT: + * g_value_get_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type * - * The #GType of #GParamSpecVariant. + * Get the contents of a %G_TYPE_BOXED derived #GValue. * - * Since: 2.26 + * Returns: (transfer none): boxed contents of @value */ /** - * GObjectFinalizeFunc: - * @object: the #GObject being finalized + * g_value_get_char: + * @value: a valid #GValue of type %G_TYPE_CHAR * - * The type of the @finalize function of #GObjectClass. + * Get the contents of a %G_TYPE_CHAR #GValue. + * + * Returns: character contents of @value */ /** - * g_closure_unref: - * @closure: #GClosure to decrement the reference count on + * g_value_get_double: + * @value: a valid #GValue of type %G_TYPE_DOUBLE * - * 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. + * Get the contents of a %G_TYPE_DOUBLE #GValue. + * + * Returns: double contents of @value */ /** - * g_value_type_compatible: - * @src_type: source type to be copied. - * @dest_type: destination type for copying. + * g_value_get_enum: + * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM * - * Returns whether a #GValue of type @src_type can be copied into - * a #GValue of type @dest_type. + * Get the contents of a %G_TYPE_ENUM #GValue. * - * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. + * Returns: enum contents of @value */ /** - * g_signal_emitv: - * @instance_and_params: argument list for the signal emission. The first element in the array is a #GValue for the instance the signal is being emitted on. The rest are any arguments to be passed to the signal. - * @signal_id: the signal id - * @detail: the detail - * @return_value: Location to store the return value of the signal emission. + * g_value_get_flags: + * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS * - * Emits a signal. - * Note that g_signal_emitv() doesn't change @return_value if no handlers are - * connected, in contrast to g_signal_emit() and g_signal_emit_valist(). + * Get the contents of a %G_TYPE_FLAGS #GValue. + * + * Returns: flags contents of @value */ /** - * G_INITIALLY_UNOWNED: - * @object: Object which is subject to casting. + * g_value_get_float: + * @value: a valid #GValue of type %G_TYPE_FLOAT * - * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*) - * pointer. Depending on the current debugging level, this function may invoke - * certain runtime checks to identify invalid casts. + * Get the contents of a %G_TYPE_FLOAT #GValue. + * + * Returns: float contents of @value */ /** - * G_TYPE_FROM_INSTANCE: - * @instance: Location of a valid #GTypeInstance structure. + * g_value_get_gtype: + * @value: a valid #GValue of type %G_TYPE_GTYPE * - * Get the type identifier from a given @instance structure. - * This macro should only be used in type implementations. + * Get the contents of a %G_TYPE_GTYPE #GValue. * - * Returns: the #GType + * Since: 2.12 + * Returns: the #GType stored in @value */ /** - * G_VALUE_LCOPY: - * @value: a #GValue return location. @value is supposed to be initialized according to the value type to be collected - * @var_args: the va_list variable; it may be evaluated multiple times - * @flags: flags which are passed on to the lcopy_value() function of the #GTypeValueTable of @value. - * @__error: a #gchar** variable that will be modified to hold a g_new() allocated error messages if something fails + * g_value_get_int: + * @value: a valid #GValue of type %G_TYPE_INT * - * Collects a value's variable argument locations from a va_list. Usage is - * analogous to G_VALUE_COLLECT(). + * Get the contents of a %G_TYPE_INT #GValue. + * + * Returns: integer contents of @value */ /** - * G_VALUE_HOLDS_FLAGS: - * @value: a valid #GValue structure + * g_value_get_int64: + * @value: a valid #GValue of type %G_TYPE_INT64 * - * Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. + * Get the contents of a %G_TYPE_INT64 #GValue. * - * Returns: %TRUE on success. + * Returns: 64bit integer contents of @value */ /** - * g_signal_new: - * @signal_name: the name for the signal - * @itype: the type this signal pertains to. It will also pertain to types which are derived from this type. - * @signal_flags: a combination of #GSignalFlags specifying detail of when the default handler is to be invoked. You should at least specify %G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST. - * @class_offset: The offset of the function pointer in the class structure for this type. Used to invoke a class method generically. Pass 0 to not associate a class method slot with this signal. - * @accumulator: the accumulator for this signal; may be %NULL. - * @accu_data: user data for the @accumulator. - * @c_marshaller: the function to translate arrays of parameter values to signal emissions into C language callback invocations. - * @return_type: the type of return value, or #G_TYPE_NONE for a signal without a return value. - * @n_params: the number of parameter types to follow. - * @...: a list of types, one for each parameter. + * g_value_get_long: + * @value: a valid #GValue of type %G_TYPE_LONG * - * Creates a new signal. (This is usually done in the class initializer.) - * A signal name consists of segments consisting of ASCII letters and - * digits, separated by either the '-' or '_' character. The first - * character of a signal name must be a letter. Names which violate these - * rules lead to undefined behaviour of the GSignal system. - * When registering a signal and looking up a signal, either separator can - * be used, but they cannot be mixed. - * If 0 is used for @class_offset subclasses cannot override the class handler - * in their <code>class_init</code> method by doing - * <code>super_class->signal_handler = my_signal_handler</code>. Instead they - * will have to use g_signal_override_class_handler(). + * Get the contents of a %G_TYPE_LONG #GValue. * - * Returns: the signal id + * Returns: long integer contents of @value */ /** - * g_boxed_copy: - * @boxed_type: The type of @src_boxed. - * @src_boxed: The boxed structure to be copied. + * g_value_get_object: + * @value: a valid #GValue of %G_TYPE_OBJECT derived type * - * Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. + * Get the contents of a %G_TYPE_OBJECT derived #GValue. * - * Returns: The newly created copy of the boxed structure. + * Returns: (type GObject.Object) (transfer none): object contents of @value */ /** - * GBookmarkFileError: - * @G_BOOKMARK_FILE_ERROR_INVALID_URI: URI was ill-formed - * @G_BOOKMARK_FILE_ERROR_INVALID_VALUE: a requested field was not found - * @G_BOOKMARK_FILE_ERROR_APP_NOT_REGISTERED: a requested application did not register a bookmark - * @G_BOOKMARK_FILE_ERROR_URI_NOT_FOUND: a requested URI was not found - * @G_BOOKMARK_FILE_ERROR_READ: document was ill formed - * @G_BOOKMARK_FILE_ERROR_UNKNOWN_ENCODING: the text being parsed was in an unknown encoding - * @G_BOOKMARK_FILE_ERROR_WRITE: an error occurred while writing - * @G_BOOKMARK_FILE_ERROR_FILE_NOT_FOUND: requested file was not found + * g_value_get_param: + * @value: a valid #GValue whose type is derived from %G_TYPE_PARAM * - * Error codes returned by bookmark file parsing. + * Get the contents of a %G_TYPE_PARAM #GValue. + * + * Returns: (transfer none): #GParamSpec content of @value */ /** - * GTypePluginUnuse: - * @plugin: the #GTypePlugin whose use count should be decreased + * g_value_get_pointer: + * @value: a valid #GValue of %G_TYPE_POINTER * - * The type of the @unuse_plugin function of #GTypePluginClass. + * Get the contents of a pointer #GValue. + * + * Returns: (transfer none): pointer contents of @value */ /** - * G_DEFINE_INTERFACE: - * @TN: The name of the new type, in Camel case. - * @t_n: The name of the new type, in lowercase, with words separated by '_'. - * @T_P: The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. + * g_value_get_string: + * @value: a valid #GValue of type %G_TYPE_STRING * - * A convenience macro for #GTypeInterface definitions, which declares - * a default vtable initialization function and defines a *_get_type() - * function. - * The macro expects the interface initialization function to have the - * name <literal>t_n ## _default_init</literal>, and the interface - * structure to have the name <literal>TN ## Interface</literal>. + * Get the contents of a %G_TYPE_STRING #GValue. * - * Since: 2.24 + * Returns: string content of @value */ /** - * GCallback: + * g_value_get_uchar: + * @value: a valid #GValue of type %G_TYPE_UCHAR * - * 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. + * Get the contents of a %G_TYPE_UCHAR #GValue. + * + * Returns: unsigned character contents of @value */ /** - * G_VARIANT_TYPE_STRING_ARRAY: + * g_value_get_uint: + * @value: a valid #GValue of type %G_TYPE_UINT * - * The type of an array of strings. + * Get the contents of a %G_TYPE_UINT #GValue. + * + * Returns: unsigned integer contents of @value */ /** - * g_value_set_string: - * @value: a valid #GValue of type %G_TYPE_STRING - * @v_string: caller-owned string to be duplicated for the #GValue + * g_value_get_uint64: + * @value: a valid #GValue of type %G_TYPE_UINT64 * - * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + * Get the contents of a %G_TYPE_UINT64 #GValue. + * + * Returns: unsigned 64bit integer contents of @value */ /** - * G_SIGNAL_MATCH_MASK: + * g_value_get_ulong: + * @value: a valid #GValue of type %G_TYPE_ULONG * - * A mask for all #GSignalMatchType bits. + * Get the contents of a %G_TYPE_ULONG #GValue. + * + * Returns: unsigned long integer contents of @value */ /** - * g_signal_connect: - * @instance: the instance to connect to. - * @detailed_signal: a string of the form "signal-name::detail". - * @c_handler: the #GCallback to connect. - * @data: data to pass to @c_handler calls. + * g_value_get_variant: + * @value: a valid #GValue of type %G_TYPE_VARIANT * - * Connects a #GCallback function to a signal for a particular object. - * The handler will be called before the default handler of the signal. + * Get the contents of a variant #GValue. * - * Returns: the handler id + * Returns: variant contents of @value + * Since: 2.26 */ /** - * G_TYPE_PARAM_INT64: + * g_value_init: + * @value: A zero-filled (uninitialized) #GValue structure. + * @g_type: Type the #GValue should hold values of. * - * The #GType of #GParamSpecInt64. + * Initializes @value with the default value of @type. + * + * Returns: (transfer none): the #GValue structure that has been passed in */ /** - * g_param_spec_get_name: - * @pspec: a valid #GParamSpec + * g_value_peek_pointer: + * @value: An initialized #GValue structure. * - * Get the name of a #GParamSpec. + * function asserts that g_value_fits_pointer() returned %TRUE for the + * passed in value. This is an internal function introduced mainly + * for C marshallers. * - * Returns: the name of @pspec. + * Returns: (transfer none): the value contents as pointer. This */ /** - * g_param_spec_double: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE - * property. - * See g_param_spec_internal() for details on property names. + * g_value_register_transform_func: (skip) + * @src_type: Source type. + * @dest_type: Target type. + * @transform_func: a function which transforms values of type @src_type into value of type @dest_type * - * Returns: a newly created parameter specification + * Registers a value transformation function for use in g_value_transform(). + * A previously registered transformation function for @src_type and @dest_type + * will be replaced. */ /** - * g_value_set_variant: - * @value: a valid #GValue of type %G_TYPE_VARIANT - * @variant: a #GVariant, or %NULL + * g_value_reset: + * @value: An initialized #GValue structure. * - * Set the contents of a variant #GValue to @variant. - * If the variant is floating, it is consumed. + * Clears the current value in @value and resets it to the default value + * (as if the value had just been initialized). * - * Since: 2.26 + * Returns: the #GValue structure that has been passed in */ /** - * G_VALUE_HOLDS_UINT: - * @value: a valid #GValue structure + * g_value_set_boolean: + * @value: a valid #GValue of type %G_TYPE_BOOLEAN + * @v_boolean: boolean value to be set * - * Checks whether the given #GValue can hold values of type %G_TYPE_UINT. + * Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. + */ + + +/** + * g_value_set_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: boxed value to be set * - * Returns: %TRUE on success. + * Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. */ /** - * G_IS_PARAM_SPEC_INT64: - * @pspec: a valid #GParamSpec instance + * g_value_set_boxed_take_ownership: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: duplicated unowned boxed value to be set * - * Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. + * This is an internal function introduced mainly for C marshallers. * - * Returns: %TRUE on success. + * Deprecated: 2.4: Use g_value_take_boxed() instead. */ /** - * GParamSpecUInt64: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified + * g_value_set_char: + * @value: a valid #GValue of type %G_TYPE_CHAR + * @v_char: character value to be set * - * A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. + * Set the contents of a %G_TYPE_CHAR #GValue to @v_char. */ /** - * g_try_new: - * @struct_type: the type of the elements to allocate - * @n_structs: the number of elements to allocate - * - * Attempts to allocate @n_structs elements of type @struct_type, and returns - * %NULL on failure. Contrast with g_new(), which aborts the program on failure. - * The returned pointer is cast to a pointer to the given type. - * The function returns %NULL when @n_structs is 0 of if an overflow occurs. + * g_value_set_double: + * @value: a valid #GValue of type %G_TYPE_DOUBLE + * @v_double: double value to be set * - * Since: 2.8 - * Returns: a pointer to the allocated memory, cast to a pointer to @struct_type + * Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. */ /** - * g_closure_add_finalize_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data to pass to @notify_func - * @notify_func: the callback function to register + * g_value_set_enum: + * @value: a valid #GValue whose type is derived from %G_TYPE_ENUM + * @v_enum: enum value to be set * - * 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. + * Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. */ /** - * g_param_spec_object: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @object_type: %G_TYPE_OBJECT derived type of this property - * @flags: flags for the property specified - * - * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_OBJECT - * derived property. - * See g_param_spec_internal() for details on property names. + * g_value_set_flags: + * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS + * @v_flags: flags value to be set * - * Returns: a newly created parameter specification + * Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. */ /** - * g_closure_remove_finalize_notifier: (skip) - * @closure: a #GClosure - * @notify_data: data which was passed to g_closure_add_finalize_notifier() when registering @notify_func - * @notify_func: the callback function to remove + * g_value_set_float: + * @value: a valid #GValue of type %G_TYPE_FLOAT + * @v_float: float value to be set * - * Removes a finalization notifier. - * Notice that notifiers are automatically removed after they are run. + * Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. */ /** - * g_signal_remove_emission_hook: - * @signal_id: the id of the signal - * @hook_id: the id of the emission hook, as returned by g_signal_add_emission_hook() + * g_value_set_gtype: + * @value: a valid #GValue of type %G_TYPE_GTYPE + * @v_gtype: #GType to be set * - * Deletes an emission hook. + * Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. + * + * Since: 2.12 */ /** - * GParamSpecDouble: - * @parent_instance: private #GParamSpec portion - * @minimum: minimum value for the property specified - * @maximum: maximum value for the property specified - * @default_value: default value for the property specified - * @epsilon: values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. + * g_value_set_instance: + * @value: An initialized #GValue structure. + * @instance: the instance * - * A #GParamSpec derived structure that contains the meta data for double properties. + * Sets @value from an instantiatable type via the + * value_table's collect_value() function. */ /** - * G_TYPE_IS_DERIVED: - * @type: A #GType value. + * g_value_set_int: + * @value: a valid #GValue of type %G_TYPE_INT + * @v_int: integer value to be set * - * Checks if @type is derived (or in object-oriented terminology: - * inherited) from another type (this holds true for all non-fundamental - * types). + * Set the contents of a %G_TYPE_INT #GValue to @v_int. + */ + + +/** + * g_value_set_int64: + * @value: a valid #GValue of type %G_TYPE_INT64 + * @v_int64: 64bit integer value to be set * - * Returns: %TRUE on success. + * Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. */ /** - * GObject::notify: - * @gobject: the object which received the signal. - * @pspec: the #GParamSpec of the property which changed. + * g_value_set_long: + * @value: a valid #GValue of type %G_TYPE_LONG + * @v_long: long integer value to be set * - * The notify signal is emitted on an object when one of its - * properties has been changed. Note that getting this signal - * doesn't guarantee that the value of the property has actually - * changed, it may also be emitted when the setter for the property - * is called to reinstate the previous value. - * 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: - * |[ - * 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 - * <link linkend="canonical-parameter-name">canonical</link> parameter names as - * detail strings for the notify signal. + * Set the contents of a %G_TYPE_LONG #GValue to @v_long. */ /** - * G_PARAM_USER_SHIFT: + * g_value_set_object: + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: (type GObject.Object): object value to be set * - * Minimum shift count to be used for user defined flags, to be stored in - * #GParamSpec.flags. The maximum allowed is 30 + G_PARAM_USER_SHIFT. + * Set the contents of a %G_TYPE_OBJECT derived #GValue to @v_object. + * g_value_set_object() increases the reference count of @v_object + * (the #GValue holds a reference to @v_object). If you do not wish + * to increase the reference count of the object (i.e. you wish to + * pass your current reference to the #GValue because you no longer + * need it), use g_value_take_object() instead. + * It is important that your #GValue holds a reference to @v_object (either its + * own, or one it has taken) to ensure that the object won't be destroyed while + * the #GValue still exists). */ /** - * GBinding:source-property: + * g_value_set_object_take_ownership: (skip) + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: object value to be set * - * The name of the property of #GBinding:source that should be used - * as the source of the binding + * This is an internal function introduced mainly for C marshallers. * - * Since: 2.26 + * Deprecated: 2.4: Use g_value_take_object() instead. */ /** - * g_param_spec_string: (skip) - * @name: canonical name of the property specified - * @nick: nick name for the property specified - * @blurb: description of the property specified - * @default_value: default value for the property specified - * @flags: flags for the property specified - * - * Creates a new #GParamSpecString instance. - * See g_param_spec_internal() for details on property names. + * g_value_set_param: + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set * - * Returns: a newly created parameter specification + * Set the contents of a %G_TYPE_PARAM #GValue to @param. */ /** - * GParamSpecOverride: + * g_value_set_param_take_ownership: (skip) + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set * - * 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 overidden - * 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. + * This is an internal function introduced mainly for C marshallers. * - * Since: 2.4 + * Deprecated: 2.4: Use g_value_take_param() instead. */ /** - * G_TYPE_PARAM_DOUBLE: + * g_value_set_pointer: + * @value: a valid #GValue of %G_TYPE_POINTER + * @v_pointer: pointer value to be set * - * The #GType of #GParamSpecDouble. + * Set the contents of a pointer #GValue to @v_pointer. */ /** - * g_value_get_flags: - * @value: a valid #GValue whose type is derived from %G_TYPE_FLAGS + * g_value_set_static_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: static boxed value to be set * - * Get the contents of a %G_TYPE_FLAGS #GValue. + * 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. + */ + + +/** + * g_value_set_static_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: static string to be set * - * Returns: flags contents of @value + * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + * The string is assumed to be static, and is thus not duplicated + * when setting the #GValue. */ /** - * G_TYPE_IS_DERIVABLE: - * @type: A #GType value. + * g_value_set_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: caller-owned string to be duplicated for the #GValue * - * Checks if @type is a derivable type. A derivable type can - * be used as the base class of a flat (single-level) class hierarchy. + * Set the contents of a %G_TYPE_STRING #GValue to @v_string. + */ + + +/** + * g_value_set_string_take_ownership: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: duplicated unowned string to be set * - * Returns: %TRUE on success. + * This is an internal function introduced mainly for C marshallers. + * + * Deprecated: 2.4: Use g_value_take_string() instead. */ /** - * GSignalMatchType: - * @G_SIGNAL_MATCH_ID: The signal id must be equal. - * @G_SIGNAL_MATCH_DETAIL: The signal detail be equal. - * @G_SIGNAL_MATCH_CLOSURE: The closure must be the same. - * @G_SIGNAL_MATCH_FUNC: The C closure callback must be the same. - * @G_SIGNAL_MATCH_DATA: The closure data must be the same. - * @G_SIGNAL_MATCH_UNBLOCKED: Only unblocked signals may matched. + * g_value_set_uchar: + * @value: a valid #GValue of type %G_TYPE_UCHAR + * @v_uchar: unsigned character value to be set * - * The match types specify what g_signal_handlers_block_matched(), - * g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() - * match signals by. + * Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. */ /** - * G_PARAM_SPEC_INT: - * @pspec: a valid #GParamSpec instance + * g_value_set_uint: + * @value: a valid #GValue of type %G_TYPE_UINT + * @v_uint: unsigned integer value to be set * - * Cast a #GParamSpec instance into a #GParamSpecInt. + * Set the contents of a %G_TYPE_UINT #GValue to @v_uint. */ /** - * GCClosure: - * @closure: the #GClosure - * @callback: the callback function + * g_value_set_uint64: + * @value: a valid #GValue of type %G_TYPE_UINT64 + * @v_uint64: unsigned 64bit integer value to be set * - * A #GCClosure is a specialization of #GClosure for C function callbacks. + * Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. */ /** - * g_object_disconnect: (skip) - * @object: a #GObject - * @signal_spec: the spec for the first signal - * @...: #GCallback for the first signal, followed by data for the first signal, followed optionally by more signal spec/callback/data triples, followed by %NULL + * g_value_set_ulong: + * @value: a valid #GValue of type %G_TYPE_ULONG + * @v_ulong: unsigned long integer value to be set * - * A convenience function to disconnect multiple signals at once. - * The signal specs expected by this function have the form - * "any_signal", which means to disconnect any signal with matching - * callback and data, or "any_signal::signal_name", which only - * disconnects the signal named "signal_name". + * Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. */ /** - * g_closure_set_marshal: (skip) - * @closure: a #GClosure - * @marshal: a #GClosureMarshal function + * g_value_set_variant: + * @value: a valid #GValue of type %G_TYPE_VARIANT + * @variant: a #GVariant, or %NULL * - * Sets the marshaller of @closure. The <literal>marshal_data</literal> - * 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_*() - * functions), what it provides is a callback function to use instead of + * Set the contents of a variant #GValue to @variant. + * If the variant is floating, it is consumed. + * + * Since: 2.26 */ /** - * GSourceCallbackFuncs: - * @ref: Called when a reference is added to the callback object - * @unref: Called when a reference to the callback object is dropped - * @get: Called to extract the callback function and data from the callback object. + * g_value_take_boxed: + * @value: a valid #GValue of %G_TYPE_BOXED derived type + * @v_boxed: duplicated unowned boxed value to be set * - * The <structname>GSourceCallbackFuncs</structname> struct contains - * functions for managing callback objects. + * Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed + * and takes over the ownership of the callers reference to @v_boxed; + * the caller doesn't have to unref it any more. + * + * Since: 2.4 */ /** - * G_VARIANT_TYPE_HANDLE: + * g_value_take_object: (skip) + * @value: a valid #GValue of %G_TYPE_OBJECT derived type + * @v_object: object value to be set * - * The type of a 32bit signed integer value, that by convention, is used - * as an index into an array of file descriptors that are sent alongside - * a DBus message. - * If you are not interacting with DBus, then there is no reason to make - * use of this type. + * Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object + * and takes over the ownership of the callers reference to @v_object; + * the caller doesn't have to unref it any more (i.e. the reference + * count of the object is not increased). + * If you want the #GValue to hold its own reference to @v_object, use + * g_value_set_object() instead. + * + * Since: 2.4 */ /** - * GParamSpecParam: - * @parent_instance: private #GParamSpec portion + * g_value_take_param: (skip) + * @value: a valid #GValue of type %G_TYPE_PARAM + * @param: the #GParamSpec to be set * - * A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM - * properties. + * Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes + * over the ownership of the callers reference to @param; the caller + * doesn't have to unref it any more. + * + * Since: 2.4 */ /** - * g_object_class_override_property: - * @oclass: a #GObjectClass - * @property_id: the new property ID - * @name: the name of a property registered in a parent class or in an interface of this class. + * g_value_take_string: + * @value: a valid #GValue of type %G_TYPE_STRING + * @v_string: string to take ownership of * - * Registers @property_id as referring to a property with the - * name @name in a parent class or in an interface implemented - * by @oclass. This allows this class to <firstterm>override</firstterm> - * a property implementation in a parent class or to provide - * the implementation of a property from an interface. - * <note> - * Internally, overriding is implemented by creating a property of type - * #GParamSpecOverride; generally operations that query the properties of - * the object class, such as g_object_class_find_property() or - * g_object_class_list_properties() will return the overridden - * property. However, in one case, the @construct_properties argument of - * the @constructor virtual function, the #GParamSpecOverride is passed - * instead, so that the @param_id field of the #GParamSpec will be - * correct. For virtually all uses, this makes no difference. If you - * need to get the overridden property, you can call - * g_param_spec_get_redirect_target(). - * </note> + * Sets the contents of a %G_TYPE_STRING #GValue to @v_string. * * Since: 2.4 */ /** - * G_TYPE_RESERVED_BSE_FIRST: + * g_value_take_variant: + * @value: a valid #GValue of type %G_TYPE_VARIANT + * @variant: a #GVariant, or %NULL * - * First fundamental type number to create a new fundamental type id with - * G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. + * Set the contents of a variant #GValue to @variant, and takes over + * the ownership of the caller's reference to @variant; + * the caller doesn't have to unref it any more (i.e. the reference + * count of the variant is not increased). + * It is a programmer error to pass a floating variant to this function. + * In particular this means that callbacks in closures, and signal handlers + * for signals of return type %G_TYPE_VARIANT, must never return floating + * variants. + * If you want the #GValue to hold its own reference to @variant, use + * g_value_set_variant() instead. + * This is an internal function introduced mainly for C marshallers. + * + * Since: 2.26 */ /** - * g_signal_handlers_block_matched: - * @instance: The instance to block handlers from. - * @mask: Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. - * @signal_id: Signal the handlers have to be connected to. - * @detail: Signal detail the handlers have to be connected to. - * @closure: The closure the handlers will invoke. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * g_value_transform: + * @src_value: Source value. + * @dest_value: Target value. * - * Blocks all handlers on an instance that match a certain selection criteria. - * The criteria mask is passed as an OR-ed combination of #GSignalMatchType - * flags, and the criteria values are passed as arguments. - * Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC - * or %G_SIGNAL_MATCH_DATA match flags is required for successful matches. - * If no handlers were found, 0 is returned, the number of blocked handlers - * otherwise. + * Tries to cast the contents of @src_value into a type appropriate + * to store in @dest_value, e.g. to transform a %G_TYPE_INT value + * into a %G_TYPE_FLOAT value. Performing transformations between + * value types might incur precision lossage. Especially + * transformations into strings might reveal seemingly arbitrary + * results and shouldn't be relied upon for production code (such + * as rcfile value or object property serialization). + * Upon failing transformations, @dest_value is left untouched. * - * Returns: The number of handlers that matched. + * Returns: Whether a transformation rule was found and could be applied. */ /** - * g_node_first_child: - * @node: a #GNode + * g_value_type_compatible: + * @src_type: source type to be copied. + * @dest_type: destination type for copying. * - * Gets the first child of a #GNode. - * or has no children + * Returns whether a #GValue of type @src_type can be copied into + * a #GValue of type @dest_type. * - * Returns: the first child of @node, or %NULL if @node is %NULL + * Returns: %TRUE if g_value_copy() is possible with @src_type and @dest_type. */ /** - * GBaseFinalizeFunc: - * @g_class: The #GTypeClass structure to finalize. + * g_value_type_transformable: + * @src_type: Source type. + * @dest_type: Target type. * - * 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 intialization is performed. - * See GClassInitFunc() for a discussion of the class intialization process. + * Check whether g_value_transform() is able to transform values + * of type @src_type into values of type @dest_type. + * + * Returns: %TRUE if the transformation is possible, %FALSE otherwise. */ /** - * g_signal_handlers_block_by_func: - * @instance: The instance to block handlers from. - * @func: The C closure callback of the handlers (useless for non-C closures). - * @data: The closure data of the handlers' closures. + * g_value_unset: + * @value: An initialized #GValue structure. * - * Blocks all handlers on an instance that match @func and @data. + * Clears the current value in @value and "unsets" the type, + * this releases all resources associated with this GValue. + * An unset value is the same as an uninitialized (zero-filled) + * #GValue structure. + */ + + +/** + * g_variant_get_gtype: * - * Returns: The number of handlers that matched. + * + * + * Since: 2.24 + * Deprecated: 2.26 + */ + + +/** + * gchararray: + * + * A C representable type name for #G_TYPE_STRING. */ |