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. This is the signature of va_list marshaller functions, an optional marshaller that can be used in some situations to avoid marshalling the signal argument into GValues. A numerical value which represents the unique identifier of a registered type. A convenience macro to ease adding private data to instances of a new type in the @_C_ section of G_DEFINE_TYPE_WITH_CODE() or G_DEFINE_ABSTRACT_TYPE_WITH_CODE(). For instance: |[<!-- language="C" --> typedef struct _MyObject MyObject; typedef struct _MyObjectClass MyObjectClass; typedef struct { gint foo; gint bar; } MyObjectPrivate; G_DEFINE_TYPE_WITH_CODE (MyObject, my_object, G_TYPE_OBJECT, G_ADD_PRIVATE (MyObject)) ]| Will add MyObjectPrivate as the private data to any instance of the MyObject type. G_DEFINE_TYPE_* macros will automatically create a private function based on the arguments to this macro, which can be used to safely retrieve the private data from an instance of the type; for instance: |[<!-- language="C" --> gint my_object_get_foo (MyObject *obj) { MyObjectPrivate *priv = my_object_get_instance_private (obj); g_return_val_if_fail (MY_IS_OBJECT (obj), 0); return priv->foo; } void my_object_set_bar (MyObject *obj, gint bar) { MyObjectPrivate *priv = my_object_get_instance_private (obj); g_return_if_fail (MY_IS_OBJECT (obj)); if (priv->bar != bar) priv->bar = bar; } ]| Note that this macro can only be used together with the G_DEFINE_TYPE_* macros, since it depends on variable names from those macros. Also note that private structs added with these macros must have a struct name of the form `TypeNamePrivate`. It is safe to call the `_get_instance_private` function on %NULL or invalid objects since it's only adding an offset to the instance pointer. In that case the returned pointer must not be dereferenced. the name of the type in CamelCase A convenience macro to ease adding private data to instances of a new dynamic type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED(). See G_ADD_PRIVATE() for details, it is similar but for static types. 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. the name of the type in CamelCase A callback function used by the type system to finalize those portions of a derived types class structure that were setup from the corresponding GBaseInitFunc() function. Class finalization basically works the inverse way in which class initialization is performed. See GClassInitFunc() for a discussion of the class initialization process. The #GTypeClass structure to finalize 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 initialization process. The #GTypeClass structure to initialize #GBinding is the representation of a binding between a property on a #GObject instance (or source) and another property on another #GObject instance (or target). Whenever the source property changes, the same value is applied to the target property; for instance, the following binding: |[<!-- language="C" --> g_object_bind_property (object1, "property-a", object2, "property-b", G_BINDING_DEFAULT); ]| will cause the property named "property-b" of @object2 to be updated every time g_object_set() or the specific accessor changes the value of the property "property-a" of @object1. It is possible to create a bidirectional binding between two properties of two #GObject instances, so that if either property changes, the other is updated as well, for instance: |[<!-- language="C" --> g_object_bind_property (object1, "property-a", object2, "property-b", G_BINDING_BIDIRECTIONAL); ]| will keep the two properties in sync. It is also possible to set a custom transformation function (in both directions, in case of a bidirectional binding) to apply a custom transformation from the source value to the target value before applying it; for instance, the following binding: |[<!-- language="C" --> g_object_bind_property_full (adjustment1, "value", adjustment2, "value", G_BINDING_BIDIRECTIONAL, celsius_to_fahrenheit, fahrenheit_to_celsius, NULL, NULL); ]| will keep the "value" property of the two adjustments in sync; the @celsius_to_fahrenheit function will be called whenever the "value" property of @adjustment1 changes and will transform the current value of the property before applying it to the "value" property of @adjustment2. Vice versa, the @fahrenheit_to_celsius function will be called whenever the "value" property of @adjustment2 changes, and will transform the current value of the property before applying it to the "value" property of @adjustment1. Note that #GBinding does not resolve cycles by itself; a cycle like |[ object1:propertyA -> object2:propertyB object2:propertyB -> object3:propertyC object3:propertyC -> object1:propertyA ]| might lead to an infinite loop. The loop, in this particular case, can be avoided if the objects emit the #GObject::notify signal only if the value has effectively been changed. A binding is implemented using the #GObject::notify signal, so it is susceptible to all the various ways of blocking a signal emission, like g_signal_stop_emission() or g_signal_handler_block(). A binding will be severed, and the resources it allocates freed, whenever either one of the #GObject instances it refers to are finalized, or when the #GBinding instance loses its last reference. Bindings for languages with garbage collection can use g_binding_unbind() to explicitly release a binding between the source and target properties, instead of relying on the last reference on the binding, source, and target instances to drop. #GBinding is available since GObject 2.26 Retrieves the flags passed when constructing the #GBinding. the #GBindingFlags used by the #GBinding a #GBinding Retrieves the #GObject instance used as the source of the binding. the source #GObject a #GBinding Retrieves the name of the property of #GBinding:source used as the source of the binding. the name of the source property a #GBinding Retrieves the #GObject instance used as the target of the binding. the target #GObject a #GBinding Retrieves the name of the property of #GBinding:target used as the target of the binding. the name of the target property a #GBinding Explicitly releases the binding between the source and the target property expressed by @binding. This function will release the reference that is being held on the @binding instance; if you want to hold on to the #GBinding instance after calling g_binding_unbind(), you will need to hold a reference to it. a #GBinding Flags to be used to control the #GBinding The #GObject that should be used as the source of the binding The name of the property of #GBinding:source that should be used as the source of the binding. This should be in [canonical form][canonical-parameter-names] to get the best performance. The #GObject that should be used as the target of the binding The name of the property of #GBinding:target that should be used as the target of the binding. This should be in [canonical form][canonical-parameter-names] to get the best performance. Flags to be passed to g_object_bind_property() or g_object_bind_property_full(). This enumeration can be extended at later date. The default binding; if the source property changes, the target property is updated with its value. Bidirectional binding; if either the property of the source or the property of the target changes, the other is updated. Synchronize the values of the source and target properties when creating the binding; the direction of the synchronization is always from the source to the target. If the two properties being bound are booleans, setting one to %TRUE will result in the other being set to %FALSE and vice versa. This flag will only work for boolean properties, and cannot be used when passing custom transformation functions to g_object_bind_property_full(). A function to be called to transform @from_value to @to_value. If this is the @transform_to function of a binding, then @from_value is the @source_property on the @source object, and @to_value is the @target_property on the @target object. If this is the @transform_from function of a %G_BINDING_BIDIRECTIONAL binding, then those roles are reversed. %TRUE if the transformation was successful, and %FALSE otherwise a #GBinding the #GValue containing the value to transform the #GValue in which to store the transformed value data passed to the transform function This function is provided by the user and should produce a copy of the passed in boxed structure. The newly created copy of the boxed structure. The boxed structure to be copied. This function is provided by the user and should free the boxed structure passed. The boxed structure to be freed. Cast a function pointer to a #GCallback. a function pointer. Checks whether the user data of the #GCClosure should be passed as the first parameter to the callback. See g_cclosure_new_swap(). a #GCClosure A #GCClosure is a specialization of #GClosure for C function callbacks. the #GClosure the callback function A #GClosureMarshal function for use with signals with handlers that take two boxed pointers as arguments and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled(). A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__BOXED_BOXED(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. the #GClosure to which the marshaller belongs a #GValue which can store the returned #gboolean 2 a #GValue array holding instance and arg1 the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_BOOLEAN__FLAGS(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. the #GClosure to which the marshaller belongs a #GValue, which can store the returned string 3 a #GValue array holding instance, arg1 and arg2 the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_STRING__OBJECT_POINTER(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gboolean parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOOLEAN(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #GBoxed* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__BOXED(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gchar parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__CHAR(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gdouble parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__DOUBLE(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the enumeration parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ENUM(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the flags parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLAGS(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gfloat parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__FLOAT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gint parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__INT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #glong parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__LONG(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #GObject* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__OBJECT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #GParamSpec* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__PARAM(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gpointer parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__POINTER(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gchar* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__STRING(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #guchar parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UCHAR(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #guint parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 3 a #GValue array holding instance, arg1 and arg2 the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT_POINTER(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__UINT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gulong parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__ULONG(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #GVariant* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VARIANT(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 1 a #GValue array holding only the instance the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller The #GVaClosureMarshal equivalent to g_cclosure_marshal_VOID__VOID(). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. A generic marshaller function implemented via [libffi](http://sourceware.org/libffi/). Normally this function is not passed explicitly to g_signal_new(), but used automatically by GLib when specifying a %NULL marshaller. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A generic #GVaClosureMarshal function implemented via [libffi](http://sourceware.org/libffi/). the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args_list. Creates a new closure which invokes @callback_func with @user_data as the last parameter. @destroy_data will be called as a finalize notifier on the #GClosure. a floating reference to a new #GCClosure the function to invoke user data to pass to @callback_func destroy notify to be called when @user_data is no longer used 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. a new #GCClosure the function to invoke a #GObject pointer to pass to @callback_func 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. a new #GCClosure the function to invoke a #GObject pointer to pass to @callback_func Creates a new closure which invokes @callback_func with @user_data as the first parameter. @destroy_data will be called as a finalize notifier on the #GClosure. a floating reference to a new #GCClosure the function to invoke user data to pass to @callback_func destroy notify to be called when @user_data is no longer used Check if the closure still needs a marshaller. See g_closure_set_marshal(). a #GClosure 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(). a #GClosure 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. 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). The #GTypeClass structure to finalize The @class_data member supplied via the #GTypeInfo structure 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: - Copying common members from the parent class over to the derived class structure. - Zero initialization of the remaining members not copied over from the parent class. - Invocation of the GBaseInitFunc() initializers of all parent types and the class' type. - Invocation of the class' GClassInitFunc() initializer. 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: |[<!-- language="C" --> 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"); } 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. The #GTypeClass structure to initialize. The @class_data member supplied via the #GTypeInfo structure. A #GClosure represents a callback supplied by the programmer. It will generally comprise a function of some kind and a marshaller used to call it. It is the responsibility of the marshaller to convert the arguments for the invocation from #GValues into a suitable form, perform the callback on the converted arguments, 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 #GValues and suitable representations in the runtime of the language in order to use functions written in that language as callbacks. Use g_closure_set_marshal() to set the marshaller on such a custom closure implementation. Within GObject, closures play an important role in the implementation of signals. When a signal is registered, the @c_marshaller argument to g_signal_new() specifies the default C 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 [glib-genmarshal][glib-genmarshal] 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: - 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. - 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. - g_closure_invalidate() and invalidation notifiers allow callbacks to be automatically removed when the objects they point to go away. Indicates whether the closure is currently being invoked with g_closure_invoke() Indicates whether the closure has been invalidated by g_closure_invalidate() A variant of g_closure_new_simple() which stores @object in the @data field of the closure and calls g_object_watch_closure() on @object and the created closure. This function is mainly useful when implementing new types of closures. a newly allocated #GClosure the size of the structure to allocate, must be at least `sizeof (GClosure)` a #GObject pointer to store in the @data field of the newly allocated #GClosure 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. |[<!-- language="C" --> 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; } ]| a floating reference to a new #GClosure the size of the structure to allocate, must be at least `sizeof (GClosure)` data to store in the @data field of the newly allocated #GClosure 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. a #GClosure data to pass to @notify_func the callback function to register Registers an invalidation notifier which will be called when the @closure is invalidated with g_closure_invalidate(). Invalidation notifiers are invoked before finalization notifiers, in an unspecified order. a #GClosure data to pass to @notify_func the callback function to register 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. a #GClosure data to pass to @pre_marshal_notify a function to call before the closure callback data to pass to @post_marshal_notify a function to call after the closure callback 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). #GClosure to invalidate Invokes the closure, i.e. executes the callback represented by the @closure. a #GClosure a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the length of the @param_values array an array of #GValues holding the arguments on which to invoke the callback of @closure a context-dependent invocation hint Increments the reference count on a closure to force it staying alive while the caller holds a pointer to it. The @closure passed in, for convenience #GClosure to increment the reference count on Removes a finalization notifier. Notice that notifiers are automatically removed after they are run. a #GClosure data which was passed to g_closure_add_finalize_notifier() when registering @notify_func the callback function to remove Removes an invalidation notifier. Notice that notifiers are automatically removed after they are run. a #GClosure data which was passed to g_closure_add_invalidate_notifier() when registering @notify_func the callback function to remove Sets the marshaller of @closure. The `marshal_data` of @marshal provides a way for a meta marshaller to provide additional information to the marshaller. (See g_closure_set_meta_marshal().) For GObject's C predefined marshallers (the g_cclosure_marshal_*() functions), what it provides is a callback function to use instead of @closure->callback. a #GClosure a #GClosureMarshal function Sets the meta marshaller of @closure. A meta marshaller wraps @closure->marshal and modifies the way it is called in some fashion. The most common use of this facility is for C callbacks. The same marshallers (generated by [glib-genmarshal][glib-genmarshal]), are used everywhere, but the way that we get the callback function differs. In most cases we want to use @closure->callback, but in 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 @marshal_data argument. a #GClosure context-dependent data to pass to @meta_marshal a #GClosureMarshal function Takes over the initial ownership of a closure. Each closure is initially created in a "floating" state, which means that the initial reference count is not owned by any caller. g_closure_sink() checks to see if the object is still floating, and if so, unsets the floating state and decreases the reference count. If the closure is not floating, g_closure_sink() does nothing. The reason for the existence of the floating state is to prevent cumbersome code sequences like: |[<!-- language="C" --> closure = g_cclosure_new (cb_func, cb_data); g_source_set_closure (source, closure); g_closure_unref (closure); // GObject doesn't really need this ]| Because g_source_set_closure() (and similar functions) take ownership of the initial reference count, if it is unowned, we instead can write: |[<!-- language="C" --> g_source_set_closure (source, g_cclosure_new (cb_func, cb_data)); ]| Generally, this function is used together with g_closure_ref(). An example of storing a closure for later notification looks like: |[<!-- language="C" --> static GClosure *notify_closure = NULL; void 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. #GClosure to decrement the initial reference count on, if it's still being held 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. #GClosure to decrement the reference count on The type used for marshaller functions. the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the length of the @param_values array an array of #GValues holding the arguments on which to invoke the callback of @closure the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() The type used for the various notification callbacks which can be registered on closures. data specified when registering the notification callback the #GClosure on which the notification is emitted The connection flags are used to specify the behaviour of a signal's connection. whether the handler should be called before or after the default handler of the signal. whether the instance and data should be swapped when calling the handler; see g_signal_connect_swapped() for an example. A convenience macro for emitting the usual declarations in the header file for a type which is intended to be subclassed. You might use it in a header as follows: |[ #ifndef _gtk_frobber_h_ #define _gtk_frobber_h_ #define GTK_TYPE_FROBBER gtk_frobber_get_type () GDK_AVAILABLE_IN_3_12 G_DECLARE_DERIVABLE_TYPE (GtkFrobber, gtk_frobber, GTK, FROBBER, GtkWidget) struct _GtkFrobberClass { GtkWidgetClass parent_class; void (* handle_frob) (GtkFrobber *frobber, guint n_frobs); gpointer padding[12]; }; GtkWidget * gtk_frobber_new (void); ... #endif ]| This results in the following things happening: - the usual gtk_frobber_get_type() function is declared with a return type of #GType - the GtkFrobber struct is created with GtkWidget as the first and only item. You are expected to use a private structure from your .c file to store your instance variables. - the GtkFrobberClass type is defined as a typedef to struct _GtkFrobberClass, which is left undefined. You should do this from the header file directly after you use the macro. - the GTK_FROBBER() and GTK_FROBBER_CLASS() casts are emitted as static inline functions along with the GTK_IS_FROBBER() and GTK_IS_FROBBER_CLASS() type checking functions and GTK_FROBBER_GET_CLASS() function. - g_autoptr() support being added for your type, based on the type of your parent class You can only use this function if your parent type also supports g_autoptr(). Because the type macro (GTK_TYPE_FROBBER in the above example) is not a callable, you must continue to manually define this as a macro for yourself. The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. If you are writing a library, it is important to note that it is possible to convert a type from using G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be subclassed. Once a class structure has been exposed it is not possible to change its size or remove or reorder items without breaking the API and/or ABI. If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE(). If you want to declare a class without exposing the class or instance structures, use G_DECLARE_FINAL_TYPE(). If you must use G_DECLARE_DERIVABLE_TYPE() you should be sure to include some padding at the bottom of your class structure to leave space for the addition of future virtual functions. The name of the new type, in camel case (like GtkWidget) The name of the new type in lowercase, with words separated by '_' (like 'gtk_widget') The name of the module, in all caps (like 'GTK') The bare name of the type, in all caps (like 'WIDGET') the name of the parent type, in camel case (like GtkWidget) A convenience macro for emitting the usual declarations in the header file for a type which is not (at the present time) intended to be subclassed. You might use it in a header as follows: |[ #ifndef _myapp_window_h_ #define _myapp_window_h_ #include <gtk/gtk.h> #define MY_APP_TYPE_WINDOW my_app_window_get_type () G_DECLARE_FINAL_TYPE (MyAppWindow, my_app_window, MY_APP, WINDOW, GtkWindow) MyAppWindow * my_app_window_new (void); ... #endif ]| This results in the following things happening: - the usual my_app_window_get_type() function is declared with a return type of #GType - the MyAppWindow types is defined as a typedef of struct _MyAppWindow. The struct itself is not defined and should be defined from the .c file before G_DEFINE_TYPE() is used. - the MY_APP_WINDOW() cast is emitted as static inline function along with the MY_APP_IS_WINDOW() type checking function - the MyAppWindowClass type is defined as a struct containing GtkWindowClass. This is done for the convenience of the person defining the type and should not be considered to be part of the ABI. In particular, without a firm declaration of the instance structure, it is not possible to subclass the type and therefore the fact that the size of the class structure is exposed is not a concern and it can be freely changed at any point in the future. - g_autoptr() support being added for your type, based on the type of your parent class You can only use this function if your parent type also supports g_autoptr(). Because the type macro (MY_APP_TYPE_WINDOW in the above example) is not a callable, you must continue to manually define this as a macro for yourself. The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. If you want to declare your own class structure, use G_DECLARE_DERIVABLE_TYPE(). If you are writing a library, it is important to note that it is possible to convert a type from using G_DECLARE_FINAL_TYPE() to G_DECLARE_DERIVABLE_TYPE() without breaking API or ABI. As a precaution, you should therefore use G_DECLARE_FINAL_TYPE() until you are sure that it makes sense for your class to be subclassed. Once a class structure has been exposed it is not possible to change its size or remove or reorder items without breaking the API and/or ABI. The name of the new type, in camel case (like GtkWidget) The name of the new type in lowercase, with words separated by '_' (like 'gtk_widget') The name of the module, in all caps (like 'GTK') The bare name of the type, in all caps (like 'WIDGET') the name of the parent type, in camel case (like GtkWidget) A convenience macro for emitting the usual declarations in the header file for a GInterface type. You might use it in a header as follows: |[ #ifndef _my_model_h_ #define _my_model_h_ #define MY_TYPE_MODEL my_model_get_type () GDK_AVAILABLE_IN_3_12 G_DECLARE_INTERFACE (MyModel, my_model, MY, MODEL, GObject) struct _MyModelInterface { GTypeInterface g_iface; gpointer (* get_item) (MyModel *model); }; gpointer my_model_get_item (MyModel *model); ... #endif ]| This results in the following things happening: - the usual my_model_get_type() function is declared with a return type of #GType - the MyModelInterface type is defined as a typedef to struct _MyModelInterface, which is left undefined. You should do this from the header file directly after you use the macro. - the MY_MODEL() cast is emitted as static inline functions along with the MY_IS_MODEL() type checking function and MY_MODEL_GET_IFACE() function. - g_autoptr() support being added for your type, based on your prerequisite type. You can only use this function if your prerequisite type also supports g_autoptr(). Because the type macro (MY_TYPE_MODEL in the above example) is not a callable, you must continue to manually define this as a macro for yourself. The declaration of the _get_type() function is the first thing emitted by the macro. This allows this macro to be used in the usual way with export control and API versioning macros. The name of the new type, in camel case (like GtkWidget) The name of the new type in lowercase, with words separated by '_' (like 'gtk_widget') The name of the module, in all caps (like 'GTK') The bare name of the type, in all caps (like 'WIDGET') the name of the prerequisite type, in camel case (like GtkWidget) A convenience macro for type implementations. Similar to G_DEFINE_TYPE(), but defines an abstract type. See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. 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. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. Custom code that gets inserted in the @type_name_get_type() function. Similar to G_DEFINE_TYPE_WITH_PRIVATE(), but defines an abstract type. See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. A convenience macro for boxed type implementations, which defines a type_name_get_type() function registering the boxed type. The name of the new type, in Camel case The name of the new type, in lowercase, with words separated by '_' the #GBoxedCopyFunc for the new type the #GBoxedFreeFunc for the new type A convenience macro for boxed type implementations. Similar to G_DEFINE_BOXED_TYPE(), but allows to insert custom code into the type_name_get_type() function, e.g. to register value transformations with g_value_register_transform_func(), for instance: |[<!-- language="C" --> G_DEFINE_BOXED_TYPE_WITH_CODE (GdkRectangle, gdk_rectangle, gdk_rectangle_copy, gdk_rectangle_free, register_rectangle_transform_funcs (g_define_type_id)) ]| Similarly to the %G_DEFINE_TYPE family of macros, the #GType of the newly defined boxed type is exposed in the `g_define_type_id` variable. The name of the new type, in Camel case The name of the new type, in lowercase, with words separated by '_' the #GBoxedCopyFunc for the new type the #GBoxedFreeFunc for the new type Custom code that gets inserted in the *_get_type() function A convenience macro for dynamic type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these) and a static variable named `t_n`_parent_class pointing to the parent class. Furthermore, it defines a `*_get_type()` and a static `*_register_type()` functions for use in your `module_init()`. See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. 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); } } ]| The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. #GTypeFlags to pass to g_type_module_register_type() Custom code that gets inserted in the *_get_type() function. 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 `t_n ## _default_init`, and the interface structure to have the name `TN ## Interface`. The initialization function has signature `static void t_n ## _default_init (TypeName##Interface *klass);`, rather than the full #GInterfaceInitFunc signature, for brevity and convenience. If you need to use an initialization function with an `iface_data` argument, you must write the #GTypeInterface definitions manually. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. A convenience macro for #GTypeInterface definitions. Similar to G_DEFINE_INTERFACE(), but allows you to insert custom code into the *_get_type() function, e.g. additional interface implementations via G_IMPLEMENT_INTERFACE(), or additional prerequisite types. See G_DEFINE_TYPE_EXTENDED() for a similar example using G_DEFINE_TYPE_WITH_CODE(). The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the prerequisite type for the interface, or 0 (%G_TYPE_INVALID) for no prerequisite type. Custom code that gets inserted in the *_get_type() function. A convenience macro for pointer type implementations, which defines a type_name_get_type() function registering the pointer type. The name of the new type, in Camel case The name of the new type, in lowercase, with words separated by '_' A convenience macro for pointer type implementations. Similar to G_DEFINE_POINTER_TYPE(), but allows to insert custom code into the type_name_get_type() function. The name of the new type, in Camel case The name of the new type, in lowercase, with words separated by '_' Custom code that gets inserted in the *_get_type() function A convenience macro for type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these) and a static variable named `t_n_parent_class` pointing to the parent class. Furthermore, it defines a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. The most general convenience macro for type implementations, on which G_DEFINE_TYPE(), etc are based. |[<!-- language="C" --> G_DEFINE_TYPE_EXTENDED (GtkGadget, gtk_gadget, GTK_TYPE_WIDGET, 0, G_ADD_PRIVATE (GtkGadget) G_IMPLEMENT_INTERFACE (TYPE_GIZMO, gtk_gadget_gizmo_init)); ]| expands to |[<!-- language="C" --> static void gtk_gadget_init (GtkGadget *self); static void gtk_gadget_class_init (GtkGadgetClass *klass); static gpointer gtk_gadget_parent_class = NULL; static gint GtkGadget_private_offset; static void gtk_gadget_class_intern_init (gpointer klass) { gtk_gadget_parent_class = g_type_class_peek_parent (klass); if (GtkGadget_private_offset != 0) g_type_class_adjust_private_offset (klass, &GtkGadget_private_offset); gtk_gadget_class_init ((GtkGadgetClass*) klass); } static inline gpointer gtk_gadget_get_instance_private (GtkGadget *self) { return (G_STRUCT_MEMBER_P (self, GtkGadget_private_offset)); } 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, 0); { GtkGadget_private_offset = g_type_add_instance_private (g_define_type_id, sizeof (GtkGadgetPrivate)); } { 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. The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. #GTypeFlags to pass to g_type_register_static() 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. The name of the new type, in Camel case. The name of the new type in lowercase, with words separated by '_'. The #GType of the parent type. Custom code that gets inserted in the *_get_type() function. A convenience macro for type implementations, which declares a class initialization function, an instance initialization function (see #GTypeInfo for information about these), a static variable named `t_n_parent_class` pointing to the parent class, and adds private instance data to the type. Furthermore, it defines a *_get_type() function. See G_DEFINE_TYPE_EXTENDED() for an example. Note that private structs added with this macros must have a struct name of the form @TN Private. The private instance data can be retrieved using the automatically generated getter function `t_n_get_instance_private()`. See also: G_ADD_PRIVATE() The name of the new type, in Camel case. The name of the new type, in lowercase, with words separated by '_'. The #GType of the parent type. Casts a derived #GEnumClass structure into a #GEnumClass structure. a valid #GEnumClass Get the type identifier from a given #GEnumClass structure. a #GEnumClass Get the static type name from a given #GEnumClass structure. a #GEnumClass The class of an enumeration type holds information about its possible values. the parent class the smallest possible value. the largest possible value. the number of possible values. an array of #GEnumValue structs describing the individual values. A structure which contains a single enum value, its name, and its nickname. the enum value the name of the value the nickname of the value Casts a derived #GFlagsClass structure into a #GFlagsClass structure. a valid #GFlagsClass Get the type identifier from a given #GFlagsClass structure. a #GFlagsClass Get the static type name from a given #GFlagsClass structure. a #GFlagsClass The class of a flags type holds information about its possible values. the parent class a mask covering all possible values. the number of possible values. an array of #GFlagsValue structs describing the individual values. A structure which contains a single flags value, its name, and its nickname. the flags value the name of the value the nickname of the value 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. The #GType of the interface to add The interface init function, of type #GInterfaceInitFunc 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. The #GType of the interface to add The interface init function 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. Object which is subject to casting. Casts a derived #GInitiallyUnownedClass structure into a #GInitiallyUnownedClass structure. a valid #GInitiallyUnownedClass Get the class structure associated to a #GInitiallyUnowned instance. a #GInitiallyUnowned instance. Checks whether @class "is a" valid #GEnumClass structure of type %G_TYPE_ENUM or derived. a #GEnumClass Checks whether @class "is a" valid #GFlagsClass structure of type %G_TYPE_FLAGS or derived. a #GFlagsClass Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED. Instance to check for being a %G_TYPE_INITIALLY_UNOWNED. Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type %G_TYPE_INITIALLY_UNOWNED or derived. a #GInitiallyUnownedClass Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. Instance to check for being a %G_TYPE_OBJECT. Checks whether @class "is a" valid #GObjectClass structure of type %G_TYPE_OBJECT or derived. a #GObjectClass Checks whether @pspec "is a" valid #GParamSpec structure of type %G_TYPE_PARAM or derived. a #GParamSpec Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOOLEAN. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_BOXED. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_CHAR. a valid #GParamSpec instance Checks whether @pclass "is a" valid #GParamSpecClass structure of type %G_TYPE_PARAM or derived. a #GParamSpecClass Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_DOUBLE. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ENUM. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLAGS. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_FLOAT. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_GTYPE. a #GParamSpec Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_INT64. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_LONG. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_OVERRIDE. a #GParamSpec Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_PARAM. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_POINTER. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_STRING. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UCHAR. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UINT64. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_ULONG. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_UNICHAR. a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VALUE_ARRAY. Use #GArray instead of #GValueArray a valid #GParamSpec instance Checks whether the given #GParamSpec is of type %G_TYPE_PARAM_VARIANT. a #GParamSpec Checks if @value is a valid and initialized #GValue structure. A #GValue structure. All the fields in the GInitiallyUnowned structure are private to the #GInitiallyUnowned implementation and should never be accessed directly. The class structure for the GInitiallyUnowned type. the parent class a #GObject 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. The extended members of @instance are guaranteed to have been filled with zeros before this function is called. The instance to initialize The class of the type the instance is created for 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. The interface structure to finalize The @interface_data supplied via the #GInterfaceInfo structure A structure that provides information to the type system which is used specifically for managing interface types. location of the interface initialization function location of the interface finalization function user-supplied data passed to the interface init/finalize functions 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 members of @iface_data are guaranteed to have been filled with zeros before this function is called. The interface structure to initialize The @interface_data supplied via the #GInterfaceInfo structure 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. Object which is subject to casting. Casts a derived #GObjectClass structure into a #GObjectClass structure. a valid #GObjectClass Return the name of a class structure's type. a valid #GObjectClass Get the type id of a class structure. a valid #GObjectClass Get the class structure associated to a #GObject instance. a #GObject instance. Get the type id of an object. Object to return the type id for. Get the name of an object's type. Object to return the type name for. This macro should be used to emit a standard warning about unexpected properties in set_property() and get_property() implementations. the #GObject on which set_property() or get_property() was called the numeric id of the property the #GParamSpec of the property All the fields in the GObject structure are private to the #GObject implementation and should never be accessed directly. 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. Any private data for the object is guaranteed to be initialized with zeros, as per g_type_create_instance(). Note that in C, small integer types in variable argument lists are promoted up to #gint or #guint as appropriate, and read back accordingly. #gint is 32 bits on every platform on which GLib is currently supported. This means that you can use C expressions of type #gint with g_object_new() and properties of type #gint or #guint or smaller. Specifically, you can use integer literals with these property types. When using property types of #gint64 or #guint64, you must ensure that the value that you provide is 64 bit. This means that you should use a cast or make use of the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. Similarly, #gfloat is promoted to #gdouble, so you must ensure that the value you provide is a #gdouble, even for a property of type #gfloat. a new instance of @object_type the type id of the #GObject subtype to instantiate 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. a new instance of @object_type the type id of the #GObject subtype to instantiate 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 using the provided arrays. Both arrays must have exactly @n_properties elements, and the names and values correspond by index. Construction parameters (see %G_PARAM_CONSTRUCT, %G_PARAM_CONSTRUCT_ONLY) which are not explicitly specified are set to their default values. a new instance of @object_type the object type to instantiate the number of properties the names of each property to be set the values of each property to be set 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. Use g_object_new_with_properties() instead. deprecated. See #GParameter for more information. a new instance of @object_type the type id of the #GObject subtype to instantiate the length of the @parameters array an array of #GParameter 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(). the #GParamSpec for the property of the interface with the name @property_name, or %NULL if no such property exists. any interface vtable for the interface, or the default vtable for the interface name of a property to look up. 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. If @pspec is a floating reference, it will be consumed. any interface vtable for the interface, or the default vtable for the interface. the #GParamSpec for the new property 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(). a 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. any interface vtable for the interface, or the default vtable for the interface location to store number of properties returned. 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. Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called. a #GObject 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 paired references: the strong reference added by 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 @object, a strong reference is held. The @notify callback is called when the reference from @object to the proxy object should be "toggled" 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_add_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. a #GObject a function to call when this reference is the last reference to the object, or is no longer the last reference. data to pass to @notify 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, @weak_pointer will be set to %NULL. Note that as with g_object_weak_ref(), the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use #GWeakRef if thread-safety is required. The object that should be weak referenced. The memory address of a pointer. Creates a binding between @source_property on @source and @target_property on @target. Whenever the @source_property is changed the @target_property is updated using the same value. For instance: |[ g_object_bind_property (action, "active", widget, "sensitive", 0); ]| Will result in the "sensitive" property of the widget #GObject instance to be updated with the same value of the "active" property of the action #GObject instance. 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 binding will automatically be removed when either the @source or the @target instances are finalized. To remove the binding without affecting the @source and the @target you can just call g_object_unref() on the returned #GBinding instance. A #GObject can have multiple bindings. the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. the source #GObject the property on @source to bind the target #GObject the property on @target to bind flags to pass to #GBinding 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 @target instances are finalized. This will release the reference that is being held on the #GBinding instance; if you want to hold on to the #GBinding instance, you will need to hold a reference to it. To remove the binding, call g_binding_unbind(). A #GObject can have multiple bindings. 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. the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. the source #GObject the property on @source to bind the target #GObject the property on @target to bind flags to pass to #GBinding the transformation function from the @source to the @target, or %NULL to use the default the transformation function from the @target to the @source, or %NULL to use the default custom data to be passed to the transformation functions, or %NULL a function to call when disposing the binding, to free resources used by the transformation functions, or %NULL if not required 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 #GClosures instead of function pointers. the #GBinding instance representing the binding between the two #GObject instances. The binding is released whenever the #GBinding reference count reaches zero. the source #GObject the property on @source to bind the target #GObject the property on @target to bind flags to pass to #GBinding a #GClosure wrapping the transformation function from the @source to the @target, or %NULL to use the default a #GClosure wrapping the transformation function from the @target to the @source, or %NULL to use the default A convenience function to connect multiple signals at once. The signal specs expected by this function have the form "modifier::signal_name", where modifier can be one of the following: - signal: equivalent to g_signal_connect_data (..., NULL, 0) - object-signal, object_signal: equivalent to g_signal_connect_object (..., 0) - swapped-signal, swapped_signal: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED) - swapped_object_signal, swapped-object-signal: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED) - signal_after, signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_AFTER) - object_signal_after, object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_AFTER) - swapped_signal_after, swapped-signal-after: equivalent to g_signal_connect_data (..., NULL, G_CONNECT_SWAPPED | G_CONNECT_AFTER) - swapped_object_signal_after, swapped-object-signal-after: equivalent to g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER) |[<!-- language="C" --> menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW, "type", GTK_WINDOW_POPUP, "child", menu, NULL), "signal::event", gtk_menu_window_event, menu, "signal::size_request", gtk_menu_window_size_request, menu, "signal::destroy", gtk_widget_destroyed, &menu->toplevel, NULL); ]| @object a #GObject 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 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". a #GObject 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 This is a variant of g_object_get_data() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the @key is not set on the object then @dup_func will be called with a %NULL argument. Note that @dup_func is called while user data of @object is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. the result of calling @dup_func on the value associated with @key on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. the #GObject to store user data on a string, naming the user data pointer function to dup the value passed as user_data to @dup_func This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value. @dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the @quark is not set on the object then @dup_func will be called with a %NULL argument. Note that @dup_func is called while user data of @object is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. the result of calling @dup_func on the value associated with @quark on @object, or %NULL if not set. If @dup_func is %NULL, the value is returned unmodified. the #GObject to store user data on a #GQuark, naming the user data pointer function to dup the value passed as user_data to @dup_func This function is intended for #GObject implementations to re-enforce a [floating][floating-ref] object reference. Doing this is seldom required: all #GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink(). a #GObject 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. Duplicate notifications are squashed so that at most one #GObject::notify signal is emitted for each property modified while the object is frozen. This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified. a #GObject 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(). Here is an example of using g_object_get() to get the contents of three properties: an integer, a string and an object: |[<!-- language="C" --> gint intval; guint64 uint64val; gchar *strval; GObject *objval; g_object_get (my_object, "int-property", &intval, "uint64-property", &uint64val, "str-property", &strval, "obj-property", &objval, NULL); // Do something with intval, uint64val, strval, objval g_free (strval); g_object_unref (objval); ]| a #GObject name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Gets a named field from the objects table of associations (see g_object_set_data()). the data if found, or %NULL if no such data exists. #GObject containing the associations name of the key for that association Gets a property of an object. The @value can be: - an empty #GValue initialized by %G_VALUE_INIT, which will be automatically initialized with the expected type of the property (since GLib 2.60) - a #GValue initialized with the expected type of the property - a #GValue initialized with a type to which the expected type of the property can be transformed 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 #GObject the name of the property to get return location for the property value This function gets back user data pointers stored via g_object_set_qdata(). The user data pointer set, or %NULL The GObject to get a stored user data pointer from A #GQuark, naming the user data pointer 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(). a #GObject name of the first property to get return location for the first property, followed optionally by more name/return location pairs, followed by %NULL Gets @n_properties properties for an @object. Obtained properties will be set to @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in. a #GObject the number of properties the names of each property to get the values of each property to get Checks whether @object has a [floating][floating-ref] reference. %TRUE if @object has a floating reference a #GObject 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. Note that emission of the notify signal may be blocked with g_object_freeze_notify(). In this case, the signal emissions are queued and will be emitted (in reverse order) when g_object_thaw_notify() is called. a #GObject the name of a property installed on the class of @object. 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.: |[<!-- language="C" --> 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: |[<!-- language="C" --> g_object_notify_by_pspec (self, properties[PROP_FOO]); ]| a #GObject the #GParamSpec of a property installed on the class of @object. Increases the reference count of @object. Since GLib 2.56, if `GLIB_VERSION_MAX_ALLOWED` is 2.56 or greater, the type of @object will be propagated to the return type (using the GCC typeof() extension), so any casting the caller needs to do on the return type must be explicit. the same @object a #GObject Increase the reference count of @object, and possibly remove the [floating][floating-ref] 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 GLib 2.56, the type of @object will be propagated to the return type under the same conditions as for g_object_ref(). @object a #GObject Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one. a #GObject a function to call when this reference is the last reference to the object, or is no longer the last reference. data to pass to @notify 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(). The object that is weak referenced. The memory address of a pointer. Compares the user data for the key @key on @object with @oldval, and if they are the same, replaces @oldval with @newval. This is like a typical atomic compare-and-exchange operation, for user data on an object. If the previous value was replaced then ownership of the old value (@oldval) is passed to the caller, including the registered destroy notify for it (passed out in @old_destroy). It’s up to the caller to free this as needed, which may or may not include using @old_destroy as sometimes replacement should not destroy the object in the normal way. See g_object_set_data() for guidance on using a small, bounded set of values for @key. %TRUE if the existing value for @key was replaced by @newval, %FALSE otherwise. the #GObject to store user data on a string, naming the user data pointer the old value to compare against the new value a destroy notify for the new value destroy notify for the existing value Compares the user data for the key @quark on @object with @oldval, and if they are the same, replaces @oldval with @newval. This is like a typical atomic compare-and-exchange operation, for user data on an object. If the previous value was replaced then ownership of the old value (@oldval) is passed to the caller, including the registered destroy notify for it (passed out in @old_destroy). It’s up to the caller to free this as needed, which may or may not include using @old_destroy as sometimes replacement should not destroy the object in the normal way. %TRUE if the existing value for @quark was replaced by @newval, %FALSE otherwise. the #GObject to store user data on a #GQuark, naming the user data pointer the old value to compare against the new value a destroy notify for the new value destroy notify for the existing value Releases all references to other objects. This can be used to break reference cycles. This function should only be called from object system implementations. a #GObject Sets properties on an object. The same caveats about passing integer literals as varargs apply as with g_object_new(). In particular, any integer literals set as the values for properties of type #gint64 or #guint64 must be 64 bits wide, using the %G_GINT64_CONSTANT or %G_GUINT64_CONSTANT macros. Note that the "notify" signals are queued and only emitted (in reverse order) after all properties have been set. See g_object_freeze_notify(). a #GObject name of the first property to set value for the first property, followed optionally by more name/value pairs, followed by %NULL 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. Internally, the @key is converted to a #GQuark using g_quark_from_string(). This means a copy of @key is kept permanently (even after @object has been finalized) — so it is recommended to only use a small, bounded set of values for @key in your program, to avoid the #GQuark storage growing unbounded. #GObject containing the associations. name of the key data to associate with that key 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. #GObject containing the associations name of the key data to associate with that key function to call when the association is destroyed Sets a property on an object. a #GObject the name of the property to set the value This sets an opaque, named pointer on an object. 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 @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. The GObject to set store a user data pointer A #GQuark, naming the user data pointer An opaque user data pointer 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. The GObject to set store a user data pointer A #GQuark, naming the user data pointer An opaque user data pointer Function to invoke with @data as argument, when @data needs to be freed Sets properties on an object. a #GObject name of the first property to set value for the first property, followed optionally by more name/value pairs, followed by %NULL Sets @n_properties properties for an @object. Properties to be set will be taken from @values. All properties must be valid. Warnings will be emitted and undefined behaviour may result if invalid properties are passed in. a #GObject the number of properties the names of each property to be set the values of each property to be set Remove a specified datum from the object's data associations, without invoking the association's destroy handler. the data if found, or %NULL if no such data exists. #GObject containing the associations name of the key 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: |[<!-- language="C" --> 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"); // retrieve 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(). The user data pointer set, or %NULL The GObject to get a stored user data pointer from A #GQuark, naming the user data pointer Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on @object and when it reaches zero, queued "notify" signals are emitted. Duplicate notifications for each property are squashed so that at most one #GObject::notify signal is emitted for each property, in the reverse order in which they have been queued. It is an error to call this function when the freeze count is zero. a #GObject Decreases the reference count of @object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed). If the pointer to the #GObject may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to %NULL rather than retain a dangling pointer to a potentially invalid #GObject instance. Use g_clear_object() for this. a #GObject 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 @closure. Usually, this function will be called on closures that use this @object as closure data. #GObject restricting lifetime of @closure #GClosure to watch 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). Note that the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use #GWeakRef if thread-safety is required. #GObject to reference weakly callback to invoke before the object is freed extra data to pass to notify Removes a weak reference callback to an object. #GObject to remove a weak reference from callback to search for data to search for The notify signal is emitted on an object when one of its properties has its value set through g_object_set_property(), g_object_set(), et al. Note that getting this signal doesn’t itself guarantee that the value of the property has actually changed. When it is emitted is determined by the derived GObject class. If the implementor did not create the property with %G_PARAM_EXPLICIT_NOTIFY, then any call to g_object_set_property() results in ::notify being emitted, even if the new value is the same as the old. If they did pass %G_PARAM_EXPLICIT_NOTIFY, then this signal is emitted only when they explicitly call g_object_notify() or g_object_notify_by_pspec(), and common practice is to do that only when the value has actually changed. This signal is typically used to obtain change notification for a single property, by specifying the property name as a detail in the g_signal_connect() call, like this: |[<!-- language="C" --> g_signal_connect (text_view->buffer, "notify::paste-target-list", G_CALLBACK (gtk_text_view_target_list_notify), text_view) ]| It is important to note that you must use [canonical parameter names][canonical-parameter-names] as detail strings for the notify signal. the #GParamSpec of the property which changed. The class structure for the GObject type. |[<!-- language="C" --> // Example of implementing a singleton using a constructor. 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; } ]| the parent class a #GObject Looks up the #GParamSpec for a property of a class. the #GParamSpec for the property, or %NULL if the class doesn't have a property of that name a #GObjectClass the name of the property to look up Installs new properties from an array of #GParamSpecs. All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not recommend, and specifically, is not guaranteed to be thread-safe vs. use of properties on the same type on other threads. 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 #GParamSpecs and g_object_notify_by_pspec(). For instance, this class initialization: |[<!-- language="C" --> 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: |[<!-- language="C" --> 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]); } } ]| a #GObjectClass the length of the #GParamSpecs array the #GParamSpecs array defining the new properties Installs a new property. All properties should be installed during the class initializer. It is possible to install properties after that, but doing so is not recommend, and specifically, is not guaranteed to be thread-safe vs. use of properties on the same type on other threads. 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. a #GObjectClass the id for the new property the #GParamSpec for the new property Get an array of #GParamSpec* for all properties of a class. an array of #GParamSpec* which should be freed after use a #GObjectClass return location for the length of the returned array 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 "override" a property implementation in a parent class or to provide the implementation of a property from an interface. 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(). a #GObjectClass the new property ID the name of a property registered in a parent class or in an interface of this class. The GObjectConstructParam struct is an auxiliary structure used to hand #GParamSpec/#GValue pairs to the @constructor of a #GObjectClass. the #GParamSpec of the construct parameter the value to set the parameter to The type of the @finalize function of #GObjectClass. the #GObject being finalized The type of the @get_property function of #GObjectClass. a #GObject the numeric id under which the property was registered with g_object_class_install_property(). a #GValue to return the property value in the #GParamSpec describing the property The type of the @set_property function of #GObjectClass. a #GObject the numeric id under which the property was registered with g_object_class_install_property(). the new value for the property the #GParamSpec describing the property Mask containing the bits of #GParamSpec.flags which are reserved for GLib. Casts a derived #GParamSpec object (e.g. of type #GParamSpecInt) into a #GParamSpec object. a valid #GParamSpec Cast a #GParamSpec instance into a #GParamSpecBoolean. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecBoxed. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecChar. a valid #GParamSpec instance Casts a derived #GParamSpecClass structure into a #GParamSpecClass structure. a valid #GParamSpecClass Cast a #GParamSpec instance into a #GParamSpecDouble. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecEnum. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecFlags. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecFloat. a valid #GParamSpec instance Retrieves the #GParamSpecClass of a #GParamSpec. a valid #GParamSpec Casts a #GParamSpec into a #GParamSpecGType. a #GParamSpec Cast a #GParamSpec instance into a #GParamSpecInt. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecInt64. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecLong. a valid #GParamSpec instance Casts a #GParamSpec instance into a #GParamSpecObject. a valid #GParamSpec instance Casts a #GParamSpec into a #GParamSpecOverride. a #GParamSpec Casts a #GParamSpec instance into a #GParamSpecParam. a valid #GParamSpec instance Casts a #GParamSpec instance into a #GParamSpecPointer. a valid #GParamSpec instance Casts a #GParamSpec instance into a #GParamSpecString. a valid #GParamSpec instance Retrieves the #GType of this @pspec. a valid #GParamSpec Retrieves the #GType name of this @pspec. a valid #GParamSpec Cast a #GParamSpec instance into a #GParamSpecUChar. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecUInt. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecUInt64. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecULong. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecUnichar. a valid #GParamSpec instance Cast a #GParamSpec instance into a #GParamSpecValueArray. Use #GArray instead of #GValueArray a valid #GParamSpec instance Retrieves the #GType to initialize a #GValue for this parameter. a valid #GParamSpec Casts a #GParamSpec into a #GParamSpecVariant. a #GParamSpec #GParamFlags value alias for %G_PARAM_STATIC_NAME | %G_PARAM_STATIC_NICK | %G_PARAM_STATIC_BLURB. Since 2.13.0 Minimum shift count to be used for user defined flags, to be stored in #GParamSpec.flags. The maximum allowed is 10. Evaluates to the @field_name inside the @inst private data structure for @TypeName. Note that this macro can only be used together with the G_DEFINE_TYPE_* and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. the name of the type in CamelCase the instance of @TypeName you wish to access the type of the field in the private data structure the name of the field in the private data structure Evaluates to a pointer to the @field_name inside the @inst private data structure for @TypeName. Note that this macro can only be used together with the G_DEFINE_TYPE_* and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. the name of the type in CamelCase the instance of @TypeName you wish to access the name of the field in the private data structure Evaluates to the offset of the @field inside the instance private data structure for @TypeName. Note that this macro can only be used together with the G_DEFINE_TYPE_* and G_ADD_PRIVATE() macros, since it depends on variable names from those macros. the name of the type in CamelCase the name of the field in the private data structure Through the #GParamFlags flag values, certain aspects of parameters can be configured. See also #G_PARAM_STATIC_STRINGS. the parameter is readable the parameter is writable alias for %G_PARAM_READABLE | %G_PARAM_WRITABLE the parameter will be set upon object construction the parameter can only be set upon object construction upon parameter conversion (see g_param_value_convert()) strict validation is not required 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 internal 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 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 calls to g_object_set_property() for this property will not automatically result in a "notify" signal being emitted: the implementation must call g_object_notify() themselves in case the property actually changes. Since: 2.42. 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 #GParamSpec is an object structure that encapsulates the metadata required to specify parameters, such as e.g. #GObject properties. ## Parameter names # {#canonical-parameter-names} A property name consists of one or more segments consisting of ASCII letters and digits, separated by either the `-` or `_` character. The first character of a property name must be a letter. These are the same rules as for signal naming (see g_signal_new()). When creating and looking up a #GParamSpec, either separator can be used, but they cannot be mixed. Using `-` is considerably more efficient, and is the ‘canonical form’. Using `_` is discouraged. Creates a new #GParamSpec instance. See [canonical parameter names][canonical-parameter-names] for details of the rules for @name. Names which violate these rules lead to undefined behaviour. Beyond the name, #GParamSpecs 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 @blurb, which should be a somewhat longer description, suitable for e.g. a tooltip. The @nick and @blurb should ideally be localized. a newly allocated #GParamSpec instance the #GType for the property; must be derived from #G_TYPE_PARAM the canonical name of the property the nickname of the property a short description of the property a combination of #GParamFlags Validate a property name for a #GParamSpec. This can be useful for dynamically-generated properties which need to be validated at run-time before actually trying to create them. See [canonical parameter names][canonical-parameter-names] for details of the rules for valid names. %TRUE if @name is a valid property name, %FALSE otherwise. the canonical name of the property Get the short description of a #GParamSpec. the short description of @pspec. a valid #GParamSpec Gets the default value of @pspec as a pointer to a #GValue. The #GValue will remain valid for the life of @pspec. a pointer to a #GValue which must not be modified a #GParamSpec Get the name of a #GParamSpec. The name is always an "interned" string (as per g_intern_string()). This allows for pointer-value comparisons. the name of @pspec. a valid #GParamSpec Gets the GQuark for the name. the GQuark for @pspec->name. a #GParamSpec Get the nickname of a #GParamSpec. the nickname of @pspec. a valid #GParamSpec Gets back user data pointers stored via g_param_spec_set_qdata(). the user data pointer set, or %NULL a valid #GParamSpec a #GQuark, naming the user data pointer 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 to which requests on this paramspec should be redirected, or %NULL if none. a #GParamSpec Increments the reference count of @pspec. the #GParamSpec that was passed into this function a valid #GParamSpec Convenience function to ref and sink a #GParamSpec. the #GParamSpec that was passed into this function a valid #GParamSpec 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. the #GParamSpec to set store a user data pointer a #GQuark, naming the user data pointer an opaque user data pointer This function works like g_param_spec_set_qdata(), but in addition, a `void (*destroy) (gpointer)` 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. the #GParamSpec to set store a user data pointer a #GQuark, naming the user data pointer an opaque user data pointer function to invoke with @data as argument, when @data needs to be freed 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 `g_param_spec_ref (pspec); g_param_spec_sink (pspec);` 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). a valid #GParamSpec 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. the user data pointer set, or %NULL the #GParamSpec to get a stored user data pointer from a #GQuark, naming the user data pointer Decrements the reference count of a @pspec. a valid #GParamSpec private #GTypeInstance portion name of this parameter: always an interned string #GParamFlags flags for this parameter the #GValue type for this parameter #GType type that uses (introduces) this parameter A #GParamSpec derived structure that contains the meta data for boolean properties. private #GParamSpec portion default value for the property specified A #GParamSpec derived structure that contains the meta data for boxed properties. private #GParamSpec portion A #GParamSpec derived structure that contains the meta data for character properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified The class structure for the GParamSpec type. Normally, GParamSpec classes are filled by g_param_type_register_static(). the parent class the #GValue type for this parameter A #GParamSpec derived structure that contains the meta data for double properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-90. A #GParamSpec derived structure that contains the meta data for enum properties. private #GParamSpec portion the #GEnumClass for the enum default value for the property specified A #GParamSpec derived structure that contains the meta data for flags properties. private #GParamSpec portion the #GFlagsClass for the flags default value for the property specified A #GParamSpec derived structure that contains the meta data for float properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified values closer than @epsilon will be considered identical by g_param_values_cmp(); the default value is 1e-30. A #GParamSpec derived structure that contains the meta data for #GType properties. private #GParamSpec portion a #GType whose subtypes can occur as values A #GParamSpec derived structure that contains the meta data for integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for 64bit integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for long integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for object properties. private #GParamSpec portion This is a type of #GParamSpec type that simply redirects operations to another paramspec. All operations other than getting or setting the value are redirected, including accessing the nick and blurb, validating a value, and so forth. See g_param_spec_get_redirect_target() for retrieving the overridden 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. A #GParamSpec derived structure that contains the meta data for %G_TYPE_PARAM properties. private #GParamSpec portion A #GParamSpec derived structure that contains the meta data for pointer properties. private #GParamSpec portion A #GParamSpecPool maintains a collection of #GParamSpecs which can be quickly accessed by owner and name. The implementation of the #GObject property system uses such a pool to store the #GParamSpecs of the properties all object types. Inserts a #GParamSpec in the pool. a #GParamSpecPool. the #GParamSpec to insert a #GType identifying the owner of @pspec Gets an array of all #GParamSpecs owned by @owner_type in the pool. a newly allocated array containing pointers to all #GParamSpecs owned by @owner_type in the pool a #GParamSpecPool the owner to look for return location for the length of the returned array Gets an #GList of all #GParamSpecs owned by @owner_type in the pool. a #GList of all #GParamSpecs owned by @owner_type in the pool#GParamSpecs. a #GParamSpecPool the owner to look for Looks up a #GParamSpec in the pool. The found #GParamSpec, or %NULL if no matching #GParamSpec was found. a #GParamSpecPool the name to look for the owner to look for If %TRUE, also try to find a #GParamSpec with @param_name owned by an ancestor of @owner_type. Removes a #GParamSpec from the pool. a #GParamSpecPool the #GParamSpec to remove 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 newly allocated #GParamSpecPool. Whether the pool will support type-prefixed property names. A #GParamSpec derived structure that contains the meta data for string properties. private #GParamSpec portion default value for the property specified a string containing the allowed values for the first byte a string containing the allowed values for the subsequent bytes the replacement byte for bytes which don't match @cset_first or @cset_nth. replace empty string by %NULL replace %NULL strings by an empty string 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(). Size of the instance (object) structure. 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 [slice allocator][glib-Memory-Slices] now. The #GType of values conforming to this #GParamSpec A #GParamSpec derived structure that contains the meta data for unsigned character properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for unsigned integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for unsigned 64bit integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for unsigned long integer properties. private #GParamSpec portion minimum value for the property specified maximum value for the property specified default value for the property specified A #GParamSpec derived structure that contains the meta data for unichar (unsigned integer) properties. private #GParamSpec portion default value for the property specified A #GParamSpec derived structure that contains the meta data for #GValueArray properties. private #GParamSpec portion a #GParamSpec describing the elements contained in arrays of this property, may be %NULL if greater than 0, arrays of this property will always have this many elements A #GParamSpec derived structure that contains the meta data for #GVariant properties. When comparing values with g_param_values_cmp(), scalar values with the same type will be compared with g_variant_compare(). Other non-%NULL variants will be checked for equality with g_variant_equal(), and their sort order is otherwise undefined. %NULL is ordered before non-%NULL variants. Two %NULL values compare equal. private #GParamSpec portion a #GVariantType, or %NULL a #GVariant, or %NULL The GParameter struct is an auxiliary structure used to hand parameter name/value pairs to g_object_newv(). This type is not introspectable. the parameter name the parameter value A mask for all #GSignalFlags bits. A mask for all #GSignalMatchType bits. 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. The accumulator function returns whether the signal emission should be aborted. Returning %FALSE means to abort the current emission and %TRUE is returned for continuation. Signal invocation hint, see #GSignalInvocationHint. Accumulator to collect callback return values in, this is the return value of the current signal emission. A #GValue holding the return value of the signal handler. Callback data that was specified when creating the signal. 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. whether it wants to stay connected. If it returns %FALSE, the signal hook is disconnected (and destroyed). Signal invocation hint, see #GSignalInvocationHint. the number of parameters to the function, including the instance on which the signal was emitted. the instance on which the signal was emitted, followed by the parameters of the emission. user data associated with the hook. 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. Invoke the object method handler in the first emission stage. Invoke the object method handler in the third emission stage. Invoke the object method handler in the last emission stage. 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. This signal supports "::detail" appendices to the signal name upon handler connections and emissions. 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. No emissions hooks are supported for this signal. Varargs signal emission will always collect the arguments, even if there are no signal handlers connected. Since 2.30. The signal is deprecated and will be removed in a future version. A warning will be generated if it is connected while running with G_ENABLE_DIAGNOSTIC=1. Since 2.32. The #GSignalInvocationHint structure is used to pass on additional information to callbacks during a signal emission. The signal id of the signal invoking the callback The detail passed on for this emission The stage the signal emission is currently in, this field will contain one of %G_SIGNAL_RUN_FIRST, %G_SIGNAL_RUN_LAST or %G_SIGNAL_RUN_CLEANUP. The match types specify what g_signal_handlers_block_matched(), g_signal_handlers_unblock_matched() and g_signal_handlers_disconnect_matched() match signals by. The signal id must be equal. The signal detail must be equal. The closure must be the same. The C closure callback must be the same. The closure data must be the same. Only unblocked signals may be matched. A structure holding in-depth information for a specific signal. It is filled in by the g_signal_query() function. The signal id of the signal being queried, or 0 if the signal to be queried was unknown. The signal name. The interface/instance type that this signal can be emitted for. The signal flags as passed in to g_signal_new(). The return type for user callbacks. The number of parameters that user callbacks take. The individual parameter types for user callbacks, note that the effective callback signature is: |[<!-- language="C" --> @return_type callback (#gpointer data1, [param_types param_names,] gpointer data2); ]| 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. %NULL is not a valid class structure. This macro should only be used in type implementations. Location of a #GTypeClass structure The type to be returned The corresponding C type of class structure of @g_type Checks if @g_class is a class structure of the type identified by @g_type. If @g_class is %NULL, %FALSE will be returned. This macro should only be used in type implementations. Location of a #GTypeClass structure The type to be checked Checks if @instance is a valid #GTypeInstance structure, otherwise issues a warning and returns %FALSE. %NULL is not a valid #GTypeInstance. This macro should only be used in type implementations. Location of a #GTypeInstance structure 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. No warning will be issued if @instance is %NULL, and %NULL will be returned. This macro should only be used in type implementations. Location of a #GTypeInstance structure The type to be returned The corresponding C type of @g_type Checks if @instance is an instance of the fundamental type identified by @g_type. If @instance is %NULL, %FALSE will be returned. This macro should only be used in type implementations. Location of a #GTypeInstance structure. The fundamental type to be checked Checks if @instance is an instance of the type identified by @g_type. If @instance is %NULL, %FALSE will be returned. This macro should only be used in type implementations. Location of a #GTypeInstance structure. The type to be checked Checks if @value has been initialized to hold values of a value type. This macro should only be used in type implementations. a #GValue Checks if @value has been initialized to hold values of type @g_type. This macro should only be used in type implementations. a #GValue The type to be checked 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. the class of a type deriving from @private_type the type identifying which private data to retrieve The C type for the private structure A bit in the type number that's supposed to be left untouched. Get the type identifier from a given @class structure. This macro should only be used in type implementations. Location of a valid #GTypeClass structure Get the type identifier from a given @instance structure. This macro should only be used in type implementations. Location of a valid #GTypeInstance structure Get the type identifier from a given @interface structure. This macro should only be used in type implementations. Location of a valid #GTypeInterface structure 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 #GType value. An integer constant that represents the number of identifiers reserved for types that are assigned at compile-time. Shift value used in converting numbers to type IDs. Checks if @type has a #GTypeValueTable. A #GType value 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. Location of the #GTypeInstance structure The #GType of the class to be returned The C type of the class structure Get the interface structure for interface @g_type of a given @instance. This macro should only be used in type implementations. Location of the #GTypeInstance structure The #GType of the interface to be returned The C type of the interface structure 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. Use %G_ADD_PRIVATE and the generated `your_type_get_instance_private()` function instead the instance of a type deriving from @private_type the type identifying which private data to retrieve The C type for the private structure Checks if @type is an abstract type. An abstract type cannot be instantiated and is normally used as an abstract base class for derived classes. A #GType value Checks if @type is a classed type. A #GType value 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. A #GType value Checks if @type is a derivable type. A derivable type can be used as the base class of a flat (single-level) class hierarchy. A #GType value Checks if @type is derived (or in object-oriented terminology: inherited) from another type (this holds true for all non-fundamental types). A #GType value Checks whether @type "is a" %G_TYPE_ENUM. a #GType ID. Checks whether @type "is a" %G_TYPE_FLAGS. a #GType ID. Checks if @type is a fundamental type. A #GType value Checks if @type can be instantiated. Instantiation is the process of creating an instance (object) of this type. A #GType value 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). A #GType value Check if the passed in type id is a %G_TYPE_OBJECT or derived from it. Type id to check Checks whether @type "is a" %G_TYPE_PARAM. a #GType ID 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. 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. A #GType value Checks if @type is a value type and can be used with g_value_init(). A #GType value Get the type ID for the fundamental type number @x. Use g_type_fundamental_next() instead of this macro to create new fundamental types. the fundamental type number. First fundamental type number to create a new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL() reserved for BSE. Last fundamental type number reserved for BSE. First fundamental type number to create a new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL() reserved for GLib. Last fundamental type number reserved for GLib. First available fundamental type number to create new fundamental type id with G_TYPE_MAKE_FUNDAMENTAL(). A callback function used for notification when the state of a toggle reference changes. See g_object_add_toggle_ref(). Callback data passed to g_object_add_toggle_ref() The object on which g_object_add_toggle_ref() was called. %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. An opaque structure used as the base of all classes. 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, and are zero-filled. Note that the accumulated size of the private structures of a type and all its parent types cannot exceed 64 KiB. 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 MyObjectPrivate to an object MyObject defined in the standard GObject fashion in the type's class_init() function. Note the use of a structure member "priv" to avoid the overhead of repeatedly calling MY_OBJECT_GET_PRIVATE(). |[<!-- language="C" --> 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); // my_object->priv->some_field will be automatically initialised to 0 } static int my_object_get_some_field (MyObject *my_object) { MyObjectPrivate *priv; g_return_val_if_fail (MY_IS_OBJECT (my_object), 0); priv = my_object->priv; return priv->some_field; } ]| Use the G_ADD_PRIVATE() macro with the `G_DEFINE_*` family of macros to add instance private data to a type class structure for an instantiatable type size of private structure Gets the offset of the private data for instances of @g_class. This is how many bytes you should add to the instance pointer of a class in order to get the private data for the type represented by @g_class. You can only call this function after you have registered a private data area for @g_class using g_type_class_add_private(). the offset, in bytes a #GTypeClass 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: g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class))) the parent class of @g_class the #GTypeClass structure to retrieve the parent class for 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. a #GTypeClass structure to unref A variant of g_type_class_unref() for use in #GTypeClassCacheFunc implementations. It unreferences a class without consulting the chain of #GTypeClassCacheFuncs, avoiding the recursion which would occur otherwise. a #GTypeClass structure to unref 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). the #GTypeClass structure for the given type ID or %NULL if the class does not currently exist type ID of a classed type A more efficient version of g_type_class_peek() which works only for static types. the #GTypeClass structure for the given type ID or %NULL if the class does not currently exist or is dynamically loaded type ID of a classed type Increments the reference count of the class structure belonging to @type. This function will demand-create the class if it doesn't exist already. the #GTypeClass structure for the given type ID type ID of a classed type 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. %TRUE to stop further #GTypeClassCacheFuncs from being called, %FALSE to continue data that was given to the g_type_add_class_cache_func() call The #GTypeClass structure which is unreferenced These flags used to be passed to g_type_init_with_debug_flags() which is now deprecated. If you need to enable debugging features, use the GOBJECT_DEBUG environment variable. g_type_init() is now done automatically Print no messages Print messages about object bookkeeping Print messages about signal emissions Keep a count of instances of each type Mask covering all debug flags Bit masks used to check or determine characteristics of a type. Indicates an abstract type. No instances can be created for an abstract type Indicates an abstract value type, i.e. a type that introduces a value table, but can't be used for g_value_init() Bit masks used to check or determine specific characteristics of a fundamental type. Indicates a classed type Indicates an instantiable type (implies classed) Indicates a flat derivable type Indicates a deep derivable type (implies derivable) A structure that provides information to the type system which is used specifically for managing fundamental types. #GTypeFundamentalFlags describing the characteristics of the fundamental type 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(). Size of the class structure (required for interface, classed and instantiatable types) Location of the base initialization function (optional) Location of the base finalization function (optional) 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. Location of the class finalization function for classed and instantiatable types. Location of the default vtable finalization function for interface types. (optional) User-supplied data passed to the class init/finalize functions Size of the instance (object) structure (required for instantiatable types only) 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 [slice allocator][glib-Memory-Slices] now. Location of the instance initialization function (optional, for instantiatable types only) A #GTypeValueTable function table for generic handling of GValues of this type (usually only useful for fundamental types) An opaque structure used as the base of all type instances. An opaque structure used as the base of all interface types. 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. the 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 a #GTypeInterface structure Adds @prerequisite_type to the list of prerequisites of @interface_type. This means that any type implementing @interface_type must also implement @prerequisite_type. Prerequisites can be thought of as an alternative to interface derivation (which GType doesn't support). An interface can have at most one instantiatable prerequisite type. #GType value of an interface type #GType value of an interface or instantiatable type Returns the #GTypePlugin structure for the dynamic interface @interface_type which has been added to @instance_type, or %NULL if @interface_type has not been added to @instance_type or does not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). the #GTypePlugin for the dynamic interface @interface_type of @instance_type #GType of an instantiatable type #GType of an interface type Returns the #GTypeInterface structure of an interface to which the passed in class conforms. the #GTypeInterface structure of @iface_type if implemented by @instance_class, %NULL otherwise a #GTypeClass structure an interface ID which this class conforms to Returns the prerequisites of an interfaces type. a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type an interface type location to return the number of prerequisites, or %NULL A callback called after an interface vtable is initialized. See g_type_add_interface_check(). data passed to g_type_add_interface_check() the interface that has been initialized #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 cannot 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. 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. Since 2.56 if @module is %NULL this will call g_type_add_interface_static() instead. This can be used when making a static build of the module. a #GTypeModule type to which to add the interface. interface type to add type information structure 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.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. the new or existing type ID a #GTypeModule name for the type an array of #GEnumValue structs for the possible enumeration 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. Since 2.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. the new or existing type ID a #GTypeModule name for the type 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 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.56 if @module is %NULL this will call g_type_register_static() instead. This can be used when making a static build of the module. the new or existing type ID a #GTypeModule the type for the parent class name for the type type information structure flags field providing details about the type Sets the name for a #GTypeModule a #GTypeModule. a human-readable name to use in error messages. 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.) 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. %FALSE if the plugin needed to be loaded and loading the plugin failed. a #GTypeModule the name of the module In order to implement dynamic loading of types based on #GTypeModule, the @load and @unload functions in #GTypeModuleClass must be implemented. the parent class 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: 1. 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: |[<!-- language="C" --> new_type_id = g_type_register_dynamic (parent_type_id, "TypeName", new_type_plugin, type_flags); ]| where @new_type_plugin is an implementation of the #GTypePlugin interface. 2. 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 @new_type_id. 3. 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 @new_type_plugin. 4. 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). 5. 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 @new_type_plugin. 6. Things may repeat from the second step. 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. 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 #GTypePlugin the #GType of an instantiable type to which the interface is added the #GType of the interface whose info is completed the #GInterfaceInfo to fill in 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. a #GTypePlugin the #GType whose info is completed the #GTypeInfo struct to fill in the #GTypeValueTable to fill in Calls the @unuse_plugin function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. a #GTypePlugin Calls the @use_plugin function from the #GTypePluginClass of @plugin. There should be no need to use this function outside of the GObject type system itself. a #GTypePlugin The #GTypePlugin interface is used by the type system in order to handle the lifecycle of dynamically loaded types. Increases the use count of the plugin. Decreases the use count of the plugin. Fills in the #GTypeInfo and #GTypeValueTable structs for the type. The structs are initialized with `memset(s, 0, sizeof (s))` before calling this function. Fills in missing parts of the #GInterfaceInfo for the interface. The structs is initialized with `memset(s, 0, sizeof (s))` before calling this function. The type of the @complete_interface_info function of #GTypePluginClass. the #GTypePlugin the #GType of an instantiable type to which the interface is added the #GType of the interface whose info is completed the #GInterfaceInfo to fill in The type of the @complete_type_info function of #GTypePluginClass. the #GTypePlugin the #GType whose info is completed the #GTypeInfo struct to fill in the #GTypeValueTable to fill in The type of the @unuse_plugin function of #GTypePluginClass. the #GTypePlugin whose use count should be decreased The type of the @use_plugin function of #GTypePluginClass, which gets called to increase the use count of @plugin. the #GTypePlugin whose use count should be increased A structure holding information for a specific type. It is filled in by the g_type_query() function. the #GType value of the type the name of the type the size of the class structure the size of the instance structure The #GTypeValueTable provides the functions required by the #GValue implementation, to serve as a container for values of a type. 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: - 'i' - Integers. passed as collect_values[].v_int. - 'l' - Longs. passed as collect_values[].v_long. - 'd' - Doubles. passed as collect_values[].v_double. - 'p' - Pointers. passed as collect_values[].v_pointer. 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'. 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. Returns the location of the #GTypeValueTable associated with @type. Note that this function should only be used from source code that implements or has internal knowledge of the implementation of @type. location of the #GTypeValueTable associated with @type or %NULL if there is no #GTypeValueTable associated with @type a #GType 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. A #GValue structure. A #GType value. Checks whether the given #GValue can hold values of type %G_TYPE_BOOLEAN. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_BOXED. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_CHAR. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_DOUBLE. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_ENUM. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_FLAGS. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_FLOAT. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_GTYPE. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_INT. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_INT64. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_LONG. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT. a valid #GValue structure Checks whether the given #GValue can hold values derived from type %G_TYPE_PARAM. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_POINTER. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_STRING. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_UCHAR. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_UINT. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_UINT64. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_ULONG. a valid #GValue structure Checks whether the given #GValue can hold values of type %G_TYPE_VARIANT. a valid #GValue structure For string values, indicates that the string contained is canonical and will exist for the duration of the process. See g_value_set_interned_string(). Checks whether @value contains a string which is canonical. a valid #GValue structure If passed to G_VALUE_COLLECT(), allocated data won't be copied but used verbatim. This does not affect ref-counted types like objects. This does not affect usage of g_value_copy(), the data will be copied if it is not ref-counted. Get the type identifier of @value. A #GValue structure. Gets the type name of @value. A #GValue structure. This is the signature of va_list marshaller functions, an optional marshaller that can be used in some situations to avoid marshalling the signal argument into GValues. the #GClosure to which the marshaller belongs a #GValue to store the return value. May be %NULL if the callback of @closure doesn't return a value. the instance on which the closure is invoked. va_list of arguments to be passed to the closure. additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() the length of the @param_types array the #GType of each argument from @args. An opaque structure used to hold different types of values. The data within the structure has protected scope: it is accessible only to functions within a #GTypeValueTable structure, or implementations of the g_value_*() API. That is, code portions which implement new fundamental types. #GValue users cannot make any assumptions about how data is stored within the 2 element @data union, and the @g_type member should only be accessed through the G_VALUE_TYPE() macro. Copies the value of @src_value into @dest_value. An initialized #GValue structure. An initialized #GValue structure of the same type as @src_value. Get the contents of a %G_TYPE_BOXED derived #GValue. Upon getting, the boxed value is duplicated and needs to be later freed with g_boxed_free(), e.g. like: g_boxed_free (G_VALUE_TYPE (@value), return_value); boxed contents of @value a valid #GValue of %G_TYPE_BOXED derived type Get the contents of a %G_TYPE_OBJECT derived #GValue, increasing its reference count. If the contents of the #GValue are %NULL, then %NULL will be returned. object content of @value, should be unreferenced when no longer needed. a valid #GValue whose type is derived from %G_TYPE_OBJECT Get the contents of a %G_TYPE_PARAM #GValue, increasing its reference count. #GParamSpec content of @value, should be unreferenced when no longer needed. a valid #GValue whose type is derived from %G_TYPE_PARAM Get a copy the contents of a %G_TYPE_STRING #GValue. a newly allocated copy of the string content of @value a valid #GValue of type %G_TYPE_STRING Get the contents of a variant #GValue, increasing its refcount. The returned #GVariant is never floating. variant contents of @value (may be %NULL); should be unreffed using g_variant_unref() when no longer needed a valid #GValue of type %G_TYPE_VARIANT Determines if @value will fit inside the size of a pointer value. This is an internal function introduced mainly for C marshallers. %TRUE if @value will fit inside a pointer value. An initialized #GValue structure. Get the contents of a %G_TYPE_BOOLEAN #GValue. boolean contents of @value a valid #GValue of type %G_TYPE_BOOLEAN Get the contents of a %G_TYPE_BOXED derived #GValue. boxed contents of @value a valid #GValue of %G_TYPE_BOXED derived type Do not use this function; it is broken on platforms where the %char type is unsigned, such as ARM and PowerPC. See g_value_get_schar(). Get the contents of a %G_TYPE_CHAR #GValue. This function's return type is broken, see g_value_get_schar() character contents of @value a valid #GValue of type %G_TYPE_CHAR Get the contents of a %G_TYPE_DOUBLE #GValue. double contents of @value a valid #GValue of type %G_TYPE_DOUBLE Get the contents of a %G_TYPE_ENUM #GValue. enum contents of @value a valid #GValue whose type is derived from %G_TYPE_ENUM Get the contents of a %G_TYPE_FLAGS #GValue. flags contents of @value a valid #GValue whose type is derived from %G_TYPE_FLAGS Get the contents of a %G_TYPE_FLOAT #GValue. float contents of @value a valid #GValue of type %G_TYPE_FLOAT Get the contents of a %G_TYPE_GTYPE #GValue. the #GType stored in @value a valid #GValue of type %G_TYPE_GTYPE Get the contents of a %G_TYPE_INT #GValue. integer contents of @value a valid #GValue of type %G_TYPE_INT Get the contents of a %G_TYPE_INT64 #GValue. 64bit integer contents of @value a valid #GValue of type %G_TYPE_INT64 Get the contents of a %G_TYPE_LONG #GValue. long integer contents of @value a valid #GValue of type %G_TYPE_LONG Get the contents of a %G_TYPE_OBJECT derived #GValue. object contents of @value a valid #GValue of %G_TYPE_OBJECT derived type Get the contents of a %G_TYPE_PARAM #GValue. #GParamSpec content of @value a valid #GValue whose type is derived from %G_TYPE_PARAM Get the contents of a pointer #GValue. pointer contents of @value a valid #GValue of %G_TYPE_POINTER Get the contents of a %G_TYPE_CHAR #GValue. signed 8 bit integer contents of @value a valid #GValue of type %G_TYPE_CHAR Get the contents of a %G_TYPE_STRING #GValue. string content of @value a valid #GValue of type %G_TYPE_STRING Get the contents of a %G_TYPE_UCHAR #GValue. unsigned character contents of @value a valid #GValue of type %G_TYPE_UCHAR Get the contents of a %G_TYPE_UINT #GValue. unsigned integer contents of @value a valid #GValue of type %G_TYPE_UINT Get the contents of a %G_TYPE_UINT64 #GValue. unsigned 64bit integer contents of @value a valid #GValue of type %G_TYPE_UINT64 Get the contents of a %G_TYPE_ULONG #GValue. unsigned long integer contents of @value a valid #GValue of type %G_TYPE_ULONG Get the contents of a variant #GValue. variant contents of @value (may be %NULL) a valid #GValue of type %G_TYPE_VARIANT Initializes @value with the default value of @type. the #GValue structure that has been passed in A zero-filled (uninitialized) #GValue structure. Type the #GValue should hold values of. Initializes and sets @value from an instantiatable type via the value_table's collect_value() function. Note: The @value will be initialised with the exact type of @instance. If you wish to set the @value's type to a different GType (such as a parent class GType), you need to manually call g_value_init() and g_value_set_instance(). An uninitialized #GValue structure. the instance Returns the value contents as pointer. This function asserts that g_value_fits_pointer() returned %TRUE for the passed in value. This is an internal function introduced mainly for C marshallers. the value contents as pointer An initialized #GValue structure Clears the current value in @value and resets it to the default value (as if the value had just been initialized). the #GValue structure that has been passed in An initialized #GValue structure. Set the contents of a %G_TYPE_BOOLEAN #GValue to @v_boolean. a valid #GValue of type %G_TYPE_BOOLEAN boolean value to be set Set the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed. a valid #GValue of %G_TYPE_BOXED derived type boxed value to be set This is an internal function introduced mainly for C marshallers. Use g_value_take_boxed() instead. a valid #GValue of %G_TYPE_BOXED derived type duplicated unowned boxed value to be set Set the contents of a %G_TYPE_CHAR #GValue to @v_char. This function's input type is broken, see g_value_set_schar() a valid #GValue of type %G_TYPE_CHAR character value to be set Set the contents of a %G_TYPE_DOUBLE #GValue to @v_double. a valid #GValue of type %G_TYPE_DOUBLE double value to be set Set the contents of a %G_TYPE_ENUM #GValue to @v_enum. a valid #GValue whose type is derived from %G_TYPE_ENUM enum value to be set Set the contents of a %G_TYPE_FLAGS #GValue to @v_flags. a valid #GValue whose type is derived from %G_TYPE_FLAGS flags value to be set Set the contents of a %G_TYPE_FLOAT #GValue to @v_float. a valid #GValue of type %G_TYPE_FLOAT float value to be set Set the contents of a %G_TYPE_GTYPE #GValue to @v_gtype. a valid #GValue of type %G_TYPE_GTYPE #GType to be set Sets @value from an instantiatable type via the value_table's collect_value() function. An initialized #GValue structure. the instance Set the contents of a %G_TYPE_INT #GValue to @v_int. a valid #GValue of type %G_TYPE_INT integer value to be set Set the contents of a %G_TYPE_INT64 #GValue to @v_int64. a valid #GValue of type %G_TYPE_INT64 64bit integer value to be set Set the contents of a %G_TYPE_STRING #GValue to @v_string. The string is assumed to be static and interned (canonical, for example from g_intern_string()), and is thus not duplicated when setting the #GValue. a valid #GValue of type %G_TYPE_STRING static string to be set Set the contents of a %G_TYPE_LONG #GValue to @v_long. a valid #GValue of type %G_TYPE_LONG long integer value to be set 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). a valid #GValue of %G_TYPE_OBJECT derived type object value to be set This is an internal function introduced mainly for C marshallers. Use g_value_take_object() instead. a valid #GValue of %G_TYPE_OBJECT derived type object value to be set Set the contents of a %G_TYPE_PARAM #GValue to @param. a valid #GValue of type %G_TYPE_PARAM the #GParamSpec to be set This is an internal function introduced mainly for C marshallers. Use g_value_take_param() instead. a valid #GValue of type %G_TYPE_PARAM the #GParamSpec to be set Set the contents of a pointer #GValue to @v_pointer. a valid #GValue of %G_TYPE_POINTER pointer value to be set Set the contents of a %G_TYPE_CHAR #GValue to @v_char. a valid #GValue of type %G_TYPE_CHAR signed 8 bit integer to be set 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. a valid #GValue of %G_TYPE_BOXED derived type static boxed value to be set 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. If the the string is a canonical string, using g_value_set_interned_string() is more appropriate. a valid #GValue of type %G_TYPE_STRING static string to be set Set the contents of a %G_TYPE_STRING #GValue to @v_string. a valid #GValue of type %G_TYPE_STRING caller-owned string to be duplicated for the #GValue This is an internal function introduced mainly for C marshallers. Use g_value_take_string() instead. a valid #GValue of type %G_TYPE_STRING duplicated unowned string to be set Set the contents of a %G_TYPE_UCHAR #GValue to @v_uchar. a valid #GValue of type %G_TYPE_UCHAR unsigned character value to be set Set the contents of a %G_TYPE_UINT #GValue to @v_uint. a valid #GValue of type %G_TYPE_UINT unsigned integer value to be set Set the contents of a %G_TYPE_UINT64 #GValue to @v_uint64. a valid #GValue of type %G_TYPE_UINT64 unsigned 64bit integer value to be set Set the contents of a %G_TYPE_ULONG #GValue to @v_ulong. a valid #GValue of type %G_TYPE_ULONG unsigned long integer value to be set Set the contents of a variant #GValue to @variant. If the variant is floating, it is consumed. a valid #GValue of type %G_TYPE_VARIANT a #GVariant, or %NULL Sets the contents of a %G_TYPE_BOXED derived #GValue to @v_boxed and takes over the ownership of the caller’s reference to @v_boxed; the caller doesn’t have to unref it any more. a valid #GValue of %G_TYPE_BOXED derived type duplicated unowned boxed value to be set Sets the contents of a %G_TYPE_OBJECT derived #GValue to @v_object and takes over the ownership of the caller’s 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. a valid #GValue of %G_TYPE_OBJECT derived type object value to be set Sets the contents of a %G_TYPE_PARAM #GValue to @param and takes over the ownership of the caller’s reference to @param; the caller doesn’t have to unref it any more. a valid #GValue of type %G_TYPE_PARAM the #GParamSpec to be set Sets the contents of a %G_TYPE_STRING #GValue to @v_string. a valid #GValue of type %G_TYPE_STRING string to take ownership of 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). If @variant was floating then its floating reference is converted to a hard reference. 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. a valid #GValue of type %G_TYPE_VARIANT a #GVariant, or %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). Whether a transformation rule was found and could be applied. Upon failing transformations, @dest_value is left untouched. Source value. Target value. Clears the current value in @value (if any) 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. An initialized #GValue structure. 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. Source type. Target type. a function which transforms values of type @src_type into value of type @dest_type Returns whether a #GValue of type @src_type can be copied into a #GValue of type @dest_type. %TRUE if g_value_copy() is possible with @src_type and @dest_type. source type to be copied. destination type for copying. Check whether g_value_transform() is able to transform values of type @src_type into values of type @dest_type. Note that for the types to be transformable, they must be compatible or a transformation function must be registered. %TRUE if the transformation is possible, %FALSE otherwise. Source type. Target type. A #GValueArray contains an array of #GValue elements. number of values contained in the array array of values 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. Use #GArray and g_array_sized_new() instead. a newly allocated #GValueArray with 0 values number of values to preallocate space for Insert a copy of @value as last element of @value_array. If @value is %NULL, an uninitialized value is appended. Use #GArray and g_array_append_val() instead. the #GValueArray passed in as @value_array #GValueArray to add an element to #GValue to copy into #GValueArray, or %NULL Construct an exact copy of a #GValueArray by duplicating all its contents. Use #GArray and g_array_ref() instead. Newly allocated copy of #GValueArray #GValueArray to copy Free a #GValueArray including its contents. Use #GArray and g_array_unref() instead. #GValueArray to free Return a pointer to the value at @index_ containd in @value_array. Use g_array_index() instead. pointer to a value at @index_ in @value_array #GValueArray to get a value from index of the value of interest Insert a copy of @value at specified position into @value_array. If @value is %NULL, an uninitialized value is inserted. Use #GArray and g_array_insert_val() instead. the #GValueArray passed in as @value_array #GValueArray to add an element to insertion position, must be <= value_array->;n_values #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. Use #GArray and g_array_prepend_val() instead. the #GValueArray passed in as @value_array #GValueArray to add an element to #GValue to copy into #GValueArray, or %NULL Remove the value at position @index_ from @value_array. Use #GArray and g_array_remove_index() instead. the #GValueArray passed in as @value_array #GValueArray to remove an element from position of value to remove, which must be less than @value_array->n_values Sort @value_array using @compare_func to compare the elements according to the semantics of #GCompareFunc. The current implementation uses the same sorting algorithm as standard C qsort() function. Use #GArray and g_array_sort(). the #GValueArray passed in as @value_array #GValueArray to sort function to compare elements Sort @value_array using @compare_func to compare the elements according to the semantics of #GCompareDataFunc. The current implementation uses the same sorting algorithm as standard C qsort() function. Use #GArray and g_array_sort_with_data(). the #GValueArray passed in as @value_array #GValueArray to sort function to compare elements extra data argument provided for @compare_func The type of value transformation functions which can be registered with g_value_register_transform_func(). @dest_value will be initialized to the correct destination type. Source value. Target value. A #GWeakNotify function can be added to an object as a callback that gets triggered when the object is finalized. Since the object is already being finalized when the #GWeakNotify is called, there's not much you could do with the object, apart from e.g. using its address as hash-index or the like. data that was provided when the weak reference was established the object being finalized A structure containing a weak reference to a #GObject. It can either be empty (i.e. point to %NULL), or point to an object for as long as at least one "strong" reference to that object exists. Before the object's #GObjectClass.dispose method is called, every #GWeakRef associated with becomes empty (i.e. points to %NULL). Like #GValue, #GWeakRef can be statically allocated, stack- or heap-allocated, or embedded in larger structures. Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak reference is thread-safe: converting a weak pointer to a reference is atomic with respect to invalidation of weak pointers to destroyed objects. If the object's #GObjectClass.dispose method results in additional references to the object being held, any #GWeakRefs taken before it was disposed will continue to point to %NULL. If #GWeakRefs are taken after the object is disposed and re-referenced, they will continue to point to it until its refcount goes back to zero, at which point they too will be invalidated. Frees resources associated with a non-statically-allocated #GWeakRef. After this call, the #GWeakRef is left in an undefined state. You should only call this on a #GWeakRef that previously had g_weak_ref_init() called on it. location of a weak reference, which may be empty If @weak_ref is not empty, atomically acquire a strong reference to the object it points to, and return that reference. This function is needed because of the potential race between taking the pointer value and g_object_ref() on it, if the object was losing its last reference at the same time in a different thread. The caller should release the resulting reference in the usual way, by using g_object_unref(). the object pointed to by @weak_ref, or %NULL if it was empty location of a weak reference to a #GObject Initialise a non-statically-allocated #GWeakRef. This function also calls g_weak_ref_set() with @object on the freshly-initialised weak reference. This function should always be matched with a call to g_weak_ref_clear(). It is not necessary to use this function for a #GWeakRef in static storage because it will already be properly initialised. Just use g_weak_ref_set() directly. uninitialized or empty location for a weak reference a #GObject or %NULL Change the object to which @weak_ref points, or set it to %NULL. You must own a strong reference on @object while calling this function. location for a weak reference a #GObject or %NULL Assert that @object is non-%NULL, then release one reference to it with g_object_unref() and assert that it has been finalized (i.e. that there are no more references). If assertions are disabled via `G_DISABLE_ASSERT`, this macro just calls g_object_unref() without any further checks. This macro should only be used in regression tests. an object Provide a copy of a boxed structure @src_boxed which is of type @boxed_type. The newly created copy of the boxed structure. The type of @src_boxed. The boxed structure to be copied. Free the boxed structure @boxed which is of type @boxed_type. The type of @boxed. The boxed structure to be freed. 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. New %G_TYPE_BOXED derived type id for @name. Name of the new boxed type. Boxed structure copy function. Boxed structure free function. A #GClosureMarshal function for use with signals with handlers that take two boxed pointers as arguments and return a boolean. If you have such a signal, you will probably also need to use an accumulator, such as g_signal_accumulator_true_handled(). A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() A marshaller for a #GCClosure with a callback of type `gboolean (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. the #GClosure to which the marshaller belongs a #GValue which can store the returned #gboolean 2 a #GValue array holding instance and arg1 the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `gchar* (*callback) (gpointer instance, GObject *arg1, gpointer arg2, gpointer user_data)`. the #GClosure to which the marshaller belongs a #GValue, which can store the returned string 3 a #GValue array holding instance, arg1 and arg2 the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gboolean arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gboolean parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, GBoxed *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #GBoxed* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gchar arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gchar parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gdouble arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gdouble parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes an enumeration type.. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the enumeration parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gint arg1, gpointer user_data)` where the #gint parameter denotes a flags type. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the flags parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gfloat arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gfloat parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gint arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gint parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, glong arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #glong parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, GObject *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #GObject* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, GParamSpec *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #GParamSpec* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gpointer arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gpointer parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, const gchar *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gchar* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, guchar arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #guchar parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, guint arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #guint parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, guint arg1, gpointer arg2, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 3 a #GValue array holding instance, arg1 and arg2 the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gulong arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #gulong parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, GVariant *arg1, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 2 a #GValue array holding the instance and the #GVariant* parameter the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A marshaller for a #GCClosure with a callback of type `void (*callback) (gpointer instance, gpointer user_data)`. the #GClosure to which the marshaller belongs ignored 1 a #GValue array holding only the instance the invocation hint given as the last argument to g_closure_invoke() additional data specified when registering the marshaller A generic marshaller function implemented via [libffi](http://sourceware.org/libffi/). Normally this function is not passed explicitly to g_signal_new(), but used automatically by GLib when specifying a %NULL marshaller. A #GClosure. A #GValue to store the return value. May be %NULL if the callback of closure doesn't return a value. The length of the @param_values array. An array of #GValues holding the arguments on which to invoke the callback of closure. The invocation hint given as the last argument to g_closure_invoke(). Additional data specified when registering the marshaller, see g_closure_set_marshal() and g_closure_set_meta_marshal() Creates a new closure which invokes @callback_func with @user_data as the last parameter. @destroy_data will be called as a finalize notifier on the #GClosure. a floating reference to a new #GCClosure the function to invoke user data to pass to @callback_func destroy notify to be called when @user_data is no longer used 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. a new #GCClosure the function to invoke a #GObject pointer to pass to @callback_func 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. a new #GCClosure the function to invoke a #GObject pointer to pass to @callback_func Creates a new closure which invokes @callback_func with @user_data as the first parameter. @destroy_data will be called as a finalize notifier on the #GClosure. a floating reference to a new #GCClosure the function to invoke user data to pass to @callback_func destroy notify to be called when @user_data is no longer used Clears a reference to a #GObject. @object_ptr must not be %NULL. 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. A macro is also included that allows this function to be used without pointer casts. a pointer to a #GObject reference Disconnects a handler from @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_ptr is then set to zero, which is never a valid handler ID value (see g_signal_connect()). If the handler ID is 0 then this function does nothing. A macro is also included that allows this function to be used without pointer casts. A pointer to a handler ID (of type #gulong) of the handler to be disconnected. The instance to remove the signal handler from. Clears a weak reference to a #GObject. @weak_pointer_location must not be %NULL. If the weak reference is %NULL then this function does nothing. Otherwise, the weak reference to the object is removed for that location and the pointer is set to %NULL. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary between compilation units. The memory address of a pointer This function is meant to be called from the `complete_type_info` function of a #GTypePlugin implementation, as in the following example: |[<!-- language="C" --> static void my_enum_complete_type_info (GTypePlugin *plugin, GType g_type, GTypeInfo *info, GTypeValueTable *value_table) { 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); } ]| the type identifier of the type being completed the #GTypeInfo struct to be filled in An array of #GEnumValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. Returns the #GEnumValue for a value. the #GEnumValue for @value, or %NULL if @value is not a member of the enumeration a #GEnumClass the value to look up Looks up a #GEnumValue by name. the #GEnumValue with name @name, or %NULL if the enumeration doesn't have a member with that name a #GEnumClass the name to look up Looks up a #GEnumValue by nickname. the #GEnumValue with nickname @nick, or %NULL if the enumeration doesn't have a member with that nickname a #GEnumClass the nickname to look up Registers a new static enumeration type with the name @name. It is normally more convenient to let [glib-mkenums][glib-mkenums], generate a my_enum_get_type() function from a usual C enumeration definition than to write one yourself using g_enum_register_static(). The new type identifier. A nul-terminated string used as the name of the new type. 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. Pretty-prints @value in the form of the enum’s name. This is intended to be used for debugging purposes. The format of the output may change in the future. a newly-allocated text string the type identifier of a #GEnumClass type the 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 [glib-mkenums][glib-mkenums], that can construct suitable type registration functions from C enumeration definitions. Example of how to get a string representation of an enum value: |[<!-- language="C" --> GEnumClass *enum_class; GEnumValue *enum_value; enum_class = g_type_class_ref (MAMAN_TYPE_MY_ENUM); enum_value = g_enum_get_value (enum_class, MAMAN_MY_ENUM_FOO); g_print ("Name: %s\n", enum_value->value_name); g_type_class_unref (enum_class); ]| 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. the type identifier of the type being completed the #GTypeInfo struct to be filled in An array of #GFlagsValue structs for the possible enumeration values. The array is terminated by a struct with all members being 0. Returns the first #GFlagsValue which is set in @value. the first #GFlagsValue which is set in @value, or %NULL if none is set a #GFlagsClass the value Looks up a #GFlagsValue by name. the #GFlagsValue with name @name, or %NULL if there is no flag with that name a #GFlagsClass the name to look up Looks up a #GFlagsValue by nickname. the #GFlagsValue with nickname @nick, or %NULL if there is no flag with that nickname a #GFlagsClass the nickname to look up Registers a new static flags type with the name @name. It is normally more convenient to let [glib-mkenums][glib-mkenums] generate a my_flags_get_type() function from a usual C enumeration definition than to write one yourself using g_flags_register_static(). The new type identifier. A nul-terminated string used as the name of the new type. 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. Pretty-prints @value in the form of the flag names separated by ` | ` and sorted. Any extra bits will be shown at the end as a hexadecimal number. This is intended to be used for debugging purposes. The format of the output may change in the future. a newly-allocated text string the type identifier of a #GFlagsClass type the value #GBoxed is a generic wrapper mechanism for arbitrary C structures. The only thing the type system needs to know about the structures is how to copy them (a #GBoxedCopyFunc) and how to free them (a #GBoxedFreeFunc) — beyond that they are treated as opaque chunks of memory. Boxed types are useful for simple value-holder structures like rectangles or points. They can also be used for wrapping structures defined in non-#GObject based libraries. They allow arbitrary structures to be handled in a uniform way, allowing uniform copying (or referencing) and freeing (or unreferencing) of them, and uniform representation of the type of the contained structure. In turn, this allows any type which can be boxed to be set as the data in a #GValue, which allows for polymorphic handling of a much wider range of data types, and hence usage of such types as #GObject property values. #GBoxed is designed so that reference counted types can be boxed. Use the type’s ‘ref’ function as the #GBoxedCopyFunc, and its ‘unref’ function as the #GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref(). The #GValue structure is basically a variable container that consists of a type identifier and a specific value of that type. The type identifier within a #GValue structure always determines the type of the associated value. To create an undefined #GValue structure, simply create a zero-filled #GValue structure. To initialize the #GValue, use the g_value_init() function. A #GValue cannot be used until it is initialized. 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. |[<!-- language="C" --> #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 be initialized GValue a = G_VALUE_INIT; GValue b = G_VALUE_INIT; const gchar *message; // 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; } ]| 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. For type creation and registration purposes, all types fall into one of two categories: static or dynamic. Static types are never loaded or 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. Type instance and class structs are limited to a total of 64 KiB, including all parent types. Similarly, type instances' private data (as created by G_ADD_PRIVATE()) are limited to a total of 64 KiB. If a type instance needs a large static buffer, allocate it separately (typically by using #GArray or #GPtrArray) and put a pointer to the buffer in the structure. As mentioned in the [GType conventions][gtype-conventions], type names must be at least three characters long. There is no upper length limit. The first character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent characters can be letters, numbers or any of ‘-_+’. 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 [here][gobject-Signals]. For a tutorial on implementing a new GObject class, see [How to define and implement a new GObject][howto-gobject]. For a list of naming conventions for GObjects and their methods, see the [GType conventions][gtype-conventions]. For the high-level concepts behind GObject, read [Instantiable classed types: Objects][gtype-instantiable-classed]. ## Floating references # {#floating-ref} **Note**: Floating references are a C convenience API and should not be used in modern GObject code. Language bindings in particular find the concept highly problematic, as floating references are not identifiable through annotations, and neither are deviations from the floating reference behavior, like types that inherit from #GInitiallyUnowned and still return a full reference from g_object_new(). GInitiallyUnowned is derived from GObject. The only difference between the two is that the initial reference of a GInitiallyUnowned is flagged as a "floating" reference. This means that it is not specifically claimed to be "owned" by any code portion. The main motivation for providing floating references is C convenience. In particular, it allows code to be written as: |[<!-- language="C" --> container = create_container (); container_add_child (container, create_child()); ]| If container_add_child() calls g_object_ref_sink() on the passed-in child, no reference of the newly created child is leaked. Without floating references, container_add_child() can only g_object_ref() the new child, so to implement this code without reference leaks, it would have to be written as: |[<!-- language="C" --> Child *child; container = create_container (); 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) should not expose floating references in their API. The best practice for handling types that have initially floating references is to immediately sink those references after g_object_new() returns, by checking if the #GType inherits from #GInitiallyUnowned. For instance: |[<!-- language="C" --> GObject *res = g_object_new_with_properties (gtype, n_props, prop_names, prop_values); // or: if (g_type_is_a (gtype, G_TYPE_INITIALLY_UNOWNED)) if (G_IS_INITIALLY_UNOWNED (res)) g_object_ref_sink (res); return res; ]| Some object implementations may need to save an objects floating state across certain code portions (an example is #GtkMenu), to achieve this, the following sequence can be used: |[<!-- language="C" --> // 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); else g_object_unref (object); // release previously acquired reference ]| Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN property. In many cases, it may be more appropriate to use an enum with g_param_spec_enum(), both to improve code clarity by using explicitly named values, and to allow for more values to be added in future without breaking API. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED derived property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified %G_TYPE_BOXED derived type of this property flags for the property specified Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified 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. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecEnum instance specifying a %G_TYPE_ENUM property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GType derived from %G_TYPE_ENUM default value for the property specified 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. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GType derived from %G_TYPE_FLAGS default value for the property specified flags for the property specified Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified 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. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GType whose subtypes are allowed as values of the property (use %G_TYPE_NONE for any type) flags for the property specified Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified 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. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified %G_TYPE_OBJECT derived type of this property flags for the property specified 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. the newly created #GParamSpec the name of the property. The property that is being overridden Creates a new #GParamSpecParam instance specifying a %G_TYPE_PARAM property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GType derived from %G_TYPE_PARAM flags for the property specified Creates a new #GParamSpecPointer instance specifying a pointer property. Where possible, it is better to use g_param_spec_object() or g_param_spec_boxed() to expose memory management information. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified flags for the property specified 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 newly allocated #GParamSpecPool. Whether the pool will support type-prefixed property names. Creates a new #GParamSpecString instance. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified flags for the property specified Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 property. See g_param_spec_internal() for details on property names. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified 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. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified minimum value for the property specified maximum value for the property specified default value for the property specified 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. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified default value for the property specified flags for the property specified 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. a newly created parameter specification canonical name of the property specified nick name for the property specified description of the property specified a #GParamSpec describing the elements contained in arrays of this property, may be %NULL flags for the property specified 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. the newly created #GParamSpec canonical name of the property specified nick name for the property specified description of the property specified a #GVariantType a #GVariant of type @type to use as the default value, or %NULL flags for the property specified Registers @name as the name of a new static type derived from #G_TYPE_PARAM. The type system uses the information contained in the #GParamSpecTypeInfo structure pointed to by @info to manage the #GParamSpec type and its instances. The new type identifier. 0-terminated string used as the name of the new #GParamSpec type. The #GParamSpecTypeInfo for this #GParamSpec type. Transforms @src_value into @dest_value if possible, and then validates @dest_value, in order for it to conform to @pspec. If @strict_validation is %TRUE this function will only succeed if the transformed @dest_value complied to @pspec without modifications. See also g_value_type_transformable(), g_value_transform() and g_param_value_validate(). %TRUE if transformation and validation were successful, %FALSE otherwise and @dest_value is left untouched. a valid #GParamSpec source #GValue destination #GValue of correct type for @pspec %TRUE requires @dest_value to conform to @pspec without modifications Checks whether @value contains the default value as specified in @pspec. whether @value contains the canonical default for this @pspec a valid #GParamSpec a #GValue of correct type for @pspec Sets @value to its default value as specified in @pspec. a valid #GParamSpec a #GValue of correct type for @pspec; since 2.64, you can also pass an empty #GValue, initialized with %G_VALUE_INIT #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. 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. whether modifying @value was necessary to ensure validity a valid #GParamSpec 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. -1, 0 or +1, for a less than, equal to or greater than result a valid #GParamSpec a #GValue of correct type for @pspec a #GValue of correct type for @pspec Creates a new %G_TYPE_POINTER derived type id for a new pointer type with name @name. a new %G_TYPE_POINTER derived type id for @name. the name of the new pointer type. Updates a #GObject pointer to refer to @new_object. It increments the reference count of @new_object (if non-%NULL), decrements the reference count of the current value of @object_ptr (if non-%NULL), and assigns @new_object to @object_ptr. The assignment is not atomic. @object_ptr must not be %NULL. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary between compilation units. One convenient usage of this function is in implementing property setters: |[ void foo_set_bar (Foo *foo, Bar *new_bar) { g_return_if_fail (IS_FOO (foo)); g_return_if_fail (new_bar == NULL || IS_BAR (new_bar)); if (g_set_object (&foo->bar, new_bar)) g_object_notify (foo, "bar"); } ]| a pointer to a #GObject reference a pointer to the new #GObject to assign to it, or %NULL to clear the pointer Updates a pointer to weakly refer to @new_object. It assigns @new_object to @weak_pointer_location and ensures that @weak_pointer_location will automatically be set to %NULL if @new_object gets destroyed. The assignment is not atomic. The weak reference is not thread-safe, see g_object_add_weak_pointer() for details. @weak_pointer_location must not be %NULL. A macro is also included that allows this function to be used without pointer casts. The function itself is static inline, so its address may vary between compilation units. One convenient usage of this function is in implementing property setters: |[ void foo_set_bar (Foo *foo, Bar *new_bar) { g_return_if_fail (IS_FOO (foo)); g_return_if_fail (new_bar == NULL || IS_BAR (new_bar)); if (g_set_weak_pointer (&foo->bar, new_bar)) g_object_notify (foo, "bar"); } ]| the memory address of a pointer a pointer to the new #GObject to assign to it, or %NULL to clear the pointer 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"). standard #GSignalAccumulator result standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter A predefined #GSignalAccumulator for signals that return a boolean values. The behavior that this accumulator gives is that a return of %TRUE stops the signal emission: no further callbacks will be invoked, while a return of %FALSE allows the emission to continue. The idea here is that a %TRUE return indicates that the callback handled the signal, and no further handling is needed. standard #GSignalAccumulator result standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter standard #GSignalAccumulator parameter 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. the hook id, for later use with g_signal_remove_emission_hook(). the signal identifier, as returned by g_signal_lookup(). the detail on which to call the hook. a #GSignalEmissionHook function. user data for @hook_func. a #GDestroyNotify for @hook_data. 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 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. Location for the return value. 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 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. Connects a #GCallback function to a signal for a particular object. The handler will be called before the default handler of the signal. See [memory management of signal handlers][signal-memory-management] for details on how to handle the return value and memory management of @data. the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. 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. the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. data to pass to @c_handler calls. Connects a closure to a signal for a particular object. the handler ID (always greater than 0 for successful connections) the instance to connect to. a string of the form "signal-name::detail". the closure to connect. whether the handler should be called before or after the default handler of the signal. Connects a closure to a signal for a particular object. the handler ID (always greater than 0 for successful connections) the instance to connect to. the id of the signal. the detail. the closure to connect. whether the handler should be called before or after the default handler of the signal. 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 `..._after()` or `..._swapped()` variants of this function. the handler ID (always greater than 0 for successful connections) the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. data to pass to @c_handler calls. a #GClosureNotify for @data. a combination of #GConnectFlags. 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. When the @gobject is destroyed the signal handler will be automatically disconnected. Note that this is not currently threadsafe (ie: emitting a signal while @gobject is being destroyed in another thread is not safe). the handler id. the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. the object to pass as data to @c_handler. a combination of #GConnectFlags. 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. This is useful when calling pre-existing functions to operate purely on the @data, rather than the @instance: swapping the parameters avoids the need to write a wrapper function. For example, this allows the shorter code: |[<!-- language="C" --> g_signal_connect_swapped (button, "clicked", (GCallback) gtk_widget_hide, other_widget); ]| Rather than the cumbersome: |[<!-- language="C" --> static void button_clicked_cb (GtkButton *button, GtkWidget *other_widget) { gtk_widget_hide (other_widget); } ... g_signal_connect (button, "clicked", (GCallback) button_clicked_cb, other_widget); ]| the instance to connect to. a string of the form "signal-name::detail". the #GCallback to connect. data to pass to @c_handler calls. 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(). the instance the signal is being emitted on. the signal id 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. 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(). the instance the signal is being emitted on. 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. 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 instance the signal is being emitted on. the signal id the detail 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. 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(). 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. the signal id the detail Location to store the return value of the signal emission. This must be provided if the specified signal returns a value, but may be ignored otherwise. Returns the invocation hint of the innermost signal emission of instance. the invocation hint of the innermost signal emission. the instance to query 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 deactivate 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. The instance to block the signal handler of. Handler id of the handler to be blocked. 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 instance to remove the signal handler from. Handler id of the handler to be disconnected. 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. A valid non-0 signal handler id for a successful match. The instance owning the signal handler to be found. Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handler has to match. Signal the handler has to be connected to. Signal detail the handler has to be connected to. The closure the handler will invoke. The C closure callback of the handler (useless for non-C closures). The closure data of the handler's closure. Returns whether @handler_id is the ID of a handler connected to @instance. whether @handler_id identifies a handler connected to @instance. The instance where a signal handler is sought. the handler ID. 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. The instance to unblock the signal handler of. Handler id of the handler to be unblocked. Blocks all handlers on an instance that match @func and @data. The instance to block handlers from. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. 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. The number of handlers that matched. The instance to block handlers from. Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. The closure the handlers will invoke. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Destroy all signal handlers of a type instance. This function is an implementation detail of the #GObject dispose implementation, and should not be used outside of the type system. The instance whose signal handlers are destroyed Disconnects all handlers on an instance that match @data. The instance to remove handlers from the closure data of the handlers' closures Disconnects all handlers on an instance that match @func and @data. The instance to remove handlers from. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. 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. The number of handlers that matched. The instance to remove handlers from. Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. The closure the handlers will invoke. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Unblocks all handlers on an instance that match @func and @data. The instance to unblock handlers from. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. 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. The number of handlers that matched. The instance to unblock handlers from. Mask indicating which of @signal_id, @detail, @closure, @func and/or @data the handlers have to match. Signal the handlers have to be connected to. Signal detail the handlers have to be connected to. The closure the handlers will invoke. The C closure callback of the handlers (useless for non-C closures). The closure data of the handlers' closures. Returns whether there are any handlers connected to @instance for the given signal id and detail. If @detail is 0 then it will only match handlers that were connected without detail. If @detail is non-zero then it will match handlers connected both without detail and with the given detail. This is consistent with how a signal emitted with @detail would be delivered to those handlers. Since 2.46 this also checks for a non-default class closure being installed, as this is basically always what you want. 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. %TRUE if a handler is connected to the signal, %FALSE otherwise. the object whose signal handlers are sought. the signal id. the detail. whether blocked handlers should count as match. Validate a signal name. This can be useful for dynamically-generated signals which need to be validated at run-time before actually trying to create them. See [canonical parameter names][canonical-parameter-names] for details of the rules for valid names. The rules for signal names are the same as those for property names. %TRUE if @name is a valid signal name, %FALSE otherwise. the canonical name of the signal 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(). Newly allocated array of signal IDs. Instance or interface type. Location to store the number of signal ids for @itype. 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. The type class passed as @itype must already have been instantiated (for example, using g_type_class_ref()) for this function to work, as signals are always installed during class initialization. See g_signal_new() for details on allowed signal names. the signal's identifying number, or 0 if no signal was found. the signal's name. the type that the signal operates on. Given the signal's identifier, finds its name. Two different signals may have the same name, if they have differing types. the signal name, or %NULL if the signal number was invalid. the signal's identifying number. 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. These are the same rules as for property naming (see g_param_spec_internal()). When registering a signal and looking up a signal, either separator can be used, but they cannot be mixed. Using `-` is considerably more efficient. Using `_` is discouraged. If 0 is used for @class_offset subclasses cannot override the class handler in their class_init method by doing super_class->signal_handler = my_signal_handler. Instead they will have to use g_signal_override_class_handler(). If @c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. In some simple cases, g_signal_new() will use a more optimized c_marshaller and va_marshaller for the signal instead of g_cclosure_marshal_generic(). If @c_marshaller is non-%NULL, you need to also specify a va_marshaller using g_signal_set_va_marshaller() or the generic va_marshaller will be used. the signal id the name for the signal the type this signal pertains to. It will also pertain to types which are derived from this type. 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. 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. the accumulator for this signal; may be %NULL. user data for the @accumulator. the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or #G_TYPE_NONE for a signal without a return value. the number of parameter types to follow. a list of types, one for each parameter. 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 of 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 overridden 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. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. the signal id the name for the signal the type this signal pertains to. It will also pertain to types which are derived from this type. 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. 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. the accumulator for this signal; may be %NULL. user data for the @accumulator. the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or #G_TYPE_NONE for a signal without a return value. the number of parameter types to follow. a list 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. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. the signal id the name for the signal the type this signal pertains to. It will also pertain to types which are derived from this type. 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. The closure to invoke on signal emission; may be %NULL. the accumulator for this signal; may be %NULL. user data for the @accumulator. the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL. the type of return value, or #G_TYPE_NONE for a signal without a return value. the number of parameter types in @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. If c_marshaller is %NULL, g_cclosure_marshal_generic() will be used as the marshaller for this signal. the signal id the name for the signal the type this signal pertains to. It will also pertain to types which are derived from this type 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 The closure to invoke on signal emission; may be %NULL the accumulator for this signal; may be %NULL user data for the @accumulator the function to translate arrays of parameter values to signal emissions into C language callback invocations or %NULL the type of return value, or #G_TYPE_NONE for a signal without a return value the length of @param_types an array of types, one for each parameter 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. the signal id the instance type on which to override the class closure for the signal. the closure. Overrides the class closure (i.e. the default handler) for the given signal for emissions on instances of @instance_type with callback @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. the name for the signal the instance type on which to override the class handler for the signal. the handler. Internal function to parse a signal name into its @signal_id and @detail quark. Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values. a string of the form "signal-name::detail". The interface/instance type that introduced "signal-name". Location to store the signal id. Location to store the detail quark. %TRUE forces creation of a #GQuark for the detail. 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. The signal id of the signal to query information for. A user provided structure that is filled in with constant values upon success. Deletes an emission hook. the id of the signal the id of the emission hook, as returned by g_signal_add_emission_hook() Change the #GSignalCVaMarshaller used for a given signal. This is a specialised form of the marshaller that can often be used for the common case of a single connected signal handler and avoids the overhead of #GValue. Its use is optional. the signal id the instance type on which to set the marshaller. the marshaller to set. 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. the object whose signal handlers you wish to stop. the signal identifier, as returned by g_signal_lookup(). the detail which the signal was emitted with. Stops a signal's current emission. This is just like g_signal_stop_emission() except it will look up the signal id for you. the object whose signal handlers you wish to stop. a string of the form "signal-name::detail". Creates a new closure which invokes the function found at the offset @struct_offset in the class structure of the interface or classed type identified by @itype. a floating reference to a new #GCClosure the #GType identifier of an interface or classed type the offset of the member function of @itype's class structure which is to be invoked by the new closure The basic concept of the signal system is that of the emission 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 ones and user provided ones. (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.) 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: 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals 2. Invocation of normal user-provided signal handlers (where the @after flag is not set) 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals 4. Invocation of user provided signal handlers (where the @after flag is set) 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals 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 blocked. 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. While the @detail argument is typically used to pass an object property name (as with #GObject::notify), no specific format is mandated for the detail string, other than that it must be non-empty. ## Memory management of signal handlers # {#signal-memory-management} If you are connecting handlers to signals and using a #GObject instance as your signal handler user data, you should remember to pair calls to g_signal_connect() with calls to g_signal_handler_disconnect() or g_signal_handlers_disconnect_by_func(). While signal handlers are automatically disconnected when the object emitting the signal is finalised, they are not automatically disconnected when the signal handler user data is destroyed. If this user data is a #GObject instance, using it from a signal handler after it has been finalised is an error. There are two strategies for managing such user data. The first is to disconnect the signal handler (using g_signal_handler_disconnect() or g_signal_handlers_disconnect_by_func()) when the user data (object) is finalised; this has to be implemented manually. For non-threaded programs, g_signal_connect_object() can be used to implement this automatically. Currently, however, it is unsafe to use in threaded programs. The second is to hold a strong reference on the user data until after the signal is disconnected for other reasons. This can be implemented automatically using g_signal_connect_data(). The first approach is recommended, as the second approach can result in effective memory leaks of the user data if the signal handler is never disconnected for some reason. 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. the source a #GClosure 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 @closure_callback and @closure_marshal fields of the #GSourceFuncs structure must have been filled in with pointers to appropriate functions. the source 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. Newly allocated string. #GValue which contents are to be described. 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. data to be passed to @cache_func a #GTypeClassCacheFunc 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, and are zero-filled. 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. GType of a classed type size of private structure 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. data to pass to @check_func function to be called after each interface is initialized Adds @interface_type to the dynamic @instantiable_type. The information contained in the #GTypePlugin structure pointed to by @plugin is used to manage the relationship. #GType value of an instantiable type #GType value of an interface type #GTypePlugin structure to retrieve the #GInterfaceInfo from Adds @interface_type to the static @instantiable_type. The information contained in the #GInterfaceInfo structure pointed to by @info is used to manage the relationship. #GType value of an instantiable type #GType value of an interface type #GInterfaceInfo structure for this (@instance_type, @interface_type) combination Private helper function to aid implementation of the G_TYPE_CHECK_INSTANCE() macro. %TRUE if @instance is valid, %FALSE otherwise a valid #GTypeInstance structure Return a newly allocated and 0-terminated array of type IDs, listing the child types of @type. Newly allocated and 0-terminated array of child types, free with g_free() the parent type location to store the length of the returned array, or %NULL 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). the #GTypeClass structure for the given type ID or %NULL if the class does not currently exist type ID of a classed type A more efficient version of g_type_class_peek() which works only for static types. the #GTypeClass structure for the given type ID or %NULL if the class does not currently exist or is dynamically loaded type ID of a classed type Increments the reference count of the class structure belonging to @type. This function will demand-create the class if it doesn't exist already. the #GTypeClass structure for the given type ID type ID of a classed type Creates and initializes an instance of @type if @type is valid and can be instantiated. The type system only performs basic allocation and structure setups for instances: actual instance creation should happen through functions supplied by the type's fundamental type implementation. So use of g_type_create_instance() is reserved for implementers of fundamental types only. E.g. instances of the #GObject hierarchy should be created via g_object_new() and never directly through g_type_create_instance() which doesn't handle things like singleton objects or object construction. The extended members of the returned instance are guaranteed to be filled with zeros. Note: Do not use this function, unless you're implementing a fundamental type. Also language bindings should not use this function, but g_object_new() instead. an allocated and initialized instance, subject to further treatment by the fundamental type implementation an instantiatable type to create an instance for If the interface type @g_type is currently in use, returns its default interface vtable. the default vtable for the interface, or %NULL if the type is not currently in use an interface type 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 initialized by calling the base interface init and default vtable init functions for the type (the @base_init and @class_init 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. the default vtable for the interface; call g_type_default_interface_unref() when you are done using the interface. an interface type 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 @class_finalize member of #GTypeInfo) will be called. the default vtable structure for an interface, as returned by g_type_default_interface_ref() 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. the depth of @type a #GType Ensures that the indicated @type has been registered with the type system, and its _class_init() method has been run. In theory, simply calling the type's _get_type() method (or using the corresponding macro) is supposed take care of this. However, _get_type() methods are often marked %G_GNUC_CONST for performance reasons, even though this is technically incorrect (since %G_GNUC_CONST requires that the function not have side effects, which _get_type() methods do on the first call). As a result, if you write a bare call to a _get_type() macro, it may get optimized out by the compiler. Using g_type_ensure() guarantees that the type's _get_type() method is called. a #GType 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. an instance of a type Look up 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). corresponding type ID or 0 type name to look up Internal function, used to extract the fundamental type ID portion. Use G_TYPE_FUNDAMENTAL() instead. fundamental type ID valid type ID 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. the next available fundamental type ID to be registered, or 0 if the type system ran out of fundamental type IDs Returns the number of instances allocated of the particular type; this is only available if GLib is built with debugging support and the instance_count debug flag is set (by setting the GOBJECT_DEBUG variable to include instance-count). the number of instances allocated of the given type; if instance counts are not available, returns 0. a #GType Returns the #GTypePlugin structure for @type. the corresponding plugin if @type is a dynamic type, %NULL otherwise #GType to retrieve the plugin for Obtains data which has previously been attached to @type with g_type_set_qdata(). Note that this does not take subtyping into account; data attached to one type with g_type_set_qdata() cannot be retrieved from a subtype using g_type_get_qdata(). the data, or %NULL if no data was found a #GType a #GQuark id to identify the data Returns an opaque serial number that represents the state of the set of registered types. Any time a type is registered this serial changes, which means you can cache information based on type lookups (such as g_type_from_name()) and know if the cache is still valid at a later time by comparing the current serial with the one at the type lookup. An unsigned int, representing the state of type registrations This function used to initialise the type system. Since GLib 2.36, the type system is initialised automatically and this function does nothing. the type system is now initialised automatically This function used to initialise the type system with debugging flags. Since GLib 2.36, the type system is initialised automatically and this function does nothing. If you need to enable debugging features, use the GOBJECT_DEBUG environment variable. the type system is now initialised automatically bitwise combination of #GTypeDebugFlags values for debugging purposes Adds @prerequisite_type to the list of prerequisites of @interface_type. This means that any type implementing @interface_type must also implement @prerequisite_type. Prerequisites can be thought of as an alternative to interface derivation (which GType doesn't support). An interface can have at most one instantiatable prerequisite type. #GType value of an interface type #GType value of an interface or instantiatable type Returns the #GTypePlugin structure for the dynamic interface @interface_type which has been added to @instance_type, or %NULL if @interface_type has not been added to @instance_type or does not have a #GTypePlugin structure. See g_type_add_interface_dynamic(). the #GTypePlugin for the dynamic interface @interface_type of @instance_type #GType of an instantiatable type #GType of an interface type Returns the #GTypeInterface structure of an interface to which the passed in class conforms. the #GTypeInterface structure of @iface_type if implemented by @instance_class, %NULL otherwise a #GTypeClass structure an interface ID which this class conforms to Returns the prerequisites of an interfaces type. a newly-allocated zero-terminated array of #GType containing the prerequisites of @interface_type an interface type location to return the number of prerequisites, or %NULL Return a newly allocated and 0-terminated array of type IDs, listing the interface types that @type conforms to. Newly allocated and 0-terminated array of interface types, free with g_free() the type to list interface types for location to store the length of the returned array, or %NULL 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. %TRUE if @type is a @is_a_type type to check anchestry for possible anchestor of @type or interface that @type could conform to 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. static type name or %NULL type to return name for 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 @leaf_type. Given a root type and a leaf type, this function can be used to determine the types and order in which the leaf type is descended from the root type. immediate child of @root_type and anchestor of @leaf_type descendant of @root_type and the type to be returned immediate parent of the returned 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. the parent type the derived type Get the corresponding quark of the type IDs name. the type names quark or 0 type to return quark of type name for 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 @type member of the #GTypeQuery is 0. All members filled into the #GTypeQuery structure should be considered constant and have to be left untouched. #GType of a static, classed type a user provided structure that is filled in with constant values upon success Registers @type_name as the name of a new dynamic type derived from @parent_type. The type system uses the information contained in the #GTypePlugin structure pointed to by @plugin 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. the new type identifier or #G_TYPE_INVALID if registration failed type from which this type will be derived 0-terminated string used as the name of the new type #GTypePlugin structure to retrieve the #GTypeInfo from bitwise combination of #GTypeFlags values Registers @type_id as the predefined identifier and @type_name as the name of a fundamental type. If @type_id is already registered, or a type named @type_name is already registered, the behaviour is undefined. 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. the predefined type identifier a predefined type identifier 0-terminated string used as the name of the new type #GTypeInfo structure for this type #GTypeFundamentalInfo structure for this type bitwise combination of #GTypeFlags values Registers @type_name as the name of a new static type derived from @parent_type. The type system uses the information contained in the #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. the new type identifier type from which this type will be derived 0-terminated string used as the name of the new type #GTypeInfo structure for this type bitwise combination of #GTypeFlags values Registers @type_name as the name of a new static type derived from @parent_type. The value of @flags determines the nature (e.g. abstract or not) of the type. It works by filling a #GTypeInfo struct and calling g_type_register_static(). the new type identifier type from which this type will be derived 0-terminated string used as the name of the new type size of the class structure (see #GTypeInfo) location of the class initialization function (see #GTypeInfo) size of the instance structure (see #GTypeInfo) location of the instance initialization function (see #GTypeInfo) bitwise combination of #GTypeFlags values 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. data that was given when adding @cache_func a #GTypeClassCacheFunc Removes an interface check function added with g_type_add_interface_check(). callback data passed to g_type_add_interface_check() callback function passed to g_type_add_interface_check() Attaches arbitrary data to a type. a #GType a #GQuark id to identify the data the data Returns the location of the #GTypeValueTable associated with @type. Note that this function should only be used from source code that implements or has internal knowledge of the implementation of @type. location of the #GTypeValueTable associated with @type or %NULL if there is no #GTypeValueTable associated with @type a #GType 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. #GValueArray is deprecated in favour of #GArray since GLib 2.32. It is possible to create a #GArray that behaves like a #GValueArray by using the size of #GValue as the element size, and by setting g_value_unset() as the clear function using g_array_set_clear_func(), for instance, the following code: |[<!-- language="C" --> GValueArray *array = g_value_array_new (10); ]| can be replaced by: |[<!-- language="C" --> GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10); g_array_set_clear_func (array, (GDestroyNotify) g_value_unset); ]| 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. Source type. Target type. a function which transforms values of type @src_type into value of type @dest_type Returns whether a #GValue of type @src_type can be copied into a #GValue of type @dest_type. %TRUE if g_value_copy() is possible with @src_type and @dest_type. source type to be copied. destination type for copying. Check whether g_value_transform() is able to transform values of type @src_type into values of type @dest_type. Note that for the types to be transformable, they must be compatible or a transformation function must be registered. %TRUE if the transformation is possible, %FALSE otherwise. Source type. Target type.