Glib::Ex::TieProperties -- tied hash for Glib object property access
use Glib::Ex::TieProperties; my %hash; tie %hash, 'Glib::Ex::TieProperties', $object; # or an anonymous hashref my $href = Glib::Ex::TieProperties->new ($object);
Glib::Ex::TieProperties accesses properties of a given Glib::Object through a tied hash. The keys are the property names and fetching and storing values operates on the property values.
Glib::Ex::TieProperties
Glib::Object
If you're just getting and setting properties then the Object get() and set() methods are enough. But a 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).
get()
set()
local
goto
return
die
{ tie my(%aprops), 'Glib::Ex::TieProperties', $adjustment; local $aprops{'page-increment'} = 100; do_page_up(); }
With new() to create a tied hashref a single long local expression is possible
new()
# 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 is better in concept than actuality. There's relatively few object properties needing block-scoped changes, and things like getting all property names or values must generally pay attention to whether properties are read-only, write-only, etc, so an each() etc iteration is rarely good.
tie
each()
The property name 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.
get_property()
find_property()
border_width
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.
keys
each
$obj->list_properties()
Getting a non-existent property name returns undef, the same as a non-existent entry in an ordinary Perl hash. exists tests for a key with find_property().
undef
exists
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 property throws an error, a bit like a restricted hash (see Hash::Util). Storing to a read-only property likewise throws an error.
In Perl 5.8.3 and up scalar() gives a bucket count like "17/17" when not empty, similar to a real hash. This might help code expecting a slashed count, not just a boolean. The return pretends the hashing is perfect, but don't depend on that since perhaps in the future some more realistic report might be possible.
scalar()
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 property values in $object.
%h
$object
Optional key/value pairs in the tie set the following options
weak => boolean
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 a hash and a hashref is normally just a matter of which style you prefer. Both can be created with one line of code (the my worked into the tie call of the plain hash).
my
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
property
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 => $str
Set the field name within $object for 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,
field
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 that it's not a circular reference which would keep $object alive forever.
weak
in_object()
The tie object associated with the hash, which is returned by the tie or obtained later with tied(), has the following methods.
tied()
$tobj->object()
Return the underlying object (Glib::Object object) being accessed by $tobj.
$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;
The Glib module $object->tie_properties() feature does a very similar thing. But it works by populating $object with individual tied field objects for the properties. Glib::Ex::TieProperties is separate from the object and may use a little less memory since it's one object instead of many. But separate means an extra variable, or an extra indirection for the in_object() style above.
Glib
$object->tie_properties()
Glib, Glib::Object
http://user42.tuxfamily.org/glib-ex-objectbits/index.html
Copyright 2009, 2010, 2011, 2012, 2014 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/.
To install Glib::Ex::ObjectBits, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Glib::Ex::ObjectBits
CPAN shell
perl -MCPAN -e shell install Glib::Ex::ObjectBits
For more information on module installation, please visit the detailed CPAN module installation guide.