NAME

Gtk2::Ex::Statusbar::DynamicContext -- pool of Gtk2::Statusbar context strings

SYNOPSIS

use Gtk2::Ex::Statusbar::DynamicContext;
my $dc = Gtk2::Ex::Statusbar::DynamicContext->new
             ($statusbar);
$statusbar->push ($dc->id, 'Some message');
$statusbar->pop  ($dc->id);

DESCRIPTION

A DynamicContext object is a generated context string and ID number for a Gtk2::Statusbar widget. It's designed for message sources or contexts which are created and destroyed dynamically at runtime.

Usually you don't need a dynamic context. Most libraries or parts of a program can just take something distinctive from their name as a context string. For example a Perl package name, or package name plus component.

# fixed id for package
$id = $statusbar->get_context_id(__PACKAGE__.'.warning');

Dynamic context is when you do something like spawn multiple object instances each of which might display a status message. In that case they need a separate context string each.

# dynamic id for each instance of a package
$obj = MyPackage->new;
$obj->{'dc'} = Gtk2::Ex::Statusbar::DynamicContext->new($statusbar);
$id = $obj->{'dc'}->id;

When a DynamicContext object is garbage collected the string is returned to a pool for future re-use on the Statusbar widget. This is important for a long-running program because a context string and its ID in a Statusbar are permanent additions to the memory of that widget and to the global quark table. That means a simple approach like sequentially numbered context strings is not enough, it would consume ever more memory. With DynamicContext style re-use the space is capped at the peak number of contexts used at any one time.

Weakening

DynamicContext only holds a weak reference to its $statusbar, so the mere fact a message context exists doesn't keep the Statusbar alive.

FUNCTIONS

$dc = Gtk2::Ex::Statusbar::DynamicContext->new ($statusbar)

Create and return a new DynamicContext object for $statusbar (a Gtk2::Statusbar widget).

$id = $dc->id()

Return the context ID (an integer) from $dc. It can be used with $statusbar->push etc.

$statusbar->push ($dc->id, 'Some message');

If the statusbar has been garbage collected then the return from id() is unspecified.

$str = $dc->str()

Return the context description string from $dc. This is not often needed, usually the integer id() is enough. In the current implementation the string is like

"Gtk2::Ex::Statusbar::DynamicContext.123"

but don't depend on its exact form, only that it's unique within the target $statusbar. The id() method above is simply

$statusbar->get_context_id($dc->str)

DynamicContext strings are unique within the particular $statusbar but are not globally unique, ie. the same string might be used by another DynamicContext object on another statusbar. Doing so keeps down the size of the Glib quark table.

$statusbar = $dc->statusbar()

Return the Gtk2::Statusbar from $dc. If the statusbar has been garbage collected then this is undef.

SEE ALSO

Gtk2::Statusbar, "weaken" in Scalar::Util

Gtk2::Ex::Statusbar::Message, Gtk2::Ex::Statusbar::MessageUntilKey

HOME PAGE

http://user42.tuxfamily.org/gtk2-ex-widgetbits/index.html

LICENSE

Copyright 2008, 2009, 2010, 2011, 2012 Kevin Ryde

Gtk2-Ex-WidgetBits 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.

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