GET/SET_PROPERTY docs

[Kevin Ryde <user42 zip com au>]

I found the docs on GET_PROPERTY/SET_PROPERTY a little hard going at
first.  I wonder if it could be expanded a bit, perhaps like the
following (formatted for readability, diff below).



       GET_PROPERTY $self, $pspec                          [not a method]
       SET_PROPERTY $self, $pspec, $newval                 [not a method]
           "GET_PROPERTY" and "SET_PROPERTY" are called whenever somebody does
           "$object->get ($propname)" or "$object->set ($propname => $newval)"
           (from other languages, too).  The default implementations hold
           property values in the object hash, equivalent to

              sub GET_PROPERTY {
                my ($self, $pspec) = @_;
                my $pname = $pspec->get_name;
                return (exists $self->{$pname} ? $self->{$pname}
                        : $pspec->get_default_value);  # until set
              }
              sub SET_PROPERTY {
                my ($self, $pspec, $newval) = @_;
                $self->{$pspec->get_name} = $newval;
              }

           Because "$pspec->get_name" converts hyphens to underscores, a prop-
           erty "line-style" is in the hash as "line_style".

           These methods let you store/fetch properties in any way you need
           to.  They don't have to be in the hash, you can calculate some-
           thing, read a file, whatever.

           Most often you'll write your own "SET_PROPERTY" so you can take
           action when a property changes, like redraw or resize a widget.
           Eg.

              sub SET_PROPERTY {
                my ($self, $pspec, $newval) = @_;
                my $pname = $pspec->get_name
                $self->{$pname} = $newval; # ready for default GET_PROPERTY

                if ($pname eq 'line_style') {
                  $self->queue_draw;  # redraw with new lines
                }
              }

           "GET_PROPERTY" is different from a C get_property method in that
           the perl method returns the retrieved value. For symmetry, the
           $newval and $pspec args on "SET_PROPERTY" are swapped from the C
           usage.


--- Subclass.pm	02 Jul 2005 10:35:15 +1000	1.13
+++ Subclass.pm	21 Apr 2008 11:12:33 +1000	
@@ -141,31 +141,47 @@
 
 =item GET_PROPERTY $self, $pspec                          [not a method]
 
-Get a property value, see C<SET_PROPERTY>.
-
-The default implementation looks like this:
-
-   my ($self, $pspec) = @_;
-   return ($self->{$pspec->get_name} || $pspec->get_default_value);
-
 =item SET_PROPERTY $self, $pspec, $newval                 [not a method]
 
 C<GET_PROPERTY> and C<SET_PROPERTY> are called whenever somebody does
 C<< $object->get ($propname) >> or C<< $object->set ($propname => $newval) >>
-(from other languages, too). This is your hook that allows you to
-store/fetch properties in any way you need to (maybe you have to calculate
-something or read a file).
+(from other languages, too).  The default implementations hold property
+values in the object hash, equivalent to
+
+   sub GET_PROPERTY {
+     my ($self, $pspec) = @_;
+     my $pname = $pspec->get_name;
+     return (exists $self->{$pname} ? $self->{$pname}
+             : $pspec->get_default_value);  # until set
+   }
+   sub SET_PROPERTY {
+     my ($self, $pspec, $newval) = @_;
+     $self->{$pspec->get_name} = $newval;
+   }
+
+Because C<< $pspec->get_name >> converts hyphens to underscores, a property
+C<"line-style"> is in the hash as C<line_style>.
+
+These methods let you store/fetch properties in any way you need to.  They
+don't have to be in the hash, you can calculate something, read a file,
+whatever.
+
+Most often you'll write your own C<SET_PROPERTY> so you can take action when
+a property changes, like redraw or resize a widget.  Eg.
+
+   sub SET_PROPERTY {
+     my ($self, $pspec, $newval) = @_;
+     my $pname = $pspec->get_name
+     $self->{$pname} = $newval; # ready for default GET_PROPERTY
+
+     if ($pname eq 'line_style') {
+       $self->queue_draw;  # redraw with new lines
+     }
+   }
 
 C<GET_PROPERTY> is different from a C get_property method in that the
 perl method returns the retrieved value. For symmetry, the C<$newval>
-and C<$pspec> args on C<SET_PROPERTY> are swapped from the C usage. The
-default get and set methods store property data in the object as hash
-values named for the parameter name.
-
-The default C<SET_PROPERTY> looks like this:
-
-   my ($self, $pspec, $newval) = @_;
-   $self->{$pspec->get_name} = $newval;
+and C<$pspec> args on C<SET_PROPERTY> are swapped from the C usage.
 
 =item FINALIZE_INSTANCE $self                             [not a method]