NAME

Gtk2::Ex::ToolItem::ComboEnum -- toolitem with combobox of enum values

SYNOPSIS

 use Gtk2::Ex::ToolItem::ComboEnum;
 my $toolitem = Gtk2::Ex::ToolItem::ComboEnum->new
                  (enum_type   => 'Glib::UserDirectory',
                   overflow_mnemonic => '_Directory',
                   active_nick => 'home');  # initial selection

WIDGET HIERARCHY

Gtk2::Ex::ToolItem::ComboEnum is a subclass of Gtk2::ToolItem (new in Gtk 2.4).

    Gtk2::Widget
      Gtk2::Container
        Gtk2::Bin
          Gtk2::ToolItem
            Gtk2::Ex::ToolItem::ComboEnum

and implements interfaces

    Gtk2::Buildable  (in Gtk 2.12 up)

DESCRIPTION

This is a ToolItem holding a Gtk2::Ex::ComboBox::Enum to let the user choose a value from an enum. It shows the ComboBox normally, or in an overflow menu offers the same choices in a radio menu using Gtk2::Ex::Menu::EnumRadio. The menu is linked to the combobox so they update together.

    toolbar overflow
       +---+    
       | V |  
       +---------------+
       | Other         |
       | Enumeration > |+------------+
       | Other         ||   EChoice1 |
       +---------------+|   EChoice2 |
                        | * EChoice3 |   <-- active-nick
                        |   EChoice4 |       radio choice
                        +------------+

The enum-type and active-nick properties on the ToolItem act on the ComboBox. They're on the ToolItem for ease of initialization.

The ComboBox child can be accessed with $toolitem->get_child in the usual way if desired, perhaps to set ComboBox specific properties. See "BUILDABLE" below for doing the same from Gtk2::Builder.

Implementation

This is a subclass rather than just a create-menu-proxy helper function so as to have overflow-mnemonic as an actual property, and since enum-type and active-nick on item means less setup code for an application.

FUNCTIONS

$toolitem = Gtk2::Ex::ToolItem::ComboEnum->new (key=>value,...)

Create and return a new ComboEnum toolitem widget. Optional key/value pairs set initial properties per Glib::Object->new.

    my $toolitem = Gtk2::Ex::ToolItem::ComboEnum->new
                     (enum_type   => 'Gtk2::TextDirection',
                      active_nick => 'ltr',
                      overflow_mnemonic => '_Direction');

$combobox = $toolitem->get_child

The usual get_child method (from Gtk2::Bin) gives the child ComboBox if you want to set properties etc on it.

PROPERTIES

enum-type (type name, default undef)

The enum type to display and select from. This is the child ComboBox property made available on the ToolItem for convenience.

active-nick (string or undef, default undef)

The nick of the selected enum value. This is the child ComboBox property made available on the ToolItem for convenience.

overflow-mnemonic (string or undef, default undef)

A mnemonic style string to show in the overflow menu.

If undef then currently the fallback is to present the enum type, which might at least suggest what the item is for if you forgot to set overflow-mnemonic.

The add-tearoffs property on the ComboBox child is propagated to the overflow enum submenu so if there's a tearoff on the ComboBox then there's also a tearoff on the enum menu.

BUILDABLE

Gtk2::Ex::ToolItem::ComboEnum can be constructed with Gtk2::Builder (new in Gtk 2.12). The class name is Gtk2__Ex__ToolItem__ComboEnum and properties and signal handlers can be set in the usual way.

The child combobox is made available as an "internal child" under the name "combobox". This can be used to set desired properties on that child (those not otherwise offered on the ToolItem). Here's a sample fragment, or see examples/tool-enum-builder.pl in the ComboBoxBits sources for a complete program.

    <object class="Gtk2__Ex__ToolItem__ComboEnum" id="toolitem">
      <child internal-child="combobox">
        <object class="Gtk2__Ex__ComboBox__Enum" id="blah_combo">
          <property name="tooltip-text">Tooltip for the ComboBox</property>
        </object>
      </child>
    </object>

The internal-child means <child> is not creating a new child object, but accessing one already built. The id="blah_combo" part is the name to refer to the child elsewhere in the Builder specification, including a later $builder->get_object. That id be present even if unused.

BUGS

As of Perl-Gtk 1.223 the Gtk2::Buildable interface from Perl code doesn't chain up to the parent buildable methods, so some of GtkWidget specifics may be lost, such as the <accessibility> tags.

SEE ALSO

Gtk2::ToolItem, Gtk2::Ex::ComboBox::Enum, Gtk2::Ex::Menu::EnumRadio, Gtk2::Ex::ToolItem::OverflowToDialog

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