widget_validator(3tk)

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

💖 widget_validator — bestie edition 💖

okay so this is widget_validator(3tk), a whole manual page from the widget::validator behaviour family, and honestly? she's giving "tiny package, huge responsibility." let's get into it 🫶

✨ NAME ✨

widget_validator — the whole widget::validator behaviour, that's her, that's the girl 💅

🌸 SYNOPSIS 🌸

package require Tcl 8.5

package require Tk 8.5

package require widget::validator ?0.1?

widget::validator attach w color cmdprefix

widget::validator detach w

widget::validator validate w

🦋 DESCRIPTION 🦋

so basically this package hands you a unified validation API for ttk's entry and combobox widgets. one API to rule them all, no cap ✨

⚠️ okay IMPORTANT bestie, read this twice: the validation behaviour defined in this package will not reject invalid edits. it will only highlight the entry containing invalid data and set the proper state flag. that's it. that's the whole job.

and like, it is the responsibility of the using package or application to decide how and when to actually reject such invalid content. so don't come for this package when your invalid text just sits there looking pretty in lightblue 😭

🎀 the three methods 🎀

  • widget::validator attach w color cmdprefix — adds a validating behaviour to the widget w. every time the content of the widget's entry field changes, the specified cmdprefix gets invoked and has to return a boolean value: true means the content is ok, false means the content is invalid (more on the command prefix in the Validation section below, iykyk). if it comes back invalid, the background color of the entry field is changed to color to indicate the invalidity. 💅

the system does not support nesting of validators on a widget, nor the attachment of multiple validators. so if you wanna change validating conditions, detach the current validator first before attaching the new one. periodt.

an error is thrown if the widget has already had validating behaviour attached to it. 🙈

the result of the method is the empty string.

to achieve its aims, the package overrides various configuration options of the widget the behaviour is attached to. these options are restored to their previous values on detach. good as new, no trace left behind 💖

⚠️ if other behaviours are attached, the validator may be rendered temporarily (partially) non-functional. similarly, if the validator is detached while a different behaviour is also attached, its restoration of configuration settings may render the other non-functional. it's giving chaos, so be careful out there.
  • widget::validator detach w — removes the validating behaviour from the widget w and restores it to its original state. glow-up reversed ✨

an error is thrown if the widget has no validating behaviour attached to it. (nothing to detach, bestie, there's nothing there 😭)

the result of the method is the empty string.

  • widget::validator validate w — invoking this method forces a validation of the widget w, assuming that it has a validator behaviour attached to it. like a vibe check but for your entry field 👑

the result of the method is the empty string.

⭐ VALIDATION ⭐

the command prefix used for validation has to have the following signature:

{*}cmdprefix text
  • the argument is the text to validate.
  • the result of the callback has to be a boolean value where true means that text is ok, and false that text is invalid.

that's the whole contract, no cap 🫶

🌈 EXAMPLE 🌈

package require Tk 8.5
package require widget::validator

set TE {}
set TC {}

ttk::entry    .e -textvariable TE
ttk::combobox .c -textvariable TC -values {fruit vegetable corn}
ttk::combobox .n -values {fruit vegetable corn}
ttk::button   .x -command ::exit -text Exit

pack .e -expand 1 -fill both -side top
pack .c -expand 1 -fill both -side top
pack .n -expand 1 -fill both -side top
pack .x -expand 1 -fill both -side top

widget::validator attach .e lightblue {apply {text {
    expr {$text ne {}}
}}}

widget::validator attach .c yellow {apply {text {
    expr {$text ni {{} hello world}}
}}}

widget::validator attach .n pink {apply {text {
    expr {$text ni {{} blub}}
}}}

three widgets, three colors, three little expr bouncers at the door. iconic behavior honestly 🎀

💀 BUGS, IDEAS, FEEDBACK 💀

this document, and the package it describes, will undoubtedly contain bugs and other problems. (she said it herself, not me 💀) please report such in the category widget::validator of the Tklib Trackers at [http://core.tcl.tk/tklib/reportlist]. please also report any ideas for enhancements you may have for either package and/or documentation — they wanna hear from you, fr fr 🙏

👑 KEYWORDS 👑

invalid, state management, ttk::combobox, ttk::entry, validation, widget validation

okay that's the whole page bestie, slay 💅

this was widget_validator(3tk), tklib version 0.1, and honestly she ate and left no crumbs. go forth and validate responsibly 🌸💖✨

📦 where this page comes from