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.

Attachment: Subclass.pm.prop-doc.diff
Description: Text Data