From: Matthias Clasen Date: Fri, 7 Feb 2003 22:08:53 +0000 (+0000) Subject: Move all docs out-of-line. Boy, what a waste of time. X-Git-Tag: GLIB_2_3_0~260 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=280a213b09c3c91f5c20797d483a90552d603014;p=platform%2Fupstream%2Fglib.git Move all docs out-of-line. Boy, what a waste of time. 2003-02-07 Matthias Clasen * 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. --- diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 73d3856..300c0f3 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,14 @@ +2003-02-07 Matthias Clasen + + * 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 * glib/tmpl/strings.sgml: Document the return value of g_string_free(). diff --git a/docs/reference/gobject/tmpl/gclosure.sgml b/docs/reference/gobject/tmpl/gclosure.sgml index 97210ac..9f52377 100644 --- a/docs/reference/gobject/tmpl/gclosure.sgml +++ b/docs/reference/gobject/tmpl/gclosure.sgml @@ -319,11 +319,16 @@ atfer this function, unles g_closure_ref() was called beforehand. - +Set the callback for a source as a #GClosure. + + +If the source is not one of the standard GLib types, the @closure_callback +and @closure_marshal fields of the GSourceFuncs structure must have been +filled in with pointers to appropriate functions. -@source: -@closure: +@source: the source +@closure: a #GClosure diff --git a/docs/reference/gobject/tmpl/gobject-unused.sgml b/docs/reference/gobject/tmpl/gobject-unused.sgml index aa57654..ec1cdb1 100644 --- a/docs/reference/gobject/tmpl/gobject-unused.sgml +++ b/docs/reference/gobject/tmpl/gobject-unused.sgml @@ -196,6 +196,13 @@ Shift value used in converting numbers to type IDs. @closure: @Returns: + + + + + +@instance: + diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml index e03618a..1490fc0 100644 --- a/docs/reference/gobject/tmpl/gparamspec.sgml +++ b/docs/reference/gobject/tmpl/gparamspec.sgml @@ -311,15 +311,26 @@ if @value1 is found to be less than, equal to or greater than @value2, respectiv - +Creates a new #GParamSpec instance. + + +A property name consists of segments consisting of ASCII letters and +digits, separated by either the '-' or '_' character. The first +character of a property name must be a letter. Names which violate these +rules lead to undefined behaviour. + + +When creating and looking up a #GParamSpec, either separator can be used, +but they cannot be mixed. Using '-' is considerably more efficient and in +fact required when using property names as detail strings for signals. -@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 diff --git a/docs/reference/gobject/tmpl/gtype.sgml b/docs/reference/gobject/tmpl/gtype.sgml index 9b76330..2304a66 100644 --- a/docs/reference/gobject/tmpl/gtype.sgml +++ b/docs/reference/gobject/tmpl/gtype.sgml @@ -707,11 +707,16 @@ class conforms. - +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. -@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. @@ -739,40 +744,50 @@ g_free()ed after use. - +Returns the prerequisites of an interfaces type. -@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 + +@Since: 2.2 - +Attaches arbitrary data to a type. -@type: -@quark: -@data: +@type: a #GType +@quark: a #GQuark id to identify the data +@data: the data - +Obtains data which has previously been attached to @type +with g_type_set_qdata(). -@type: -@quark: -@Returns: +@type: a #GType +@quark: a #GQuark id to identify the data +@Returns: the data, or %NULL if no data was found +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. -@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. @@ -1068,20 +1083,27 @@ is used to manage the relationship. +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. -@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. - +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. -@interface_type: -@prerequisite_type: +@interface_type: #GType value of an interface type. +@prerequisite_type: #GType value of an interface or instantiatable type. @@ -1097,11 +1119,16 @@ Returns the #GTypePlugin structure for @type or +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(). -@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. diff --git a/docs/reference/gobject/tmpl/gtypemodule.sgml b/docs/reference/gobject/tmpl/gtypemodule.sgml index b098b9d..cdc021e 100644 --- a/docs/reference/gobject/tmpl/gtypemodule.sgml +++ b/docs/reference/gobject/tmpl/gtypemodule.sgml @@ -71,51 +71,70 @@ in #GTypeModuleClass. - +Increases the use count of a #GTypeModule by one. If the +use count was zero before, the plugin will be loaded. -@module: -@Returns: +@module: a #GTypeModule +@Returns: %FALSE if the plugin needed to be loaded and + loading the plugin failed. - +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.) -@module: +@module: a #GTypeModule - +Sets the name for a #GTypeModule -@module: -@name: +@module: a #GTypeModule. +@name: a human-readable name to use in error messages. - +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. + + +As long as any instances of the type exist, the type plugin will +not be unloaded. -@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. - +Registers an additional interface for a type, whose interface +lives in the given type plugin. If the interface was already registered +for the type in this plugin, nothing will be done. + + +As long as any instances of the type exist, the type plugin will +not be unloaded. -@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 diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml index 246d2ab..870d464 100644 --- a/docs/reference/gobject/tmpl/objects.sgml +++ b/docs/reference/gobject/tmpl/objects.sgml @@ -16,8 +16,8 @@ The base object type -All the fields in the GObject structure are private to the #GObject implementation -and should never be accessed directly. +All the fields in the GObject structure are private +to the #GObject implementation and should never be accessed directly. @g_type_instance: @@ -37,8 +37,6 @@ and should never be accessed directly. @property_id: @value: @pspec: - -@trailer: @@ -50,8 +48,6 @@ and should never be accessed directly. @property_id: @value: @pspec: - -@trailer: @@ -64,7 +60,7 @@ and should never be accessed directly. -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. @@ -74,7 +70,7 @@ the passed in type id is a %G_TYPE_OBJECT or derived from it. -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. @@ -84,7 +80,7 @@ certain runtime checks to identify invalid casts. -Check whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. +Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT. @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. - +Casts a derived #GObjectClass structure into a #GObjectClass structure. -@class: +@class: a valid #GObjectClass - +Checks whether @class "is a" valid #GObjectClass structure of type +%G_TYPE_OBJECT or derived. -@class: +@class: a #GObjectClass - +Returns the class structure associated to a #GObject instance. -@object: +@object: a #GObject instance. @@ -125,10 +122,12 @@ Return the type id of an object. - +Returns the name of an object's type. -@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. @@ -149,10 +148,14 @@ Return the type id of an object. - +Installs a new property. This is usually done in the class initializer. @oclass: +@property_id: the id for the new property +@pspec: the #GParamSpec for the new property + +@class: a #GObjectClass @property_id: @pspec: @@ -325,27 +328,29 @@ to match the one used with g_object_add_weak_pointer(). - +Emits a "notify" signal for the property @property_name on @object. -@object: -@property_name: +@object: a #GObject +@property_name: the name of a property installed on the class of @object. - +Stops emission of "notify" signals on @object. The signals are +queued until g_object_thaw_notify() is called on @object. -@object: +@object: a #GObject - +Reverts the effect of a previous call to g_object_freeze_notify(). +This causes all queued "notify" signals on @object to be emitted. -@object: +@object: a #GObject diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml index b8fb0dc..3cbb303 100644 --- a/docs/reference/gobject/tmpl/param_value_types.sgml +++ b/docs/reference/gobject/tmpl/param_value_types.sgml @@ -60,14 +60,19 @@ A #GParamSpec derived structure that contains the meta data for boolean properti +Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN +property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -131,16 +136,17 @@ A #GParamSpec derived structure that contains the meta data for character proper +Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. -@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 @@ -204,16 +210,17 @@ A #GParamSpec derived structure that contains the meta data for unsigned charact +Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. -@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 @@ -277,16 +284,20 @@ A #GParamSpec derived structure that contains the meta data for integer properti +Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -350,16 +361,20 @@ A #GParamSpec derived structure that contains the meta data for unsigned integer +Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -423,16 +438,20 @@ A #GParamSpec derived structure that contains the meta data for long integer pro +Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -496,17 +515,20 @@ A #GParamSpec derived structure that contains the meta data for unsigned long in -Create a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. +Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -570,16 +592,20 @@ A #GParamSpec derived structure that contains the meta data for 64bit integer pr +Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -643,16 +669,21 @@ A #GParamSpec derived structure that contains the meta data for unsigned 64bit i +Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 +property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -717,16 +748,20 @@ A #GParamSpec derived structure that contains the meta data for float properties +Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -791,16 +826,21 @@ A #GParamSpec derived structure that contains the meta data for double propertie +Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE +property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -1200,14 +1240,19 @@ A #GParamSpec derived structure that contains the meta data for boxed properties +Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED +derived property. + + +See g_param_spec_internal() for details on property names. -@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 @@ -1447,14 +1492,20 @@ A #GParamSpec derived structure that contains the meta data for unichar (unsigne +Creates a new #GParamSpecUnichar instance specifying a %G_TYPE_UINT +property. #GValue structures for this property can be accessed with +g_value_set_uint() and g_value_get_uint(). + + +See g_param_spec_internal() for details on property names. -@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 @@ -1491,13 +1542,21 @@ A #GParamSpec derived structure that contains the meta data for #GValueArray pro +Creates a new #GParamSpecValueArray instance specifying a +%G_TYPE_VALUE_ARRAY property. %G_TYPE_VALUE_ARRAY is a %G_TYPE_BOXED +type, as such, #GValue structures for this property can be accessed +with g_value_set_boxed() and g_value_get_boxed(). + + +See g_param_spec_internal() for details on property names. -@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 diff --git a/docs/reference/gobject/tmpl/signals.sgml b/docs/reference/gobject/tmpl/signals.sgml index cc6dc6c..7ede610 100644 --- a/docs/reference/gobject/tmpl/signals.sgml +++ b/docs/reference/gobject/tmpl/signals.sgml @@ -233,135 +233,213 @@ of g_signal_new(). - +Creates a new signal. (This is usually done in the class initializer.) + + +A signal name consists of segments consisting of ASCII letters and +digits, separated by either the '-' or '_' character. The first +character of a signal name must be a letter. Names which violate these +rules lead to undefined behaviour of the GSignal system. + + +When registering a signal and looking up a signal, either separator can +be used, but they cannot be mixed. -@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 - +Creates a new signal. (This is usually done in the class initializer.) + + +See g_signal_new() for details on allowed signal names. -@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 - +Creates a new signal. (This is usually done in the class initializer.) + + +See g_signal_new() for details on allowed signal names. -@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 +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. -@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. - +Given the name of the signal and the type of object it connects to, gets +the signal's identifying integer. Emitting the signal by number is +somewhat faster than using the name each time. + + +Also tries the ancestors of the given type. + + +See g_signal_new() for details on allowed signal names. -@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. - +Given the signal's identifier, finds its name. + + +Two different signals may have the same name, if they have differing types. -@signal_id: -@Returns: +@signal_id: the signal's identifying number. +@Returns: the signal name, or %NULL if the signal number was invalid. +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(). -@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. - +Emits a signal. + + +Note that g_signal_emit() resets the return value to the default +if no handlers are connected, in contrast to g_signal_emitv(). -@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. - +Emits a signal. + + +Note that g_signal_emit_by_name() resets the return value to the default +if no handlers are connected, in contrast to g_signal_emitv(). -@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. - +Emits a signal. + + +Note that g_signal_emitv() doesn't change @return_value if no handlers are +connected, in contrast to g_signal_emit() and g_signal_emit_valist(). -@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. - +Emits a signal. + + +Note that g_signal_emit_valist() resets the return value to the default +if no handlers are connected, in contrast to g_signal_emitv(). -@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. @@ -412,15 +490,22 @@ calling the handler. - + * 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. + * @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. @@ -436,131 +521,194 @@ connection. - +Connects a #GCallback function to a signal for a particular object. -@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 - +Connects a closure to a signal for a particular object. -@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 - +Connects a closure to a signal for a particular object. -@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 +Blocks a handler of an instance so it will not be called during +any signal emissions unless it is unblocked again. Thus "blocking" +a signal handler means to temporarily deactive it, a signal handler +has to be unblocked exactly the same amount of times it has been +blocked before to become active again. + + +The @handler_id has to be a valid signal handler id, connected to a +signal of @instance. -@instance: -@handler_id: +@instance: The instance to block the signal handler of. +@handler_id: Handler id of the handler to be blocked. +Undoes the effect of a previous g_signal_handler_block() call. +A blocked handler is skipped during signal emissions and will not be +invoked, unblocking it (for exactly the amount of times it has been +blocked before) reverts its "blocked" state, so the handler will be +recognized by the signal system and is called upon future or currently +ongoing signal emissions (since the order in which handlers are +called during signal emissions is deterministic, whether the +unblocked handler in question is called as part of a currently +ongoing emission depends on how far that emission has proceeded +yet). + + +The @handler_id has to be a valid id of a signal handler that is +connected to a signal of @instance and is currently blocked. -@instance: -@handler_id: +@instance: The instance to unblock the signal handler of. +@handler_id: Handler id of the handler to be unblocked. +Disconnects a handler from an instance so it will not be called during +any future or currently ongoing emissions of the signal it has been +connected to. The @handler_id becomes invalid and may be reused. + + +The @handler_id has to be a valid signal handler id, connected to a +signal of @instance. -@instance: -@handler_id: +@instance: The instance to remove the signal handler from. +@handler_id: Handler id of the handler to be disconnected. +Finds the first signal handler that matches certain selection criteria. +The criteria mask is passed as an OR-ed combination of #GSignalMatchType +flags, and the criteria values are passed as arguments. +The match @mask has to be non-0 for successful matches. +If no handler was found, 0 is returned. -@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. +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. -@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. +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. -@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. +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. -@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. - +Returns whether @handler_id is the id of a handler connected to @instance. -@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. @@ -598,97 +746,126 @@ Disconnects all handlers on an instance that match @func and @data. - +Returns whether there are any handlers connected to @instance for the +given signal id and detail. + + +One example of when you might use this is when the arguments to the +signal are difficult to compute. A class implementor may opt to not emit +the signal if no one is attached anyway, thus saving the cost of building +the arguments. -@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. - +Stops a signal's current emission. + + +This will prevent the default method from running, if the signal was +%G_SIGNAL_RUN_LAST and you connected normally (i.e. without the "after" +flag). + + +Prints a warning if used on a signal which isn't being emitted. -@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. - +Stops a signal's current emission. + + +This is just like g_signal_stop_emission() except it will look up the +signal id for you. -@instance: -@detailed_signal: +@instance: the object whose signal handlers you wish to stop. +@detailed_signal: a string of the form "signal-name::detail". - +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. -@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. - +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(). -@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. - +Adds an emission hook for a signal, which will get called for any emission +of that signal, independent of the instance. -@signal_id: -@detail: -@hook_func: -@hook_data: -@data_destroy: -@Returns: - -@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(). - +Deletes an emission hook. -@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() +Internal function to parse a signal name into its @signal_id +and @detail quark. -@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. - +Returns the invocation hint of the innermost signal emission of instance. -@instance: -@Returns: +@instance: the instance to query +@Returns: the invocation hint of the innermost signal emission.