# Copyright (c) 1999 by Greg London. All rights reserved.
# Permission is granted to reprint this file, Text_menu.readme, 
# as long as it is reprinted in its entirety.

# please send corrections, ammendments, questions to:
# greg42@bellatlantic.net

####

Popup menus are new to the Text.pm and TextUndo.pm modules.
This readme attempts to explain different ways for 
you to override the default menus in Tk::Text and Tk::TextUndo.


The two main solutions are to create a subclass or
to modify the menu on a per-instance basis

####

Subclassing:
============

You can create a subclass of Text.pm and override the menu methods
as you wish.

#####################################################################
package MyText;
use Tk qw (Ev);
use Autoloader;
use base qw(Tk::Text); # or substitute Text with TextUndo etc
Construct Tk::Widget 'MyText';

# add this sub to complete disable popup menus
sub ClassInit
{
 my ($class,$mw)=@_;
 $class->SUPER::ClassInit($mw);
 $mw->bind($class, <3>, sub{});   # do this to totally disable popup menus
 return $class;
}

# example of how to add menu items to already existing menu pulldown
sub FileMenuItems
{
 my ($w)=@_;
 return 
  [
        # add a method to File pulldown
          ["command'=>'Twiddle', -command=>sub{$w->twiddle_method}],  
        # keep the current File menu items
         "-", @{$w->SUPER::FileMenuItems} 
  ]);

#example of how to override existing menu pulldown
sub EditMenuItems
{
 my ($w)=@_;
 return 
  [
        # redefine Edit pulldown menu to contain just "Spindle" item.
          ["command'=>'Spindle', -command=>sub{$w->spindle_method}],
  ]);


# example of how to add a pulldown to existing menus.
sub InitObject
{
 my($w)=@_;
 $w->SUPER::InitObject;

 # get base class menu bar
 my $menu = $w->SUPER::menu;

 # add another pulldown to the existing menu
 $menu->cascade(-label=>'-Help', -menuitems => 
        [
        [Command => 'A~bout', -command=>\&help_about],
        [Command => 'Info', -command=>\&help_info],
        ]);
}

#####################################################################


Per-Instance solution:
=======================

if you do not want to create a sub-class, you can instantiate an
already existing widget, get a reference to its menu with ->menu,
and then modify the menu contents for that widget.


an example of adding to default menus on a per-widget basis:

####

my $text=$mw->Text;

my $menu = $text->menu;

# and then add new menu items to $menu.

$menu->cascade(-label=>'-Help', -menuitems => 
        [
        [Command => 'A~bout', -command=>\&help_about],
        [Command => 'Info', -command=>\&help_info],
        ]);

#############################################################


an example of completely overriding the default menus on a per-widget basis:

####

my $menu->cascade(-label=>'-Help', -menuitems => 
        [
        [Command => 'A~bout', -command=>\&help_about],
        [Command => 'Info', -command=>\&help_info],
        ]);

my $text=$mw->Text;

$text->menu($menu);



####


if you wish to disable the pop-up menu on a per-instance basis,
you can pass the ->menu method an undef value 


####

$text->menu(undef);	# disable popup menu via the ->menu method


####

or you can do it the hard way and bind the mouse button <3> to an empty subroutine.


$text->bind('<3>', sub{} );

You can invoke a do-nothing subroutine or a method of your own design.
You may also need to end your callback subroutine with ->break
so that no other bindings are called (class level, etc).

$text->bind('<3>', sub{ $text->break; } );

To override the binding on a specific text instance, you will need to 
re-prioritize the bindings on that widget to first 
perform per-widget bindings, and then perform class bindings.

$text_widget->bindtags(
        [$text_widget, ref($text_widget), $text_widget->toplevel, 'all']
        );

this then allows the instance binding 
        $text->bind('<3>', sub{} );
to override the class binding.

one wrinkle may occur if $text is a scrolled text widget.
a scrolled widget requires that you access the text subwidget first
before you can ->bindtags it.

$text->bind('<3>', sub{ $text->break; } );

my $text_subwidget = $scrolled_text->Subwidget('scrolled');

$text_subwidget -> bindtags ( [
        $text_subwidget,
        ref($text_subwidget),
        $text_subwidget->toplevel,
        'all' ]);


###########

The latest version of the widget demo contains a text demo
which implements a number of menuing features. you can look
at this code for an example of how to modify menus for your
own applications.

there is also a gedi application which is a stand alone implementation
of a full-fledged text editor. This application should be included
in the Tk tar-kit, although where exactly it gets installed will
depend on your system.

please feel free to send questions or comments to:

greg42@bellatlantic.net

Enjoy,
Greg London





####

I hope you find this information useful.
Please feel free to send questions or comments to me at:

greg42@bellatlantic.net

Thanks,
Greg London