NAME

Gtk2::Ex::Statusbar::MessageUntilKey -- Statusbar message until key or button

SYNOPSIS

use Gtk2::Ex::Statusbar::MessageUntilKey;
Gtk2::Ex::Statusbar::MessageUntilKey->message
   ($statusbar, 'Hello World');

DESCRIPTION

This is an easy way to display a message in a Gtk2::Statusbar, automatically cleared when the user presses a key or mouse button. It's good for the result of a user action, cleared by the next action.

In a multi-display program (multiple Gtk2::Gdk::Display's) the message is only cleared by a key or button from the statusbar's own display. A statusbar can be moved between displays and is cleared only by its current display.

FUNCTIONS

Gtk2::Ex::Statusbar::MessageUntilKey->message ($statusbar, $message)

Push string $message onto $statusbar (a Gtk2::Statusbar), and setup to remove it on the next key press or button press.

If another MessageUntilKey is already displayed in $statusbar then it's replaced by the new $message. The new message goes on the top of the statusbar stack, even if the old one had been buried under other things.

The MessageUntilKey setups only keep a weak reference to $statusbar, so the mere fact there's a message displayed doesn't keep it alive.

Gtk2::Ex::Statusbar::MessageUntilKey->remove ($statusbar)

Remove any MessageUntilKey message displayed in $statusbar. This is what's done on the next key or button press but you can use this sooner for explicit removal. If $statusbar has no MessageUntilKey then remove does nothing.

IMPLEMENTATION

Keypresses are detected with a key snooper, and button presses with a button-press-event emission hook. Of course only those delivered to the program are seen, so keypresses in another program don't clear the message.

A button press in a widget without button-press-mask (meaning something not normally clickable) doesn't reach the client program and so doesn't clear anything. This isn't ideal, but clicking an unclickable isn't really a new user action, so keeping the message may be reasonable. One possibility is to add button-press-mask to the toplevel widget (or all relevant toplevels), even if it doesn't do anything with buttons, so the event reaches the client. Perhaps MessageUntilKey could do that itself, or try selecting on the root window to pick up button presses anywhere at all.

If a statusbar is not under a toplevel window (Gtk2::Window) then currently it ends up treated as on the default display (Gtk2::Gdk::Display->get_default) and MessageUntilKey cleared by a key or button from that display. Would it be better to leave an unparented statusbar alone? Of course when unparented it's not visible, so the contents aren't important until redisplayed later.

SEE ALSO

Gtk2::Statusbar, Gtk2::Ex::KeySnooper, Gtk2::Ex::Statusbar::DynamicContext

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