Tcl Library Source Code

Documentation
Login


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

tepam::argument_dialogbox - TEPAM argument_dialogbox, reference manual

Table Of Contents

SYNOPSIS

package require Tcl 8.5 9
package require Tk 8.3
package require tepam ?0.5?

tepam::argument_dialogbox item_name item_attributes ?item_name item_attributes? ?...?
tepam::argument_dialogbox {item_name item_attributes ?item_name item_attributes? ?...?}

DESCRIPTION

ARGUMENT DIALOGBOX CALL

The TEPAM argument_dialogbox is a flexible and easily usable data entry form generator that is available if Tk has been loaded. Each data entry element of a form is defined via a data entry item that can be provided to argument_dialogbox in two formats:

The commands argument_dialogbox as well as procedure are exported from the namespace tepam. To use these commands without the tepam:: namespace prefix, it is sufficient to import them into the main namespace:

namespace import tepam::*

set DialogResult [argument_dialogbox \
   -title "Itinerary selection"
   ...

The following subsections explain the different argument item types that are accepted by the argument_dialogbox, classified into three groups. The first data entry item definition format will be used in the remaining document, knowing that this format can always be transformed into the second format by putting all arguments into a single list that is then provided to argument_dialogbox.

Context Definition Items

The first item group allows specifying some context aspects of an argument dialog box. These items are taking a simple character string as item attribute:

tepam::argument_dialogbox \
   - string \
   ...

The following items are classified into this group:

tepam::argument_dialogbox \
   -title "System configuration" \
   ...

tepam::argument_dialogbox \
   -window .dialog \
   ...

tepam::argument_dialogbox \
   -parent .my_appl \
   ...

tepam::argument_dialogbox \
   -context destination_definitions \
   ...

Formatting and Display Options

Especially for big, complex forms it becomes important that the different data entry widgets are graphically well organized and commented to provide an immediate and clear overview to the user. A couple of items allow structuring and commenting the dialog boxes.

The items of this classification group require as item attributes a definition list, which contains itself attribute name and value pairs:

tepam::argument_dialogbox \
   ...
   - {
      ?- ?
      ?- ?
      ?...?

   }
   ...

The following items are classified into this group:

tepam::argument_dialogbox \
   ...
   -frame {-label "Destination address"}
   ...

To close an open frame without opening a new one, an empty list has to be
provided to the *\-frame* statement\.

tepam::argument_dialogbox \
   ...
   -frame {}
   ...

tepam::argument_dialogbox \
   ...
   -sep {}
   ...

tepam::argument_dialogbox \
   ...
   -comment {-text "Specify bellow the destination address"}
   ...

tepam::argument_dialogbox \
   ...
   -yscroll auto
   ...

Global Custom Data Validation

This item group allows specifying global custom checks to validate the entered data.

tepam::argument_dialogbox \
   -entry {-label "Your comment" -variable YourCom} \
   -validatecommand {IllegalWordDetector $YourCom}

The validation command is executed in the context of the calling procedure,
once all the basic data checks have been performed and data variables are
assigned\. All data is accessed via the data variables\. Note that there is
also an entry widget specific attribute *\-validatecommand* that allows
declaring custom checks for specific data entries\.

The attribute *\-validatecommand* can be repeated to declare multiple
custom checks\.

Data Entry Widget Items

Data entry widgets are created with the widget items. These items require as item attributes a definition list, which contains itself attribute name and value pairs:

tepam::argument_dialogbox \
   ...
   - {
      ?- ?
      ?- ?
      ?...?

   }
   ...

The attribute list can contain various attributes to describe and comment an entry widget and to constrain its entered value. All entry widgets are accepting a common set of attributes that are described in the section Entry Widget Item Attributes.

TEPAM defines a rich set of entry widgets. If necessary, this set can be extended with additional application specific entry widgets (see APPLICATION SPECIFIC ENTRY WIDGETS):

tepam::argument_dialogbox \
   -entry {-label Name -variable Entry}

tepam::argument_dialogbox \
   -text {-label Name -variable Text -height 5}

tepam::argument_dialogbox \
   -checkbox {-label "Font sytle" -variable FontStyle \
               -choices {bold italic underline} -default italic}

If the labels of the check boxes should differ from the option values, their
labels can be defined with the *\-choicelabels* attribute:

tepam::argument_dialogbox \
   -checkbox {-label "Font sytle" -variable FontStyle \
              -choices {bold italic underline} \
              -choicelabels {Bold Italic Underline} \
              -default italic}

In contrast to a radio box group, a check box group allows selecting
simultaneously several choice options\. The selection is stored for this
reason inside the defined variable in form of a list, even if only one
choice option has been selected\.

tepam::argument_dialogbox \
   -radiobox {-label "Text adjustment" -variable Adjustment \
              -choices {left center right} -default left}

If the labels of the radio boxes should differ from the option values, their
labels can be defined with the *\-choicelabels* attribute:

tepam::argument_dialogbox \
   -radiobox {-label "Text adjustment" -variable Adjustment \
              -choices {left center right} \
              -choicelabels {Left Center Right} -default left}

tepam::argument_dialogbox \
   -checkbutton {-label Capitalize -variable Capitalize -default 1}

Several types of list and combo boxes are available to handle selection lists.

tepam::argument_dialogbox \
   -combobox {-label "Text size" -variable Size -choices {8 9 10 12 15 18} -default 12}

And here is an example of using a variable to define the selection list:

set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
   -combobox {-label "Text size" -variable Size -choicevariable TextSizes -default 12}

set set AvailableSizes
for {set k 0} {$k<16} {incr k} {lappend AvailableSizes [expr 1<<$k]}

tepam::argument_dialogbox \
   -listbox {-label "Distance" -variable Distance \
             -choicevariable AvailableSizes -default 6 -height 5}

Here is a multi\-element selection example\. Please note that also the default
selection can contain multiple elements:

tepam::argument_dialogbox \
   -listbox {-label "Text styles" -variable Styles \
             -choices {bold italic underline overstrike} \
             -choicelabels {Bold Italic Underline Overstrike} \
             -default {bold underline} -multiple_selection 1 \
             -height 3}

tepam::argument_dialogbox \
   -disjointlistbox {-label "Preferred scripting languages" -variable Languages \
             -comment "Please select your preferred languages in the order" \
             -choices {JavaScript Lisp Lua Octave PHP Perl Python Ruby Scheme Tcl} \
             -default {Tcl Perl Python}}

The file and directory selectors are building a next group of data entry widgets. A paragraph of section Entry Widget Item Attributes explains the widget specific attributes that allow specifying the targeted file types, active directory etc.

tepam::argument_dialogbox \
   -file {-label "Image file" -variable ImageF \
          -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
          -initialfile "picture.gif"}

tepam::argument_dialogbox \
   -existingfile {-label "Image file" -variable ImageF \
                  -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}} \
                  -initialfile "picture.gif"}

tepam::argument_dialogbox \
   -directory {-label "Report directory" -variable ReportDir}

tepam::argument_dialogbox \
   -existingdirectory {-label "Report directory" -variable ReportDir}

Finally, there is a last group of some other special data entry widgets.

tepam::argument_dialogbox \
   -color {-label "Background color" -variable Color -default red}

tepam::argument_dialogbox \
   -font {-label "Font" -variable Font \
          -font_sizes {8 10 12 16} \
          -default {Arial 20 italic}}

Entry Widget Item Attributes

All the entry widget items are accepting the following attributes:

tepam::argument_dialogbox \
   -entry {-text "Please enter your name bellow" -variable Name}

tepam::argument_dialogbox \
   -entry {-label Name -variable Name}

tepam::argument_dialogbox \
   -existingdirectory {-label "Report directory" -variable ReportDir}

tepam::argument_dialogbox \
   -checkbox {-label "Font sytle" -variable FontStyle \
               -choices {bold italic underline} -default italic}

tepam::argument_dialogbox \
   -entry {-label "City" -variable start_city -type string} \
   -entry {-label "Street" -variable start_street -type string -optional 0} \
   -entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \

tepam::argument_dialogbox \
   -entry {-label "Street number" -variable start_street_nbr -type integer} \

tepam::argument_dialogbox \
   -entry {-label Month -variable Month -type integer -range {1 12}}

tepam::argument_dialogbox \
   -entry {-label "Your comment" -variable YourCom \
           -validatecommand "IllegalWordDetector %P"}

While the purpose of this custom argument validation attribute is the
validation of a specific argument, there is also a global data validation
attribute *\-validatecommand* that allows performing validation that
involves multiple arguments\.

Some other attributes are supported by the list and combo boxes as well as by the radio and check buttons.

tepam::argument_dialogbox \
   -listbox {-label "Text styles" -variable Styles \
             -choices {bold italic underline} -default underline

tepam::argument_dialogbox \
   -checkbox {-label "Font sytle" -variable FontStyle \
              -choices {bold italic underline} \
              -choicelabels {Bold Italic Underline}

set TextSizes {8 9 10 12 15 18}
tepam::argument_dialogbox \
   -combobox {-label "Text size" -variable Size -choicevariable TextSizes}

tepam::argument_dialogbox \
   -listbox {-label "Text styles" -variable Styles \
             -choices {bold italic underline} -default underline \
             -multiple_selection 1 -height 3}

Some additional attributes are supported by the file and directory selection widgets.

tepam::argument_dialogbox \
   -file {-label "Image file" -variable ImageF \
          -filetypes {{"GIF" {*.gif}} {"JPG" {*.jpg}}}}

tepam::argument_dialogbox \
   -file {-variable ImageF -initialfile "picture.gif"}

tepam::argument_dialogbox \
   -file "-variable ImageF -activedir $pwd"

Finally, there is a last attribute supported by some widgets:

tepam::argument_dialogbox \
   -listbox {-label "Text size" -variable Size \
             -choices {8 9 10 12 15 18} -default 12 -height 3}

If the no height has been explicitly specified the height of the widget will
be dynamically adapted to the argument dialog box size\.

APPLICATION SPECIFIC ENTRY WIDGETS

An application specific entry widget can be made available to the argument dialog box by adding a dedicated procedure to the tepam namespace. This procedure has three arguments; the first one is the widget path, the second one a subcommand and the third argument has various purposes:

proc tepam::ad_form() {W Command {Par ""}} {
   upvar Option Option; # if required
   variable argument_dialogbox; # if required
   switch $Command {
      "create"
      "set_choice"
      "set"
      "get"
   }
}

Argument_dialogbox takes care about the -label and -text attributes for all entry widgets. For any data entry widget it creates a frame into which the data entry widget components can be placed. The path to this frame is provided via the W argument.

The entry widget procedure has to support 3 mandatory and an optional command that are selected via the argument Command:

Eventually specified entry widget item attributes are available via the Option array variable of the calling procedure. This variable becomes accessible inside the entry widget procedure via the upvar command.

There may be a need to store some information in a variable. The array variable argument_dialogbox has to be used for this purpose together with array indexes starting with "$W,", e.g. argument_dialogbox($W,values).

Examples of entry widget procedures are directly provided by the TEPAM package source file that specifies the standard entry widget procedures. The simplest procedure is the one for the basic entry widget:

proc tepam::ad_form(entry) {W Command {Par ""}} {
   switch $Command {
      "create" {pack [entry \$W.entry] -fill x \
                        -expand yes -pady 4 -side left}
      "set" {\$W.entry insert 0 $Par}
      "get" {return [\$W.entry get]}
   }
}

It is also possible to relay on an existing entry widget procedure to derive a new, more specific one. The radiobox widget is used for example, to create a new entry widget that allows selecting either left, center or right. The original radiobox widget is called with the set_choice command immediately after the create command, to define the fixed list of selection options.

proc tepam::ad_form(rcl) {W Command {Par ""}} {
   set Res [ad_form(radiobox) $W $Command $Par]
   if {$Command=="create"} {
      ad_form(radiobox) $W set_choice {left center right}
   }
   return $Res
}

Please consult the TEPAM package source file to find additional and more complex examples of entry widget procedures.

VARIABLES

The argument_dialogbox is using two variables inside the namespace ::tepam:

SEE ALSO

tepam(n), tepam::procedure(n)

KEYWORDS

data entry form, parameter entry form

CATEGORY

Argument entry form, mega widget

COPYRIGHT

Copyright © 2009-2013, Andreas Drollinger