/ 
Glib-Ex-ObjectBits-17
River stage two • 16 direct dependents • 18 total dependents
/ Glib::Ex::TieProperties

NAME

Glib::Ex::TieProperties -- tied hash for Glib 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 fetching and storing values operates on the property values.

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).

{
  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

# 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.

Details

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.

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 for 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 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.

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 property values in $object.

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

weak => boolean, default false

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).

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 => $str, default "property"

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,

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.

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 WAYS TO DO IT

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.

SEE ALSO

Glib, Glib::Object

HOME PAGE

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

LICENSE

Copyright 2009, 2010, 2011, 2012, 2014, 2024 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/.