1QWizard(3)            User Contributed Perl Documentation           QWizard(3)
2
3
4

NAME

6       QWizard - Display a series of questions, get the answers, and act on
7       the answers.
8

SYNOPSIS

10         #
11         # The following code works as a application *or* as a CGI script both:
12         #
13
14         use QWizard;
15
16         my %primaries =
17         (
18          starting_node =>
19          { title => "starting here",
20            introduction => "foo bar",
21            questions =>
22            [{ type => 'text',
23               name => 'mytext',
24               text => 'enter something:',
25               default => "hello world" },
26             { type => 'checkbox',
27               text => 'yes or no:',
28               values => ['yes','no'],
29               name => 'mycheck'} ],
30            actions =>
31            [sub { return [
32                   "msg: text = " . qwparam('mytext'),
33                   "msg: checkbox = " . qwparam('mycheck')
34                   ];}]
35           }
36          );
37
38         my $qw = new QWizard(primaries => \%primaries,
39                              title => "window title");
40
41         $qw->magic('starting_node');
42
43
44         #
45         # PLEASE see the examples in the examples directory.
46         #
47

DESCRIPTION

49       QWizard displays a list of grouped questions, and retrieves and
50       processes user-specified answers to the questions.  Multiple
51       question/answer sets may be displayed before the answers are dealt
52       with.  Once a "commit" action is taken (instigated by the user), a
53       series of actions is performed to handle the answers.  The actions are
54       executed in the order required by the QWizard programmer.
55
56       QWizard's real power lies in its inherent ability to keep track of all
57       state information between one wizard screen and the next, even in
58       normally stateless transaction environments like HTTP and HTML.  This
59       allows a QWizard programmer to collect a large body of data with a
60       number of simple displays.  After all the data has been gathered and
61       verified, then it can be handled as appropriate (e.g., written to a
62       database, used for system configuration, or used to generate a graph.)
63
64       Current user interfaces that exist are HTML, Gtk2, Tk, and (minimally)
65       ReadLine.  A single QWizard script implementation can make use of any
66       of the output formats without code modification.  Thus it is extremely
67       easy to write portable wizard scripts that can be used without
68       modification by both graphical window environments (Gtk2 and Tk) and
69       HTML-based web environments (e.g., CGI scripts.), as well with
70       intercative command line enviornments (ReadLine).
71
72       Back-end interfaces (child classes of the QWizard::Generator module)
73       are responsible for displaying the information to the user.  Currently
74       HTML, Gtk2, Tk and ReadLine, are the output mechanisms that work the
75       best (in that order).  Some others are planned (namely a curses
76       version), but are not far along in development.  Developing new
77       generator back-ends is fairly simple and doesn't take a lot of code
78       (assuming the graphic interface is fairly powerful and contains a
79       widget library.)
80
81       QWizard operates by displaying a series of "screens" to the user.  Each
82       screen is defined in a QWizard construct called a primary that
83       describes the attributes of a given screen, including the list of
84       questions to be presented to the user.  Primaries can contain
85       questions, things to do immediately after the questions are answered
86       (post_answers), and things to do once the entire series of screens have
87       been answered (actions).  Other information, such as a title and an
88       introduction, can also be attached to a primary.
89
90       An example very minimal primary definition containing one question:
91
92         my %primaries = (
93           myprimary =>
94           {
95             title => "my screen title",
96             introduction => "optional introduction to the screen",
97             questions =>
98             [
99               {
100                 type => 'checkbox',
101                 text => 'Should the chicken cross the road?',
102               }
103             ],
104           }
105
106       After defining a set of primaries, a new QWizard object must be
107       created.  The QWizard new() constructor is given a set of options, such
108       as window title and a reference to a hash table containing the
109       primaries.  (The complete set of options may be found in the "QWizard
110       new() Options" section.) The question display and data collection is
111       started by calling the magic() routine of the new QWizard object.
112
113         my $qw = new QWizard(primaries => \%primaries,
114                              title => 'my title');
115         $qw->magic('myprimary');
116
117       There are examples distributed with the QWizard module sources that may
118       help to understand the whole system and what it is capable of.  See the
119       examples directory of the QWizard source code tree for details.  Also,
120       QWizard was written mostly due to requirements of the Net-Policy
121       project.  Net-Policy makes very extensive use of QWizard and is another
122       good place to look for examples.  In fact, the QWizard CVS code is
123       located inside the Net-Policy CVS tree.  See
124       http://net-policy.sourceforge.net/ for details on the Net-Policy
125       project.  There are a number of screen shots showing all the interfaces
126       as well on the main net-policy web site.
127
128   MAGIC() PSEUDO-CODE
129       A pseudo-code walk-through of the essential results of the magic()
130       routine above is below.  In a CGI script, for example, the magic()
131       routine will be called multiple times (once per screen) but the results
132       will be the same in the end -- it's all taken care of magically ;-).
133
134         ################
135         ## WARNING:  pseudo-code describing a process! Not real code!
136         ################
137
138         # Loop through each primary and display the primary's questions.
139         while(primaries to process) {
140             display_primary_questions();
141             get_user_input();
142             check_results();
143             run_primary_post_answers();
144         }
145
146         # Displays a "will be doing these things" screen,
147         # and has a commit button.
148         display_commit_screen();
149
150         # Loop through each primary and run its actions.
151         # Note: see action documentation about execution order!
152         foreach (primary that was displayed) {
153             results = run_primary_actions();
154             display(results);
155         }
156
157         # If magic() is called again, it restarts from
158         # the top primary again.
159
160   QWIZARD NEW() OPTIONS
161       Options passed to the QWizard new() operator define how the QWizard
162       instance will behave.  Options are passed in the following manner:
163
164         new QWizard (option => value, ...)
165
166       Valid options are:
167
168       title => "document title"
169           The document title to be printed in the title bar of the window.
170
171       generator => GENERATOR
172           GENERATOR is a reference to a valid QWizard generator.  Current
173           generator classes are:
174
175             - QWizard::Generator::Best           (default: picks the best available)
176             - QWizard::Generator::HTML
177             - QWizard::Generator::Gtk2
178             - QWizard::Generator::Tk
179             - QWizard::Generator::ReadLine       (limited in functionality)
180
181           The QWizard::Generator::Best generator is used if no specific
182           generator is specified.  The Best generator will create an HTML
183           generator if used in a web context (i.e., a CGI script), or else
184           pick the best of the available other generators (Gtk2, then Tk,
185           then ReadLine).
186
187           This example forces a Gtk2 generator to be used:
188
189              my $wiz = new QWizard(generator => new QWizard::QWizard::Gtk2(),
190                                    # ...
191                                   );
192
193       generator_args => [ARGS],
194           If you want the default generator that QWizard will provide you,
195           but would still like to provide that generator with some arguments
196           you can use this token to pass an array reference of arguments.
197           These arguments will be passed to the new() method of the Generator
198           that is created.
199
200       top_location => "webaddress"
201           This should be the top location of a web page where the questions
202           will be displayed.  This is needed for "go to top" buttons and the
203           like to work.  This is not needed if the QWizard-based script is
204           not going to be used in a CGI or other web-based environment (eg,
205           if it's going to be used in mod_perl).
206
207       primaries => \%my_primaries
208           my_primaries will define the list of questions to be given to the
209           user.  my_primaries just defines the questions, but does not mean
210           the user will be prompted with each question.  The questions in
211           this series that will be displayed for the user to answer is
212           determined by the magic() function's starting arguments, described
213           below.  The format of the primaries hash is described in the
214           Primaries Definition section below.  The recognized values in the
215           primaries hash is described in the Primaries Options section.
216
217       no_confirm => 1
218           If set, the final confirmation screen will not be displayed, but
219           instead the resulting actions will be automatically run.  This can
220           also be achieved inside the wizard tokens primaries by setting a
221           question name to no_confirm with a value of 1 (using a hidden
222           question type.)
223
224       begin_section_hook => \&subroutine
225           This function will be called just before each screen is displayed.
226           It can be used to perform such functions as printing preliminary
227           information and initializing data.
228
229       end_section_hook => \&subroutine
230           This function will be called just after a set of questions is
231           displayed.
232
233       topbar
234           A place to add extra widgets to a primary at the very top.
235
236           See the bar documentation in the QUESTION DEFINITIONS section below
237           for details on this field.
238
239       leftside => [WIDGETS]
240       rightside => [WIDGETS]
241           Adds a left or right side frame to the main screen where the
242           WIDGETS are always shown for all primaries.  Basically, these
243           should be "axillary" widgets that augment the widgets is the main
244           set of questions.  They can be used for just about anything, but
245           the look and feel will likely be better if they're suplimental.
246
247           The WIDGETS are normal question widgets, just as can appear in the
248           questions section of the primaries definition as described below.
249
250           In addition, however, there can be subgroupings with a title as
251           well.  These are then in a sub-array and are displayed with a title
252           above them.  EG:
253
254             leftside => [
255                          { type => 'button',
256                            # ...  normal button widget definition; see below
257                          },
258                          [
259                           "Special Grouped-together Buttons",
260                           { type => 'button',
261                             # ...
262                           },
263                           { type => 'button',
264                             # ...
265                           },
266                          ],
267                         ],
268
269           The above grouped set of buttons will appear slightly differently
270           and grouped together under the title "Special Grouped-together
271           Buttons".
272
273           The widget-test-screen.pl in the examples directory shows examples
274           of using this.
275
276           Important note: Not all backends support this yet.  HTML and Gtk2
277           do, though.
278
279   PRIMARIES DEFINITION
280       The primaries argument of the new() function defines the list of
281       questions that may be posed to a user.  Each primary in the hash will
282       contain a list of questions, answers, etc., and are grouped together by
283       a name (the key in the hash).  Thus, a typical primary set definition
284       would look something like:
285
286         %my_primaries =
287           (
288            # The name of the primary.
289            'question_set_1' =>
290            # its definition
291            {
292              title => 'My question set',
293              questions =>
294                 # questions are defined in an array of hashes.
295                 [{type => 'checkbox',
296                   text => 'Is this fun?',
297                   name => is_fun,
298                   default => 1,
299                   values => [1, 0] },
300                  {type => 'text',
301                   text => 'Enter your name:',
302                   name => 'their_name'}],
303              post_answers =>
304                 # post_answers is a list of things to do immediately after
305                 # this set of questions has been asked.
306                 [ sub { print "my question set answered" } ],
307              actions =>
308                 # actions is a list of actions run when all is said and done.
309                 [ sub {
310                         return "msg: %s thinks this %s fun.\n",
311                         qwparam('their_name'),
312                         (qwparam('is_fun')) ? "is" : "isn't"
313                        }],
314              actions_descr =>
315                 # An array of strings displayed to the user before they agree
316                 # to commit to their answers.
317                 [ 'I\'m going to process stuff from @their_name@)' ]
318             });
319
320       See the QWizard::API module for an alternative, less verbose, form of
321       API for creating primaries which can produce more compact-looking code.
322
323       VALUE conventions
324
325       In the documentation to follow, any time the keyword VALUE appears, the
326       following types of "values" can be used in its place:
327
328         - "a string"
329         - 10
330         - \&sub_to_call
331         - sub { return "a calculated string or value" }
332         - [\&sub_to_call, arguments, to, sub, ...]
333
334       Subroutines are called and expected to return a single value or an
335       array reference of multiple values.
336
337       Much of the time the VALUE keyword appears in array brackets: [].  Thus
338       you may often specify multiple values in various ways.  E.g., a values
339       clause in a question may be given in this manner:
340
341         sub my_examp1 { return 3; }
342         sub my_examp2 { return [$_[0]..$_[1]]; }
343
344         values => [1, 2, \&my_examp1, [\&my_examp2, 4, 10]],
345
346       After everything is evaluated, the end result of this (complex) example
347       will be an array passed of digits from 1 to 10 passed to the values
348       clause.
349
350       In any function at any point in time during processing, the qwparam()
351       function can be called to return the results of a particular question
352       as it was answered by the user.  I.e., if a question named their_name
353       was answered with "John Doe" at any point in the past series of wizard
354       screens, then qwparam('their_name') would return "John Doe".  As most
355       VALUE functions will be designed to process previous user input,
356       understanding this is the key to using the QWizard Perl module.  More
357       information and examples follow in the sections below.
358
359   PRIMARY OPTIONS
360       These are the tokens that can be specified in a primary:
361
362       title => VALUE
363           The title name for the set of questions.  This will be displayed at
364           the top of the screen.
365
366       introduction => VALUE
367           Introductory text to be printed above the list of questions for a
368           given primary.  This is useful as a starting piece of text to help
369           the user with this particular wizard screen.  Display of the
370           introductory text is controlled by the Net-Policy pref_intro user
371           preference.  The default is to display introductory text, but this
372           setting can be turned off and on by the user.
373
374       questions => [{ QUESTION_DEFINITION }, { QUESTION_DEFINITION }, ...]
375           This is a list of questions to pose to the user for this screen.
376
377           The Question Definitions section describes valid question
378           formatting.
379
380       post_answers => [ VALUES ]
381           This is a list of actions to run after the questions on the screen
382           have been answered.  Although this is a VALUES clause, as described
383           above, these should normally be subroutines and not hard-coded
384           values.  The first argument to the VALUE functions will be a
385           reference to the wizard.  This is particularly useful to
386           conditionally add future screens/primaries that need to be shown to
387           the user.  This can be done by using the following add_todos()
388           function call in the action section:
389
390                if (some_condition()) {
391                    $_[0]->add_todos('primary1', ...);
392                }
393
394           See the QWizard Object Functions section for more information on
395           the add_todos() function, but the above will add the 'primary1'
396           screen to the list of screens to display for the user before the
397           wizard is finished.
398
399           A post_answers subroutine should return the word "OK" for it to be
400           successful (right now, this isn't checked, but it may be (again) in
401           the future).  It may also return "REDISPLAY" which will cause the
402           screen to displayed again.
403
404           For HTML output, these will be run just before the next screen is
405           printed after the user has submitted the answers back to the web
406           server.  For window-based output (Gtk2, Tk, etc.) the results are
407           similar and these subroutines are evaluated before the next window
408           is drawn.
409
410       check_value => sub { ... }
411       check_value => [sub { ... }, arg1, arg2, ...]
412           The primary may have a check_value clause assigned to it to do high
413           level consistency checks.  Returning anything but "OK" will have
414           the returned text displayed as an error to the user that they
415           should fix before they're allowed to continue past the screen.
416
417       actions => [ VALUES ]
418           The action functions will be run after the entire wizard series of
419           questions has been displayed and answered and after the user has
420           hit the "commit" button.  It is assumed that the actions of the
421           earlier screens are dependent on the actions of the later screens
422           and so the action functions will be executed in reverse order from
423           the way the screens were displayed.  See the add_todos() function
424           description in the QWizard Object Functions section for more
425           information on to change the order of execution away from the
426           default.
427
428           The collected values returned from the VALUES evaluation will be
429           displayed to the user.  Any message beginning with a 'msg:' prefix
430           will be displayed as a normal output line.  Any value not prefixed
431           with 'msg:' will be displayed as an error (typically displayed in
432           bold and red by most generators.)
433
434       actions_descr => [ VALUES ]
435           Just before the actions are run, a change-summary screen is shown
436           to the user.  A "commit" button will also be given on this screen.
437           VALUE strings, function results, etc., will be displayed as a list
438           on this commit screen.  Strings may have embedded special @TAG@
439           keywords which will be replaced by the value for the question with
440           a name of TAG.  These strings should indicate to the user what the
441           commit button will do for any actions to be run by this set of
442           questions.  If any question was defined whose name was no_confirm
443           and whose value was 1, this screen will be skipped and the actions
444           will be run directly.
445
446       sub_modules => [ 'subname1', ... ]
447           This hash value adds the specified sub-modules to the list of
448           screens to display after this one.  This is equivalent to having a
449           post_answers clause that includes the function:
450
451             sub { $_[0]->add_todos('subname1', ...); }
452
453       doif => sub { LOGIC }
454           Allows primaries to be optional and only displayed under certain
455           conditions.
456
457           If specified, it should be a CODE reference which when executed
458           should return a 1 if the primary is to be displayed or a 0 if not.
459           The primary will be entirely skipped if the CODE reference returns
460           a 0.
461
462       topbar
463           A place to add extra widgets to a primary at the very top.
464
465           See the bar documentation in the QUESTION DEFINITIONS section below
466           for details on this field.
467
468       leftside => [WIDGETS]
469       rightside => [WIDGETS]
470           Adds a left or right side frame to the main screen where the
471           WIDGETS are shown for this primary.
472
473           Important note: See the leftside/rightside documentation for
474           QWizard for more details and support important notes there.
475
476       take_over => \&subroutine
477           This hash value lets a subroutine completely take control of
478           processing beyond this point.  The wizard methodology functionally
479           stops here and control for anything in the future is entirely
480           passed to this subroutine.  This should be rarely (if ever) used
481           and it is really a way of breaking out of the wizard completely.
482
483   QUESTION DEFINITIONS
484       Questions are implemented as a collection of hash references.  A
485       question generally has the following format:
486
487         {
488             type => QUESTION_TYPE
489             text => QUESTION_TEXT,
490             name => NAME_FOR_ANSWER,
491             default => VALUE,
492             # for menus, checkboxes, multichecks, ... :
493             values => [ VALUE1, VALUE2, ... ],                # i.e., [VALUES]
494             # for menus, checkboxes, multichecks, ... :
495             labels => { value1 => label1, value2 => label2 }  # i.e., [VALUES]
496         }
497
498       Other than this sort of hash reference, the only other type of question
499       allowed in the question array is a single "" empty string.  The empty
500       string acts as a vertical spatial separator, indicating that a space
501       should occur between the previous question and the next question.
502
503       The fields available to question types are given below.  Unless
504       otherwise stated, the fields are available to all question types.
505
506       name => 'NAME'
507           Names the answer to the question.  This name can then be used later
508           in other sections (action, post_answers, etc.) to retrieve the
509           value of the answer using the qwparam() function.  For example,
510           qwparam('NAME') at any point in future executed code should return
511           the value provided by the user for the question named 'NAME'.
512
513           The namespace for these names is shared among all primaries (except
514           'remapped' primaries, which are described later).  A warning will
515           be issued if different questions from two different primaries use
516           the same name.  This warning will not be given if the question
517           contains an override flag set to 1.
518
519       text => 'QUESTION TEXT'
520           Text displayed for the user for the given question.  The text will
521           generally be on the left of the screen, and the widget the user is
522           supposed to interact with will be to the question text's right.
523           (This is subject to the implementation of the back-end question
524           Generator.  The standard QWizard generators use this layout
525           scheme.)
526
527       type => 'TYPE'
528           Defines the type of question.  TYPE can be one of:
529
530           label   Displays information on the screen without requesting any
531                   input.  The text of the question is printed on the left
532                   followed by the values portion on the right.  If the values
533                   portion is omitted, the text portion is printed across the
534                   entire width of the screen.
535
536           paragraph
537                   Paragraphs are similar to labels but are designed for
538                   spaces where text needs to be wrapped and is likely to be
539                   quite long.
540
541           text    Text input.  Displays an entry box where a standard single
542                   line of text can be entered.
543
544           textbox Text input, but in a large box allowing for multi-line
545                   entries.
546
547           hidetext
548                   Obscured text input.  Displays a text entry box, but with
549                   the typed text echoed as asterisks.  This is suitable for
550                   prompting users for entering passwords, as it is not shown
551                   on the screen.
552
553           checkbox
554                   A checkbox.  The values clause should have only 2 values in
555                   it: one for its "on" value, and one for its "off" value
556                   (which defaults to 1 and 0, respectively).
557
558                   The button_label clause can specify text to put right next
559                   to the checkbox itself.
560
561                   If a backend supports key accelerators (GTk2): Checkbox
562                   labels can be bound to Alt-key accelerators.  See QUESTION
563                   KEY-ACCELERATORS below for more information.
564
565           multi_checkbox
566                   Multiple checkboxes, one for each label/value pair.  The
567                   name question field is a prefix, and all values and/or
568                   label keywords will be the second half of the name.
569
570                   For example, the following clauses:
571
572                     {
573                         type => 'multi_checkbox',
574                         name => 'something',
575                         values => ['end1','end2'],
576                         ...
577                     }
578
579                   will give parameters of 'somethingend1' and
580                   'somethingend2'.
581
582                   If a backend supports key accelerators (GTk2): Checkbox
583                   labels can be bound to Alt-key accelerators.  See QUESTION
584                   KEY-ACCELERATORS below for more information.
585
586           radio   Radio buttons, only one of which can be selected at a time.
587                   If two questions have the same name and are of type
588                   'radio', they will be "linked" together such that clicking
589                   on a radio button for one question will affect the other.
590
591                   If a backend supports key accelerators (GTk2): Radio button
592                   labels can be bound to Alt-key accelerators.  See QUESTION
593                   KEY-ACCELERATORS below for more information.
594
595           menu    Pull-down menu, where each label is displayed as a menu
596                   item.  If just the values clause (see below) is used, the
597                   labels on the screen will match the values.  If the default
598                   clause is set, then that menu entry will be the menu's
599                   initial selection.  If the labels clause is used, the
600                   values shown to the user will be converted to the screen
601                   representations that will differ from the qwparam() values
602                   available later.  This is useful for displaying human
603                   representations of programmatic values.  E.g.:
604
605                     {
606                         type => 'menu',
607                         name => 'mymenu',
608                         labels => [ 1 => 'my label1',
609                                     2 => 'my label2']
610                     }
611
612                   In this example, the user will see a menu containing 2
613                   entries "my label1" and "my label2", but qwparam() will
614                   return 1 or 2 for qwparam('mymenu').
615
616           table   Table to display.  The values section should return a
617                   reference to an array, where each element of the array is a
618                   row containing the columns to display for that row.  The
619                   top-most table must actually be returned in an array
620                   itself.  (This is due to an oddity of internal QWizard
621                   processing).  E.g.:
622
623                     {
624                         type => 'table',
625                         text => 'The table:',
626                         values => sub {
627                             my $table = [['row1:col1', 'row1:col2'],
628                                          ['row2:col1', 'row2:col2']];
629                             return [$table];
630                           }
631                     }
632
633                   This would be displayed graphically on the screen in this
634                   manner:
635
636                        row1:col1     row1:col2
637
638                        row2:col1     row2:col2
639
640                   Additionally, a column value within the table may itself be
641                   a sub-table (another double-array reference set) or a hash
642                   reference, which will be a sub-widget to display any of the
643                   other types listed in this section.
644
645                   Finally, a headers clause may be added to the question
646                   definition which will add column headers to the table.
647                   E.g.:
648
649                     headers => [['col1 header','col2 header']]
650
651           fileupload
652                   A dialog box for a user to upload a file into the
653                   application.  When a user submits a file the question name
654                   can be used later to retrieve a read file handle on the
655                   file using the function qw_upload_fh('NAME').
656                   qwparam('NAME') will return the original name of the file
657                   submitted, but because of the variability in how web-
658                   browsers submit file names along with the data, this field
659                   should generally not be used.  Instead, get access to the
660                   data through the qw_upload_fh() function instead.  The
661                   second best alternative is to use the
662                   qw_upload_file('NAME') function which returns a safe path
663                   to access under web-environments (which will be something
664                   like /tmp/qwHTMLXXXXXX...)
665
666           filedownload
667                   A button that allows the user to download something
668                   generated by the application.  The data that will be stored
669                   in this file should be defined in the 'data' field or the
670                   'datafn' field.  The name displayed within the button will
671                   be taken from the default question parameter.
672
673                   The data field is processed early during display of the
674                   screen, so generation of large sets of data that won't
675                   always be downloaded or will take a lot of memor shouldn't
676                   use the data field.  The data field is processed like any
677                   other value field where raw data or a coderef can be passed
678                   that will be called to return the data.
679
680                   The datafn field should contain a CODE reference that will
681                   be called with five arguments:
682
683                   a IO::File filehandle to print to
684                   the file name (if appropriate) it's going to print to.
685                   a QWizard object reference
686                   a reference to the primary hash
687                   a reference to the question hash
688                       Example usage:
689
690                            { type => 'filedownload',
691                              text => 'Download a file:',
692                              datafn =>
693                              sub {
694                                  my $fh = shift;
695                                  print $fh "hello world: val=" . qwparam('someparam') . "\n";
696                              }
697                            },
698
699                       Currently only Gtk2 supports this button, but others
700                       will in the future.
701
702                   image
703                       Image file.  The image name is specified by the image
704                       hash keyword.  Several optional hash keys are
705                       recognized to control display of the image.  imagealt
706                       specifies a string to display if the image file is not
707                       found.  height specifies the height of the image.
708                       width specifies the width of the image.  (height and
709                       width are currently only implemented for HTML.)
710
711                   graph
712                       Graph of passed data.  This is only available if the
713                       GD::Graph module is installed.  Data is passed in from
714                       the values clause and is expected to be an array of
715                       arrays of data, where the first row is the x-axis data,
716                       and the rest are y values (one line will be drawn for
717                       each y value).
718
719                       Additionally, the GD::Graph options can be specified
720                       with a graph_options tag to the question, allowing
721                       creation of such things as axis labels and legends.
722
723                   tree
724                       Hierarchical tree.  Displays a selectable hierarchical
725                       tree set from which the user should pick a single item.
726                       Two references to subroutines must be passed in via the
727                       parent and children question tags.  Also, a root tag
728                       should specify the starting point.
729
730                       Widget Options:
731
732                       parent => CODEREF
733                           The parent function will be called with a wizard
734                           reference and a node name.  It is expected to
735                           return the name of the node's parent.
736
737                           The function should return undef when no parent
738                           exists above the current node.
739
740                       children => CODEREF
741                           The children function will be passed a wizard
742                           reference and a node name.  It is expected to
743                           return an array reference to all the children
744                           names.  It may also return a hash reference for
745                           some names instead, which will contain an internal
746                           name tag along with a label tag for displaying
747                           something to the user which is different than is
748                           internally passed around as the resulting selected
749                           value.
750
751                           An example return array structure could look like:
752
753                              [
754                               'simple string 1',
755                               'simple string 2',
756                               {
757                                name => 'myanswer:A',
758                                label => 'Answer #A'
759                               },
760                               {
761                                name => 'myanswer:B',
762                                label => 'Answer #B'
763                               },
764                              ]
765
766                           The function should return undef when no children
767                           exist below the current node.
768
769                       expand_all => NUM
770                           The expand_all tag may be passed which will
771                           indicate that all initial option trees sholud be
772                           expanded up to the number indicated by the
773                           expand_all tag.
774
775                   button
776                       Button widget.  When the button is clicked, the QWizard
777                       parameter name (available by calling qwparam('name'))
778                       will be assigned the value indicated by the default
779                       clause.  The parameter value will not be set if the
780                       button is not clicked.  The button's label text will be
781                       set to the value of the values clause.
782
783                       The button widget will be equivalent to pressing the
784                       next button.  The next primary will be shown after the
785                       user presses the button.
786
787                       If a backend supports key accelerators (GTk2): Button
788                       labels can be bound to Alt-key accelerators.  See
789                       QUESTION KEY-ACCELERATORS below for more information.
790
791                   bar A bar widget is functionally a separator in the middle
792                       of the list of questions.  It is useful for breaking a
793                       set of questions in two as well as providing button-
794                       containers or menu containers within widget sets and
795                       not having them tied to the normal QWizard left/right
796                       feel.  One intentional artifact of this is they can be
797                       used to provide a visual difference between the flow of
798                       the questions.  EG, if the QWizard primary showed a
799                       screen which had two questions in it, it would look
800                       something like the following when displayed by most of
801                       the generators that exist today:
802
803                         +-------------------+-----------------+
804                         | Question 1        | Answer Widget 1 |
805                         | Longer Question 2 | Answer Widget 2 |
806                         +-------------------+-----------------+
807
808                       Adding a bar in the middle of these questions, however,
809                       would break the forced columns above into separate
810                       pieces:
811
812                         +------------+------------------------+
813                         | Question 1 | Answer Widget 1        |
814                         +------------+------------------------+
815                         |               BAR                   |
816                         +-------------------+-----------------+
817                         | Longer Question 2 | Answer Widget 2 |
818                         +-------------------+-----------------+
819
820                       Finally, there is an implicit top bar in every primary
821                       and the QWizard object as a whole.  You can push
822                       objects onto this bar by adding objects to the
823                       $qwizard->{'topbar'} array or by adding objects to a
824                       primary's 'topbar' tag.  E.G.
825
826                         my $qw = new QWizard(primaries => \%primaries,
827                                              topbar => [
828                                                         {
829                                                          type => 'menu', name => 'menuname',
830                                                          values => [qw(1 2 3 4)],
831                                                          # ...
832                                                         }]);
833
834                       The widgets shown in the topbar will be a merge of
835                       those from the QWizard object and the primary currently
836                       being displayed.
837
838                       TODO: make it work better with merged primaries
839
840                       TODO: make a bottom bar containing the next/prev/cancel
841                       buttons
842
843                   hidden
844                       This clause is used to set internal parameters (name =>
845                       value), but these values are not shown to the user.
846
847                       Note:  This is not a secure way to hide information
848                       from the user.  The data set using hidden are
849                       contained, for example, in the HTML text sent to the
850                       user.
851
852                   dynamic
853                       A dynamic question is one where the values field is
854                       evaluated and is expected to return an array of
855                       question definitions which are in turn each evaluated
856                       as a question.  It is useful primarily when doing
857                       things like creating a user-defined number of input
858                       fields, or interacting with an external data source
859                       where the number of questions and their nature is
860                       directly related to the external data source.
861
862                   raw Raw data.  The values portion is displayed straight to
863                       the screen.  Use of this is strongly discouraged.
864                       Obviously, the values portion should be a subroutine
865                       that understands how to interact with the generator.
866
867                       Really, don't use this.  It's for emergencies only.  It
868                       only works with HTML output.
869
870           values => [ VALUES ]
871                   An array of values that may be assigned to question types
872                   that need choices (eg: menu, checkbox, multi_checkbox.)  It
873                   should be a reference to an array containing a list of
874                   strings, functions to execute, and possibly sub-arrays
875                   containing a function and arguments, as described by the
876                   VALUE conventions section above.  Any function listed in a
877                   values clause should return a list of strings.
878
879                   The values clause is not needed if the labels clause is
880                   present.
881
882           labels => [ VALUE1 => 'LABEL1', VALUE2 => 'LABEL2', ... ]
883                   Assigns labels to the question's values.  Labels are
884                   displayed to the user instead of the raw values.  This is
885                   useful for converting human-readable text strings into
886                   real-world values for use in code.
887
888                   If the values clause is not specified and the labels clause
889                   is, the values to display are extracted from this labels
890                   clause directly.  If a value from the values clause does
891                   not have a corresponding label, the raw value is presented
892                   and used instead.  Generally, only the labels clause should
893                   be used with radio buttons, menus, or check boxes; but
894                   either or both in combination work.
895
896                   The labels clause subscribes to all the properties of the
897                   VALUES convention previously discussed.  Thus, it may be a
898                   function, an array of functions, or any other type of data
899                   that a VALUE may be.  The final results should be an array,
900                   especially if the values clause is not present, as the
901                   order displayed to the user can be specified.  It can also
902                   be a hash as well but the displayed order is subject to
903                   Perl keys() conventions and thus an array is preferred when
904                   no values clause has been defined.
905
906           default => VALUE
907                   The default value to use for this question.  It may be a
908                   subroutine reference which will be called to calculate and
909                   return the value.
910
911           check_value => \&subroutine
912                   A script to check the answer submitted by the user for
913                   legality.  The script should return 'OK' to indicate no
914                   error found. In the event an error is detected, it should
915                   return an error string.  The string will be shown to the
916                   user as an error message that the user must fix before
917                   being allowed to proceed further in the wizard screens.
918                   Alternately, the script may return 'REDISPLAY' to indicate
919                   no error but that screen should be redisplyed (perhaps with
920                   new values set with qwparam() from within the script). In
921                   the case of error or 'REDISPLAY', the current primary
922                   screen will be repeated until the function returns 'OK'.
923
924                   The arguments passed to the function are the reference to
925                   the wizard, a reference to the question definition (the
926                   hash), and a reference to the primary containing the
927                   question (also a hash.)  The function should use the
928                   qwparam() function to obtain the value to check.  An array
929                   can be passed in which the first argument should be the
930                   subroutine reference, and the remaining arguments will be
931                   passed back to the subroutine after the already mentioned
932                   default arguments.
933
934                   There are a set of standard functions that can be used for
935                   checking values.  These are:
936
937                   \&qw_required_field
938                       Ensures that a value is supplied or else a "This is a
939                       required field" error message is returned.  The
940                       function only checks that the value is non-zero in
941                       length.
942
943                   \&qw_integer
944                   \&qw_optional_integer
945                       Ensures that the value is an integer value (required or
946                       not, respectively.)
947
948                   \&qw_hex
949                   \&qw_optional_hex
950                       Ensures that the value is a hex string (required or
951                       not, respectively.)
952
953                   [\&qw_check_hex_and_length, length]
954                       Ensures that a value is supplied and is a hex string
955                       sufficiently long for length bytes. This means that the
956                       hex string must be "length * 2" ASCII characters (two
957                       hex characters per byte.)
958
959                   [\&qw_check_int_ranges, low1, high1, low2, high2, ...]
960                       Ensures that the value specified falls within one of
961                       the lowX - highX ranges.  The value must be between
962                       (low1 and high1) or (low2 and high2).
963
964                   [\&qw_check_length_ranges, low1, high1, low2, high2, ...]
965                       qw_check_length_ranges is similar to
966                       qw_check_int_ranges(), but it checks that the length of
967                       the data string specified by the user falls within the
968                       given ranges.
969
970           doif => sub { LOGIC }
971                   Allows questions to be optional and only displayed under
972                   certain conditions.
973
974                   If specified, it should be a CODE reference which when
975                   executed should return a 1 if the question is to be
976                   displayed or a 0 if not.  The question will be entirely
977                   skipped if the CODE reference returns a 0.
978
979           helptext =item helpdescr
980                   If specified, these define the help text for a question.
981                   helpdescr should be short descriptions printed on screen
982                   when the wizard screen is displayed, and helptext should be
983                   a full length description of help that will be displayed
984                   only when the user clicks on the help button.  helpdescr is
985                   optional, and a button will be shown linking to helptext
986                   regardless.
987
988           indent => 1
989                   Slightly indents the question for some generators.
990
991           submit => 1
992                   When this is specified as a question argument, if the user
993                   changes the value then it will also be the equivelent of
994                   pressing the 'Next' button at the same time.  With the HTML
995                   generator, this requires javascript and thus you shouldn't
996                   absolutely depend on it working.
997
998           refresh_on_change => 1
999                   If the contents of a screen are generated based on data
1000                   extracted from dynamically changing sources (e.g., a
1001                   database), then setting this parameter to 1 will make the
1002                   current question force a refresh if the value changes (ie,
1003                   when they pull down a menu and change the value or click on
1004                   a checkbox or ...) and the screen be redrawn (possibly
1005                   changing its contents).
1006
1007                   As an example, Net-Policy uses this functionality to allow
1008                   users to redisplay generated data tables and changes the
1009                   column that is used for sorting depending on a menu widget.
1010
1011           handle_results => sub { ... }
1012                   The handle_results tag can specify a CODE reference to be
1013                   run when the questions are answered so each question can
1014                   perform its own processing.  This is sort of like a per-
1015                   question post_answers hook equivalent.
1016
1017       QUESTION KEY-ACCELERATORS
1018
1019       Some generators (currently only Gtk2 actually) support key accelerators
1020       so that you can bind alt-keys to widgets.  This is done by including a
1021       '_' (underscore) character where appropriate to create the binding.
1022       EG:
1023
1024         {
1025           type => 'radio',
1026           text => 'select one:',
1027           values => ['_Option1','O_ption2', 'Option3']
1028         }
1029
1030       When Gtk2 gets the above construct it will make Alt-o be equivelent to
1031       pressing the first option and Alt-p to the second.  It will also
1032       display the widget with a underline under the character that is bound
1033       to the widget.  HTML and other non-accelerator supported interfaces
1034       will strip out the _ character before displaying the string in a
1035       widget.
1036
1037       In addition, unless a no_auto_accelerators = 1> option is passed to the
1038       generator creation arguments, widgets will automatically get
1039       accelerators assigned to them.  In the above case the 't' in Option3
1040       would automatically get assigned the Alt-t accelerator (the 't' is
1041       selected because it hasn't been used yet, unlike the o and p
1042       characters).  You can also prefix something with a ! character to force
1043       a single widget to not receive an auto-accelerator (EG: "!Option4"
1044       wouldn't get one).
1045

SPECIAL VARIABLES

1047       A few QWizard parameters are special and help control how QWizard
1048       behaves.  Most of these should be set in the primaries question sets
1049       using a hidden question type.
1050
1051       no_actions
1052           If set to 1, the actions phase will not be run.
1053
1054       no_confirm
1055           If set to 1, the screen which prompts the user to decide if they
1056           really want to commit their series of answers won't be shown.
1057           Instead, QWizard will jump straight to the actions execution (if
1058           appropriate.)  This can also be given as a parameter to the QWizard
1059           new() function to make it always true.
1060
1061       allow_refresh
1062           If the contents of a screen are generated based on data extracted
1063           from dynamically changing sources (e.g., a database), then setting
1064           this parameter to 1 will add a "Refresh" button beside the "Next"
1065           button so that the user can request the screen be redrawn (possibly
1066           changing its contents).
1067
1068           As an example, Net-Policy uses this functionality to allow users to
1069           redisplay generated graphs and maps that will change dynamically as
1070           network data are collected.
1071
1072           This token can also be set directly in a primary definition to
1073           affect just that primary screen.
1074
1075       QWizard_next
1076           The button text to display for the "Next" button.  This defaults to
1077           "_Next" but can be overridden using this parameter.
1078
1079       QWizard_commit
1080           The button text to display for the "Commit" button.  This defaults
1081           to "_Commit" but can be overridden using this parameter.  The
1082           commit button is shown after the questions have been asked and the
1083           actions_descr's are being shown to ask the user if they really want
1084           to run the actions.
1085
1086       QWizard_finish
1087           The button text to display for the "Finish" button.  This defaults
1088           to "_Finish" but can be overridden using this parameter.  The
1089           finish button is shown after the actions have been run and the
1090           results are being displayed.
1091

QWIZARD RESERVED VARIABLES

1093       The following parameters are used internally by QWizard.  They should
1094       not be modified.
1095
1096       pass_vars
1097       qw_cancel
1098       no_cancel
1099       qwizard_tree
1100       display_help_p
1101       disp_q_num
1102       redo_screen
1103       upd_time
1104       wiz_confirmed
1105       wiz_canceled
1106       wizard_queue_list
1107

QWizard OBJECT FUNCTIONS

1109       The following functions are defined in the QWizard class and can be
1110       called as needed.
1111
1112       $qw->magic(primary_name, ...);
1113           This tells QWizard to start its magic, beginning at the primary
1114           named primary_name.  Multiple primaries will be displayed one after
1115           the other until the list of primaries to display is empty.  The
1116           actions clauses of all these primaries will not be run, however,
1117           until after all the primaries have been processed.
1118
1119           The magic() routine exits only after all the primaries have been
1120           run up through their actions, or unless one of the following
1121           conditions occurs:
1122
1123             - $qw->{'one_pass'} == 1
1124             - $qw->{'generator'}{'one_pass'} == 1
1125
1126           By default, some of the stateless generators (HTML) will set their
1127           one_pass option automatically since it is expected that the client
1128           will exit the magic() loop and return later with the next set of
1129           data to process.  The magic() routine will automatically restart
1130           where it left off if the last set of primaries being displayed was
1131           never finished.  This is common for stateless generators like HTTP
1132           and HTML.
1133
1134       $qw->finished();
1135           Closes the open qwizard window.  Useful after your magic() routine
1136           has ended and you don't intend to call it again.  Calling
1137           finished() will remove the QWizard window from visibility.
1138
1139       $qw->set_progress(FRACTION, TEXT);
1140           If available, some generators (Gtk2 can) may be able to display a
1141           progress meter.  If they are, calling this function inside action
1142           clauses, for example, will start the display of this meter with
1143           FRACTION complete (0 <= FRACTION <= 1).  The TEXT is optional and
1144           if left blank will be set to NN% showing the percentage complete.
1145
1146       $qw->add_todos([options], primary_name, ...);
1147           Adds a primary to the list of screens to display to the user.  This
1148           function should be called during the post_answers section of a
1149           primary.  Options that can be passed before the first primary name
1150           are:
1151
1152           -early
1153               Adds the primaries in question as early as possible in the todo
1154               list (next, unless trumped by future calls.)  This is the
1155               default.
1156
1157           -late
1158               Adds the primary to the end of the list of primaries to call,
1159               such that it is called last, unless another call to add_todos()
1160               appends something even later.
1161
1162           -actionslast
1163               All the actions of subsequent primaries that have been added as
1164               the result of a current primary's post_answers clauses are
1165               called before the actions for the current primary.  This means
1166               that the actions of any childrens are executed prior to the
1167               actions of their parents.  This is done by default, as the
1168               general usage prediction is that parent primaries are likely to
1169               be dependent on the actions of their children in order for
1170               their own actions to be successful.
1171
1172               However, this flag indicates that the actions of the childrens'
1173               primaries listed in this call are to be called before the
1174               current primary's actions.
1175
1176           -merge
1177               Merges all the specified primaries listed into a single screen.
1178               This has the effect of having multiple primaries displayed in
1179               one window.
1180
1181               Important note: you can not use both -remap (see below) and
1182               -merge at the same time!  This will break the remapping support
1183               and you will not get expected results!
1184
1185           -remap => 'NAME'
1186               If a series of questions must be called repeatedly, you can use
1187               this flag to remap the names of the child primary questions to
1188               begin with this prefix.  The children's clauses (questions,
1189               actions, post_answers, etc.) will be called in such a way that
1190               they can be oblivious to the fact this is being done behind
1191               their backs, allowing qwparam() to work as expected.  However,
1192               for the current primary (and any parents), the 'NAME' prefix
1193               will be added to the front of any question name values that the
1194               child results in defining.
1195
1196               This is rather complex and is better illustrated through an
1197               example.  There is an example that illustrates this in the
1198               QWizard Perl module source code examples directory, in the file
1199               number_adding.pl.  This code repeatedly asks for numbers from
1200               the user using the same primary.
1201
1202               Important note: you can not use both -remap and -merge at the
1203               same time!  This will break the remapping support and you will
1204               not get expected results!
1205
1206       $qw->add_primary(key => value, key => value);
1207           Adds a primary definition into the existing primary data set for
1208           the QWizard object.  One key value pair MUST be a 'name' => 'NAME'
1209           pair, where NAME will be the installed primary name for later
1210           referral (e.g., in add_todos() calls.)  If a name collision takes
1211           place (a primary already exists under the given name), the original
1212           is kept and the new is not installed.
1213
1214       $qw->merge_primaries(\%new_primaries);
1215           Merges a new set of primaries into the existing set.  If a name
1216           collision takes place, the original is kept and the new is not
1217           installed.
1218
1219       $qw->get_primary('NAME');
1220           Returns a primary definition given its NAME.
1221
1222       $val = $qw->qwparam('NAME')
1223       $val = qwparam('NAME')
1224       $qw->qwparam('NAME', 'VALUE')
1225       qwparam('NAME', 'VALUE')
1226           Retrieves a value specified by NAME that was submitted by a user
1227           from a QWizard widget.  If a VALUE is specified as a second
1228           argument, it replaces the previous value with the new for future
1229           calls.
1230
1231           QWizard parameters are accessible until the last screen in which
1232           all the actions are run and the results are displayed.  Parameters
1233           are not retained across primary execution.
1234
1235           The qwparam() function is exported by the QWizard module by
1236           default, so the function shouldn't need to be called directly from
1237           the QWizard object.  Thus, just calling qwparam('NAME') by itself
1238           will work.
1239
1240       $val = $qw->qwpref('NAME')
1241       $val = qwpref('NAME')
1242       $qw->qwpref('NAME', 'VALUE')
1243       qwpref('NAME', 'VALUE')
1244           qwpref() acts almost identically to qwparam(), except that it is
1245           expected to be used for "preferences" -- hence the name.  The
1246           preferences are stored persistently across primary screens, unlike
1247           parameters.  Preferences are not erased between multiple passes
1248           through the QWizard screens.  (In the HTML generator, they are
1249           implemented using cookies).
1250

HOOKS

1252       TBD: Document the $qw->add_hook and $qw->run_hooks methods that exist.
1253
1254       (basically $qw->add_hook('start_magic', \&coderef) will run coderef at
1255       the start of the magic function.  Search the QWizard code for run_hooks
1256       for a list of hook spots available.
1257

DEBUGGING

1259       The variable $QWizard::qwdebug controls debugging output from QWizard.
1260       If set to 1, it dumps processing information to STDERR.  This can be
1261       very useful when debugging QWizard scripts as it displays the step-by-
1262       step process about how QWizard is processing information.
1263
1264       Additionally, a qwdebug_set_output() function exists which can control
1265       the debugging output destination.  Its argument should be a reference
1266       to a variable where the debugging output will be stored.  Thus,
1267       debugging information can be stored to a previously opened error log
1268       file by doing the following:
1269
1270         our $dvar;
1271         $QWizard::qwdebug = 1;
1272         $qw->qwdebug_set_output(\$dvar);
1273         $qw->magic('stuff');
1274         print LOGFILE $dvar;
1275

EXAMPLES

1277       There are a few usage examples in the examples directory of the source
1278       package.  These examples can be run from the command line or installed
1279       as a CGI script without modification.  They will run as a CGI script if
1280       run from a web server, or will launch a Gtk2 or Tk window if run from
1281       the command line.
1282

EXPORT

1284       qwparam(), qwpref()
1285
1286       qw_required_field(), qw_integer(), qw_optional_integer(),
1287       qw_check_int_ranges(), qw_check_length_ranges(), qw_hex(),
1288       qw_optional_hex(), qw_check_hex_and_length()
1289

AUTHOR

1291       Wes Hardaker, hardaker@users.sourceforge.net
1292
1294       Copyright (c) 2003-2007, SPARTA, Inc.  All rights reserved
1295
1296       Copyright (c) 2006-2007, Wes Hardaker. All rights reserved
1297
1298       QWizard is free software; you can redistribute it and/or modify it
1299       under the same terms as Perl itself.
1300

SEE ALSO

1302       For extra information, consult the following manual pages:
1303
1304       QWizard_Widgets
1305           Manual page for more information about the Various QWizard display
1306           generators and the questions and arguments that each one supports.
1307           This page is actually generated from what the generator actually
1308           advertises that it supports.
1309
1310       QWizard::API
1311           If you get tired of typing anonymous hash references, this API set
1312           will let you generate some widgets with less typing by using APIs
1313           instead.
1314
1315           Example API call:
1316
1317             perl -MQWizard::API -MData::Dumper -e 'print Dumper(qw_checkbox("my ?","it",'A','B', default => 'B'));'
1318             $VAR1 = {
1319                     'text' => 'it',
1320                     'name' => 'my ?',
1321                     'default' => 'B',
1322                     'values' => [
1323                                   'A',
1324                                   'B'
1325                                 ],
1326                     'type' => 'checkbox'
1327                   };
1328
1329       Net-Policy: http://net-policy.sourceforge.net/
1330           The entire QWizard system was created to support a multiple-access-
1331           point network management system called "Net-Policy" and the SVN
1332           repository for Net-Policy actually contains the QWizard development
1333           tree.
1334
1335
1336
1337perl v5.32.1                      2021-01-27                        QWizard(3)
Impressum