NAME

Tk::Wizard - Wizard GUI Framework

SYNOPSIS

use Tk::Wizard;

# Instantiate a Wizard
my $wizard = new Tk::Wizard(
	-title => "A title",
	-imagepath => "/image/for/the/left/panel.gif",
);

# Create pages
my $SPLASH       	= $wizard->addPage( sub{ page_splash ($wizard)} );
my $COPYRIGHT_PAGE	= $wizard->addLicencePage( -filepath => "end_user_licence.txt" );
my $GET_PREFS    	= $wizard->addPage( sub{ page_get_prefs($wizard) });
my $user_chosen_dir;
my $GET_DIR   		= $wizard->addDirSelectPage ( -variable => \$user_chosen_dir )
my $INSTALL_FILES	= $wizard->addPage( sub{ page_install_files($wizard,$user_chosen_dir) });
my $FINISH			= $wizard->addPage( sub{ page_finish($wizard) });

$wizard->Show();
MainLoop;

sub page_get_prefs { my $wizard = shift;
	my $frame = $wizard->blank_frame(-title=>"The First Page",-text=>"This is page one...");
	# ....
	return $frame;
}

sub preNextButtonAction { my $wizard = shift;
	$_ = $wizard->currentPage;
	if (/^$SPLASH$/){
		warn "Pressed NEXT in the splash page ($SPLASH)";
		return 1;
	}
	elsif (/^$COPYRIGHT_PAGE$/){
		return $wizard->callback_licence_agreement;
	}
	elsif (/^$GET_DIR/){
		return $wizard->callback_dirSelect( \$user_chosen_dir );
	}
	# ...
}

__END__

DESCRIPTION

The Tk::Wizard module automates a large part of the creation of a wizard program to collect information and then perform some complex task based upon it. The wizard feel is largly based upon the Microsoft(TM,etc) wizard style.

The Wizard was developed to aid software installation by end-users using ActiveState's ActivePerl, but should function under under OS and circumstances. There are a number of routines specific to software installation, which may be removed to a sub-class at a later date.

THIS IS AN ALPHA RELEASE: ALL CONTRIBUTIONS ARE WELCOME!

ACTION EVENT HANDLERS

Tk::Wizard action event handlers are code-references called at the press of a Tk::Wizard button.

The handler functions should return a Boolean value, signifying whether the remainder of the action should continue. If a false value is returned, execution of the event handler halts.

All active event handlers can be set at construction or using configure - see CONSTRUCTOR (new) and "METHOD configure".

-preNextButtonAction =>

This is a reference to a function that will be dispatched before the Next button is processed.

-postNextButtonAction =>

This is a reference to a function that will be dispatched after the Next button is processed.

-prePrevButtonAction =>

This is a reference to a function that will be dispatched before the Previous button is processed.

-postPrevButtonAction =>

This is a reference to a function that will be dispatched after the Previous button is processed.

-preHelpButtonAction =>

This is a reference to a function that will be dispatched before the Help button is processed.

-helpButtonAction =>

This is a reference to a function that will be dispatched to handle the Help button action.

-postHelpButtonAction =>

This is a reference to a function that will be dispatched after the Help button is processed.

-preFinishButtonAction =>

This is a reference to a function that will be dispatched before the Finish button is processed.

-finishButtonAction =>

This is a reference to a funciton that will be dispatched to handle the Finish button action.

-postFinishButtonAction =>

This is a reference to a function that will be dispatched after the Finish button is processed.

-preCancelButtonAction =>

This is a reference to a function that will be dispatched before the Cancel button is processed. Default is to exit on user confirmation - see "METHOD DIALOGUE_really_quit".

-preCloseWindowAction =>

This is a reference to a funciton that will be dispatched before the window is issued a close command. Default is to exit on user confirmation - see "DIALOGUE METHOD DIALOGUE_really_quit".

CONSTRUCTOR (new)

Tk::Wizard->new( -name1=>"value1"...-nameN=>"valueN" )

Creates a new instance of the Tk::Wizard object as a MainWindow, or in the supplied MainWindow (see below).

Standard paramters, appyling to the MainWindow:

-width -height -background

Non-standard parameters:

-title =>

This is the title that will be displayed in the Windows title bar

-imagepath =>

Path to a JPEG file that will be displayed on the left-hand side of the screen.

-mw =>

Optionally a TK MainWindow for the Wizard to occupy. If none is supplied, one is created.

-style =>

If supplied and is top, will put the image at the top. Could do more....

-nohelpbutton =>

Set to anything to disable the display of the help buton.

Action Event Handlers:

See "ACTION EVENT HANDLERS" for details.

All paramters can be set after construction using configure - see "METHOD configure".

As the Tk::Wizard object also controls the Next and Previous buttons, you can set the configuration - use the cancelButtonRef and prevButtonRef object fields:

$wizard->{prevButtonRef}->configure( -state => "disabled" )

The default font is created by the constructor as 8pt Verdana, named DEFAULT_FONT and placed in the object's defaultFont field. All references to the default font in the Wizard call this routine, so changing the default is easy.

Privately, licence_agree flags whether the end-user licence agreement has been accepted.

METHODS

METHOD configure

Allows the configuration of all object properties.

METHOD addPage

$wizard->addPage ($page_code_ref)

This method is used to add a Wizard page to the wizard. The $page parameter must be a Tk::Frame object. The pages are stored and will be displayed in the order that they were added to the Wizard control.

METHOD Show

C<wizard>->Show()

This method must be dispatched before the Wizard will be displayed, and must preced the MainLoop call.

METHOD currentPage

my $current_page = $wizard->currentPage()

This returns the index of the page that is currently shown. Pages are indexed starting at 1 with the first page that is associated with the wizard through the addWizardPage method.

METHOD parent

my $parent_window = C<wizard>->parent

This returns areference to the parent Tk widget that was used to create the wizard and all of the controls. By default, returns a reference to the main window.

Defined at construction - see CONSTRUCTOR (new)..

METHOD blank_frame

my ($frame,@packing) = C<wizard>->blank_frame(-title=>$title,-text=>$standfirst);

Returns a Tk::Frame object that is a child of the Wizard control. Some padding parameters are applied to the frame by the wizard control;

Arguments are name/value pairs:

-title =>

Printed in a big, bold font at the top of the frame as a title

-text =>

Printed under the title in standard font.

Also:

-width -height -background -font

METHOD addLicencePage

$wizard->addLicencePage ( -filepath => $path_to_licence_text )

Adds a page that contains a scroll texxt box of a licence text file specifed in the -filepath argument. Presents the user with two options, accept and continue, or not accept and quit. The user cannot progress until the 'agree' option has been chosen.

You could supply the GNU Artistic Licence....

See "CALLBACK callback_licence_agreement" and "METHOD page_licence_agreement".

METHOD addDirSelectPage

$wizard->addDirSelectPage ( -variable => \$chosen_dir )

Adds a page that contains a scroll texxt box of all directories including, on Win32, logical drives. You can also specify the -title and -text paramters, as in "METHOD blank_frame".

See "CALLBACK callback_dirSelect".

CALLBACK callback_licence_agreement

Intended to be used with an action-event handler like -preNextButtonAction, this routine check that the object field licence_agree is a Boolean true value. If that operand is not set, it warns the user to read the licence; if that operand is set to a Boolean false value, a message box says goodbye and quits the program.

CALLBACK callback_dirSelect

A callback to check that the directory, passed as a reference in the sole argument, exists, and can and should be created.

Will not allow the Wizard to continue unless a directory has been chosen. If the chosen directory does not exist, Setup will ask if it should create it. If the user affirms, it is created; otherwise the user is again asked to chose a directory.

Returns a Boolean value.

DIALOGUE METHOD DIALOGUE_really_quit

The default routine called when the user clicks Cancel or attempts to close the window (-preCancelButtonAction and -preCloseWindowAction). Justs asks 'Are you sure?' Calls exit if they are.

DIALOGUE METHOD prompt

Equivalent to the JavaScript method of the same name: pops up a dialogue box to get a text string, and returns it. Arguemnts are:

-parent =>

Tk object that is our parent window. Default's to our parent field.

-title =>

The title of the dialogue box.

-text =>

The text to display above the Entry widget.

-value =>

The initial value of the Entry box.

-wraplength =>

Text Label's wraplength: defaults to 275.

-width =>

The Entry widget's width: defaults to 40. =back

LEGACY METHOD wpFrame

my $frame = C<wizard>->wpFrame;

Returns a Tk::Frame object that is a child of the Wizard control. It should be used when creating wizard pages since some padding parameters are applied to it by the wizard control.

CAVEATS / BUGS

• Nothing is currently done to ensure text fits into the window - it is currently up to the client to make frames Scrolled), as I'm having problems making &blank_frame produce them.

• Dimenions are not yet fixed - more of my novice Tk problems!

• When The New Directory button in the addDirSelectPage method is used to create a new directory, the DirTree object does not open the branch. How can it?

• If a Wizard is one page long, the FINISH button will not appear as expected.

CHANGES

VERSION 1.01

• Made the supply of a MainWindow to the constructor optional, and changed the supply method from a reference to part of the passed name/value list.

• Changed filename field to -imagepath for readability.

• Made all arguments begin with - to fit in with Tk "switches".

• Added method blank_frame that can take title and standfirst text.

• Added a bit of space between the Wizard body and the button footer.

• Added default font and background.

• Added licence agreement bits.

VERSION 1.0

Initial version by Daniel T Hable, found with Google, at http://perlmonks.thepen.com/139336.html.

AUTHOR

Daniel T Hable,

Lee Goddard (lgoddard@cpan.org).

COPYRIGHT

Copyright (c) 2002 Daniel T. Hable.

Modifications Copyright (C) Lee Goddard, 2002.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

cpanm Tk::Wizard

perl -MCPAN -e shell
install Tk::Wizard