Tk/Wizard - Wizard GUI Framework - Version 1.036
================================================

VERSION 1.036 04 April 2003
	*	New page type, text_frame via addTextFrame.
	*	New page type, multiple choice.

VERSION 1.035 02 April 2003
	*	-nohelpbutton bug now corrected
	*	-continue now works for empty task lists
		(previously it asked for a key to be pressed)

VERSION 1.034 21 January 2003
	*	Typed = instead of =~, resulting in
		incomplete dir listings in DirTrees.

VERSION 1.033 20 January 2003
	*	Fixed lack of require of File::Path

VERSION 1.032
	*	Added &forward> and &backward, mainly to automate tests.
	*	Added -continue method to &Tk::Wizard::Installer::addFileListPage
		and &Tk::Wizard::addTaskListPage.

INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

Be careful with the tests: some are currently interactive.

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 Microsoft Windows 95; a more
Windows 2000-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".

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

Please also see "IMPLIMENTATION NOTES".

STANDARD OPTIONS
	-title -background -width -height

Please see the Tk::options documentation for details of the standard
options.

WIDGET-SPECIFIC OPTIONS
Name: style
Class: ""
Switch: -style
	Sets the display style of the Wizard.

	The default 95 value creates a traditional, Windows 95-style wizard,
	with every page being "SystemButtonFace" coloured, with a large
	image on the left ("-imagepath", below).

	A value of "top", the Wizard will be more of a Windows 2000-like
	affair, 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).

Name: imagepath
Class: ""
Switch: -imagepath
	Path to an image file that will be displayed on the left-hand side
	of the screen. Dimensions are not been restrained (yet).

	Notes:

	*   This is a "Tk::Photo" object without the format being specified
		- this has been tested only on GIF and JPEG.

	*   No checking is done, but paths ought to be absolute, as no
		effort is made to maintain or restore any initial current
		working directory.

	*   The supplied images wizard_blue.gif and wizard_blue_top.gif are
		used by default. If you supply others you will probably have to
		set the Wizard's "-width" and "-height" properties, as there is
		(currently) no image-sized checking performed.

Name: topimagepath
Class: ""
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 50px x 50px has been
	tested.

	Please see notes for the "-imagepath" entry, above.

Name: nohelpbutton
Class: ""
Switch: -nohelpbutton
	Set to anything to disable the display of the *Help* buton.

Name: resizable
Class: ""
Switch: -resizable
	Supply a boolean value to allow resizing of the window: default is
	to disable that feature to minimise display issues.

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" and "METHOD addDirSelectPage".

METHOD Show
		C<wizard>->Show()

This method must be dispatched 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".

METHOD backward
Convenience method to move the Wizard back a page by invoking the
callback for the "backBUtton".

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. Returns a reference to the Wizard's "MainWindow".

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

Returns a "Tk::Frame" object that is a child of the Wizard control, with
some "pack"ing 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 as a title

=subtitle =>
	Subtitle/standfirst.

-text =>
	Main body text.

Also:

		-width -height -background -font

See also "METHOD addDirSelectPage".

METHOD addTextFrame
Add to the wizard a frame containing a scroll box of text, specified in
the paramter "-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 a file to
be opened and read.

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

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

Adds a page ("Tk::Frame") that contains a scrollable texxt box 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" with any other
value to avoid listing drives which are both inacessible 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" paramters, 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, and 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 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.

Paramters 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 (ie 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
-done_photo
	Optional: both "Tk::Photo" objects, the former displayed before an
	item on the taks list has been executed, which is changed to the
	latter after completion of the item. If not provided, then not
	displayed.

	If I knew more about TK bitmaps, or any bitmaps other than Vic-20,
	I'd extend this to have defaults.

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

		$wizard->addTaskListPage(
				-title => "Toy example",
				-tasks => [
						"Wait five seconds" => sub { warn "waiting for 5 ...."; sleep 5;  print "ok 8\n"},
						"Wait ten seconds!" => sub { warn "waiting for 10...."; sleep 10; print "ok 9\n"},
				],
		);

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

Note that unlink "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:".

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. Arguemnts 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. =back

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

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

	-finishButtonAction =>
		This is a reference to a funciton that will be dispatched to
		handle the Finish button action.

	-postFinishButtonAction =>
		This is a reference to a function that will be dispatched after
		the Finish button is processed.

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

IMPLIMENTATION NOTES
	This widget is implimented 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 implimentation to the
	more-standard manner. That is: because "Wizard" is a sub-class of
	"MainWIndow", the "-background" is inacessible 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
		implimentations 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
	*   20 January 2003: the directory tree part does not create
		directories unless the eponymous button is clicked.

	*   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"), as
		I'm having problems making &blank_frame produce them.

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

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

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

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

	Modifications Copyright (C) Lee Goddard, 11/2002 - 01/2003.

	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.


Tool completed successfully
