diff options
| -rw-r--r-- | docs/reference/ChangeLog | 4 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/param_value_types.sgml | 225 | ||||
| -rw-r--r-- | gobject/ChangeLog | 8 | ||||
| -rw-r--r-- | gobject/gobject.c | 8 | ||||
| -rw-r--r-- | gobject/gparam.c | 22 | ||||
| -rw-r--r-- | gobject/gparamspecs.c | 228 | ||||
| -rw-r--r-- | gobject/gsignal.c | 2 |
7 files changed, 374 insertions, 123 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index addf2b2b0..940843164 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,5 +1,9 @@ 2002-12-15 Matthias Clasen <maclas@gmx.de> + * gobject/tmpl/param_value_types.sgml: Move some docs inline. + +2002-12-15 Matthias Clasen <maclas@gmx.de> + * glib/Makefile.am (IGNORE_HFILES): Add gprintfint.h and trio. 2002-12-13 Matthias Clasen <maclas@gmx.de> diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml index b8941c85f..1fea2ab59 100644 --- a/docs/reference/gobject/tmpl/param_value_types.sgml +++ b/docs/reference/gobject/tmpl/param_value_types.sgml @@ -60,15 +60,14 @@ A #GParamSpec derived structure that contains the meta data for boolean properti <!-- ##### FUNCTION g_param_spec_boolean ##### --> <para> -Create a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN property. </para> -@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 +@name: +@nick: +@blurb: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_boolean ##### --> @@ -132,17 +131,16 @@ A #GParamSpec derived structure that contains the meta data for character proper <!-- ##### FUNCTION g_param_spec_char ##### --> <para> -Create a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_char ##### --> @@ -206,17 +204,16 @@ A #GParamSpec derived structure that contains the meta data for unsigned charact <!-- ##### FUNCTION g_param_spec_uchar ##### --> <para> -Create a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_uchar ##### --> @@ -280,17 +277,16 @@ A #GParamSpec derived structure that contains the meta data for integer properti <!-- ##### FUNCTION g_param_spec_int ##### --> <para> -Create a new #GParamSpecInt instance specifying a %G_TYPE_INT property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_int ##### --> @@ -354,17 +350,16 @@ A #GParamSpec derived structure that contains the meta data for unsigned integer <!-- ##### FUNCTION g_param_spec_uint ##### --> <para> -Create a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_uint ##### --> @@ -428,17 +423,16 @@ A #GParamSpec derived structure that contains the meta data for long integer pro <!-- ##### FUNCTION g_param_spec_long ##### --> <para> -Create a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_long ##### --> @@ -505,14 +499,14 @@ A #GParamSpec derived structure that contains the meta data for unsigned long in Create a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_ulong ##### --> @@ -576,17 +570,16 @@ A #GParamSpec derived structure that contains the meta data for 64bit integer pr <!-- ##### FUNCTION g_param_spec_int64 ##### --> <para> -Create a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_int64 ##### --> @@ -650,17 +643,16 @@ A #GParamSpec derived structure that contains the meta data for unsigned 64bit i <!-- ##### FUNCTION g_param_spec_uint64 ##### --> <para> -Create a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_uint64 ##### --> @@ -725,17 +717,16 @@ A #GParamSpec derived structure that contains the meta data for float properties <!-- ##### FUNCTION g_param_spec_float ##### --> <para> -Create a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_float ##### --> @@ -800,17 +791,16 @@ A #GParamSpec derived structure that contains the meta data for double propertie <!-- ##### FUNCTION g_param_spec_double ##### --> <para> -Create a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE property. </para> -@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 +@name: +@nick: +@blurb: +@minimum: +@maximum: +@default_value: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_double ##### --> @@ -1210,15 +1200,14 @@ A #GParamSpec derived structure that contains the meta data for boxed properties <!-- ##### FUNCTION g_param_spec_boxed ##### --> <para> -Create a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED derived property. </para> -@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 +@name: +@nick: +@blurb: +@boxed_type: +@flags: +@Returns: <!-- ##### FUNCTION g_value_set_boxed ##### --> @@ -1458,17 +1447,14 @@ A #GParamSpec derived structure that contains the meta data for unichar (unsigne <!-- ##### FUNCTION g_param_spec_unichar ##### --> <para> -Create 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> -@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 +@name: +@nick: +@blurb: +@default_value: +@flags: +@Returns: <!-- ##### MACRO G_IS_PARAM_SPEC_VALUE_ARRAY ##### --> @@ -1505,16 +1491,13 @@ A #GParamSpec derived structure that contains the meta data for #GValueArray pro <!-- ##### FUNCTION g_param_spec_value_array ##### --> <para> -Create 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> -@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 +@name: +@nick: +@blurb: +@element_spec: +@flags: +@Returns: diff --git a/gobject/ChangeLog b/gobject/ChangeLog index a3aa8ad74..42f32b0df 100644 --- a/gobject/ChangeLog +++ b/gobject/ChangeLog @@ -1,3 +1,11 @@ +2002-12-15 Matthias Clasen <maclas@gmx.de> + + * gsignal.c (g_signal_new): Typo fix. + + * gparamspecs.c: + * gparam.c (g_param_spec_internal): + * gobject.c (g_object_class_install_property): Add docs. + 2002-12-13 Matthias Clasen <maclas@gmx.de> * glib-genmarshal.c, gobject-query.c: Use g_printf() instead of diff --git a/gobject/gobject.c b/gobject/gobject.c index 0db5ec7a1..63076645f 100644 --- a/gobject/gobject.c +++ b/gobject/gobject.c @@ -258,6 +258,14 @@ g_object_do_class_init (GObjectClass *class) 1, G_TYPE_PARAM); } +/** + * g_object_class_install_property: + * @class: a #GObjectClass + * @property_id: the id for the new property + * @pspec: the #GParamSpec for the new property + * + * Installs a new property. This is usually done in the class initializer. + **/ void g_object_class_install_property (GObjectClass *class, guint property_id, diff --git a/gobject/gparam.c b/gobject/gparam.c index 0d4a1b3e0..10c7d9398 100644 --- a/gobject/gparam.c +++ b/gobject/gparam.c @@ -274,6 +274,28 @@ canonicalize_key (gchar *key) } } +/** + * g_param_spec_internal: + * @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 + * + * 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<!-- -->s, either separator can + * be used, but they cannot be mixed. Using '-' is considerably more efficient + * and in fact <emphasis>required</emphasis> when using property names as + * detail strings for signals. + * + * Return value: a newly allocated #GParamSpec instance + **/ gpointer g_param_spec_internal (GType param_type, const gchar *name, diff --git a/gobject/gparamspecs.c b/gobject/gparamspecs.c index b4504bbc8..c9bdd8320 100644 --- a/gobject/gparamspecs.c +++ b/gobject/gparamspecs.c @@ -1344,8 +1344,24 @@ g_param_spec_types_init (void) /* sync with gtype.c */ g_assert (spec_types == spec_types_bound); } - /* --- GParamSpec initialization --- */ + +/** + * g_param_spec_char: + * @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 + * + * Creates a new #GParamSpecChar instance specifying a %G_TYPE_CHAR property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_char (const gchar *name, const gchar *nick, @@ -1372,6 +1388,22 @@ g_param_spec_char (const gchar *name, return G_PARAM_SPEC (cspec); } +/** + * g_param_spec_uchar: + * @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 + * + * Creates a new #GParamSpecUChar instance specifying a %G_TYPE_UCHAR property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_uchar (const gchar *name, const gchar *nick, @@ -1398,6 +1430,21 @@ g_param_spec_uchar (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_boolean: + * @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 + * + * Creates a new #GParamSpecBoolean instance specifying a %G_TYPE_BOOLEAN + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_boolean (const gchar *name, const gchar *nick, @@ -1420,6 +1467,22 @@ g_param_spec_boolean (const gchar *name, return G_PARAM_SPEC (bspec); } +/** + * g_param_spec_int: + * @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 + * + * Creates a new #GParamSpecInt instance specifying a %G_TYPE_INT property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_int (const gchar *name, const gchar *nick, @@ -1446,6 +1509,22 @@ g_param_spec_int (const gchar *name, return G_PARAM_SPEC (ispec); } +/** + * g_param_spec_uint: + * @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 + * + * Creates a new #GParamSpecUInt instance specifying a %G_TYPE_UINT property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_uint (const gchar *name, const gchar *nick, @@ -1472,6 +1551,22 @@ g_param_spec_uint (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_long: + * @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 + * + * Creates a new #GParamSpecLong instance specifying a %G_TYPE_LONG property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_long (const gchar *name, const gchar *nick, @@ -1498,6 +1593,22 @@ g_param_spec_long (const gchar *name, return G_PARAM_SPEC (lspec); } +/** + * g_param_spec_ulong: + * @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 + * + * Creates a new #GParamSpecULong instance specifying a %G_TYPE_ULONG property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_ulong (const gchar *name, const gchar *nick, @@ -1524,6 +1635,22 @@ g_param_spec_ulong (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_int64: + * @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 + * + * Creates a new #GParamSpecInt64 instance specifying a %G_TYPE_INT64 property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_int64 (const gchar *name, const gchar *nick, @@ -1550,6 +1677,23 @@ g_param_spec_int64 (const gchar *name, return G_PARAM_SPEC (lspec); } +/** + * g_param_spec_uint64: + * @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 + * + * Creates a new #GParamSpecUInt64 instance specifying a %G_TYPE_UINT64 + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_uint64 (const gchar *name, const gchar *nick, @@ -1576,6 +1720,22 @@ g_param_spec_uint64 (const gchar *name, return G_PARAM_SPEC (uspec); } +/** + * g_param_spec_unichar: + * @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 + * + * 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. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_unichar (const gchar *name, const gchar *nick, @@ -1656,6 +1816,22 @@ g_param_spec_flags (const gchar *name, return G_PARAM_SPEC (fspec); } +/** + * g_param_spec_float: + * @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 + * + * Creates a new #GParamSpecFloat instance specifying a %G_TYPE_FLOAT property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_float (const gchar *name, const gchar *nick, @@ -1682,6 +1858,23 @@ g_param_spec_float (const gchar *name, return G_PARAM_SPEC (fspec); } +/** + * g_param_spec_double: + * @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 + * + * Creates a new #GParamSpecDouble instance specifying a %G_TYPE_DOUBLE + * property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_double (const gchar *name, const gchar *nick, @@ -1747,6 +1940,21 @@ g_param_spec_param (const gchar *name, return G_PARAM_SPEC (pspec); } +/** + * g_param_spec_boxed: + * @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 + * + * Creates a new #GParamSpecBoxed instance specifying a %G_TYPE_BOXED + * derived property. + * + * See g_param_spec_internal() for details on property names. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_boxed (const gchar *name, const gchar *nick, @@ -1785,6 +1993,24 @@ g_param_spec_pointer (const gchar *name, return G_PARAM_SPEC (pspec); } +/** + * g_param_spec_value_array: + * @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 + * + * 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. + * + * Return value: a newly created parameter specification + **/ GParamSpec* g_param_spec_value_array (const gchar *name, const gchar *nick, diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 8bdcdae61..694f05902 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -1231,7 +1231,7 @@ g_signal_query (guint signal_id, * * A signal name consists of segments consisting of ASCII letters and * digits, separated by either the '-' or '_' character. The first - * character of a signal names must be a letter. Names which violate these + * 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 |