tep...gbox(3tcl)

📦

version 2.0 · 2 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.21 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

✨ NAME ✨

okay so bestie, this is the tepam::argument_dialogbox manual page — TEPAM argument_dialogbox, reference manual. 💖 It's part of Tcl's Enhanced Procedure and Argument Manager, and it's literally the main character of your Tk data entry forms. 🫶 No cap.

🌸 SYNOPSIS 🌸

the vibe check starts here — you gotta have these packages, fr fr:

package require Tcl 8.5 9

package require Tk 8.3

package require tepam ?0.5?

And here are the two ways to call it, bestie:

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 🔥

okay so the TEPAM argument_dialogbox is a flexible and easily usable data entry form generator that's available if Tk has been loaded. Periodt. Each data entry element of a form is defined via a data entry item that you can hand over to <code>argument_dialogbox</code> in two formats:

First format:

tepam::argument_dialogbox item_name item_attributes ?item_name
item_attributes? ?...?

Using this first format, each data entry item is defined via a pair of two arguments. The first one is the item name that defines the entry widget that has to be used in the form. The second argument, called item attributes, specifies the variable which is attributed to the data entry element as well as eventual formatting and context information.

The <code>argument_dialogbox</code> 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) the <code>argument_dialogbox</code> returns cancel.

A small example illustrates how the <code>argument_dialogbox</code> 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}]

This example opens a dialog box that has the title Itinerary selection. A first entry widget in this box allows selecting a report file. It follows two frames to define respectively an itinerary start and end location. Each of these locations that are described with a comment has three entry widgets to specify respectively the city, street and the street number. Below the second frame there is a check button that allows specifying if eventual highways should be ignored. <emoji>🦋</emoji>

Second format:

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

Sometimes it is simpler to provide all the data entry item definitions in form of a single list to <code>argument_dialogbox</code>, and not as individual arguments. The second format that is supported by <code>argument_dialogbox</code> corresponds exactly to the first one, except that all item definitions are packed into a single list that is provided to <code>argument_dialogbox</code>. 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} }]

The commands <code>argument_dialogbox</code> as well as <code>procedure</code> are exported from the namespace <code>tepam</code>. To use these commands without the <code>tepam::</code> 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 <code>argument_dialogbox</code>, 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 <code>argument_dialogbox</code>.

🦋 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 <code>Dialog</code> can be changed with the -title item:

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

-window string — The argument dialog box uses by default <code>.dialog</code> 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 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. The assignment of a context allows saving the dialog box state in its context to distinguish between different usages of the argument dialog box.

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

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.

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

💜 GLOBAL CUSTOM DATA VALIDATION 💜

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

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

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

okay so data entry widgets? they get created with the widget items, bestie. and every single one of them needs a definition list handed to it as its item attributes — that list is literally just attribute-name-and-value pairs stacked up, no cap:

tepam::argument_dialogbox \
   ...
   -<argument_name> {
      ?-<attribute_name> <attribute_value>?
      ?-<attribute_name> <attribute_value>?
      ?...?
   }
   ...

That attribute list can carry all kinds of stuff — it describes an entry widget, comments on it, and constrains whatever value somebody types into it. And the shared set of attributes that every entry widget accepts? Those live in the section Entry Widget Item Attributes — go read it, it's giving required reading. 🫶

TEPAM comes with a whole rich set of entry widgets 💅 and if that's not enough for you, the set can be extended with extra application specific entry widgets (peep APPLICATION SPECIFIC ENTRY WIDGETS). obsessed.

-entry list — this one makes the simplest but also the most universal data entry widget. It lets you enter literally any kind of data, as single line strings. slay:

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

-text list — makes a multi line text entry widget ✨ and you pick how tall it is with the -height attribute:

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

-checkbox list — a whole group of check boxes, one item, periodt. how many there are and what their option values are? you set that with a list on the -choices attribute, or through a variable declared with the -choicevariable attribute:

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

If you want the labels on the boxes to be different from the option values, define them with the -choicelabels attribute:

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

And here's the plot twist that separates it from a radio box group: a check box group lets you select several choice options at the same time. which is exactly why the selection gets stored inside the defined variable in the form of a list — even when only one choice option got selected. fr fr, it's always a list.

-radiobox list — a group of radio boxes. how many, and their option values, come from a list on the -choices attribute or from a variable declared with the -choicevariable attribute.

Now, in contrast to a check box group, a radio box group lets you select only one choice option at a time. And the selected option value gets stored directly, not in the form of a list, inside the defined variable. periodt.

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

Same deal as before — if the radio box labels should differ from the option values, use -choicelabels:

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

-checkbutton list — this entry widget turns a single choice option on or off. what lands in the variable is either 0 if the check button wasn't activated, or 1 if it was. and if you hand it a default value, that default has to be either 0 or 1 too. no in-betweens bestie:

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

There are several types of list and combo boxes available for handling selection lists. 🦋

-combobox list — the combobox is a glow-up of a normal entry widget paired with a drop-down list box. it lets you pick one single element out of that drop-down list box. the list of available elements can come either as a list on the -choices attribute, or via a variable named with the -choicevariable attribute:

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

And here's the same energy, but with a variable defining 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 — unlike the combo box, the list box is always on display, it never hides. Only one element is selectable — unless the -multiple_selection attribute is set. You pick the list box height with the -height attribute, and if you don't explicitly define a height, the list box height automatically adapts itself to the argument dialog box size. 💅 This 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's a multi-element selection example. And heads up — the default selection can hold multiple elements too:

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 — you reach for a disjoint list box instead of a normal list box whenever the order of the selection actually matters. because this entry widget is literally two list boxes: one to select elements, and one to show the selected elements in the order you chose. 👑

Disjoint listboxes always allow selecting multiple elements. And apart from the -multiple_selection attribute, disjointed list boxes accept the exact same attributes as the normal listbox — think -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 the next group of data entry widgets. 🌸 A paragraph over in the section Entry Widget Item Attributes explains the widget specific attributes that let you specify the targeted file types, the active directory, etc. iykyk.

-file list — this item makes a group of an entry widget plus a button that opens up a file browser. The data type file gets automatically selected for this entry if no data type was 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 — this item makes a group of an entry widget plus a button that opens a browser so you can select an existing file. The data type existingfile gets automatically selected for this entry if no data type was 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 — this item makes a group of an entry widget plus a button that opens a directory browser. The data type directory gets automatically selected for this entry if no data type was explicitly defined with the -type attribute:

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

-existingdirectory list — this item makes a group of an entry widget plus a button that opens a browser to select an existing directory. The data type existingdirectory gets automatically selected for this entry if no data type was explicitly defined with the -type attribute:

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

And finally, there's one last group of other special data entry widgets. ✨

-color list — the color selector is an entry widget plus a button that opens a color browser. The data type color gets automatically selected for this entry widget type if no data type was explicitly defined with the -type attribute:

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

-font list — the font selector is an entry widget plus a button that opens a font browser. The data type font gets automatically selected for this entry widget type if no data type was explicitly defined with the -type attribute. And cute detail: the entry widget shows you an example text rendered in the format of the selected font. 💅

The font browser lets you select, by default, the font families provided by the font families Tk command, plus a reasonable set of different font sizes between 6 points and 40 points. If you want different sets of font families and font sizes, you specify those with the -font_families or -font_sizes attributes respectively. 🎀

If no default font is provided via the -default attribute, the default font of the label widget to display the selected font will be used as default selected font. ✨ And okay, so — if the font family of this label widget isn't part of the available families, the first available family gets used as the default. And if the font size of this label widget isn't part of the available sizes, the next close available size is selected as the default size. It's giving "we'll find you a fit, bestie." 💅

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

All the entry widget items are accepting the following attributes: — like, every single one, no cap. 🫶

-text string — Eventual descriptions and comments specified with the -text attribute are displayed above the entry widget. It's the little note floating over your input box, iconic.

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

-label string — the -label attribute creates, to the left of the entry widget, a label using the provided string as label text. Side-label energy. 💖

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

-variable string — 🚨 All entry widgets require a specified variable. After accepting the entered information with the OK button, the entry widget data is stored inside the defined variables. That's the whole point, fr fr.

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

-default string — eventual default data for the entry widgets can be provided via the -default attribute. And here's the plot twist: the default value is overridden if an argument dialog box with a defined context is called another time — the value acknowledged in a previous call will be used in this case as default value. Memory queen. 👑

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

-optional 0|1 — data can be specified as optional or mandatory with the -optional attribute, which requires either 0 (mandatory) or 1 (optional) as attribute data. Choose wisely.

In case an entry is optional and no data has been entered — e.g. the entry contains an empty character string — the entry will be considered as undefined and the assigned variable will not be defined. Not me pointing out that "nothing" is a real answer here. 💀

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

-type string — if the data type is defined with the -type attribute, the argument dialog box will automatically perform a data type check after acknowledging the entered values and before the dialog box is closed. If a type incompatible value is found, an error message box appears and the user can correct the value. Built-in proofreading, we love to see it. ✨

The argument dialog box accepts all types that have been specified by the TEPAM package and that are also used by tepam::procedure (see the tepam::procedure reference manual). iykyk. 📖

Some entry widgets — like the file and directory widgets, as well as the color and font widgets — are specifying automatically the default data type if no type has been specified explicitly with the -type attribute. They just know. 🌈

tepam::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.

⚠️ The -range attribute has to be used only for numerical arguments, like integers and doubles. Don't try it on your text fields, bestie, it will not slay.

tepam::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 that are defined with the -validatecommand attribute. The provided validation command can be a complete script in which the pattern %P is a placeholder for the argument value that has to be validated. 🕵️♀️

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. Two flavors, both valid. 🍓

-validatecommand_error_text string — this attribute allows overriding the default error message for a custom argument validation (defined by -validatecommand). Make the scolding sound however you want. 💅

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

-choices string — choice lists can directly be defined with the -choices attribute. This way to define choice lists is especially adapted for smaller, fixed selection lists. Cute and compact.

tepam::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, they can be defined with the -choicelabels attribute. Show one thing, store another. Main character duality. 🎀

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

-choicevariable string — another way to define the choice lists is using the -choicevariable attribute. This way to define choice lists is especially adapted for huge and eventually variable selection lists. Big list energy only. 🦋

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

-multiple_selection 0|1 — the list box item (-listbox) allows by default selecting only one list element. By setting the -multiple_selection attribute to 1, multiple elements can be selected. Pick 'em all, greedy girl. 💖

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

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

tepam::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. Override privileges, unlocked. 🔓

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

-activedir string — the -activedir attribute will override the default active search directory used by the file browsers of all file and directory entry widgets. The default active search directory is defined by the directory of a specified initial file (-initialfile) if defined, and otherwise by the directory of the default file/directory, specified with the -default attribute. So it's a whole chain of "well, actually, if…" and we respect it. 🌈

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

Finally, there is 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 are accepting the -height attribute, which defines the number of displayed rows of the selection lists. Rows on rows. 📏

tepam::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 will be dynamically adapted to the argument dialog box size. It just fits itself, no notes. ✨

✨ APPLICATION SPECIFIC ENTRY WIDGETS ✨

okay so bestie, you can totally make your own custom entry widget for 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:

create — The entry widget is called a first time with the command create to build the data entry widget. The frames that are made available by argument_dialogbox for the entry widgets are by default only extendable in the X direction. To make them also extendable in the Y direction, for example for extendable list boxes, the command ad_form(make_expandable) $W has to be executed when an entry widget is built. 💖
set_choice — The entry widget procedure is only called with the set_choice command if the -choices or -choicevariable has been specified. The command is therefore only relevant for list and combo boxes. The available selection list that is either specified with the -choices or -choicevariable attribute is provided via the Par argument to the entry widget procedure. This list can be used to initialize an available choice list. ✨
set — If a default value is either defined via the -default attribute or via a preceding call the entry widget procedure is called with the set command. The argument Par contains in this case the value to which the entry widget has to be initialized. 💅
get — The entry widget procedure command get has to return the current value of the entry widget. Periodt. 🔥

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:

argument_dialogbox — Application specific entry widget procedures can use this array variable to store their own data, using as index the widget path provided to the procedure, e.g. argument_dialogbox($W,<sub_index>). 💅
last_parameters — This array variable is only used by an argument dialog box if its context has been specified via the -context attribute. The argument dialog box position and size as well as its entered data are stored inside this variable if the data are acknowledged and the form is closed. This allows the form to restore its previous state once it is called another time. To reuse the saved parameters not just in the actual application session but also in another one, it is sufficient to store the last_parameter array variable contents in a configuration file which is loaded the next time an application is launched. 🎀

👀 SEE ALSO 👀

tepam(3tcl)
tepam::procedure(3tcl)

🔑 KEYWORDS 🔑

data entry form, parameter entry form

📂 CATEGORY 📂

Argument entry form, mega widget

that's the whole vibe, bestie 💖 this was tcllib 0.5.0, page tep...gbox(3tcl). no cap, you're gonna slay with these custom widgets. ✨👑

📦 where this page comes from

debian trixie: tcllib 2.0+dfsg-4 · Tcl
ubuntu questing: tcllib 2.0+dfsg-4
ubuntu resolute: tcllib 2.0+dfsg-5 · Tcl
ubuntu stonking: tcllib 2.0+dfsg-6 · Tcl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms