/ 
Glib-Ex-ObjectBits-3
/ Glib::Ex::TieProperties

NAME

Glib::Ex::TieProperties -- tied hash for object property access

SYNOPSIS

use Glib::Ex::TieProperties;
my %hash;
tie %hash, 'Glib::Ex::TieProperties', $object;

# or an anonymous hashref
my $href = Glib::Ex::TieProperties->new ($object);

DESCRIPTION

Glib::Ex::TieProperties accesses properties of a given Glib::Object through a tied hash. The keys are the property names and fetch and store operate on the property values.

If you're just getting and setting property values you're best off simply calling the get and set methods, but one good use for a tie is to apply local settings within a block, to be undone by a set back to their previous values no matter how the block is left (goto, return, die, etc).

{
  tie my(%aprops), 'Glib::Ex::TieProperties', $adjustment;
  local $aprops{'page-increment'} = 100;
  do_page_up();
}

With new function to create a tied anonymous hashref a single long local expression is possible

# usually allow-shrink is not a good idea, have it temporarily
local Glib::Ex::TieProperties->new($toplevel)->{'allow-shrink'} = 1;
some_resize();

You can even be creative with hash slices for multiple settings in one statement.

# how big is $toplevel if $widget width is forced
{
  tie my(%wprops), 'Glib::Ex::TieProperties', $widget;
  local @wprops{'width-request','height-request'} = (100, 200);
  my $req = $toplevel->size_request;
}

Like most tie things, TieProperties tends to be better in concept than actuality. There's relatively few object properties that you want to make block-scoped changes to, and things like getting all property names or values generally must pay attention to whether they're read-only, write-only, etc, so a naive iteration is rarely much good.

Details

The property names for the keys are anything accepted by get_property, find_property, etc. This means underscores "_" can be used in place of dashes "-", for example border_width is an alias for border-width.

The keys and each operations return just the dashed names. Currently they return properties in the same order as $obj->list_properties gives, but don't depend on that.

Getting a non-existent property name returns undef, the same as a non-existent entry in an ordinary Perl hash. exists tests a key with find_property.

If a property exists but is not readable then fetching returns undef. An error in that case would also be possible, but that would make it impossible to use each to iterate through an object with any write-only properties. Storing to a non-existent or read-only property throws an error.

FUNCTIONS

tie %h, 'Glib::Ex::TieProperties', $object
tie %h, 'Glib::Ex::TieProperties', $object, key=>value,...

Tie a hash %h to $object so that %h accesses the properties of $object. The keys of %h are property names, the values the settings in $object.

Optional key/value pairs in the tie set the following options

weak

Hold only a weak reference to $object.

tie %h, 'Glib::Ex::TieProperties', $object, weak=>1;

If $object is garbage collected while the tied %h still exists then %h gives undef for all fetches, does nothing for all stores, exists is always false, and keys and each are empty.

Doing nothing for stores is designed to ignore local or similar cleanups which might still be pending. If no-one else cared whether the object lived or died then restoring settings can't be too important.

$hashref = Glib::Ex::TieProperties->new ($object)
$hashref = Glib::Ex::TieProperties->new ($object, key=>value, ...)

Create and return a new anonymous hashref tied to the properties of $object. This is the same as

tie my(%hash), 'Glib::Ex::TieProperties', $object;
$hashref = \%hash;

The difference between using a hash or hashref is normally just a matter of which style you prefer. With the my worked into the tie call it can be a one line setup either way.

Glib::Ex::TieProperties->in_object ($object)
Glib::Ex::TieProperties->in_object ($object, key=>value, ...)

Establish a tied hash within $object accessing its properties. The default is a field called property, so for instance

Glib::Ex::TieProperties->in_object ($object)
$object->{'property'}->{'tooltip-text'} = 'Hello.';

The optional key/value pairs are passed to the tie constructor as above, and in addition

field

Set the field name within $object which becomes the tied hash. The default "property" is designed to be readable and not too likely to clash with other things, but you can control it with the field parameter,

Glib::Ex::TieProperties->in_object ($object, field => 'xyzzy')
print $object->{'xyzzy'}->{'border-width'};

The weak parameter described above is always set on a tied hash established by in_object so it doesn't create a circular reference which would keep $object alive forever.

Tied Object Functions

The tie object associated with the hash, which is returned by the tie or obtained later with tied, has the following methods.

$tobj->object

Return the underlying object (Glib::Object object) being accessed by $tobj.

my %hash
my $tobj = tie %hash, 'Gtk2::Ex::TiedListColumn', $object;
...
print $tobj->object;  # the original $object

Or getting the $tobj later with tied,

my %hash
tie %hash, 'Gtk2::Ex::TiedListColumn', $object;
...
my $tobj = tied(%hash);
my $object = $tobj->object;
$object->show;

OTHER NOTES

The Glib builtin $object->tie_properties feature does a similar thing. It works instead by populating $object with individual tied field objects for the properties. Glib::Ex::TieProperties however is separate from the object and may use a bit less memory since it's one object instead of many. But being separate means an extra variable, or an extra indirection for the in_object style above.

SEE ALSO

Glib, Glib::Object

HOME PAGE

http://www.geocities.com/user42_kevin/glib-ex-objectbits/index.html

LICENSE

Copyright 2009 Kevin Ryde

Glib-Ex-ObjectBits 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-ObjectBits 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-ObjectBits. If not, see http://www.gnu.org/licenses/.