/ 
Gtk2-Ex-WidgetBits-34
River stage two • 12 direct dependents • 12 total dependents
/ Gtk2::Ex::MenuItem::Subclass

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 given 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 in application code create a My::MenuItem widget with

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

$item is created as a My::MenuItem, as the call would suggest. 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 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/.