NAME

Glib::Ex::ConnectProperties::Element -- special property handling

SYNOPSIS

 package Glib::Ex::ConnectProperties::Element::some_thing;
 use base 'Glib::Ex::ConnectProperties::Element';

DESCRIPTION

This is the base class for special properties in Glib::Ex::ConnectProperties. A subclass for a property such as

    some-thing#foo

should be a class created

    package Glib::Ex::ConnectProperties::Element::some_thing;
    use base 'Glib::Ex::ConnectProperties::Element';

An Element instance is a hashref created from Glib::Ex::ConnectProperties->new() etc with property name and options.

    { object  => $obj,       # Glib::Object
      pname   => $string,    # property name "foo"
      ids     => $signalids, # signal connections
      ... further options
    }

A subclass should as a minimum implement the following methods, described below.

    find_property() or pspec_hash()
    read_signal()
    get_value()            # if readable
    set_value()            # if writable

As an example, the simplest subclass is Glib::Ex::ConnectProperties::Element::object which is the code for plain object get_property() etc. It can be seen how find_property() looks at the object property pspecs and read_signal() is the notify, then simply get_property() or set_property() to manipulate the value.

Glib::Ex::ConnectProperties::Element::textbuffer is an example of read-only access to non-property characteristics of a text buffer. It has a fixed set of property names in pspec_hash(), and in fact shares the pspec for "empty" and "not-empty" because the ParamSpec name field doesn't matter, only the type etc.

Glib::Ex::ConnectProperties::Element::screen_size is another read-only, with some runtime adaption to notice when Gtk2 is new enough to have the monitors-changed signal for screen size in millimetres changing.

METHODS

Mandatory Methods

$pspec = $elem->find_property()

$hashref = $elem->pspec_hash()

find_property() should return a Glib::ParamSpec object for the property name $elem->{'pname'}, or return undef if no such property.

The default find_property() implementation calls pspec_hash(). That method should return a hashref name to ParamSpec

   { pname => $pspec,
     ...
   }

pspec_hash() suits subclasses with a fixed set of property names. Subclasses where it varies should implement some sort of find_property().

In each ParamSpec the following fields should be set

    flags       "readable" and/or "writable"
    type        for object, boxed, enum, flags

and for writable properties

    min,max     for int, float

The type of the ParamSpec, such as Glib::Param::Int etc, is used to know what sort of value comparison and validation should be done in the ConnectProperties propagation. For example Glib::Param::Int properties are compared using == whereas strings are compared with eq.

@signal_names = $elem->read_signal()

Return the name of a signal on $self->{'object'} to use to listen for changes to the property value.

The signal name may vary with the property name $self->{'pname'}. For example the plain object properties which use notify,

    sub read_signal {
      my ($self) = @_;
      return 'notify::'.$self->{'pname'};
    }

For some element subclasses there might be a single signal for the changes in a set of related properties,

    use constant read_signal => 'foo-changed';

The read_signal option to ConnectProperties overrides the element method. read_signal() is only ever used for readable properties.

The return from read_signal() is actually a list of signal names. If a class doesn't need any signal at all on $self->{'object'} then return an empty list.

    use constant read_signal => ();

$value = $elem->get_value()

$elem->set_value($value)

Get or set the value of the $elem->{'pname'} property on $elem->{'object'}.

This is usually a method call on the object, acting on some attribute it doesn't offer as a real property or which is more convenient when transformed in some way.

An element subclass will generally look up or derive a method name from $elem->{'pname'}.

    my %get_method = (width  => 'get_width',
                      height => 'get_height');
    sub get_value {
      my ($self) = @_;
      my $method = $method{$self->{'pname'}};
      return $self->{'object'}->$method;
    }

Optional Methods

$elem->check_property()

Check that $elem->{'pname'} is a valid property for the target $elem->{'object'}. Croak if it's not.

This is called during element initialization. The base implementation does $elem->find_property() and if that's undef then croaks with "no such property". An element subclass might make additional checks, or might give a better explanation if perhaps a property is sometimes available and sometimes not.

It's suggested that an element class should not look at the class of the target $elem->{'object'}, but only check for required methods or signals, etc on that object. This allows a similar object with compatible features to be used with the element class.

SEE ALSO

Glib::Ex::ConnectProperties

Glib::Object, Glib::ParamSpec

HOME PAGE

http://user42.tuxfamily.org/glib-ex-connectproperties/index.html

LICENSE

Copyright 2010, 2011, 2012, 2014 Kevin Ryde

Glib-Ex-ConnectProperties is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Glib-Ex-ConnectProperties is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Glib-Ex-ConnectProperties. If not, see http://www.gnu.org/licenses/.

cpanm Glib::Ex::ConnectProperties

perl -MCPAN -e shell
install Glib::Ex::ConnectProperties