QWizard(3) User Contributed Perl Documentation QWizard(3)NAMEQWizard - Display a series of questions, get the answers, and act on
the answers.
SYNOPSIS
#
# The following code works as a application *or* as a CGI script both:
#
use QWizard;
my %primaries =
(
starting_node =>
{ title => "starting here",
introduction => "foo bar",
questions =>
[{ type => 'text',
name => 'mytext',
text => 'enter something:',
default => "hello world" },
{ type => 'checkbox',
text => 'yes or no:',
values => ['yes','no'],
name => 'mycheck'} ],
actions =>
[sub { return [
"msg: text = " . qwparam('mytext'),
"msg: checkbox = " . qwparam('mycheck')
];}]
}
);
my $qw = new QWizard(primaries => \%primaries,
title => "window title");
$qw->magic('starting_node');
#
# PLEASE see the examples in the examples directory.
#
DESCRIPTIONQWizard displays a list of grouped questions, and retrieves and
processes user-specified answers to the questions. Multiple
question/answer sets may be displayed before the answers are dealt
with. Once a "commit" action is taken (instigated by the user), a
series of actions is performed to handle the answers. The actions are
executed in the order required by the QWizard programmer.
QWizard's real power lies in its inherent ability to keep track of all
state information between one wizard screen and the next, even in
normally stateless transaction environments like HTTP and HTML. This
allows a QWizard programmer to collect a large body of data with a
number of simple displays. After all the data has been gathered and
verified, then it can be handled as appropriate (e.g., written to a
database, used for system configuration, or used to generate a graph.)
Current user interfaces that exist are HTML, Gtk2, Tk, and (minimally)
ReadLine. A single QWizard script implementation can make use of any
of the output formats without code modification. Thus it is extremely
easy to write portable wizard scripts that can be used without
modification by both graphical window environments (Gtk2 and Tk) and
HTML-based web environments (e.g., CGI scripts.), as well with
intercative command line enviornments (ReadLine).
Back-end interfaces (child classes of the QWizard::Generator module)
are responsible for displaying the information to the user. Currently
HTML, Gtk2, Tk and ReadLine, are the output mechanisms that work the
best (in that order). Some others are planned (namely a curses
version), but are not far along in development. Developing new
generator back-ends is fairly simple and doesn't take a lot of code
(assuming the graphic interface is fairly powerful and contains a
widget library.)
QWizard operates by displaying a series of "screens" to the user. Each
screen is defined in a QWizard construct called a primary that
describes the attributes of a given screen, including the list of
questions to be presented to the user. Primaries can contain
questions, things to do immediately after the questions are answered
(post_answers), and things to do once the entire series of screens have
been answered (actions). Other information, such as a title and an
introduction, can also be attached to a primary.
An example very minimal primary definition containing one question:
my %primaries = (
myprimary =>
{
title => "my screen title",
introduction => "optional introduction to the screen",
questions =>
[
{
type => 'checkbox',
text => 'Should the chicken cross the road?',
}
],
}
After defining a set of primaries, a new QWizard object must be
created. The QWizardnew() constructor is given a set of options, such
as window title and a reference to a hash table containing the
primaries. (The complete set of options may be found in the "QWizard
new() Options" section.) The question display and data collection is
started by calling the magic() routine of the new QWizard object.
my $qw = new QWizard(primaries => \%primaries,
title => 'my title');
$qw->magic('myprimary');
There are examples distributed with the QWizard module sources that may
help to understand the whole system and what it is capable of. See the
examples directory of the QWizard source code tree for details. Also,
QWizard was written mostly due to requirements of the Net-Policy
project. Net-Policy makes very extensive use of QWizard and is another
good place to look for examples. In fact, the QWizard CVS code is
located inside the Net-Policy CVS tree. See
http://net-policy.sourceforge.net/ for details on the Net-Policy
project. There are a number of screen shots showing all the interfaces
as well on the main net-policy web site.
MAGIC() PSEUDO-CODE
A pseudo-code walk-through of the essential results of the magic()
routine above is below. In a CGI script, for example, the magic()
routine will be called multiple times (once per screen) but the results
will be the same in the end -- it's all taken care of magically ;-).
################
## WARNING: pseudo-code describing a process! Not real code!
################
# Loop through each primary and display the primary's questions.
while(primaries to process) {
display_primary_questions();
get_user_input();
check_results();
run_primary_post_answers();
}
# Displays a "will be doing these things" screen,
# and has a commit button.
display_commit_screen();
# Loop through each primary and run its actions.
# Note: see action documentation about execution order!
foreach (primary that was displayed) {
results = run_primary_actions();
display(results);
}
# If magic() is called again, it restarts from
# the top primary again.
QWIZARD NEW() OPTIONS
Options passed to the QWizardnew() operator define how the QWizard
instance will behave. Options are passed in the following manner:
new QWizard (option => value, ...)
Valid options are:
title => "document title"
The document title to be printed in the title bar of the window.
generator => GENERATOR
GENERATOR is a reference to a valid QWizard generator. Current
generator classes are:
- QWizard::Generator::Best (default: picks the best available)
- QWizard::Generator::HTML
- QWizard::Generator::Gtk2
- QWizard::Generator::Tk
- QWizard::Generator::ReadLine (limited in functionality)
The QWizard::Generator::Best generator is used if no specific
generator is specified. The Best generator will create an HTML
generator if used in a web context (i.e., a CGI script), or else
pick the best of the available other generators (Gtk2, then Tk,
then ReadLine).
This example forces a Gtk2 generator to be used:
my $wiz = new QWizard(generator => new QWizard::QWizard::Gtk2(),
# ...
);
generator_args => [ARGS],
If you want the default generator that QWizard will provide you,
but would still like to provide that generator with some arguments
you can use this token to pass an array reference of arguments.
These arguments will be passed to the new() method of the Generator
that is created.
top_location => "webaddress"
This should be the top location of a web page where the questions
will be displayed. This is needed for "go to top" buttons and the
like to work. This is not needed if the QWizard-based script is
not going to be used in a CGI or other web-based environment (eg,
if it's going to be used in mod_perl).
primaries => \%my_primaries
my_primaries will define the list of questions to be given to the
user. my_primaries just defines the questions, but does not mean
the user will be prompted with each question. The questions in
this series that will be displayed for the user to answer is
determined by the magic() function's starting arguments, described
below. The format of the primaries hash is described in the
Primaries Definition section below. The recognized values in the
primaries hash is described in the Primaries Options section.
no_confirm => 1
If set, the final confirmation screen will not be displayed, but
instead the resulting actions will be automatically run. This can
also be achieved inside the wizard tokens primaries by setting a
question name to no_confirm with a value of 1 (using a hidden
question type.)
begin_section_hook => \&subroutine
This function will be called just before each screen is displayed.
It can be used to perform such functions as printing preliminary
information and initializing data.
end_section_hook => \&subroutine
This function will be called just after a set of questions is
displayed.
topbar
A place to add extra widgets to a primary at the very top.
See the bar documentation in the QUESTION DEFINITIONS section below
for details on this field.
leftside => [WIDGETS]
rightside => [WIDGETS]
Adds a left or right side frame to the main screen where the
WIDGETS are always shown for all primaries. Basically, these
should be "axillary" widgets that augment the widgets is the main
set of questions. They can be used for just about anything, but
the look and feel will likely be better if they're suplimental.
The WIDGETS are normal question widgets, just as can appear in the
questions section of the primaries definition as described below.
In addition, however, there can be subgroupings with a title as
well. These are then in a sub-array and are displayed with a title
above them. EG:
leftside => [
{ type => 'button',
# ... normal button widget definition; see below
},
[
"Special Grouped-together Buttons",
{ type => 'button',
# ...
},
{ type => 'button',
# ...
},
],
],
The above grouped set of buttons will appear slightly differently
and grouped together under the title "Special Grouped-together
Buttons".
The widget-test-screen.pl in the examples directory shows examples
of using this.
Important note: Not all backends support this yet. HTML and Gtk2
do, though.
PRIMARIES DEFINITION
The primaries argument of the new() function defines the list of
questions that may be posed to a user. Each primary in the hash will
contain a list of questions, answers, etc., and are grouped together by
a name (the key in the hash). Thus, a typical primary set definition
would look something like:
%my_primaries =
(
# The name of the primary.
'question_set_1' =>
# its definition
{
title => 'My question set',
questions =>
# questions are defined in an array of hashes.
[{type => 'checkbox',
text => 'Is this fun?',
name => is_fun,
default => 1,
values => [1, 0] },
{type => 'text',
text => 'Enter your name:',
name => 'their_name'}],
post_answers =>
# post_answers is a list of things to do immediately after
# this set of questions has been asked.
[ sub { print "my question set answered" } ],
actions =>
# actions is a list of actions run when all is said and done.
[ sub {
return "msg: %s thinks this %s fun.\n",
qwparam('their_name'),
(qwparam('is_fun')) ? "is" : "isn't"
}],
actions_descr =>
# An array of strings displayed to the user before they agree
# to commit to their answers.
[ 'I\'m going to process stuff from @their_name@)' ]
});
See the QWizard::API module for an alternative, less verbose, form of
API for creating primaries which can produce more compact-looking code.
VALUE conventions
In the documentation to follow, any time the keyword VALUE appears, the
following types of "values" can be used in its place:
- "a string"
- 10
- \&sub_to_call
- sub { return "a calculated string or value" }
- [\&sub_to_call, arguments, to, sub, ...]
Subroutines are called and expected to return a single value or an
array reference of multiple values.
Much of the time the VALUE keyword appears in array brackets: []. Thus
you may often specify multiple values in various ways. E.g., a values
clause in a question may be given in this manner:
sub my_examp1 { return 3; }
sub my_examp2 { return [$_[0]..$_[1]]; }
values => [1, 2, \&my_examp1, [\&my_examp2, 4, 10]],
After everything is evaluated, the end result of this (complex) example
will be an array passed of digits from 1 to 10 passed to the values
clause.
In any function at any point in time during processing, the qwparam()
function can be called to return the results of a particular question
as it was answered by the user. I.e., if a question named their_name
was answered with "John Doe" at any point in the past series of wizard
screens, then qwparam('their_name') would return "John Doe". As most
VALUE functions will be designed to process previous user input,
understanding this is the key to using the QWizard Perl module. More
information and examples follow in the sections below.
PRIMARY OPTIONS
These are the tokens that can be specified in a primary:
title => VALUE
The title name for the set of questions. This will be displayed at
the top of the screen.
introduction => VALUE
Introductory text to be printed above the list of questions for a
given primary. This is useful as a starting piece of text to help
the user with this particular wizard screen. Display of the
introductory text is controlled by the Net-Policy pref_intro user
preference. The default is to display introductory text, but this
setting can be turned off and on by the user.
questions => [{ QUESTION_DEFINITION }, { QUESTION_DEFINITION }, ...]
This is a list of questions to pose to the user for this screen.
The Question Definitions section describes valid question
formatting.
post_answers => [ VALUES ]
This is a list of actions to run after the questions on the screen
have been answered. Although this is a VALUES clause, as described
above, these should normally be subroutines and not hard-coded
values. The first argument to the VALUE functions will be a
reference to the wizard. This is particularly useful to
conditionally add future screens/primaries that need to be shown to
the user. This can be done by using the following add_todos()
function call in the action section:
if (some_condition()) {
$_[0]->add_todos('primary1', ...);
}
See the QWizard Object Functions section for more information on
the add_todos() function, but the above will add the 'primary1'
screen to the list of screens to display for the user before the
wizard is finished.
A post_answers subroutine should return the word "OK" for it to be
successful (right now, this isn't checked, but it may be (again) in
the future). It may also return "REDISPLAY" which will cause the
screen to displayed again.
For HTML output, these will be run just before the next screen is
printed after the user has submitted the answers back to the web
server. For window-based output (Gtk2, Tk, etc.) the results are
similar and these subroutines are evaluated before the next window
is drawn.
check_value => sub { ... }
check_value => [sub { ... }, arg1, arg2, ...]
The primary may have a check_value clause assigned to it to do high
level consistency checks. Returning anything but "OK" will have
the returned text displayed as an error to the user that they
should fix before they're allowed to continue past the screen.
actions => [ VALUES ]
The action functions will be run after the entire wizard series of
questions has been displayed and answered and after the user has
hit the "commit" button. It is assumed that the actions of the
earlier screens are dependent on the actions of the later screens
and so the action functions will be executed in reverse order from
the way the screens were displayed. See the add_todos() function
description in the QWizard Object Functions section for more
information on to change the order of execution away from the
default.
The collected values returned from the VALUES evaluation will be
displayed to the user. Any message beginning with a 'msg:' prefix
will be displayed as a normal output line. Any value not prefixed
with 'msg:' will be displayed as an error (typically displayed in
bold and red by most generators.)
actions_descr => [ VALUES ]
Just before the actions are run, a change-summary screen is shown
to the user. A "commit" button will also be given on this screen.
VALUE strings, function results, etc., will be displayed as a list
on this commit screen. Strings may have embedded special @TAG@
keywords which will be replaced by the value for the question with
a name of TAG. These strings should indicate to the user what the
commit button will do for any actions to be run by this set of
questions. If any question was defined whose name was no_confirm
and whose value was 1, this screen will be skipped and the actions
will be run directly.
sub_modules => [ 'subname1', ... ]
This hash value adds the specified sub-modules to the list of
screens to display after this one. This is equivalent to having a
post_answers clause that includes the function:
sub { $_[0]->add_todos('subname1', ...); }
doif => sub { LOGIC }
Allows primaries to be optional and only displayed under certain
conditions.
If specified, it should be a CODE reference which when executed
should return a 1 if the primary is to be displayed or a 0 if not.
The primary will be entirely skipped if the CODE reference returns
a 0.
topbar
A place to add extra widgets to a primary at the very top.
See the bar documentation in the QUESTION DEFINITIONS section below
for details on this field.
leftside => [WIDGETS]
rightside => [WIDGETS]
Adds a left or right side frame to the main screen where the
WIDGETS are shown for this primary.
Important note: See the leftside/rightside documentation for
QWizard for more details and support important notes there.
take_over => \&subroutine
This hash value lets a subroutine completely take control of
processing beyond this point. The wizard methodology functionally
stops here and control for anything in the future is entirely
passed to this subroutine. This should be rarely (if ever) used
and it is really a way of breaking out of the wizard completely.
QUESTION DEFINITIONS
Questions are implemented as a collection of hash references. A
question generally has the following format:
{
type => QUESTION_TYPE
text => QUESTION_TEXT,
name => NAME_FOR_ANSWER,
default => VALUE,
# for menus, checkboxes, multichecks, ... :
values => [ VALUE1, VALUE2, ... ], # i.e., [VALUES]
# for menus, checkboxes, multichecks, ... :
labels => { value1 => label1, value2 => label2 } # i.e., [VALUES]
}
Other than this sort of hash reference, the only other type of question
allowed in the question array is a single "" empty string. The empty
string acts as a vertical spatial separator, indicating that a space
should occur between the previous question and the next question.
The fields available to question types are given below. Unless
otherwise stated, the fields are available to all question types.
name => 'NAME'
Names the answer to the question. This name can then be used later
in other sections (action, post_answers, etc.) to retrieve the
value of the answer using the qwparam() function. For example,
qwparam('NAME') at any point in future executed code should return
the value provided by the user for the question named 'NAME'.
The namespace for these names is shared among all primaries (except
'remapped' primaries, which are described later). A warning will
be issued if different questions from two different primaries use
the same name. This warning will not be given if the question
contains an override flag set to 1.
text => 'QUESTION TEXT'
Text displayed for the user for the given question. The text will
generally be on the left of the screen, and the widget the user is
supposed to interact with will be to the question text's right.
(This is subject to the implementation of the back-end question
Generator. The standard QWizard generators use this layout
scheme.)
type => 'TYPE'
Defines the type of question. TYPE can be one of:
label Displays information on the screen without requesting any
input. The text of the question is printed on the left
followed by the values portion on the right. If the values
portion is omitted, the text portion is printed across the
entire width of the screen.
paragraph
Paragraphs are similar to labels but are designed for
spaces where text needs to be wrapped and is likely to be
quite long.
text Text input. Displays an entry box where a standard single
line of text can be entered.
textbox Text input, but in a large box allowing for multi-line
entries.
hidetext
Obscured text input. Displays a text entry box, but with
the typed text echoed as asterisks. This is suitable for
prompting users for entering passwords, as it is not shown
on the screen.
checkbox
A checkbox. The values clause should have only 2 values in
it: one for its "on" value, and one for its "off" value
(which defaults to 1 and 0, respectively).
The button_label clause can specify text to put right next
to the checkbox itself.
If a backend supports key accelerators (GTk2): Checkbox
labels can be bound to Alt-key accelerators. See QUESTION
KEY-ACCELERATORS below for more information.
multi_checkbox
Multiple checkboxes, one for each label/value pair. The
name question field is a prefix, and all values and/or
label keywords will be the second half of the name.
For example, the following clauses:
{
type => 'multi_checkbox',
name => 'something',
values => ['end1','end2'],
...
}
will give parameters of 'somethingend1' and
'somethingend2'.
If a backend supports key accelerators (GTk2): Checkbox
labels can be bound to Alt-key accelerators. See QUESTION
KEY-ACCELERATORS below for more information.
radio Radio buttons, only one of which can be selected at a time.
If two questions have the same name and are of type
'radio', they will be "linked" together such that clicking
on a radio button for one question will affect the other.
If a backend supports key accelerators (GTk2): Radio button
labels can be bound to Alt-key accelerators. See QUESTION
KEY-ACCELERATORS below for more information.
menu Pull-down menu, where each label is displayed as a menu
item. If just the values clause (see below) is used, the
labels on the screen will match the values. If the default
clause is set, then that menu entry will be the menu's
initial selection. If the labels clause is used, the
values shown to the user will be converted to the screen
representations that will differ from the qwparam() values
available later. This is useful for displaying human
representations of programmatic values. E.g.:
{
type => 'menu',
name => 'mymenu',
labels => [ 1 => 'my label1',
2 => 'my label2']
}
In this example, the user will see a menu containing 2
entries "my label1" and "my label2", but qwparam() will
return 1 or 2 for qwparam('mymenu').
table Table to display. The values section should return a
reference to an array, where each element of the array is a
row containing the columns to display for that row. The
top-most table must actually be returned in an array
itself. (This is due to an oddity of internal QWizard
processing). E.g.:
{
type => 'table',
text => 'The table:',
values => sub {
my $table = [['row1:col1', 'row1:col2'],
['row2:col1', 'row2:col2']];
return [$table];
}
}
This would be displayed graphically on the screen in this
manner:
row1:col1 row1:col2
row2:col1 row2:col2
Additionally, a column value within the table may itself be
a sub-table (another double-array reference set) or a hash
reference, which will be a sub-widget to display any of the
other types listed in this section.
Finally, a headers clause may be added to the question
definition which will add column headers to the table.
E.g.:
headers => [['col1 header','col2 header']]
fileupload
A dialog box for a user to upload a file into the
application. When a user submits a file the question name
can be used later to retrieve a read file handle on the
file using the function qw_upload_fh('NAME').
qwparam('NAME') will return the original name of the file
submitted, but because of the variability in how web-
browsers submit file names along with the data, this field
should generally not be used. Instead, get access to the
data through the qw_upload_fh() function instead. The
second best alternative is to use the
qw_upload_file('NAME') function which returns a safe path
to access under web-environments (which will be something
like /tmp/qwHTMLXXXXXX...)
filedownload
A button that allows the user to download something
generated by the application. The data that will be stored
in this file should be defined in the 'data' field or the
'datafn' field. The name displayed within the button will
be taken from the default question parameter.
The data field is processed early during display of the
screen, so generation of large sets of data that won't
always be downloaded or will take a lot of memor shouldn't
use the data field. The data field is processed like any
other value field where raw data or a coderef can be passed
that will be called to return the data.
The datafn field should contain a CODE reference that will
be called with five arguments:
a IO::File filehandle to print to
the file name (if appropriate) it's going to print to.
a QWizard object reference
a reference to the primary hash
a reference to the question hash
Example usage:
{ type => 'filedownload',
text => 'Download a file:',
datafn =>
sub {
my $fh = shift;
print $fh "hello world: val=" . qwparam('someparam') . "\n";
}
},
Currently only Gtk2 supports this button, but others
will in the future.
image
Image file. The image name is specified by the image
hash keyword. Several optional hash keys are
recognized to control display of the image. imagealt
specifies a string to display if the image file is not
found. height specifies the height of the image.
width specifies the width of the image. (height and
width are currently only implemented for HTML.)
graph
Graph of passed data. This is only available if the
GD::Graph module is installed. Data is passed in from
the values clause and is expected to be an array of
arrays of data, where the first row is the x-axis data,
and the rest are y values (one line will be drawn for
each y value).
Additionally, the GD::Graph options can be specified
with a graph_options tag to the question, allowing
creation of such things as axis labels and legends.
tree
Hierarchical tree. Displays a selectable hierarchical
tree set from which the user should pick a single item.
Two references to subroutines must be passed in via the
parent and children question tags. Also, a root tag
should specify the starting point.
Widget Options:
parent => CODEREF
The parent function will be called with a wizard
reference and a node name. It is expected to
return the name of the node's parent.
The function should return undef when no parent
exists above the current node.
children => CODEREF
The children function will be passed a wizard
reference and a node name. It is expected to
return an array reference to all the children
names. It may also return a hash reference for
some names instead, which will contain an internal
name tag along with a label tag for displaying
something to the user which is different than is
internally passed around as the resulting selected
value.
An example return array structure could look like:
[
'simple string 1',
'simple string 2',
{
name => 'myanswer:A',
label => 'Answer #A'
},
{
name => 'myanswer:B',
label => 'Answer #B'
},
]
The function should return undef when no children
exist below the current node.
expand_all => NUM
The expand_all tag may be passed which will
indicate that all initial option trees sholud be
expanded up to the number indicated by the
expand_all tag.
button
Button widget. When the button is clicked, the QWizard
parameter name (available by calling qwparam('name'))
will be assigned the value indicated by the default
clause. The parameter value will not be set if the
button is not clicked. The button's label text will be
set to the value of the values clause.
The button widget will be equivalent to pressing the
next button. The next primary will be shown after the
user presses the button.
If a backend supports key accelerators (GTk2): Button
labels can be bound to Alt-key accelerators. See
QUESTION KEY-ACCELERATORS below for more information.
bar A bar widget is functionally a separator in the middle
of the list of questions. It is useful for breaking a
set of questions in two as well as providing button-
containers or menu containers within widget sets and
not having them tied to the normal QWizard left/right
feel. One intentional artifact of this is they can be
used to provide a visual difference between the flow of
the questions. EG, if the QWizard primary showed a
screen which had two questions in it, it would look
something like the following when displayed by most of
the generators that exist today:
+-------------------+-----------------+
| Question 1 | Answer Widget 1 |
| Longer Question 2 | Answer Widget 2 |
+-------------------+-----------------+
Adding a bar in the middle of these questions, however,
would break the forced columns above into separate
pieces:
+------------+------------------------+
| Question 1 | Answer Widget 1 |
+------------+------------------------+
| BAR |
+-------------------+-----------------+
| Longer Question 2 | Answer Widget 2 |
+-------------------+-----------------+
Finally, there is an implicit top bar in every primary
and the QWizard object as a whole. You can push
objects onto this bar by adding objects to the
$qwizard->{'topbar'} array or by adding objects to a
primary's 'topbar' tag. E.G.
my $qw = new QWizard(primaries => \%primaries,
topbar => [
{
type => 'menu', name => 'menuname',
values => [qw(1 2 3 4)],
# ...
}]);
The widgets shown in the topbar will be a merge of
those from the QWizard object and the primary currently
being displayed.
TODO: make it work better with merged primaries
TODO: make a bottom bar containing the next/prev/cancel
buttons
hidden
This clause is used to set internal parameters (name =>
value), but these values are not shown to the user.
Note: This is not a secure way to hide information
from the user. The data set using hidden are
contained, for example, in the HTML text sent to the
user.
dynamic
A dynamic question is one where the values field is
evaluated and is expected to return an array of
question definitions which are in turn each evaluated
as a question. It is useful primarily when doing
things like creating a user-defined number of input
fields, or interacting with an external data source
where the number of questions and their nature is
directly related to the external data source.
raw Raw data. The values portion is displayed straight to
the screen. Use of this is strongly discouraged.
Obviously, the values portion should be a subroutine
that understands how to interact with the generator.
Really, don't use this. It's for emergencies only. It
only works with HTML output.
values => [ VALUES ]
An array of values that may be assigned to question types
that need choices (eg: menu, checkbox, multi_checkbox.) It
should be a reference to an array containing a list of
strings, functions to execute, and possibly sub-arrays
containing a function and arguments, as described by the
VALUE conventions section above. Any function listed in a
values clause should return a list of strings.
The values clause is not needed if the labels clause is
present.
labels => [ VALUE1 => 'LABEL1', VALUE2 => 'LABEL2', ... ]
Assigns labels to the question's values. Labels are
displayed to the user instead of the raw values. This is
useful for converting human-readable text strings into
real-world values for use in code.
If the values clause is not specified and the labels clause
is, the values to display are extracted from this labels
clause directly. If a value from the values clause does
not have a corresponding label, the raw value is presented
and used instead. Generally, only the labels clause should
be used with radio buttons, menus, or check boxes; but
either or both in combination work.
The labels clause subscribes to all the properties of the
VALUES convention previously discussed. Thus, it may be a
function, an array of functions, or any other type of data
that a VALUE may be. The final results should be an array,
especially if the values clause is not present, as the
order displayed to the user can be specified. It can also
be a hash as well but the displayed order is subject to
Perl keys() conventions and thus an array is preferred when
no values clause has been defined.
default => VALUE
The default value to use for this question. It may be a
subroutine reference which will be called to calculate and
return the value.
check_value => \&subroutine
A script to check the answer submitted by the user for
legality. The script should return 'OK' to indicate no
error found. In the event an error is detected, it should
return an error string. The string will be shown to the
user as an error message that the user must fix before
being allowed to proceed further in the wizard screens.
Alternately, the script may return 'REDISPLAY' to indicate
no error but that screen should be redisplyed (perhaps with
new values set with qwparam() from within the script). In
the case of error or 'REDISPLAY', the current primary
screen will be repeated until the function returns 'OK'.
The arguments passed to the function are the reference to
the wizard, a reference to the question definition (the
hash), and a reference to the primary containing the
question (also a hash.) The function should use the
qwparam() function to obtain the value to check. An array
can be passed in which the first argument should be the
subroutine reference, and the remaining arguments will be
passed back to the subroutine after the already mentioned
default arguments.
There are a set of standard functions that can be used for
checking values. These are:
\&qw_required_field
Ensures that a value is supplied or else a "This is a
required field" error message is returned. The
function only checks that the value is non-zero in
length.
\&qw_integer
\&qw_optional_integer
Ensures that the value is an integer value (required or
not, respectively.)
\&qw_hex
\&qw_optional_hex
Ensures that the value is a hex string (required or
not, respectively.)
[\&qw_check_hex_and_length, length]
Ensures that a value is supplied and is a hex string
sufficiently long for length bytes. This means that the
hex string must be "length * 2" ASCII characters (two
hex characters per byte.)
[\&qw_check_int_ranges, low1, high1, low2, high2, ...]
Ensures that the value specified falls within one of
the lowX - highX ranges. The value must be between
(low1 and high1) or (low2 and high2).
[\&qw_check_length_ranges, low1, high1, low2, high2, ...]
qw_check_length_ranges is similar to
qw_check_int_ranges(), but it checks that the length of
the data string specified by the user falls within the
given ranges.
doif => sub { LOGIC }
Allows questions to be optional and only displayed under
certain conditions.
If specified, it should be a CODE reference which when
executed should return a 1 if the question is to be
displayed or a 0 if not. The question will be entirely
skipped if the CODE reference returns a 0.
helptext =item helpdescr
If specified, these define the help text for a question.
helpdescr should be short descriptions printed on screen
when the wizard screen is displayed, and helptext should be
a full length description of help that will be displayed
only when the user clicks on the help button. helpdescr is
optional, and a button will be shown linking to helptext
regardless.
indent => 1
Slightly indents the question for some generators.
submit => 1
When this is specified as a question argument, if the user
changes the value then it will also be the equivelent of
pressing the 'Next' button at the same time. With the HTML
generator, this requires javascript and thus you shouldn't
absolutely depend on it working.
refresh_on_change => 1
If the contents of a screen are generated based on data
extracted from dynamically changing sources (e.g., a
database), then setting this parameter to 1 will make the
current question force a refresh if the value changes (ie,
when they pull down a menu and change the value or click on
a checkbox or ...) and the screen be redrawn (possibly
changing its contents).
As an example, Net-Policy uses this functionality to allow
users to redisplay generated data tables and changes the
column that is used for sorting depending on a menu widget.
handle_results => sub { ... }
The handle_results tag can specify a CODE reference to be
run when the questions are answered so each question can
perform its own processing. This is sort of like a per-
question post_answers hook equivalent.
QUESTION KEY-ACCELERATORS
Some generators (currently only Gtk2 actually) support key accelerators
so that you can bind alt-keys to widgets. This is done by including a
'_' (underscore) character where appropriate to create the binding.
EG:
{
type => 'radio',
text => 'select one:',
values => ['_Option1','O_ption2', 'Option3']
}
When Gtk2 gets the above construct it will make Alt-o be equivelent to
pressing the first option and Alt-p to the second. It will also
display the widget with a underline under the character that is bound
to the widget. HTML and other non-accelerator supported interfaces
will strip out the _ character before displaying the string in a
widget.
In addition, unless a no_auto_accelerators = 1> option is passed to the
generator creation arguments, widgets will automatically get
accelerators assigned to them. In the above case the 't' in Option3
would automatically get assigned the Alt-t accelerator (the 't' is
selected because it hasn't been used yet, unlike the o and p
characters). You can also prefix something with a ! character to force
a single widget to not receive an auto-accelerator (EG: "!Option4"
wouldn't get one).
SPECIAL VARIABLES
A few QWizard parameters are special and help control how QWizard
behaves. Most of these should be set in the primaries question sets
using a hidden question type.
no_actions
If set to 1, the actions phase will not be run.
no_confirm
If set to 1, the screen which prompts the user to decide if they
really want to commit their series of answers won't be shown.
Instead, QWizard will jump straight to the actions execution (if
appropriate.) This can also be given as a parameter to the QWizardnew() function to make it always true.
allow_refresh
If the contents of a screen are generated based on data extracted
from dynamically changing sources (e.g., a database), then setting
this parameter to 1 will add a "Refresh" button beside the "Next"
button so that the user can request the screen be redrawn (possibly
changing its contents).
As an example, Net-Policy uses this functionality to allow users to
redisplay generated graphs and maps that will change dynamically as
network data are collected.
This token can also be set directly in a primary definition to
affect just that primary screen.
QWizard_next
The button text to display for the "Next" button. This defaults to
"_Next" but can be overridden using this parameter.
QWizard_commit
The button text to display for the "Commit" button. This defaults
to "_Commit" but can be overridden using this parameter. The
commit button is shown after the questions have been asked and the
actions_descr's are being shown to ask the user if they really want
to run the actions.
QWizard_finish
The button text to display for the "Finish" button. This defaults
to "_Finish" but can be overridden using this parameter. The
finish button is shown after the actions have been run and the
results are being displayed.
QWIZARD RESERVED VARIABLES
The following parameters are used internally by QWizard. They should
not be modified.
pass_vars
qw_cancel
no_cancel
qwizard_tree
display_help_p
disp_q_num
redo_screen
upd_time
wiz_confirmed
wiz_canceled
wizard_queue_list
QWizard OBJECT FUNCTIONS
The following functions are defined in the QWizard class and can be
called as needed.
$qw->magic(primary_name, ...);
This tells QWizard to start its magic, beginning at the primary
named primary_name. Multiple primaries will be displayed one after
the other until the list of primaries to display is empty. The
actions clauses of all these primaries will not be run, however,
until after all the primaries have been processed.
The magic() routine exits only after all the primaries have been
run up through their actions, or unless one of the following
conditions occurs:
- $qw->{'one_pass'} == 1
- $qw->{'generator'}{'one_pass'} == 1
By default, some of the stateless generators (HTML) will set their
one_pass option automatically since it is expected that the client
will exit the magic() loop and return later with the next set of
data to process. The magic() routine will automatically restart
where it left off if the last set of primaries being displayed was
never finished. This is common for stateless generators like HTTP
and HTML.
$qw->finished();
Closes the open qwizard window. Useful after your magic() routine
has ended and you don't intend to call it again. Calling
finished() will remove the QWizard window from visibility.
$qw->set_progress(FRACTION, TEXT);
If available, some generators (Gtk2 can) may be able to display a
progress meter. If they are, calling this function inside action
clauses, for example, will start the display of this meter with
FRACTION complete (0 <= FRACTION <= 1). The TEXT is optional and
if left blank will be set to NN% showing the percentage complete.
$qw->add_todos([options], primary_name, ...);
Adds a primary to the list of screens to display to the user. This
function should be called during the post_answers section of a
primary. Options that can be passed before the first primary name
are:
-early
Adds the primaries in question as early as possible in the todo
list (next, unless trumped by future calls.) This is the
default.
-late
Adds the primary to the end of the list of primaries to call,
such that it is called last, unless another call to add_todos()
appends something even later.
-actionslast
All the actions of subsequent primaries that have been added as
the result of a current primary's post_answers clauses are
called before the actions for the current primary. This means
that the actions of any childrens are executed prior to the
actions of their parents. This is done by default, as the
general usage prediction is that parent primaries are likely to
be dependent on the actions of their children in order for
their own actions to be successful.
However, this flag indicates that the actions of the childrens'
primaries listed in this call are to be called before the
current primary's actions.
-merge
Merges all the specified primaries listed into a single screen.
This has the effect of having multiple primaries displayed in
one window.
Important note: you can not use both -remap (see below) and
-merge at the same time! This will break the remapping support
and you will not get expected results!
-remap => 'NAME'
If a series of questions must be called repeatedly, you can use
this flag to remap the names of the child primary questions to
begin with this prefix. The children's clauses (questions,
actions, post_answers, etc.) will be called in such a way that
they can be oblivious to the fact this is being done behind
their backs, allowing qwparam() to work as expected. However,
for the current primary (and any parents), the 'NAME' prefix
will be added to the front of any question name values that the
child results in defining.
This is rather complex and is better illustrated through an
example. There is an example that illustrates this in the
QWizard Perl module source code examples directory, in the file
number_adding.pl. This code repeatedly asks for numbers from
the user using the same primary.
Important note: you can not use both -remap and -merge at the
same time! This will break the remapping support and you will
not get expected results!
$qw->add_primary(key => value, key => value);
Adds a primary definition into the existing primary data set for
the QWizard object. One key value pair MUST be a 'name' => 'NAME'
pair, where NAME will be the installed primary name for later
referral (e.g., in add_todos() calls.) If a name collision takes
place (a primary already exists under the given name), the original
is kept and the new is not installed.
$qw->merge_primaries(\%new_primaries);
Merges a new set of primaries into the existing set. If a name
collision takes place, the original is kept and the new is not
installed.
$qw->get_primary('NAME');
Returns a primary definition given its NAME.
$val = $qw->qwparam('NAME')
$val = qwparam('NAME')
$qw->qwparam('NAME', 'VALUE')
qwparam('NAME', 'VALUE')
Retrieves a value specified by NAME that was submitted by a user
from a QWizard widget. If a VALUE is specified as a second
argument, it replaces the previous value with the new for future
calls.
QWizard parameters are accessible until the last screen in which
all the actions are run and the results are displayed. Parameters
are not retained across primary execution.
The qwparam() function is exported by the QWizard module by
default, so the function shouldn't need to be called directly from
the QWizard object. Thus, just calling qwparam('NAME') by itself
will work.
$val = $qw->qwpref('NAME')
$val = qwpref('NAME')
$qw->qwpref('NAME', 'VALUE')
qwpref('NAME', 'VALUE')
qwpref() acts almost identically to qwparam(), except that it is
expected to be used for "preferences" -- hence the name. The
preferences are stored persistently across primary screens, unlike
parameters. Preferences are not erased between multiple passes
through the QWizard screens. (In the HTML generator, they are
implemented using cookies).
HOOKS
TBD: Document the $qw->add_hook and $qw->run_hooks methods that exist.
(basically $qw->add_hook('start_magic', \&coderef) will run coderef at
the start of the magic function. Search the QWizard code for run_hooks
for a list of hook spots available.
DEBUGGING
The variable $QWizard::qwdebug controls debugging output from QWizard.
If set to 1, it dumps processing information to STDERR. This can be
very useful when debugging QWizard scripts as it displays the step-by-
step process about how QWizard is processing information.
Additionally, a qwdebug_set_output() function exists which can control
the debugging output destination. Its argument should be a reference
to a variable where the debugging output will be stored. Thus,
debugging information can be stored to a previously opened error log
file by doing the following:
our $dvar;
$QWizard::qwdebug = 1;
$qw->qwdebug_set_output(\$dvar);
$qw->magic('stuff');
print LOGFILE $dvar;
EXAMPLES
There are a few usage examples in the examples directory of the source
package. These examples can be run from the command line or installed
as a CGI script without modification. They will run as a CGI script if
run from a web server, or will launch a Gtk2 or Tk window if run from
the command line.
EXPORTqwparam(), qwpref()qw_required_field(), qw_integer(), qw_optional_integer(),
qw_check_int_ranges(), qw_check_length_ranges(), qw_hex(),
qw_optional_hex(), qw_check_hex_and_length()AUTHOR
Wes Hardaker, hardaker@users.sourceforge.net
COPYRIGHT and LICENSE
Copyright (c) 2003-2007, SPARTA, Inc. All rights reserved
Copyright (c) 2006-2007, Wes Hardaker. All rights reserved
QWizard is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
For extra information, consult the following manual pages:
QWizard_Widgets
Manual page for more information about the Various QWizard display
generators and the questions and arguments that each one supports.
This page is actually generated from what the generator actually
advertises that it supports.
QWizard::API
If you get tired of typing anonymous hash references, this API set
will let you generate some widgets with less typing by using APIs
instead.
Example API call:
perl -MQWizard::API -MData::Dumper -e 'print Dumper(qw_checkbox("my ?","it",'A','B', default => 'B'));'
$VAR1 = {
'text' => 'it',
'name' => 'my ?',
'default' => 'B',
'values' => [
'A',
'B'
],
'type' => 'checkbox'
};
Net-Policy: http://net-policy.sourceforge.net/
The entire QWizard system was created to support a multiple-access-
point network management system called "Net-Policy" and the SVN
repository for Net-Policy actually contains the QWizard development
tree.
perl v5.14.0 2008-09-17 QWizard(3)
