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 #
45 # PLEASE see the examples in the examples directory.
46 #
47
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 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 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 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 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 An example very minimal primary definition containing one question:
91 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 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 my $qw = new QWizard(primaries => \%primaries,
114 title => 'my title');
115 $qw->magic('myprimary');
116 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 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 ################
135 ## WARNING: pseudo-code describing a process! Not real code!
136 ################
137 # 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 # Displays a "will be doing these things" screen,
147 # and has a commit button.
148 display_commit_screen();
149 # 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 # If magic() is called again, it restarts from
158 # the top primary again.
159 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 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
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 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
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 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 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
231 displayed.
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
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 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
271 Buttons".
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
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 %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 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 VALUE conventions
324 In the documentation to follow, any time the keyword VALUE appears, the
326 following types of "values" can be used in its place:
327 - "a string"
329 - 10
330 - \&sub_to_call
331 - sub { return "a calculated string or value" }
332 - [\&sub_to_call, arguments, to, sub, ...]
333 Subroutines are called and expected to return a single value or an
335 array reference of multiple values.
336 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 sub my_examp1 { return 3; }
342 sub my_examp2 { return [$_[0]..$_[1]]; }
343 values => [1, 2, \&my_examp1, [\&my_examp2, 4, 10]],
345 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 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 PRIMARY OPTIONS
360 These are the tokens that can be specified in a primary:
361 title => VALUE
363 The title name for the set of questions. This will be displayed at
364 the top of the screen.
365 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 questions => [{ QUESTION_DEFINITION }, { QUESTION_DEFINITION }, ...]
375 This is a list of questions to pose to the user for this screen.
376 The Question Definitions section describes valid question
378 formatting.
379 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 if (some_condition()) {
391 $_[0]->add_todos('primary1', ...);
392 }
393 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 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 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 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 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 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 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 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 sub { $_[0]->add_todos('subname1', ...); }
452 doif => sub { LOGIC }
454 Allows primaries to be optional and only displayed under certain
455 conditions.
456 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 topbar
463 A place to add extra widgets to a primary at the very top.
464 See the bar documentation in the QUESTION DEFINITIONS section below
466 for details on this field.
467 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 Important note: See the leftside/rightside documentation for
474 QWizard for more details and support important notes there.
475 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 QUESTION DEFINITIONS
484 Questions are implemented as a collection of hash references. A
485 question generally has the following format:
486 {
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 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 The fields available to question types are given below. Unless
504 otherwise stated, the fields are available to all question types.
505 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 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 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 type => 'TYPE'
528 Defines the type of question. TYPE can be one of:
529 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 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 text Text input. Displays an entry box where a standard single
542 line of text can be entered.
543 textbox Text input, but in a large box allowing for multi-line
545 entries.
546 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 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 The button_label clause can specify text to put right next
559 to the checkbox itself.
560 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 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 For example, the following clauses:
571 {
573 type => 'multi_checkbox',
574 name => 'something',
575 values => ['end1','end2'],
576 ...
577 }
578 will give parameters of 'somethingend1' and
580 'somethingend2'.
581 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 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 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 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 {
606 type => 'menu',
607 name => 'mymenu',
608 labels => [ 1 => 'my label1',
609 2 => 'my label2']
610 }
611 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 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 {
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 This would be displayed graphically on the screen in this
634 manner:
635 row1:col1 row1:col2
637 row2:col1 row2:col2
639 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 Finally, a headers clause may be added to the question
646 definition which will add column headers to the table.
647 E.g.:
648 headers => [['col1 header','col2 header']]
650 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 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 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
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 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
721 creation 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
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 An example return array structure could look like:
752 [
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 The function should return undef when no children
767 exist below the current node.
768 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 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 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 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 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 +-------------------+-----------------+
804 | Question 1 | Answer Widget 1 |
805 | Longer Question 2 | Answer Widget 2 |
806 +-------------------+-----------------+
807 Adding a bar in the middle of these questions, however,
809 would break the forced columns above into separate
810 pieces:
811 +------------+------------------------+
813 | Question 1 | Answer Widget 1 |
814 +------------+------------------------+
815 | BAR |
816 +-------------------+-----------------+
817 | Longer Question 2 | Answer Widget 2 |
818 +-------------------+-----------------+
819 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 my $qw = new QWizard(primaries => \%primaries,
827 topbar => [
828 {
829 type => 'menu', name => 'menuname',
830 values => [qw(1 2 3 4)],
831 # ...
832 }]);
833 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 TODO: make it work better with merged primaries
839 TODO: make a bottom bar containing the next/prev/cancel
841 buttons
842 hidden
844 This clause is used to set internal parameters (name =>
845 value), but these values are not shown to the user.
846 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 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 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 Really, don't use this. It's for emergencies only. It
868 only works with HTML output.
869 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 The values clause is not needed if the labels clause is
880 present.
881 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 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 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 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 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 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 There are a set of standard functions that can be used for
935 checking values. These are:
936 \&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 \&qw_integer
944 \&qw_optional_integer
945 Ensures that the value is an integer value (required or
946 not, respectively.)
947 \&qw_hex
949 \&qw_optional_hex
950 Ensures that the value is a hex string (required or
951 not, respectively.)
952 [\&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 [\&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 [\&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 doif => sub { LOGIC }
971 Allows questions to be optional and only displayed under
972 certain conditions.
973 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 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 indent => 1
989 Slightly indents the question for some generators.
990 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 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 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 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 QUESTION KEY-ACCELERATORS
1018 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 {
1025 type => 'radio',
1026 text => 'select one:',
1027 values => ['_Option1','O_ption2', 'Option3']
1028 }
1029 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 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
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 no_actions
1052 If set to 1, the actions phase will not be run.
1053 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 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 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 This token can also be set directly in a primary definition to
1073 affect just that primary screen.
1074 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 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 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
1093 The following parameters are used internally by QWizard. They should
1094 not be modified.
1095 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
1109 The following functions are defined in the QWizard class and can be
1110 called as needed.
1111 $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 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 - $qw->{'one_pass'} == 1
1124 - $qw->{'generator'}{'one_pass'} == 1
1125 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 $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 $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 $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 -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 -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 -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 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 -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 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 -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 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 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 $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 $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 $qw->get_primary('NAME');
1220 Returns a primary definition given its NAME.
1221 $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 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 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 $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
1252 TBD: Document the $qw->add_hook and $qw->run_hooks methods that exist.
1253 (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
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 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 our $dvar;
1271 $QWizard::qwdebug = 1;
1272 $qw->qwdebug_set_output(\$dvar);
1273 $qw->magic('stuff');
1274 print LOGFILE $dvar;
1275
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
1284 qwparam(), qwpref()
1285 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
1291 Wes Hardaker, hardaker@users.sourceforge.net
1292
1294 Copyright (c) 2003-2007, SPARTA, Inc. All rights reserved
1295 Copyright (c) 2006-2007, Wes Hardaker. All rights reserved
1297 QWizard is free software; you can redistribute it and/or modify it
1299 under the same terms as Perl itself.
1300
1302 For extra information, consult the following manual pages:
1303 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 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 Example API call:
1316 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 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.
1334perl v5.12.0 2008-09-17 QWizard(3)