What is registerOnTouched for?

Question

When creating a custom form element that uses ngModel, one must provide NG_VALUE_ACCESSOR, which in turn requires that the component implements ControlValueAccessor, which has a method called registerOnTouched. All the angular.io docs say about it is this:

registerOnTouched(fn: any) : void

Set the function to be called when the control receives a touch event.

The Angular docs make it sound like this is for touch input, but I assume it is part of ngForm's way of seeing if a user has ever interacted with an input. There seems to be some information missing from the docs about what a "touch event" is, and how one is supposed to register and use an "onTouch" handler from outside the component.

What in the world is this for? How is it used? Who provides the fn? ...the developer using my component ((touched)="handler()"), or only Angular itself? I've seen some examples that simply register a handler, and then never call it, or ignore it. If that's the case, why do I need to implement it at all?

An end to end example of the "touch event" would probably clear this all up.

Answer 1

An issue was created and the documentation for registerOnTouched has since changed:

Registers a callback function that should be called when the control receives a blur event.

This is called by the forms API on initialization so it can update the form model on blur.

...

See the documentation for registerOnTouched.

Registering a touch handler causes ngForm to properly set the ng-touched class and ng-untouched class on the custom input. Here's an example on plunker.

I'm not sure what a touch event consists of, nor do I know of a way to directly check or listen to when a custom input has been touched.