Animatron/player — pull request #17 by shamansir (2012-06-19 01:49:20+00:00)
Title: Collisions: Contains (Bounds & Path)

* If you want to test contains (now), intersects and collides (near future), you need to include `anm.collisions.js` file in the head of your html, before `anm.builder.js` and after `anm.player.js`.
* There are several methods added to Element (not Builder!) when you include this file:
* `contains(pt[, t])`, `dcontains(pt[, t])` — test if point is inside of this element in specified time. Point is in global coords, all parent modifications are applied to it before test. If t is not specified, the current state used for calculation (in fact — state at the previous render) and in this way it may be called in any moment. If t is specified, it may be called only from handler, because it needs a re-calling of modifiers (all, except event handlers). d- version goes deep and checks all of the children (including grand*-children).
* `ibounds()` — get bounds of the element in its local coordinates.
* `bounds([t])`, `dbounds([t])` — get global bounds, for specified time or current state (restrictions are the same as for `contains()`); deep or not.
* `local(pt[, t])`, `global(pt[, t])` — convert global point to local coordinates or global to local coordinates respectively, specified time or current state (restrictions are the same as for `contains()`).
* `reactAs(path)` — you may set the path which will be used as reference for this elements in contains/intersects/collides tests. it is useful when your element is drawn only with painters, but you know its bounds. (all path points are required to be relative to the element's origin point). this path may be created with the help of B.path, for example.
* `reactWith(func)` — you may set the function that will be called instead of internal tests for collision test. the local point will be passed to it and the element itself will be 'this' value.
* `collides(elm[, t])`, `dcollides(elm[, t])` — NOT IMPLEMENTED FOR THE MOMENT, will return collision information
* `intersects(elm[, t])`, `dintersects(elm[, t])` — NOT IMPLEMENTED FOR THE MOMENT, will return if the given element intersects with the current one
* If you want to enable path-based 'contains' checking for these methods (they check bounds by default, but `reactAs`-path, if given, is anyway taken into account, even for bounds), put this line in the beginning of code (it only matter to be before any calls to these methods): `anm.MODULES['COLLISIONS'].pathCheck = true;`
* I haven't still corrected mouse handlers to always check contains for the moment (but I will soon), so the mouse-click pattern check still looks like this:

b().rect(....)
.on(C.X_MCLICK, function(evt) {
console.log(this.$.contains(evt.pos));
});
* With the help of `reactAs` and @Nek circles-contains-test now works and they are painted right!