mirrors/gstreamer-rs
mirrors/gstreamer-rs
1
1
Fork 1
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer-rs.git synced 2024-06-15 20:50:35 +00:00
Code Issues Projects Releases Wiki Activity

gir-files: Import from gir-files at 824aa87

Browse source
This commit is contained in:
Marijn Suijten 2021-01-05 02:56:48 +01:00
parent f10d6990e4
commit 9023ce0a94
4 changed files with 7260 additions and 352 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6039
gir-files/GLib-2.0.gir
View file

File diff suppressed because it is too large Load diff

74
gir-files/GModule-2.0.gir
View file

@ -262,5 +262,79 @@ directory it will return `\Windows\mylibrary.dll`.</doc>
<type name="gboolean" c:type="gboolean"/>
</return-value>
</function>
<docsection name="modules">
<doc xml:space="preserve">These functions provide a portable way to dynamically load object files
(commonly known as 'plug-ins'). The current implementation supports all
systems that provide an implementation of dlopen() (e.g. Linux/Sun), as
well as Windows platforms via DLLs.
A program which wants to use these functions must be linked to the
libraries output by the command `pkg-config --libs gmodule-2.0`.
To use them you must first determine whether dynamic loading
is supported on the platform by calling g_module_supported().
If it is, you can open a module with g_module_open(),
find the module's symbols (e.g. function names) with g_module_symbol(),
and later close the module with g_module_close().
g_module_name() will return the file name of a currently opened module.
If any of the above functions fail, the error status can be found with
g_module_error().
The #GModule implementation features reference counting for opened modules,
and supports hook functions within a module which are called when the
module is loaded and unloaded (see #GModuleCheckInit and #GModuleUnload).
If your module introduces static data to common subsystems in the running
program, e.g. through calling
`g_quark_from_static_string ("my-module-stuff")`,
it must ensure that it is never unloaded, by calling g_module_make_resident().
Example: Calling a function defined in a GModule
|[&lt;!-- language="C" --&gt;
// the function signature for 'say_hello'
typedef void (* SayHelloFunc) (const char *message);
gboolean
just_say_hello (const char *filename, GError **error)
{
SayHelloFunc say_hello;
GModule *module;
module = g_module_open (filename, G_MODULE_BIND_LAZY);
if (!module)
{
g_set_error (error, FOO_ERROR, FOO_ERROR_BLAH,
"%s", g_module_error ());
return FALSE;
}
if (!g_module_symbol (module, "say_hello", (gpointer *)&amp;say_hello))
{
g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
"%s: %s", filename, g_module_error ());
if (!g_module_close (module))
g_warning ("%s: %s", filename, g_module_error ());
return FALSE;
}
if (say_hello == NULL)
{
g_set_error (error, SAY_ERROR, SAY_ERROR_OPEN,
"symbol say_hello is NULL");
if (!g_module_close (module))
g_warning ("%s: %s", filename, g_module_error ());
return FALSE;
}
// call our function in the module
say_hello ("Hello world!");
if (!g_module_close (module))
g_warning ("%s: %s", filename, g_module_error ());
return TRUE;
}
]|</doc>
</docsection>
</namespace>
</repository>

478
gir-files/GObject-2.0.gir
View file

@ -3040,7 +3040,7 @@ initial reference count, if it is unowned, we instead can write:
g_source_set_closure (source, g_cclosure_new (cb_func, cb_data));
]|
Generally, this function is used together with g_closure_ref(). Ane example
Generally, this function is used together with g_closure_ref(). An example
of storing a closure for later notification looks like:
|[&lt;!-- language="C" --&gt;
static GClosure *notify_closure = NULL;
@ -4745,7 +4745,9 @@ to the #GObject implementation and should never be accessed directly.</doc>
<doc xml:space="preserve">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.
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
@ -6126,7 +6128,7 @@ Note that the @destroy callback is not called if @data is %NULL.</doc>
</method>
<method name="set_qdata" c:identifier="g_object_set_qdata" introspectable="0">
<doc xml:space="preserve">This sets an opaque, named pointer on an object.
The name is specified through a #GQuark (retrived e.g. via
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.
@ -6270,7 +6272,7 @@ object_add_to_user_list (GObject *object,
{
// the quark, naming the object data
GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
// retrive the old string list
// retrieve the old string list
GList *list = g_object_steal_qdata (object, quark_string_list);
// prepend new string
@ -7326,8 +7328,8 @@ required to specify parameters, such as e.g. #GObject properties.
## Parameter names # {#canonical-parameter-names}
A property name consists of segments consisting of ASCII letters and
digits, separated by either the `-` or `_` character. The first
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()).
@ -7375,6 +7377,25 @@ e.g. a tooltip. The @nick and @blurb should ideally be localized.</doc>
</parameter>
</parameters>
</function>
<function name="is_valid_name" c:identifier="g_param_spec_is_valid_name" version="2.66">
<doc xml:space="preserve">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.</doc>
<return-value transfer-ownership="none">
<doc xml:space="preserve">%TRUE if @name is a valid property name, %FALSE otherwise.</doc>
<type name="gboolean" c:type="gboolean"/>
</return-value>
<parameters>
<parameter name="name" transfer-ownership="none">
<doc xml:space="preserve">the canonical name of the property</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
</parameters>
</function>
<virtual-method name="finalize">
<return-value transfer-ownership="none">
@ -7998,7 +8019,7 @@ properties.</doc>
another paramspec. All operations other than getting or
setting the value are redirected, including accessing the nick and
blurb, validating a value, and so forth. See
g_param_spec_get_redirect_target() for retrieving the overidden
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.</doc>
@ -10676,10 +10697,26 @@ from type %G_TYPE_BOXED.</doc>
</parameter>
</parameters>
</function-macro>
<constant name="VALUE_INTERNED_STRING" value="268435456" c:type="G_VALUE_INTERNED_STRING" version="2.66">
<doc xml:space="preserve">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().</doc>
<type name="gint" c:type="gint"/>
</constant>
<function-macro name="VALUE_IS_INTERNED_STRING" c:identifier="G_VALUE_IS_INTERNED_STRING" version="2.66" introspectable="0">
<doc xml:space="preserve">Checks whether @value contains a string which is canonical.</doc>
<parameters>
<parameter name="value">
<doc xml:space="preserve">a valid #GValue structure</doc>
</parameter>
</parameters>
</function-macro>
<constant name="VALUE_NOCOPY_CONTENTS" value="134217728" c:type="G_VALUE_NOCOPY_CONTENTS">
<doc xml:space="preserve">If passed to G_VALUE_COLLECT(), allocated data won't be copied
but used verbatim. This does not affect ref-counted types like
objects.</doc>
objects. This does not affect usage of g_value_copy(), the data will
be copied if it is not ref-counted.</doc>
<type name="gint" c:type="gint"/>
</constant>
@ -11455,6 +11492,25 @@ value_table's collect_value() function.</doc>
</parameter>
</parameters>
</method>
<method name="set_interned_string" c:identifier="g_value_set_interned_string" version="2.66">
<doc xml:space="preserve">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.</doc>
<return-value transfer-ownership="none">
<type name="none" c:type="void"/>
</return-value>
<parameters>
<instance-parameter name="value" transfer-ownership="none">
<doc xml:space="preserve">a valid #GValue of type %G_TYPE_STRING</doc>
<type name="Value" c:type="GValue*"/>
</instance-parameter>
<parameter name="v_string" transfer-ownership="none" nullable="1" allow-none="1">
<doc xml:space="preserve">static string to be set</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
</parameters>
</method>
<method name="set_long" c:identifier="g_value_set_long">
<doc xml:space="preserve">Set the contents of a %G_TYPE_LONG #GValue to @v_long.</doc>
@ -11608,7 +11664,10 @@ when setting the #GValue.</doc>
<method name="set_static_string" c:identifier="g_value_set_static_string">
<doc xml:space="preserve">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.</doc>
when setting the #GValue.
If the the string is a canonical string, using g_value_set_interned_string()
is more appropriate.</doc>
<return-value transfer-ownership="none">
<type name="none" c:type="void"/>
@ -13559,6 +13618,35 @@ may change in the future.</doc>
</parameter>
</parameters>
</function>
<docsection name="enumerations_flags">
<doc xml:space="preserve">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:
|[&lt;!-- language="C" --&gt;
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-&gt;value_name);
g_type_class_unref (enum_class);
]|</doc>
</docsection>
<function name="flags_complete_type_info" c:identifier="g_flags_complete_type_info">
<doc xml:space="preserve">This function is meant to be called from the complete_type_info()
function of a #GTypePlugin implementation, see the example for
@ -13687,12 +13775,231 @@ may change in the future.</doc>
</parameter>
</parameters>
</function>
<docsection name="gboxed">
<doc xml:space="preserve">#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) &#x2014; 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&#x2019;s &#x2018;ref&#x2019; function as the #GBoxedCopyFunc, and its &#x2018;unref&#x2019; function as the
#GBoxedFreeFunc. For example, for #GBytes, the #GBoxedCopyFunc is
g_bytes_ref(), and the #GBoxedFreeFunc is g_bytes_unref().</doc>
</docsection>
<docsection name="generic_values">
<doc xml:space="preserve">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.
|[&lt;!-- language="C" --&gt;
#include &lt;glib-object.h&gt;
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 (&amp;a));
// Put a string in it
g_value_init (&amp;a, G_TYPE_STRING);
g_assert (G_VALUE_HOLDS_STRING (&amp;a));
g_value_set_static_string (&amp;a, "Hello, world!");
g_printf ("%s\n", g_value_get_string (&amp;a));
// Reset it to its pristine state
g_value_unset (&amp;a);
// It can then be reused for another type
g_value_init (&amp;a, G_TYPE_INT);
g_value_set_int (&amp;a, 42);
// Attempt to transform it into a GValue of type STRING
g_value_init (&amp;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 (&amp;a, &amp;b);
g_printf ("%s\n", g_value_get_string (&amp;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 (&amp;a, &amp;b);
g_printf ("%s\n", g_value_get_string (&amp;b));
return 0;
}
]|</doc>
</docsection>
<docsection name="gtype">
<doc xml:space="preserve">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&#x2013;z or A&#x2013;Z) or an underscore (&#x2018;_&#x2019;). Subsequent
characters can be letters, numbers or any of &#x2018;-_+&#x2019;.</doc>
</docsection>
<function name="gtype_get_type" c:identifier="g_gtype_get_type">
<return-value transfer-ownership="none">
<type name="GType" c:type="GType"/>
</return-value>
</function>
<docsection name="objects">
<doc xml:space="preserve">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:
|[&lt;!-- language="C" --&gt;
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:
|[&lt;!-- language="C" --&gt;
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:
|[&lt;!-- language="C" --&gt;
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:
|[&lt;!-- language="C" --&gt;
// 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
]|</doc>
</docsection>
<function name="param_spec_boolean" c:identifier="g_param_spec_boolean">
<doc xml:space="preserve">Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
property. In many cases, it may be more appropriate to use an enum with
@ -14587,7 +14894,7 @@ g_param_value_validate().</doc>
<type name="ParamSpec" c:type="GParamSpec*"/>
</parameter>
<parameter name="src_value" transfer-ownership="none">
<doc xml:space="preserve">souce #GValue</doc>
<doc xml:space="preserve">source #GValue</doc>
<type name="Value" c:type="const GValue*"/>
</parameter>
<parameter name="dest_value" transfer-ownership="none">
@ -14637,6 +14944,19 @@ without modifications</doc>
</parameter>
</parameters>
</function>
<docsection name="param_value_types">
<doc xml:space="preserve">#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.</doc>
</docsection>
<function name="param_value_validate" c:identifier="g_param_value_validate">
<doc xml:space="preserve">Ensures that the contents of @value comply with the specifications
set out by @pspec. For example, a #GParamSpecInt might require
@ -14738,7 +15058,7 @@ One convenient usage of this function is in implementing property setters:
<function-macro name="set_weak_pointer" c:identifier="g_set_weak_pointer" version="2.56" introspectable="0">
<doc xml:space="preserve">Updates a pointer to weakly refer to @new_object. It assigns @new_object
to @weak_pointer_location and ensures that @weak_pointer_location will
automaticaly be set to %NULL if @new_object gets destroyed. The assignment
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.
@ -15276,7 +15596,7 @@ specified signal returns a value, but may be ignored otherwise.</doc>
<function name="signal_handler_block" c:identifier="g_signal_handler_block">
<doc xml:space="preserve">Blocks a handler of an instance so it will not be called during any
signal emissions unless it is unblocked again. Thus "blocking" a
signal handler means to temporarily deactive it, a signal handler
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.
@ -15660,6 +15980,25 @@ of building the arguments.</doc>
</parameter>
</parameters>
</function>
<function name="signal_is_valid_name" c:identifier="g_signal_is_valid_name" version="2.66">
<doc xml:space="preserve">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.</doc>
<return-value transfer-ownership="none">
<doc xml:space="preserve">%TRUE if @name is a valid signal name, %FALSE otherwise.</doc>
<type name="gboolean" c:type="gboolean"/>
</return-value>
<parameters>
<parameter name="name" transfer-ownership="none">
<doc xml:space="preserve">the canonical name of the signal</doc>
<type name="utf8" c:type="const gchar*"/>
</parameter>
</parameters>
</function>
<function name="signal_list_ids" c:identifier="g_signal_list_ids">
<doc xml:space="preserve">Lists the signals by id that a certain instance or interface type
created. Further information about the signals can be acquired through
@ -15813,7 +16152,7 @@ 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 overriden by derived classes with
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
@ -16224,6 +16563,92 @@ identified by @itype.</doc>
</parameter>
</parameters>
</function>
<docsection name="signals">
<doc xml:space="preserve">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.</doc>
</docsection>
<function name="source_set_closure" c:identifier="g_source_set_closure">
<doc xml:space="preserve">Set the callback for a source as a #GClosure.
@ -16638,7 +17063,7 @@ 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
implementators of fundamental types only. E.g. instances of the
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.
@ -16684,7 +17109,7 @@ default interface vtable.</doc>
and returns the default interface vtable for the type.
If the type is not currently in use, then the default vtable
for the type will be created and initalized by calling
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
@ -17395,6 +17820,29 @@ that implements or has internal knowledge of the implementation of
</parameter>
</parameters>
</function>
<docsection name="value_arrays">
<doc xml:space="preserve">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:
|[&lt;!-- language="C" --&gt;
GValueArray *array = g_value_array_new (10);
]|
can be replaced by:
|[&lt;!-- language="C" --&gt;
GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
]|</doc>
</docsection>
<function name="value_register_transform_func" c:identifier="g_value_register_transform_func" moved-to="Value.register_transform_func" introspectable="0">
<doc xml:space="preserve">Registers a value transformation function for use in g_value_transform().
A previously registered transformation function for @src_type and @dest_type

1021
gir-files/Gio-2.0.gir
View file

File diff suppressed because it is too large Load diff