/ 
math-image-28
River stage zero No dependents
/ App::MathImage::Gtk2::Ex::MenuItem::Subclass

NAME

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

SYNOPSIS

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

use App::MathImage::Gtk2::Ex::MenuItem::Subclass;
unshift @ISA, 'App::MathImage::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

This is an internal part of Math-Image and will be moved and renamed if it has wider use.

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

new
new_with_label
new_with_mnemonic

They behave the same as the base Gtk2::MenuItem methods but create a widget of the given subclass, not merely a Gtk2::MenuItem the way the wrapped C code methods do. 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 App::MathImage::Gtk2::Ex::MenuItem::Subclass;
unshift @ISA, 'App::MathImage::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 above ensures App::MathImage::Gtk2::Ex::MenuItem::Subclass is before the new from Glib::Object::Subclass and before the new_with_label and new_with_mnemonic from Gtk2::MenuItem. The effect is

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

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

# for key/value new() per plain Glib::Object
@ISA = ('Glib::Object::Subclass',
        'App::MathImage::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's 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 underscores 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.

When running on Gtk 2.16 and up new_with_label simply sets the label property and new_with_mnemonic 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.

For reference it doesn't work just to re-bless the return from the base new_with_label and new_with_mnemonic in Gtk2::MenuItem. Doing so changes the Perl hierarchy but doesn't change the underlying C code widget 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 means there's no particular need for a separate new_with_label method, simply pass the string as an argument in the usual key/value new you get from Glib::Object::Subclass.

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

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

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

SEE ALSO

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

HOME PAGE

http://user42.tuxfamily.org/math-image/index.html

LICENSE

Copyright 2010 Kevin Ryde

Math-Image 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.

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