NAME

Gtk2::Ex::MenuBits -- miscellaneous Gtk2::Menu helpers

SYNOPSIS

 use Gtk2::Ex::MenuBits;

FUNCTIONS

($x,$y,$push_in) = Gtk2::Ex::MenuBits::position_widget_topcentre ($menu, $x, $y, $userdata)

Position a menu with its top edge centred in a given $userdata widget. This is good for a menu popped up by a keystroke in a "strip" type widget which is wide but has only a small height.

    $menu->popup (undef,    # no parent menushell
                  undef,    # no parent menuitem
                  \&Gtk2::Ex::MenuBits::position_widget_topcentre,
                  $widget,  # userdata
                  0,        # no button for keyboard popup
                  $event_time);

$userdata can be either a widget or a reference to a widget. The latter can be a weak reference so as to avoid a circular reference between a widget and a menu within it ($menu->popup holds $userdata within the menu for later reposition).

If $userdata is undef or a ref to undef, or if the widget is not mapped or is on a different screen than $menu, then the return is the given $x,$y input parameters. This is the mouse pointer position if called straight from Gtk2::Menu.

A multi-screen program should set_screen on the menu to ensure it's the same as the widget. This is left to the application because it's probably not safe within the positioning function, especially not if the positioning is called from set_screen itself due to moving a popped-up menu to a different screen.

In the current implementation if the widget is in an iconified toplevel then the position is based on its un-iconified location. The intention in the future is to go to the mouse position fallback in this case, since the widget is not on-screen. Of course when iconified a widget won't get keyboard or button events to cause a menu popup, so in practice this doesn't arise.

Mnemonic Strings

$mstr = Gtk2::Ex::MenuBits::mnemonic_escape ($str)

Return $str with underscores doubled. This can be used to ensure $str will appear as-is in a "mnemonic" type label etc. For example,

    Gtk2::Ex::MenuBits::mnemonic_undo ("Some_Thing_XYZ")
    # gives "Some__Thing__XYZ"

$str = Gtk2::Ex::MenuBits::mnemonic_undo ($mstr)

Return $mstr with "_" underscore mnemonic markers removed. This is how $mstr would appear, without the underlining implied by the "_" marker.

Doubled underscores "__" mean a literal single underscore. So for example,

    Gtk2::Ex::MenuBits::mnemonic_undo ("Save _As X__Y__Z")
    # gives "Save As X_Y_Z"

EXPORTS

Nothing is exported by default, but position_widget_topcentre can be requested in usual Exporter style,

    use Gtk2::Ex::MenuBits 'position_widget_topcentre';
    $menu->popup (undef, undef,
                  \&position_widget_topcentre, $widget,
                  0, 0);

There's no :all tag since this module is meant as a grab-bag of functions and to import as-yet unknown things would be asking for name clashes!

SEE ALSO

Gtk2::Menu, Gtk2::Ex::WidgetBits, Exporter

HOME PAGE

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

LICENSE

Copyright 2007, 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/.