NAME

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

SYNOPSIS

        use Tk::Wizard;
        my $wizard = new Tk::Wizard;
        #
        # OR
        # my $MW = Tk::MainWindow->new;
        # my $wizard = $MW->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     => $seconds_b4_proceeding_anyway,
                );
        });
        $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 files that are run during the make test phase of installation: you may rename them without harm once you have installed the module.

CHANGES

The widget now works from within a MainWindow, or creates its own as necessary for backwards compatability.

The optoin -image_dir has been deprecated, and the once-used binary images have been dropped from the distribution in favour of Base64- encoded images. More and other details in ChangeLog.

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 namespace, 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 largly based upon the Microsoft(TM,etc) wizard style: the default is simillar 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.

NB: THIS IS STILL AN ALPHA RELEASE: ALL CONTRIBUTIONS ARE WELCOME!

Please read "CAVEATS, BUGS, TODO".

ADVERTISED SUB-WIDGETS

Still untested. Use:

        $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

tagText

The grayed-out text above the buttonpanel.

tagBox

The frame holding the tag text.

imagePane

Either the image on the first and last pages. Also: for 95 style wizards: the same; for style top (default) Wizards, the box at the top of the wizard. What a terrible sentance.

wizardFrame

The frame that holds the content frame.

STANDARD OPTIONS

-title

Text that appears in the title bar.

-background

Main background colour of the Wizard's window.

-width -height

Size of the wizard. This is adjustable per-page - every method that adds a page will accept these options and pass them on to the main Wizard window.

WIDGET-SPECIFIC OPTIONS

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 white-backgrounded version of the traditional style, 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.

  • Base64-encoded images to pass in the -data field of the Tk::Photo object. This is the default form, and a couple of 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 buton.

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.

Switch: -tag_width

Width for -tag_text, above: when I work out better packing, this will no longer be needed. Default value is based on the length of your -tag_text.

Switch: -tag_disable

Disables display of the -tag_text, above.

-image_dir

Deprecated. Supply -imagepath and/or -topimagepath.

Please see also "ACTION EVENT HANDLERS".

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

See also "METHOD blank_frame".

METHOD Show

        $wizard->Show()

This method must be called before the Wizard will be displayed, and must preced the MainLoop call.

METHOD 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});

METHOD backward

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

See also "METHOD back".

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

METHOD parent

        my $apps_main_window = $wizard->parent;

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

METHOD blank_frame

        my $frame = wizard>->blank_frame(
                -title          => $title,
                -subtitle       => $sub,
                -text           => $standfirst,
                -wait           => $sometime
        );

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

-text =>

Main body text.

-wait =>

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

See also: Tk::after.

Also:

        -width -height -background -font

METHOD addTextFrame

Add to the wizard a frame 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.

CloseWindowEventCycle

If this method recieves a true value from the -preCloseWindowAction callback, the calling object's destroy method is called, by default closing the Wizard.

DIALOGUE_really_quit

Returns true if we are to continue. By default, may be called by closing the Wizard's window or pressing CANCEL.

METHOD addDirSelectPage

        $wizard->addDirSelectPage ( -variable => \$chosen_dir )

Adds a page (Tk::Frame) that contains a scrollable tree list of all directories including, on Win32, logical drives.

Supply in -variable a reference to a variable to set the initial directory, and to have set with the chosen path.

Supply -nowarnings with a value of 1 to list only drives which are accessible, thus avoiding Tk::DirTree warnings on Win32 where removable drives have no media.

Supply -nowarnings a value other than 1 to avoid listing drives which are both inaccessible and - on Win32 - are either fixed drives, network drives, or RAM drives (that is types 3, 4, and 6, according to Win32API::File::GetDriveType.

You may also specify the -title, -subtitle and -text parameters, as in "METHOD blank_frame".

See "CALLBACK callback_dirSelect".

CALLBACK callback_dirSelect

A callback to check that the directory, passed as a reference in the sole argument, exists, or can and should be created.

Will not allow the Wizard to continue unless a directory has been chosen. If the chosen directory does not exist, Setup will ask if it should create it. If the user affirms, it is created; otherwise the user is again asked to chose a directory.

Returns a Boolean value.

This method relies on Win32API::File on MS Win32 machines only.

METHOD addFileSelectPage

  $wizard->addFileSelectPage(
                             -directory => 'C:/Windows/System32',
                             -variable => \$chosen_file,
                            );

Adds a page (Tk::Frame) that contains a "Browse" button which pops up a file-select dialog box. The selected file will be displayed in a read-only Entry widget.

Supply in -directory the full path of an existing folder where the user's search shall begin.

Supply in -variable a reference to a variable to have set with the chosen file name.

You may also specify the -title, -subtitle and -text parameters, as in "METHOD blank_frame".

METHOD addTaskListPage

Adds a page to the Wizard that will perform a series of tasks, keeping the user informed by ticking-off a list as each task is accomplished.

Whilst the task list is being executed, both the Back and Next buttons are disabled.

Parameters are as for blank_frame (see "METHOD blank_frame"), plus:

-tasks

The tasks to perform, supplied as a reference to an array, where each entry is a pair (i.e. a two-member list), the first of which is a text string to display, the second a reference to code to execute.

-delay

The length of the delay, in milliseconds, after the page has been displayed and before execution the task list is begun. See the entry for the 'after' routine in the Tk::After manpage.

-continue

Display the next Wizard page once the job is done: invokes the callback of the Next button at the end of the task.

-todo_photo
-doing_photo
-ok_photo
-error_photo

In progress. Optional: all Tk::Photo objects, displayed as appropriate. -ok_photo is displayed if the task code refernce returns a true value, otherwise -error_photo is displayed. These have defaults taken from Tk::Wizard::Image.

-label_frame_title

The label above the Tk::LabFrame object which contains the task list. Default label is the boring Performing Tasks:.

-frame_args

Optional: the arguments to pass in the creation of the Frame object used to contain the list.

-frame_pack

Optional: array-refernce to pass to the pack method of the Frame containing the list.

TASK LIST EXAMPLE

  $wizard->addTaskListPage(
      -title => "Toy example",
      -tasks => [
                "Wait five seconds" => sub { sleep 5 },
                        "Wait ten seconds!" => sub { sleep 10 },
                ],
        );

METHOD page_taskList

The same as addTaskListPage (see "METHOD addTaskListPage") but does not add the page to the Wizard.

Note that unlike addTaskListPage, arguments are expected in a hash reference.

Useful for a task list that cannot be filled before the call to Show().

Parameter -label_frame_title is the label above the Tk::LabFrame object which contains the task list. Default label is the boring Performing Tasks:.

METHOD addMultipleChoicePage

Allow the user to make multiple choices among several options: each choice sets a variable passed as reference to this method.

Accepts the usual parameters plus:

-relief

For the checkbox buttons - see Tk::options.

-choices

A reference to an array of hashes with the following fields:

-title

Title of the option, will be rendered in bold

-subtitle

Text rendered smaller beneath the title

-variable

Reference to a variable that will contain the result of the choice. Croaks if none supplied.

-checked

Pass a true value to specify that the box should initially appear checked.

DIALOGUE METHOD 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:

-parent =>

Tk object that is our parent window. Default's to our parent field.

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

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.

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

-preCloseWindowAction =>

This is a reference to a function that will be dispatched before the window is issued a close command. Default is to exit on user confirmation - see "DIALOGUE METHOD DIALOGUE_really_quit".

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

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. Yes, this is not 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}.

See also INTERNATIONALISATION.

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 my almost three weeks of exposure to Tk. Please, if you have a suggestion, or patch, send it to me directly: LGoddard@CPAN.org.

The widget is a MainWindow and not a TopLevel window. The reasoning is that Wizards are applications in their own right, and not usually parts of other applications. Although at the time of writing, I had only three weeks of Tk, I believe it should be possible to embed a Tk::Wizard into another window using -use and -container -- but any info on this practice would be appreciated.

There is one outstanding bug which came about when this Wizard was translated from an even more naive implementation to the more-standard manner. That is: because Wizard is a sub-class of MainWindow, the -background is inaccessible to me. Advice and/or patches suggestions much appreciated.

THE Tk::Wizard NAMESPACE

In discussion on comp.lang.perl.tk, it was suggested by Dominique Dumont (would you mind your address appearing here?) that the following guidelines for the use of the Tk::Wizard namespace be followed:

  1. That the module Tk::Wizard act as a base module, providing all the basic services and components a Wizard might require.

  2. That modules beneath the base in the hierachy 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, BUGS, TODO

POTENTIAL 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" proivde a callback to -finishButtonAction:

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

Please let me know if you need to do this.

  • Bit messy when composing frames.

  • Task Frame LabFrame backgrond 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 propertly. 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).

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 Martin Thurn (mthurn@cpan.org) for support and patches.

KEYWORDS

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

COPYRIGHT

Copyright (c) Daniel T Hable, 2/2002.

Copyright (C) Lee Goddard, 11/2002 - 05/2005 ff

Patches Copyright (C) Martin Thurn 2005.

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

1 POD Error

The following errors were encountered while parsing the POD:

Around line 1667:

You forgot a '=back' before '=head1'