NAME
       Tk::ObjectHandler - Perl extension for Tk

SYNOOPSIS
         use Tk::ObjectHandler;
         my $tk = Tk::ObjectHandler->new();
         $tk->add_widget("Button","but1", -text, "Press Me", -command => sub{ $tk->destroy(); });
         $tk->but1->pack(-fill => "both");
         $tk->Loop;


ABSTRACT
       Tk::ObjectHandler provides an automated method for
       creating, ordering and cataloging the variables used to
       hold Tk widgets. Rather than having to use a confusing
       number of individual holders ObjectHandler arranges the
       widgets so that widgets that are packed onto a parent
       widget are called via the parent widget.

DESCRIPTION
       Creating a program in Tk can sometimes become confusing
       due to the number of variables needed to hold pointers to
       widgets. Tk::ObjectHandler is an attempt to provide a
       generic method for providing a logical heirarchy for
       widgets, allowing easy reference through one entrance
       point.

       When created, the Tk::ObjectHandler object sets up a
       Tk::Toplevel widget and wraps it in it's own
       administration code. This code allows you to set up a
       heirarchy of widgets all accessable through one entry
       point. For example, imagine a simple report window, say
       with a couple of labels and a close button.  In
       traditional Tk you would create these like the following:

               my $mw = new MainWindow();
               my $label1 = $mw->Label(-text => 'Title text');
               my $label2 = $mw->Label(-text => 'Body text of the message window');
               my $button = $mw->Button(-text => 'Close', -command => sub { $mw->destroy; });
               $label1->pack();
               $label2->pack();
               $button->pack();

       Using ObjectHandler, there is only one variable used:

               my $mw = Tk::ObjectHandler->new();
               $mw->add_widget('Label', 'Label1', -text => 'Title text');
               $mw->add_widget('Label', 'Label2', -text => 'Body text of the message window');
               $mw->add_widget('Button', 'button', -text => 'Close', -command => sub { $mw->destroy; });
               $mw->Label1->pack();
               $mw->Label2->pack();
               $mw->button->pack();

       So, what is the difference? Well, in the example above,
       not much really, but in larger programs the number of
       variables required can become hard to keep track of
       leading to duplication and slowing development time while
       you play 'hunt the variable'. ObjectHandler overcoes this
       problem in two ways. First, objects are refered to in a
       structured format, you can only refer to a widget through
       its parent, like below:

               $mw->frame->label1->configure(...)

       ...would configure the widget label1 that is attatched to
       the frame that is attatched to the main window.

       Using this heirarcal method of naming means that you can
       use the following as valid widget names:

               $mw->frame1->label1...
               $mw->frame2->label1...
               $mw->frame3->label1...
               $mw->frame4->label1...

       ...which can save wear and tear on the brain when thinking
       of variable names ;)

       The second method in which ObjectHandler helps is with
       it's self-documenting code. Using the report method you
       can automatically generate reports on the widgets and sub
       widgets (and sub-sub widgets etc) of the whole program or
       any section thereof. As well as names and widget types,
       ObjectHandler also allows you to inser comments into the
       tree.

CONSTRUCTOR
       new([ARGS])
           New initiates the ObjectHandler and creates a standard
           Tk::Toplevel widget. See Tk::TopLevel for ARGS.

METHODS
       $obj->add_widget(type, name[, ARGS])
           Add widget creates an object of the type type and adds
           it as a sub object of the object $obj with a name
           name. In other words:

                   $obj->add_widget('Frame', 'Frame1');

           Creates a frame widget under $obj that can be accessed
           by $obj->Frame1:

                   $obj->Frame1->add_widget('Label', 'L1', -text => 'This is a test');

           This would create another widget, a label this time,
           under the Frame1 frame and give it the text 'This is a
           test'. For a description of ARGS see the perldoc or
           manpage for the widget you wish to create.

       $obj->comment([text])
           If called with an argument this method attatches the
           argument to the object. If called without an argument
           it returns any existing argument. This comment is
           included in the widget report. See report below.

       $obj->report()
           This method returns a string containing a report of
           the current widget and all widgets below it. Included
           for each widget is it's name, it's type and any
           comment attatched to it with the $obj-comment> method.
           This is a documentation tool, allowing for a simple
           method to describe the structure of your program. A
           sample report is as follows:

           Structural layout of snake.pl

           MainWindow reportwin - Tk::Toplevel
            title - Tk::Label
            text - Tk::Label
            close - Tk::Button

            field - Tk::Canvas
             score - Tk::Frame
             snake_length - Tk::Label
             score - Tk::Label
             l1 - Tk::Label
             l3 - Tk::Label

             message - Tk::Frame
              messages - Tk::Label

             menu - Tk::Frame                      This  comment could describe
                                                   this menubar, telling us about the
                                                   buttons.
              help - Tk::Menubutton
              game - Tk::Menubutton
              rep - Tk::Menubutton




       $obj->getobj()
           This returns the windget in Tk form. This is intended
           for use with things like fonts, etc, that are included
           as arguments in other widgets.

STANDARD TK COMMANDS
       All commands that a widget could normally use can still be
       used by a widget created with object handler.  Grid, pack,
       configure etc are accessed in the normal way,
       $mw->widget->configure() for example.

AUTHOR
       Simon Parsons caillte@ityen.freeserve.co.uk

COPYRIGHT
       Copyright (C) 2001-2002, Simon Parsons.  This module is
       distributed under the terms and conditions of the GNU
       public licence and the Perl Artistic Licence

SEE ALSO
       perl(1), Tk.

TODO
       Add variable storage to the object heirarchy.
       Copy and Move commands for quick propogation of widgets.