NAME

Gtk2::Ex::ActionTooltips -- propagate Action tooltips to MenuItems

SYNOPSIS

 use Gtk2::Ex::ActionTooltips;
 Gtk2::Ex::ActionTooltips::group_tooltips_to_menuitems
     ($actiongroup);
 Gtk2::Ex::ActionTooltips::action_tooltips_to_menuitems_dynamic
     ($action1, $action2, $action2);

DESCRIPTION

This spot of code sets tooltips from Gtk2::Actions onto Gtk2::MenuItems connected to those actions. Normally the action connection sets tooltips onto Gtk2::ToolItems, but not MenuItems.

The widget tooltip-text mechanism is used, which is new in Gtk 2.12 and up. For earlier Gtk the functions here do nothing.

Whether you want tooltips on MenuItems depends on personal preference or how much explanation the actions need. A MenuItem tooltip is fairly unintrusive though, and pops up only after the usual delay.

See examples/action-tooltips.pl in the Gtk2-Ex-WidgetBits sources for a sample program setting tooltips on menu items.

There's other ways to show what a menu item might do of course. For instance the Gtk manual under the GtkActionGroup connect-proxy signal describes showing action tooltips in a statusbar.

EXPORTS

Nothing is exported by default and the functions can be called with a fully qualified name as shown. Or they can be imported in usual Exporter style, including tag :all for all functions.

    use Gtk2::Ex::ActionTooltips 'group_tooltips_to_menuitems';
    group_tooltips_to_menuitems ($actiongroup);

FUNCTIONS

Gtk2::Ex::ActionTooltips::group_tooltips_to_menuitems ($actiongroup)

Setup $actiongroup (a Gtk2::ActionGroup) so tooltips in its actions are installed on any connected Gtk2::MenuItems.

    my $actiongroup = Gtk2::ActionGroup->new ("main");
    Gtk2::Ex::ActionTooltips::group_tooltips_to_menuitems
        ($actiongroup);

The tooltips are applied to current and future connected MenuItems, for all current and future actions in the group. But the tooltips in the actions are assumed to be unchanging. If you change a tooltip then the change is not propagated to already-connected menu items.

Gtk2::Ex::ActionTooltips::action_tooltips_to_menuitems_dynamic ($action1, $action2, ...)

Setup each given $action (Gtk2::Action object) so its tooltip property is installed on any connected Gtk2::MenuItmss dynamically.

    Gtk2::Ex::ActionTooltips::action_tooltips_to_menuitems_dynamic
      ($my_help_action,
       $my_frobnicate_action);

The tooltips are applied to currently connected MenuItems, and any future connected MenuItems, and the setup is "dynamic" in that if you change the action tooltip then the change is propagated to connected MenuItems.

    $my_help_action->set (tooltip => 'New text');

action_tooltips_to_menuitems_dynamic makes a signal connection on each Action. To keep down overheads you probably only want it on actions which might change their tooltips. If you want dynamic propagation for all Actions in an ActionGroup you could use

    Gtk2::Ex::ActionTooltips::action_tooltips_to_menuitems_dynamic
      ($actiongroup->list_actions);

Of course this is only actions currently in the ActionGroup, not future added ones. As of Gtk 2.16 there's no callback from an ActionGroup when an action is added to it, so there's no easy way to cover future added actions too.

SEE ALSO

Gtk2::Action, Gtk2::ActionGroup, Gtk2::MenuItem

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