Documentation of Mouse Interaction is very incomplete, somehow confusing, and lacks examples

[teo1978]

http://api.jqueryui.com/mouse/

This part of the documentation needs serious improvement, and/or a corresponding dedicated section in Demos, which does not exist.

1. (this applies to several methods but I take _mouseStart() as an example)

_mouseStart()Returns: jQuery (plugin only)

The extending widget should implement a _mouseStart() method to handle the beginning of an interaction

=> Explain how the widget author is supposed to implement this method. Because the obvious apparent meaning is that you are expected to implement it in this way:

$.widget("my.widget.name", {
  //....
  //....
  _mouseStart: function() {
    //my definition of the method. e.g.:
    alert("Mouse interaction starting");
    return this;
  }
});

but that's not the case, as this way the method won't ever be called.

The same applies to all the other methods of this part of the api (_mouseCapture, _mouseStop, _mouseDrag...)

2. The following can be seen in the documentation of most of these methods:

This method will receive the mouse event associated with the start of the interaction.

• This method does not accept any arguments.

There's an apparent contraddiction there.

3. Code examples. The current code examples are completely useless. Most (or all) examples are like this:

Code examples:
Invoke the _mouseStart method:

$( ".selector" ).mouse( "_mouseStart" );

That or no example at all is the same. A useful example would be an example implementation of the method, rather than an example of calling it which is something you wouldn't usually do.

[scottgonzalez]

1. I'm not sure what to write; how you implement the method is entirely dependent on what you're trying to implement. As for your code not working, you're not extending $.ui.mouse, so there's no reason that _mouseStart() would ever be called.

2. Yeah, the documentation for these methods is pretty terrible, and inconsistent with itself.

3. The code examples are just wrong. They're using the auto-generated examples which aren't valid for internal methods. However, it's impossible to give a useful implementation example without building an entire widget.

---

Until the documentation is updated, I think the best reference would be to look at http://view.jqueryui.com/interactions/demos/interaction/default.html and http://view.jqueryui.com/interactions/demos/interaction/box.html which uses the new Interaction API, but should give you enough of an idea of how to use the current Mouse API.

[teo1978]

1. What I mean is you should explain how you override those methods. Not an example implementation of the code inside it (that can be a simple alert()). The key is precisely this:

As for your code not working, you're not extending $.ui.mouse.

What should be clarified is what "extending $.ui.mouse" means. This is probably obvious to you but the page lacks a basic explanation of how to use the whole mouse thing.

3. An entire minimal widget example is exactly what I'm missing here. Or in the demos (and link it from here).
   The code inside the methods can be as trivial as alert("Mouse interaction started[stopped]");
   What is unclear here is the mechanics of the framework and how it interacts with the Widget factory.

Perhaps what I'm missing (and it may be my fault) is the inheritance mechanism in widgets.

Similar to jQuery.Widget, the mouse interaction is not intended to be used directly. It is purely a base layer for other widgets to inherit from.

Perhaps what's missing here is just something as simple as "See [link]" where [link] points to whatever part of the documentation where it explains how to write a widget that extends another. Because is that what it means? That mouse is a widget one should extend?

[scottgonzalez]

What should be clarified is what "extending $.ui.mouse" means.

http://api.jqueryui.com/jQuery.widget/#jQuery-widget1

The code inside the methods can be as trivial as alert("Mouse interaction started[stopped]");
What is unclear here is the mechanics of the framework and how it interacts with the Widget factory.

You're actually not confused about how the mouse widget works, you're confused about how to inherit from another widget.