tepa...ogbox(n)

📦

version 2.0 · 2 versions

2.0 · fedora 43, fedora 44, nixos 26.05, nixpkgs unstable (latest)
1.21 · alpine 3.24, epel 9, opensuse-leap 16.0

, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

💖 tepa...ogbox(n) — Tcl's Enhanced Procedure and Argument Manager 💖

okay bestie, welcome to tepa...ogbox(n), aka the manual page for Tcl's Enhanced Procedure and Argument Manager. we're doing this in parts, this is part 1, and it is so much. grab a snack 🍓

✨ NAME ✨

tepam::argument_dialogbox — TEPAM argument_dialogbox, reference manual. that's it, that's the name, and honestly? iconic.

✨ 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? ?...?}

like. look at her. two whole ways to call her and she eats both 💅

✨ DESCRIPTION ✨

🌸 ARGUMENT DIALOGBOX CALL 🌸

okay so. the TEPAM argument_dialogbox is a flexible and easily usable data entry form generator, and here's the tea: she's only available if Tk has been loaded. no Tk, no form, periodt.

every single data entry element of a form is defined via a data entry item, and you can hand those items to argument_dialogbox in two formats:

tepam::argument_dialogbox item_name item_attributes ?item_name item_attributes? ?...? — the first format, where each data entry item is a pair of two arguments. the first one is the item name, which defines which entry widget has to be used in the form. the second argument, called the item attributes, specifies the variable that's attributed to the data entry element plus any eventual formatting and context info. lowkey the whole personality of the item lives in there.

argument_dialogbox returns ok if the entered data have been acknowledged (via the OK button) and validated by a data checker. if the entered data have been rejected (via the Cancel button), she returns cancel. simple as.

a small example illustrates how the argument_dialogbox can be employed:

set DialogResult [tepam::argument_dialogbox \
   -title "Itinerary selection" \
   -file {-label "Itinerary report" -variable report_file} \
   -frame {-label "Itinerary start"} \
      -comment {-text "Specify your itinerary start location"} \
      -entry {-label "City" -variable start_city -type string} \
      -entry {-label "Street" -variable start_street -type string -optional 1} \
      -entry {-label "Street number" -variable start_street_nbr -type integer -optional 1} \
   -frame {-label "Itinerary destination"} \
      -comment {-text "Specify your itinerary destination"} \
      -entry {-label "City" -variable dest_city -type string} \
      -entry {-label "Street" -variable dest_street -type string -optional 1} \
      -entry {-label "Street number" -variable dest_street_nbr -type integer -optional 1} \
   -frame {} \
   -checkbutton {-label "Don't use highways" -variable no_highway}]

so this example opens a dialog box that has the title Itinerary selection. a first entry widget in this box allows selecting a report file. then it follows two frames that define respectively an itinerary start and end location. each of these locations — described with a comment — has three entry widgets to specify respectively the city, the street and the street number. bellow the second frame there's a check button that allows specifying if eventual highways should be ignored. it's giving road trip planning, no cap. 🦋

tepam::argument_dialogbox {item_name item_attributes ?item_name item_attributes? ?...?} — okay so sometimes it's simpler to provide all the data entry item definitions in the form of a single list to argument_dialogbox, instead of as individual arguments. the second format supported by argument_dialogbox corresponds exactly to the first one, except that all item definitions are packed into a single list that is provided to argument_dialogbox. so the previous example can therefore also be written in the following way:

set DialogResult [tepam::argument_dialogbox {
   -title "Itinerary selection"
   -file {-label "Itinerary report" -variable report_file}
   ...
   -checkbutton {-label "Don't use highways" -variable no_highway} }]

fr fr, same energy, different wrapper 🎀

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"
   ...

bestie note: 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. so don't stress about picking a favourite. 🫶

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

-title string — the dialog box window title, which is by default Dialog, can be changed with the -title item:

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

-window string — the argument dialog box uses by default .dialog as dialog top level window. this path can be changed with the -window item:

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

-parent string — by defining a parent window, the argument dialog box will be displayed beside this one. without an explicit parent window definition, the top-level window will be considered as parent window.

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

-context string — if a context is defined, the dialog box state — e.g. the entered data as well as the window size and position — is restored the next time the argument dialog box is called. assigning a context allows saving the dialog box state in its context to distinguish between different usages of the argument dialog box. memory? she has it. 💅

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, so the user gets an immediate and clear overview. a couple of items allow structuring and commenting the dialog boxes. aesthetic matters, bestie.

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:

-frame list — the -frame item allows packing all following entry widgets into a labeled frame, until a next frame item is defined or until the last entry widget has been defined. it recognizes the following attributes inside the item attribute list:
- -label string — an optional frame label can be specified with the -label statement.

example:

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 {}
   ...

-sep [const {{}}] — entry widgets can be separated with the -sep statement, which doesn't require additional definitions. the related definition list has to exist, but its content is ignored. (yes, it's a vibe-only parameter. she's decorative. 🌸)

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

-comment string — comments and descriptions can be added with the -text attribute of the -comment item. please note that each entry widget itself can also contain a -text attribute for comments and descriptions. but the -comment item allows for example adding a description between two frames.

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

-yscroll 0|1|auto — this attribute allows controlling an eventual vertical scrollbar. setting it to 0 will permanently disable the scrollbar, setting it to 1 will enable it. by default it is set to auto. the scrollbar is enabled in this mode only if the vertical data entry form size exceeds 66% of the screen height. 66%, very specific, we respect the precision.

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

💜 GLOBAL CUSTOM DATA VALIDATION 💜

this item group allows specifying global custom checks to validate the entered data. she's the bouncer at the door of your form. 🚪

-validatecommand script — custom data checks can be performed via validation commands that are defined with the -validatecommand item. example:

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. stack 'em up bestie ✨

-validatecommand_error_text string — this item allows overriding the default error message for a global custom argument validation (defined by -validatecommand). also this attribute can be repeated in case multiple checks are declared.
-validatecommand2 script
-validatecommand2_error_text string

these items are mainly for TEPAM internal usage.

these items correspond respectively to -validatecommand and -validatecommand_error_text. however, the data validation is not performed in the next upper stack level, but two stack levels higher. yes, really. it's giving "we go up two floors, not one" 💀

part 1 done, bestie — more parts are coming, so don't go anywhere 🦋

okay bestie, so data entry widgets? they're created with the widget items. 🎀 and here's the vibe: these items require, as their item attributes, a definition list — and that definition list is itself made of attribute name and value pairs, like this:

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

`-entry` list

The -entry item generates the simplest but most universal data entry widget. It allows entering any kind of data in form of single line strings. literally the GOAT of "just let me type something" 💅

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

`-text` list

The -text item generates a multi line text entry widget. The widget height can be selected with the -height attribute. 📝

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

`-checkbox` list

A group of check boxes is created with the -checkbox item. The number of check boxes and their option values are specified with a list assigned to the -choices attribute or via a variable declared with the -choicevariable attribute:

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. yes bestie, even ONE pick comes back as a list — that's just how she is 🫶

`-radiobox` list

A group of radio boxes is created with the -radiobox item. The number of radio boxes and their option values are specified with a list assigned to the -choices attribute or via a variable declared with the -choicevariable attribute.

In contrast to a check box group, a radio box group allows selecting simultaneously only one choice option. The selected option value is stored directly, and not in form of a list, inside the defined variable. 👑

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}

`-checkbutton` list

The -checkbutton entry widget allows activating or deactivating a single choice option. The result written into the variable will either be 0 if the check button was not activated or 1 if it was activated. An eventually provided default value has also to be either 0 or 1. 🎀

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

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

`-combobox` list

The combobox is a combination of a normal entry widget together with a drop-down list box. The combobox allows selecting from this drop-down list box a single element. The list of the available elements can be provided either as a list to the -choices attribute, or via a variable that is specified with the -choicevariable attribute.

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}

`-listbox` list

In contrast to the combo box, the list box is always displayed by the listbox entry widget. Only one element is selectable unless the -multiple_selection attribute is set. The list box height can be selected with the -height attribute. If the height is not explicitly defined, the list box height is automatically adapted to the argument dialog box size. The first example uses a variable to define the available choices:

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}

`-disjointlistbox` list

A disjoint list box has to be used instead of a normal list box if the selection order is important. The disjoint list box entry widget has in fact two list boxes, one to select elements and one to display the selected elements in the chosen order. two boxes, one destiny ✨

Disjoint listboxes allow always selecting multiple elements. With the exception of the -multiple_selection attribute, disjointed list boxes are accepting the same attributes as the normal listbox, e.g. -height, -choices, -choicevariable, -default.

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. 📁

`-file` list

The item -file creates a group composed by an entry widget together with a button that allows opening a file browser. The data type file is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

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

`-existingfile` list

The item -existingfile creates a group composed by an entry widget together with a button that allows opening a browser to select an existing file. The data type existingfile is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

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

`-directory` list

The item -directory creates a group composed by an entry widget together with a button that allows opening a directory browser. The data type directory is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

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

`-existingdirectory` list

The item -existingdirectory creates a group composed by an entry widget together with a button that allows opening a browser to select an existing directory. The data type existingdirectory is automatically selected for this entry if no data type has been explicitly defined with the -type attribute.

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

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

`-color` list

The color selector is composed by an entry widget together with a button that allows opening a color browser. The data type color is automatically selected for this entry widget type if no data type has been explicitly defined with the -type attribute. 🌈

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

`-font` list

The font selector is composed by an entry widget together with a button that allows opening a font browser. The data type font is automatically selected for this entry widget type if no data type has been explicitly defined with the -type attribute. The entry widget displays an example text in the format of the selected font. 💅

The font browser allows selecting by default the font families provided by the font families Tk command as well as a reasonable set of different font sizes between 6 points and 40 points. Different sets of font families and font sizes can be specified respectively via the -font_families or -font_sizes attributes.

If no default font is provided via the -default attribute, then the default font of the label widget that's displaying the selected font becomes the default selected font, periodt. And if that label widget's font family isn't one of the available families? The first available family gets picked as default. If its font size isn't in the available sizes, the next closest available size gets selected as the default size. 💅

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

Okay bestie, every single entry widget item out there accepts all of these attributes:

-text string — any eventual descriptions and comments you drop in with the -text attribute get displayed above the entry widget. 👑

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

-label string — the label attribute creates a label to the left of the entry widget, using the string you hand it as the label text:

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

-variable string — every entry widget requires a specified variable, no skipping. Once you hit the OK button and accept the info you entered, the entry widget data gets stored inside the variables you defined. ✨

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

-default string — any eventual default data for the entry widgets goes in through the -default attribute. Heads up though: the default value gets overridden if an argument dialog box with a defined context gets called another time — in that case, the value you acknowledged in a previous call becomes the default value. 🦋

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

-optional 0|1 — you can mark data as optional or mandatory with the -optional attribute, which wants either 0 (mandatory) or 1 (optional) as its attribute data.

So if an entry is optional and no data got entered — like, the entry holds an empty character string — then that entry is considered undefined and the assigned variable will not be defined. 🙈

tepa::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} \

-type string — if you define the data type with the -type attribute, the argument dialog box automatically runs a data type check after you acknowledge the entered values and before the dialog box closes. Find a type-incompatible value and an error message box pops up so the user can fix it. 🔥

The argument dialog box accepts all the types that have been specified by the TEPAM package, the same ones that tepam::procedure uses (go peek at the tepam::procedure reference manual, iykyk).

Some entry widgets — like the file and directory widgets, plus the color and font widgets — automatically specify the default data type if no type was explicitly given with the -type attribute. Iconic behaviour, honestly.

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

-range string — values can be constrained with the -range attribute. The valid range is defined with a list containing the minimum valid value and a maximum valid value.

Use -range only for numerical arguments, like integers and doubles. Don't be out here ranging your strings. 💀

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

-validatecommand string — custom argument value validations can be performed via specific validation commands, defined with the -validatecommand attribute. The validation command you provide can be a complete script, and inside it the pattern %P is a placeholder for the argument value that has to be validated. 🫶

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

Now, while the whole purpose of this custom argument validation attribute is validating a specific argument, there's also a global data validation attribute -validatecommand that lets you perform validation involving multiple arguments. Two different vibes, both valid.

-validatecommand_error_text string — this attribute lets you override the default error message for a custom argument validation (the one defined by -validatecommand). ✨

Some other attributes are supported by the list and combo boxes, and also by the radio and check buttons. Let's go:

-choices string — choice lists can be defined directly with the -choices attribute. This way of defining choice lists is especially adapted for smaller, fixed selection lists. 🌸

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

-choicelabels string (only check and radio buttons) — if the labels of the check and radio boxes should differ from the option values, you define them with the -choicelabels attribute:

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

-choicevariable string — another way to define choice lists is using the -choicevariable attribute. This way is especially adapted for huge and eventually variable selection lists. The way that this scales… we love to see it. 💜

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

-multiple_selection 0|1 — the list box item (-listbox) only lets you select one single list element by default. Set the -multiple_selection attribute to 1 and you can select multiple elements. Main character energy. 👑

tepa::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. 🦋

-filetypes string — the file type attribute is used by the -file and -existingfile items to define the file endings that the file browser searches for.

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

-initialfile string — the initial file used by the file browsers of the -file and -existingfile widgets is by default the file defined with the -default attribute — unless a file is specified with the -initialfile attribute, which wins.

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

-activedir string — the -activedir attribute overrides the default active search directory used by the file browsers of all file and directory entry widgets. That default active search directory is defined by the directory of a specified initial file (-initialfile) if one is defined, and otherwise by the directory of the default file/directory specified with the -default attribute.

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

Finally, there's a last attribute supported by some widgets: 🌈

-height string — all widgets containing a selection list (-listbox, -disjointlistbox, -font) as well as the multi line -text widget accept the -height attribute, which defines the number of displayed rows of the selection lists.

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

If no height has been explicitly specified, the height of the widget gets dynamically adapted to the argument dialog box size. She adapts, she's flexible, she ate. 💅

✨ APPLICATION SPECIFIC ENTRY WIDGETS ✨

okay so bestie, you wanna make your own custom entry widget for the argument dialog box? iconic. All you gotta do is add a dedicated procedure to the tepam namespace. This procedure takes three arguments: the widget path, a subcommand, and a third argument that's like a wildcard — it does different things depending on the subcommand. 💅

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 is literally the bestie that handles the -label and -text attributes for all entry widgets. For any data entry widget it creates a frame where you can put your widget components. The path to that frame comes in via the W argument. 🫶

The entry widget procedure has to support 3 mandatory commands and 1 optional command, picked via the Command argument:

create — The first time the entry widget is called, it uses this command to build the data entry widget. The frames that argument_dialogbox gives you for entry widgets are only extendable in the X direction by default. If you want them to also stretch in the Y direction (like for extendable list boxes), you gotta run ad_form(make_expandable) $W when you build the widget. 💖
set_choice — This one only gets called if you specified -choices or -choicevariable. So it's really only relevant for list and combo boxes. The available selection list (from -choices or -choicevariable) is handed to you via the Par argument. Use it to initialize your choice list. ✨
set — If a default value is defined via -default or from a previous call, your procedure gets called with set. Then Par contains the value you need to initialize the widget to. 🌸
get — This one has to return the current value of the entry widget. Periodt. 💅

Any entry widget item attributes you specified are available via the Option array variable of the calling procedure. You can get to it inside your widget procedure using the upvar command.

Sometimes you need to store some info in a variable. Use the array variable argument_dialogbox for that, with indexes starting with "$W,", like argument_dialogbox($W,values). 🎀

The TEPAM package source file has examples of entry widget procedures, including all the standard ones. The simplest is 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]}
   }
}

You can also build on an existing entry widget procedure to make a new, more specific one. Like the radiobox widget — it's used to create a new widget that lets you pick left, center, or right. The original radiobox widget gets called with the set_choice command right after create to define that fixed list. 🦋

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
}

Go check the TEPAM package source file for more and more complex examples of entry widget procedures. 👑

🦋 VARIABLES 🦋

The argument_dialogbox uses two variables inside the ::tepam namespace:

argument_dialogbox — Application specific entry widget procedures can use this array variable to store their own data. Use the widget path as the index, like argument_dialogbox($W,<sub_index>). 💖
last_parameters — This array variable is only used by an argument dialog box if its context was specified via the -context attribute. The dialog box position and size, plus all the entered data, get stored here when the data are acknowledged and the form closes. That way the form can restore its previous state next time it's called. And if you wanna reuse those saved parameters in another session, just save the last_parameter array variable contents in a config file and load it when the app launches next time. 🌈

🌈 SEE ALSO 🌈

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

🌸 KEYWORDS 🌸

data entry form, parameter entry form

🎀 CATEGORY 🎀

Argument entry form, mega widget

👑 COPYRIGHT 👑

📦 where this page comes from

fedora 43: tcllib 2.0-3.fc43 · TCL
fedora 44: tcllib 2.0-4.fc44 · TCL
nixos 26.05: tcllib 2.0
nixpkgs unstable: tcllib 2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms

tepa...ogbox(n)

💖 tepa...ogbox(n) — Tcl's Enhanced Procedure and Argument Manager 💖

✨ NAME ✨

✨ SYNOPSIS ✨

✨ DESCRIPTION ✨

🌸 ARGUMENT DIALOGBOX CALL 🌸

🌈 CONTEXT DEFINITION ITEMS 🌈

🎀 FORMATTING AND DISPLAY OPTIONS 🎀

💜 GLOBAL CUSTOM DATA VALIDATION 💜

💖 DATA ENTRY WIDGET ITEMS 💖

`-entry` list

`-text` list

`-checkbox` list

`-radiobox` list

`-checkbutton` list

`-combobox` list

`-listbox` list

`-disjointlistbox` list

`-file` list

`-existingfile` list

`-directory` list

`-existingdirectory` list

`-color` list

`-font` list

ENTRY WIDGET ITEM ATTRIBUTES 🎀

✨ APPLICATION SPECIFIC ENTRY WIDGETS ✨

🦋 VARIABLES 🦋

🌈 SEE ALSO 🌈

🌸 KEYWORDS 🌸

🎀 CATEGORY 🎀

👑 COPYRIGHT 👑

tepa...ogbox(n)

💖 tepa...ogbox(n) — Tcl's Enhanced Procedure and Argument Manager 💖

✨ NAME ✨

✨ SYNOPSIS ✨

✨ DESCRIPTION ✨

🌸 ARGUMENT DIALOGBOX CALL 🌸

🌈 CONTEXT DEFINITION ITEMS 🌈

🎀 FORMATTING AND DISPLAY OPTIONS 🎀

💜 GLOBAL CUSTOM DATA VALIDATION 💜

💖 DATA ENTRY WIDGET ITEMS 💖

-entry list

-text list

-checkbox list

-radiobox list

-checkbutton list

-combobox list

-listbox list

-disjointlistbox list

-file list

-existingfile list

-directory list

-existingdirectory list

-color list

-font list

ENTRY WIDGET ITEM ATTRIBUTES 🎀

✨ APPLICATION SPECIFIC ENTRY WIDGETS ✨

🦋 VARIABLES 🦋

🌈 SEE ALSO 🌈

🌸 KEYWORDS 🌸

🎀 CATEGORY 🎀

👑 COPYRIGHT 👑

`-entry` list

`-text` list

`-checkbox` list

`-radiobox` list

`-checkbutton` list

`-combobox` list

`-listbox` list

`-disjointlistbox` list

`-file` list

`-existingfile` list

`-directory` list

`-existingdirectory` list

`-color` list

`-font` list