widget_listentry(3tk)

📦
version 0.9 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 widget_listentry — the widget::listentry glow-up 💖

okay bestie, gather round, because we're talking about widget_listentry(3tk) — the widget::listentry widget from the tklib fam. it's giving manual page, it's giving megawidget, and yes it's literally in section 3tk. 🎀

✨ SYNOPSIS ✨

first things first, the prerequisites, no skipping:

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

and the commands themselves, verbatim, don't @ me:

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

🌸 DESCRIPTION 🌸

so this package hands you a megawidget for the interactive entry of ordered and unordered lists. that's the whole vibe. it eats lists for breakfast, orders them or doesn't, and looks cute doing it. 🦋

if you want something simpler and more restricted, bestie, there's a whole other megawidget for that — go peek at the package widget::listsimple. this one is the main character; that one is the chill sidekick.

👑 CLASS API 👑

the widget class keeps it minimal — literally one command, and it's for making widgets. iconic behavior.

  • widget::listentry pathname ?options? — this creates and configures brand new instances of the widget. for the deets on which options exist, scroll to the Widget Options section. and the result of the command? the pathname of your shiny new widget. slay. ✨

🫶 INSTANCE API 🫶

every widget instance supports these methods. memorize them, they're your new besties.

  • widgetCmd destroy — destroys the widget. 💀 and fr fr, after this, any further access to the widget will generate errors. it's gone gone. the result of the command is the empty string.
  • widgetCmd configure — okay so this method comes in three variants, and this one right here returns a list containing the current configuration of the widget, aka the values for all options. for details on the available options, see the Widget Options section.
  • widgetCmd configure option value ... — variant number two of three! this one reconfigures the widget, setting the specified options to the given values.
heads up bestie: it is not possible to change the construction-time only options. they're locked in at birth, periodt.

for details on the available options, see the section Widget General Options. the result of the command is the empty string.

  • widgetCmd configure option — variant number three of three! this one is an alias for the method cget below, and identical to it. twins fr.
  • widgetCmd cget option — returns the current value of the specified option. for details on the available options, see the Widget Options section. 🔍

💅 WIDGET OPTIONS 💅

this section explains all the options available to instances of widget::listentry. important note bestie: a few of these options can be set only at instance construction time. the majority though? totally settable both during construction and runtime. flexible queen. 👑

🎀 WIDGET CONSTRUCTION-TIME ONLY OPTIONS 🎀

  • -ordered boolean — tells the new widget instance whether the list it manages is ordered or not. if it is ordered, the widget shows buttons so the selected entries can be moved around, editing the order. the default is false, meaning an unordered list. 🌈
  • -allow-duplicates boolean — tells the new widget instance whether we're allowed to add a string to the list multiple times, or not. the default is false, meaning duplicates are not allowed. one of each, we're not messy. 🍓
  • -values cmdprefix — specifies a callback for managing a predefined list of strings a user may enter. if you specify it, the widget uses a combobox instead of a plain entry field, and fills its list during widget construction using the data delivered by this callback. the callback gets invoked again whenever a new value is entered into the main list, so it can save the extended list of predefined values.

the signature of this callback is:

  • {*}cmdprefix get — in this form the callback is expected to return a list of strings. those strings get 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 is 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 — specifies a callback invoked after every change of the contents of the internal entry field. signature time:
    • {*}cmdprefix text errvar — where text is the string to validate, and errvar is the name of a variable the callback can store an error message into when it detects invalid data. the widget expects the callback to return a boolean value, where true means text is valid. ✅

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

okay important: 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. so no double-dipping. 🙈
  • -transform cmdprefix — specifies a callback invoked whenever a newly entered element is moved from the entry field to the main list, or when the entry field is validated, as part of a check for duplicates (if duplicates aren't 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 here is essentially input normalization. the most simple case would be, for example, the use of

string tolower

to case on the data. more complex examples can be thought of, like rewriting 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 the callback to return the transformed string. 🪄

the default is to not transform the entered strings.

  • -browse cmdprefix — if you specify this option, the widget displays a "Search" button and invokes the callback whenever the user clicks it. signature:
    • {*}cmdprefix cookievar — where the cookie variable provides access to context information the callback may wish to preserve between invokations. the initial value stored in the variable is the empty string. after that it's whatever the callback wishes to store. the widget expects the callback to return 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 — 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 sync, we love a communicative relationship. 💞
  • -state normal|disabled — specifies the status of the widget: normal (= active), or disabled. a disabled widget can not be edited. the default is normal.
  • -height integer — specifies the height of the internal listbox, in lines. the default is 20. 📏
  • -skin-add string
  • -skin-remove string
  • -skin-up string
  • -skin-down string
  • -skin-browse string
  • -skin-tip-add string
  • -skin-tip-remove string
  • -skin-tip-up string
  • -skin-tip-down string
  • -skin-tip-browse string
  • -skin-tip-main string
  • -skin-tip-entry string
  • -skin-tip-list string
  • -skin-tip-empty string
  • -skin-tip-duplicate string
  • -skin-tip-add-none string
  • -skin-tip-remove-none string
  • -skin-img-add image
  • -skin-img-remove image
  • -skin-img-up string
  • -skin-img-down string
  • -skin-img-browse string
  • -skin-invalid-color color — these options all modify the appearance of the widget, aka 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 the 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 🌈

okay so real talk... this section is, like, empty in the original. no example given. i know, i know, we were all ready. 😭 it's just vibes and whitespace down here, bestie.

💜 BUGS, IDEAS, FEEDBACK 💜

this document, and the package it describes, will undoubtedly contain bugs and other problems. no cap. please report such in the category widget::listentry of the Tklib Trackers at [http://core.tcl.tk/tklib/reportlist]. please also report any ideas for enhancements you may have for either the package and/or the documentation — they wanna hear it. 🫶

⭐ KEYWORDS ⭐

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

and that's the whole page, bestie! 🎀 this one's from tklib, version 0.1.2, dated right there with widget_listentry(3tk) in the footer. go build something cute with your ordered lists. mwah. 💖✨

📦 where this page comes from