Text Fields
Originally, I did not plan on canvasGUI having keyboard input controls but I needed them for a web-app I wanted to create so they were added to version 0.9.3. Unfortunately, the text fields didn’t behave well when the canvas lost focus but this was fixed in 0.9.4.
Text field status
A text field can be in one of two states 'active' and 'inactive'
While a text field is active all other canvasGUI controls cannot be used.
Active state
In this state the text field will
- display keyboard input
- allow user to edit displayed text
- allow the left and right arrow keys to move the text insertion point (TIP)
- allow text selection pressing the shift key while using the left and right arrow keys
To make a text field active simply click on it.
Inactive state
In this state the textfield does not respond to the keyboard.
text(text) |
Sets the text to appear in the text field. If no text is provided then it returns the current text being displayed. |
index(uid, offset) |
The 1st parameter is the unique identity (UID) number for this textfield. The 2nd parameter is optional and if provided sets the UID offset to use with the UP / DOWN arrows. |
noIndex() |
Removes the UID from this text field. |
validation(vfunc) |
Sets the function to be used when validating the text. |
isValid() |
Returns true if the displayed text is considered valid, els returns false. |
clearValid() |
Clears the vaild flag |
Multiple text fields to create an input form
Filling forms on-line is such a common activity I suspect that most users have hit the tab key to move to the next input field. Since the web browser uses the tab key for its own navigation, canvasGUI uses the arrow keys instead.
To make this possible each text field must have a unique identity number (UID). The user can set the UIDs with the index method.
If the active text field has a UID of idx then activity transfer is shown in this table
| Movement condition A | Adjusted UID |
|---|---|
| LEFT arrow + TIP in front of any text | idx - 1 |
| RIGHT arrow + TIP at the end of any text | idx + 1 |
| UP arrow B | idx - offset |
| DOWN arrow B | idx + offset |
- A only applies if the current active control has a UID
- B use the second parameter (optional) of the
index()method to set the offset. If none is provided the up and down keys are ignored.
If one of these conditions is met then the active text field is made inactive then, if there is a text field with the adjusted UID it is made active.
At any time, an active text field can be deactivated by pressing the Enter / Return key.
In this sketch the user can move between the four text fields using the arrow keys as shown.
Validation
A powwerful feature of text fields is the ability to validate the displayed text. Validation is not applied during keyboard input rather it occurs when the text field is deactivated.
The validation function is user defined and must decide whether the display text is valid or not. As well as validity, the function can be used to modify the displayed text. In the above sketch any displayed text is capitalized when the text field is deactivated, so 'gryffindor' would be changed to 'Gryffindor'
The text field control demo shows validation in action and has examples of various validation functions you could adapt to your needs.