NAME

Tk::Program - MainWindow Widget with special features.

SYNOPSIS

use Tk;
use Tk::Program;

my $top = Tk::Program->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::Program 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

BINDINGS

Double-Escape: Exit the Programm

CHANGES

$Log: Program.pm,v $
Revision 1.7  2003/06/20 13:53:18  xpix
! wrong english in font dialog ;-)

Revision 1.6  2003/06/20 12:52:27  xpix
! change from Tk::Pod to standart way with ROText

Revision 1.5  2003/06/06 16:48:11  xpix
* add toolbar function
! liitle bugfix in change font

Revision 1.4  2003/06/06 12:56:03  xpix
* correct docu, thanks on susy ;-)

Revision 1.3  2003/06/05 15:32:26  xpix
* with new Module Tk::Program
! unitialized values in tm2unix

Revision 1.2  2003/06/05 12:51:56  xpix
! add better docu
* add help function

Revision 1.1  2003/06/04 17:14:35  xpix
* New Modul for standart way to build a Programwindow.

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::Program

perl -MCPAN -e shell
install Tk::Program