mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-10 19:36:18 +01:00
bbc5a3adac
Sat Feb 17 04:55:35 2001 Tim Janik <timj@gtk.org>
* gtype.[hc]: changed collect_format, collect_value() and lcopy_format,
lcopy_value() in the GTypeValueTable. the collect functions are now
called only once per value, collect_format/lcopy_format are strings
that enlist all necessary GTypeCValues to be varargs-collected.
* gvalue.h: ranamed STATIC_TAG to G_VALUE_NOCOPY_CONTENTS to indicate that
a value shouldn't copy its contents.
* gvaluecollector.h: changed G_VALUE_COLLECT() and G_VALUE_LCOPY()
macros to carry an additional argument (flags) that can be used
to pass G_VALUE_NOCOPY_CONTENTS along to the collection functions.
* *.c: adapted collect_value() and lcopy_value() functions to the new
prototypes, support G_VALUE_NOCOPY_CONTENTS where apropriate.
* gsignal.[hc]: introduced a G_SIGNAL_TYPE_STATIC_SCOPE flag that can
be passed along (ORed) with the parameter types, indicating that the
emission arguments are to be considered static for the scope of the
emission. should be used with care and only if the caller knows that
a parameter cannot be destroyed/freed from signal handlers connected
to an emission.
589 lines
12 KiB
Plaintext
589 lines
12 KiB
Plaintext
<!-- ##### SECTION ./tmpl/closures.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/closures.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/closures.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/closures.sgml:Title ##### -->
|
|
Closures
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/enumerations_flags.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/enumerations_flags.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/enumerations_flags.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/enumerations_flags.sgml:Title ##### -->
|
|
Enumeration and Flag Types
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gboxed.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gboxed.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gboxed.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gboxed.sgml:Title ##### -->
|
|
gboxed
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/generic_values.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/generic_values.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/generic_values.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/generic_values.sgml:Title ##### -->
|
|
Generic values
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Title ##### -->
|
|
gtypemodule.sgml
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypemodule.sgml:Long_Description ##### -->
|
|
<para>
|
|
#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 registerse 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.
|
|
</para>
|
|
<para>
|
|
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 explicitely 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.
|
|
</para>
|
|
<para>
|
|
#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.
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypemodule.sgml:See_Also ##### -->
|
|
<para>
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>#GTypePlugin</term>
|
|
<listitem><para>The abstract type loader interface.</para></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>#GModule</term>
|
|
<listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypemodule.sgml:Short_Description ##### -->
|
|
Type Loading Modules
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypemodule.sgml:Title ##### -->
|
|
GTypeModule
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypeplugin.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypeplugin.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypeplugin.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/gtypeplugin.sgml:Title ##### -->
|
|
GTypePlugin
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/objects.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/objects.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/objects.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/objects.sgml:Title ##### -->
|
|
The Base Object Type
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/param_specs.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/param_specs.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/param_specs.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/param_specs.sgml:Title ##### -->
|
|
Parameter Specifications
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/signals.sgml:Long_Description ##### -->
|
|
<para>
|
|
The basic concept of the signal system is that of the <emphasis>emission</emphasis>
|
|
of a signal.
|
|
Signals are introduced per-type and are identified through strings.
|
|
Signals introduced for a parent type are availale in derived types as well,
|
|
so basically they are a per-type facility that is inherited.
|
|
A signal emission mainly involves invocation of a certain set of callbacks in
|
|
precisely defined manner. There are two main categories of such callbacks,
|
|
per-object
|
|
<footnote><para> Although signals can deal with any kind of type, i'm
|
|
referring to those types as "object types" in the following, simply
|
|
because that is the context most users will encounter signals in.
|
|
</para></footnote>
|
|
ones and user provided ones.
|
|
The per-object callbacks are most often referred to as "object method
|
|
handler" or "default (signal) handler", while user provided callbacks are
|
|
usually just called "signal handler".
|
|
The object method handler is provided at signal creation time (this most
|
|
frequently happens at the end of an object class' creation), while user
|
|
provided handlers are frequently connected and disconnected to/from a certain
|
|
signal on certain object instances.
|
|
</para>
|
|
<para>
|
|
A signal emission consists of five stages, unless prematurely stopped:
|
|
<variablelist>
|
|
<varlistentry><term></term><listitem><para>
|
|
1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term></term><listitem><para>
|
|
2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term></term><listitem><para>
|
|
3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term></term><listitem><para>
|
|
4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
|
|
</para></listitem></varlistentry>
|
|
<varlistentry><term></term><listitem><para>
|
|
5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
|
|
</para></listitem></varlistentry>
|
|
</variablelist>
|
|
The user provided signal handlers are called in the order they were
|
|
connected in.
|
|
All handlers may prematurely stop a signal emission, and any number of
|
|
handlers may be connected, disconnected, blocked or unblocked during
|
|
a signal emission.
|
|
There are certain criteria for skipping user handlers in stages 2 and 4
|
|
of a signal emission.
|
|
First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted
|
|
during callback invocation, to return from the "blocked" state, a
|
|
handler has to get unblocked exactly the same amount of times
|
|
it has been blocked before.
|
|
Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
|
|
"detail" argument passed in to g_signal_emit() has to match the detail
|
|
argument of the signal handler currently subject to invocation.
|
|
Specification of no detail argument for signal handlers (omission of the
|
|
detail part of the signal specification upon connection) serves as a
|
|
wildcard and matches any detail argument passed in to emission.
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/signals.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/signals.sgml:Short_Description ##### -->
|
|
Signals provide a means for customization of object behaviour and are used
|
|
as general purpose notification mechanism.
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/signals.sgml:Title ##### -->
|
|
Signals
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/standard_params.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/standard_params.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/standard_params.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/standard_params.sgml:Title ##### -->
|
|
Standard Parameter Types
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/value_collection.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/value_collection.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/value_collection.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/value_collection.sgml:Title ##### -->
|
|
Varargs Value Collection
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/value_types.sgml:Long_Description ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/value_types.sgml:See_Also ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/value_types.sgml:Short_Description ##### -->
|
|
|
|
|
|
|
|
<!-- ##### SECTION ./tmpl/value_types.sgml:Title ##### -->
|
|
Standard value types
|
|
|
|
|
|
<!-- ##### USER_FUNCTION GObjectGetParamFunc ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@param_id:
|
|
@value:
|
|
@pspec:
|
|
@trailer:
|
|
|
|
<!-- ##### USER_FUNCTION GObjectSetParamFunc ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@param_id:
|
|
@value:
|
|
@pspec:
|
|
@trailer:
|
|
|
|
<!-- ##### ENUM GSignalType ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@G_SIGNAL_RUN_FIRST:
|
|
@G_SIGNAL_RUN_LAST:
|
|
@G_SIGNAL_RUN_CLEANUP:
|
|
@G_SIGNAL_NO_RECURSE:
|
|
@G_SIGNAL_ACTION:
|
|
@G_SIGNAL_NO_HOOKS:
|
|
|
|
<!-- ##### USER_FUNCTION GTypePluginFillInterfaceInfo ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@plugin:
|
|
@interface_type:
|
|
@instance_type:
|
|
@info:
|
|
|
|
<!-- ##### USER_FUNCTION GTypePluginFillTypeInfo ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@plugin:
|
|
@g_type:
|
|
@info:
|
|
@value_table:
|
|
|
|
<!-- ##### USER_FUNCTION GTypePluginRef ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@plugin:
|
|
|
|
<!-- ##### USER_FUNCTION GTypePluginUnRef ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@plugin:
|
|
|
|
<!-- ##### STRUCT GTypePluginVTable ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@plugin_ref:
|
|
@plugin_unref:
|
|
@complete_type_info:
|
|
@complete_interface_info:
|
|
|
|
<!-- ##### MACRO G_IS_PARAM_VALUE ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@pspec:
|
|
@value:
|
|
|
|
<!-- ##### MACRO G_NOTIFY_PRIORITY ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
|
|
<!-- ##### MACRO G_WARN_INVALID_PARAM_ID ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@param_id:
|
|
@pspec:
|
|
|
|
<!-- ##### FUNCTION g_object_class_find_param_spec ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@oclass:
|
|
@param_name:
|
|
@Returns:
|
|
|
|
<!-- ##### FUNCTION g_object_class_install_param ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@oclass:
|
|
@param_id:
|
|
@pspec:
|
|
|
|
<!-- ##### FUNCTION g_object_get_param ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@param_name:
|
|
@value:
|
|
|
|
<!-- ##### FUNCTION g_object_queue_param_changed ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@param_name:
|
|
|
|
<!-- ##### FUNCTION g_object_set_param ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@object:
|
|
@param_name:
|
|
@value:
|
|
|
|
<!-- ##### FUNCTION g_param_spec_hash_table_insert ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@hash_table:
|
|
@pspec:
|
|
@owner_type:
|
|
|
|
<!-- ##### FUNCTION g_param_spec_hash_table_lookup ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@hash_table:
|
|
@param_name:
|
|
@owner_type:
|
|
@try_ancestors:
|
|
@trailer:
|
|
@Returns:
|
|
|
|
<!-- ##### FUNCTION g_param_spec_hash_table_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@Returns:
|
|
|
|
<!-- ##### FUNCTION g_param_spec_hash_table_remove ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@hash_table:
|
|
@pspec:
|
|
|
|
<!-- ##### FUNCTION g_signal_type_closure_new ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@itype:
|
|
@struct_offset:
|
|
@Returns:
|
|
|
|
<!-- ##### FUNCTION g_signals_destroy ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@itype:
|
|
|
|
<!-- ##### FUNCTION g_type_conforms_to ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@type:
|
|
@iface_type:
|
|
@Returns:
|
|
|
|
<!-- ##### FUNCTION g_type_instance_conforms_to ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@instance:
|
|
@iface_type:
|
|
@Returns:
|
|
|
|
<!-- ##### FUNCTION g_type_is_dynamic ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@type:
|
|
@flags:
|
|
@Returns:
|
|
|
|
<!-- ##### FUNCTION g_type_value_conforms_to ##### -->
|
|
<para>
|
|
|
|
</para>
|
|
|
|
@value:
|
|
@type:
|
|
@Returns:
|
|
|