Document interface properties and GParamSpecOverride.

Tue Oct 14 17:45:33 2003  Owen Taylor  <otaylor@redhat.com>

        * gobject/gobject-sections.txt gobject/tmpl/objects.sgml
        gobject/tmpl/param_value_types.sgml gobject/tmpl/gparamspec.sgml:
        Document interface properties and GParamSpecOverride.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 6354975..8b46025 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,9 @@
+Tue Oct 14 17:45:33 2003  Owen Taylor  <otaylor@redhat.com>
+
+       * gobject/gobject-sections.txt gobject/tmpl/objects.sgml
+       gobject/tmpl/param_value_types.sgml gobject/tmpl/gparamspec.sgml:
+       Document interface properties and GParamSpecOverride.
+
 Mon Oct 20 22:05:37 2003  Matthias Clasen  <maclas@gmx.de>
 
        * gobject/tmpl/objects.sgml: 

diff --git a/docs/reference/glib/tmpl/unicode.sgml b/docs/reference/glib/tmpl/unicode.sgml
index 5e0fa3f..1f197dd 100644 (file)
--- a/docs/reference/glib/tmpl/unicode.sgml
+++ b/docs/reference/glib/tmpl/unicode.sgml
@@ -335,6 +335,16 @@ See <ulink url="http://www.unicode.org/unicode/reports/tr14/"
 @Returns: 
 
 
+<!-- ##### FUNCTION g_unichar_get_mirror_char ##### -->
+<para>
+
+</para>
+
+@ch: 
+@mirrored_ch: 
+@Returns: 
+
+
 <!-- ##### MACRO g_utf8_next_char ##### -->
 <para>
 Skips to the next character in a UTF-8 string. The string must be

diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt
index c85c8db..e3d5d32 100644 (file)
--- a/docs/reference/gobject/gobject-sections.txt
+++ b/docs/reference/gobject/gobject-sections.txt
@@ -209,6 +209,10 @@ G_OBJECT_CLASS_NAME
 g_object_class_install_property
 g_object_class_find_property
 g_object_class_list_properties
+g_object_class_override_property
+g_object_interface_install_property
+g_object_interface_find_property
+g_object_interface_list_properties
 g_object_new
 g_object_newv
 GParameter
@@ -375,6 +379,7 @@ g_param_spec_get_qdata
 g_param_spec_set_qdata
 g_param_spec_set_qdata_full
 g_param_spec_steal_qdata
+g_param_spec_get_redirect_target
 g_param_spec_internal
 GParamSpecTypeInfo
 g_param_type_register_static
@@ -600,6 +605,13 @@ G_TYPE_PARAM_VALUE_ARRAY
 GParamSpecValueArray
 g_param_spec_value_array
 
+<SUBSECTION Override>
+G_IS_PARAM_SPEC_OVERRIDE
+G_PARAM_SPEC_OVERRIDE
+G_TYPE_PARAM_OVERRIDE
+GParamSpecOverride
+g_param_spec_override
+
 <SUBSECTION Private>
 g_value_set_instance
 g_param_spec_types

diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml
index a728696..52698e6 100644 (file)
--- a/docs/reference/gobject/tmpl/gparamspec.sgml
+++ b/docs/reference/gobject/tmpl/gparamspec.sgml
@@ -330,6 +330,22 @@ user data pointers with a destroy notifier.
 @Returns: the user data pointer set, or %NULL
 
 
+<!-- ##### FUNCTION g_param_spec_get_redirect_target ##### -->
+<para>
+If the paramspec redirects operations to another paramspec,
+returns that paramspec. Redirect is used typically for
+providing a new implementation of a property in a derived
+type while perserving all the properties from the parent
+type. Redirection is established by creating a property
+of type #GParamSpecOverride. See g_object_override_property()
+for an example of the use of this capability.
+</para>
+
+@pspec: a #GParamSpec
+@Returns: paramspec to which requests on this paramspec should
+  be redirected, or %NULL if none.
+
+
 <!-- ##### FUNCTION g_param_spec_internal ##### -->
 <para>
 Creates a new #GParamSpec instance.

diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml
index fccb76a..c302e29 100644 (file)
--- a/docs/reference/gobject/tmpl/objects.sgml
+++ b/docs/reference/gobject/tmpl/objects.sgml
@@ -210,6 +210,92 @@ Returns an array of #GParamSpec* for all properties of a class.
 @Returns: an array of #GParamSpec* which should be freed after use
 
 
+<!-- ##### FUNCTION g_object_class_override_property ##### -->
+<para>
+Registers @property_id as referring to a property with the
+name @name in a parent class or in an interface implemented
+by @oclass. This allows this class to <firstterm>override</firstterm>
+a property implementation in a parent class or to provide
+the implementation of a property from an interface.
+</para>
+<note>
+<para>
+Internally, overriding is implemented by creating a property of type
+#GParamSpecOverride; generally operations that query the properties of
+the object class, such as g_object_class_find_property() or
+g_object_class_list_properties() will return the overridden
+property. However, in one case, the @construct_properties argument of
+the @constructor virtual function, the #GParamSpecOverride is passed
+instead, so that the @param_id field of the #GParamSpec will be
+correct.  For virtually all uses, this makes no difference. If you
+need to get the overridden property, you can call
+g_param_spec_get_redirect_target().
+</para>
+</note>
+
+@oclass: a #GObjectClass
+@property_id: the new property ID
+@name: the name of a property registered in a parent class or
+       in an interface of this class.
+
+
+<!-- ##### FUNCTION g_object_interface_install_property ##### -->
+<para>
+Add a property to an interface; this is only useful for interfaces
+that are added to GObject-derived types. Adding a property to an
+interface forces all objects classes with that interface to have a
+compatible property. The compatible property could be a newly
+created #GParamSpec, but normally
+g_object_class_override_property() will be used so that the object
+class only needs to provide an implementation and inherits the
+property description, default value, bounds, and so forth from the
+interface property.
+</para>
+<para>
+This function is meant to be called from the interface's default
+vtable initialization function (the @class_init member of
+#GTypeInfo.) It must not be called after after @class_init has
+been called for any object types implementing this interface.
+</para>
+
+@g_iface: any interface vtable for the interface, or the default
+ vtable for the interface.
+@pspec: the #GParamSpec for the new property
+
+
+<!-- ##### FUNCTION g_object_interface_find_property ##### -->
+<para>
+Find the #GParamSpec with the given name for an
+interface. Generally, the interface vtable passed in as @g_iface
+will be the default vtable from g_type_default_interface_ref(), or,
+if you know the interface has already been loaded,
+g_type_default_interface_peek().
+</para>
+
+@g_iface: any interface vtable for the interface, or the default
+  vtable for the interface
+@property_name: name of a property to lookup.
+@Returns: the #GParamSpec for the property of the
+  interface with the name @property_name, or %NULL
+  if no such property exists.
+
+
+<!-- ##### FUNCTION g_object_interface_list_properties ##### -->
+<para>
+Lists the properties of an interface.Generally, the interface
+vtable passed in as @g_iface will be the default vtable from
+g_type_default_interface_ref(), or, if you know the interface has
+already been loaded, g_type_default_interface_peek().
+</para>
+
+@g_iface: any interface vtable for the interface, or the default
+ vtable for the interface
+@n_properties_p: location to store number of properties returned.
+@Returns: a pointer to an array of pointers to #GParamSpec structures.
+  The paramspecs are owned by GLib, but the array should
+  be freed with g_free() when you are done with it.
+
+
 <!-- ##### FUNCTION g_object_new ##### -->
 <para>
 Creates a new instance of a #GObject subtype and sets its properties.

diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml
index 59613b9..0c1ae3b 100644 (file)
--- a/docs/reference/gobject/tmpl/param_value_types.sgml
+++ b/docs/reference/gobject/tmpl/param_value_types.sgml
@@ -1640,3 +1640,51 @@ See g_param_spec_internal() for details on property names.
 @Returns: a newly created parameter specification
 
 
+<!-- ##### MACRO G_IS_PARAM_SPEC_OVERRIDE ##### -->
+<para>
+Returns whether the given #GParamSpec is of type %G_TYPE_PARAM_OBJECT.
+</para>
+
+@pspec: a #GParamSpec
+
+
+<!-- ##### MACRO G_PARAM_SPEC_OVERRIDE ##### -->
+<para>
+Casts a #GParamSpec into a #GParamSpecObject.
+</para>
+
+@pspec:  a #GParamSpec
+
+
+<!-- ##### MACRO G_TYPE_PARAM_OVERRIDE ##### -->
+<para>
+The #GType of #GParamSpecOverride.
+</para>
+
+
+
+<!-- ##### STRUCT GParamSpecOverride ##### -->
+<para>
+This is a type of #GParamSpec type that simply redirects operations to
+another paramspec.  All operations other than getting or
+setting the value are redirected, including accessing the nick and
+blurb, validating a value, and so forth. See
+g_param_spec_get_redirect_target() for retrieving the overidden
+property. #GParamSpecOverride is used in implementing
+g_object_class_override_property(), and will not be directly useful
+unless you are implementing a new base type similar to GObject.
+</para>
+
+
+<!-- ##### FUNCTION g_param_spec_override ##### -->
+<para>
+Creates a new property of type #GParamSpecOverride. This is used
+to direct operations to another paramspec, and will not be directly
+useful unless you are implementing a new base type similar to GObject.
+</para>
+
+@name: the name of the property.
+@overridden: The property that is being overridden
+@Returns: the newly created #GParamSpec
+
+