Inconsistent description of field focus behavior in fieldValidationFailed documentation

Bugs or Feedback
1

The documentation for fieldValidationFailed seems to contain an inconsistency regarding field focus.

The dictionary states:

When fieldValidationFailed is sent, the field retains focus so the user can correct the value without having to click back into the field.

However, it also states:

fieldValidationFailed is only sent for user-initiated edits, matching the same conditions under which closeField would fire.

Since closeField is triggered when the field loses focus, it appears that the focus has already changed by the time fieldValidationFailed is sent.

The example provided:

-- Show an inline error and keep the field focused
on fieldValidationFailed pFieldName, pError
    set the borderColor of field pFieldName to "red"
    show field (pFieldName & "Error")
    put pError into field (pFieldName & "Error")
end fieldValidationFailed

displays the validation error correctly, but it cannot actually keep the field focused because the message is received after the focus change.

The expected behavior can be achieved by explicitly restoring the focus:

focus on me

at the end of the handler :

-- Show an inline error and keep the field focused
on fieldValidationFailed pFieldName, pError
    set the borderColor of field pFieldName to "red"
    show field (pFieldName & "Error")
    put pError into field (pFieldName & "Error")
    focus on me
end fieldValidationFailed

Could the documentation be clarified to explain that fieldValidationFailed allows the handler to restore focus, rather than implying that the field still has focus when the message is sent?

2

Follow along here Inconsistent description of field focus behavior in fieldValidationFailed documentation · Issue #417 · emily-elizabeth/HyperXTalk · GitHub

3

I think the documentation states the intended action. Validation should happen first and either fieldValidationFailed is sent or closeField is sent.

4

Looked at the example stack. If the field does not validate, then the closeField message does not get sent. It is up to the developer to use the validation message to maintain focus so the docs do need correction.

5

Thanks Brian, that makes sense.

My confusion came from the sentence saying that the field “retains focus”. From my reading, I expected that to happen automatically.

If restoring the focus is the responsibility of the developer, then I agree the documentation should be updated to make that clear. Thanks for checking the example stack!

I also noticed the same wording in the note at the bottom of the validateField page:

Validation also fires automatically when the user edits a field and moves focus elsewhere (on closeField). If validation fails at that point, a fieldValidationFailed message is sent instead of closeField, and the field remains focused so the user can make a correction.

I agree that validation is performed in this case (although the validateField command itself is not sent). Here again, the field cannot retain focus automatically.

6

I suggest the following example script placed in the field script:

on fieldValidationFailed pFieldName, pError
   -- Show the error and keep the field focused
   answer pError
   focus on me
end fieldValidationFailed

on enterInField
   -- validate the field or not
   focus on nothing
end enterInField