NAME

Tk::Wizard - GUI for step-by-step logical process

SYNOPSIS

use Tk::Wizard;
my $wizard = new Tk::Wizard(
	-title		=> "TitleBar Title",
	-imagepath	=> "/image/for/the/left/panel.gif",
);
$wizard->configure( ...add event handlers... );
$wizard->cget( ...whatever... );
$wizard->addPage(
	... code-ref to anything returning a Tk::Frame ...
);
$wizard->addPage( sub {
	return $wizard->blank_frame(
		-title	=> "Page Title",
		-text	=> "Stand-first text.",
	);
});
$wizard->Show;
MainLoop;
__END__

To avoid 50 lines of SYNOPSIS, please see the file test.pl included with the distribution.

DEPENDENCIES

Tk and modules of the current standard Perl Tk distribution.

On MS Win32 only: Win32API::File.

And if you plan to use the method register_with_windows (available on MsWin32 only), you'll need Win32::TieRegistry.

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 was developed to aid software installation by end-users using ActiveState's ActivePerl, but should function under other OS and circumstances. There package does contain a number of routines specific to software installation: these may be removed to a sub-class at a later date.

The wizard feel is largly based upon the Microsoft(TM,etc) wizard style: the default is simillar to that found in Microsoft Windows 95; a more Windows 2000-like feel is also supported (see the -style entry in "WIDGET-SPECIFIC OPTIONS".

THIS IS AN ALPHA RELEASE: ALL CONTRIBUTIONS ARE WELCOME!

STANDARD OPTIONS

-title -background -width -height

See the Tk::options manpage for details of the standard options.

Name: style

Class: ""

Switch: -style

Sets the display style of the Wizard.

The default 95 value creates a traditional, Windows 95-style wizard, with every page being SystemButtonFace coloured, with a large image on the left (-imagepath, below).

A value of top, the Wizard will be more of a Windows 2000-like affair, with the initial page being a white-backgrounded version of the traditional style, and subsequent pages being SystemButtonFace coloured, with a white strip at the top holding a title and subtitle, and a smaller image (-topimagepath, below>.

Name: imagepath

Class: ""

Switch: -imagepath

Path to an image file that will be displayed on the left-hand side of the screen. Dimensions are not been restrained (yet).

Notes:

This is a Tk::Photo object without the format being specified - this has been tested only on GIF and JPEG.
No checking is done, but paths ought to be absolute, as no effort is made to maintain or restore any initial current working directory.
The supplied images setup_blue.gif and setup_blue_top.gif are used by default. If you supply others you will probably have to set the Wizard's -width and -height properties, as there is (currently) no image-sized checking performed.

Name: topimagepath

Class: ""

Switch: -topimagepath

Only required if -style='top'> (as above): the image this filepath specifies will be displayed in the top-right corner of the screen. Dimensions are not restrained (yet), but only 50px x 50px has been tested.

Please see notes the -imagepath entry, above.

Name: nohelpbutton

Class: ""

Switch: nohelpbutton

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

Please see also "ACTION EVENT HANDLERS".

METHOD addPage

$wizard->addPage ($page_code_ref1 ... $page_code_refN)

Adds a page to the wizard. The parameters must be references to code that evaluate to Tk::Frame objects, such as those returned by the methods blank_frame, addLicencePage and addDirSelectPage.

Pages are (currently) stored and displayed in the order added.

Returns the index of the page added, which is useful as a page UID when peforming checks as the Next button is pressed (see file test.pl supplied with the distribution).

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 currently being shown to the user. Page are indexes start at 1, with the first page that is associated with the wizard through the addPage method.

See "METHOD addPage".

METHOD parent

my $apps_main_window = $wizard->parent;

This returns a reference to the parent Tk widget that was used to create the wizard. Returns a reference to the Wizard's MainWindow.

METHOD blank_frame

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

Returns a Tk::Frame object that is a child of the Wizard control, with some packing parameters applied - for more details, please see -style entry elsewhere in this document.

Arguments are name/value pairs:

-title =>: Printed in a big, bold font at the top of the frame as a title
=subtitle =>: Subtitle/standfirst.
-text =>: Main body text.

Also:

-width -height -background -font

METHOD addLicencePage

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

Adds a page (Tk::Frame) 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. The choice is entered into the object field licence_agree, which you can test as the Next button is pressed, either using your own function or with the Wizard's callback_licence_agreement function.

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 (Tk::Frame) that contains a scrollable texxt box of all directories including, on Win32, logical drives.

Supply in -variable a reference to a variable to set the initial directory, and to have set with the chosen path.

Supply -nowarnings to list only drives which are accessible, thus avoiding Tk::DirTree warnings on Win32 where removable drives have no media.

You may also specify the -title, -subtitle 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.

This method relies on Win32API::File on MS Win32 machines only.

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

METHOD register_with_windows

Registers an application with Windows so that it can be Uninstalled using the Add/Remove Programs dialogue.

An entry is created in the Windows' registry pointing to the uninstall script path. See uninstall_string, below.

Returns undef on failure, 1 on success.

Aguments are:

display_name =>

The string displayed in bold in the Add/Remove Programs dialogue.

display_version =>

Optional: the version number displayed in the Add/Remove Programs dialogue.

uninstall_key_name

The name of the registery sub-key to be used.

uninstall_string

The command-line to execute to uninstall the script.

According to Microsoft:

You must supply complete names for both the DisplayName and UninstallString
values for your uninstall program to appear in the Add/Remove Programs
utility. The path you supply to Uninstall-String must be the complete
command line used to carry out your uninstall program. The command line you
supply should carry out the uninstall program directly rather than from a
batch file or subprocess.

The default value is:

perl -e '$args->{app_path} -u'

This default assumes you have set the argument app_path, and that it checks and reacts to the the command line switch -u:

package MyInstaller;
use strict;
use Tk::Wizard;
if ($ARGV[0] =~ /^-*u$/i){
	# ... Have been passed the uninstall switch: uninstall myself now ...
}
# ...

Or something like that.

Note: this method uses eval to require Win32::TieRegistry.

This method returns 1 and does nothing on non-MSWin32 platforms.

ACTION EVENT HANDLERS

A Wizard is a series of pages that gather information and perform tasks based upon that information. Navigated through the pages is via Back and Next buttons, as well as Help, Cancel and Finish buttons.

In the Tk::Wizard implimentation, each button has associated with it one or more action event handlers, supplied as code-references executed before, during and/or after the button press.

The handler code 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.

-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.
-preBackButtonAction =>: This is a reference to a function that will be dispatched before the Previous button is processed.
-postBackButtonAction =>: 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.
-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".

All active event handlers can be set at construction or using configure - see "WIDGET-SPECIFIC OPTIONS" and "METHOD configure".

BUTTONS

backButton nextButton helpButton cancelButton

If you must, you can access the Wizard's button through the object fields listed above, each of which represents a Tk::BUtton object.

This is not advised for anything other than disabling or re-enabling the display status of the buttons, as the -command switch is used by the Wizard:

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

Note: the Finish button is simply the nextButton with the label $LABEL{FINISH}.

INTERNATIONALISATION

The labels of the buttons can be changed (perhaps into a language other an English) by changing the values of the package-global %LABELS hash, where keys are BACK, NEXT, CANCEL, HELP, and FINISH.

The text of the licence agreement page and callbacks can also be changed via the %LABELS hash: see the top of the source code for details.

CAVEATS / BUGS / TODO

In Windows, with the system font set to > 96 dpi (via Display Properties / Settings / Advanced / General / Display / Font Size), the Wizard will not display propertly. This seems to be a Tk feature.
Still not much of a Tk widget inheritance - any pointers welcome.
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.

CHANGES

Please see the file CHANGES.txt included with the distribution.

AUTHOR

Lee Goddard (lgoddard@cpan.org) based on work Daniel T Hable.

KEYWORDS

Wizard; set-up; setup; installer; uninstaller; install; uninstall; Tk; GUI.

COPYRIGHT

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.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 969:: You forgot a '=back' before '=head2'

To install Tk::Wizard, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Tk::Wizard

CPAN shell

perl -MCPAN -e shell
install Tk::Wizard

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DEPENDENCIES

DESCRIPTION

STANDARD OPTIONS

WIDGET-SPECIFIC OPTIONS

METHOD addPage

METHOD Show

METHOD currentPage

METHOD parent

METHOD blank_frame

METHOD addLicencePage

METHOD addDirSelectPage

CALLBACK callback_licence_agreement

CALLBACK callback_dirSelect

DIALOGUE METHOD prompt

METHOD register_with_windows

ACTION EVENT HANDLERS

BUTTONS

INTERNATIONALISATION

CAVEATS / BUGS / TODO

CHANGES

AUTHOR

KEYWORDS

COPYRIGHT

Module Install Instructions