The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Puppet-Any-0.04
++
/ Puppet::Any

NAME

Puppet::Any - Common base class for lab development tools

SYNOPSIS

 use Puppet::Any ;

 package myClass ;

 @myClass::ISA=('Puppet::Any') ;

 package main ;
 my $file = 'test.db';
 my %dbhash;
 tie %dbhash,  'MLDBM',    $file , O_CREAT|O_RDWR, 0640 or die $! ;

 my $test = new myClass (name => 'test',
                           dbHash => \%dbhash,
                           keyRoot => 'key root'
                          );

 $test->display;
 $test->setDbInfo(toto => 'toto val', 
                 'titi' => 'titi val',
                dummy => 'null') ;

 $test->deleteDbInfo('dummy');

 MainLoop ; # Tk's

 untie %dbhash ;

DESCRIPTION

Puppet::* classes are designed to provide an access to the "puppeted" object using a GUI based on Tk.

The basic idea is when you construct a Puppet::* object, you have all the functionnality of the object without the GUI. Then, when the need arises, you may (or the class may decide to) open the GUI of the object and then the user may perform any interactive he wishes.

On the other hand, if the need does not arise, you may instanciate a lot of objects without cluttering your display.

For instance, if you have an object (say a ProcessGroup) controlling a set of processes (Process objects). The user may start the ProcessGroup through its GUI. Then all processes are run. If one of them fails, it will raise its own GUI to display the cause of the problem and let the user decide what to do.

This class named Puppet::Any is the base class inherited by all other Puppet classes. In this example, Process and Process group both will inherit Puppet::Any.

The base class features : - A Tk::Multi::Manager to show or hide the different display of the base class (or of the derived class) - A menu bar - An event log display so derived object may log their activity - A Debug log display so derived object may log their "accidental" activities - An Object Scanner to display the attribute of the derived object - A set of functions to managed "has-a" relationship between Puppet objects. The menu bar feature a "content" bar which enabled the user to open the display of all "contained" objects. - a facility to store data on a database file tied to a hash.

The class is designed to store its data in a SINGLE entry of the database file. (For this you should use MLDBM if you want to store more than a scalar in the database). The key for this entry is "$keyRoot;$name". keyRoot and name being passed to the constructor of the object. Needless to say, it's a bad idea to create two instances of Puppet::WithDb with the same keyRoot and name.

default bindings

<Meta-d> is bound to pop-up a Tk object scanner widget. This will be handy to debug the child class you're going to develop.

DEFAULT WINDOWS

debug log window

This log window (see Puppet::Log(3)) will get all debug information for this instance of the object. More or less reserved for developers of children of Puppet::Any.

Users object inheriting from Puppet::Any must use the printDebug() method to log debug info in this window.

event log window

This log window (see Puppet::Log(3)) will get all event information for this instance of the object.

Users object inheriting from Puppet::Any must use the printEvent() method to log debug info in this window. =head1 Object attributes

name

name of the instance. No treatment or special signification to it except that it can be handy for the debug.

content

Hash containing the reference of all acquired objects ('name' => ref).

topTk

Reference of the Tk main window.

log

hash array which contains 'event' and 'debug' Puppet::Log objects. Do not squash it.

tk

Hash containing the following keys :

 - toplevel: toplevel window ref of this object.
 - menubar: Frame containing the menu buttons. (you may call MenuButton on it)
 - contentMnb: ref to the menu managing content (private)
 - menu: hash containing menu widgets. ('File' for instance) 
  ( you may call command on
   $self->{tk}{menu}{'File'} to define a new command in the menu for instance)
 - multiMgr Tk::Multi::Manager buddy ref.

When the closeDisplay method is called, it will destroy $self->{tk}{toplevel}, thus it will destroy all Tk widgets and then it will delete the $self->{tk} hash, thus it will delete all internal reference to the destroyed widgets. So you can also test whether your widget has a display by testing if $self->{tk} is defined.

The sub-class MUST abide to this rule if the closeDisplay is to work properly.

dbHash

Tied hash to the database.

keyRoot

First part of the key to access the database

myDbKey

The key to access the database

Methods

new( ... )

Creates new Puppet object.

parameters are : - name - topTk (optionnal, will create a MainWindow if ommitted) - keyRoot - dbHash: ref of the tied hash

Note that all other arguments are passed to the Puppet::Log constructors. I.e. you can also specify arguments specific to Puppet::Log->new() through Puppet::Any->new() function.

acquire(a_name, a_ref)

Acquire the object ref as a child. a_ref must be an object derived of Puppet::Any.

Each acquired object must have different names.

drop('name')

Destroy child 'name'.

display()

defines a top level display for each object, contains a MultiText ,a manager and a objScanner.

<Meta-d> will create an object scanner to scan this object.

A debug and an events log objects (Puppet::Log) are created for use by the child class

Return 1 if a display is actually created. 0 otherwise (i.e is the display already exists).

When overloading display, you may write you function like this :

 sub display
  {
    my $self = shift ;
    return unless $self->SUPER::display(@_ );

 ...
 }

So the display instruction you add will be run only when creating the display.

closeDisplay

Close the display. Note that the display can be re-invoked later.

printDebug(text)

Will log the passed text into the debug log object.

printEvent(text)

Will log the passed text into the events log object.

showEvent(text)

Will display the 'event' log window.

storeDbInfo( key => value, ...)

Store the passed hash in the database. You may also pass a hash ref as single argument.

deleteDbInfo( key, ...)

delete the "key" entries from the database.

AUTHOR

Dominique Dumont, Dominique_Dumont@grenoble.hp.com

Copyright (c) 1998 Dominique Dumont. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

perl(1), Tk(3), Puppet::Log(3)