The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Tk-Wizard-Bases-1.953
++
/ Tk::Wizard::Installer::Win32

NAME

Tk::Wizard::Installer::Win32 - Win32-specific routines for Tk::Wizard::Installer

DESCRIPTION

All the methods and means of Tk::Wizard and Tk::Wizard::Installer,

plus the below, which are thought to be specific to the Microsoft Windows

platform.

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.

If you are looking for a means to update the Windows Path variable,

have a look for PathTool.exe, a tiny Windows 32-bit executable

by Luke Bailey (luke@notts.flexeprint.com). This tool can also be

used to add new, persistant environment variables to the system.

DEPENDENCIES

        Tk::Wizard

        Tk::Wizard::Installer

        Win32::TieRegistry

        Tk::Hlist

        Win32

        Win32::Shortcut

        File::Path

METHODS

METHOD register_with_windows

Registers an application with Windows so that it can be "uninstalled"

using the Control Panel's Add/Remove Programs dialogue.

An entry is created in the Windows' registry pointing to the

uninstall script path. See UninstallString, below.

Returns undef on failure, 1 on success.

Does nothing on non-MSWin32 platforms

Aguments are:

uninstall_key_name

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

end-user, but should be unique for all applications.

UninstallString

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.

QuiteUninstallString

As UninstallString above, but for ... quiet uninstalls.

app_path

Please see the entry for UninstallString, above.

DisplayName
DisplayVersion
Size

The strings displayed in the application list of the Add/Remove dialogue.

ModifyPath
NoRepair NoModify NoRemove
EstimatedSize InstallSorce InstallDate InstallLocation
AthorizedCDFPrefix Language ProductID

Unknown

Comments
RegOwner
RegCompnay
Contact
HelpTelephone
Publisher
URLUpdateInfo
URLInfoAbout

These are all displayed when the Support Information link

is clicked in the Add/Remove Programs dialogue. The last

should be full URIs.

The routine will also try to add any other paramters to the

registry tree in the current location: YMMV.

METHOD page_start_menu

Returns a page (a filled Tk::Frame object) that allows

users to select a location on the Windows "Start Menu",

perhaps to add a shortcut there.

This routine does not currently create the directory in the

Start Menu, nor does it place a link there - see

"CALLBACK callback_create_shortcut" for that. Rather, the

caller supplies a -variable paramter that is a reference

to a scalar which, once the page is 'run', will contain

either the path to the user's chosen directory, or undef

if the option to not select was chosen.

In addition, when the page is 'run', it places the path to the

current user's Start Menu/Programs directory into the object

field startmenu_dir_current, and the path to the common

Start Menu/Programs in the object field startmenu_dir_common.

The adding of a shortcut is left as an exercise to the reader

until later this year, when I'll get around to finishing this.

Have a look at the $mkdir Button in Tk::Wizard::page_dirSelect.

-user

Set to current, all or both to list the "Start Menu"

for all users, just the current user, or both. Default is both.

If there exist entries in both the common and current user's

Start Menu with the same name, the entry in the common menu

takes precedence.

-variable

A reference to a variable that, when the page is completed,

will contain the directory the user has chosen to create an item in. Note

this is not the full path: see above.

-program_group

Name of the directory to create on the start menu, if any.

If defined, this will be appended to any selection the user makes.

Since this is just the GUI part, no directory will actually be

created until callback_create_shortcut is called (though this will

change).

-disable_nochoice

Set to prevent the display of the checkbox which

allows the user not to use this feature. See -label_nochoice,

below.

-label_nochoice

If the paramter -disable_nochoice has not been set,

-label_nochoice should contains text to use for the label by the

checkbox which disables choices on

this page and causes the page to set the -variable paramter to

undef. Default text is Do not create a shortcut on the Start Menu

-listHeight

Height of the list box, default is 10 but you may

vary this if your -text attribute takes up more or less much room.

Accepts the Standard Options that are common to the HList and

Label widgets, but does not accept aliases:

        -relief -highlightthickness -background -borderwidth -cursor

        -highlightcolor -foreground -font

You can supply the common Wizard page options:

        -title -subtitle -text

This method will initially attempt to use Win32.pm; failing

that, it will attempt to use a Windows Scripting Host object

created via Win32::OLE. If both fail (WSH only existing by

default in Win98 and above), the routine will return undef,

rather than a page frame object. This may not be ideal but works

for me - suggestions welcomed for a better idea.

CALLBACK callback_create_shortcut

A convenience interface to Win32::Shortcut method that creates a shortcut

at the path specified. Parameters are pretty much what you see when

you right-click a shortcut:

-save_path

The location at which the shortcut should be saved.

This should be the full path including filename ending

in .lnk.

The filename minus extension will be visible in the shortcut.

If the -program_group parameter was passed to

METHOD page_start_menu, the directory it refers to

will be included in the save path you supply.To avoid

this, either undefine the object field -program_group,

or supply the paramter -no_program_group.

-no_program_group>

See -save_path, above.

-target

The shortcut points to this file, directory, or URI -

see notes for -save_path, above.

-workingdir

The working directory for the -target, above.

-description

This is what you see when you mouse-over a shortcut

in more "modern" (Win2k/ME+) Windows.

-iconpath

Path to the icon file - an .exe, .dll, .ico or

other acceptable format.

-iconindex

Index of the icon in the file if a .exe or .dll.

-arguments

Um... it's the second parameter in Win32::Shortcut::Set -

could well be parameters for the target, but I'm too much of

a rush to check. XXX

-show

Whether the -target, above, should be

started maximized or minimized. Acceptable values are

the constants:

    SW_SHOWMAXIMIZED SW_SHOWMINNOACTIVE SW_SHOWNORMAL
-hotkey

Key combination to activate the shortcut. Probably looks

something like ctrl+t.

On success, returns the -save_path; on failure, undef.

CALLBACK callback_create_shortcut

Convenience method to create multiple shortcuts at once.

Supply an array of hashes, each hash being arguments

to supply to callback_create_shortcut.

Returns an array or reference to an array that contains

the reults of the shortcut creation.

See "CALLBACK callback_create_shortcut".

DIALOUGE METHOD DIALOGUE_really_quit

Refers to the Instllaer, rather than the Wizard.

CAVEATS AND BUGS

* Error going backwards into a addStartMenuPage.

CHANGES

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

AUTHOR

Lee Goddard (lgoddard@cpan.org).

SEE ALSO

Tk::Wizard; Tk::Wizard::Installer;

Win32::GetFolderPath();

Win32::Shortcut;

Win32::OLE.

KEYWORDS

Wizard; set-up; setup; installer; uninstaller; install; uninstall; Tk; GUI; windows; win32; registry; shortcut;

COPYRIGHT

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

Distributed under the same terms as Perl itself.