NAME

Tk::ApplicationNest - MainWindow Widget with special features.

SYNOPSIS

        use Tk;
        use Tk::ApplicationNest;
        
        my $top = Tk::ApplicationNest->new(
                -app => 'xpix',
                -cfg => './testconfig.cfg',
                -set_icon => './icon.gif',
                -set_logo => './logo.gif',
                -about => \$about,
                -help => '../Tk/Program.pm',
                -add_prefs => [
                        'Tools',
                        ['acrobat', '=s', '/usr/local/bin/acroread',
                        { 'subtype' => 'file',
                        'help' => 'Path to acrobat reader.'
                        } ],
                ],
        );
        
        MainLoop;

DESCRIPTION

This is a megawidget to display a program window. I was tired of creating menues, prefs dialogues, about dialogues,... for every new application..... I searched for a generic way wrote this module. This modules stores the main window's font, size and position and embodies the fucntions from the Tk::Mainwindow module.

WIDGET-SPECIFIC OPTIONS

-app => $Applikation_Name

Set a Application name, default is Program

-set_icon => $Path_to_icon_image

Set a Application Icon, please give this in 32x32 pixel and in gif format.

-cfg => $path_to_config_file;

Set the path to the config file, default:

   $HOME/.$Application_Name.cfg

-add_prefs => $arrey_ref_more_prefs or $path_to_cfg_file;

This allows to include your Preferences into default:

   -add_prefs => [
          'Tools',
           ['acrobat', '=s', '/usr/local/bin/acroread',
           { 'subtype' => 'file',
            'help' => 'Path to acrobat reader.'
           } ],
   ],

Also you can use a config file as parameter:

   -add_prefs => $path_to_cfg_file;

-set_logo => $image_file;

One logo for one program This picture will be use from the Splash and About Method. Carefully, if not defined in the Splash then an error is returned.

-help => $pod_file;

This includes a Help function as a topwindow with Poddisplay. Look for more Information on Tk::Pod. Default is the program source ($0).

METHODS

These are the methods you can use with this Widget.

$top->init_prefs( $prefs );

This will initialize the user or default preferences. It returns a reference to the options hash. More information about the prefsobject look at Tk::Getopt from slaven. The Program which uses this Module has a configuration dialog in tk and on the commandline with the following standard options:

Geometry: Save the geometry (size and position) from mainwindow.

Font: Save the font from mainwindow.

Color: Save the color from mainwindow.

In the Standard menu you find the preferences dialog under File - Prefs.

I.E.:

        my $opt = $top->init_prefs();
        print $opt->{Geometry};
        ....

$top->prefs();

Display the Configuration dialog.

$top->set_icon( $path_to_icon );

Set a new Icon at runtime.

$top->set_logo( $path_to_logo );

Set a new Logo at runtime.

$top->init_menu( $menuitems );

Initialize the user or default Menu and return the Menuobject. You can set your own menu with the first parameter. the other (clever) way: you add your own menu to the standart menu. I.E:

        # New menu item
        my $edit_menu = $mw->Menu();
        $edit_menu->command(-label => '~Copy', -command => sub{ print "Choice Copy\n" });
        $edit_menu->command(-label => '~Cut', -command => sub{ print "Choice Cut\n" });
        # ....
        
        my $menu = $mw->init_menu();
        $menu->insert(1, 'cascade', -label => 'Edit', -menu => $edit_menu);

$top->splash( $milliseconds );

Display the Splashscreen for (optional) x milliseconds. The -set_logo option is required to initialize with a Picture. Also you can use this as Switch, without any Parameter:

        $top->splash(); # Splash on
        ....
        working
        ...
        $top->splash(); # Splash off

$top->config( Name, $value );

You have data from your widgets and you will make this data persistent? No Problem:

        $top->config( 'Info', $new_ref_with_importand_informations )
        ...
        my $info = $top->config( 'Info' );      

$top->add_status( $name, \$value or \$widget );

Display a Status text field or a widget in the status bar, if you first call add_status then will Tk::ApplicationNest create a status bar:

        my $widget = $mw->init_status()->Entry();
        $widget->insert('end', 'Exampletext ....');
        
        my $status = {
                One => 'Status one',
                Full => 'Full sentence ....',
                Time => sprintf('%d seconds', time),
                Widget => $widget, 
        };
        
        # Add Status fields
        foreach (sort keys %$status) {
                $mw->add_status($_, \$status->{$_}) ;
        }

$top->add_toolar( $typ, $options );

Display the ToolbarWidget at first call and include the Widget ($typ) with options ($options):

        # Add Button to toolbar
        $mw->add_toolbar('Button', 
                -text  => 'Button', 
                -tip   => 'tool tip', 
                -command => sub { print "hi\n" });
        $mw->add_toolbar('Label', -text  => 'Label');
        $mw->add_toolbar('separator');

Look for more Information on Tk::ToolBar.

$top->exit( );

Close the program, you can include your code (before call the exit command) with:

        ...
        $mw->configure(-exit_cb => sub{ .... })
        $mw->exit;

ADVERTISED WIDGETS

You can use the advertise widget with the following command '$top->Subwidget('name_from_adv_widget')'.

menu: Menubar

main: Mainframe

status: Statusframe

status_name: StatusEntry from $top->add_status

toolbar: Toolbar, if created

BINDINGS

Double-Escape: Exit the Programm

CHANGES

  $Log: ApplicationNest.pm,v $
  Revision 1.1  2003/11/06 17:55:04  xpix
  * new Modulname Tk::ApplicationNest
  - little bug fixes and doku changes

  Revision 1.10  2003/08/18 11:26:39  xpix
  * better debug routine

AUTHOR

Copyright (C) 2003 , Frank (xpix) Herrmann. All rights reserved.

http://xpix.dieserver.de

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

KEYWORDS

Tk, Tk::MainWindow

cpanm Tk::ApplicationNest

perl -MCPAN -e shell
install Tk::ApplicationNest