Skip to content

validation module

This module contains classes and functions that are used to add validation to Entry, Spinbox, and Combobox widgets. Several helper methods are included which start with the "add" prefix.

Using predefined methods

When validation is applied to a widget and the input is determined to be invalid, a 'danger' colored border is applied to the widget. This border disappears when the widget is determined to have valid contents.

Below are a few examples using predefined validation. Browse the full list in the documentation below:

app = ttk.Window()

entry = ttk.Entry()
entry.pack(padx=10, pady=10)

# check if contents is text
add_text_validation(entry)

# prevent any entry except text
add_text_validation(entry, when='key')

# check for a specific list of options
add_option_validation(entry, ['red', 'blue', 'green'])

# validate against a specific regex expression
add_regex_validation(entry, r'\d{4}-\d{2}-\d{2}')    

Adding a custom validation

First, create a custom validation function. This must accept a ValidationEvent object and should return a boolean. You should also use the @validator decorator to convert this method to a validation method. Check the ValidationEvent attributes to learn about what is returned in this event.

from ttkbootstrap import validator, add_validation

@validator
def validate_long_text(event):
    if len(event.postchangetext) > 20:
        return True
    else:
        return False

Apply your custom validation to the widget

add_validation(entry, validate_long_text)

ValidationEvent

Contains the attributes of a validation event returned by the validatecommand on a tkinter widget.

Attributes:

Name Type Description
actioncode str

0 for an attempted deletion, 1 for an attempted insertion, or -1 if the callback was for focusin, focusout, or a change to the textvariable.

insertdeletetext str

When the user attempts to insert or delete text, this attribute will be the index of the beginning of the insertion or deletion. If the callback was due to focusin, focusout, or a change to the textvariable, the attribute will be -1.

postchangetext str

The value that the text will have if the change is allowed.

prechangetext str

The text in the entry before the change.

insertdeletetext str

The text inserted or deleted if the call was due to an insertion or deletion.

validationtype str

Specifies the widget's validation option which specifies when the validation will occur.

widget Widget

The widget object that is being validated.

add_numeric_validation(widget, when='focusout')

Check if widget contents is numeric. Sets the state to 'Invalid' if not a number.

Parameters:

Name Type Description Default
widget Widget

The widget on which to add validation.

required
when str

Specifies when to apply validation. See the add_validation method docstring for a full list of options.

'focusout'
Source code in ttkbootstrap/validation.py
def add_numeric_validation(widget, when="focusout"):
    """Check if widget contents is numeric. Sets the state to 'Invalid'
    if not a number.

    Parameters:

        widget (Widget):
            The widget on which to add validation.

        when (str):
            Specifies when to apply validation. See the `add_validation`
            method docstring for a full list of options.
    """
    add_validation(widget, _validate_number, when=when)

add_option_validation(widget, options, when='focusout')

Check if the widget contents is in a list of options.

Parameters:

Name Type Description Default
widget Widget

The widget on which to add validation.

required
when str

Specifies when to apply validation. See the add_validation method docstring for a full list of options.

'focusout'
Source code in ttkbootstrap/validation.py
def add_option_validation(widget, options, when="focusout"):
    """Check if the widget contents is in a list of options.


    Parameters:

        widget (Widget):
            The widget on which to add validation.

        when (str):
            Specifies when to apply validation. See the `add_validation`
            method docstring for a full list of options.
    """
    add_validation(widget, _validate_options, options=options, when=when)

add_phonenumber_validation(widget, when='focusout')

Check if the widget contents matches a phone number pattern.

Parameters:

Name Type Description Default
widget Widget

The widget on which to add validation.

required
when str

Specifies when to apply validation. See the add_validation method docstring for a full list of options.

'focusout'
Source code in ttkbootstrap/validation.py
def add_phonenumber_validation(widget, when="focusout"):
    """Check if the widget contents matches a phone number pattern.

    Parameters:

        widget (Widget):
            The widget on which to add validation.

        when (str):
            Specifies when to apply validation. See the `add_validation`
            method docstring for a full list of options.
    """
    pattern = r"^[\+]?[(]?[0-9]{3}[)]?[-\s\.]?[0-9]{3}[-\s\.]?[0-9]{4,6}$"
    add_validation(widget, _validate_regex, pattern=pattern, when=when)

add_range_validation(widget, startrange, endrange, when='focusout')

Check if widget contents is within a range of numbers, inclusive. Sets the state to 'Invalid' if the number is outside of the range.

Parameters:

Name Type Description Default
widget Widget

The widget on which to add validation.

required
when str

Specifies when to apply validation. See the add_validation method docstring for a full list of options.

'focusout'
Source code in ttkbootstrap/validation.py
def add_range_validation(widget, startrange, endrange, when="focusout"):
    """Check if widget contents is within a range of numbers, inclusive.
    Sets the state to 'Invalid' if the number is outside of the range.

    Parameters:

        widget (Widget):
            The widget on which to add validation.

        when (str):
            Specifies when to apply validation. See the `add_validation`
            method docstring for a full list of options.
    """
    add_validation(
        widget,
        _validate_range,
        startrange=startrange,
        endrange=endrange,
        when=when,
    )

add_regex_validation(widget, pattern, when='focusout')

Check if widget contents matches regular expresssion. Sets the state to 'Invalid' if no match is found.

Parameters:

Name Type Description Default
widget Widget

The widget on which to add validation.

required
when str

Specifies when to apply validation. See the add_validation method docstring for a full list of options.

'focusout'
Source code in ttkbootstrap/validation.py
def add_regex_validation(widget, pattern, when="focusout"):
    """Check if widget contents matches regular expresssion. Sets the
    state to 'Invalid' if no match is found.

    Parameters:

        widget (Widget):
            The widget on which to add validation.

        when (str):
            Specifies when to apply validation. See the `add_validation`
            method docstring for a full list of options.
    """
    add_validation(widget, _validate_regex, pattern=pattern, when=when)

add_text_validation(widget, when='focusout')

Check if widget contents is alpha. Sets the state to 'Invalid' if not text.

Parameters:

Name Type Description Default
widget Widget

The widget on which to add validation.

required
when str

Specifies when to apply validation. See the add_validation method docstring for a full list of options.

'focusout'
Source code in ttkbootstrap/validation.py
def add_text_validation(widget, when="focusout"):
    """Check if widget contents is alpha. Sets the state to 'Invalid'
    if not text.

    Parameters:

        widget (Widget):
            The widget on which to add validation.

        when (str):
            Specifies when to apply validation. See the `add_validation`
            method docstring for a full list of options.
    """
    add_validation(widget, _validate_text, when=when)

add_validation(widget, func, when='focusout', **kwargs)

Adds validation to the widget of type Entry, Combobox, or Spinbox. The func should accept a parameter of type ValidationEvent and should return a boolean value.

Parameters:

Name Type Description Default
widget Widget

The widget on which validation will be applied.

required
func Callable

The function that will be called when a validation event occurs.

required
when str

Indicates when the validation event should occur. Possible values include:

  • focus - whenever the widget gets or loses focus
  • focusin - whenever the widget gets focus
  • focusout - whenever the widget loses focus
  • key - whenever a key is pressed
  • all - validate in all of the above situations
'focusout'
kwargs Dict

Optional arguments passed to the callback.

{}
Source code in ttkbootstrap/validation.py
def add_validation(widget, func, when="focusout", **kwargs):
    """Adds validation to the widget of type `Entry`, `Combobox`, or
    `Spinbox`. The func should accept a parameter of type
    `ValidationEvent` and should return a boolean value.

    Parameters:

        widget (Widget):
            The widget on which validation will be applied.

        func (Callable):
            The function that will be called when a validation event
            occurs.

        when (str):
            Indicates when the validation event should occur. Possible
            values include:

            * focus - whenever the widget gets or loses focus
            * focusin - whenever the widget gets focus
            * focusout - whenever the widget loses focus
            * key - whenever a key is pressed
            * all - validate in all of the above situations

        kwargs (Dict):
            Optional arguments passed to the callback.
    """
    f = widget.register(lambda *e: func(*e, **kwargs))
    subs = (r"%d", r"%i", r"%P", r"%s", r"%S", r"%v", r"%V", r"%W")
    widget.configure(validate=when, validatecommand=(f, *subs))

validator(func)

Decorates a standard function so that it receives the validation events returned by the validate command on the tkinter widgets.

Parameters:

Name Type Description Default
func Callable

The validation function to be decorated.

required
Source code in ttkbootstrap/validation.py
def validator(func):
    """Decorates a standard function so that it receives the validation
    events returned by the validate command on the tkinter widgets.

    Parameters:

        func (Callable):
            The validation function to be decorated.
    """

    def inner(*args, **kw):
        event = ValidationEvent(*args)
        return func(event, **kw)

    return inner