NAME

Tk::ObjectHandler - Perl extension for Tk

SYNOPSIS

  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.