NAME

Gtk2::Ex::ToolItem::OverflowToDialog -- toolitem overflowing to a dialog

SYNOPSIS

 use Gtk2::Ex::ToolItem::OverflowToDialog;
 my $toolitem = Gtk2::Ex::ToolItem::OverflowToDialog->new
                  (child_widget => $widget);

WIDGET HIERARCHY

Gtk2::Ex::ToolItem::OverflowToDialog is a subclass of Gtk2::ToolItem,

    Gtk2::Widget
      Gtk2::Container
        Gtk2::Bin
          Gtk2::ToolItem
            Gtk2::Ex::ToolItem::OverflowToDialog

DESCRIPTION

This ToolItem displays a given child widget in the usual way, and makes an overflow menu item to display it in a dialog if the toolbar is full.

       toolbar overflow  
       +---+             
       | V |                   dialog                  
       +-----------+           +----------------------+
       | Other     |           |        My Item       |
       | My Item   |  -->      | +------------------+ |
       | Other     |           | |   child-widget   | |
       +-----------+           | +------------------+ |
                               +----------------------+
                               | Close                |
                               +----------------------+

This ensures a toolitem is always available to the user, if you don't have a better idea for an overflow. It's quite well suited to widgets with a lot of state, such as Gtk2::Entry, as it's the one child widget presented in two places.

For buttons or check box type children usually it's better to have the overflow menu item just act directly on the child, like the usual Gtk2::ToolButton, Gtk2::ToggleToolButton and Gtk2::RadioToolButton. Or for instance Gtk2::Ex::ToolItem::ComboEnum does a menu item with sub-menu.

Implementation

The dialog works by reparenting the child widget to the dialog then putting it back to the toolitem when closed, unmapped, or destroyed.

If the dialog is open and the toolbar becomes big enough to show the toolitem, then the dialog is not immediately popped down. This seems most sensible for the user, in particular as it's not easy to be sure the child would be visible if put back, and if the toolbar size is jumping about then the user won't be pleased to have the dialog taken away but the item not visible.

Due to the reparenting, the child widget isn't in the usual container $toolitem->get_child (or get_children, foreach, etc). The child-widget property is always the child, wherever it's been reparented.

Care should be taken in any signal handlers in the child not to assume that get_parent or get_ancestor will give the toolbar or main window etc.

FUNCTIONS

Gtk2::Ex::ToolItem::OverflowToDialog->new (key=>value,...)

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

PROPERTIES

child-widget (Gtk2::Widget, default undef)

The child widget to show in the toolitem or dialog.

This is set by the usual Gtk2::Container child property too, but child is write-only and can only store to an empty ToolItem, whereas child-widget is read/write and setting it replaces any existing child widget.

The usual container method $toolitem->add($widget) sets this child widget too, but again only into an empty ToolItem.

overflow-mnemonic (string, default undef)

A mnemonic string to show in the overflow menu item. It should have "_" underscores like "_Foo" with the "_F" meaning the "F" can be pressed to select the item. (Double underscore "__" is a literal underscore.)

The ToolItem sensitive property is propagated to the overflow menu item and to the dialog's child area. (But the dialog close button is always sensitive.) Setting insensitive just on the child widget works too, but will leave the menu item sensitive. It's probably better to make the whole toolitem insensitive so the menu item is disabled too.

The ToolItem tooltip-text property (new in Gtk 2.12) is copied to the dialog's child area. A tooltip can also be put just on the child widget too.

BUILDABLE

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

    <object class="Gtk2__Ex__ToolItem__OverflowToDialog" id="toolitem">
      <property name="overflow-mnemonic">_Foo</property>
    </object>

There's two "internal child" widgets available,

    overflow_menuitem    GtkMenuItem for toolbar overflow
    dialog               GtkDialog opened from there

They can be used to set desired properties on those widgets (things not otherwise offered from the ToolItem itself). Here's a sample fragment,

    <object class="Gtk2__Ex__ToolItem__OverflowToDialog" id="toolitem">
      <child internal-child="dialog">
        <object class="GtkDialog" id="ddd">
          <property name="icon-name">something</property>
        </object>
      </child>
    </object>

internal-child means <child> doesn't create a new child object, but accesses one already in the parent. id="ddd" is the name to refer to it elsewhere in the Builder specification and possible later $builder->get_object(). An id must be present even if not used.

Both overflow_menuitem and dialog have the effect of creating those sub-parts immediately, where normally they wait until actually needed for a toolbar overflow and then when the user clicks on the menu item, both of which might never happen of course.

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::ToolButton, Gtk2::ToggleToolButton, Gtk2::RadioToolButton, Gtk2::Ex::ToolItem::ComboEnum, Gtk2::Ex::ToolItem::CheckButton, Gtk2::Ex::MenuBits

HOME PAGE

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

LICENSE

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

cpanm Gtk2::Ex::WidgetBits

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