Menu.on callback documentation issue? about pebblejs

[Meiguro]

pebble.js internally uses its own Emitter or event dispatcher implementation which calls all listeners or callbacks with three parameters, event, eventType, and listenerIndex where listenerIndex is the listener's position among all listeners currently registered to the same object's eventType.

This is not documented because this is a feature specific to the underlying Emitter implementation that none of the classes that depend on it rely on. It may change before a stable release.

Thinking about it again, I may actually remove those other two parameters. eventType might be removed because some events also have a subtype, and yet it's not being passed as a parameter. listenerIndex is for cases where listener order is important for dynamic listeners, although receiving that information after registration isn't quite useful except possibly for debugging to figure out if something else is registered before the current handler executing. There should have probably been a fourth parameter totalListeners.

The original reason for eventType was in case the event object is missing the type field. This is not possible now since Emitter sets the type field automatically, unless a frozen object is emitted. As you've noticed, eventType continues to be passed for dynamic listeners despite type being automatically set.

Thanks for having me look into this again. If the eventType is actually useful for you or anyone else, I can instead consider changing listenerIndex into eventSubtype instead of removing both parameters. And of course, the final Emitter behavior would then be documented.

[Rocketeer007]

For the app I'm currently working on, the eventType is not important. I can't comment on whether or not it might be useful in the future though!

This issue probably would never impact anyone unless they have a similar coding style to me...
I have an event handler function that also takes an optional parameter that is only expected when the function is called directly. Reading the documentation, I expected parameter 2 to be undefined - but actually, it was populated, so my "optional" parameter had to be number 4!

I'm not normally a JavaScript developer (more Java & C actually), so I'm not used to having such flexible callback function definitions :-)

[Meiguro]

Ah, I see, I'm leaning towards removing them then as that sounds like a fairly common use case that I overlooked by only using anonymous functions most of the time.

In the mean time you could use an additional anonymous function Menu.on('select', function(e) { myFunction(e); }). It seems wasteful, but with this arrangement, you could, for example, move logic that only performs if it was called by the event (if any) into this new function. Or at the very least, guard against this API change.

I have to admit this could be a breaking change, so it might be awhile for it to land.

[Rocketeer007]

With more JS experience under my belt, clearly the anonymous callback is the correct solution!