Tk::XML::WizardMaker - easy way to build the Software Assistants and Installation Wizards based on XML description.
To use Tk::XML::WizardMaker just provide an XML file with descriptions of the WizardMaker's features and of the feaures of all its pages. Then use something like this:
use Tk; use Tk::XML::WizardMaker; my $mw = MainWindow->new(); $mw->WizardMaker([<options>])->build_all(); MainLoop;
For other usage possibilities please see the methods description below.
The Software Wizards are popular for tasks like software installation, upgrade or just gathering of configuration options. There is a lot of good software (often called as Install Schild) which provides developers with APIs for building of those Wizards.
This package is just one "Install Shild" more.
Many of those Install Shields provide only API interface. You have a lot of functions or methods to build a wizard page and to bind some callbacks. So if you develope an install script, you have to code in how to create and maintain all its wizard pages.
If you maintains this script some time later (because the new release of your software is ready in 6 months), you will have to change a lot of code. If you want to add a new page into the old script, you have to program:
1. prepare variables to hold new values. 2. the code to create the new page with all its components. 3. changes in callbacks (what to do on the NEXT button)
But all this is not your problem as it is a new developer who must maintain your script now ...
After some new releases your script is less readeable and seems to have bugs.
Not so if you use the Tk::XML::WizardMaker. It does provide an API interface too, but it can help you separate the page building from what to do with information gathered.
You just describe the entire wizard in XML. All the pages will be than generated automatically.
All callbacks can be described both in XML or directly in the script code. All callbacks can be individual functions for every page - your code is more.
If you will maintain your script some time later, the only you have to do is to program
1. what to do with new informations.
All other things can be descriptive XML code.
Here are some features of the Tk::XML::WizardMaker:
It is easy to use.
It separates the program logic from the GUI generation and event processing.
It provides a simle XML description of all GUI features in one file.
Some types of page layouts are predefined. So you can simply describe what kind of page you wanto to have and which elemets have to be displayed with it.
To add a new page into the Program is as simple as to write some lines of XML code.
You don't have to insert any event handling code into your program. But If you need this, it is possible to include event handling subroutines direct into XML description for any page.
An object oriented interface is although provided. So you can be creative developing new page layouts and extending features.
This file should look like this (four pages here, for more complex examples look below in this document and in the demo files):
<my_assistent
title="Demo WizardMaker" left_image="left_image.gif" top_image="top_image.gif"> <page name = "Start" status = "normal" type = "TextPage" title = "The first generic Page" subtitle = "The first generic Page Subtitle" text = "The first generic Page Text" summary = "Welcome to the Installatin WizardMaker. blah blah blah ..." help_text= "Press NEXT to install or CANCEL to abort!" /> <page name ="UserInfo" status ="normal" type ="LabeledEntriesPage" title ="User Information" subtitle ="Some customer data."> <LabeledEntry name="Name" title="Name" status="normal"/> <LabeledEntry name="Company" title="Company" status="normal" /> <LabeledEntry name="Install_path" title="Directory" status="normal" button = "dir_select"/> </page> <page name ="SelectComponents" status ="normal" type ="CheckButtonPage" title ="Software Components" subtitle ="List of available sotfware components." text ="Please select components you want to install."> <CheckButton name="Java" title="Java SDK" status="normal" /> <CheckButton name="Office" title="Office Suite" status="normal" /> <CheckButton name="DB" title="Database" status="normal" /> </page> <page name="StartInstallation" status="normal" type="TextPage" title="Start Installation" subtitle="Installation will start now." text="Press Start button to process the Installation." summary="All software yuo have choosen will be installed. NOW!" help_text="Press Start button to process the Installation!" pre_next_button_code=" print qq/\n\tYou can place the installation code here!/; sleep 3; return 1; " /> <page name ="Finish" status ="normal" type ="TextPage" title ="Finish" subtitle ="Installationd is complete." text ="Press FINISH to end Wizard." summary ="Installation complete." />
</my_assistent>
I shell refer this file as GUI.XML.
In the current implementation, all structures comming from GUI.XML file are saved in hash $self->{gui}. All pages constructed on the basis of GUI.XML are then saved in the hash $self->{internal}->{pages}. This inplementation details can change, but there are methods to refer to this structures.
The XML files will be parsed with XML::Simple. So be carefull in how to write the file.
This file should contain default values for GUI pages and action descriptions to process installation. I shell refer this file as OPT.XML. It is not really nessesary. I use it for two reasons.
- I want to separate the GUI from what to do to install the software. So I describe all the installation steps in this separate file. The tags here are free except of <gui> - tag. - I want to have only one place for all variables used in the GUI. So I place all default values in the OPT file under <gui>. Then in the WizardMaker these variables can change values. All them are currently maintained as $self->{opt}->{gui} hash. Use method gui_option() to get or set this values in your script. This way all the variables can be comfortably pre- or postprocessed.
If you do not like the OPT.XML you have just to set default values manually in you script. See demo_04 for how to do so.
A simple version of OPT.XML may looks like this (the element names here are the same as the corresponding attribute "name" in the GUI file). Once again - only <gui> tag is important, all other tags CAN be used by you to describe the installation steps.
<opt>
<gui> <Name value="MyName" /> <Company value="MyCompany" /> <Office value="1" /> <DB value="0" /> <Install_path value="C:\\Programs" /> </gui> <instal> <part name="database"> <command="copy" src="D:\\database\\dings.dll" dest="C:\\WINNT" /> <command="exec" command="SetupDB.exe" dest="$self->gui_option(q/Install_path/)" /> <command="eval" command=" main::patch_registry(qq/Software\\myDB\\description/, $self->gui_option(q/Name/))" /> </part> </instal>
</opt>
Now you can use the WizardMaker in your Wizard (or what is the name of your Program?):
use Tk::XML::WizardMaker; # The WizardMaker is based on Tk::Frame, so we need a MainWindow my $mw = Tk::MainWindow->new(); # initialize a new instance. There are no pages yet. my $w = $mw->WizardMaker( -gui_file => 'gui.xml', -opt_file => 'opt.xml'); # add all valid pages to the instance. $w->build_all(); # Go! Tk::MainLoop;
Don't forget to write the installation code as well...
Almost all features and beheavors of Tk::XML::WizardMaker can be customised.
All options can be defined in an XML file. The only exceptions are options -gui, -gui_file, -opt, -opt_file which self define wich XML files to use.
All options have build in defaults.
I don't really use the X11 resource database and do provide some replacement options due to compatibility reasons.
Since Assistant is a Tk::Frame, there can be more then one WizardMaker instances in one time.
All instance wide options can be overwritten during WizardMaker creation or later with given API or direct with Tk commando configure.
They have form of document root attributes if defined in XML file:
background = "gray"
or, they can be defined as perl list if specified as call or config option:
$main_window->WizardMaker( -background => 'gray');
GUI Description (only one of the following options is possible)
-gui # a perl hash with assistent discription -gui_file # an XML file with assistent discription. If you # read it with XML::Simple->XMLIn, it beckoms the same # form as -gui - hash.
Process Instruction Descriptions and default values. (One or no of the options must be defined)
-opt # a perl hash -opt_file # an XML file
Grafic images to use on the WizardMaker pages (GIF files). The left image will be displayed on the first and last pages, on all other pages will be displayed top_image. The options can be redefined for every page with top_image_name and top_image_file (see demo_03).
-top_image # file to display on top of WizardMaker -left_image # file to display on its left site
Default Fonts (can be rewritten on the page level):
-title_font # for the page title -subtitle_font # for the page subtitle -subsubtitle_font # for the page subsubtitle -small_font # small font (not really used) -text_font # text font -radio_font # for radio buttons, check buttond and entries -fixed_font # fixed font -button_font # for command buttons
Default Texts
-title # in the title of parent window -help_title # in the title of the online help -no_help_text # default help text -warning_title # in the title of warnings -no_warning_text # default warning text -error_title # in the title of the error messages -no_error_text # default error text -info_title # in the title of the online info -no_info_text # default info text -button_help # for help button -button_next # for next button -button_back # for back button -button_finish # for finish button -button_cancel # forcancel button -button_log # for show log button -button_done # for done button -button_dir_select # for dir select button -button_file_open # for file open button
Default Colors and Reliefs (can be rewritten on the page level):
-foreground # for all common elements -background # for all common elements -select_foreground # for all common elements (heilight) -select_background # for all common elements (heilight) -header_background # for page headers -header_foreground # for page headers -select_header_background # for page headers (heilight) -select_header_foreround # for page headers (heilight) -header_background1 # for page header's title -header_foreground1 # for page header's title -header_background2 # for page header's subtitle -header_foreground2 # for page header's subtitle -header_background3 # for page header's subsubtitle -header_foreground3 # for page header's subsubtitle -button_background # for buttons -button_foreground # -button_select_foreground # -button_select_background # -button_disabled_foreground # -button_frame_background # for the buttons' frame -button_frame_select_foreground -button_frame_select_background -radio_button_foreground # for radio buttons -radio_button_background -radio_button_select_foreground -radio_button_select_background -radio_button_disabled_foreground -check_button_foreground # for check buttons -check_button_background -check_button_select_foreground -check_button_select_indicator -check_button_select_background -check_button_disabled_foreground -entry_foreground # for text entries -entry_background -entry_highlightbackground -entry_highlightcolor -entry_select_foreground -entry_select_background -relief # relief (see Tk man pages) for common elements -buttons_relief # relief (see Tk man pages) for buttons
Geometry of the parent window (values following are user in -geometry option):
-wish_width -wish_height -wish_x -wish_y
The WizardMaker can process pages of some predefined types. This is no really restriction - as you have access to the Programming Interface, you can design any page layouts.
TextPage
Pages of this type contain only a message text such as release notes or license agreements. Page specific options / attributes / elements: summary # Option. Text to display file # Option. File whith Text to display
LabeledEntriesPage
Pages of this type contain only entries to put single text. An entry can optionally have a button to search files and directories in file system. Page specific options / attributes / elements: LabeledEntry # Element with attributes: name # Internal name of element title # Label status # display status (normal or disabled) evaluate # when 1, the title will be evalueted befor displaying. button # predefined Button at right site # (at present only dir_select / file_open)
RadioButtonPage
Pages of this type contain only Radio Buttons. Page specific options / attributes / elements: RadioButton # Element with attributes: name # Internal name of element title # Label status # display status (normal or disabled) evaluate # when 1, the title will be evalueted befor displaying.
CheckButtonPage
Pages of this type contain only Check Buttons. Page specific options / attributes / elements: RadioButton # Element with attributes: name # Internal name of element title # Label status # display status (normal or disabled) evaluate # when 1, the title will be evalueted befor displaying.
ExternalPage
Pages of this type are of free layout. The WizardMaker don't knows how to build them. Use the method build_external_page() to build such pages.
new
It is simple the Tk - constructor. It creates new instance of WizardMaker. No pages are added yet. Parameters are -gui, -gui_file, -opt, -opt_file Usage Example: my $wizard = MainWindow->new()->WizardMaker(-gui_file=>'my_gui_file.xml');
build_all
Processes all options , creates all pages and shows the assistent Usage Example: $wizard->build_all();
add_all_pages
Processes all options , creates all pages Usage Example: $wizard->add_all_pages();
show
Shows the assistent Usage Example: $wizard->show();
build_node
Create only node structure. The only parameter is a hash reference to page attributes Usage Example: $wizard->build_node($p);
build_generic_node
Calls build_node and makes some preparations for common layout. This method should never be used directly. The only parameter is a hash reference to attributes of new page. Usage Example: $wizard->build_generic_node($p);
build_external_node
This procedure is intend to build page types not provided by WizardMaker themself. The only parameter is a hash reference to attributes of new page. Usage Example: $wizard->build_external_node($p);
link_node
All pages are bind together with double linked list. This method links a node on the given position. Paremeters are: page name how to link ('after', 'before') where to link (name, 'first', 'last') Usage Example: $wizard->link_node('myVeryFirstPage', 'before', 'first'); $wizard->link_node('myVeryLastPage', 'after', 'last'); $wizard->link_node('mySecondPage', 'after', 'myVeryFirstPage');
unlink_node
Unlinks a node from node list. The node can be accessed afterwards by its name. Usage Example: $wizard->unlink_node('myVeryFirstPage');
find_node
Returns name of searched page or undef if page does not exist. The only parameter is the description of node( name, 'first', 'last') Usage Example: my $page_name = $wizard->find_node('last');
first_node
Retutns the first node name in the node list Usage Example: my $page_name = $wizard->first_node();
last_node
Retutns the last node name in the node list Usage Example: my $page_name = $wizard->last_node();
current_node
Sets or returns the current node name in the node list Usage Example: my $page_name = $wizard->current_node(); $wizard->current_node('myNewPage');
is_linked
Retutns true if node is linked into the node list Usage Example: print 'I am insite' if ($wizard->is_linked('myGoodPage'));
add_text_page
After a node was created, a Text Page will be constructed. Parameters are: Page frame and page description - hash reference Usage Example: $wizard->add_text_page($pf, $p);
add_le_page
After a node was created, a labeled Entry Page will be constructed Parameters are: Page frame and page desctiption hash reference Usage Example: $wizard->add_le_page($pf, $p);
add_rb_page
After a node was created, a RadioButton Page will be constructed Parameters are: Page frame and page desctiption hash reference Usage Example: $wizard->add_rb_page($pf, $p);
add_cb_page
After a node was created, a CheckButton Page will be constructed Parameters are: Page frame and page desctiption hash reference Usage Example: $wizard->add_cb_page($pf, $p);
add_external_frame
After a node was created, an External Page will be constructed Parameters are: Page frame and page desctiption hash reference Usage Example: $wizard->add_external_frame($pf, $p); This method is usefull only if exists $p->{build_frame_code}. It must be a CODE REF.
add_radio_button
Adds a radio button to RadioButton Page Parameters are: target frame title variable behind the entry initial value of this variable state width of value Usage Example see in demo directory.
add_check_button
Adds a Check button to CheckButton Page Parameters are: target frame label text state, reference to the variable behind the entry width of title Usage Example see in demo directory.
drop_page
Drops a given page (inclusive node) The only parameter is the page name Usage Example: $wizard->drop_page('BadPage');
dir_select_dialog
opens dialog to help user to fild directory. Parameters are - reference to variable for directory name - Toplevel window title Usage Example see in demo directory.
file_open_dialog
opens standard system dialog to help user to fild a file. Parameters are - textvariable for file name - Toplevel window title Usage Example see in demo directory.
show_message
opens a message windows Parameters are message text type (info/help/warning/error) title text buttons description (see -type option of Tk::messageBox) Usage Example see in demo directory.
get_assistent_id
It is possible to have more than one WizardMaker instance opened by parallel. get_assistent_id returns an internal instance ID. Usage Example: $wizard->get_assistent_id();
get_common_element
Returns value of a commont element, so you can direct manipulate things like buttons and images. assistent_id - only usefull if you have more then one instance current_node - name of the current node total_pages - pages builded (not used) status - 'GOOD' or 'CANCELED' if WizardMaker was not finished propertly BUTTONS: button_back button_cancel button_help button_next FRAMES: main_frame user_frame command_frame deco_frame IMAGES (as Tk::Label): left_image top_image ALL PAGES (as HASH REFS): pages The only parameter is the name of common element Usage Example: $wizard->get_common_element('current_node');
cget_common_element
Returns current value of given common element options. Just like cget. This method is only usefull for common elements - Tk objects. Parameters are the element name and option name. Usage Example: $wizard->cget_common_element('left_image', 'image');
configure_common_element
Manipulate common element options. Just like configure. Parameters are the element name and an option list. Usage Example: my $image = $wizard->Photo('other_image', -file=>'other_image.gif'); $wizard->configure_common_element('left_image', ('image', $image));
add_common_element
Adds a new common element. Parameter are element name and its value. The Value can be an object reference too. Usage Example: $wizard->add_common_element('newHiddenStatusElement', 'OK');
drop_common_element
Removes common element. All packed subelements are forgotten. Usage Example: $wizard->drop_common_element('newHiddenStatusElement');
set_common_image
Sets left/top image. The left_image and right_image are common elements shown at the left site of WizardMaker's first and last pages and on the top of all other pages. The images are static, but you can manipulate them dynamic with this method. Alternative you can use get_common_element() and configure_common_element(). Parameters are: - position (can be 'top' or 'left'), - image name - image file Usage Example: In the XML description of a page: <page name="this_page" status="normal" type="TextPage" title="This Page" subtitle="This Page Subtitle" pre_next_button_code=" $self->set_common_image('top', 'next_picture', 'next_picture.gif'); 1; " />
reset_buttons
Resets visual options of standard buttons to defaults. Paremeter is list of button names. If ommited, all buttons (button_back, button_cancel, button_help, button_next) will be reseted.
get_page
Returns page as Object ref. The only parameter is the page name Usage Example: $wizard->get_page('myPage');
get_page_element
Returns page element as Object Reference Parameters are the page name and element description. The element description can be element name or one of following RadioButton CheckButton LabeledEntry summary_text. In the last case the third parameter - subelement should be used. Usage Example see in demo directory.
cget_tk_element
Returns current value of given element options. Just like cget. Parameters are the element reference (like given by get_page_element) and the option name. Usage Example see in demo directory.
configure_tk_element
Manipulate the Title of a builded page. Just like configure. Parameters are the element reference (like given by get_page_element) and an option list. Usage Example see in demo directory.
get_user_frame
Returns the user frame of given page. The user frame is a part of page frame. The only parameter is page name.
gui_option
Get or set GUI option. Usefull for programmatic manipulation of GUI values. The initial values are set normally over OPT.XML file. The options are placed in WizardMaker as $self->{opt}->{gui}->{$option_name}->{$option_value} Parameters are option name and option value. Usage Example see in demo directory.
get_page_frame
Returns page frame as Object. The only parameter is page name. Usage Example see in demo directory.
Tk XML::Simple (requires XML::Parser and File::Spec) Data::Dumper Storable Win32 (Win32 plattform only) Win32API::File (Win32 plattform only)
XML::Simple, Tk::Wizard
Viktor Zimmermann, <ZiMTraining@gmx.net>
Copyright 2004 by Viktor Zimmermann
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Tk::XML::WizardMaker, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Tk::XML::WizardMaker
CPAN shell
perl -MCPAN -e shell install Tk::XML::WizardMaker
For more information on module installation, please visit the detailed CPAN module installation guide.