Tcl Library Source Code

Documentation
Login
Core Home Blog Docs Downloads Tickets Timeline Branches Tags Wiki

[ 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.3
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 \\
   __\-<argument\_name>__ *string* \\
   \.\.\.

The following items are classified into this group:

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 \\
   \.\.\.
   __\-<argument\_name>__ \{ *
      ?\-<attribute\_name> <attribute\_value>?
      ?\-<attribute\_name> <attribute\_value>?
      ?\.\.\.?*
   \}
   \.\.\.

The following items are classified into this group:

Global Custom Data Validation

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

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 \\
   \.\.\.
   __\-<argument\_name>__ \{ *
      ?\-<attribute\_name> <attribute\_value>?
      ?\-<attribute\_name> <attribute\_value>?
      ?\.\.\.?*
   \}
   \.\.\.

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):

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

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.

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

Entry Widget Item Attributes

All the entry widget items are accepting the following attributes:

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

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

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

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\(<WidgetName>\) \{W Command \{Par ""\}\} \{
   *upvar Option Option; \# if required*
   *variable argument\_dialogbox; \# if required*
   switch $Command \{
      "create" <CreateCommandSequence>
      "set\_choice" <SetChoiceCommandSequence>
      "set" <SetCommandv>
      "get" <GetCommandSequence>
   \}
\}

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

This page was generated in about 0.103s by Fossil 2.27 [a6d506ecc4] 2025-07-09 13:52:53