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.
- 'Hint' is greyed out text that shows in the box when there is no user data there, it serves to hint to the user what they should enter.
- 'Password' will conceal the entered text in the display
- 'MaximumCharacters' is totally self-explanatory
- 'AllowTabs' determines whether the tab-key will be entered as text or used to move to the next control
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.
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.