/ 
Tk-Wizard-2.158
River stage one • 1 direct dependent • 1 total dependent
/ Tk::Wizard::Installer

NAME

Tk::Wizard::Installer - Building-blocks for a software install wizard

SYNOPSIS

use Tk::Wizard::Installer;
my $wizard = new Tk::Wizard::Installer( -title => "Installer Test", );
$wizard->addDownloadPage(
    -no_retry => 1,
    -files  => {
        'http://www.cpan.org/' => './cpan_index1.html',
    },
);
$wizard->addPage( sub {
    return $wizard->blank_frame(
        -title=>"Finished",
        -subtitle => "Please press Finish to leave the Wizard.",
        -text => ""
    );
});
$wizard->Show;
MainLoop;

DESCRIPTION

This module makes the first moves towards a Tk::Wizard extension to automate software installation, primarily for end-users, in the manner of InstallShield.

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.

METHODS

Tk::Wizard::Installer supports all the methods and means of Tk::Wizard plus those listed in the remainder of this document.

addLicencePage

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

Adds a page (a Tk::Frame) that contains a scroll text box of a licence text file specified in the -filepath argument. Presents the user with two options: accept, or don't accept. The user cannot progress until the former option has been chosen. The choice is entered into the object field licence_agree, which is automatically tested when the Next button is pressed, or with the Wizard's callback_licence_agreement function. You can over-ride this last action by providing your own -preNextButtonAction callback.

addFileListPage

$wizard->addFileListPage ( name1=>value1 ... nameN=>valueN )

Adds a page (a Tk::Frame) that contains a progress bar (Tk::ProgressBar) which is updated as a supplied list of files is copied or moved from one location to another.

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 occurring as needed:

-copy => 1,
-from   => [
  '/html/index.html',
  '/html/imgs/index.gif',
  '/html/oldname.html'
  ],
-to => [
  '/docs/',
  '/docs/imgs/',
  '/html/newname.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 copied to newname.html in the same html directory.

Arguments:

-title
-subtitle
-text

See "blank_frame" in Tk::Wizard.

-copy
-move

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.

-from

Reference to an array of locations to copy/move from

-to

Reference to an array of locations to move/copy to

-delay

Delay (in mS) before copying begins (see Tk::after). Default is 1000.

-wait

Prevents display of the next Wizard page once the job is done.

-bar

A list of properties to pass to the Tk::ProgessBar object created and used in this routine. Assumes reasonable defaults.

-label_frame_title

Text for the label frame (Tk::LabFrame object) which contains our moving parts. Defaults to Copying Files.

-label_preparing

Text for label displayed whilst counting files to be copied. Defaults to Preparing....

-label_from

The text of the label prepended to the name of the directory being copied. Defaults to From:.

-label_file

The text of the label prepended to the name of the file being copied. Defaults to Copying:.

-on_error

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 "pre_install_files_quit".

-uninstall_db

Path at which to store an uninstall database file for use with addUninstallPage. This path will be used to create two files, one with a dir extension and one with a pag extension.

-uninstall_db_perms

If you supply -uninstall_db to create an uninstaller, you may use this argument to provide a file permissions for the db files; otherwise, the default is 0666. Please see the notes in SDBM_File that explain why 0666 is a good choice.

addFileCopyPage

Alias for addFileListPage.

addDownloadPage

$wizard->addDownloadPage( name1 => value1 ... nameN => valueN )

Adds a page 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 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 parameter is provided, the Wizard will continue.

The Next and Back buttons of the Wizard are disabled whilst the download process takes place.

-files

A reference to a hash, where keys are URIs and values are local locations to place the contents of those URIs.

WARNING: Files that are successfully downloaded will be deleted from the hash.

-wait

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.

-bar

A list of properties to pass to the Tk::ProgessBar object created and used in this routine. Assumes reasonable defaults.

-no_retry

If set to a true value, will prevent the Try again? dialogue.

-on_error

If a file cannot be downloaded and the user chooses not to keep trying, then this parameter comes into operation. If it is a reference, then it is assumed to be a code reference to execute; otherwise a dialogue box asks the user if they really wish to quit. If they do, then the Tk::Wizard CloseWindow event cycle is triggered -- the default result of which is probably yet another confirmation of closure....

If no -on_error parameter is provided, the Wizard will continue even if it cannot download the requested data.

-done_text

Text to display when complete. Default: complete.

Would it be useful to implement globbing for FTP URIs?

CALLBACKS

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.

confirm_download_again

This callback is triggered when a file download fails during a DownloadPage. In the default implementation, the user is asked if they would like to try again (Yes or No).

confirm_download_quit

This callback is triggered when the -on_error condition happens at the end of a DownloadPage. In the default implementation, the user is asked if they would like to abort the entire installation process (Yes or No).

pre_install_files_quit

Asks if the user wishes to continue after file copy errors.

addUninstallPage

Basically the same as addFileListPage, but rather than taking arguments to indicate from and to where files are to be moved or copied, takes the argument -uninstall_db, which should be the same value as supplied to addFileListPage.

DIALOGUES

DIALOGUE_really_quit

Called when the user tries to quit. As opposed to the base Wizard's dialogue of the same name, this dialogue refers to "the Installer", rather than "the Wizard".

INTERNATIONALISATION

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.

Please see other functions' arguments for label-changing parameters.

CAVEATS / TODO / BUGS

  • 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.

SEE ALSO

Tk::LabFrame; File::Path; Tk::ProgressBar; File::Spec; File::Copy; Tk; Tk::Wizard; Tk::Wizard::Install::Win32.

AUTHOR

Lee Goddard (lgoddard @ cpan.org).

KEYWORDS

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

AUTHOR

Lee Goddard (lgoddard@cpan.org).

COPYRIGHT

Copyright (C) Lee Goddard, 11/2002 - 01/s ff.

Made available under the same terms as Perl itself.