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 particular Gtk2::Statusbar widget. It's designed for message sources or contexts 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 string, like package name, or package plus component. Dynamic context is when you're doing something like spawning object instances each of which may make a status message. In that case they need a context string each and will want to re-use in later instances.

When a DynamicContext object is garbage collected its 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 make permanent additions to the widget memory and the global quark table. Something simple like sequentially numbered strings will consume ever more memory. With re-use space is capped at the peak contexts in use 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. Usually the integer id is all you need. The ID is simply

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

Strings are unique within a particular $statusbar widget, but not globally. DynamicContext deliberately uses the same strings on different statusbars so as to keep the quark table smaller.

$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::MessageUntilKey

HOME PAGE

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

LICENSE

Copyright 2008, 2009, 2010 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/.