1tepam::argument_diTacllo'gsboExn(hna)nced Procedure and ArgumteenptamM:a:naarggeurment_dialogbox(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual
9

SYNOPSIS

11       package require Tcl  8.3
12
13       package require Tk  8.3
14
15       package require tepam  ?0.5?
16
17       tepam::argument_dialogbox    item_name    item_attributes    ?item_name
18       item_attributes? ?...?
19
20       tepam::argument_dialogbox   {item_name    item_attributes    ?item_name
21       item_attributes? ?...?}
22
23______________________________________________________________________________
24

DESCRIPTION

ARGUMENT DIALOGBOX CALL

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
32       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
41              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
46              A  small  example  illustrates how the argument_dialogbox can be
47              employed:
48
49              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
65              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
74       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
84              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
90       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
94              namespace import tepam::*
95
96              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
106   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
111              tepam::argument_dialogbox \
112                 -<argument_name> string \
113                 ...
114       The following items are classified into this group:
115
116       -title string
117              The  dialog  box  window title which is by default Dialog can be
118              changed with the -title item:
119
120              tepam::argument_dialogbox \
121                 -title "System configuration" \
122                 ...
123
124       -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
128              tepam::argument_dialogbox \
129                 -window .dialog \
130                 ...
131
132       -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
138              tepam::argument_dialogbox \
139                 -parent .my_appl \
140                 ...
141
142       -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
149              tepam::argument_dialogbox \
150                 -context destination_definitions \
151                 ...
152
153   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
159       The  items  of  this  classification group require as item attributes a
160       definition list, which contains itself attribute name and value pairs:
161
162              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
172       -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
178              -label string
179                     An  optional frame label can be specified with the -label
180                     statement.
181
182              Example:
183
184              tepam::argument_dialogbox \
185                 ...
186                 -frame {-label "Destination address"}
187                 ...
188
189              To close an open frame without opening a new one, an empty  list
190              has to be provided to the -frame statement.
191
192              tepam::argument_dialogbox \
193                 ...
194                 -frame {}
195                 ...
196
197       -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
202              tepam::argument_dialogbox \
203                 ...
204                 -sep {}
205                 ...
206
207       -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
214              tepam::argument_dialogbox \
215                 ...
216                 -comment {-text "Specify bellow the destination address"}
217                 ...
218
219       -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
226              tepam::argument_dialogbox \
227                 ...
228                 -yscroll auto
229                 ...
230
231   GLOBAL CUSTOM DATA VALIDATION
232       This  item group allows specifying global custom checks to validate the
233       entered data.
234
235       -validatecommand script
236              Custom data checks can be performed via validation commands that
237              are defined with the -validatecommand item. Example:
238
239              tepam::argument_dialogbox \
240                 -entry {-label "Your comment" -variable YourCom} \
241                 -validatecommand {IllegalWordDetector $YourCom}
242
243              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
250              The attribute -validatecommand can be repeated to declare multi‐
251              ple custom checks.
252
253       -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
259       -validatecommand2 script
260
261       -validatecommand2_error_text string
262              These items are mainly for TEPAM internal usage.
263
264              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
269   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
274              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
287       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
291       -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
296              tepam::argument_dialogbox \
297                 -entry {-label Name -variable Entry}
298
299       -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
303              tepam::argument_dialogbox \
304                 -text {-label Name -variable Text -height 5}
305
306       -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
312              tepam::argument_dialogbox \
313                 -checkbox {-label "Font sytle" -variable FontStyle \
314                             -choices {bold italic underline} -default italic}
315
316              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
320              tepam::argument_dialogbox \
321                 -checkbox {-label "Font sytle" -variable FontStyle \
322                            -choices {bold italic underline} \
323                            -choicelabels {Bold Italic Underline} \
324                            -default italic}
325
326              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
331       -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
337              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
342              tepam::argument_dialogbox \
343                 -radiobox {-label "Text adjustment" -variable Adjustment \
344                            -choices {left center right} -default left}
345
346              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
350              tepam::argument_dialogbox \
351                 -radiobox {-label "Text adjustment" -variable Adjustment \
352                            -choices {left center right} \
353                            -choicelabels {Left Center Right} -default left}
354
355       -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
362              tepam::argument_dialogbox \
363                 -checkbutton {-label Capitalize -variable Capitalize -default 1}
364
365       Several types of list and combo boxes are available to handle selection
366       lists.
367
368       -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
376              tepam::argument_dialogbox \
377                 -combobox {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}
378
379              And  here is an example of using a variable to define the selec‐
380              tion list:
381
382              set TextSizes {8 9 10 12 15 18}
383              tepam::argument_dialogbox \
384                 -combobox {-label "Text size" -variable Size -choicevariable TextSizes -default 12}
385
386       -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
395              set set AvailableSizes
396              for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}
397
398              tepam::argument_dialogbox \
399                 -listbox {-label "Distance" -variable Distance \
400                           -choicevariable AvailableSizes -default 6 -height 5}
401
402              Here is a multi-element selection example. Please note that also
403              the default selection can contain multiple elements:
404
405              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
412       -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
418              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
423              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
429       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
434       -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
440              tepam::argument_dialogbox \
441                 -file {-label "Image file" -variable ImageF \
442                        -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
443                        -initialfile "picture.gif"}
444
445       -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
452              tepam::argument_dialogbox \
453                 -existingfile {-label "Image file" -variable ImageF \
454                                -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
455                                -initialfile "picture.gif"}
456
457       -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
464              tepam::argument_dialogbox \
465                 -directory {-label "Report directory" -variable ReportDir}
466
467       -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
474              tepam::argument_dialogbox \
475                 -existingdirectory {-label "Report directory" -variable ReportDir}
476
477       Finally,  there  is  a last group of some other special data entry wid‐
478       gets.
479
480       -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
486              tepam::argument_dialogbox \
487                 -color {-label "Background color" -variable Color -default red}
488
489       -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
497              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
503              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
511              tepam::argument_dialogbox \
512                 -font {-label "Font" -variable Font \
513                        -font_sizes {8 10 12 16} \
514                        -default {Arial 20 italic}}
515
516   ENTRY WIDGET ITEM ATTRIBUTES
517       All the entry widget items are accepting the following attributes:
518
519       -text string
520              Eventual descriptions and  comments  specified  with  the  -text
521              attribute are displayed above the entry widget.
522
523              tepam::argument_dialogbox \
524                 -entry {-text "Please enter your name bellow" -variable Name}
525
526       -label string
527              The  label  attribute  creates  left to the entry widget a label
528              using the provided string as label text:
529
530              tepam::argument_dialogbox \
531                 -entry {-label Name -variable Name}
532
533       -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
538              tepam::argument_dialogbox \
539                 -existingdirectory {-label "Report directory" -variable ReportDir}
540
541       -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
548              tepam::argument_dialogbox \
549                 -checkbox {-label "Font sytle" -variable FontStyle \
550                             -choices {bold italic underline} -default italic}
551
552       -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
557              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
562              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
567       -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
574              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
578              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
583              tepam::argument_dialogbox \
584                 -entry {-label "Street number" -variable start_street_nbr -type integer} \
585
586       -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
591              The -range attribute has to be used  only  for  numerical  argu‐
592              ments, like integers and doubles.
593
594              tepam::argument_dialogbox \
595                 -entry {-label Month -variable Month -type integer -range {1 12}}
596
597       -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
604              tepam::argument_dialogbox \
605                 -entry {-label "Your comment" -variable YourCom \
606                         -validatecommand "IllegalWordDetector %P"}
607
608              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
613       -validatecommand_error_text string
614              This attribute allows overriding the default error message for a
615              custom argument validation (defined by -validatecommand).
616
617       Some other attributes are supported by the list and combo boxes as well
618       as by the radio and check buttons.
619
620       -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
625              tepam::argument_dialogbox \
626                 -listbox {-label "Text styles" -variable Styles \
627                           -choices {bold italic underline} -default underline
628
629       -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
634              tepam::argument_dialogbox \
635                 -checkbox {-label "Font sytle" -variable FontStyle \
636                            -choices {bold italic underline} \
637                            -choicelabels {Bold Italic Underline}
638
639       -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
644              set TextSizes {8 9 10 12 15 18}
645              tepam::argument_dialogbox \
646                 -combobox {-label "Text size" -variable Size -choicevariable TextSizes}
647
648       -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
653              tepam::argument_dialogbox \
654                 -listbox {-label "Text styles" -variable Styles \
655                           -choices {bold italic underline} -default underline \
656                           -multiple_selection 1 -height 3}
657
658       Some additional attributes are supported  by  the  file  and  directory
659       selection widgets.
660
661       -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
666              tepam::argument_dialogbox \
667                 -file {-label "Image file" -variable ImageF \
668                        -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}}
669
670       -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
676              tepam::argument_dialogbox \
677                 -file {-variable ImageF -initialfile "picture.gif"}
678
679       -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
687              tepam::argument_dialogbox \
688                 -file "-variable ImageF -activedir $pwd"
689
690       Finally, there is a last attribute supported by some widgets:
691
692       -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
698              tepam::argument_dialogbox \
699                 -listbox {-label "Text size" -variable Size \
700                           -choices {8 9 10 12 15 18} -default 12 -height 3}
701
702              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

APPLICATION SPECIFIC ENTRY WIDGETS

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
713              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
728       The  entry  widget procedure has to support 3 mandatory and an optional
729       command that are selected via the argument Command:
730
731       create The entry widget is called a first time with the command  create
732              to build the data entry widget.
733
734              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
740       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
745              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
750       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
755       get    The entry widget procedure command get has to return the current
756              value of the entry widget.
757
758       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
762       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
767       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
771              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
786              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

VARIABLES

797       The  argument_dialogbox  is  using  two  variables inside the namespace
798       ::tepam:
799
800       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
806       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
814              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

SEE ALSO

820       tepam(n), tepam::procedure(n)
821

KEYWORDS

823       data entry form, parameter entry form
824

CATEGORY

826       Argument entry form, mega widget
827
829       Copyright (c) 2009-2013, Andreas Drollinger
830
831
832
833
834tcllib                               0.5.0        tepam::argument_dialogbox(n)
Impressum