1tepam::argument_diTacllo'gsboExn(hna)nced Procedure and ArgumteenptamM:a:naarggeurment_dialogbox(n)
2______________________________________________________________________________
6
8 tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual
9
11 package require Tcl 8.3
12 package require Tk 8.3
14 package require tepam ?0.5?
16 tepam::argument_dialogbox item_name item_attributes ?item_name
18 item_attributes? ?...?
19 tepam::argument_dialogbox {item_name item_attributes ?item_name
21 item_attributes? ?...?}
22______________________________________________________________________________
24
27 The TEPAM argument_dialogbox is a flexible and easily usable data entry
28 form generator that is available if Tk has been loaded. Each data entry
29 element of a form is defined via a data entry item that can be provided
30 to argument_dialogbox in two formats:
31 tepam::argument_dialogbox item_name item_attributes ?item_name
33 item_attributes? ?...?
34 Using this first format, each data entry item is defined via a
35 pair of two arguments. The first one is the item name that
36 defines the entry widget that has to be used in the form. The
37 second argument, called item attributes, specifies the variable
38 which is attributed to the data entry element as well as even‐
39 tual formatting and context information.
40 The argument_dialogbox returns ok if the entered data have been
42 acknowledged (via the OK button) and validated by a data
43 checker. If the entered data have been rejected (via the Cancel
44 button) the argument_dialogbox returns cancel.
45 A small example illustrates how the argument_dialogbox can be
47 employed:
48 set DialogResult [tepam::argument_dialogbox \
50 -title "Itinerary selection" \
51 -file {-label "Itinerary report" -variable report_file} \
52 -frame {-label "Itinerary start"} \
53 -comment {-text "Specify your itinerary start location"} \
54 -entry {-label "City" -variable start_city -type string} \
55 -entry {-label "Street" -variable start_street -type string -optional 1} \
56 -entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
57 -frame {-label "Itinerary destination"} \
58 -comment {-text "Specify your itinerary destination"} \
59 -entry {-label "City" -variable dest_city -type string} \
60 -entry {-label "Street" -variable dest_street -type string -optional 1} \
61 -entry {-label "Street number" -variable dest_street_nbr -type integer -optional 1} \
62 -frame {} \
63 -checkbutton {-label "Don't use highways" -variable no_highway}]
64 This example opens a dialog box that has the title Itinerary
66 selection. A first entry widget in this box allows selecting a
67 report file. It follows two frames to define respectively an
68 itinerary start and end location. Each of these locations that
69 are described with a comment has three entry widgets to specify
70 respectively the city, street and the street number. Bellow the
71 second frame there is a check button that allows specifying if
72 eventual highways should be ignored.
73 tepam::argument_dialogbox {item_name item_attributes ?item_name
75 item_attributes? ?...?}
76 Sometimes it is simpler to provide all the data entry item defi‐
77 nitions in form of a single list to argument_dialogbox, and not
78 as individual arguments. The second format that is supported by
79 argument_dialogbox corresponds exactly to the first one, except
80 that all item definitions are packed into a single list that is
81 provided to argument_dialogbox. The previous example can there‐
82 fore also be written in the following way:
83 set DialogResult [tepam::argument_dialogbox {
85 -title "Itinerary selection"
86 -file {-label "Itinerary report" -variable report_file}
87 ...
88 -checkbutton {-label "Don't use highways" -variable no_highway} }]
89 The commands argument_dialogbox as well as procedure are exported from
91 the namespace tepam. To use these commands without the tepam:: names‐
92 pace prefix, it is sufficient to import them into the main namespace:
93 namespace import tepam::*
95 set DialogResult [argument_dialogbox \
97 -title "Itinerary selection"
98 ...
99 The following subsections explain the different argument item types
100 that are accepted by the argument_dialogbox, classified into three
101 groups. The first data entry item definition format will be used in the
102 remaining document, knowing that this format can always be transformed
103 into the second format by putting all arguments into a single list that
104 is then provided to argument_dialogbox.
105 CONTEXT DEFINITION ITEMS
107 The first item group allows specifying some context aspects of an argu‐
108 ment dialog box. These items are taking a simple character string as
109 item attribute:
110 tepam::argument_dialogbox \
112 -<argument_name> string \
113 ...
114 The following items are classified into this group:
115 -title string
117 The dialog box window title which is by default Dialog can be
118 changed with the -title item:
119 tepam::argument_dialogbox \
121 -title "System configuration" \
122 ...
123 -window string
125 The argument dialog box uses by default .dialog as dialog top
126 level window. This path can be changed with the -window item:
127 tepam::argument_dialogbox \
129 -window .dialog \
130 ...
131 -parent string
133 By defining a parent window, the argument dialog box will be
134 displayed beside this one. Without explicit parent window defi‐
135 nition, the top-level window will be considered as parent win‐
136 dow.
137 tepam::argument_dialogbox \
139 -parent .my_appl \
140 ...
141 -context string
143 If a context is defined the dialog box state, e.g. the entered
144 data as well as the window size and position, is restored the
145 next time the argument dialog box is called. The assignment of a
146 context allows saving the dialog box state in its context to
147 distinguish between different usages of the argument dialog box.
148 tepam::argument_dialogbox \
150 -context destination_definitions \
151 ...
152 FORMATTING AND DISPLAY OPTIONS
154 Especially for big, complex forms it becomes important that the differ‐
155 ent data entry widgets are graphically well organized and commented to
156 provide an immediate and clear overview to the user. A couple of items
157 allow structuring and commenting the dialog boxes.
158 The items of this classification group require as item attributes a
160 definition list, which contains itself attribute name and value pairs:
161 tepam::argument_dialogbox \
163 ...
164 -<argument_name> {
165 ?-<attribute_name> <attribute_value>?
166 ?-<attribute_name> <attribute_value>?
167 ?...?
168 }
169 ...
170 The following items are classified into this group:
171 -frame list
173 The -frame item allows packing all following entry widgets into
174 a labeled frame, until a next frame item is defined or until the
175 last entry widget has been defined. It recognizes the following
176 attributes inside the item attribute list:
177 -label string
179 An optional frame label can be specified with the -label
180 statement.
181 Example:
183 tepam::argument_dialogbox \
185 ...
186 -frame {-label "Destination address"}
187 ...
188 To close an open frame without opening a new one, an empty list
190 has to be provided to the -frame statement.
191 tepam::argument_dialogbox \
193 ...
194 -frame {}
195 ...
196 -sep [const {{}}]
198 Entry widgets can be separated with the -sep statement which
199 doesn't require additional definitions. The related definition
200 list has to exist, but its content is ignored.
201 tepam::argument_dialogbox \
203 ...
204 -sep {}
205 ...
206 -comment string
208 Comments and descriptions can be added with the -text attribute
209 of the -comment item. Please note that each entry widget itself
210 can also contain a -text attribute for comments and descrip‐
211 tions. But the -comment item allows for example adding a
212 description between two frames.
213 tepam::argument_dialogbox \
215 ...
216 -comment {-text "Specify bellow the destination address"}
217 ...
218 -yscroll 0|1|auto
220 This attribute allows controlling an eventual vertical scroll‐
221 bar. Setting it to 0 will permanently disable the scrollbar,
222 setting it to 1 will enable it. By default it is set to auto.
223 The scrollbar is enabled in this mode only if the vertical data
224 entry form size exceeds 66% of the screen height.
225 tepam::argument_dialogbox \
227 ...
228 -yscroll auto
229 ...
230 GLOBAL CUSTOM DATA VALIDATION
232 This item group allows specifying global custom checks to validate the
233 entered data.
234 -validatecommand script
236 Custom data checks can be performed via validation commands that
237 are defined with the -validatecommand item. Example:
238 tepam::argument_dialogbox \
240 -entry {-label "Your comment" -variable YourCom} \
241 -validatecommand {IllegalWordDetector $YourCom}
242 The validation command is executed in the context of the calling
244 procedure, once all the basic data checks have been performed
245 and data variables are assigned. All data is accessed via the
246 data variables. Note that there is also an entry widget specific
247 attribute -validatecommand that allows declaring custom checks
248 for specific data entries.
249 The attribute -validatecommand can be repeated to declare multi‐
251 ple custom checks.
252 -validatecommand_error_text string
254 This item allows overriding the default error message for a
255 global custom argument validation (defined by -validatecommand).
256 Also this attribute can be repeated in case multiple checks are
257 declared.
258 -validatecommand2 script
260 -validatecommand2_error_text string
262 These items are mainly for TEPAM internal usage.
263 These items corrspond respectively to -validatecommand and -val‐
265 idatecommand_error_text. However, the data validation is not
266 performed in the next upper stack level, but two stack levels
267 higher.
268 DATA ENTRY WIDGET ITEMS
270 Data entry widgets are created with the widget items. These items
271 require as item attributes a definition list, which contains itself
272 attribute name and value pairs:
273 tepam::argument_dialogbox \
275 ...
276 -<argument_name> {
277 ?-<attribute_name> <attribute_value>?
278 ?-<attribute_name> <attribute_value>?
279 ?...?
280 }
281 ...
282 The attribute list can contain various attributes to describe and com‐
283 ment an entry widget and to constrain its entered value. All entry wid‐
284 gets are accepting a common set of attributes that are described in the
285 section Entry Widget Item Attributes.
286 TEPAM defines a rich set of entry widgets. If necessary, this set can
288 be extended with additional application specific entry widgets (see
289 APPLICATION SPECIFIC ENTRY WIDGETS):
290 -entry list
292 The -entry item generates the simplest but most universal data
293 entry widget. It allows entering any kind of data in form of
294 single line strings.
295 tepam::argument_dialogbox \
297 -entry {-label Name -variable Entry}
298 -text list
300 The -text item generates a multi line text entry widget. The
301 widget height can be selected with the -height attribute.
302 tepam::argument_dialogbox \
304 -text {-label Name -variable Text -height 5}
305 -checkbox list
307 A group of check boxes is created with the -checkbox item. The
308 number of check boxes and their option values are specified with
309 a list assigned to the -choices attribute or via a variable
310 declared with the -choicevariable attribute:
311 tepam::argument_dialogbox \
313 -checkbox {-label "Font sytle" -variable FontStyle \
314 -choices {bold italic underline} -default italic}
315 If the labels of the check boxes should differ from the option
317 values, their labels can be defined with the -choicelabels
318 attribute:
319 tepam::argument_dialogbox \
321 -checkbox {-label "Font sytle" -variable FontStyle \
322 -choices {bold italic underline} \
323 -choicelabels {Bold Italic Underline} \
324 -default italic}
325 In contrast to a radio box group, a check box group allows
327 selecting simultaneously several choice options. The selection
328 is stored for this reason inside the defined variable in form of
329 a list, even if only one choice option has been selected.
330 -radiobox list
332 A group of radio boxes is created with the -radiobox item. The
333 number of radio boxes and their option values are specified with
334 a list assigned to the -choices attribute or via a variable
335 declared with the -choicevariable attribute.
336 In contrast to a check box group, a radio box group allows
338 selecting simultaneously only one choice option. The selected
339 option value is stored directly, and not in form of a list,
340 inside the defined variable.
341 tepam::argument_dialogbox \
343 -radiobox {-label "Text adjustment" -variable Adjustment \
344 -choices {left center right} -default left}
345 If the labels of the radio boxes should differ from the option
347 values, their labels can be defined with the -choicelabels
348 attribute:
349 tepam::argument_dialogbox \
351 -radiobox {-label "Text adjustment" -variable Adjustment \
352 -choices {left center right} \
353 -choicelabels {Left Center Right} -default left}
354 -checkbutton list
356 The -checkbutton entry widget allows activating or deactivating
357 a single choice option. The result written into the variable
358 will either be 0 if the check button was not activated or 1 if
359 it was activated. An eventually provided default value has also
360 to be either 0 or 1.
361 tepam::argument_dialogbox \
363 -checkbutton {-label Capitalize -variable Capitalize -default 1}
364 Several types of list and combo boxes are available to handle selection
366 lists.
367 -combobox list
369 The combobox is a combination of a normal entry widget together
370 with a drop-down list box. The combobox allows selecting from
371 this drop-down list box a single element. The list of the avail‐
372 able elements can be provided either as a list to the -choices
373 attribute, or via a variable that is specified with the -choice‐
374 variable attribute.
375 tepam::argument_dialogbox \
377 -combobox {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}
378 And here is an example of using a variable to define the selec‐
380 tion list:
381 set TextSizes {8 9 10 12 15 18}
383 tepam::argument_dialogbox \
384 -combobox {-label "Text size" -variable Size -choicevariable TextSizes -default 12}
385 -listbox list
387 In contrast to the combo box, the list box is always displayed
388 by the listbox entry widget. Only one element is selectable
389 unless the -multiple_selection attribute is set. The list box
390 height can be selected with the -height attribute. If the height
391 is not explicitly defined, the list box height is automatically
392 adapted to the argument dialog box size. The first example uses
393 a variable to define the available choices:
394 set set AvailableSizes
396 for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}
397 tepam::argument_dialogbox \
399 -listbox {-label "Distance" -variable Distance \
400 -choicevariable AvailableSizes -default 6 -height 5}
401 Here is a multi-element selection example. Please note that also
403 the default selection can contain multiple elements:
404 tepam::argument_dialogbox \
406 -listbox {-label "Text styles" -variable Styles \
407 -choices {bold italic underline overstrike} \
408 -choicelabels {Bold Italic Underline Overstrike} \
409 -default {bold underline} -multiple_selection 1 \
410 -height 3}
411 -disjointlistbox list
413 A disjoint list box has to be used instead of a normal list box
414 if the selection order is important. The disjoint list box entry
415 widget has in fact two list boxes, one to select elements and
416 one to display the selected elements in the chosen order.
417 Disjoint listboxes allow always selecting multiple elements.
419 With the exception of the -multiple_selection attribute, dis‐
420 jointed list boxes are accepting the same attributes as the nor‐
421 mal listbox, e.g. -height, -choices, -choicevariable, -default.
422 tepam::argument_dialogbox \
424 -disjointlistbox {-label "Preferred scripting languages" -variable Languages \
425 -comment "Please select your preferred languages in the order" \
426 -choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \
427 -default {Tcl Perl Python}}
428 The file and directory selectors are building a next group of data
430 entry widgets. A paragraph of section Entry Widget Item Attributes
431 explains the widget specific attributes that allow specifying the tar‐
432 geted file types, active directory etc.
433 -file list
435 The item -file creates a group composed by an entry widget
436 together with a button that allows opening a file browser. The
437 data type file is automatically selected for this entry if no
438 data type has been explicitly defined with the -type attribute.
439 tepam::argument_dialogbox \
441 -file {-label "Image file" -variable ImageF \
442 -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
443 -initialfile "picture.gif"}
444 -existingfile list
446 The item -existingfile creates a group composed by an entry wid‐
447 get together with a button that allows opening a browser to
448 select an existing file. The data type existingfile is automati‐
449 cally selected for this entry if no data type has been explic‐
450 itly defined with the -type attribute.
451 tepam::argument_dialogbox \
453 -existingfile {-label "Image file" -variable ImageF \
454 -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
455 -initialfile "picture.gif"}
456 -directory list
458 The item -directory creates a group composed by an entry widget
459 together with a button that allows opening a directory browser.
460 The data type directory is automatically selected for this entry
461 if no data type has been explicitly defined with the -type
462 attribute.
463 tepam::argument_dialogbox \
465 -directory {-label "Report directory" -variable ReportDir}
466 -existingdirectory list
468 The item -existingdirectory creates a group composed by an entry
469 widget together with a button that allows opening a browser to
470 select an existing directory. The data type existingdirectory is
471 automatically selected for this entry if no data type has been
472 explicitly defined with the -type attribute.
473 tepam::argument_dialogbox \
475 -existingdirectory {-label "Report directory" -variable ReportDir}
476 Finally, there is a last group of some other special data entry wid‐
478 gets.
479 -color list
481 The color selector is composed by an entry widget together with
482 a button that allows opening a color browser. The data type
483 color is automatically selected for this entry widget type if no
484 data type has been explicitly defined with the -type attribute.
485 tepam::argument_dialogbox \
487 -color {-label "Background color" -variable Color -default red}
488 -font list
490 The font selector is composed by an entry widget together with a
491 button that allows opening a font browser. The data type font is
492 automatically selected for this entry widget type if no data
493 type has been explicitly defined with the -type attribute. The
494 entry widget displays an example text in the format of the
495 selected font.
496 The font browser allows selecting by default the font families
498 provided by the font families Tk command as well as a reasonable
499 set of different font sizes between 6 points and 40 points. Dif‐
500 ferent sets of font families and font sizes can be specified
501 respectively via the -font_families or -font_sizes attributes.
502 If no default font is provided via the -default attribute, the
504 default font of the label widget to display the selected font
505 will be used as default selected font. If the font family of
506 this label widget is not part of the available families the
507 first available family is used as default. If the font size of
508 this label widget is not part of the available sizes the next
509 close available size is selected as default size.
510 tepam::argument_dialogbox \
512 -font {-label "Font" -variable Font \
513 -font_sizes {8 10 12 16} \
514 -default {Arial 20 italic}}
515 ENTRY WIDGET ITEM ATTRIBUTES
517 All the entry widget items are accepting the following attributes:
518 -text string
520 Eventual descriptions and comments specified with the -text
521 attribute are displayed above the entry widget.
522 tepam::argument_dialogbox \
524 -entry {-text "Please enter your name bellow" -variable Name}
525 -label string
527 The label attribute creates left to the entry widget a label
528 using the provided string as label text:
529 tepam::argument_dialogbox \
531 -entry {-label Name -variable Name}
532 -variable string
534 All entry widgets require a specified variable. After accepting
535 the entered information with the OK button, the entry widget
536 data is stored inside the defined variables.
537 tepam::argument_dialogbox \
539 -existingdirectory {-label "Report directory" -variable ReportDir}
540 -default string
542 Eventual default data for the entry widgets can be provided via
543 the -default attribute. The default value is overridden if an
544 argument dialog box with a defined context is called another
545 time. The value acknowledged in a previous call will be used in
546 this case as default value.
547 tepam::argument_dialogbox \
549 -checkbox {-label "Font sytle" -variable FontStyle \
550 -choices {bold italic underline} -default italic}
551 -optional 0|1
553 Data can be specified as optional or mandatory with the
554 -optional attribute that requires either 0 (mandatory) or 1
555 (optional) as attribute data.
556 In case an entry is optional and no data has been entered, e.g.
558 the entry contains an empty character string, the entry will be
559 considered as undefined and the assigned variable will not be
560 defined.
561 tepam::argument_dialogbox \
563 -entry {-label "City" -variable start_city -type string} \
564 -entry {-label "Street" -variable start_street -type string -optional 0} \
565 -entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
566 -type string
568 If the data type is defined with the -type attribute the argu‐
569 ment dialog box will automatically perform a data type check
570 after acknowledging the entered values and before the dialog box
571 is closed. If a type incompatible value is found an error mes‐
572 sage box appears and the user can correct the value.
573 The argument dialog box accepts all types that have been speci‐
575 fied by the TEPAM package and that are also used by tepam::pro‐
576 cedure (see the tepam::procedure reference manual).
577 Some entry widgets like the file and directory widgets, as well
579 as the color and font widgets are specifying automatically the
580 default data type if no type has been specified explicitly with
581 the -type attribute.
582 tepam::argument_dialogbox \
584 -entry {-label "Street number" -variable start_street_nbr -type integer} \
585 -range string
587 Values can be constrained with the -range attribute. The valid
588 range is defined with a list containing the minimum valid value
589 and a maximum valid value.
590 The -range attribute has to be used only for numerical argu‐
592 ments, like integers and doubles.
593 tepam::argument_dialogbox \
595 -entry {-label Month -variable Month -type integer -range {1 12}}
596 -validatecommand string
598 Custom argument value validations can be performed via specific
599 validation commands that are defined with the -validatecommand
600 attribute. The provided validation command can be a complete
601 script in which the pattern %P is placeholder for the argument
602 value that has to be validated.
603 tepam::argument_dialogbox \
605 -entry {-label "Your comment" -variable YourCom \
606 -validatecommand "IllegalWordDetector %P"}
607 While the purpose of this custom argument validation attribute
609 is the validation of a specific argument, there is also a global
610 data validation attribute -validatecommand that allows perform‐
611 ing validation that involves multiple arguments.
612 -validatecommand_error_text string
614 This attribute allows overriding the default error message for a
615 custom argument validation (defined by -validatecommand).
616 Some other attributes are supported by the list and combo boxes as well
618 as by the radio and check buttons.
619 -choices string
621 Choice lists can directly be defined with the -choices
622 attribute. This way to define choice lists is especially adapted
623 for smaller, fixed selection lists.
624 tepam::argument_dialogbox \
626 -listbox {-label "Text styles" -variable Styles \
627 -choices {bold italic underline} -default underline
628 -choicelabels string (only check and radio buttons)
630 If the labels of the check and radio boxes should differ from
631 the option values, they can be defined with the -choicelabels
632 attribute:
633 tepam::argument_dialogbox \
635 -checkbox {-label "Font sytle" -variable FontStyle \
636 -choices {bold italic underline} \
637 -choicelabels {Bold Italic Underline}
638 -choicevariable string
640 Another way to define the choice lists is using the -choicevari‐
641 able attribute. This way to define choice lists is especially
642 adapted for huge and eventually variable selection lists.
643 set TextSizes {8 9 10 12 15 18}
645 tepam::argument_dialogbox \
646 -combobox {-label "Text size" -variable Size -choicevariable TextSizes}
647 -multiple_selection 0|1
649 The list box item (-listbox) allows by default selecting only
650 one list element. By setting the -multiple_selection attribute
651 to 1, multiple elements can be selected.
652 tepam::argument_dialogbox \
654 -listbox {-label "Text styles" -variable Styles \
655 -choices {bold italic underline} -default underline \
656 -multiple_selection 1 -height 3}
657 Some additional attributes are supported by the file and directory
659 selection widgets.
660 -filetypes string
662 The file type attribute is used by the -file and -existingfile
663 items to define the file endings that are searched by the file
664 browser.
665 tepam::argument_dialogbox \
667 -file {-label "Image file" -variable ImageF \
668 -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}}
669 -initialfile string
671 The initial file used by the file browsers of the -file and
672 -existingfile widgets are by default the file defined with the
673 -default attribute, unless a file is specified with the -ini‐
674 tialfile attribute.
675 tepam::argument_dialogbox \
677 -file {-variable ImageF -initialfile "picture.gif"}
678 -activedir string
680 The -activedir attribute will override the default active search
681 directory used by the file browsers of all file and directory
682 entry widgets. The default active search directory is defined by
683 the directory of a specified initial file (-initialfile) if
684 defined, and otherwise by the directory of the default
685 file/directory, specified with the -default attribute.
686 tepam::argument_dialogbox \
688 -file "-variable ImageF -activedir $pwd"
689 Finally, there is a last attribute supported by some widgets:
691 -height string
693 All widgets containing a selection list (-listbox, -dis‐
694 jointlistbox, -font) as well as the multi line -text widget are
695 accepting the -height attribute that defines the number of dis‐
696 played rows of the selection lists.
697 tepam::argument_dialogbox \
699 -listbox {-label "Text size" -variable Size \
700 -choices {8 9 10 12 15 18} -default 12 -height 3}
701 If the no height has been explicitly specified the height of the
703 widget will be dynamically adapted to the argument dialog box
704 size.
705
707 An application specific entry widget can be made available to the argu‐
708 ment dialog box by adding a dedicated procedure to the tepam namespace.
709 This procedure has three arguments; the first one is the widget path,
710 the second one a subcommand and the third argument has various pur‐
711 poses:
712 proc tepam::ad_form(<WidgetName>) {W Command {Par ""}} {
714 upvar Option Option; # if required
715 variable argument_dialogbox; # if required
716 switch $Command {
717 "create" <CreateCommandSequence>
718 "set_choice" <SetChoiceCommandSequence>
719 "set" <SetCommandv>
720 "get" <GetCommandSequence>
721 }
722 }
723 Argument_dialogbox takes care about the -label and -text attributes for
724 all entry widgets. For any data entry widget it creates a frame into
725 which the data entry widget components can be placed. The path to this
726 frame is provided via the W argument.
727 The entry widget procedure has to support 3 mandatory and an optional
729 command that are selected via the argument Command:
730 create The entry widget is called a first time with the command create
732 to build the data entry widget.
733 The frames that are made available by argument_dialogbox for the
735 entry widgets are by default only extendable in the X direction.
736 To make them also extendable in the Y direction, for example for
737 extendable list boxes, the command ad_form(make_expandable) $W
738 has to be executed when an entry widget is built.
739 set_choice
741 The entry widget procedure is only called with the set_choice
742 command if the -choices or -choicevariable has been specified.
743 The command is therefore only relevant for list and combo boxes.
744 The available selection list that is either specified with the
746 -choices or -choicevariable attribute is provided via the Par
747 argument to the entry widget procedure. This list can be used to
748 initialize an available choice list.
749 set If a default value is either defined via the -default attribute
751 or via a preceding call the entry widget procedure is called
752 with the set command. The argument Par contains in this case the
753 value to which the entry widget has to be initialized.
754 get The entry widget procedure command get has to return the current
756 value of the entry widget.
757 Eventually specified entry widget item attributes are available via the
759 Option array variable of the calling procedure. This variable becomes
760 accessible inside the entry widget procedure via the upvar command.
761 There may be a need to store some information in a variable. The array
763 variable argument_dialogbox has to be used for this purpose together
764 with array indexes starting with "$W,", e.g. argument_dialogbox($W,val‐
765 ues).
766 Examples of entry widget procedures are directly provided by the TEPAM
768 package source file that specifies the standard entry widget proce‐
769 dures. The simplest procedure is the one for the basic entry widget:
770 proc tepam::ad_form(entry) {W Command {Par ""}} {
772 switch $Command {
773 "create" {pack [entry \$W.entry] -fill x \
774 -expand yes -pady 4 -side left}
775 "set" {\$W.entry insert 0 $Par}
776 "get" {return [\$W.entry get]}
777 }
778 }
779 It is also possible to relay on an existing entry widget procedure to
780 derive a new, more specific one. The radiobox widget is used for exam‐
781 ple, to create a new entry widget that allows selecting either left,
782 center or right. The original radiobox widget is called with the
783 set_choice command immediately after the create command, to define the
784 fixed list of selection options.
785 proc tepam::ad_form(rcl) {W Command {Par ""}} {
787 set Res [ad_form(radiobox) $W $Command $Par]
788 if {$Command=="create"} {
789 ad_form(radiobox) $W set_choice {left center right}
790 }
791 return $Res
792 }
793 Please consult the TEPAM package source file to find additional and
794 more complex examples of entry widget procedures.
795
797 The argument_dialogbox is using two variables inside the namespace
798 ::tepam:
799 argument_dialogbox
801 Application specific entry widget procedures can use this array
802 variable to store their own data, using as index the widget path
803 provided to the procedure, e.g. argument_dialog‐
804 box($W,<sub_index>).
805 last_parameters
807 This array variable is only used by an argument dialog box if
808 its context has been specified via the -context attribute. The
809 argument dialog box position and size as well as its entered
810 data are stored inside this variable if the data are acknowl‐
811 edged and the form is closed. This allows the form to restore
812 its previous state once it is called another time.
813 To reuse the saved parameters not just in the actual application
815 session but also in another one, it is sufficient to store the
816 last_parameter array variable contents in a configuration file
817 which is loaded the next time an application is launched.
818
820 tepam(n), tepam::procedure(n)
821
823 data entry form, parameter entry form
824
826 Argument entry form, mega widget
827
829 Copyright (c) 2009-2013, Andreas Drollinger
830tcllib 0.5.0 tepam::argument_dialogbox(n)