widget_listentry(n)

📦 version 0.7, in alpine 3.24

💖 widget_listentry(n) 💖 — the widget::listentry widget, bestie, no cap

okay so this is the manual page for widget_listentry, a.k.a. the widget::listentry widget. It’s giving list-entry megawidget energy, and we’re going through every option, signature, default, and caveat together, periodt. 🫶

🌸 NAME 🌸

widget_listentry - widget::listentry widget — that’s the name, that’s the vibe. 💅

✨ SYNOPSIS ✨

First up, the requires and command shapes. These are literal, so I’m keeping them exactly as written, no editing, no “fixing,” none of that:

package require Tcl  8.5

package require Tk  8.5

package require widget::listentry  ?0.1.2?

package require widget::validator  ?0.1?

package require widget::scrolledwindow

package require snit

package require tooltip

package require img::png

package require msgcat

widget::listentry pathname ?options?

widgetCmd destroy

widgetCmd configure

widgetCmd configure option value ...

widgetCmd configure option

widgetCmd cget option

{*}cmdprefix get

{*}cmdprefix set values

{*}cmdprefix text errvar

{*}cmdprefix text

{*}cmdprefix cookievar

The ?0.1.2? and ?0.1? are literally part of the synopsis, iykyk. 🎀

🦋 DESCRIPTION 🦋

This package provides a megawidget for the interactive entry of ordered and unordered lists. For a simpler and more restricted megawidget please see the package widget::listsimple. That’s the whole description, and honestly it understood the assignment. ✨

👑 CLASS API 👑

The widget class supports a single command, for the creation of widgets. One command, main character energy, we love to see it. 👑

  • widget::listentry pathname ?options? — this command creates and configures new instances of the widget. For details on the available options please see section Widget Options. The result of the command is the pathname of the new widget. Slay. 💖

💅 INSTANCE API 💅

The original says “All widget instances supported the following methods.” I’m keeping the whole list intact, bestie: 🫶

  • widgetCmd destroy — this method destroys the widget. Any further access to the widget will generate errors. The result of the command is the empty string.
  • widgetCmd configure — this method comes in three variants. This variant here returns a list containing the current configuration of the widget, i.e. the values for all options. For details on the available options please see section Widget Options.
  • widgetCmd configure option value ... — this method comes in three variants. This variant here reconfigures the widget, setting the specified options to the given values. Note that it is not possible to change the construction-time only options. For details on the available options please see section Widget General Options. The result of the command is the empty string.
  • widgetCmd configure option — this method comes in three variants. This variant here is an alias for the method cget below and identical to it.
  • widgetCmd cget option — this method returns the current value of the specified option. For details on the available options please see section Widget Options.

🌈 WIDGET OPTIONS 🌈

This section explains all the options available to instances of widget::listentry. Please note that a few of the options can be set only at instance construction time. The majority of the options can however be set both during construction- and runtime. So yes, some are locked after birth, and some are glow-up-able whenever. 💖

🎀 WIDGET CONSTRUCTION-TIME ONLY OPTIONS 🎀

Construction-time only means construction-time only, bestie. The page says it is not possible to change construction-time only options later, so set them with intention. 💅
  • -ordered boolean — this option tells the new widget instance whether the list it manages is ordered or not. If it is ordered, the widget will show buttons with which the selected entries can be moved around, editing the order. The default is false, indicating an unordered list.
  • -allow-duplicates boolean — this option tells the new widget instance whether we are allowed to add a string to the list multiple times, or not. The default is false, indicating that duplicates are not allowed.
  • -values cmdprefix — this option specifies a callback for the management of a predefined list of strings a user may enter. If specified, the widget will use a combobox instead of a plain entry field and fill its list during widget construction using the data delivered by this callback. The callback will be further invoked whenever a new value is entered into the main list, to save the extended list of predefined values. The signatures of this callback are:
    • {*}cmdprefix get — in this form the callback is expected to return a list of strings. The strings are loaded into the list of the internal combobox for quick access by the user. It will be invoked once, during widget construction, to load the list of predefined strings a user may enter.
    • {*}cmdprefix set values — in this form the callback is given a list of new strings and expected to save them somewhere for future use. The return value of the callback is ignored. This form is invoked whenever the user entered a new string into the main list. The order of strings in values represents the order used to show them in the combobox’s list.
  • -validate cmdprefix — this option specifies a callback which is invoked after every change of the contents of the internal entry field. The signature of this callback is:
    • {*}cmdprefix text errvar — where text is the string to validate, and errvar the name of a variable the callback can store an error message into when it detects invalid data. The widget expects that the callback returns a boolean value, where true indicates that text is valid.

The default validation, when no callback was specified, will treat the empty string as invalid, and everything else as valid.

Duplicate check is separate from validity, no cap. The widget will prevent the entry of duplicate values into the main list, regardless of the validity of the input otherwise. This is in keeping with that this widget is meant for the entry of unordered lists, essentially a set of strings. 💀
  • -transform cmdprefix — this option specifies a callback which is invoked whenever a newly entered element is moved from the entry field to the main list, or the entry field is validated, as part of a check for duplicates, if such are not allowed. The callback is given the text in the entry field and has to return the text which is actually added to, or checked against the list. The use case for this callback is essentially input normalization. The most simple case of such would be, for example, the use of string tolower to case on the data. More complex examples can be thought of, like rewriting of multiple syntaxes of input to a canonical form. The signature of this callback is:
    • {*}cmdprefix text — where text is the string to transform. The widget expects that the callback returns the transformed string.

The default is to not transform the entered strings.

  • -browse cmdprefix — if this option is specified the widget will display a "Search" button and invoke the callback provided by the option whenever the user clicks on that button. The signature of the callback is:
    • {*}cmdprefix cookievar — where the cookie variable provides access to context information the callback may wish to preserve between invocations. The initial value stored in the variable is the empty string. After that it is whatever the callback wishes to store. The widget expects that the callback returns a list of strings, which are then added to the list, modulo validity and duplicate checks.

By default there is no browse callback and no button shown.

🌟 WIDGET GENERAL OPTIONS 🌟

  • -listvariable varname — this option specifies the variable holding the list to be manipulated by the widget. Any changes to the list outside of the widget are automatically imported into the widget. Similarly, all changes made to the list by the widget are automatically exported to this variable. Two-way list gossip, lowkey iconic. 🦋
  • -state normal|disabled — this option specifies the status of the widget, normal (= active), or disabled. A disabled widget can not be edited. The default is normal.
  • -height integer — this option specifies the height of the internal listbox, in lines. The default is 20.

And now the skin controls — yes, every single one is here, bestie, we are not skipping a crumb: 🎀

  • -skin-add string — skin string.
  • -skin-remove string — skin string.
  • -skin-up string — skin string.
  • -skin-down string — skin string.
  • -skin-browse string — skin string.
  • -skin-tip-add string — skin tooltip string.
  • -skin-tip-remove string — skin tooltip string.
  • -skin-tip-up string — skin tooltip string.
  • -skin-tip-down string — skin tooltip string.
  • -skin-tip-browse string — skin tooltip string.
  • -skin-tip-main string — skin tooltip string.
  • -skin-tip-entry string — skin tooltip string.
  • -skin-tip-list string — skin tooltip string.
  • -skin-tip-empty string — skin tooltip string.
  • -skin-tip-duplicate string — skin tooltip string.
  • -skin-tip-add-none string — skin tooltip string.
  • -skin-tip-remove-none string — skin tooltip string.
  • -skin-img-add image — skin image.
  • -skin-img-remove image — skin image.
  • -skin-img-up string — skin image value, typed as string in the manual.
  • -skin-img-down string — skin image value, typed as string in the manual.
  • -skin-img-browse string — skin image value, typed as string in the manual.
  • -skin-invalid-color color — invalid-entry highlight color; defaults to yellow.

These options all modify the appearance of the widget, i.e. its skin. All options taking a string argument influence the various labels shown, with the -skin-tip-* options influencing the tooltips shown on hovering over various parts in particular. All the strings are run through msgcat first, enabling text localization through message catalogs. The default values are keys into the message catalogs which are part of the package itself. The options taking images modify the images shown on the buttons for adding and removing elements of the list. They default to the PNG images distributed with the package itself. The single option taking a color value modifies the color used to highlight invalid data entered into the internal entry field of the widget. This option defaults to yellow.

🍓 EXAMPLE 🍓

The original page has an EXAMPLE heading and then literally nothing under it. No example. Not a crumb. Iconic minimalist behavior, honestly. 💀

💀 BUGS, IDEAS, FEEDBACK 💀

okay so real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category widget::listentry of the Tklib Trackers [http://core.tcl.tk/tklib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation. We’re keeping it cute but the bug reports are real, bestie. 🫶

⭐ KEYWORDS ⭐

  • data entry lists
  • data entry ordered list
  • data entry set of strings
  • data entry unordered list
  • list entry panel
  • set entry panel
  • widget

Signed off from the tklib source, version 0.1.2, with the footer tag widget_listentry(n) — and the original footer doesn’t show a separate date, so I’m not inventing one, bestie 💖✨

📦 where this page comes from