1QWizard(3) User Contributed Perl Documentation QWizard(3)
2
6 QWizard - Display a series of questions, get the answers, and act on
7 the answers.
8
10 #
11 # The following code works as a application *or* as a CGI script both:
12 #
13 use QWizard;
15 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 my $qw = new QWizard(primaries => \%primaries,
39 title => "window title");
40 $qw->magic('starting_node');
42 #
44 # PLEASE see the examples in the examples directory.
45 #
46
48 QWizard displays a list of grouped questions, and retrieves and pro‐
49 cesses user-specified answers to the questions. Multiple ques‐
50 tion/answer sets may be displayed before the answers are dealt with.
51 Once a "commit" action is taken (instigated by the user), a series of
52 actions is performed to handle the answers. The actions are executed
53 in the order required by the QWizard programmer.
54 QWizard's real power lies in its inherent ability to keep track of all
56 state information between one wizard screen and the next, even in nor‐
57 mally stateless transaction environments like HTTP and HTML. This
58 allows a QWizard programmer to collect a large body of data with a num‐
59 ber of simple displays. After all the data has been gathered and veri‐
60 fied, then it can be handled as appropriate (e.g., written to a data‐
61 base, used for system configuration, or used to generate a graph.)
62 Current user interfaces that exist are HTML, Gtk2, Tk, and (minimally)
64 ReadLine. A single QWizard script implementation can make use of any
65 of the output formats without code modification. Thus it is extremely
66 easy to write portable wizard scripts that can be used without modifi‐
67 cation by both graphical window environments (Gtk2 and Tk) and HTML-
68 based web environments (e.g., CGI scripts.), as well with intercative
69 command line enviornments (ReadLine).
70 Back-end interfaces (child classes of the QWizard::Generator module)
72 are responsible for displaying the information to the user. Currently
73 HTML, Gtk2, Tk and ReadLine, are the output mechanisms that work the
74 best (in that order). Some others are planned (namely a curses ver‐
75 sion), but are not far along in development. Developing new generator
76 back-ends is fairly simple and doesn't take a lot of code (assuming the
77 graphic interface is fairly powerful and contains a widget library.)
78 QWizard operates by displaying a series of "screens" to the user. Each
80 screen is defined in a QWizard construct called a primary that
81 describes the attributes of a given screen, including the list of ques‐
82 tions to be presented to the user. Primaries can contain questions,
83 things to do immediately after the questions are answered
84 (post_answers), and things to do once the entire series of screens have
85 been answered (actions). Other information, such as a title and an
86 introduction, can also be attached to a primary.
87 An example very minimal primary definition containing one question:
89 my %primaries = (
91 myprimary =>
92 {
93 title => "my screen title",
94 introduction => "optional introduction to the screen",
95 questions =>
96 [
97 {
98 type => 'checkbox',
99 text => 'Should the chicken cross the road?',
100 }
101 ],
102 }
103 After defining a set of primaries, a new QWizard object must be cre‐
105 ated. The QWizard new() constructor is given a set of options, such as
106 window title and a reference to a hash table containing the primaries.
107 (The complete set of options may be found in the "QWizard new()
108 Options" section.) The question display and data collection is started
109 by calling the magic() routine of the new QWizard object.
110 my $qw = new QWizard(primaries => \%primaries,
112 title => 'my title');
113 $qw->magic('myprimary');
114 There are examples distributed with the QWizard module sources that may
116 help to understand the whole system and what it is capable of. See the
117 examples directory of the QWizard source code tree for details. Also,
118 QWizard was written mostly due to requirements of the Net-Policy
119 project. Net-Policy makes very extensive use of QWizard and is another
120 good place to look for examples. In fact, the QWizard CVS code is
121 located inside the Net-Policy CVS tree. See http://net-policy.source‐
122 forge.net/ for details on the Net-Policy project. There are a number
123 of screen shots showing all the interfaces as well on the main net-pol‐
124 icy web site.
125 MAGIC() PSEUDO-CODE
127 A pseudo-code walk-through of the essential results of the magic() rou‐
129 tine above is below. In a CGI script, for example, the magic() routine
130 will be called multiple times (once per screen) but the results will be
131 the same in the end -- it's all taken care of magically ;-).
132 ################
134 ## WARNING: pseudo-code describing a process! Not real code!
135 ################
136 # Loop through each primary and display the primary's questions.
138 while(primaries to process) {
139 display_primary_questions();
140 get_user_input();
141 check_results();
142 run_primary_post_answers();
143 }
144 # Displays a "will be doing these things" screen,
146 # and has a commit button.
147 display_commit_screen();
148 # Loop through each primary and run its actions.
150 # Note: see action documentation about execution order!
151 foreach (primary that was displayed) {
152 results = run_primary_actions();
153 display(results);
154 }
155 # If magic() is called again, it restarts from
157 # the top primary again.
158 QWIZARD NEW() OPTIONS
160 Options passed to the QWizard new() operator define how the QWizard
162 instance will behave. Options are passed in the following manner:
163 new QWizard (option => value, ...)
165 Valid options are:
167 title => "document title"
169 The document title to be printed in the title bar of the window.
170 generator => GENERATOR
172 GENERATOR is a reference to a valid QWizard generator. Current
173 generator classes are:
174 - 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 The QWizard::Generator::Best generator is used if no specific gen‐
182 erator is specified. The Best generator will create an HTML gener‐
183 ator if used in a web context (i.e., a CGI script), or else pick
184 the best of the available other generators (Gtk2, then Tk, then
185 ReadLine).
186 This example forces a Gtk2 generator to be used:
188 my $wiz = new QWizard(generator => new QWizard::QWizard::Gtk2(),
190 # ...
191 );
192 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 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 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 deter‐
212 mined by the magic() function's starting arguments, described
213 below. The format of the primaries hash is described in the Pri‐
214 maries Definition section below. The recognized values in the pri‐
215 maries hash is described in the Primaries Options section.
216 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 ques‐
222 tion type.)
223 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 end_section_hook => \&subroutine
230 This function will be called just after a set of questions is dis‐
231 played.
232 topbar
234 A place to add extra widgets to a primary at the very top.
235 See the bar documentation in the QUESTION DEFINITIONS section below
237 for details on this field.
238 leftside => [WIDGETS]
240 rightside => [WIDGETS]
241 Adds a left or right side frame to the main screen where the WID‐
242 GETS are always shown for all primaries. Basically, these should
243 be "axillary" widgets that augment the widgets is the main set of
244 questions. They can be used for just about anything, but the look
245 and feel will likely be better if they're suplimental.
246 The WIDGETS are normal question widgets, just as can appear in the
248 questions section of the primaries definition as described below.
249 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 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 The above grouped set of buttons will appear slightly differently
270 and grouped together under the title "Special Grouped-together But‐
271 tons".
272 The widget-test-screen.pl in the examples directory shows examples
274 of using this.
275 Important note: Not all backends support this yet. HTML and Gtk2
277 do, though.
278 PRIMARIES DEFINITION
280 The primaries argument of the new() function defines the list of ques‐
282 tions that may be posed to a user. Each primary in the hash will con‐
283 tain a list of questions, answers, etc., and are grouped together by a
284 name (the key in the hash). Thus, a typical primary set definition
285 would look something like:
286 %my_primaries =
288 (
289 # The name of the primary.
290 'question_set_1' =>
291 # its definition
292 {
293 title => 'My question set',
294 questions =>
295 # questions are defined in an array of hashes.
296 [{type => 'checkbox',
297 text => 'Is this fun?',
298 name => is_fun,
299 default => 1,
300 values => [1, 0] },
301 {type => 'text',
302 text => 'Enter your name:',
303 name => 'their_name'}],
304 post_answers =>
305 # post_answers is a list of things to do immediately after
306 # this set of questions has been asked.
307 [ sub { print "my question set answered" } ],
308 actions =>
309 # actions is a list of actions run when all is said and done.
310 [ sub {
311 return "msg: %s thinks this %s fun.\n",
312 qwparam('their_name'),
313 (qwparam('is_fun')) ? "is" : "isn't"
314 }],
315 actions_descr =>
316 # An array of strings displayed to the user before they agree
317 # to commit to their answers.
318 [ 'I\'m going to process stuff from @their_name@)' ]
319 });
320 See the QWizard::API module for an alternative, less verbose, form of
322 API for creating primaries which can produce more compact-looking code.
323 VALUE conventions
325 In the documentation to follow, any time the keyword VALUE appears, the
327 following types of "values" can be used in its place:
328 - "a string"
330 - 10
331 - \&sub_to_call
332 - sub { return "a calculated string or value" }
333 - [\&sub_to_call, arguments, to, sub, ...]
334 Subroutines are called and expected to return a single value or an
336 array reference of multiple values.
337 Much of the time the VALUE keyword appears in array brackets: []. Thus
339 you may often specify multiple values in various ways. E.g., a values
340 clause in a question may be given in this manner:
341 sub my_examp1 { return 3; }
343 sub my_examp2 { return [$_[0]..$_[1]]; }
344 values => [1, 2, \&my_examp1, [\&my_examp2, 4, 10]],
346 After everything is evaluated, the end result of this (complex) example
348 will be an array passed of digits from 1 to 10 passed to the values
349 clause.
350 In any function at any point in time during processing, the qwparam()
352 function can be called to return the results of a particular question
353 as it was answered by the user. I.e., if a question named their_name
354 was answered with "John Doe" at any point in the past series of wizard
355 screens, then qwparam('their_name') would return "John Doe". As most
356 VALUE functions will be designed to process previous user input, under‐
357 standing this is the key to using the QWizard Perl module. More infor‐
358 mation and examples follow in the sections below.
359 PRIMARY OPTIONS
361 These are the tokens that can be specified in a primary:
363 title => VALUE
365 The title name for the set of questions. This will be displayed at
366 the top of the screen.
367 introduction => VALUE
369 Introductory text to be printed above the list of questions for a
370 given primary. This is useful as a starting piece of text to help
371 the user with this particular wizard screen. Display of the intro‐
372 ductory text is controlled by the Net-Policy pref_intro user pref‐
373 erence. The default is to display introductory text, but this set‐
374 ting can be turned off and on by the user.
375 questions => [{ QUESTION_DEFINITION }, { QUESTION_DEFINITION }, ...]
377 This is a list of questions to pose to the user for this screen.
378 The Question Definitions section describes valid question format‐
380 ting.
381 post_answers => [ VALUES ]
383 This is a list of actions to run after the questions on the screen
384 have been answered. Although this is a VALUES clause, as described
385 above, these should normally be subroutines and not hard-coded val‐
386 ues. The first argument to the VALUE functions will be a reference
387 to the wizard. This is particularly useful to conditionally add
388 future screens/primaries that need to be shown to the user. This
389 can be done by using the following add_todos() function call in the
390 action section:
391 if (some_condition()) {
393 $_[0]->add_todos('primary1', ...);
394 }
395 See the QWizard Object Functions section for more information on
397 the add_todos() function, but the above will add the 'primary1'
398 screen to the list of screens to display for the user before the
399 wizard is finished.
400 A post_answers subroutine should return the word "OK" for it to be
402 successful (right now, this isn't checked, but it may be (again) in
403 the future). It may also return "REDISPLAY" which will cause the
404 screen to displayed again.
405 For HTML output, these will be run just before the next screen is
407 printed after the user has submitted the answers back to the web
408 server. For window-based output (Gtk2, Tk, etc.) the results are
409 similar and these subroutines are evaluated before the next window
410 is drawn.
411 check_value => sub { ... }
413 check_value => [sub { ... }, arg1, arg2, ...]
414 The primary may have a check_value clause assigned to it to do high
415 level consistency checks. Returning anything but "OK" will have
416 the returned text displayed as an error to the user that they
417 should fix before they're allowed to continue past the screen.
418 actions => [ VALUES ]
420 The action functions will be run after the entire wizard series of
421 questions has been displayed and answered and after the user has
422 hit the "commit" button. It is assumed that the actions of the
423 earlier screens are dependent on the actions of the later screens
424 and so the action functions will be executed in reverse order from
425 the way the screens were displayed. See the add_todos() function
426 description in the QWizard Object Functions section for more infor‐
427 mation on to change the order of execution away from the default.
428 The collected values returned from the VALUES evaluation will be
430 displayed to the user. Any message beginning with a 'msg:' prefix
431 will be displayed as a normal output line. Any value not prefixed
432 with 'msg:' will be displayed as an error (typically displayed in
433 bold and red by most generators.)
434 actions_descr => [ VALUES ]
436 Just before the actions are run, a change-summary screen is shown
437 to the user. A "commit" button will also be given on this screen.
438 VALUE strings, function results, etc., will be displayed as a list
439 on this commit screen. Strings may have embedded special @TAG@
440 keywords which will be replaced by the value for the question with
441 a name of TAG. These strings should indicate to the user what the
442 commit button will do for any actions to be run by this set of
443 questions. If any question was defined whose name was no_confirm
444 and whose value was 1, this screen will be skipped and the actions
445 will be run directly.
446 sub_modules => [ 'subname1', ... ]
448 This hash value adds the specified sub-modules to the list of
449 screens to display after this one. This is equivalent to having a
450 post_answers clause that includes the function:
451 sub { $_[0]->add_todos('subname1', ...); }
453 doif => sub { LOGIC }
455 Allows primaries to be optional and only displayed under certain
456 conditions.
457 If specified, it should be a CODE reference which when executed
459 should return a 1 if the primary is to be displayed or a 0 if not.
460 The primary will be entirely skipped if the CODE reference returns
461 a 0.
462 topbar
464 A place to add extra widgets to a primary at the very top.
465 See the bar documentation in the QUESTION DEFINITIONS section below
467 for details on this field.
468 leftside => [WIDGETS]
470 rightside => [WIDGETS]
471 Adds a left or right side frame to the main screen where the WID‐
472 GETS are shown for this primary.
473 Important note: See the leftside/rightside documentation for QWiz‐
475 ard for more details and support important notes there.
476 take_over => \&subroutine
478 This hash value lets a subroutine completely take control of pro‐
479 cessing beyond this point. The wizard methodology functionally
480 stops here and control for anything in the future is entirely
481 passed to this subroutine. This should be rarely (if ever) used
482 and it is really a way of breaking out of the wizard completely.
483 QUESTION DEFINITIONS
485 Questions are implemented as a collection of hash references. A ques‐
487 tion generally has the following format:
488 {
490 type => QUESTION_TYPE
491 text => QUESTION_TEXT,
492 name => NAME_FOR_ANSWER,
493 default => VALUE,
494 # for menus, checkboxes, multichecks, ... :
495 values => [ VALUE1, VALUE2, ... ], # i.e., [VALUES]
496 # for menus, checkboxes, multichecks, ... :
497 labels => { value1 => label1, value2 => label2 } # i.e., [VALUES]
498 }
499 Other than this sort of hash reference, the only other type of question
501 allowed in the question array is a single "" empty string. The empty
502 string acts as a vertical spatial separator, indicating that a space
503 should occur between the previous question and the next question.
504 The fields available to question types are given below. Unless other‐
506 wise stated, the fields are available to all question types.
507 name => 'NAME'
509 Names the answer to the question. This name can then be used later
510 in other sections (action, post_answers, etc.) to retrieve the
511 value of the answer using the qwparam() function. For example,
512 qwparam('NAME') at any point in future executed code should return
513 the value provided by the user for the question named 'NAME'.
514 The namespace for these names is shared among all primaries (except
516 'remapped' primaries, which are described later). A warning will
517 be issued if different questions from two different primaries use
518 the same name. This warning will not be given if the question con‐
519 tains an override flag set to 1.
520 text => 'QUESTION TEXT'
522 Text displayed for the user for the given question. The text will
523 generally be on the left of the screen, and the widget the user is
524 supposed to interact with will be to the question text's right.
525 (This is subject to the implementation of the back-end question
526 Generator. The standard QWizard generators use this layout
527 scheme.)
528 type => 'TYPE'
530 Defines the type of question. TYPE can be one of:
531 label Displays information on the screen without requesting any
533 input. The text of the question is printed on the left
534 followed by the values portion on the right. If the values
535 portion is omitted, the text portion is printed across the
536 entire width of the screen.
537 paragraph
539 Paragraphs are similar to labels but are designed for spa‐
540 ces where text needs to be wrapped and is likely to be
541 quite long.
542 text Text input. Displays an entry box where a standard single
544 line of text can be entered.
545 textbox Text input, but in a large box allowing for multi-line
547 entries.
548 hidetext
550 Obscured text input. Displays a text entry box, but with
551 the typed text echoed as asterisks. This is suitable for
552 prompting users for entering passwords, as it is not shown
553 on the screen.
554 checkbox
556 A checkbox. The values clause should have only 2 values in
557 it: one for its "on" value, and one for its "off" value
558 (which defaults to 1 and 0, respectively).
559 The button_label clause can specify text to put right next
561 to the checkbox itself.
562 If a backend supports key accelerators (GTk2): Checkbox
564 labels can be bound to Alt-key accelerators. See QUESTION
565 KEY-ACCELERATORS below for more information.
566 multi_checkbox
568 Multiple checkboxes, one for each label/value pair. The
569 name question field is a prefix, and all values and/or
570 label keywords will be the second half of the name.
571 For example, the following clauses:
573 {
575 type => 'multi_checkbox',
576 name => 'something',
577 values => ['end1','end2'],
578 ...
579 }
580 will give parameters of 'somethingend1' and 'somethin‐
582 gend2'.
583 If a backend supports key accelerators (GTk2): Checkbox
585 labels can be bound to Alt-key accelerators. See QUESTION
586 KEY-ACCELERATORS below for more information.
587 radio Radio buttons, only one of which can be selected at a time.
589 If two questions have the same name and are of type
590 'radio', they will be "linked" together such that clicking
591 on a radio button for one question will affect the other.
592 If a backend supports key accelerators (GTk2): Radio button
594 labels can be bound to Alt-key accelerators. See QUESTION
595 KEY-ACCELERATORS below for more information.
596 menu Pull-down menu, where each label is displayed as a menu
598 item. If just the values clause (see below) is used, the
599 labels on the screen will match the values. If the default
600 clause is set, then that menu entry will be the menu's ini‐
601 tial selection. If the labels clause is used, the values
602 shown to the user will be converted to the screen represen‐
603 tations that will differ from the qwparam() values avail‐
604 able later. This is useful for displaying human represen‐
605 tations of programmatic values. E.g.:
606 {
608 type => 'menu',
609 name => 'mymenu',
610 labels => [ 1 => 'my label1',
611 2 => 'my label2']
612 }
613 In this example, the user will see a menu containing 2
615 entries "my label1" and "my label2", but qwparam() will
616 return 1 or 2 for qwparam('mymenu').
617 table Table to display. The values section should return a ref‐
619 erence to an array, where each element of the array is a
620 row containing the columns to display for that row. The
621 top-most table must actually be returned in an array
622 itself. (This is due to an oddity of internal QWizard pro‐
623 cessing). E.g.:
624 {
626 type => 'table',
627 text => 'The table:',
628 values => sub {
629 my $table = [['row1:col1', 'row1:col2'],
630 ['row2:col1', 'row2:col2']];
631 return [$table];
632 }
633 }
634 This would be displayed graphically on the screen in this
636 manner:
637 row1:col1 row1:col2
639 row2:col1 row2:col2
641 Additionally, a column value within the table may itself be
643 a sub-table (another double-array reference set) or a hash
644 reference, which will be a sub-widget to display any of the
645 other types listed in this section.
646 Finally, a headers clause may be added to the question def‐
648 inition which will add column headers to the table. E.g.:
649 headers => [['col1 header','col2 header']]
651 fileupload
653 A dialog box for a user to upload a file into the applica‐
654 tion. When a user submits a file the question name can be
655 used later to retrieve a read file handle on the file using
656 the function qw_upload_fh('NAME'). qwparam('NAME') will
657 return the original name of the file submitted, but because
658 of the variability in how web-browsers submit file names
659 along with the data, this field should generally not be
660 used. Instead, get access to the data through the
661 qw_upload_fh() function instead. The second best alterna‐
662 tive is to use the qw_upload_file('NAME') function which
663 returns a safe path to access under web-environments (which
664 will be something like /tmp/qwHTMLXXXXXX...)
665 filedownload
667 A button that allows the user to download something gener‐
668 ated by the application. The data that will be stored in
669 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 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 The datafn field should contain a CODE reference that will
681 be called with five arguments:
682 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 { 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 Currently only Gtk2 supports this button, but others
700 will in the future.
701 image
703 Image file. The image name is specified by the image
704 hash keyword. Several optional hash keys are recog‐
705 nized to control display of the image. imagealt speci‐
706 fies 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 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 Additionally, the GD::Graph options can be specified
720 with a graph_options tag to the question, allowing cre‐
721 ation of such things as axis labels and legends.
722 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 Widget Options:
731 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 The function should return undef when no parent
738 exists above the current node.
739 children => CODEREF
741 The children function will be passed a wizard ref‐
742 erence and a node name. It is expected to return
743 an array reference to all the children names. It
744 may also return a hash reference for some names
745 instead, which will contain an internal name tag
746 along with a label tag for displaying something to
747 the user which is different than is internally
748 passed around as the resulting selected value.
749 An example return array structure could look like:
751 [
753 'simple string 1',
754 'simple string 2',
755 {
756 name => 'myanswer:A',
757 label => 'Answer #A'
758 },
759 {
760 name => 'myanswer:B',
761 label => 'Answer #B'
762 },
763 ]
764 The function should return undef when no children
766 exist below the current node.
767 expand_all => NUM
769 The expand_all tag may be passed which will indi‐
770 cate that all initial option trees sholud be
771 expanded up to the number indicated by the
772 expand_all tag.
773 button
775 Button widget. When the button is clicked, the QWizard
776 parameter name (available by calling qwparam('name'))
777 will be assigned the value indicated by the default
778 clause. The parameter value will not be set if the
779 button is not clicked. The button's label text will be
780 set to the value of the values clause.
781 The button widget will be equivalent to pressing the
783 next button. The next primary will be shown after the
784 user presses the button.
785 If a backend supports key accelerators (GTk2): Button
787 labels can be bound to Alt-key accelerators. See QUES‐
788 TION KEY-ACCELERATORS below for more information.
789 bar A bar widget is functionally a separator in the middle
791 of the list of questions. It is useful for breaking a
792 set of questions in two as well as providing button-
793 containers or menu containers within widget sets and
794 not having them tied to the normal QWizard left/right
795 feel. One intentional artifact of this is they can be
796 used to provide a visual difference between the flow of
797 the questions. EG, if the QWizard primary showed a
798 screen which had two questions in it, it would look
799 something like the following when displayed by most of
800 the generators that exist today:
801 +-------------------+-----------------+
803 ⎪ Question 1 ⎪ Answer Widget 1 ⎪
804 ⎪ Longer Question 2 ⎪ Answer Widget 2 ⎪
805 +-------------------+-----------------+
806 Adding a bar in the middle of these questions, however,
808 would break the forced columns above into separate
809 pieces:
810 +------------+------------------------+
812 ⎪ Question 1 ⎪ Answer Widget 1 ⎪
813 +------------+------------------------+
814 ⎪ BAR ⎪
815 +-------------------+-----------------+
816 ⎪ Longer Question 2 ⎪ Answer Widget 2 ⎪
817 +-------------------+-----------------+
818 Finally, there is an implicit top bar in every primary
820 and the QWizard object as a whole. You can push
821 objects onto this bar by adding objects to the $qwiz‐
822 ard->{'topbar'} array or by adding objects to a pri‐
823 mary's 'topbar' tag. E.G.
824 my $qw = new QWizard(primaries => \%primaries,
826 topbar => [
827 {
828 type => 'menu', name => 'menuname',
829 values => [qw(1 2 3 4)],
830 # ...
831 }]);
832 The widgets shown in the topbar will be a merge of
834 those from the QWizard object and the primary currently
835 being displayed.
836 TODO: make it work better with merged primaries
838 TODO: make a bottom bar containing the next/prev/cancel
840 buttons
841 hidden
843 This clause is used to set internal parameters (name =>
844 value), but these values are not shown to the user.
845 Note: This is not a secure way to hide information
847 from the user. The data set using hidden are con‐
848 tained, for example, in the HTML text sent to the user.
849 dynamic
851 A dynamic question is one where the values field is
852 evaluated and is expected to return an array of ques‐
853 tion definitions which are in turn each evaluated as a
854 question. It is useful primarily when doing things
855 like creating a user-defined number of input fields, or
856 interacting with an external data source where the num‐
857 ber of questions and their nature is directly related
858 to the external data source.
859 raw Raw data. The values portion is displayed straight to
861 the screen. Use of this is strongly discouraged.
862 Obviously, the values portion should be a subroutine
863 that understands how to interact with the generator.
864 Really, don't use this. It's for emergencies only. It
866 only works with HTML output.
867 values => [ VALUES ]
869 An array of values that may be assigned to question types
870 that need choices (eg: menu, checkbox, multi_checkbox.) It
871 should be a reference to an array containing a list of
872 strings, functions to execute, and possibly sub-arrays con‐
873 taining a function and arguments, as described by the VALUE
874 conventions section above. Any function listed in a values
875 clause should return a list of strings.
876 The values clause is not needed if the labels clause is
878 present.
879 labels => [ VALUE1 => 'LABEL1', VALUE2 => 'LABEL2', ... ]
881 Assigns labels to the question's values. Labels are dis‐
882 played to the user instead of the raw values. This is use‐
883 ful for converting human-readable text strings into real-
884 world values for use in code.
885 If the values clause is not specified and the labels clause
887 is, the values to display are extracted from this labels
888 clause directly. If a value from the values clause does
889 not have a corresponding label, the raw value is presented
890 and used instead. Generally, only the labels clause should
891 be used with radio buttons, menus, or check boxes; but
892 either or both in combination work.
893 The labels clause subscribes to all the properties of the
895 VALUES convention previously discussed. Thus, it may be a
896 function, an array of functions, or any other type of data
897 that a VALUE may be. The final results should be an array,
898 especially if the values clause is not present, as the
899 order displayed to the user can be specified. It can also
900 be a hash as well but the displayed order is subject to
901 Perl keys() conventions and thus an array is preferred when
902 no values clause has been defined.
903 default => VALUE
905 The default value to use for this question. It may be a
906 subroutine reference which will be called to calculate and
907 return the value.
908 check_value => \&subroutine
910 A script to check the answer submitted by the user for
911 legality. The script should return 'OK' to indicate no
912 error found. In the event an error is detected, it should
913 return an error string. The string will be shown to the
914 user as an error message that the user must fix before
915 being allowed to proceed further in the wizard screens.
916 Alternately, the script may return 'REDISPLAY' to indicate
917 no error but that screen should be redisplyed (perhaps with
918 new values set with qwparam() from within the script). In
919 the case of error or 'REDISPLAY', the current primary
920 screen will be repeated until the function returns 'OK'.
921 The arguments passed to the function are the reference to
923 the wizard, a reference to the question definition (the
924 hash), and a reference to the primary containing the ques‐
925 tion (also a hash.) The function should use the qwparam()
926 function to obtain the value to check. An array can be
927 passed in which the first argument should be the subroutine
928 reference, and the remaining arguments will be passed back
929 to the subroutine after the already mentioned default argu‐
930 ments.
931 There are a set of standard functions that can be used for
933 checking values. These are:
934 \&qw_required_field
936 Ensures that a value is supplied or else a "This is a
937 required field" error message is returned. The func‐
938 tion only checks that the value is non-zero in length.
939 \&qw_integer
941 \&qw_optional_integer
942 Ensures that the value is an integer value (required or
943 not, respectively.)
944 \&qw_hex
946 \&qw_optional_hex
947 Ensures that the value is a hex string (required or
948 not, respectively.)
949 [\&qw_check_hex_and_length, length]
951 Ensures that a value is supplied and is a hex string
952 sufficiently long for length bytes. This means that the
953 hex string must be "length * 2" ASCII characters (two
954 hex characters per byte.)
955 [\&qw_check_int_ranges, low1, high1, low2, high2, ...]
957 Ensures that the value specified falls within one of
958 the lowX - highX ranges. The value must be between
959 (low1 and high1) or (low2 and high2).
960 [\&qw_check_length_ranges, low1, high1, low2, high2, ...]
962 qw_check_length_ranges is similar to
963 qw_check_int_ranges(), but it checks that the length of
964 the data string specified by the user falls within the
965 given ranges.
966 doif => sub { LOGIC }
968 Allows questions to be optional and only displayed under
969 certain conditions.
970 If specified, it should be a CODE reference which when exe‐
972 cuted should return a 1 if the question is to be displayed
973 or a 0 if not. The question will be entirely skipped if
974 the CODE reference returns a 0.
975 helptext =item helpdescr
977 If specified, these define the help text for a question.
978 helpdescr should be short descriptions printed on screen
979 when the wizard screen is displayed, and helptext should be
980 a full length description of help that will be displayed
981 only when the user clicks on the help button. helpdescr is
982 optional, and a button will be shown linking to helptext
983 regardless.
984 indent => 1
986 Slightly indents the question for some generators.
987 submit => 1
989 When this is specified as a question argument, if the user
990 changes the value then it will also be the equivelent of
991 pressing the 'Next' button at the same time. With the HTML
992 generator, this requires javascript and thus you shouldn't
993 absolutely depend on it working.
994 refresh_on_change => 1
996 If the contents of a screen are generated based on data
997 extracted from dynamically changing sources (e.g., a data‐
998 base), then setting this parameter to 1 will make the cur‐
999 rent question force a refresh if the value changes (ie,
1000 when they pull down a menu and change the value or click on
1001 a checkbox or ...) and the screen be redrawn (possibly
1002 changing its contents).
1003 As an example, Net-Policy uses this functionality to allow
1005 users to redisplay generated data tables and changes the
1006 column that is used for sorting depending on a menu widget.
1007 handle_results => sub { ... }
1009 The handle_results tag can specify a CODE reference to be
1010 run when the questions are answered so each question can
1011 perform its own processing. This is sort of like a per-
1012 question post_answers hook equivalent.
1013 QUESTION KEY-ACCELERATORS
1015 Some generators (currently only Gtk2 actually) support key accelerators
1017 so that you can bind alt-keys to widgets. This is done by including a
1018 '_' (underscore) character where appropriate to create the binding.
1019 EG:
1020 {
1022 type => 'radio',
1023 text => 'select one:',
1024 values => ['_Option1','O_ption2', 'Option3']
1025 }
1026 When Gtk2 gets the above construct it will make Alt-o be equivelent to
1028 pressing the first option and Alt-p to the second. It will also dis‐
1029 play the widget with a underline under the character that is bound to
1030 the widget. HTML and other non-accelerator supported interfaces will
1031 strip out the _ character before displaying the string in a widget.
1032 In addition, unless a no_auto_accelerators = 1> option is passed to the
1034 generator creation arguments, widgets will automatically get accelera‐
1035 tors assigned to them. In the above case the 't' in Option3 would
1036 automatically get assigned the Alt-t accelerator (the 't' is selected
1037 because it hasn't been used yet, unlike the o and p characters). You
1038 can also prefix something with a ! character to force a single widget
1039 to not receive an auto-accelerator (EG: "!Option4" wouldn't get one).
1040
1042 A few QWizard parameters are special and help control how QWizard
1043 behaves. Most of these should be set in the primaries question sets
1044 using a hidden question type.
1045 no_actions
1047 If set to 1, the actions phase will not be run.
1048 no_confirm
1050 If set to 1, the screen which prompts the user to decide if they
1051 really want to commit their series of answers won't be shown.
1052 Instead, QWizard will jump straight to the actions execution (if
1053 appropriate.) This can also be given as a parameter to the QWizard
1054 new() function to make it always true.
1055 allow_refresh
1057 If the contents of a screen are generated based on data extracted
1058 from dynamically changing sources (e.g., a database), then setting
1059 this parameter to 1 will add a "Refresh" button beside the "Next"
1060 button so that the user can request the screen be redrawn (possibly
1061 changing its contents).
1062 As an example, Net-Policy uses this functionality to allow users to
1064 redisplay generated graphs and maps that will change dynamically as
1065 network data are collected.
1066 This token can also be set directly in a primary definition to
1068 affect just that primary screen.
1069 QWizard_next
1071 The button text to display for the "Next" button. This defaults to
1072 "_Next" but can be overridden using this parameter.
1073 QWizard_commit
1075 The button text to display for the "Commit" button. This defaults
1076 to "_Commit" but can be overridden using this parameter. The com‐
1077 mit button is shown after the questions have been asked and the
1078 actions_descr's are being shown to ask the user if they really want
1079 to run the actions.
1080 QWizard_finish
1082 The button text to display for the "Finish" button. This defaults
1083 to "_Finish" but can be overridden using this parameter. The fin‐
1084 ish button is shown after the actions have been run and the results
1085 are being displayed.
1086
1088 The following parameters are used internally by QWizard. They should
1089 not be modified.
1090 pass_vars
1092 qw_cancel
1093 no_cancel
1094 qwizard_tree
1095 display_help_p
1096 disp_q_num
1097 redo_screen
1098 upd_time
1099 wiz_confirmed
1100 wiz_canceled
1101 wizard_queue_list
1102
1104 The following functions are defined in the QWizard class and can be
1105 called as needed.
1106 $qw->magic(primary_name, ...);
1108 This tells QWizard to start its magic, beginning at the primary
1109 named primary_name. Multiple primaries will be displayed one after
1110 the other until the list of primaries to display is empty. The
1111 actions clauses of all these primaries will not be run, however,
1112 until after all the primaries have been processed.
1113 The magic() routine exits only after all the primaries have been
1115 run up through their actions, or unless one of the following condi‐
1116 tions occurs:
1117 - $qw->{'one_pass'} == 1
1119 - $qw->{'generator'}{'one_pass'} == 1
1120 By default, some of the stateless generators (HTML) will set their
1122 one_pass option automatically since it is expected that the client
1123 will exit the magic() loop and return later with the next set of
1124 data to process. The magic() routine will automatically restart
1125 where it left off if the last set of primaries being displayed was
1126 never finished. This is common for stateless generators like HTTP
1127 and HTML.
1128 $qw->finished();
1130 Closes the open qwizard window. Useful after your magic() routine
1131 has ended and you don't intend to call it again. Calling fin‐
1132 ished() will remove the QWizard window from visibility.
1133 $qw->set_progress(FRACTION, TEXT);
1135 If available, some generators (Gtk2 can) may be able to display a
1136 progress meter. If they are, calling this function inside action
1137 clauses, for example, will start the display of this meter with
1138 FRACTION complete (0 <= FRACTION <= 1). The TEXT is optional and
1139 if left blank will be set to NN% showing the percentage complete.
1140 $qw->add_todos([options], primary_name, ...);
1142 Adds a primary to the list of screens to display to the user. This
1143 function should be called during the post_answers section of a pri‐
1144 mary. Options that can be passed before the first primary name
1145 are:
1146 -early
1148 Adds the primaries in question as early as possible in the todo
1149 list (next, unless trumped by future calls.) This is the
1150 default.
1151 -late
1153 Adds the primary to the end of the list of primaries to call,
1154 such that it is called last, unless another call to add_todos()
1155 appends something even later.
1156 -actionslast
1158 All the actions of subsequent primaries that have been added as
1159 the result of a current primary's post_answers clauses are
1160 called before the actions for the current primary. This means
1161 that the actions of any childrens are executed prior to the
1162 actions of their parents. This is done by default, as the gen‐
1163 eral usage prediction is that parent primaries are likely to be
1164 dependent on the actions of their children in order for their
1165 own actions to be successful.
1166 However, this flag indicates that the actions of the childrens'
1168 primaries listed in this call are to be called before the cur‐
1169 rent primary's actions.
1170 -merge
1172 Merges all the specified primaries listed into a single screen.
1173 This has the effect of having multiple primaries displayed in
1174 one window.
1175 Important note: you can not use both -remap (see below) and
1177 -merge at the same time! This will break the remapping support
1178 and you will not get expected results!
1179 -remap => 'NAME'
1181 If a series of questions must be called repeatedly, you can use
1182 this flag to remap the names of the child primary questions to
1183 begin with this prefix. The children's clauses (questions,
1184 actions, post_answers, etc.) will be called in such a way that
1185 they can be oblivious to the fact this is being done behind
1186 their backs, allowing qwparam() to work as expected. However,
1187 for the current primary (and any parents), the 'NAME' prefix
1188 will be added to the front of any question name values that the
1189 child results in defining.
1190 This is rather complex and is better illustrated through an
1192 example. There is an example that illustrates this in the
1193 QWizard Perl module source code examples directory, in the file
1194 number_adding.pl. This code repeatedly asks for numbers from
1195 the user using the same primary.
1196 Important note: you can not use both -remap and -merge at the
1198 same time! This will break the remapping support and you will
1199 not get expected results!
1200 $qw->add_primary(key => value, key => value);
1202 Adds a primary definition into the existing primary data set for
1203 the QWizard object. One key value pair MUST be a 'name' => 'NAME'
1204 pair, where NAME will be the installed primary name for later
1205 referral (e.g., in add_todos() calls.) If a name collision takes
1206 place (a primary already exists under the given name), the original
1207 is kept and the new is not installed.
1208 $qw->merge_primaries(\%new_primaries);
1210 Merges a new set of primaries into the existing set. If a name
1211 collision takes place, the original is kept and the new is not
1212 installed.
1213 $qw->get_primary('NAME');
1215 Returns a primary definition given its NAME.
1216 $val = $qw->qwparam('NAME')
1218 $val = qwparam('NAME')
1219 $qw->qwparam('NAME', 'VALUE')
1220 qwparam('NAME', 'VALUE')
1221 Retrieves a value specified by NAME that was submitted by a user
1222 from a QWizard widget. If a VALUE is specified as a second argu‐
1223 ment, it replaces the previous value with the new for future calls.
1224 QWizard parameters are accessible until the last screen in which
1226 all the actions are run and the results are displayed. Parameters
1227 are not retained across primary execution.
1228 The qwparam() function is exported by the QWizard module by
1230 default, so the function shouldn't need to be called directly from
1231 the QWizard object. Thus, just calling qwparam('NAME') by itself
1232 will work.
1233 $val = $qw->qwpref('NAME')
1235 $val = qwpref('NAME')
1236 $qw->qwpref('NAME', 'VALUE')
1237 qwpref('NAME', 'VALUE')
1238 qwpref() acts almost identically to qwparam(), except that it is
1239 expected to be used for "preferences" -- hence the name. The pref‐
1240 erences are stored persistently across primary screens, unlike
1241 parameters. Preferences are not erased between multiple passes
1242 through the QWizard screens. (In the HTML generator, they are
1243 implemented using cookies).
1244
1246 TBD: Document the $qw->add_hook and $qw->run_hooks methods that exist.
1247 (basically $qw->add_hook('start_magic', \&coderef) will run coderef at
1249 the start of the magic function. Search the QWizard code for run_hooks
1250 for a list of hook spots available.
1251
1253 The variable $QWizard::qwdebug controls debugging output from QWizard.
1254 If set to 1, it dumps processing information to STDERR. This can be
1255 very useful when debugging QWizard scripts as it displays the step-by-
1256 step process about how QWizard is processing information.
1257 Additionally, a qwdebug_set_output() function exists which can control
1259 the debugging output destination. Its argument should be a reference
1260 to a variable where the debugging output will be stored. Thus, debug‐
1261 ging information can be stored to a previously opened error log file by
1262 doing the following:
1263 our $dvar;
1265 $QWizard::qwdebug = 1;
1266 $qw->qwdebug_set_output(\$dvar);
1267 $qw->magic('stuff');
1268 print LOGFILE $dvar;
1269
1271 There are a few usage examples in the examples directory of the source
1272 package. These examples can be run from the command line or installed
1273 as a CGI script without modification. They will run as a CGI script if
1274 run from a web server, or will launch a Gtk2 or Tk window if run from
1275 the command line.
1276
1278 qwparam(), qwpref()
1279 qw_required_field(), qw_integer(), qw_optional_integer(),
1281 qw_check_int_ranges(), qw_check_length_ranges(), qw_hex(),
1282 qw_optional_hex(), qw_check_hex_and_length()
1283
1285 Wes Hardaker, hardaker@users.sourceforge.net
1286
1288 Copyright (c) 2003-2007, SPARTA, Inc. All rights reserved
1289 Copyright (c) 2006-2007, Wes Hardaker. All rights reserved
1291 QWizard is free software; you can redistribute it and/or modify it
1293 under the same terms as Perl itself.
1294
1296 For extra information, consult the following manual pages:
1297 QWizard_Widgets
1299 Manual page for more information about the Various QWizard display
1300 generators and the questions and arguments that each one supports.
1301 This page is actually generated from what the generator actually
1302 advertises that it supports.
1303 QWizard::API
1305 If you get tired of typing anonymous hash references, this API set
1306 will let you generate some widgets with less typing by using APIs
1307 instead.
1308 Example API call:
1310 perl -MQWizard::API -MData::Dumper -e 'print Dumper(qw_checkbox("my ?","it",'A','B', default => 'B'));'
1312 $VAR1 = {
1313 'text' => 'it',
1314 'name' => 'my ?',
1315 'default' => 'B',
1316 'values' => [
1317 'A',
1318 'B'
1319 ],
1320 'type' => 'checkbox'
1321 };
1322 Net-Policy: http://net-policy.sourceforge.net/
1324 The entire QWizard system was created to support a multiple-access-
1325 point network management system called "Net-Policy" and the SVN
1326 repository for Net-Policy actually contains the QWizard development
1327 tree.
1328perl v5.8.8 2008-04-17 QWizard(3)