NAME

Gtk2::Ex::Menu::EnumRadio -- menu of enum values as radio items

SYNOPSIS

 use Gtk2::Ex::Menu::EnumRadio;
 my $menu = Gtk2::Ex::Menu::EnumRadio->new
              (enum_type   => 'Glib::UserDirectory',
               active_nick => 'home');  # initial selection

WIDGET HIERARCHY

Gtk2::Ex::Menu::EnumRadio is a subclass of Gtk2::Menu,

    Gtk2::Widget
      Gtk2::Container
        Gtk2::MenuShell
          Gtk2::Menu
            Gtk2::Ex::Menu::EnumRadio

DESCRIPTION

Gtk2::Ex::Menu::EnumRadio displays the values of a Glib::Enum in a menu as a radio group allowing the user to select one of them. The active-nick property is the user's selection.

    +----+
    |Menu|
    +--------------------+
    |  Enum Value One    |
    |* Enum Value Two    |
    |  Enum Value Third  |
    |  Enum Value Fourth |
    +--------------------+

The text shown for each entry is per Glib::Ex::EnumBits to_display(), so an enum class can arrange how its values appear, or the default is a sensible word split and capitalization.

(There's a secret experimental might change in the future nick-to-display signal for per-instance control of the display. A signal is good for a callback, but some care may be needed to have it connected early enough, or for the calls to be made later than when enum-type is set, since that property will often be set before making signal connections.)

There's no way to set mnemonics for each enum value. A semi-automatic way to pick sensible ones might be good.

Implementation

For reference, in the current code the menu items are a private subclass of Gtk2::CheckMenuItem. They're not Gtk2::RadioMenuItem because it insists on having one value always selected whereas for this EnumRadio the initial default is nothing selected, similar to a ComboBox. The items display in draw-as-radio style when possible (Gtk 2.4 up).

The current code will tolerate extra items added to the menu. Only those which are enum values are updated, deleted, etc. The idea is to allow say a Gtk2::TearoffMenuItem or equivalent like Gtk2::Ex::Dashes::MenuItem at the start. But this is not quite settled, so beware of future changes. In particular it may need something to express whether extra items belong before or after the enum items.

FUNCTIONS

$menu = Gtk2::Ex::Menu::EnumRadio->new (key=>value,...)

Create and return a new EnumRadio menu object. Optional key/value pairs set initial properties per Glib::Object->new.

    my $menu = Gtk2::Ex::Menu::EnumRadio->new
                 (enum_type   => 'Gtk2::TextDirection',
                  active_nick => 'ltr');

$str = $menu->get_active_nick()

Return the nick of the currently selected enum value, or undef if nothing selected. This is the active-nick property.

$menu->set_active_nick($str)

Set the enum value selected, by its nick, or undef to select nothing. This is the active-nick property.

In the current code if $str is not a nick in the current enum-type then set_active_nick (and the property setting) quietly set to nothing selected. Perhaps this will change.

PROPERTIES

enum-type (type name, default undef)

The enum type to display and select from. Until this is set the Menu is empty.

When changing enum-type if the current selected active-nick also exists in the new type then it remains selected (possibly a different menu item). If the active-nick doesn't exist in the new type then the menu changes to nothing selected.

This property is a Glib::Param::GType when possible or Glib::Param::String otherwise. In both cases at the Perl level the value is a type name string, but a GType will check the given type really is an enum.

active-nick (string or undef, default undef)

The nick of the selected enum value. The nick is the usual way an enum value appears at the Perl level.

If there's no active row in the menu or no enum-type has been set then active-nick is undef.

There's no default for active-nick, so when creating an Enum menu it's usual to set the desired initial selection.

BUGS

The enum-type paramspec default is not the actual default undef (in particular when it's a GType it's "Glib::Enum" instead).

    # this should be undef, usually isn't
    $menu->find_property('enum-type')->get_default_value

SEE ALSO

Gtk2::Menu, Glib::Ex::EnumBits, Gtk2::Ex::ComboBox::Enum

HOME PAGE

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

LICENSE

Copyright 2010, 2011 Kevin Ryde

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

cpanm Gtk2::Ex::ComboBoxBits

perl -MCPAN -e shell
install Gtk2::Ex::ComboBoxBits