NAME

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

SYNOPSIS

        use Tk::Wizard ();
        my $wizard = new Tk::Wizard;
        # OR my $wizard = Tk::MainWindow->new -> Wizard();
        $wizard->configure( -property=>'value' );
        $wizard->cget( "-property");
        # $wizard->addPage(
        # ... code-ref to anything returning a Tk::Frame ...
        # );
        $wizard->addPage(
                sub {
                        return $wizard->blank_frame(
                                -title    => "Page Title",
                                -subtitle => "Sub-title",
                                -text     => "Some text.",
                                -wait     => $milliseconds_b4_proceeding_anyway,
                        );
                }
        );
        $wizard->addPage(
                sub { $wizard->blank_frame(@args) },
                -preNextButtonAction  => sub { warn "My -preNextButtonAction  called here" },
                -postNextButtonAction => sub { warn "My -postNextButtonAction called here" },
        );
        $wizard->Show;
        MainLoop;
        exit;

To avoid 50 lines of SYNOPSIS, please see the files included with the distribution in the test directory: t/*.t. These are just Perl programs that are run during the make test phase of installation: you can move/copy/rename them without harm once you have installed the module.

CHANGES

Please see the documentation for the new import method: import.

DEPENDENCIES

Tk and modules of the current standard Perl Tk distribution.

On MS Win32 only: Win32API::File.

EXPORTS

  MainLoop();

This is so that I can say use strict; use Tk::Wizard without having to use Tk. You can always use Tk::Wizard () to avoid importing this.

DESCRIPTION

In the context of this name space, a Wizard is defined as a graphic user interface (GUI) that presents information, and possibly performs tasks, step-by-step via a series of different pages. Pages (or 'screens', or 'Wizard frames') may be chosen logically depending upon user input.

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 feel is largely based upon the Microsoft(TM,etc) wizard style: the default is similar to that found in Windows 2000, though the more traditional Windows 95-like feel is also supported (see the -style entry in "WIDGET-SPECIFIC OPTIONS". Sub-classing the module to provide different look-and-feel is highly encourage: please see "NOTES ON SUB-CLASSING Tk::Wizard". If anyone would like to do a Darwin or Aqua version, please let me know how you would like to handle the buttons. I'm not hot on advertising widgets.

ADVERTISED SUB-WIDGETS

  $wizard->Subwidget('buttonPanel');

buttonPanel: The Frame that holds the navigation buttons and optional help button.
nextButton
backButton
cancelButton
helpButton: The buttons in the buttonPanel.
tagLine: The line above the buttonpanel, a Tk::Frame object.
tagText: The grayed-out text above the buttonpanel, a Tk::Label object.
tagBox: A Tk::Frame holding the tagText and tagLine.
imagePane: On all pages of a 95-style Wizard, and for the first and last pages of the default c<top>-style Wizard, this is a large pane on the left, that holds an image. For the other pages of a top-style Wizard, this refers to the image box at the top of the wizard.
wizardFrame: The frame that holds the content frame, the current Wizard page.

STANDARD OPTIONS

-title: Text that appears in the title bar.
-background: Main background colour of the Wizard's window.

Name: style

Class: Style

Switch: -style

Sets the display style of the Wizard.

The default no-value or value of top gives the Wizard will be a Windows 2000-like look, with the initial page being a version of the traditional style with a white background, and subsequent pages being SystemButtonFace coloured, with a white strip at the top holding a title and subtitle, and a smaller image (see -topimagepath, below).

The old default of 95 is still available, if you wish to create a traditional, Windows 95-style wizard, with every page being SystemButtonFace coloured, with a large image on the left (-imagepath, below).

Name: imagepath

Class: Imagepath

Switch: -imagepath

Path to an image that will be displayed on the left-hand side of the screen. (Dimensions are not constrained.) One of either:

Path to a file from which to construct a Tk::Photo object without the format being specified; No checking is done, but paths ought to be absolute, as no effort is made to maintain or restore any initial current working directory.
A reference to a Base64-encoded image to pass in the -data field of the Tk::Photo object. This is the default form, and a couple of extra, unused images are supplied: see Tk::Wizard::Image.

Name: topimagepath

Class: Topimagepath

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 50x50 has been tested.

Please see notes for the -imagepath>.

Name: nohelpbutton

Class: Nohelpbutton

Switch: -nohelpbutton

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

Name: resizable

Class: resizable

Switch: -resizable

Supply a boolean value to allow resizing of the window: default is to disable that feature to minimise display issues.

Switch: -tag_text

Text to supply in a 'tag line' above the wizard's control buttons. Specify empty string to disable the display of the tag text box.

-fontfamily

Specify the "family" (ie name) of the font you want to use for all Wizard elements. The default is your operating system default (or a sans serif), which on my test computers is "MS Sans Serif" on Windows, "Helvetica" on Linux, and "Helvetica" on Solaris.

-basefontsize

Specify the base size of the font you want to use for all Wizard elements. Titles and subtitles will be drawn a little larger than this; licenses (the proverbial fine print) will be slightly smaller. The default is your operating system default, which on my test computers is 8 on Windows, 12 on Linux, and 12 on Solaris.

-width

Specify the width of the CONTENT AREA of the Wizard, for all pages. The default width (if you do not give any -width argument) is 50 * the basefontsize. You can override this measure for a particular page by supplying a -width argument to the add*Page() method.

-height

Specify the height of the CONTENT AREA of the Wizard, for all pages. The default height (if you do not give any -height argument) is 3/4 the default width. You can override for a particular page by supplying a -height argument to the add*Page() method.

-kill_self_after_finish

The default for the Wizard is to withdraw itself after the "finish" (or "cancel") button is clicked. This allows the Wizard to be reused during the same session (the Wizard will be destroyed when its parent MainWindow is destroyed). If you supply a non-zero value to this option, the Wizard will instead be destroyed after the "finish" button is clicked.

Please see also "ACTION EVENT HANDLERS".

WIZARD REFRESH RATE

$Tk::Wizard::REFRESH_MS is the number of milliseconds after which an update will be called to redraw the Wizard. Current value is one second.

METHODS

import

        use Tk::Wizard;
        use Tk::Wizard ();
        use Tk::Wizard ':old';
        use Tk::Wizard ':use' => [qw[ Choices FileSystem ]];

All the above examples are currently equivalent. However, as of version 3.00, later in 2008, the first two will no longer act as the last two -- that is, they will no longer import the methods now located in the Choices and FileSystem modules (Tk::Wizard::Choices, Tk::Wizard::FileSystem): you will have to do that yourself, as in the final example, or manuall:

        use Tk::Wizard;
        use Tk::Wizard::Tasks;

new

Create a new Tk::Wizard object. You can provide custom values for any or all of the standard widget options or widget-specific options

Populate

This method is part of the underlying Tk inheritance mechanisms. You the programmer do not necessarily even need to know it exists; we document it here only to satisfy Pod coverage tests.

parent

  my $apps_main_window = $wizard->parent;

This returns a reference to the parent Tk widget that was used to create the wizard.

background

Get/set the background color for the body of the Wizard.

update

Redraws the Wizard.

blank_frame

  my $frame = wizard>->blank_frame(
    -title    => $sTitle,
    -subtitle  => $sSub,
    -text    => $sStandfirst,
    -wait    => $iMilliseconds
  );

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

-subtitle =>

Subtitle/stand-first.

-text =>

Main body text.

-wait =>

Experimental, mainly for test scripts. The amount of time in milliseconds to wait before moving forward regardless of the user. This actually just calls the forward method (see "forward"). Use of this feature will enable the back-button even if you have disabled it. What's more, if the page is supposed to wait for user input, this feature will probably not give your users a chance.

WARNING: do not set -wait to too small of a number, or you might get callbacks interrupting previous callbacks and the whole wizard will get all out of whack. 100 is probably safe for most modern computers; for slower machines try 300. If you want to see the page as it flips by, use 1000 or more.

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 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 performing checks as the Next button is pressed (see file test.pl supplied with the distribution).

As of version 2.76, you may supply arguments: -preNextButtonAction, -postNextButtonAction, -preBackButtonAction, -postBackButtonAction: see "ACTION EVENT HANDLERS" for further information. More handlers, and more documentation, may be added.

addSplashPage

Add to the wizard a page containing a chunk of text, specified in the parameter -text. Suitable for an introductory "splash" page and for a final "all done" page.

Accepts exactly the same arguments as blank_frame.

addTextFramePage

Add to the wizard a page containing a scrolling textbox, specified in the parameter -boxedtext. If this is a reference to a scalar, it is taken to be plain text; if a plain scalar, it is taken to be the name of a file to be opened and read.

Accepts the usual -title, -subtitle, and -text like blank_frame.

Show

        $wizard->Show();

Draw and display the Wizard on the screen. Normally you would call MainLoop right after this.

forward

Convenience method to move the Wizard on a page by invoking the callback for the nextButton.

You can automatically move forward after $x tenths of a second by doing something like this:

  $frame->after($x,sub{$wizard->forward});

backward

Convenience method to move the Wizard back a page by invoking the callback for the backButton.

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 also the "addPage" entry.

setPageSkip

Mark one or more pages to be skipped at runtime. All integer arguments are taken to be page numbers (ie the number returned by any of the add*Page methods)

You should never set the first page to be skipped, and you can not set the last page to be skipped, though these rules are not (yet) enforced.

setPageUnskip

Mark one or more pages not to be skipped at runtime (ie reverse the effects of setPageSkip). All integer arguments are taken to be page numbers (ie the number returned by any of the addPage methods)

next_page_number

Returns the number of the page the Wizard will land on if the Next button is clicked (ie the integer returned by add*Page).

back_page_number

Returns the number (ie the integer returned by add*Page) of the page the Wizard will land on if the Back button is clicked.

prompt

Equivalent to the JavaScript method of the same name: pops up a dialogue box to get a text string, and returns it. Arguments are:

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

CALLBACKS

DIALOGUE_really_quit

This is the default callback for -preCloseWindowAction. It gives the user a Yes/No dialog box; if the user clicks "Yes", this function returns true (otherwise returns a false value).

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 implementation, 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. The function is called after the application has logically advanced to the next page, but before the next page is drawn on screen.
-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. By default there is no Help action; therefore unless you are providing this function, you should initialize your Wizard with -nohelpbutton => 1.
-postHelpButtonAction =>: This is a reference to a function that will be dispatched after the Help button is processed.
-preFinishButtonAction =>: This is a reference to a function that will be dispatched just before the Finish button action.
-finishButtonAction =>: This is a reference to a function that will be dispatched to handle the Finish button action.
-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 "DIALOGUE_really_quit".
-preCloseWindowAction =>: This is a reference to a function that will be dispatched before the window is issued a close command. If this function returns a true value, the Wizard will close. If this function returns a false value, the Wizard will stay on the current page. Default is to exit on user confirmation - see "DIALOGUE_really_quit".

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

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 may not be a good way to do it: patches always welcome ;)

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 callbacks can also be changed via the %LABELS hash: see the top of the source code for details.

IMPLEMENTATION NOTES

This widget is implemented using the Tk 'standard' API as far as possible, given that when I first needed a wizard in Perl/Tk, I had almost three weeks of exposure to the technology. Please, if you have a suggestion, or patch, send it to me directly via LGoddard@CPAN.org, or via CPAN's RT.

The widget supports both MainWindow and not TopLevel window. Originally, only the former was supported - the reasoning was that Wizards are applications in their own right, and not usually parts of other applications. However, conventions are not always bad things, hence the update.

THE `Tk::Wizard` NAMESPACE

In discussion on comp.lang.perl.tk, it was suggested by Dominique Dumont that the following guidelines for the use of the Tk::Wizard namespace be followed:

That the module Tk::Wizard act as a base module, providing all the basic services and components a Wizard might require.
That modules beneath the base in the hierarchy provide implementations based on aesthetics and/or architecture.

NOTES ON SUB-CLASSING Tk::Wizard

If you are planning to sub-class Tk::Wizard to create a different display style, there are three routines you will need to over-ride:

_initial_layout
_render_current_page
blank_frame

This may change, please bear with me.

CAVEATS

In earlier versions of this still-alpha software, if you did not call the Wizard's destroy method, you would receive errors. This may or may not still be an issue for you. If it is, you can "simply" provide a callback to -finishButtonAction:

  $wizard->configure(
    -finishButtonAction  => sub { $wizard->destroy; 1; },
  );

Please let me know if you need to do this.

Bit messy when composing frames.
Task Frame LabFrame background colour doesn't set properly under 5.6.1.
20 January 2003: the directory tree part does not create directories unless the eponymous button is clicked. Is this still an issue?
In Windows, with the system font set to > 96 DPI (via Display Properties / Settings / Advanced / General / Display / Font Size), the Wizard will not display pro pertly. 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).

BUGS

Please use RT (https://rt.cpan.org/Ticket/Create.html?Queue=Tk-Wizard) to submit a bug report.

CHANGES

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

AUTHOR

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

Thanks to co-maintainer Martin Thurn (mthurn@cpan.org) for support, patches, and estensions, whilst I'm elsewhere.

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.

THIS SOFTWARE AND THE AUTHORS OF THIS SOFTWARE ARE IN NO WAY CONNECTED TO THE MICROSOFT CORP.

THIS SOFTWARE IS NOT ENDORSED BY THE MICROSOFT CORP

MICROSOFT IS A REGISTERED TRADEMARK OF MICROSOFT CORP.

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

CHANGES

DEPENDENCIES

EXPORTS

DESCRIPTION

ADVERTISED SUB-WIDGETS

STANDARD OPTIONS

WIDGET-SPECIFIC OPTIONS

WIZARD REFRESH RATE

METHODS

import

new

Populate

parent

background

update

blank_frame

addPage

addSplashPage

addTextFramePage

Show

forward

backward

currentPage

setPageSkip

setPageUnskip

next_page_number

back_page_number

prompt

CALLBACKS

DIALOGUE_really_quit

ACTION EVENT HANDLERS

BUTTONS

INTERNATIONALISATION

IMPLEMENTATION NOTES

THE Tk::Wizard NAMESPACE

NOTES ON SUB-CLASSING Tk::Wizard

CAVEATS

BUGS

CHANGES

AUTHOR

KEYWORDS

COPYRIGHT

Module Install Instructions

THE `Tk::Wizard` NAMESPACE