view release on metacpan or  search on metacpan

lib/Glib/Ex/ConnectProperties.pm  view on Meta::CPAN

    number         integer or float
    enum           Glib::Enum subtypes
    flags          Glib::Flags subtypes
    object         Glib::Object
    string array   Glib::Strv
    some boxed     Glib::Boxed

Boxed types which work include C<Gtk2::Gdk::Color> and
C<Gtk2::Gdk::Rectangle>, but others may not.  See L</Equality> below.

Read-only properties can be used.  They're propagated out to the other
linked properties but any changes in those others are not stored back.
Usually this is only useful when the read-only is the only one changing.
You could easily enough make an explicit signal handler to propagate the
value, but a ConnectProperties is convenient and is careful not to make
circular references.  See the C<read_only> option below to force read-only.

Write-only properties can be used.  Nothing is read out of them, they're
just set from changes in the other linked properties.  Write-only properties
are unusual, but see the C<write_only> option below to force write-only.

Properties within the same object can be linked.  This can ensure they
update together.  Different ConnectProperties linkages can have an
object/property in common.  A change coming from one group propagates
through to the other.  This arises quite naturally if there's two separate
controls for the same target.  The two controls and the target then all
change together.

=head2 Property Class Name

A property name can include an explicit class such as C<GtkLabel::justify>
in the usual style of C<set_property()>, C<find_property()>, etc.

    # property name including explicit class name,
    # usually not necessary
    [ $widget, 'GtkLabel::justify' ]

If a subclass accidentally shadows a superclass property name then this
gives access to the superclass property.  But it's otherwise not necessary
and is not recommended.  For a Perl subclass like C<My::Foo::Bar> the
fully-qualified name is C<My__Foo__Bar::propname> as usual for Perl module
to Glib class name conversion.

=head2 Other Settings

Various additional object or widget settings can be accessed by
ConnectProperties.  They're either other flavours of properties, or are
non-property attributes which have some sort of signal notifying when they
change.  For example container child properties,

    "child#propname"

See the following modules for Gtk related settings,

=over

=over

=item L<Glib::Ex::ConnectProperties::Element::child>

=item L<Glib::Ex::ConnectProperties::Element::combobox_active>

=item L<Glib::Ex::ConnectProperties::Element::model_rows>

=item L<Glib::Ex::ConnectProperties::Element::response_sensitive>

=item L<Glib::Ex::ConnectProperties::Element::screen_size>

=item L<Glib::Ex::ConnectProperties::Element::tree_selection>

=item L<Glib::Ex::ConnectProperties::Element::iconview_selection>

=item L<Glib::Ex::ConnectProperties::Element::widget>

=item L<Glib::Ex::ConnectProperties::Element::widget_allocation>

=back

=back

The C<Gtk2> elements don't create a dependency on C<Gtk2> unless you use
them.  The implementation is modular so extras are not loaded unless used.
The C<#> separator character doesn't clash with plain property names as it's
not allowed in a ParamSpec name.

See L<Glib::Ex::ConnectProperties::Element> on creating a new element
subclass.

=head1 FUNCTIONS

=head2 Creation

=over 4

=item C<< $conn = Glib::Ex::ConnectProperties->new ([$obj1,$pname1], [$obj,$pname2], ...) >>

Connect two or more given object+property combinations.  The connection
lasts for as long as the objects do.

The return value is a Perl object of type C<Glib::Ex::ConnectProperties>.
It can be kept to later break the connection with C<disconnect()> below,
otherwise it can be ignored.

=item C<< $conn = Glib::Ex::ConnectProperties->dynamic ([$obj1,$pname1], [$obj,$pname2], ...) >>

Connect two or more given object+property combinations.  The return is a
Perl object of type C<Glib::Ex::ConnectProperties>.  The connection lasts
only as long as you keep this returned object.

=back

The arguments to both constructors are arrayrefs with an object, a property
name, and perhaps further options as described below.  For example

    Glib::Ex::ConnectProperties->new
      ([$object1, 'some-propname'],
       [$object2, 'another-propname']);

An initial value is propagated from the first object+property (the first
readable one) to set all the others, if they're not already the same.  So
put the object with the desired initial value first.