+2006-12-17 Matthias Clasen <mclasen@redhat.com>
+
+ * gobject/tmpl/objects.sgml: Expand GObject::notify
+ documentation. (#381722, Nickolay V. Shmyrev)
+
+ * gobject/tmpl/gparamspec.sgml: Add canonical-parameter-name id.
+
2006-12-15 Matthias Clasen <mclasen@redhat.com>
* glib/glib-docs.sgml: Add a "Since 2.14" section.
#GParamSpec is an object structure that encapsulates the metadata
required to specify parameters, such as e.g. #GObject properties.
</para>
-<para>
+<para id="canonical-parameter-name">
Parameter names need to start with a letter (a-z or A-Z). Subsequent
characters can be letters, numbers or a '-'.
All other characters are replaced by a '-' during construction.
+The result of this replacement is called the canonical name of the
+parameter.
</para>
<!-- ##### SECTION See_Also ##### -->
value of the property has actually changed, it may also be emitted when
the setter for the property is called to reinstate the previous value.
</para>
+<para>
+This signal is typically used to obtain change notification for a
+single property, by specifying the property name as a detail in the
+g_signal_connect() call, like this:
+<informalexample><programlisting>
+g_signal_connect (text_view->buffer, "notify::paste-target-list",
+ G_CALLBACK (gtk_text_view_target_list_notify),
+ text_view)
+</programlisting></informalexample>
+It is important to note that you must use
+<link linkend="canonical-parameter-name">canonical</link> parameter names as
+detail strings for the notify signal.
+</para>
@pspec: the #GParamSpec of the property which changed
@gobject: the object which received the signal.