Kevin Ryde > Gtk2-Ex-WidgetBits > Gtk2::Ex::MenuItem::Subclass

Download:
Gtk2-Ex-WidgetBits-48.tar.gz

Dependencies

Annotate this POD

Website

CPAN RT

Open  0
View/Report Bugs
Module Version: 48   Source  

NAME ^

Gtk2::Ex::MenuItem::Subclass -- help for subclassing Gtk2::MenuItem

SYNOPSIS ^

 package My::MenuItem;
 use Glib::Object::Subclass 'Gtk2::MenuItem';

 use Gtk2::Ex::MenuItem::Subclass;
 unshift @ISA, 'Gtk2::Ex::MenuItem::Subclass';

 # then in an application
 my $item1 = My::MenuItem->new ('_Foo');
 my $item2 = My::MenuItem->new_with_label ('Bar');
 my $item3 = My::MenuItem->new_with_mnemonic ('_Quux');

DESCRIPTION ^

Gtk2::Ex::MenuItem::Subclass helps subclasses of Gtk2::MenuItem. It provides versions of the following class methods

    new
    new_with_label
    new_with_mnemonic

which behave like the base Gtk2::MenuItem methods but create a widget of the subclass, not merely a Gtk2::MenuItem like the wrapped C code does. This is designed as a multiple inheritance mix-in. For example,

    package My::MenuItem;
    use Glib::Object::Subclass 'Gtk2::MenuItem',
       signals => { ... },
       properties => [ ... ];

    # prepend to prefer this new() etc
    use Gtk2::Ex::MenuItem::Subclass;
    unshift @ISA, 'Gtk2::Ex::MenuItem::Subclass';

Then application code can create a My::MenuItem widget with

    my $item = My::MenuItem->new ('_Foo');

$item is created as a My::MenuItem, as the call suggests. Similarly new_with_label() and new_with_mnemonic().

The same can be done when subclassing from Gtk2::CheckMenuItem too.

ISA order

The unshift @ISA shown above ensures Gtk2::Ex::MenuItem::Subclass is before the new_with_label() and new_with_mnemonic() from Gtk2::MenuItem, and also before the new() from Glib::Object::Subclass. The effect is

    @ISA = ('Gtk2::Ex::MenuItem::Subclass',
            'Glib::Object::Subclass',
            'Gtk2::MenuItem',
            'Gtk2::Item',
            'Gtk2::Bin',
            ...)

If you want the key/value new() from Glib::Object::Subclass rather than the label-string one then put Gtk2::Ex::MenuItem::Subclass just after Glib::Object::Subclass, like

    # for key/value new() per plain Glib::Object
    @ISA = ('Glib::Object::Subclass',
            'Gtk2::Ex::MenuItem::Subclass',
            'Gtk2::MenuItem',
            'Gtk2::Item',
            ...)

All @ISA setups are left to the subclassing package because the order can be important and it can be confusing if too many use things muck about with it.

FUNCTIONS ^

$item = $class->new ()
$item = $class->new ($str)

Create and return a new menu item widget of $class. If a $str argument is given then this behaves as new_with_mnemonic() below.

$item = $class->new_with_label ()
$item = $class->new_with_label ($str)

Create and return a new menu item widget of $class. If a $str argument is given then a Gtk2::AccelLabel child is created and added to display that string. $str should not be undef.

If there's no $str argument then new_with_label() behaves the same as plain new() and doesn't create a child widget.

$item = $class->new_with_mnemonic ()
$item = $class->new_with_mnemonic ($str)

Create and return a new menu item widget of $class. If a $str argument is given then a Gtk2::AccelLabel child is created and added to display that string. An underscore in the string becomes an underline and keyboard shortcut, eg. "_Edit" for underlined "E". $str should not be undef.

If there's no $str argument then new_with_mnemonic() behaves the same as plain new() and doesn't create a child widget.

For Gtk 2.16 and up new_with_label() simply sets the label property and new_with_mnemonic() sets the label and use-underline properties. For earlier versions an explicit Gtk2::AccelLabel creation is done as per past code in gtk_menu_item_new_with_label() and gtk_menu_item_new_with_mnemonic().

For reference, it doesn't work to re-bless the return from the MenuItem widgets from the base new_with_label() and new_with_mnemonic() into a new subclass. Doing so changes the Perl hierarchy but doesn't change the underlying C code object GType and therefore doesn't get new properties or signals from the subclass.

OTHER WAYS TO DO IT ^

When running on Gtk 2.16 the label property can be used instead of new_with_label() and so in a subclass there's no particular need to have the separate new_with_label().

    package My::MenuItem;
    use Glib::Object::Subclass 'Gtk2::MenuItem';

    # then in the application
    my $item = My::MenuItem->new (label => 'Hello');

But the benefit of Gtk2::Ex::MenuItem::Subclass is that you don't leave exposed a new_with_label() which does the wrong thing, and it can work on Gtk prior to 2.16.

SEE ALSO ^

Glib::Object::Subclass, Gtk2::MenuItem, Gtk2::CheckMenuItem

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

syntax highlighting: