Re: buildable vs plain objects

[Kevin Ryde <user42 zip com au>]

Torsten Schoenfeld <kaffeetisch gmx de> writes:
> built-in introspection mechanisms to construct the thing.

Ah yes, the g_module lookup thingie loading up classes out of the shared
libraries.  "It's not a security hole, it's a feature." :-)

> Implementing GtkBuildable is only necessary if you want to customize
> the construction, I think.

Perhaps the docs could be chopped, rather radically, to something like
below.

Perhaps synopsis bit could show how ADD_CHILD lets you do interesting
things with <child> sub-objects, or in some way emphasise the good
things Buildable can do or is needed for.



DESCRIPTION
       The Gtk2::Buildable interface allows objects and widgets to have
       "<child>" objects, special property settings, or extra custom tags in a
       Gtk2::Builder UI description
       (<http://library.gnome.org/devel/gtk/unstable/GtkBuilder.html#BUILDER-UI>).

       The main user of the Gtk2::Buildable interface is Gtk2::Builder, so
       there should be very little need for applications to call any of the
       Gtk2::Buildable methods.  So this documentation deals with implementing
       a buildable object.

       Gtk2::Builder already supports plain Glib::Object or Gtk2::Widget with
       "<object>" construction and and "<property>" settings, so often the
       "Gtk2::Buildable" interface is not needed.  The only thing to note is
       an object or widget implemented in Perl must be loaded before building.

OVERRIDING BUILDABLE INTERFACE METHODS
       The buildable interface can be added to a Perl code object or widget
       subclass by putting "Gtk2::Buildable" in the interfaces list and
       implementing the following methods.

       In current Gtk2-Perl the custom tags code doesn't chain up to any
       buildable interfaces in superclasses.  This means for instance if you
       implement Gtk2::Buildable on a new widget subclass then you lose the
       <accelerator> and <accessibility> tags normally available from
       Gtk2::Widget.  This will likely change in the future, probably by
       chaining up by default for unhandled tags, maybe with a way to ask
       deliberately not to chain.

       SET_NAME ($self, $name)
           ·   $name (string)
       ...



diff --git a/xs/GtkBuildable.xs b/xs/GtkBuildable.xs
index 416cd3b..17edf84 100644
--- a/xs/GtkBuildable.xs
+++ b/xs/GtkBuildable.xs
@@ -794,81 +794,29 @@ MODULE = Gtk2::Buildable PACKAGE = Gtk2::Buildable
 
 =head1 DESCRIPTION
 
-In order to allow construction from a Gtk2::Builder UI description
-(L<http://library.gnome.org/devel/gtk/unstable/GtkBuilder.html#BUILDER-UI>),
-an object must implement the Gtk2::Buildable interface.  The interface
-includes methods for setting names and properties of objects, parsing
-custom tags, and constructing child objects.
-
-The Gtk2::Buildable interface is implemented by all widgets and many
-of the non-widget objects that are provided by GTK+.  The main user of
-this interface is Gtk2::Builder, so there should be very little need for
-applications to call any of the Gtk2::Buildable methods.
-
-So, instead of focusing on how to call the methods of a Gtk2::Buildable,
-this documentation deals with implementing a buildable object.
-
-=head1 WIDGETS
-
-Since Gtk2::Widget implements the Gtk2::Buildable interface, all widgets
-get buildability gratis.  If your widget requires no special markup
-syntax to express its configuration, and all properties can be handled
-through the standard mechanisms, you can simply add the name of your
-perl-derived Glib::Object types to the C<object> tag in the builder UI
-description.  You don't even have to do anything special in your class
-definition.  For example, objects of this class:
-
-  package My::Frame;
-  use Gtk2;
-  use Glib::Object::Subclass
-      Gtk2::Frame::,
-      properties => [
-          Glib::ParamSpec->int ('foo', ...),
-      ],
-      ;
-
-  ...
-
-  1;
-
-could be expressed in a builder definition file like this:
-
-  <object class="My__Frame" id="myframe">
-    <property name="foo">15</property>
-  </object>
-
-Notice that the '::' package separator has been replaced with '__' in the
-C<class> attribute; this is because the ':' character is not valid for
-GType type names.  The mapping from perl package names to GType names should,
-in general, be as simple as transliterating the colons.
-
-
-=head1 PLAIN OBJECTS
-
-Glib::Object does not implement Gtk2::Buildable by itself, so to get a
-builder UI file to create your custom Glib::Object subtypes, you'll have
-add the Gtk2::Buildable interface to your class's interfaces list.
-
-  package My::Thing;
-  use Gtk2; # to get Gtk2::Buildable
-  use Glib::Object::Subclass
-      Glib::Object::,
-      interfaces => [ 'Gtk2::Buildable' ],
-      ...
-      ;
-
-Again, if you have no special requirements, then that should be all you need
-to do.
+The Gtk2::Buildable interface allows objects and widgets to have
+C<< <child> >> objects, special property settings, or extra custom
+tags in a Gtk2::Builder UI description
+(L<http://library.gnome.org/devel/gtk/unstable/GtkBuilder.html#BUILDER-UI>).
+
+The main user of the Gtk2::Buildable interface is Gtk2::Builder, so
+there should be very little need for applications to call any of the
+Gtk2::Buildable methods.  So this documentation deals with
+implementing a buildable object.
+
+Gtk2::Builder already supports plain Glib::Object or Gtk2::Widget with
+C<< <object> >> construction and and C<< <property> >> settings, so
+often the C<Gtk2::Buildable> interface is not needed.  The only thing
+to note is an object or widget implemented in Perl must be loaded
+before building.
 
 =head1 OVERRIDING BUILDABLE INTERFACE METHODS
 
-In some cases, you need to override the default Buildable behavior.  Maybe
-your objects already store their names, or you need some special markup
-tags to express configuration.  In these cases, add the Gtk2::Buildable
-interface to your object declaration, and implement the following methods
-as necessary.
+The buildable interface can be added to a Perl code object or widget
+subclass by putting C<Gtk2::Buildable> in the interfaces list and
+implementing the following methods.
 
-Note that in the current implementation the custom tags code doesn't
+In current Gtk2-Perl the custom tags code doesn't
 chain up to any buildable interfaces in superclasses.  This means for
 instance if you implement Gtk2::Buildable on a new widget subclass
 then you lose the <accelerator> and <accessibility> tags normally