luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-07-24 02:47:52 +02:00
Code Issues Packages Projects Releases Wiki Activity

Move all docs out-of-line. Boy, what a waste of time.

Browse Source 
2003-02-07  Matthias Clasen  <maclas@gmx.de>

	* gobject/tmpl/gtypemodule.sgml:
	* gobject/tmpl/gtype.sgml:
	* gobject/tmpl/gclosure.sgml:
	* gobject/tmpl/param_value_types.sgml:
	* gobject/tmpl/gparamspec.sgml:
	* gobject/tmpl/objects.sgml:
	* gobject/tmpl/signals.sgml: Move all docs out-of-line. Boy, what
	a waste of time.
This commit is contained in:
Matthias Clasen
2003-02-07 22:08:53 +00:00
committed by Matthias Clasen
parent fa21b512d5
commit 280a213b09
9 changed files with 680 additions and 359 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/reference/ChangeLog
View File

@@ -1,3 +1,14 @@
2003-02-07 Matthias Clasen <maclas@gmx.de>
* gobject/tmpl/gtypemodule.sgml:
* gobject/tmpl/gtype.sgml:
* gobject/tmpl/gclosure.sgml:
* gobject/tmpl/param_value_types.sgml:
* gobject/tmpl/gparamspec.sgml:
* gobject/tmpl/objects.sgml:
* gobject/tmpl/signals.sgml: Move all docs out-of-line. Boy, what
a waste of time.
2003-01-21 Matthias Clasen <maclas@gmx.de>
* glib/tmpl/strings.sgml: Document the return value of g_string_free().

11
docs/reference/gobject/tmpl/gclosure.sgml
View File

@@ -319,11 +319,16 @@ atfer this function, unles g_closure_ref() was called beforehand.
<!-- ##### FUNCTION g_source_set_closure ##### -->
<para>
Set the callback for a source as a #GClosure.
</para>
<para>
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.
</para>
@source:
@closure:
@source: the source
@closure: a #GClosure
<!-- ##### MACRO G_TYPE_IO_CHANNEL ##### -->

7
docs/reference/gobject/tmpl/gobject-unused.sgml
View File

@@ -196,6 +196,13 @@ Shift value used in converting numbers to type IDs.
@closure:
@Returns:
<!-- ##### FUNCTION g_signal_handlers_destroy ##### -->
<para>
</para>
@instance:
<!-- ##### MACRO g_signal_newc ##### -->
<para>

25
docs/reference/gobject/tmpl/gparamspec.sgml
View File

@@ -311,15 +311,26 @@ if @value1 is found to be less than, equal to or greater than @value2, respectiv
<!-- ##### FUNCTION g_param_spec_internal ##### -->
<para>
Creates a new #GParamSpec instance.
</para>
<para>
A property name consists of segments consisting of ASCII letters and
digits, separated by either the '-' or '_' character. The first
character of a property name must be a letter. Names which violate these
rules lead to undefined behaviour.
</para>
<para>
When creating and looking up a #GParamSpec, either separator can be used,
but they cannot be mixed. Using '-' is considerably more efficient and in
fact required when using property names as detail strings for signals.
</para>
@param_type:
@name:
@nick:
@blurb:
@flags:
@Returns:
@param_type: the #GType for the property; must be derived from #G_TYPE_PARAM
@name: the canonical name of the property
@nick: the nickname of the property
@blurb: a short description of the property
@flags: a combination of #GParamFlags
@Returns: a newly allocated #GParamSpec instance
<!-- ##### STRUCT GParamSpecTypeInfo ##### -->

79
docs/reference/gobject/tmpl/gtype.sgml
View File

@@ -707,11 +707,16 @@ class conforms.
<!-- ##### FUNCTION g_type_interface_peek_parent ##### -->
<para>
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.
</para>
@g_iface:
@Returns:
@g_iface: A #GTypeInterface structure.
@Returns: 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.
<!-- ##### FUNCTION g_type_children ##### -->
@@ -739,40 +744,50 @@ g_free()ed after use.
<!-- ##### FUNCTION g_type_interface_prerequisites ##### -->
<para>
Returns the prerequisites of an interfaces type.
</para>
@interface_type:
@n_prerequisites:
@Returns:
@interface_type: an interface type
@n_prerequisites: location to return the number of prerequisites, or %NULL
@Returns: a newly-allocated zero-terminated array of #GType containing
the prerequisites of @interface_type
<!-- # Unused Parameters # -->
@Since: 2.2
<!-- ##### FUNCTION g_type_set_qdata ##### -->
<para>
Attaches arbitrary data to a type.
</para>
@type:
@quark:
@data:
@type: a #GType
@quark: a #GQuark id to identify the data
@data: the data
<!-- ##### FUNCTION g_type_get_qdata ##### -->
<para>
Obtains data which has previously been attached to @type
with g_type_set_qdata().
</para>
@type:
@quark:
@Returns:
@type: a #GType
@quark: a #GQuark id to identify the data
@Returns: the data, or %NULL if no data was found
<!-- ##### FUNCTION g_type_query ##### -->
<para>
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.
</para>
@type:
@query:
@type: the #GType value of a static, classed type.
@query: A user provided structure that is filled in with constant values
upon success.
<!-- ##### STRUCT GTypeQuery ##### -->
@@ -1068,20 +1083,27 @@ is used to manage the relationship.
<!-- ##### FUNCTION g_type_add_interface_dynamic ##### -->
<para>
Adds the dynamic @interface_type to @instantiable_type. The information
contained in the #GTypePlugin structure pointed to by @plugin
is used to manage the relationship.
</para>
@instance_type:
@interface_type:
@plugin:
@instance_type: the #GType value of an instantiable type.
@interface_type: the #GType value of an interface type.
@plugin: the #GTypePlugin structure to retrieve the #GInterfaceInfo from.
<!-- ##### FUNCTION g_type_interface_add_prerequisite ##### -->
<para>
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.
</para>
@interface_type:
@prerequisite_type:
@interface_type: #GType value of an interface type.
@prerequisite_type: #GType value of an interface or instantiatable type.
<!-- ##### FUNCTION g_type_get_plugin ##### -->
@@ -1097,11 +1119,16 @@ Returns the #GTypePlugin structure for @type or
<!-- ##### FUNCTION g_type_interface_get_plugin ##### -->
<para>
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().
</para>
@instance_type:
@interface_type:
@Returns:
@instance_type: the #GType value of an instantiatable type.
@interface_type: the #GType value of an interface type.
@Returns: the #GTypePlugin for the dynamic interface @interface_type
of @instance_type.
<!-- ##### FUNCTION g_type_fundamental_next ##### -->

59
docs/reference/gobject/tmpl/gtypemodule.sgml
View File

@@ -71,51 +71,70 @@ in #GTypeModuleClass.
<!-- ##### FUNCTION g_type_module_use ##### -->
<para>
Increases the use count of a #GTypeModule by one. If the
use count was zero before, the plugin will be loaded.
</para>
@module:
@Returns:
@module: a #GTypeModule
@Returns: %FALSE if the plugin needed to be loaded and
loading the plugin failed.
<!-- ##### FUNCTION g_type_module_unuse ##### -->
<para>
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.)
</para>
@module:
@module: a #GTypeModule
<!-- ##### FUNCTION g_type_module_set_name ##### -->
<para>
Sets the name for a #GTypeModule
</para>
@module:
@name:
@module: a #GTypeModule.
@name: a human-readable name to use in error messages.
<!-- ##### FUNCTION g_type_module_register_type ##### -->
<para>
Looks up or registers a type that is implemented with a particular
type plugin. If a type with name @type_name is already registered,
the #GType identifier for the type is returned, otherwise the type
is newly registered, and the resulting #GType identifier returned.
</para>
<para>
As long as any instances of the type exist, the type plugin will
not be unloaded.
</para>
@module:
@parent_type:
@type_name:
@type_info:
@flags:
@Returns:
@module: a #GTypeModule
@parent_type: the type for the parent class
@type_name: name for the type
@type_info: type information structure
@flags: flags field providing details about the type
@Returns: the type ID for the class.
<!-- ##### FUNCTION g_type_module_add_interface ##### -->
<para>
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.
</para>
<para>
As long as any instances of the type exist, the type plugin will
not be unloaded.
</para>
@module:
@instance_type:
@interface_type:
@interface_info:
@module: a #GTypeModule
@instance_type: type to which to add the interface.
@interface_type: interface type to add
@interface_info: type information structure

55
docs/reference/gobject/tmpl/objects.sgml
View File

@@ -16,8 +16,8 @@ The base object type
<!-- ##### STRUCT GObject ##### -->
<para>
All the fields in the GObject structure are private to the #GObject implementation
and should never be accessed directly.
All the fields in the <structname>GObject</structname> structure are private
to the #GObject implementation and should never be accessed directly.
</para>
@g_type_instance:
@@ -37,8 +37,6 @@ and should never be accessed directly.
@property_id:
@value:
@pspec:
<!-- # Unused Parameters # -->
@trailer:
<!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
@@ -50,8 +48,6 @@ and should never be accessed directly.
@property_id:
@value:
@pspec:
<!-- # Unused Parameters # -->
@trailer:
<!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
@@ -64,7 +60,7 @@ and should never be accessed directly.
<!-- ##### MACRO G_TYPE_IS_OBJECT ##### -->
<para>
Return a boolean value of %FALSE or %TRUE indicating whether
Returns a boolean value of %FALSE or %TRUE indicating whether
the passed in type id is a %G_TYPE_OBJECT or derived from it.
</para>
@@ -74,7 +70,7 @@ the passed in type id is a %G_TYPE_OBJECT or derived from it.
<!-- ##### MACRO G_OBJECT ##### -->
<para>
Cast a #GObject or derived pointer into a (GObject*) pointer.
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.
</para>
@@ -84,7 +80,7 @@ certain runtime checks to identify invalid casts.
<!-- ##### MACRO G_IS_OBJECT ##### -->
<para>
Check whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
</para>
@object: Instance to check for being a %G_TYPE_OBJECT.
@@ -92,26 +88,27 @@ Check whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
<!-- ##### MACRO G_OBJECT_CLASS ##### -->
<para>
Casts a derived #GObjectClass structure into a #GObjectClass structure.
</para>
@class:
@class: a valid #GObjectClass
<!-- ##### MACRO G_IS_OBJECT_CLASS ##### -->
<para>
Checks whether @class "is a" valid #GObjectClass structure of type
%G_TYPE_OBJECT or derived.
</para>
@class:
@class: a #GObjectClass
<!-- ##### MACRO G_OBJECT_GET_CLASS ##### -->
<para>
Returns the class structure associated to a #GObject instance.
</para>
@object:
@object: a #GObject instance.
<!-- ##### MACRO G_OBJECT_TYPE ##### -->
@@ -125,10 +122,12 @@ Return the type id of an object.
<!-- ##### MACRO G_OBJECT_TYPE_NAME ##### -->
<para>
Returns the name of an object's type.
</para>
@object:
@object: Object to return the type name for.
@Returns: Type name of @object. The string is owned by the type system and
should not be freed.
<!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### -->
@@ -149,10 +148,14 @@ Return the type id of an object.
<!-- ##### FUNCTION g_object_class_install_property ##### -->
<para>
Installs a new property. This is usually done in the class initializer.
</para>
@oclass:
@property_id: the id for the new property
@pspec: the #GParamSpec for the new property
<!-- # Unused Parameters # -->
@class: a #GObjectClass
@property_id:
@pspec:
@@ -325,27 +328,29 @@ to match the one used with g_object_add_weak_pointer().
<!-- ##### FUNCTION g_object_notify ##### -->
<para>
Emits a "notify" signal for the property @property_name on @object.
</para>
@object:
@property_name:
@object: a #GObject
@property_name: the name of a property installed on the class of @object.
<!-- ##### FUNCTION g_object_freeze_notify ##### -->
<para>
Stops emission of "notify" signals on @object. The signals are
queued until g_object_thaw_notify() is called on @object.
</para>
@object:
@object: a #GObject
<!-- ##### FUNCTION g_object_thaw_notify ##### -->
<para>
Reverts the effect of a previous call to g_object_freeze_notify().
This causes all queued "notify" signals on @object to be emitted.
</para>
@object:
@object: a #GObject
<!-- ##### FUNCTION g_object_get_data ##### -->

269
docs/reference/gobject/tmpl/param_value_types.sgml
View File

@@ -60,14 +60,19 @@ A #GParamSpec derived structure that contains the meta data for boolean properti
<!-- ##### FUNCTION g_param_spec_boolean ##### -->
<para>
Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN
property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_boolean ##### -->
@@ -131,16 +136,17 @@ A #GParamSpec derived structure that contains the meta data for character proper
<!-- ##### FUNCTION g_param_spec_char ##### -->
<para>
Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_char ##### -->
@@ -204,16 +210,17 @@ A #GParamSpec derived structure that contains the meta data for unsigned charact
<!-- ##### FUNCTION g_param_spec_uchar ##### -->
<para>
Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_uchar ##### -->
@@ -277,16 +284,20 @@ A #GParamSpec derived structure that contains the meta data for integer properti
<!-- ##### FUNCTION g_param_spec_int ##### -->
<para>
Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_int ##### -->
@@ -350,16 +361,20 @@ A #GParamSpec derived structure that contains the meta data for unsigned integer
<!-- ##### FUNCTION g_param_spec_uint ##### -->
<para>
Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_uint ##### -->
@@ -423,16 +438,20 @@ A #GParamSpec derived structure that contains the meta data for long integer pro
<!-- ##### FUNCTION g_param_spec_long ##### -->
<para>
Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_long ##### -->
@@ -496,17 +515,20 @@ A #GParamSpec derived structure that contains the meta data for unsigned long in
<!-- ##### FUNCTION g_param_spec_ulong ##### -->
<para>
Create a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property.
Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_ulong ##### -->
@@ -570,16 +592,20 @@ A #GParamSpec derived structure that contains the meta data for 64bit integer pr
<!-- ##### FUNCTION g_param_spec_int64 ##### -->
<para>
Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_int64 ##### -->
@@ -643,16 +669,21 @@ A #GParamSpec derived structure that contains the meta data for unsigned 64bit i
<!-- ##### FUNCTION g_param_spec_uint64 ##### -->
<para>
Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64
property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_uint64 ##### -->
@@ -717,16 +748,20 @@ A #GParamSpec derived structure that contains the meta data for float properties
<!-- ##### FUNCTION g_param_spec_float ##### -->
<para>
Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_float ##### -->
@@ -791,16 +826,21 @@ A #GParamSpec derived structure that contains the meta data for double propertie
<!-- ##### FUNCTION g_param_spec_double ##### -->
<para>
Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE
property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@minimum:
@maximum:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@minimum: minimum value for the property specified
@maximum: maximum value for the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_double ##### -->
@@ -1200,14 +1240,19 @@ A #GParamSpec derived structure that contains the meta data for boxed properties
<!-- ##### FUNCTION g_param_spec_boxed ##### -->
<para>
Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED
derived property.
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@boxed_type:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@boxed_type: %G_TYPE_BOXED derived type of this property
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### FUNCTION g_value_set_boxed ##### -->
@@ -1447,14 +1492,20 @@ A #GParamSpec derived structure that contains the meta data for unichar (unsigne
<!-- ##### FUNCTION g_param_spec_unichar ##### -->
<para>
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().
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@default_value:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@default_value: default value for the property specified
@flags: flags for the property specified
@Returns: a newly created parameter specification
<!-- ##### MACRO G_IS_PARAM_SPEC_VALUE_ARRAY ##### -->
@@ -1491,13 +1542,21 @@ A #GParamSpec derived structure that contains the meta data for #GValueArray pro
<!-- ##### FUNCTION g_param_spec_value_array ##### -->
<para>
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().
</para>
<para>
See g_param_spec_internal() for details on property names.
</para>
@name:
@nick:
@blurb:
@element_spec:
@flags:
@Returns:
@name: canonical name of the property specified
@nick: nick name for the property specified
@blurb: description of the property specified
@element_spec: a #GParamSpec describing the elements contained in
arrays of this property, may be %NULL
@flags: flags for the property specified
@Returns: a newly created parameter specification

523
docs/reference/gobject/tmpl/signals.sgml
View File

@@ -233,135 +233,213 @@ of g_signal_new().
<!-- ##### FUNCTION g_signal_new ##### -->
<para>
Creates a new signal. (This is usually done in the class initializer.)
</para>
<para>
A signal name consists of segments consisting of ASCII letters and
digits, separated by either the '-' or '_' character. The first
character of a signal name must be a letter. Names which violate these
rules lead to undefined behaviour of the GSignal system.
</para>
<para>
When registering a signal and looking up a signal, either separator can
be used, but they cannot be mixed.
</para>
@signal_name:
@itype:
@signal_flags:
@class_offset:
@accumulator:
@accu_data:
@c_marshaller:
@return_type:
@n_params:
@Varargs:
@Returns:
@signal_name: the name for the signal
@itype: the type this signal pertains to. It will also pertain to
types which are derived from this type.
@signal_flags: a combination of #GSignalFlags specifying detail of when
the default handler is to be invoked. You should at least specify
%G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
@class_offset: The offset of the function pointer in the class structure
for this type. Used to invoke a class method generically.
@accumulator: the accumulator for this signal; may be %NULL.
@accu_data: user data for the @accumulator.
@c_marshaller: the function to translate arrays of parameter values to
signal emissions into C language callback invocations.
@return_type: the type of return value, or #G_TYPE_NONE for a signal
without a return value.
@n_params: the number of parameter types to follow.
@Varargs: a list of types, one for each parameter.
@Returns: the signal id
<!-- ##### FUNCTION g_signal_newv ##### -->
<para>
Creates a new signal. (This is usually done in the class initializer.)
</para>
<para>
See g_signal_new() for details on allowed signal names.
</para>
@signal_name:
@itype:
@signal_flags:
@class_closure:
@accumulator:
@accu_data:
@c_marshaller:
@return_type:
@n_params:
@param_types:
@Returns:
@signal_name: the name for the signal
@itype: the type this signal pertains to. It will also pertain to
types which are derived from this type.
@signal_flags: a combination of #GSignalFlags specifying detail of when
the default handler is to be invoked. You should at least specify
%G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
@class_closure: The closure to invoke on signal emission.
@accumulator: the accumulator for this signal; may be %NULL.
@accu_data: user data for the @accumulator.
@c_marshaller: the function to translate arrays of parameter values to
signal emissions into C language callback invocations.
@return_type: the type of return value, or #G_TYPE_NONE for a signal
without a return value.
@n_params: the length of @param_types.
@param_types: an array types, one for each parameter.
@Returns: the signal id
<!-- ##### FUNCTION g_signal_new_valist ##### -->
<para>
Creates a new signal. (This is usually done in the class initializer.)
</para>
<para>
See g_signal_new() for details on allowed signal names.
</para>
@signal_name:
@itype:
@signal_flags:
@class_closure:
@accumulator:
@accu_data:
@c_marshaller:
@return_type:
@n_params:
@args:
@Returns:
@signal_name: the name for the signal
@itype: the type this signal pertains to. It will also pertain to
types which are derived from this type.
@signal_flags: a combination of #GSignalFlags specifying detail of when
the default handler is to be invoked. You should at least specify
%G_SIGNAL_RUN_FIRST or %G_SIGNAL_RUN_LAST.
@class_closure: The closure to invoke on signal emission.
@accumulator: the accumulator for this signal; may be %NULL.
@accu_data: user data for the @accumulator.
@c_marshaller: the function to translate arrays of parameter values to
signal emissions into C language callback invocations.
@return_type: the type of return value, or #G_TYPE_NONE for a signal
without a return value.
@n_params: the number of parameter types in @args.
@args: va_list of #GType, one for each parameter.
@Returns: the signal id
<!-- ##### FUNCTION g_signal_query ##### -->
<para>
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.
</para>
@signal_id:
@query:
@signal_id: The signal id of the signal to query information for.
@query: A user provided structure that is filled in with constant
values upon success.
<!-- ##### FUNCTION g_signal_lookup ##### -->
<para>
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.
</para>
<para>
Also tries the ancestors of the given type.
</para>
<para>
See g_signal_new() for details on allowed signal names.
</para>
@name:
@itype:
@Returns:
@name: the signal's name.
@itype: the type that the signal operates on.
@Returns: the signal's identifying number, or 0 if no signal was found.
<!-- ##### FUNCTION g_signal_name ##### -->
<para>
Given the signal's identifier, finds its name.
</para>
<para>
Two different signals may have the same name, if they have differing types.
</para>
@signal_id:
@Returns:
@signal_id: the signal's identifying number.
@Returns: the signal name, or %NULL if the signal number was invalid.
<!-- ##### FUNCTION g_signal_list_ids ##### -->
<para>
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().
</para>
@itype:
@n_ids:
@Returns:
@itype: Instance or interface type.
@n_ids: Location to store the number of signal ids for @itype.
@Returns: Newly allocated array of signal IDs.
<!-- ##### FUNCTION g_signal_emit ##### -->
<para>
Emits a signal.
</para>
<para>
Note that g_signal_emit() resets the return value to the default
if no handlers are connected, in contrast to g_signal_emitv().
</para>
@instance:
@signal_id:
@detail:
@Varargs:
@instance: the instance the signal is being emitted on.
@signal_id: the signal id
@detail: the detail
@Varargs: 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.
<!-- ##### FUNCTION g_signal_emit_by_name ##### -->
<para>
Emits a signal.
</para>
<para>
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().
</para>
@instance:
@detailed_signal:
@Varargs:
@instance: the instance the signal is being emitted on.
@detailed_signal: a string of the form "signal-name::detail".
@Varargs: 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.
<!-- ##### FUNCTION g_signal_emitv ##### -->
<para>
Emits a signal.
</para>
<para>
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().
</para>
@instance_and_params:
@signal_id:
@detail:
@return_value:
@instance_and_params: argument list for the signal emission. The first
element in the array is a #GValue for the instance the signal is
being emitted on. The rest are any arguments to be passed to the
signal.
@signal_id: the signal id
@detail: the detail
@return_value: Location to store the return value of the signal emission.
<!-- ##### FUNCTION g_signal_emit_valist ##### -->
<para>
Emits a signal.
</para>
<para>
Note that g_signal_emit_valist() resets the return value to the default
if no handlers are connected, in contrast to g_signal_emitv().
</para>
@instance:
@signal_id:
@detail:
@var_args:
@instance: the instance the signal is being emitted on.
@signal_id: the signal id
@detail: the detail
@var_args: a list of parameters to be passed to the signal, followed by a
location for the return value. If the return type of the signal
is #G_TYPE_NONE, the return value location can be omitted.
<!-- ##### MACRO g_signal_connect ##### -->
@@ -412,15 +490,22 @@ calling the handler.
<!-- ##### FUNCTION g_signal_connect_object ##### -->
<para>
* This is similar to g_signal_connect_data(), but uses a closure which
* ensures that the object stays alive during the call to @c_handler.
</para>
* @instance: the instance to connect to.
* @detailed_signal: a string of the form "signal-name::detail".
* @c_handler: the #GCallback to connect.
* @gobject: the object to pass as data to @c_handler.
* @connect_flags: a combination of #GConnnectFlags.
@instance:
@detailed_signal:
@c_handler:
@gobject:
@connect_flags:
@Returns:
@Returns: the handler id.
<!-- ##### ENUM GConnectFlags ##### -->
@@ -436,131 +521,194 @@ connection.
<!-- ##### FUNCTION g_signal_connect_data ##### -->
<para>
Connects a #GCallback function to a signal for a particular object.
</para>
@instance:
@detailed_signal:
@c_handler:
@data:
@destroy_data:
@connect_flags:
@Returns:
@instance: the instance to connect to.
@detailed_signal: a string of the form "signal-name::detail".
@c_handler: the #GCallback to connect.
@data: data to pass to @c_handler calls.
@destroy_data: a #GDestroyNotify for @data.
@connect_flags: a combination of #GConnectFlags.
@Returns: the handler id
<!-- ##### FUNCTION g_signal_connect_closure ##### -->
<para>
Connects a closure to a signal for a particular object.
</para>
@instance:
@detailed_signal:
@closure:
@after:
@Returns:
@instance: the instance to connect to.
@detailed_signal: a string of the form "signal-name::detail".
@closure: the closure to connect.
@after: whether the handler should be called before or after the
default handler of the signal.
@Returns: the handler id
<!-- ##### FUNCTION g_signal_connect_closure_by_id ##### -->
<para>
Connects a closure to a signal for a particular object.
</para>
@instance:
@signal_id:
@detail:
@closure:
@after:
@Returns:
@instance: the instance to connect to.
@signal_id: the id of the signal.
@detail: the detail.
@closure: the closure to connect.
@after: whether the handler should be called before or after the
default handler of the signal.
@Returns: the handler id
<!-- ##### FUNCTION g_signal_handler_block ##### -->
<para>
Blocks a handler of an instance so it will not be called during
any signal emissions unless it is unblocked again. Thus "blocking"
a signal handler means to temporarily deactive it, a signal handler
has to be unblocked exactly the same amount of times it has been
blocked before to become active again.
</para>
<para>
The @handler_id has to be a valid signal handler id, connected to a
signal of @instance.
</para>
@instance:
@handler_id:
@instance: The instance to block the signal handler of.
@handler_id: Handler id of the handler to be blocked.
<!-- ##### FUNCTION g_signal_handler_unblock ##### -->
<para>
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).
</para>
<para>
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.
</para>
@instance:
@handler_id:
@instance: The instance to unblock the signal handler of.
@handler_id: Handler id of the handler to be unblocked.
<!-- ##### FUNCTION g_signal_handler_disconnect ##### -->
<para>
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.
</para>
<para>
The @handler_id has to be a valid signal handler id, connected to a
signal of @instance.
</para>
@instance:
@handler_id:
@instance: The instance to remove the signal handler from.
@handler_id: Handler id of the handler to be disconnected.
<!-- ##### FUNCTION g_signal_handler_find ##### -->
<para>
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.
</para>
@instance:
@mask:
@signal_id:
@detail:
@closure:
@func:
@data:
@Returns:
@instance: The instance owning the signal handler to be found.
@mask: Mask indicating which of @signal_id, @detail, @closure, @func
and/or @data the handler has to match.
@signal_id: Signal the handler has to be connected to.
@detail: Signal detail the handler has to be connected to.
@closure: The closure the handler will invoke.
@func: The C closure callback of the handler (useless for non-C closures).
@data: The closure data of the handler's closure.
@Returns: A valid non-0 signal handler id for a successful match.
<!-- ##### FUNCTION g_signal_handlers_block_matched ##### -->
<para>
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.
</para>
@instance:
@mask:
@signal_id:
@detail:
@closure:
@func:
@data:
@Returns:
@instance: The instance to block handlers from.
@mask: Mask indicating which of @signal_id, @detail, @closure, @func
and/or @data the handlers have to match.
@signal_id: Signal the handlers have to be connected to.
@detail: Signal detail the handlers have to be connected to.
@closure: The closure the handlers will invoke.
@func: The C closure callback of the handlers (useless for non-C closures).
@data: The closure data of the handlers' closures.
@Returns: The amount of handlers that got blocked.
<!-- ##### FUNCTION g_signal_handlers_unblock_matched ##### -->
<para>
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.
</para>
@instance:
@mask:
@signal_id:
@detail:
@closure:
@func:
@data:
@Returns:
@instance: The instance to unblock handlers from.
@mask: Mask indicating which of @signal_id, @detail, @closure, @func
and/or @data the handlers have to match.
@signal_id: Signal the handlers have to be connected to.
@detail: Signal detail the handlers have to be connected to.
@closure: The closure the handlers will invoke.
@func: The C closure callback of the handlers (useless for non-C closures).
@data: The closure data of the handlers' closures.
@Returns: The amount of handlers that got unblocked.
<!-- ##### FUNCTION g_signal_handlers_disconnect_matched ##### -->
<para>
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.
</para>
@instance:
@mask:
@signal_id:
@detail:
@closure:
@func:
@data:
@Returns:
@instance: The instance to remove handlers from.
@mask: Mask indicating which of @signal_id, @detail, @closure, @func
and/or @data the handlers have to match.
@signal_id: Signal the handlers have to be connected to.
@detail: Signal detail the handlers have to be connected to.
@closure: The closure the handlers will invoke.
@func: The C closure callback of the handlers (useless for non-C closures).
@data: The closure data of the handlers' closures.
@Returns: The amount of handlers that got disconnected.
<!-- ##### FUNCTION g_signal_handler_is_connected ##### -->
<para>
Returns whether @handler_id is the id of a handler connected to @instance.
</para>
@instance:
@handler_id:
@Returns:
@instance: The instance where a signal handler is sought.
@handler_id: the handler id.
@Returns: whether @handler_id identifies a handler connected to @instance.
<!-- ##### MACRO g_signal_handlers_block_by_func ##### -->
@@ -598,97 +746,126 @@ Disconnects all handlers on an instance that match @func and @data.
<!-- ##### FUNCTION g_signal_has_handler_pending ##### -->
<para>
Returns whether there are any handlers connected to @instance for the
given signal id and detail.
</para>
<para>
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.
</para>
@instance:
@signal_id:
@detail:
@may_be_blocked:
@Returns:
@instance: the object whose signal handlers are sought.
@signal_id: the signal id.
@detail: the detail.
@may_be_blocked: whether blocked handlers should count as match.
@Returns: %TRUE if a handler is connected to the signal,
%FALSE otherwise.
<!-- ##### FUNCTION g_signal_stop_emission ##### -->
<para>
Stops a signal's current emission.
</para>
<para>
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).
</para>
<para>
Prints a warning if used on a signal which isn't being emitted.
</para>
@instance:
@signal_id:
@detail:
@instance: the object whose signal handlers you wish to stop.
@signal_id: the signal identifier, as returned by g_signal_lookup().
@detail: the detail which the signal was emitted with.
<!-- ##### FUNCTION g_signal_stop_emission_by_name ##### -->
<para>
Stops a signal's current emission.
</para>
<para>
This is just like g_signal_stop_emission() except it will look up the
signal id for you.
</para>
@instance:
@detailed_signal:
@instance: the object whose signal handlers you wish to stop.
@detailed_signal: a string of the form "signal-name::detail".
<!-- ##### FUNCTION g_signal_override_class_closure ##### -->
<para>
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.
</para>
@signal_id:
@instance_type:
@class_closure:
@signal_id: the signal id
@instance_type: the instance type on which to override the class closure
for the signal.
@class_closure: the closure.
<!-- ##### FUNCTION g_signal_chain_from_overridden ##### -->
<para>
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().
</para>
@instance_and_params:
@return_value:
@instance_and_params: the argument list of the signal emission. The first
element in the array is a #GValue for the instance the signal is being
emitted on. The rest are any arguments to be passed to the signal.
@return_value: Location for the return value.
<!-- ##### FUNCTION g_signal_add_emission_hook ##### -->
<para>
Adds an emission hook for a signal, which will get called for any emission
of that signal, independent of the instance.
</para>
@signal_id:
@detail:
@hook_func:
@hook_data:
@data_destroy:
@Returns:
<!-- # Unused Parameters # -->
@quark:
@signal_id: the signal identifier, as returned by g_signal_lookup().
@detail: the detail on which to call the hook.
@hook_func: a #GSignalEmissionHook function.
@hook_data: user data for @hook_func.
@data_destroy: a #GDestroyNotify for @hook_data.
@Returns: the hook id, for later use with g_signal_remove_emission_hook().
<!-- ##### FUNCTION g_signal_remove_emission_hook ##### -->
<para>
Deletes an emission hook.
</para>
@signal_id:
@hook_id:
@signal_id: the id of the signal
@hook_id: the id of the emission hook, as returned by
g_signal_add_emission_hook()
<!-- ##### FUNCTION g_signal_parse_name ##### -->
<para>
Internal function to parse a signal name into its @signal_id
and @detail quark.
</para>
@detailed_signal:
@itype:
@signal_id_p:
@detail_p:
@force_detail_quark:
@Returns:
@detailed_signal: a string of the form "signal-name::detail".
@itype: The interface/instance type that introduced "signal-name".
@signal_id_p: Location to store the signal id.
@detail_p: Location to store the detail quark.
@force_detail_quark: %TRUE forces creation of a #GQuark for the detail.
@Returns: Whether the signal name could successfully be parsed and @signal_id_p and @detail_p contain valid return values.
<!-- ##### FUNCTION g_signal_get_invocation_hint ##### -->
<para>
Returns the invocation hint of the innermost signal emission of instance.
</para>
@instance:
@Returns:
@instance: the instance to query
@Returns: the invocation hint of the innermost signal emission.
<!-- ##### FUNCTION g_signal_type_cclosure_new ##### -->