Xojo Articles - Table of Contents

Managing User Input, DesktopTextField and Beyond (Part 1) 10/30/2022

DesktopTextEdit fields have lots of options to help manage the user's entries. These include:

The first four are pretty easy to understand and use...  However 'Format' and 'ValidationMask' are trickier to use and to fully understand.  And of course, you have to be prepared to use handle the 'ValidationFailed' event is some situations.

First let's look at 'Format'.  This is a format specifier, as is used in many languages and in the Xojo 'Format' function, which formats a number into a string according to a 'formatSpec string' which offers numerous options to make a number into a consistent format, like adding commas (thousands separators), limiting decimal places.  The application of Format ONLY occurs when a DesktopTextField loses focus, or has a new value set programmatically.

Now, 'ValidationMask' is a more of a mixed bag.  The 'ValidationMask' is a string which provides a template for the text to be accepted.  Each character entered, as entered, is checked against the validation mask and is either accepted or rejected.  The mask can include literal text characters, required specifiers and optional specifiers.  It can be a bit of trial-and-error to get a validation mask to do what you want without doing what you don't want.  ValidationMask is a very powerful feature, if you take the time to learn to use it properly.

To assist me (and you if you like) in testing the various features of DesktopTextFields, I've written a small Xojo program so you can test interactively.  It lets you adjust all those settings, plus Enabled and Visible.  It shows you when Focus received or lost events occur, when Text changed events occur, and can show you each character received by the KeyDown events.  See the box at the top of the article to download the Xojo project (as a ZIP file) or the latest MacOS executable, compiled and ready to run.

Format (details and warnings)

If the Format string is not empty, then the Format operation will occur as soon as the focus moves off the text field, or when the value of the text field is set by other code.  The user can enter anything allowed and Format will not impose any limitations on the typed values.  Whatever text is there will be converted to a number then formatted according to your format spec.  The string created will then be the value in the DesktopTextField.

ValidationMask (details and warnings)

If the ValidationMask string is not empty, then whatever is entered into the text field will be validated, character-by-character.  Non-conforming or invalid characters will be ignored (ValidationError event will fire if you have a handler for it).

In very specific cases, creating effective ValidationMasks can be quite helpful and relatively easy.  The common example is a US telephone number,  perhaps you use this mask '(###) ###-####'.  It will powerfully and effectively limit the value entry to the digits and add the required formatting characters as you go.  However if your valid input is more flexible, a good ValidationMask may be much more difficult, or impossible, to create.  For example, come up with a mask to allow entry of positive or negative numbers between -100.00 and +100.00.

Do it yourself - capturing characters

If your needs for formatting or validating input exceed what can be accomplished with Format and ValidationMask, you may fall down a rabbit hole of intercepting keypresses to implement limiting, validating and formatting on your own.  This can be effective, but in the general case can become a nightmare.  Even commonly used requirements, like "I want to allow an integer between 0 and 100" are just not easy to implement using the DesktopTextField's built-in features.

Summary

In many, if not most, actual cases, the right ValidationMask and/or Format is all you need to reasonably constrain user entered values.  Of course, look at the warning and danger boxes above, there are a few things to be aware of, especially the fact that with Format defined, your program may read different values depending upon whether the control has focus or not.

Now, of course, this is Xojo and there is a huge community of support.  Many different developers provide text field controls which may assist you in more quickly developing your software.  Some are free, some include various costs.  In my next article, I'll show you how to add some new features to simplify getting user-entered number values.

In case you are interested in my free LDS_DesktopTextField_Tester program (see above to download the project folder or MacOS executable), here's a picture of the main window.