NAME

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

DESCRIPTION

This module makes the first moves towards a Tk::Wizard extension

to automate software installation, primarily for end-users, in the manner

of Install Sheild.

If you are looking for a freeware software installer that is not

dependant upon Perl, try Inno Setup - http://www.jrsoftware.org/. It's

so good, even Microsoft have been caught using it.

DEPENDENCIES

Tk::Wizard;

Tk::ProgressBar;

Tk::LabFrame;

DETAILS

Tk::Wizard::Installer supports all the methods and means of Tk::Wizard

plus those listed in the remainder of this document.

METHOD addLicencePage

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

You could supply a copy of the licence that comes with Perl.

See "CALLBACK callback_licence_agreement" and "METHOD page_licence_agreement".

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.

METHOD addDirSelectPage

See "METHOD adddirSelectPage" in TK::Wizard.

METHOD addFileListPage

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

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:

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

Arguments:

-title

-subtitle

-text

See Tk::Wizard/METHOD blank_frame.

-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

Rerence to an array of locations to copy/move from

-to

Rerence 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 labe prepended to the name of the file being copied.

Defaults to Copying:.

DIALOUGE METHOD DIALOGUE_really_quit

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

addDownloadPage

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

The Next and Back buttons of the Wizard are disabled whilst

the download process takes place.

-files

A refernece to a hash, where keys are URIs and

values are local locations to place the contents of those URIs.

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

-on_error

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

If no -on_error paramter is provided, the Wizard will continue.

Would it be useful to impliment globbing for FTP URIs?

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' arguemnts for label-changing paramters.

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.

COPYRIGHT

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

Available under the same terms as Perl itself; no warranty of any kind.

cpanm Tk::Wizard

perl -MCPAN -e shell
install Tk::Wizard