Tk::Wizard::Installer - building-blocks for a software install wizard
use Tk::Wizard::Installer; my $wizard = new Tk::Wizard::Installer( -title => "Installer Test", ); $wizard->addDownloadPage( -wait => undef, #-on_error => sub { ... }, -no_retry => 1, -files => { 'http://www.cpan.org/' => './cpan_index1.html', 'http://www.cpan.org/' => './cpan_index2.html', 'http://www.leegoddard.net' => './author.html', }, ); $wizard->addPage( sub { return $wizard->blank_frame( -title=>"Finished", -subtitle => "Please press Finish to leave the Wizard.", -text => "" ); }); $wizard->Show; MainLoop;
This module makes the first moves towards a Tk::Wizard extension to automate software installation, primarily for end-users, in the manner of InstallShield.
Tk::Wizard
If you are looking for a freeware software installer that is not dependent upon Perl, try Inno Setup - http://www.jrsoftware.org/. It's so good, even Microsoft have been caught using it.
http://www.jrsoftware.org/
Tk::Wizard; Tk::ProgressBar; Tk::LabFrame;
Tk::Wizard::Installer supports all the methods and means of Tk::Wizard plus those listed in the remainder of this document.
Tk::Wizard::Installer
$wizard->addLicencePage ( -filepath => $path_to_licence_text )
Adds a page (Tk::Frame) that contains a scroll text box of a licence text file specifed in the -filepath argument. Presents the user with two options: accept and continue, or don't accept and quit. The user cannot progress until the former 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.
Tk::Frame
-filepath
licence_agree
callback_licence_agreement
You could supply a copy of the licence that comes with Perl.
See "CALLBACK callback_licence_agreement" and "METHOD page_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.
-preNextButtonAction
See "METHOD adddirSelectPage" in TK::Wizard.
$wizard->addFileListPage ( name1=>value1 ... nameN=>valueN )
Adds a page (Tk::Frame) that a contains a progress bar (Tk::ProgressBar) which is updated as a supplied list of files is copied or mvoed from one location to another.
Tk::ProgressBar
The Next and Back buttons of the Wizard are disabled whilst the process takes place.
The two arguments (below) -to and -from should be references to arrays (or anonymous arrays), where entries in the former are moved or copied to the locations specified to the equivalent entries in the latter, renaming and path creation occuring as needed:
-to
-from
-copy => 1, -to => [ '/html/index.html', '/html/imgs/index.gif', '/html/oldname.html' ], -from => [ '/docs/', '/docs/imgs/', '/html/newname_for_oldname.html' ],
The above example copies index.html to /docs/index.html, index.gif is copied to become /docs/imgs/index.gif, and oldname.html is moved to the html directory and given the new name, newname_for_oldname.html.
index.html
/docs/index.html
index.gif
/docs/imgs/index.gif
oldname.html
html
newname_for_oldname.html
Arguments:
See Tk::Wizard/METHOD blank_frame.
Tk::Wizard/METHOD blank_frame
Setting one or the other will determine whether files are copied (without deletion of originals) or moved (with deletion of originals). The default action is the former.
Rerence to an array of locations to copy/move from
Rerence to an array of locations to move/copy to
Delay (in mS) before copying begins (see Tk::After). Default is 1000.
Prevents display of the next Wizard page once the job is done.
A list of properties to pass to the Tk::ProgessBar object created and used in this routine. Assumes reasonable defaults.
Tk::ProgessBar
Text for the label frame (Tk::LabFrame object) which contains our moving parts. Defaults to Copying Files.
Tk::LabFrame
Copying Files
Text for label displayed whilst counting files to be copied. Defaults to Preparing....
Preparing...
The text of the label prepended to the name of the directory being copied. Defaults to From:.
From:
The text of the labe prepended to the name of the file being copied. Defaults to Copying:.
Copying:
A code reference to handle errors, which are detailed in the anonymous hash -failed, where names are filenames and values are the error messages. If not supplied, calls "DIALOGUE pre_install_files_quit".
-failed
Called when the user tries to quit. As opposed to the base Wizard's dialouge of the same name, this dialogue refers to "the Instllaer", rather than "the Wizard".
Wizard
Asks if the user wishes to continue after file copy errors.
$wizard->addDownloadPage ( name1=>value1 ... nameN=>valueN )
Adds a page (Tk::Frame) that will attempt to download specified files to specified locations, updating two progress bars in the process.
If a file cannot be downloaded, the user will be prompted to try again. If the user sooner or later wishes to carry on even though a file has not downloaded, the the calling Wizard's -failed slot is filled with the URIs of the files that could not be downloaded, and the supplied -on_error argument comes into play - see below. If no -on_error paramter is provided, the Wizard will continue.
-on_error
The Next and Back buttons of the Wizard are disabled whilst the download process takes place.
A refernece to a hash, where keys are URIs and values are local locations to place the contents of those URIs.
If supplied, the frame will remain on the screen when the download is complete - default is to automate a click on the next button once the downloads are completed without errors.
next
If set to a true value, will prevent the Try again? dialogue.
If a file cannot be downloaded and the user chooses not to keep trying, then this paramter comes into operation. If it is a reference, then it is assumed to be a code reference to execute; oftherwise a dialgoue box asks the user if they really wish to quit. If they do, then the CloseWindowEventCycle (see "CloseWindowEventCycle" in Tk::Wizard) - the default result of which is yet another confirmation of closure....
CloseWindowEventCycle
If no -on_error paramter is provided, the Wizard will continue even if it cannot download the requested data.
Text to display when complete. Default: complete.
= back
Would it be useful to impliment globbing for FTP URIs?
The labels of the licence can be changed (perhaps into a language other an English) by changing the values of the package-global %LABELS hash, at the top of the source. This will be revised in a future version.
%LABELS
Please see other functions' arguemnts for label-changing paramters.
It would be nice to have an 'Estimated Time Remaining' feature for the copy routines.
How about a remove-before-copy feature, and removing of directories? When there is time, yes.
Tk::LabFrame; File::Path; Tk::ProgressBar; File::Spec; File::Copy; Tk; Tk::Wizard; Tk::Wizard::Install::Win32.
Lee Goddard (lgoddard @ cpan.org).
Wizard; set-up; setup; installer; uninstaller; install; uninstall; Tk; GUI.
Copyright (C) Lee Goddard, 11/2002 ff.
Available under the same terms as Perl itself; no warranty of any kind.
2 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head1'
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.